Memory Manager Skill#

⚠️ All-Agent Protocol: This protocol applies to all agents in the system. Any agent completing a subtask that produces persistable information must write it according to this spec. Do not create memory files outside this structure.

---

When to Trigger#

• Before a conversation ends and new information needs storing

• When the user says "remember", "update memory", or similar

• When existing memory needs correction

• After completing a new type of task (new case)

• Real-time trigger during conversation:

  • Project deadline changes → immediately update blackboard/projects/<id>.md + blackboard/REGISTRY.md (SSOT)
  • Progress milestone completed → immediately update the corresponding Blackboard project card
  • Habit / preference changes → immediately update preferences/
  • Person / tool info changes → immediately update entities/
  • No need to wait for end of conversation or explicit instruction

---

Three-Layer Density Structure#

LayerFilePurposeUpdate FrequencyL0MEMORY.mdMinimal index, 1-3 sentences per category + path pointersOnly on structural changesL1memory/INDEX.mdCategory overview navigation, ~500-1000 wordsWhen L2 file structure changesL2memory/user/ memory/agent/Full details, read on demandDay-to-day maintenance

Retrieval order: Read L0 (MEMORY.md) to locate category → memory_get the relevant L2 → use memory_search for full-text search when uncertain.

---

Directory Structure (L2)#

text

memory/
├── INDEX.md                    ← L1 navigation
├── user/
│   ├── profile.md              # Basic info (appendable)
│   ├── preferences/            # Preferences (appendable)
│   │   ├── learning.md
│   │   ├── lifestyle.md
│   │   ├── tech.md
│   │   └── communication.md
│   ├── entities/               # Entities (updatable)
│   │   ├── tools.md
│   │   └── people.md
│   └── events/                 # Events (append-only)
│       └── YYYY-MM-event-name.md
└── agent/
    ├── cases/                  # Cases (append-only)
    │   └── case-name.md
    └── patterns/               # Patterns (appendable)
        ├── task-delegation.md
        ├── config-backup.md
        └── memory-write.md

---

Classification Decision Flow#

text

New information → determine type
  ├── User identity/background/data change → user/profile.md
  ├── User preferences/habits/style → user/preferences/[topic].md
  ├── Project/tool/person info → user/entities/[type].md
  ├── Key decisions/milestones/irreversible events → user/events/YYYY-MM-[name].md (new file)
  ├── First time handling a new task type → agent/cases/[name].md (new file)
  └── Reusable processing pattern discovered → agent/patterns/[name].md

---

Write Specification#

Format Standards#

• Each file has # Title + structured content
• Appended content is date-stamped: _Updated: YYYY-MM-DD_
• No stream-of-consciousness; write conclusions only

Integration Pattern for New Knowledge / Rules / Skills#

When receiving new knowledge, rules, or a skill, do not just stack it on top — follow this flow:

text

1. Search for existing similar content (memory_search / read relevant skill or pattern files)
2. Compare differences, derive the better conclusion (dedup, absorb, correct)
3. Update the complete content in the authoritative source file
4. Other files referencing that content become pointer-style, not independently maintained

Store details in one place only. Other files use "see X" pointers to avoid future drift.

See memory/agent/patterns/memory-write.md → "Integration pattern for new knowledge/rules"

---

Cascade Update Rules (Mandatory)#

Any change involving the following must check and sync all referencing L1/L2 source files after writing today's memory:

• Agent config / model assignment
• Toolchain / channel changes
• Project status / deadlines
• Protocol rule changes

How: When unsure which files are affected, use memory_search on keywords and verify each one. Today's event log ( memory/YYYY-MM-DD.md) cannot replace source file updates — it is a log, not the source of truth.

---

Dedup Strategy#

SituationActionExact duplicate of existingSkip, do not writeUpdate to existing infoAppend to end of file with date stampConflicts with existingAdd "updated" note after existing entry, append new versionEntirely new infoCreate new file or append to appropriate categoryevents / casesAlways create new file, never modify existing

Prohibited Actions#

• ⚠️ The memory/ root dir may hold current-week session logs (≤7 days); crontab auto-archives to memory/archive/YYYY-MM/ on the 1st of each month. Non-log files (profile/preferences/entities/events/cases/patterns) must go in their L2 category directories
• ❌ Do not write stream-of-consciousness directly to MEMORY.md
• ❌ Do not modify existing files under events/ or cases/

---

L0 Sync Rules (MEMORY.md)#

MEMORY.md is the L0 index; keep it under 30 lines.

When to update MEMORY.md:

