/forgetful-encode-repo

name: forgetful-encode-repo
description: >-
  Encode a repository into the Forgetful knowledge base, or refresh an existing encoding after
  development work. A first encode builds the project, entities, memories, and documents from
  the codebase. A refresh reviews the git changes since the project's last encoded commit and
  updates, obsoletes, or adds only the knowledge those changes affect. Use when bringing a repo
  under Forgetful, or syncing its knowledge after commits, merges, or a release.
license: MIT
disable-model-invocation: true
tags: [bootstrap, encoding, refresh, repository, knowledge-base, git]
allowed-tools:
  - mcp__forgetful__discover_forgetful_tools
  - mcp__forgetful__how_to_use_forgetful_tool
  - mcp__forgetful__execute_forgetful_tool
  - Bash(forgetful:*)

Encoding a repository

An encoding is a claim about the code at one commit. The project's `last_encoding_point` holds that commit's SHA: the checkpoint. Forgetful stores the checkpoint but never sets or advances it; this skill moves it, and only after a run has reviewed every change up to the new commit. A first encode builds knowledge from the codebase. A refresh reviews the changes since the checkpoint.

**Decide, then load.** Begin with Step 1. The branch comes from what Steps 1 and 2 observe in git and Forgetful, not from whether the request says encode or refresh, and Step 2 ends by writing it down as the branch decision. Open a reference only after that decision, and only the one it names.

Invoking operations

Operations are named by registry name (`list_projects`, `update_memory`, ...). Invoke via whichever surface this agent has:

• **MCP**: `execute_forgetful_tool(tool_name="list_projects", arguments={...})`
• **CLI**: `forgetful call list_projects --args '{"repo_name": "..."}' --json`

Get any operation's schema at runtime: `how_to_use_forgetful_tool` (MCP) or `forgetful tools info <operation>` (CLI) — schemas are deliberately not repeated here.

Skills named below resolve via `search_skills` → `export_skill` when not already available.

Step 1 — Pin the run

Run git in the repository being encoded (the current directory unless the user named one). Record, before any write:

• **HEAD**: `git rev-parse HEAD`. Unless the user names another range end, this is the end

commit: everything this run writes describes it.

• **Clean worktree**: `git status --porcelain` prints nothing. Otherwise knowledge read from

uncommitted or untracked files would be stamped with a commit that lacks them, so ask the user to commit or stash, and wait.

• **Project**: `git remote get-url origin` → `owner/repo` → `list_projects` with `repo_name`.

When no remote exists or several projects match, ask the user. Record the project ID and its `last_encoding_point` as read now.

Done when: HEAD, a clean worktree, and the project (or its absence) are recorded.

Step 2 — Choose the branch

Two requests override the table. A full re-encode selects the first-encode branch, including its review of existing knowledge. An explicit range for an existing encoding selects refresh, even when its end equals the checkpoint; resolve the range as described below. For a repo with no encoding, use the first-encode branch at the requested end commit instead.

Otherwise, the first matching row wins:

| Situation | Branch | |---|---| | No project for this repo | First encode | | Project has no encoded knowledge (check below) | First encode | | Checkpoint equals the end commit | Nothing to review: go to Step 6 | | Checkpoint is a commit and an ancestor of the end commit | Refresh, checkpoint → end | | Project holds knowledge; checkpoint missing, unknown here, or not an ancestor | Pause |

Checks: the checkpoint is a commit here when `git rev-parse --verify --quiet <sha>^{commit}` prints the stored value itself; a branch or tag name moves, so it does not count. `git merge-base --is-ancestor <sha> <end>` succeeds when it is an ancestor. Check for knowledge with `get_recent_memories` (project ID, `include_obsolete`), `list_documents`, `list_code_artifacts`, and `list_entities`, each scoped to the project. Any item returned proves knowledge; a project record alone does not. Knowledge is absent only when all four reads succeed and return nothing. A read that still fails after correcting the call leaves knowledge unknown, which counts as present.

**Pause** means: ask the user for a baseline, a commit the stored knowledge is known to describe, and refresh from it once it resolves as an ancestor of the end commit. Take the baseline from the user; tags, dates, and recent commits are guesses. The user may instead ask for a full re-encode, which runs the first-encode branch over the existing knowledge.

**User ranges.** A user may name a range `A..B`. Resolve both ends to SHAs; B becomes the end commit. The checkpoint may move to B only when the range leaves no unreviewed commit after the current checkpoint: A is the checkpoint or one of its ancestors, and the checkpoint is an ancestor of B. A user-named baseline counts as the checkpoint for this rule. Any other range still gets reviewed and curated, but the checkpoint stays where it is.

**Branch decision.** End this step by writing the decision in your response: the project ID or none, the checkpoint as read, the end commit, whether knowledge is present and which reads show it, and the branch with its range. The decision names the reference Step 3 opens: `references/first-encode.md` for a first encode, `references/refresh.md` for a refresh, and none for a pause or nothing to review.

Done when: the branch decision is written, and each value in it comes from a command or tool result in this run.

Step 3 — Load and run the branch

Open the reference the branch decision names, from where this skill came from so it matches this SKILL.md, and follow its steps, applying the curation rules below to every write:

• **Skill folder**: read that path, relative to this SKILL.md's folder.
• **For