3-Tier Memory System Spec

Core Model

The system uses a 3-layer memory architecture:

Numbered Vault Structure

The local memory uses an Obsidian-style numbered vault layout. Each directory has a specific purpose. Navigation starts at memory/00-home/index.md when orienting inside the graph.

memory/00-home/       — Navigation entrypoints
memory/10-maps/       — Maps of systems, domains, and note locations
memory/15-specs/      — Formal local specs
memory/20-domains/    — Stable domain truths
memory/30-decisions/  — Durable decisions and policies
memory/40-research/   — Canonical research takeaways
memory/50-operations/ — Operating procedures, scoreboards, and workflows
memory/60-daily/      — Chronological daily notes (YYYY-MM-DD.md)
memory/70-weekly/     — Weekly synthesis notes (YYYY-WW.md)
memory/99-archive/    — Compressed historical detail

Memory Classes

Every piece of information falls into one of five classes. Each class has a canonical home. The agent should never store information outside its designated surface.

1. Durable Facts

Approved decisions, standing directives, stable ownership rules, approved process changes.

• MEMORY.md for active operating truth
• memory/20-domains/, memory/30-decisions/, memory/40-research/ for longer-lived canonical notes

2. Operational State

Current blockers, active watch items, counters and scorecards, approval backlog.

• Canonical home: MEMORY.md

3. Daily Log

Same-day execution trace, short-horizon observations, checkpoint residue not yet promoted, chronology for what changed today.

• Canonical home: memory/60-daily/YYYY-MM-DD.md

4. Weekly Synthesis

Compression of the last 7 daily logs, recurring patterns from the week, durable promotions identified from daily notes, stale detail ready for archive.

• Canonical home: memory/70-weekly/YYYY-WW.md

5. Archive

Stale detail removed from active files, historical rollups, old logs that no longer need to live in prompt-critical surfaces.

• Canonical home: memory/99-archive/

Checkpoint Triggers

A memory checkpoint is required on each of these triggers. No exceptions.

1. Task completion
2. Model/tool/provider failure
3. Escalation
4. Compaction or memoryFlush
5. Before /new, /reset, or session end
6. Any fallback event or model-routing change that materially changes execution state
7. Any directive from the owner that creates a new standing rule, policy, or decision

Checkpoint Write Order

On each required checkpoint, write in this exact order:

1. Append short-horizon facts to memory/60-daily/YYYY-MM-DD.md
2. Promote durable local operating truth to MEMORY.md
3. Promote durable strategic/decision truth to memory/30-decisions/
4. If the item is canonical and cross-agent, also route it into _shared/knowledge/

Retrieval Order

When recalling context, read in this order:

1. MEMORY.md
2. _shared/knowledge/ when the topic may be canonical or cross-agent
3. memory/20-domains/, memory/30-decisions/, memory/40-research/
4. memory/10-maps/ and memory/00-home/index.md when navigation is needed
5. memory/60-daily/ for chronology and unpromoted short-horizon facts
6. memory/70-weekly/ for synthesis context
7. Recent session context only if the answer is still not found

Routing Policy

Every piece of information routes to one of three destinations based on its scope and durability.

Local Only

Use local memory (MEMORY.md + memory/) when the item is:

• Role-specific
• Interpretive or managerial
• Short-horizon
• A watch item, concern, or synthesis note
• Mainly useful to the orchestration role

Shared Only

Use _shared/knowledge/ when all of these are true:

1. Relevant to multiple agents
2. Durable for at least 1-2 weeks
3. A fact, rule, definition, or approved decision
4. Should remain consistent across the organization

Both

Use both local and shared only when the item is canonical company truth and the agent must actively enforce or monitor it.

Rules for Each Surface

MEMORY.md

• Holds durable facts and active operating state
• Should remain concise and prompt-useful
• Must not become a warehouse for all raw detail
• Prefer pointers and active implications when a better canonical note exists elsewhere in the graph

Daily Notes

• Append-only by date
• Used for chronology and same-day continuity
• Not the first home for durable truth

Weekly Notes

• Summarize the last 7 daily notes
• Promote durable items out of daily notes into canonical surfaces
• Capture patterns, not raw event streams
• Move stale or low-value detail toward archive

Archive

• Preserve historical detail without polluting active prompt surfaces
• Use for rollups and long-form history after promotion/compression

Anti-Duplication Rule

The same operational fact should have one canonical home. Never two.

• STATUS.md should summarize canonical state, not become a second database
• Daily notes should not duplicate full durable truth already captured elsewhere
• MEMORY.md should not repeat everything that belongs in domain/decision/research notes

Startup Read Order

Before acting on any task, the agent should read these files in order:

1. Governance files
2. MEMORY.md
3. memory/00-home/index.md
4. Today's memory/60-daily/YYYY-MM-DD.md if present
5. Current memory/70-weekly/YYYY-WW.md if present

Recreation Checklist

To implement this system from scratch, complete every item:

• ✓Create the numbered memory/ vault with all 10 directories
• ✓Define MEMORY.md as durable facts + operating state
• ✓Define memory/60-daily/ as daily chronology
• ✓Define memory/70-weekly/ as synthesis/compression
• ✓Define memory/99-archive/ as historical spillover
• ✓Enforce checkpoint triggers
• ✓Enforce checkpoint write order
• ✓Enforce retrieval order
• ✓Enforce anti-duplication discipline
• ✓Use _shared/knowledge/ only for canonical cross-agent truth

Compressed Version

If your agent needs a single-paragraph summary to internalize the system: