Skip to main content
recursive-mode maintains a memory plane separate from run artifacts and control-plane docs. Memory stores project knowledge that is worth keeping across runs — domain context, reusable patterns, recurring failure modes, and capability guidance. It is intentionally distinct from the current repository state and from run-specific evidence.
Read /.recursive/memory/MEMORY.md at the start of every new session and at the start of every new run. MEMORY.md is the router and index for the entire memory plane — start there, then load only the memory docs relevant to your current task.

​
What memory is for

Memory answers a different question than STATE.md or DECISIONS.md:
DocumentQuestion it answers
/.recursive/STATE.mdWhat is true in the codebase right now?
/.recursive/DECISIONS.mdWhat decisions were made and why?
/.recursive/memory/What has been learned that’s worth remembering across runs?
Use memory to store things that have proven durable — a recurring architectural pattern, a subsystem that frequently causes regressions, a lesson that surfaced in multiple runs. Do not use memory as a dump for session noise or one-off observations that have not been validated.

​
Memory directory layout

The router and index for the entire memory plane. It records the memory taxonomy, retrieval guide, freshness policy, sharding rules, and an ownership map of which memory docs cover which paths. Read this first — do not load the full memory tree without reading MEMORY.md first.
Domain memory docs capture durable knowledge about specific areas of the codebase — architecture, data flows, subsystem boundaries, and ownership. Each domain doc declares Owns-Paths (the code surfaces it is authoritative for) and Watch-Paths (paths it monitors for relevant changes).
Pattern docs record reusable implementation patterns that have proven effective in this repository. They declare Watch-Paths without owning the paths outright. Use patterns docs for things like “the standard way to add a new API endpoint” or “the approved error-handling strategy.”
Incident docs record recurring failure modes, past regressions, and known problem areas. When a pattern of failure is strong enough to be worth remembering, it belongs here so future runs can check for it proactively.
Episode docs capture significant run histories or cross-run narratives — for example, a multi-run migration, a refactor that unfolded over several tasks, or a platform-specific investigation that took multiple iterations to resolve.
Skills memory is a first-class part of the memory plane. SKILLS.md is the skill-memory router. Durable skill knowledge is sharded under four subdirectories:
  • availability/ — environment-specific capability probes and availability notes
  • usage/ — stable skill fit and usage guidance
  • issues/ — recurring skill failures or confusing behavior
  • patterns/ — reusable multi-skill operating patterns
Load SKILLS.md and relevant skill shards when a run involves delegated review, subagent help, review bundles, or other capability-sensitive execution.
Deprecated memory docs that have been superseded or are no longer relevant. Archived docs are excluded from normal retrieval and kept only for historical reference.

​
Memory status values

Every durable memory doc (except MEMORY.md and SKILLS.md) carries a Status field:
StatusMeaningUsed in retrieval?
CURRENTAuthoritative for planning and executionYes
SUSPECTMay be used as a lead but must be revalidated before trustYes, with caution
STALEOutdated; excluded from default retrievalNo
DEPRECATEDHistorical only; excluded from default retrievalNo
DRAFTCandidate memory, not yet durableNo
Prefer CURRENT docs for all planning and execution. Use SUSPECT docs only as leads — revalidate them before acting on them.

​
When to read memory

1

Start of every session

Read /.recursive/STATE.md, /.recursive/DECISIONS.md, and /.recursive/memory/MEMORY.md before doing any work. These three docs orient you to the current state of the repo and the accumulated knowledge from prior runs.
2

Start of every run

Re-read all three before creating or updating run artifacts. Then use DECISIONS.md to identify any earlier runs relevant to the current requirement or subsystem.
3

Load relevant shards only

After reading MEMORY.md, load only the memory docs relevant to the current task. Do not load the entire memory tree by default.
4

Load skills memory when needed

If the run involves delegated review, subagent help, review bundles, or other capability-sensitive execution, load /.recursive/memory/skills/SKILLS.md and the relevant skill shards before planning or auditing.

​
When memory is updated

Memory is updated in Phase 8 at run closeout. Phase 8:
  1. Reviews which memory docs have Owns-Paths or Watch-Paths that overlap with the validated diff.
  2. Downgrades any CURRENT docs touched by the diff to SUSPECT until semantic review against the final code, STATE.md, and DECISIONS.md is complete.
  3. Promotes durable lessons from the run into the appropriate memory subdirectory.
  4. Creates a new domain doc (or records a follow-up) for any changed code paths not covered by an existing domain doc.
  5. Records a run-local skill usage capture and decides what, if anything, is worth promoting into /.recursive/memory/skills/.
Phase 8 produces 08-memory-impact.md as a compact delta receipt pointing to the updated memory docs.

​
Skills memory

Phase 8 must update skill memory when a run teaches the repository something durable about:
  • skill availability in this environment
  • skill fit for a specific type of task
  • delegated review quality
  • repeated workflow friction with a skill
Record skill discoveries in /.recursive/memory/skills/ so future runs don’t have to rediscover whether a subskill is available or how well it fits a particular task pattern.

​
Memory freshness rules

Every durable memory doc includes metadata fields that support freshness tracking: 
Type: `domain`
Status: `CURRENT`
Scope: `Authentication subsystem`
Owns-Paths:
- `src/auth/**`
Watch-Paths:
- `src/middleware/session.ts`
Source-Runs:
- `/.recursive/run/42/`
Validated-At-Commit: `a1b2c3d4`
Last-Validated: `2025-10-01T14:00:00Z`
Tags:
- `auth`
- `session`
If the final validated diff of a run touches a path matched by Owns-Paths or Watch-Paths, that memory doc must be reviewed in Phase 8. A doc stays SUSPECT until the reviewing agent has checked it against the final code, STATE.md, and DECISIONS.md and confirmed it is still accurate.