1. New events or cases file added → add a one-line pointer in the relevant block
2. Key patterns have major changes → update the summary sentence
3. User basic info has major changes → update the user block

When MEMORY.md does not need updating:

• Small amount of info appended to an existing file
• Routine entities data updates (project progress, etc.)

L0 summary format:

markdown

- **[keyword]**: [one-sentence summary] → `memory/path`

---

L1 Sync Rules (memory/INDEX.md)#

When to update INDEX.md:

1. New L2 file added (new case / event / pattern) → add a row in the corresponding table
2. A file's topic has major changes → update the corresponding summary column
3. Old-format file officially migrated → remove from "to-migrate" list

---

Topic Archive & Compression Protocol#

When to Trigger Archival#

TriggerActionUser says "done / finished / next"Immediately generate topic summary, write to appropriate categoryConversation > 30 turns / tool calls > 40Compress closed topics, free contextNew session starts (/new triggered)Archive previous session's open items to corresponding Blackboard project card

Compression Summary Format (3-line principle)#

Write completed topics in the following format — do not retain raw conversation:

markdown

## [YYYY-MM-DD] Topic Title
Status: ✅ Done / 🔄 In Progress / ⏸️ Pending
Key points: [1-2 sentences of core content or decision]
Decision: [key decision, omit if none]
Follow-up: [only incomplete items; omit if done]
→ Details: [path to detail file if any, otherwise omit]

Tiered Storage Rules#

• Completed topics → write summary (3-5 lines) + status: done, do not retain details
• In-progress tasks → update blackboard/projects/<id>.md + one-line progress in blackboard/REGISTRY.md
• Key decisions / irreversible events → write to memory/user/events/ (permanent)
• Reusable patterns → write to memory/agent/patterns/ (permanent)

Session Reflection#

At session end (/new, idle reset, or user actively switches), if the session contained any of the following, extract one pattern:

TriggerReflection contentWrite toUser corrected a behavior"Next time X occurs, do Y"memory/agent/patterns/ or .learnings/A plan failed and was replaced"Plan X failed because A; switched to Y"memory/agent/patterns/Discovered a hidden tool/config gotcha"When using X, watch out for Y"memory/agent/patterns/ or TOOLS.mdFound a better approach than what docs say"Better approach for X is Y"memory/agent/patterns/

Format:

markdown

## [YYYY-MM-DD] Title
- **Trigger**: what situation was encountered
- **Lesson**: one-sentence conclusion
- **Next time**: specific action guidance

When reflection is NOT needed: pure execution tasks, no corrections, no surprises, routine CRUD.

Relationship to Instinct: Reflection written to patterns/ is low-barrier recording. When the same entry is triggered ≥3 times, promote to a YAML instinct in .learnings/instincts/ (see AGENTS.md §4).

---

Context Pressure Management (Memory Flush Protocol)#

Run session_status to monitor context usage; proactively write to memory at these thresholds:

Context %Action< 50%Normal operation, write on decision50–70%Alert state, write key points after each important exchange70–85%Active flush, immediately write important content to memory> 85%Emergency flush, stop and write a full context summary before continuing

Must-flush content: decisions made and rationale, pending items and owners, unresolved problem threads.

Flush Checklist (check each item to prevent omissions)#

At session end, before compaction, or when user says "done / next" — scan each item:

#CheckWrite targetTrigger words1User preference changed? (taste/habit/tool choice)memory/user/preferences/"I prefer…" "stop doing…" "switch to…"2Project progress advanced?blackboard/projects/<id>.md + REGISTRYdone/blocked/delayed/milestone3New decision made?Project card "conclusions" or memory/user/events/"decided…" "confirmed…" "not doing"4Person/entity info updated?memory/user/entities/new contact / tool change / account info5Reusable pattern discovered?memory/agent/patterns/gotcha / detour / better solution6User corrected something?.learnings/LEARNINGS.mdexplicit correction / dissatisfied / redo

How: Don't need all to fire. Scan the conversation quickly, write what hit, skip what didn't. Takes 3 seconds — don't skip it.

---

Sub-Agent Write Rules#

When any sub-agent completes a task with persistable information:

1. Blackboard project state: update project card + corresponding REGISTRY row directly (spec → blackboard/_schema.md). No need for grep-level cascade checks; the orchestrating agent handles that.
2. Memory-type info: write to the appropriate L2 file per this protocol, note _Written by: [agent name] YYYY-MM-DD_ at the end
3. Notify the orchestrating agent after writing; it syncs L0/L1 indexes as needed