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.