history-backfill

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:

1. imports/existing-docs.txt -- highest signal. README, CLAUDE.md, AGENTS.md, and project metadata contain curated intent.
2. raw/manifests.txt -- authoritative for stack and dependency boundaries.
3. raw/config-files.txt -- strongest signal for conventions and tooling.
4. raw/tests.txt and raw/ci-workflows.txt -- how the project proves and ships behavior.
5. raw/structure.txt -- actual architecture shape.
6. imports/tasks.txt and imports/session-files.txt -- recurring work areas and unresolved questions.
7. raw/git-log-detail.txt and raw/git-log.txt -- what changed and why.
8. imports/trace-index.txt -- supplemental traces only; never canonical truth.

Read confidence labels before trusting a source:

• EXTRACTED means direct structural evidence
• INFERRED means a derived summary that still needs review
• AMBIGUOUS 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:

1. Identify which memory branch it belongs to
2. Read the current branch note
3. 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
4. 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

• Each branch note has populated Current State (not just TODO markers)
• Any patterns from git log are captured in relevant branch notes
• Active decisions found in docs are recorded in decisions/
• Open questions are listed for anything evidence hints at but doesn't resolve
• Memory/MEMORY.md reflects the real branch state
• No evidence content was written directly into memory files