ClawHub

Agent Memory Protocol

Agents
Agent MemorySync

Agent memory management protocol. Activate for any memory read, write, or update operation. Defines six-category write spec, L0 sync rules, and dedup strategy.

Install

openclaw skills install @ottoprua/agent-memory-protocol

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 Frequency
L0MEMORY.mdMinimal index, 1-3 sentences per category + path pointersOnly on structural changes
L1memory/INDEX.mdCategory overview navigation, ~500-1000 wordsWhen L2 file structure changes
L2memory/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)

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

SituationAction
Exact duplicate of existingSkip, do not write
Update to existing infoAppend to end of file with date stamp
Conflicts with existingAdd "updated" note after existing entry, append new version
Entirely new infoCreate new file or append to appropriate category
events / 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:

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

TriggerAction
User says "done / finished / next"Immediately generate topic summary, write to appropriate category
Conversation > 30 turns / tool calls > 40Compress closed topics, free context
New 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:

## [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 to
User 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.md
Found a better approach than what docs say"Better approach for X is Y"memory/agent/patterns/

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:

Context %Action
< 50%Normal operation, write on decision
50–70%Alert state, write key points after each important exchange
70–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 words
1User 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/milestone
3New 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 info
5Reusable pattern discovered?memory/agent/patterns/gotcha / detour / better solution
6User 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
More in Agents