scottrbk 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 withsource_repoandsource_files, and linked to the entities it concerns via a separatelink_entity_to_memorycall (not somethingcreate_memorydoes 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.