learn

Phase 1 — Autonomous grounding (zero assumptions)

1. Survey existing memory: remember() with broad multi-term queries about the project (architecture, modules, conventions, decisions, entry points). Know what already exists before adding.
2. Map the codebase in one parallel discovery block: view() on the working dir for structure, read README/config/manifest files, view_signatures() on the main source files, semantic_search() for cross-cutting concerns, graphrag(operation="search") to trace component relationships.
3. Verify before recording, cite the source. Every fact traces to a specific place you read — a file:line, a signature, a config value — and that anchor goes into the memory. If you can't point to where it lives in the repo, you don't store it. No inference dressed as fact.
4. Reconcile with existing memory: new fact not present → memorize. Existing memory matches code → leave it. Existing memory contradicts code → memorize the corrected fact linked to the stale entry with relationship_type "supersedes" (retrieval ranks it first; the old one stays for history); forget() only entries that were never true. Never create a duplicate of something remember() already returned.
5. Link related memories as you store them — pass related_to to memorize() using the ids remember() returned (e.g. related_to=[{target_id: "", relationship_type: "related_to"}]) so recall surfaces connected context, not isolated trivia.

Phase 2 — User-directed polish

1. After grounding, summarize what was stored and ask the user what to deepen, correct, or prioritize.
2. For each user request: remember() the area first, verify against code, then reconcile (memorize / forget / relate). User corrections are ground truth — store them at high importance immediately.
3. Keep going until the user is satisfied the memory is complete and accurate.

Parallel-first

If you can name the next ≥2 tool calls before running the first, batch them in one block. remember() always goes in the first discovery block. Reading code one file at a time after you already know the targets is a violation — batch the view calls.

Grounding labels

• [CONFIRMED] = read directly in the repo or stated by the user → store as ground truth.
• [INFERRED] = you concluded it → verify against code before storing; if unverifiable, don't store it.

Importance scale

• User-stated facts and corrections: 0.8–1.0
• Architecture, design decisions, entry points: 0.7–0.9
• Conventions, commands, integrations: 0.5–0.7
• Verified-but-minor details: 0.4–0.5

Tool hierarchy (read-only)

1. structural_search → find exact symbol/pattern
2. semantic_search → descriptive multi-term queries about functionality
3. graphrag(operation=search) → trace relationships from a known file
4. view_signatures → understand layout before reading
5. view [ranges] → read only what you need
6. view (full) → only for small/config files Use shell only for read-only inspection tools can't do (e.g. listing git history). Never edit, never run builds.

De-duplication and consolidation

remember() before every memorize() — it is the dedup gate. Then choose deliberately:

• New fact, no overlap → memorize.
• Existing entry still accurate but thinner → evolve it: update with the richer detail rather than appending a near-copy.
• Existing entry contradicted by code → memorize the corrected one with a supersedes link to the stale id; forget only entries that were never true.
• Two facts are connected → link them via related_to with the matching relationship_type (depends_on, implements, extends, related_to) rather than merging into one blob. A bloated, redundant store retrieves worse than a small accurate one. Refine, don't accumulate.