robotaitai/project-bedrock/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.

Durable note requirements

Every durable memory note must have YAML frontmatter.

Branch notes use these sections:

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