diff --git a/routing-memory/SKILL.md b/routing-memory/SKILL.md index 26bff05..f4e76c9 100644 --- a/routing-memory/SKILL.md +++ b/routing-memory/SKILL.md @@ -1,393 +1,350 @@ --- name: routing-memory -description: Design and maintain routing-style agent memory: context repositories, concept maps, canonical ownership, retrieval routers, and forced lookup before answering. Use when building or repairing agent memory systems, reducing hallucinations from unactivated memory, organizing MemFS/markdown memory, or turning chat history into durable context. +description: Designs and repairs routed agent memory using a lean system layer, out-of-core reference files, flat domain indices, canonical ownership, conversation recall, and retrieval probes. Use when setting up or reorganizing MemFS or another Markdown memory repository, when an agent forgets facts that were stored, when current facts drift across files, or when durable memory should survive across conversations without loading everything into the prompt. --- # Routing Memory -Use this skill when an agent needs memory that actually changes future answers. +Build memory that changes future answers. -The central move: treat memory as a **routed context repository**, not a pile of notes, embeddings, summaries, or chat transcripts. Storage is cheap. Activated, canonical, inspectable context is the hard part. +Treat this as one practical architecture, not the correct universal hierarchy. Memory design is still empirical. Derive the structure from the agent's work, preserve useful mess when it is doing real work, and test retrieval behavior rather than admiring the directory tree. -A memory system fails when the information exists but does not fire at the moment it matters. This skill designs against that failure. +## Core model -## When to use +Use four layers: -Use this skill when the user says things like: - -- "set up my memory" -- "organize this agent's memory" -- "make this retrievable" -- "create a concept map" -- "use MemFS" -- "build a context repo" -- "route memory better" -- "the agent forgot even though it was written down" -- "stop guessing from vibes" -- "load relevant memory before answering" -- "turn these notes into agent context" -- "distribute this memory pattern to other agents" - -Also use it proactively when: +```text +Context repository + durable, inspectable, versioned state -- memory exists but answers still miss it -- current-state facts are duplicated in multiple files -- summaries have compressed away retrieval hooks -- the agent has many notes but no routing surface -- a chat transcript is being treated as the durable source of truth -- project, person, or concept knowledge should survive across sessions -- a prior correction revealed stale memory, wrong source selection, or hallucination -- multiple agents need to share or inspect the same context +Flat indices + several task-shaped views over that state -## Core thesis +Retrieval router + start-of-turn mapping from turn shape to canonical sources -Do not ask, "Did we store the memory?" +Recall fallback + conversation search for exact episodes, wording, and provenance +``` -Ask: +The key question is not whether a fact was stored. Ask: ```text -What context surface will the agent operate against next time? -+ how will the agent know to load it? -+ which file owns the fact? -+ how will conflicts fail visibly? +What cue will cause the agent to retrieve it? +Which file owns it? +What happens when two sources disagree? +How will we prove the route works? ``` -A useful memory architecture has four layers: +## Current Letta contract -```text -Context Repository - durable files, metadata, history, project state +For Letta agents, verify current product details against the official documentation before using CLI commands or changing runtime configuration: -Concept Map / Index - what exists and when to load it +- https://docs.letta.com/concepts/memfs/ +- https://docs.letta.com/configuration/memory/ +- https://docs.letta.com/concepts/conversations/ -Retrieval Router - start-of-turn decision table from trigger -> source +The stable architecture this skill relies on is: -Forced Lookup Habit - behavior rule: retrieve before answering when a source exists -``` +- MemFS is a git-backed Markdown context repository shared by an agent's conversations. +- Files under `system/` are compiled into the system prompt. +- Files outside `system/` remain visible through the memory tree and are read on demand. +- MemFS does not require a vector index. Ordinary file search and reads are the baseline retrieval path. +- Conversation-history search is separate from MemFS. Compaction can omit exact wording or provenance while the underlying message history remains searchable. +- Agent-owned procedural skills live under `$MEMORY_DIR/skills/`. -## Context repositories +Use `/init` for ordinary initialization and `/doctor` for a general memory audit. Use this skill when the user specifically wants routed, index-based, out-of-core memory or when those generic workflows produced storage without reliable activation. -A **context repository** is a durable, inspectable bundle of files, metadata, preferences, project state, schemas, timelines, and derived summaries that an agent can mount and operate over. +## Hard boundaries -Chats are not context repositories. Chats are interaction surfaces. +- Inspect before restructuring. Do not replace an evolved memory tree with a template because the template looks clean. +- Do not rewrite identity, values, protected user context, or relationship terms as a side effect of organization. +- Do not publish private memory, even when the architecture itself is public. +- Preserve git history and inspect shared or read-only state before editing. +- Migrate completely. Once ownership is settled, update routes and links in the same change and remove stale duplicate owners. Do not leave a permanent `legacy/` attic. +- Keep recall workers read-only. Retrieval authority is not edit, commit, or outbound-message authority. +- Do not call a migration successful because files exist. Run retrieval probes. -Better hierarchy: +## 1. Discover the actual memory system -```text -Agent - identity + behavior + tools +Find the canonical repository before editing it. -Context Repo - durable project/user/world knowledge - inspectable and tool-addressable - versionable, diffable, repairable - shareable across agents +Inspect: -Chat / Task / Run - ephemeral interaction against one or more context repos -``` - -If memory is trapped inside a chat, it becomes goo: hard to audit, hard to route, easy to summarize into mush. A repo gives memory a body. - -## Minimum viable repo shape +1. memory root and git status; +2. every Markdown path and frontmatter description; +3. the current `system/` surface and its context cost; +4. existing indices, routers, project notes, skills, and timelines; +5. conversation-history search or recall tools; +6. shared, read-only, generated, or externally synchronized files; +7. recent memory commits and any uncommitted changes. -For a markdown/MemFS-style memory repo: +Build a short inventory: ```text -memory/ - system/ # always-on rules; keep small - concepts/ # reusable abstractions and patterns - index.md # concept map - projects/ # active project state - reference/ # deeper static detail, audits, source notes - timeline/ # chronological event logs - skills/ # reusable procedures, if supported - README.md # repo purpose and update rules, optional +Always loaded: +Loaded on demand: +Procedures: +Historical evidence: +Shared state: +Likely duplicate owners: +Unrouted files: ``` -Adjust names to fit the environment. The structure matters less than the roles. +Do not edit during discovery unless the user explicitly requested a tiny, obvious repair. -## Layer roles +## 2. Define canonical ownership -### 1. System memory +Assign one owner to each important or volatile class of information. -Always-loaded behavior and routing hints. +| Information | Typical owner | Notes | +| --- | --- | --- | +| Agent identity and hard behavior rules | `system/persona.md` or focused system files | Preserve detail that changes behavior | +| Retrieval policy | `system/retrieval_router.md` | Keep compact and operational | +| High-churn current state | `system/now.md` or a routed current-state file | One owner; prune or archive stale detail | +| Active project state | `projects/.md` | Current contracts and pointers, not full history | +| Reusable concepts | `concepts//.md` | Focused notes with retrieval triggers | +| Deep source material and audits | `reference/` | Loaded only when needed | +| Chronological evidence | `timeline/` or conversation history | History is not current state | +| Reusable procedure | `skills//SKILL.md` | Procedure, not accumulated domain state | +| Exact prior wording or episode | Conversation-history search | Promote only durable lessons into MemFS | -Use for: +A source of truth is the file responsible for staying correct, not merely a file where the fact appears. -- hard rules -- durable communication preferences -- retrieval router -- current live state if the agent needs it every turn +When two files disagree: -Do **not** use for: +1. identify the owner; +2. verify the fact from evidence; +3. update the owner; +4. replace the duplicate with a pointer or remove it; +5. repair the route that allowed the conflict to remain hidden. -- long histories -- detailed project archives -- every interesting thought -- stale facts -- content that can be routed in when needed +## 3. Keep the always-loaded layer lean enough to route -System memory is expensive real estate. Treat it like a cockpit, not a storage unit. +The system layer must contain enough texture to recognize when retrieval is needed. A bare list of links is not equivalent to in-context knowledge. -### 2. Concept map +Keep in `system/`: -The concept map is an index of reusable ideas and where they live. +- identity and values; +- durable user preferences and critical boundaries; +- hard workflow rules and high-cost gotchas; +- a compact current-state surface when current facts affect most turns; +- the retrieval router and pointers to deeper owners. -Example: - -```markdown -# Concept Map +Move out of `system/`: -## Agent memory -- `concepts/agent-memory/context-repositories.md` — primitive above chats -- `concepts/agent-memory/forced-lookup.md` — retrieve before answering +- detailed histories; +- completed investigations; +- verbose architecture notes; +- per-project implementation detail not needed on most turns; +- raw transcripts and source dumps. -## User patterns -- `concepts/user/synthesis-over-procedure.md` — user wants grounded synthesis, not caveat theater -``` +Do not optimize for the smallest possible prompt. Preserve examples, reasons, and semantic cues that help the model notice the route. Cut redundancy and stale detail before cutting identity-bearing or behavior-shaping context. -The concept map should answer: +## 4. Build several flat indices -- what concepts exist? -- which file owns each concept? -- when should the agent retrieve it? +Do not force every retrieval path through one universal table of contents. Maintain a few overlapping views that match real work: -A concept map earns its keep only when it changes the next answer. Otherwise it is a museum. +```text +indices/ + people.md + projects.md + concepts.md + operations.md +``` -### 3. Retrieval router +An index entry should say: -A retrieval router is a start-of-turn decision table. +- what the source owns; +- when to load it; +- whether it is current state, history, procedure, or reference. Example: ```markdown -# Retrieval Router - -## Music / Suno / production -Read: `projects/music-current.md`, `reference/suno-rules.md` -Keywords: song, hook, Suno, mix, drums, bass, lyrics +## Projects -## Memory architecture -Read: `concepts/agent-memory/context-repositories.md`, `concepts/agent-memory/forced-lookup.md` -Keywords: memory, MemFS, context repo, retrieval, forgot, recall - -## User live state -Read: `system/now.md` -Keywords: today, current, plan, schedule, travel, health +- `projects/payments.md` — current payment-service state and open contracts; load for billing, invoices, Stripe, or checkout work. +- `reference/payments-architecture.md` — deep architecture and historical decisions; load only for design or incident analysis. ``` -The router is not a directory listing. It is a decision table from **turn shape** to **canonical source**. +Keep common routes one read away when possible. Three layers of disclosure can already mean several tool calls and multiple chances to miss the source. Prefer several shallow indices over one deep taxonomy. -### 4. Canonical ownership +## 5. Write an operational retrieval router -Every volatile or important fact needs one owner. +The router is a decision table, not a directory listing. -Bad: +Each route should include: -```text -user travel dates in system/now.md -same dates copied into user.md -same dates summarized in timeline.md -``` - -Good: - -```text -system/now.md owns live travel dates -timeline/travel.md owns historical narrative -user.md links to now.md for current state +```markdown +### +Read: +Fallback: +Keywords: +Update owner: ``` -Use metadata when possible: +Route by turn shape as well as keyword. "What did you say?" should route to exact message history; "what do we believe now?" should route to the current owner even if both contain the same person's name. -```yaml ---- -description: Current live state for the user and active projects. -metadata: - canonical_for: live_state - volatility: high - update_policy: prune_or_move_when_stale ---- -``` +Keep high-risk distinctions explicit: -A source of truth is not where a fact can be found. It is the place responsible for that fact staying correct. +- current state versus historical narrative; +- exact wording versus thematic memory; +- project source versus generated report; +- user preference versus agent procedure; +- private context versus public source; +- observed runtime receipt versus intended configuration. -## Forced lookup workflow +## 6. Enforce lookup before synthesis -Before answering, classify the turn and retrieve the likely owner. +Use this start-of-turn protocol when a relevant source exists: ```text -1. Classify the domain. -2. Check the retrieval router. -3. Open the canonical files. -4. Answer from retrieved context. -5. If a new reusable concept appears, add it to the concept map. +1. Classify the turn. +2. Read the matching router entry. +3. Open the ordered canonical sources. +4. Search indexed memory if the route is incomplete. +5. Search conversation history for exact episodes or provenance. +6. Answer from retrieved evidence and mark unresolved conflicts. +7. Update the canonical owner only when a durable fact changed. ``` -Common domains: - -- live state / schedule / current plans -- people / relationships / social context -- project work -- code / repo / issue / PR -- music / creative taste -- product strategy -- agent memory / identity / context architecture -- health / safety / sensitive areas - -If the user explicitly asks for fast mode, skip deep lookup. Otherwise, retrieve first when relevant sources exist. - -## Designing concept notes +Do not begin drafting from latent familiarity and retrieve afterward to decorate the answer. Retrieval must be able to change the answer. -A concept note should be focused and retrieval-oriented. +If the user explicitly requests a fast response, reduce retrieval depth. Do not silently treat casual phrasing as stateless when it contains a known person, project, place, or recurring decision. -Template: +## 7. Use recall as evidence recovery -```markdown ---- -description: One-line retrieval description. -limit: 10000 -metadata: - canonical_for: snake_case_concept_name ---- +Conversation history is an event log, not the primary knowledge base. -# Concept Name +Use recall when the task asks for: -What it means. +- exact prior wording; +- what happened in a particular interaction; +- when a preference or decision changed; +- evidence missing from a compact memory note; +- recovery after compaction lost names, dates, paths, or provenance. -## Origin +Recall procedure: -Why it exists / where it came from. +1. search with concrete handles: names, dates, quoted phrases, file paths, message ids; +2. reconstruct the relevant sequence rather than returning isolated thematic matches; +3. separate user text, agent text, tool output, and later summaries; +4. treat inherited summaries as leads, not authority; +5. return evidence to the parent agent without editing memory; +6. promote only the durable lesson or retrieval handle into the canonical owner. -## Retrieval triggers +Do not copy whole conversations into system memory. Preserve enough handles that future recall can find the source again. -Words, situations, and domains that should load it. +## 8. Separate state from procedure -## Operating rule +Use memory files for what is true or known. Use skills for how to do recurring work. -How this concept should change future behavior. - -## Links +Example: -- related files +```text +reference/literature/ papers, notes, citations, current understanding +skills/reviewing-literature procedure for searching, reading, evaluating, and updating the index ``` -Create a concept note when a pattern: - -- recurs across conversations -- explains a failure -- affects future behavior -- crosses domains -- is likely to become a phrase the user reuses -- would prevent guessing if retrieved early - -Do not create concept notes for every stray thought. That way lies bureaucracy with markdown extensions. - -## Memory audits +The skill may maintain the repository. It should not become the repository. -Periodically audit the repo for: +## 9. Migrate without creating rot -- duplicate volatile facts -- files with no frontmatter or description -- concepts missing from the index -- important files missing router triggers -- stale current-state notes -- contradictory source owners -- orphaned project notes +For a structural change: -Useful checks: +1. record the starting commit and dirty state; +2. choose canonical owners; +3. move content without flattening away useful detail; +4. update routers, indices, frontmatter, and links; +5. remove stale duplicate owners in the same pass; +6. search for old paths and old owner language; +7. inspect the final diff for semantic loss; +8. recompile the active context when the runtime requires it. -```bash -find memory -type f -name '*.md' | sort +Do not leave a half-migrated tree with old and new hierarchies both claiming authority. -grep -RIn "canonical_for\|TODO\|stale" memory/concepts memory/reference memory/system +For reusable templates, load [references/templates.md](references/templates.md). -grep -RIn "travel\|current\|today\|now" memory | head -100 -``` +## 10. Test retrieval behavior -A memory system should fail visibly. If it can silently hold two different versions of the same live fact, it is not memory. It is confident bureaucracy. +Write probes before calling the architecture complete. -## Common failure modes +At minimum test: -### 1. Storage without activation +1. **Current fact:** routes to the live owner, not an old timeline entry. +2. **Stable preference:** routes to the durable preference or identity file. +3. **Project detail:** loads the project index, then the exact source. +4. **Exact quote:** uses conversation history rather than paraphrasing from memory. +5. **Conflict:** notices two contradictory sources and applies canonical ownership. +6. **Unknown:** says the evidence is absent rather than filling the shape from atmosphere. -The fact is written down but no router points to it. Future answers miss it. +For each probe, record: +```text +Query: +Expected route: +Expected owner: +Sources actually loaded: +Answer supported: +Failure mode: Repair: +``` -- add concept-map entry -- add router trigger -- add frontmatter description +Measure routing precision as well as recall. Loading everything prevents misses by recreating prompt bloat. The goal is the smallest sufficient context that still reaches the right evidence. -### 2. Summary mush +## Common failures -Compaction preserves a vague conclusion but deletes the retrieval hooks: names, paths, dates, decision owners. +### Stored but unrouted -Repair: +Add a router cue or index entry. Do not merely rewrite the note. -- store detailed notes outside system memory -- keep summaries as pointers, not replacements -- preserve path/name/date/source handles +### One giant index -### 3. Split-brain facts +Split it into shallow task-shaped views. Keep overlapping pointers; keep canonical content singular. -Two files own the same current fact and drift apart. +### Summary replaced evidence -Repair: +Restore names, dates, paths, source handles, and the conversation-search fallback. -- choose canonical owner -- replace duplicates with links/pointers -- document ownership in frontmatter +### Current facts copied into history and profiles -### 4. Chat-as-memory +Choose one live owner. Historical notes point to it rather than mirroring it. -The agent relies on conversation history as if it were structured memory. +### Cleaner memory made the agent worse -Repair: +Use git history to restore the behavior-bearing detail. Diagnose which examples, cues, or reasoning templates were lost before attempting another compression. -- extract durable concepts/projects/decisions into repo files -- route future turns to those files -- treat chat as event log, not knowledge base +### Recall worker changed state -### 5. Vibe completion before lookup +Audit its effects, restore the read-only boundary, and keep mutation authority with the parent agent. -The model starts answering before retrieving available context. +### Agent still answers before looking -Repair: +Move the lookup rule and trigger map into the always-loaded layer. The problem is activation, not storage volume. -- forced lookup rule -- router in always-loaded memory -- explicit user override for fast mode only +## Report -## Output when applying this skill - -When setting up or repairing routing memory, report: +When applying this skill, report: ```text Canonical memory repo: -- -- Reason: - -Created/updated: -- — -- — +- -Routing added: -- -> +Owners established: +- -> -Open risks: -- +Routes added or repaired: +- -> -Next test: -- -``` +Migration: +- -## Practical principle +Retrieval probes: +- -Memory is not what the agent has stored. +Open risks: +- +``` -Memory is what the agent can route into action at the right moment, from the right source, without counterfeiting certainty. +Memory is not what the agent has stored. Memory is what it can route into action at the right moment, from the right source, without counterfeiting certainty. diff --git a/routing-memory/references/templates.md b/routing-memory/references/templates.md new file mode 100644 index 0000000..51ea5fd --- /dev/null +++ b/routing-memory/references/templates.md @@ -0,0 +1,190 @@ +# Routing memory templates + +Load these templates when implementing or repairing a routed memory repository. Adapt names and domains to the actual agent. Do not fill every template mechanically. + +## Canonical ownership map + +```markdown +# Canonical ownership + +| Information class | Canonical owner | Volatility | Update rule | Historical source | +| --- | --- | --- | --- | --- | +| Agent identity | `system/persona.md` | Low | Change deliberately with provenance | Git history | +| Current user state | `system/now.md` | High | Replace current facts; move dated detail out | `timeline/` | +| Project status | `projects/.md` | Medium | Keep current contracts and pointers | Project repo / timeline | +| Procedure | `skills//SKILL.md` | Medium | Update after real use changes the workflow | Git history | +``` + +## System routing kernel + +```markdown +--- +description: Start-of-turn retrieval routes and canonical ownership map. +--- + +# Retrieval router + +Before answering a stateful query: + +1. classify the domain; +2. read the matching route below; +3. open the ordered sources; +4. use conversation search for exact wording or missing provenance; +5. answer from evidence. + +### Current plans and state +Read: `system/now.md` +Fallback: relevant project owner, then recent conversation search +Keywords: today, current, next, plan, status, still, now +Update owner: `system/now.md` + +### Named project +Read: `projects/example.md`, then the live project repository +Fallback: `timeline/example.md`, then conversation search +Keywords: Example, exact command names, repository name, recurring feature names +Update owner: `projects/example.md` + +### Exact prior wording +Read: message or conversation history +Fallback: dated timeline handles +Keywords: what did I say, exact words, quote, sent, reply, earlier conversation +Update owner: store only durable lesson or a retrieval handle +``` + +## Domain index + +```markdown +--- +description: Project routes: current owners, deeper references, and historical evidence. +--- + +# Project index + +## Active + +- `projects/example.md` — current state, contracts, and repository pointers; load for Example work. +- `reference/example-architecture.md` — deep architecture; load for design and incident analysis. +- `timeline/example.md` — dated changes; never treat as current without the project owner. + +## Retrieval cues + +- Repository aliases: +- Important people: +- Commands and symbols: +- Failure symptoms: +``` + +## Focused concept note + +```markdown +--- +description: +--- + +# + +## Definition + + + +## Retrieval triggers + +- + +## Operating consequence + + + +## Evidence and provenance + +- + +## Related owners + +- `` — +``` + +## Recall brief + +Use a read-only recall worker or conversation-search tool with a bounded brief: + +```text +Find evidence for: +Search handles: +Return: +- chronological evidence; +- exact speaker/source ownership; +- unresolved contradictions; +- retrieval handles for future use. + +Do not edit files, commit, push, send messages, or execute the parent task. +Inherited summaries are search leads, not authority. +``` + +After recall, the parent agent decides whether anything durable belongs in MemFS. + +## Migration plan + +```markdown +# Memory migration plan + +Starting commit: +Dirty paths preserved: +Protected identity-bearing files: + +| Old path / owner | New canonical owner | Action | Routes and links to update | +| --- | --- | --- | --- | +| | | move / merge / remove / preserve | | + +## Completion checks + +- [ ] Every important information class has one owner. +- [ ] Router entries point to the new owners. +- [ ] Domain indices point to the new owners. +- [ ] Old paths and stale ownership language are absent. +- [ ] No useful rationale, example, quote, or provenance was silently lost. +- [ ] Shared and read-only files were not mutated without authority. +- [ ] The system prompt was recompiled when required. +- [ ] Retrieval probes passed. +``` + +## Retrieval probe set + +```markdown +# Retrieval probes + +| Query | Expected route | Expected owner | Actual sources | Result | Repair | +| --- | --- | --- | --- | --- | --- | +| What is the current status of Example? | Project | `projects/example.md` | | | | +| What package manager do we use? | Workflow preference | `system/workflow.md` | | | | +| What exactly did I say about the migration? | Exact history | Conversation search | | | | +| The timeline and current state disagree. Which wins? | Conflict | Ownership map | | | | +| What did we decide about Unknown Project? | Unknown | No source | | | | +``` + +Judge each probe on: + +1. route selection; +2. source sufficiency; +3. owner correctness; +4. answer support; +5. unnecessary context loaded. + +## Post-answer memory update + +```text +Did a durable fact change? + no -> do not write memory + yes -> identify canonical owner + +Is this exact episode likely to be needed verbatim? + yes -> preserve a conversation-search handle, not the whole transcript + +Did retrieval fail despite stored evidence? + yes -> repair the route, index, owner, or description + no -> update only the owner + +Would the same procedure recur? + yes -> update or create a skill + no -> keep it as state or history +```