| name | history-backfill |
| description | Backfill project memory from existing repo evidence (codebase, docs, configs, git history, tasks, sessions, agent traces). Use when the memory tree is new or sparse and the project has existing history. |
History Backfill
Reads raw evidence from the repo and existing artifacts, then distills stable facts
into the curated memory tree.
Use this after project-ontology-bootstrap when the project has existing history.
Separation rule -- enforced, never relaxed
| Location | What goes here | Who edits it |
|---|
agent-knowledge/Evidence/raw/ | Direct snapshots from the current repo state | Only the import script |
agent-knowledge/Evidence/imports/ | Imported docs, tasks, sessions, traces, graph exports | Only the import script |
agent-knowledge/Outputs/ | Generated discovery summaries and structural maps | Only scripts or agents treating them as non-canonical outputs |
agent-knowledge/Memory/ | Curated, stable, distilled facts | Only the agent, via writeback rule |
Never write raw evidence into memory. Never treat evidence as authoritative -- it is input for judgment, not truth.
Step 1 -- Collect evidence
Run the import script:
scripts/import-agent-history.sh /path/to/project
This creates evidence files under Evidence/raw/ and Evidence/imports/, and
generated summaries under Outputs/.
Step 2 -- Read evidence in priority order
Read these files in order. Each source has different signal quality:
imports/existing-docs.txt -- highest signal. README, CLAUDE.md, AGENTS.md, and project metadata contain curated intent.raw/manifests.txt -- authoritative for stack and dependency boundaries.raw/config-files.txt -- strongest signal for conventions and tooling.raw/tests.txt and raw/ci-workflows.txt -- how the project proves and ships behavior.raw/structure.txt -- actual architecture shape.imports/tasks.txt and imports/session-files.txt -- recurring work areas and unresolved questions.raw/git-log-detail.txt and raw/git-log.txt -- what changed and why.imports/trace-index.txt -- supplemental traces only; never canonical truth.
Read confidence labels before trusting a source:
EXTRACTED means direct structural evidenceINFERRED means a derived summary that still needs reviewAMBIGUOUS means the source may be stale, partial, or wrong
For agent traces and graph summaries: treat them as evidence with lower confidence than direct repo scans. Extract patterns, not individual claims.
Step 3 -- Distill into memory
For each stable fact extracted from evidence:
- Identify which memory branch it belongs to
- Read the current branch note
- Place the fact in the correct section:
- Current State: for verified facts about the project as it is now
- Recent Changes: for things that changed recently (prune after ~4 weeks)
- Open Questions: for things the evidence hints at but doesn't resolve
- Decisions: link to a decision file if it's an architectural choice
- Lead with the fact. Do not pad with context the reader can find in git.
If a fact doesn't fit any existing branch, create a new branch note using the
same-name convention. Use the project's own terminology for the branch name.
Step 4 -- Quality filters
Only write a fact to memory if it passes all of:
- Stable: unlikely to change in the next few weeks
- Non-obvious: not immediately derivable from reading the code
- Useful: would save a future agent meaningful time or prevent a mistake
- Verified: supported by at least one evidence source (not inferred)
Do not write:
- Commit-level implementation details
- Speculative interpretations of code intent
- Facts already in project docs that agents can read directly
- Anything marked as in-progress or planned (goes in session file until confirmed)
- Machine-generated summaries unless verified against the repo
Step 5 -- Update Memory/MEMORY.md
After updating branch notes, check that Memory/MEMORY.md reflects the new content:
- Keep the root note short
- Update branch summaries if their durable state changed
- Add branch links for any new branches created during backfill
Output checklist
