Persistent-Memory Architecture¶
Why this document exists¶
The framework's persistent memory is spread across six distinct layers with different lifetimes, owners, and edit semantics. Without an explicit architecture document, AI roles and human readers can't tell which layer holds what — and end up either duplicating state across layers (inflating the noise) or losing state (writing to the wrong layer and assuming it persists).
This document is the map. MEMORY-INDEX.md at D:\claude_www\MEMORY-INDEX.md is the per-file inventory; this document is the architecture that index files in.
The six layers¶
| # | Layer | File-backed? | Lifetime | Owner | Where it lives |
|---|---|---|---|---|---|
| 1 | Anthropic auto-summary | NO | Per conversation | Anthropic platform | Inside Claude's context, not on disk |
| 2 | Framework filesystem | YES | Permanent | mc1-code + role sessions | D:\claude_www\projects\ + framework/ + org_charter.md |
| 3 | Shared + role memory | YES | Permanent | Each role owns their subdir | D:\claude_www\memory\shared\ + memory/<role>/ |
| 4 | conversation_search index | NO | Indexed by Anthropic | Anthropic platform | Not on disk; queried via tool |
| 5 | Session handoffs | YES | Permanent (append-only) | Each role + chat-MC1 | D:\claude_www\handoffs\ + agent_comms/ mailboxes |
| 6 | Methodology / MkDocs library | YES | Permanent (living) | chat-MC1 + each manager | D:\claude_www\projects\enterprise\strategy\ |
Scope of this document: Layers 2, 3, 5, 6 — the file-backed layers that can be inventoried, organized, and reasoned about. Layers 1 and 4 are platform-native; we cannot touch them.
Layer 2 — Framework filesystem¶
Purpose: the organizational structure of the AI org — who exists, what they own, what they do.
What lives here:
- D:\claude_www\projects\ — role workspaces (accounting_manager/, it_manager/, mc1/, etc.) + integration projects (ansible/, authentik/, mattermost/, etc.) + projects/enterprise/ (strategic spine docs source — overlaps with Layer 6)
- D:\claude_www\framework\ — separate git-tracked sub-repo with role_*/, runbooks/, shared/, templates/
- D:\claude_www\org_charter.md — top-level org charter
Owner: Each role owns their projects/<role>/ workspace. framework/ is its own sub-repo with its own history.
Edit cadence: Whenever a role definition, scope, or workspace evolves. Live agents read paths in projects/<role>/ — moving them breaks the agent.
Layer 3 — Shared + role memory¶
Purpose: persistent knowledge each role brings to each new session, plus org-wide governance that every role reads.
What lives here:
D:\claude_www\memory\shared\— 16 governance docs read by every role at session start:principal-facts.md— Brandon's identity, address, card-on-file, decision stylebedrock-principles.md— the bedrock #1-#7 reversibility/aggregate-harm/scope/etc.standing-instructions.md+ addenda (initiative, mattermost, cross-check-claims, v2)communication-rhythm-directive.md+ addendum-mattermostdecision-log.md— framework-canonical decision record (see §dual decision logs)operating-principle-honest-state-markers.mdoperating-principle-independent-reviewer.mdanti-pattern-text-vomit.mdorg-state.mdsession-start-protocol.mduniversal-glossary.mdfuture-considerations.mdD:\claude_www\memory\<role>\— per-role persistent memory:- accounting_manager (24), operations_manager (22), website_design_manager (24), sales_marketing_manager (13), software_engineer (10), se_infrastructure (2), auction_manager (1), mc1_code (1), people (4)
D:\claude_www\memory\_archive\— already-archived prior versions (365 files, preserved; do not consolidate or move — see "Three archives" note)
Owner: Each role owns memory/<role>/. memory/shared/ is org-wide; edits broadcast through agent_comms/broadcast/.
Edit cadence: Role memory grows as the role learns. Shared governance is rare-edit; changes are ratified events.
Layer 5 — Session handoffs + agent communications¶
Purpose: the audit trail of inter-session and inter-role communication. Append-only by convention.
Two sub-patterns:
Session-handoff pattern (handoffs/)¶
D:\claude_www\handoffs\<role>\— per-role handoffs from one session to the next- Roles: accounting_manager, auction_manager, it_manager, mc1_code, operations_manager, sales_marketing_manager, se_infrastructure, software_engineer, website_design_manager
D:\claude_www\handoffs\chat-MC1-current-state.md— the file pasted at the start of every new chat-MC1 session (see §current-state pointer)- Files dated
YYYY-MM-DD_<topic>.md; never overwritten — superseded by new entries
Agent-comms mailbox pattern (agent_comms/)¶
D:\claude_www\agent_comms\to_<role>\— inbound mail to that roleD:\claude_www\agent_comms\from_<role>\— outbound mail from that roleD:\claude_www\agent_comms\broadcast\— org-wide broadcasts- Frontmatter convention:
from / to / cc / sent / topic / status / urgency / references - 620+ files of mailbox history — permanent audit trail
Owner: Originating role writes; receiving role reads. mc1-code routes cross-role coordination memos.
Edit cadence: Continuous. Mailbox + handoffs are the primary communication channel between async sessions.
Layer 6 — Methodology / MkDocs library¶
Purpose: the strategic + operational documentation that stakeholders read (Brandon, Dennis, future advisors, external readers). Renders as https://strategy.copperstatetruckparts.com/ via MkDocs.
What lives here:
- D:\claude_www\projects\enterprise\strategy\ — 70+ docs covering:
- index.md — apex
- operating-arms/, future-arms/, partner-side/ — per-entity docs
- operations/ — cross-cutting operations (intercompany billing, entity reasoning, this document, etc.)
- people/ — per-person profiles
- decisions/decision-log.md — spine-canonical decision record (see §dual decision logs)
- decisions/deferred-decisions.md — DDM system
- decisions/brandon-action-items.md
- principles/, methodology/ — operating principles + per-manager methodology library
- interview-methodology/ — Dennis + Jose microphone interview patterns
- ai-organization/ — framework overview
- archive/ — superseded versions
- D:\claude_www\projects\enterprise\mkdocs.yml — config + nav
Owner: chat-MC1 authors strategic docs + decision log; each manager authors their methodology document; mc1-code stages + maintains nav.
Edit cadence: Living. Updates after each strategic conversation, decision, or major operational change.
The notepad pattern (working memory)¶
Purpose: active per-topic working memory that doesn't fit a role memory file or a strategic spine doc.
Where: D:\claude_www\notepads\<topic>.md
Use: Brandon edits these directly to surface inputs the agents need (e.g. ironmesa.md captures Iron Mesa USA owner-input items during the website audit). Managers watch their relevant notepads + read on session start.
Cadence: Notepad files populate naturally as Brandon writes new ones. No backfill, no placeholder stubs. The pattern proves itself.
The session-handoff pattern in practice¶
Every Claude session ends by writing a handoff for the next session of the same role. The handoff captures:
- What was completed this session
- What's in flight (mid-execution state)
- What's blocked (and on what)
- Open questions surfaced to Brandon
- Next-session priorities
The next session reads its role's most recent handoff first, then mailbox to_<role>/ for inbound, then proceeds.
handoffs/chat-MC1-current-state.md is a special handoff: it's the file Brandon pastes at the start of every new chat-MC1 session to bring the strategic surface back online (Layer 1 auto-summary doesn't persist across sessions; this is the file-backed substitute).
Session-start-audit vs session-handoff — related but distinct patterns. A session-handoff answers "where are we for the next session" (forward-looking continuity, written at end of session). A session-start-audit answers "what did I find when I oriented" (backward-looking observation, written at start of session). They are NOT folded into each other — same Layer 5 family but different artifacts. Session-start audits currently live at notes/<role>/session-start-audit-*.md or notes/<role>/<date>_session-start.md (mc1-code, operations_manager). Do not merge by reflex.
Dual decision logs — both authoritative, different scopes¶
The framework intentionally maintains two decision-log files. They are NOT merged; each has its own canonical scope.
memory/shared/decision-log.md — framework-canonical¶
- Scope: decisions affecting how the framework + roles operate together
- Examples:
DECISION-MM-PRIMARY-ENFORCED,DECISION-REGISTRAR-CF-CONSOLIDATION,DECISION-LLM-INFRA-MANAGED-API,DECISION-AM-AGENT-LIVE-PRODUCTION,DECISION-CACTUS-IMS-WDM-OWNS,DECISION-MKDOCS-V0.2-CANONICAL-SOURCE,DECISION-MANAGER-AGENT-ORDERING - Read by: every Claude role at session start (Layer 3 shared)
- Format:
DECISION-<NAME> — <DATE> — <one-line summary>followed by Made-by + Implications + Supersedes lines - Append-only: corrections via new entries with
Supersedes:
projects/enterprise/strategy/decisions/decision-log.md — spine-canonical¶
- Scope: decisions affecting the strategic enterprise narrative (entity-level, multi-arm strategic choices, things external stakeholders read about)
- Examples: DET activation, MkDocs pivot, Andrea/Karin correction, Tomkins name correction, substrate v1.0 LIVE, SP entity description, framework-as-product future arm
- Read by: Brandon, Dennis, future advisors (via MkDocs render); chat-MC1 maintains
- Format: dated section headers (
## 2026-05-27) with subsections per decision - Append-only: chronological log
How to choose where a decision goes¶
| If the decision... | Log it in... |
|---|---|
| Changes how AI roles operate (MM-primary, cost caps, tier routing, agent ordering) | memory/shared/decision-log.md |
| Changes the strategic enterprise (entity activation, partner relationships, future arms) | projects/enterprise/strategy/decisions/decision-log.md |
| Both | Both, with cross-reference; the strategic version cites the framework version |
Do not merge these by reflex. They have different audiences and different scopes. The dual-log is intentional architecture, not duplication.
MEMORY-INDEX.md — the per-file inventory¶
D:\claude_www\MEMORY-INDEX.md is the auto-generated inventory of every memory-bearing file across Layers 2, 3, 5, 6. It catalogues:
- Path (relative to
D:\claude_www\) - Last-modified date
- Size
- Memory layer (heuristic classification)
- Status (LIVE_CURRENT / LIVE_HISTORICAL / ARCHIVED)
- One-line purpose (from H1 title where available)
Regeneration: Run python D:\claude_www\.tmp\build_memory_index.py to refresh. Generator is itself a memory-bearing file (in .tmp/ because it's a working tool, not architectural).
Cadence per layer:
| Layer | Inventory refresh trigger |
|---|---|
| L2 — Framework | When role workspaces materially change (new role, sub-repo restructure) |
| L3 — Shared/role memory | Monthly or after major governance edit |
| L5 — Handoffs + agent_comms | Monthly (grows continuously; mostly LIVE_HISTORICAL) |
| L6 — MkDocs library | After each strategic content drop (new chat-MC1 doc, methodology addition, decision-log entry) |
Three archive locations — preserved as-is, do NOT consolidate¶
The framework has three archive locations:
D:\claude_www\memory\_archive\(365 files) — historical role memoryD:\claude_www\_archive\(21 files) — historical framework artifactsD:\claude_www\archive\—mc1-superseded/+ post-2026-05-30 cleanup artifacts
These look duplicative but are intentionally separate. References from live framework files point INTO these specific paths. Consolidating them would break links. The MEMORY-INDEX.md records all three; that solves the findability problem without the breakage of moving.
Live-paths-untouched rule (deferred-reorg risk surface)¶
The following paths are read by live agents in production. Do NOT move or rename without coordinated path-update + agent restart:
D:\claude_www\projects\accounting_manager\agent-persona.md— AM-agent reads every cycleD:\claude_www\projects\accounting_manager\categorization-rules.md— AM-agent reads every cycleD:\claude_www\projects\enterprise\mkdocs.yml— IT MkDocs build (deployed to strategy.copperstatetruckparts.com)D:\claude_www\projects\enterprise\strategy\— MkDocsdocs_dirD:\claude_www\memory\shared\session-start-protocol.md— every session reads at startD:\claude_www\projects\<role>\— every role-Claude session starts in this workspace
IT flat-root memory. IT's canonical memory lives as flat files at memory/ root, not in a memory/it_manager/ subdir, for historical reasons (entrenched before the role-subdir pattern existed). Live IT runbooks reference these flat paths directly (e.g. memory/project_truenas_hardware_state.md). If the deferred structural reorg ever un-parks, migrating IT's flat-root files requires updating every runbook path reference in lockstep — same discipline as the AM-agent production paths. Do not relocate IT's flat-root memory files as part of any general memory/ tidy without a path-update plan.
Reorganization plans that affect any of these paths require explicit chat-MC1 ratification + a coordinated cutover with affected agents/scripts.
Open architectural questions¶
- Layer 1 + Layer 4 are platform-native. Reasoning about how they interact with file-backed layers (when do summaries leak into file memory? when do search results conflict with file content?) is a research question, not a daily-operations concern.
- Memory-pruning policy isn't defined.
agent_comms/andmemory/_archive/grow unboundedly. At what point does the framework consciously prune vs continue accumulating? - Cross-role memory (notes one role makes about another's domain) currently lives in the originating role's memory. Whether to surface to the subject role's memory is case-by-case.
These questions are deferred; flag here for future architectural conversations.
Living document. Last updated 2026-05-30 by mc1-code under Step 3 of the persistent-memory cleanup directive.