memory-management

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.