/forgetful-encode-repo

name: forgetful-encode-repo
description: >-
  Encode a repository into the Forgetful knowledge base — bootstrap the project, its
  entities, memories, and documents from the codebase itself. Use when bringing a new repo
  under Forgetful or refreshing a stale encoding. Re-encoding is an update pass:
  query-before-create makes it supersession, not duplication.
license: MIT
disable-model-invocation: true
tags: [bootstrap, encoding, repository, knowledge-base]
allowed-tools:
  - mcp__forgetful__discover_forgetful_tools
  - mcp__forgetful__how_to_use_forgetful_tool
  - mcp__forgetful__execute_forgetful_tool
  - Bash(forgetful:*)

Encoding a repository

The goal is a knowledge base a future session can lean on: the system modelled as entities, the decisions and conventions as atomic memories, the long-form understanding as documents, everything provenance-stamped back to the source. Encode twice and the second pass updates — never duplicates.

Invoking operations

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

• **MCP**: `execute_forgetful_tool(tool_name="create_project", arguments={...})`
• **CLI**: `forgetful call create_project --args '{"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.

Step 1 — Resolve the project

`git remote get-url origin` → `owner/repo` → `list_projects` with `repo_name`. Existing project means this run is a refresh; otherwise `create_project` with the repo name and a description of what the codebase is for.

Done when: a project_id exists and the run knows whether it is a first encode or a refresh.

Step 2 — Survey the sources

Read what the repo says about itself before reading code: README, docs/, contributor and agent guides, manifests (dependencies, entry points, scripts), CI and deploy configuration. Note the current commit — every write in this run cites it via provenance.

Done when: there is a source list of what will be encoded, ordered by signal.

Step 3 — Model the system as entities

Skills referenced by name below resolve via `search_skills` → `export_skill` when not already available. Per `forgetful-entities`: the system itself and its key components (services, packages, databases, external dependencies that matter) as `entity_type: "System"`, and their structure as relationships — `part_of` for composition, `depends_on` for coupling. Dedupe against existing entities on a refresh.

Done when: the architecture is walkable as a graph, components to system, dependencies out.

Step 4 — Store the knowledge

Two layers, per `forgetful-remember` (its routing, atomicity test, and importance rubric govern every write here):

• **Documents** for long-form understanding: architecture overviews, subsystem guides,

design analyses.

• **Atomic memories** as the entry points: decisions, conventions, patterns, constraints —

each linked to its document via `document_ids`, stamped with `source_repo` and `source_files`, and linked to the entities it concerns via a separate `link_entity_to_memory` call (not something `create_memory` does for you).

On a refresh, query first per source area: update what drifted, mark obsolete what the code contradicts, create only what is new.

Done when: each surveyed source area has produced its documents and entry-point memories, or explicitly had nothing worth encoding.

Step 5 — Report coverage

Close with a coverage report, in place of "done": project ID, entities created/updated, memories created/updated/obsoleted, documents written, source areas skipped and why, and the areas where knowledge is thin. Note repo-level gaps the survey turned up too — missing docs, absent CI, and the like — not only gaps in the encoding itself. Deliver the report in the final response to the user; it is not written anywhere in Forgetful. The report is the encode's acceptance surface — a reader should be able to spot a gap from it alone.

Done when: the report is delivered and honest about gaps.