memory-management

name	memory-management
description	Read on session start. Manages adaptive durable memory across conversations. Use when reading or writing curated memory under agent-knowledge/Memory/.

Memory Management

Manages the adaptive project memory tree. Read this skill at session start.

The memory directory path is provided by the session-start hook (e.g., ~/.cursor/projects/<project-id>/memory/MEMORY.md). For project-shared memory, the canonical repo entrypoint is ./agent-knowledge. Durable curated memory lives at agent-knowledge/Memory/MEMORY.md.

---

Tree structure

agent-knowledge/
  Memory/
    MEMORY.md               <- root memory note -- always loaded, keep it short
    <topic>.md              <- flat branch note (no subtopics needed)
    <topic>/
      <topic>.md            <- branch entry note (same name as folder)
      <subtopic>.md         <- leaf notes beside the entry
    decisions/
      decisions.md          <- decision log, newest first
      YYYY-MM-DD-slug.md
  Evidence/
    raw/
    imports/
  Sessions/                 <- milestone-oriented temporary state
  Outputs/
  Dashboards/
  STATUS.md

Branch convention

• One branch = one functional domain. Do not lump unrelated subsystems together.
• Folder name = ontology node. The folder is the topic.
• Same-name entry note (<topic>/<topic>.md) = summary and routing for the branch.
• Flat note (<topic>.md) when there are no subtopics yet.
• Promote to folder only when the topic grows subtopics.
• Keep each note under ~150 lines. Split if bigger.
• Link related notes to each other with relative markdown links.
• Use the project's own terminology for branch names, not generic templates.
• Do not use generic names like "architecture" or "conventions" to group unrelated content. Instead, use the project's own domain names (e.g., perception, navigation, localization).

Evidence (agent-knowledge/Evidence/raw/ and agent-knowledge/Evidence/imports/) is separate from curated memory (agent-knowledge/Memory/). Never copy raw evidence into memory. Distill only stable, verified facts. Generated structural outputs belong in Evidence/ or Outputs/ first. Only curated notes under Memory/ are durable project knowledge.

---

Durable note requirements

Every durable memory note must have YAML frontmatter.

Branch notes use these sections:

Section	Content	Updated when
Purpose	One sentence: what this area covers	At creation; rarely changes
Current State	Verified facts about what is true now	Every writeback
Recent Changes	Rolling log, YYYY-MM-DD format, pruned after ~4 weeks	After meaningful changes
Decisions	Links to decisions/YYYY-MM-DD-slug.md	When a decision is recorded
Open Questions	Unresolved items for future sessions	When identified; removed when resolved

Use markdown links for portability. Avoid wiki-links and tool-specific metadata.

---

Reading the tree

1. Memory/MEMORY.md loads automatically first.
2. Identify which branch notes the task touches from the Branches section.
3. Read only the relevant branch entry notes -- keep context lean.
4. For branches with folders, read subtopic notes only if the specific detail is needed.
5. Do not read branches unrelated to your task.

---

Writing to the tree

• Memory/MEMORY.md: short branch summaries + links. No dense detail.
• Branch entry note: all durable facts for that area, organized by section.
• Subtopic note: created only when an entry note grows beyond ~150 lines.
• Decision file: one file per architectural decision, linked from the branch.

Format for facts: lead with the fact. For lessons: add Why: and How to apply:.

---

Bootstrap

If agent-knowledge/Memory/MEMORY.md is missing or empty: -> Read and follow the project-ontology-bootstrap skill before any other work.

---

When to write back

Write to memory when any of these happen:

• A new architectural decision is made
• A pattern or convention is confirmed
• A gotcha is discovered
• A feature area is substantially completed or changed
• A recurring mistake is corrected

Do NOT write:

• In-progress task state -> session file only
• Speculative plans -> wait until confirmed
• Facts already in git history that are easily re-discoverable
• Raw evidence -> keep it in Evidence/
• Machine-generated summaries -> keep in Evidence/ or Outputs/ until curated

---

Compaction

When Memory/MEMORY.md grows noisy or a branch note exceeds ~150 lines: -> Read and follow the memory-compaction skill.

---

Explicit user requests

• "Remember X" -> save it immediately to the relevant branch note
• "Forget X" -> remove or mark stale in the relevant branch note
• "Why did we choose X" -> read decisions/decisions.md and the linked decision file