agent-memory-protocol（Agent 内存协议）

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

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)

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

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:

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

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:

- **[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

Compression Summary Format (3-line principle)

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

## [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:

Format:

## [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:

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:

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