# Bonus · The same pattern for one person The org library gives every assistant the same picture of the organization. You can give your own assistant the same kind of structure for your own work: the rules you work by, the projects in flight, the traps you've already hit, so a new session starts where the last one stopped. The structure below is the one used with Claude Code, which reads a `CLAUDE.md` and keeps a memory folder. The pattern works in any assistant that can read and write files. ## Two kinds of context, two kinds of upkeep | | Org library | Personal context | |---|---|---| | Who it serves | Everyone in the organization | One person | | Who maintains it | **People.** Agents propose; a person approves every change. | **The agent.** It writes and curates; you spot-check. | | Why | The organization has to get it right. A wrong fact reaches everyone. | One person's work spans too many projects to keep up by hand, and a wrong note costs one person a detour that they'll catch. | There's a time and a place for both. Don't copy the agent-maintained model into the org library, and don't hold your personal notes to a review process you'll never keep up with. ## The layers ```text CLAUDE.md ← workspace rules: how to work here, where things are └── MEMORY.md ← the memory index: one line per topic, loaded every session └── memory files ← one topic each: a rule, a fact, a project's state, a reference └── handoffs, specs, plans ← the full story of each workstream └── workstream docs, repos, outputs ← the work itself ``` Each layer is short and points to the next. The agent reads the top two every session and opens the rest only when the task needs them, the same as the org library's routing map. ### 1 · `CLAUDE.md`: workspace rules Durable rules for how to work in this folder: where the important documents are, which rules apply everywhere, who owns what. Not project status. If a line will be out of date next month, it belongs in memory or a handoff. ### 2 · `MEMORY.md`: the index One line per memory file: what it is, its current status, at most one warning, and the link. It loads every session, so it has to stay small. Treat about 250 characters per line as a hard limit. At the limit, rewrite the line; don't extend it. ### 3 · Memory files One topic each. Each has a type: - **user**: durable facts about you (your role, your accounts, how you like to work). - **feedback**: a rule for how the agent should work, with **Why** (what happened that led to it) and **How to apply**. - **project**: an ongoing piece of work: its current state, decisions, traps, and a pointer to its handoff. - **reference**: a durable lookup fact or gotcha (how a system behaves, which number to quote and where it comes from). Keep them under about 60 lines. A memory file is the hook, the decisions and the traps, not the build story. ### 4 · Handoffs, specs and plans The full narrative of a workstream: what's done, what's next, what was tried. A fresh session can pick up the work from a handoff alone. Memory points here; it doesn't repeat it. ### 5 · The work itself Documents, code repositories, outputs. These are the final source. When a handoff and the work disagree, the work wins and the handoff gets fixed. ## Keeping it healthy ### At the end of each session: wrap A `/wrap` command (in Claude Code, a skill) that runs a short checklist before you close: 1. **Outcomes to their source.** Everything confirmed done, fixed or decided is written into the document that owns it. The old line is rewritten, not corrected underneath, and any warning it resolved is removed. 2. **Outcomes to memory.** The topic file first, then its index line. 3. **Ideas to handoffs.** Anything "for later" goes into the relevant handoff, dated. 4. **Org facts to the org inbox.** Only real gaps in the org library, as inbox notes for a person to review. 5. **Open markers.** For each file touched this session: did this session close any of its open items? 6. **Notes from other agents** (see below). 7. **Size check.** The index and every file appended to stay within budget. 8. **Next step.** Unfinished work has a dated "next" line in its handoff. ### Once a month: memory review A deeper audit, which proposes changes and waits for your OK before applying them: - **Integrity:** every file is in the index, every index link has a file, and no fact lives only in the index. - **Staleness:** dated open items past their date; items open more than 30 days with no later mention. - **Contradictions:** the index and a file disagree, or two files disagree. The newest dated statement wins, checked against the real source where that's cheap. - **Size:** files over budget get their narrative moved to the handoff they name. - **Duplicates:** the same lesson in two files gets one owner; the other links to it. - **Retirement:** finished topics move to an archive folder under one index line. Entry count, not line length, is what eventually fills the index. - **Notes from other agents.** ### Pitfalls of agent-maintained memory, and the rules that counter them | Pitfall | What it looks like | Rule | |---|---|---| | **Stale alarms** | A warning that was resolved days ago still opens every session as an emergency. | **Close the loop at the source, in the same turn.** When something is confirmed done, rewrite the line that raised it. "That's fine, we did that" is a cue to write, not just an answer. | | **Index-only facts** | A detail exists only in the index line, and a routine cleanup deletes it for good. | **The index is derived, never original.** Write the detail into the topic file first, then the index line as a pointer to it. | | **Bloat** | Memory turns into a second set of handoffs: long session logs, a huge index, slow and noisy reads. | **Keep memory lean.** Hooks, decisions and traps only. Check size before appending; over budget means move the narrative, not add to it. | | **A wrong fact re-firing** | One wrong statement is quoted with full confidence in every session, and copied into new work. | **Correct it where it lives, everywhere it lives.** Search memory for the old value and fix every copy. Keep live numbers out of memory; point to their source instead. | | **Superseded claims left standing** | The old claim and its correction sit side by side, and the agent picks the wrong one. | **State the current truth.** Delete the superseded claim; don't preserve it as history. | ## More than one agent: one writer If you use two agents (for example Claude Code and Codex) in the same workspace, let only one of them write to memory. Two writers produce contradictions, and a wrong memory is quoted with the same confidence as a right one. - **One owner.** Claude Code is the only writer to the memory folder. - **Others propose.** Any other agent writes a note into a `memory-contributions/` folder instead: one file per proposed change, with the target file, the exact text it replaces (the **anchor**), the proposed text, and the evidence. - **Check at start, apply at wrap.** Every owner session starts by listing that folder, and says in one line if notes are waiting, without reading them mid-task. Notes are processed at wrap or at the monthly review. - **Check the anchor first.** If the anchor text no longer appears in the target file, the note is stale: re-check the claim against its evidence; don't guess where it belonged. - **Check the evidence, not memory.** Memory may be the thing that's wrong. Another memory file is never evidence. - **Keep a trail.** Applied notes move to `applied/`, declined ones to `declined/` with the reason. This is the org library's inbox pattern at a smaller scale: one owner applies changes, everyone else proposes. ## Templates ### `CLAUDE.md` skeleton ```markdown # : instructions for agents ## Where things are - Handoffs for in-flight work: `handoff-*.md` at this folder's root - Plans and specs: `` - Org context library (read-only): ; read its AGENTS.md first ## Rules that apply everywhere 1. Read the docs before guessing how a system works. A failed guess isn't evidence. 2. State assumptions as assumptions; verify the ones the work depends on. 3. Close the loop at the source: when something is confirmed done, rewrite the line that raised it, in the same turn. 4. If you break something, stop and say so in that turn: what's damaged, how, and how to recover it. ## Memory - The agent maintains memory; spot-checks. - MEMORY.md is hooks only (one line per topic, about 250 characters max). - Only Claude Code writes to memory. Other agents file notes in `memory-contributions/`. At the start of each session, list that folder (top level only) and say in one line if notes are waiting. Process them at /wrap or the monthly review, after checking each note's anchor. ``` ### A memory file ```markdown --- name: report-numbers-from-the-source description: "Rule: quote live figures from their source system with an as-of date, never from memory" metadata: type: feedback # user | feedback | project | reference --- Quote any figure that changes (member counts, revenue, registrations) from its source system, with the date you read it. Memory holds the pointer, not the number. **Why:** a member count stored in memory was quoted in a board draft three months after it changed (). **How to apply:** - When a task needs a live figure, open the source named in the relevant topic file. - If you can't reach the source, say so. Don't fall back to a remembered number. ``` ### An index line ```markdown - [Report numbers from the source](report-numbers-from-the-source.md) — rule: live figures come from the source system with an as-of date; memory holds the pointer. - [Website rebuild](website-rebuild.md) — staging live; launch blocked on redirects. ⚠ never edit the live theme directly. Handoff: `handoff-website-rebuild.md`. ``` ### A contribution note (from a second agent) File name: `memory-contributions/YYYY-MM-DD-HHMMSS-short-topic.md` ```markdown --- target_file: website-rebuild.md anchor_sha: target_missing: false # true if proposing a new topic file (then omit the anchor) change_type: replace # replace | add-after | new-file contributor: Codex verified: YYYY-MM-DD --- ## anchor_text > The exact text being replaced, copied word for word, about a full sentence. ## proposed The replacement, written the way it should read in the memory file. Current state only: no session narrative, no live numbers. ## evidence Where this was verified: a file and line, a system and what you saw, a command and its output, or the person's own words with the date. Another memory file is not evidence. ## uncertainty Anything unverified or waiting on a decision. "none" if none. ```