| 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.
