Agent Memory
Architecture

4 Complementary Memory Systems

Claude Code (the CLI/IDE agent) ships with four layered memory systems that work together — from developer-authored project context to fully autonomous learned memory.

1. CLAUDE.md — Project Memory

# Priority hierarchy (highest → lowest):
~/.claude/CLAUDE.md          # User-level (all projects)
./CLAUDE.md                   # Project root
./.claude/CLAUDE.md           # Project config dir
../CLAUDE.md                  # Parent directory (inherited)Copy

• Written by the developer, read by main agent + all subagents.
• Put: project conventions, architecture decisions, coding standards, key context.
• Keep focused — conventions not tutorials. Reference files, don't inline large content.
• Higher-priority files override lower ones in the hierarchy.

2. Auto-Memory

• Claude Code automatically saves useful context between sessions — things it learns about your codebase, preferences, and patterns.
• Per-project, per-user scope. No cross-project leakage.
• Main agent only — subagents don't see auto-memories.
• Managed via the /memory command in Claude Code CLI.

3. /memory Command

• Opens an editor to manually review and edit Claude's stored memories.
• Use to curate what Claude remembers about your project — delete noise, add important context, restructure.
• Think of it as direct access to Claude's "notebook" for this project.

4. Subagent Persistent Memory (v2.1.33+)

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Write, Edit, Bash
model: sonnet
memory: user
---
You are a code reviewer.
Update your memory with patterns and conventions you discover.Copy

Memory Scopes

• First 200 lines of MEMORY.md injected into subagent system prompt at startup.
• Agent has Read/Write/Edit access to its memory directory.
• If MEMORY.md exceeds 200 lines, agent moves details to topic files in its memory dir.

Best Practices

• Keep CLAUDE.md focused: conventions, not tutorials. It's a cheat sheet, not a manual.
• Use memory: user for subagents that should learn across projects — code reviewers, style enforcers, test writers.
• Combine skills (static knowledge) + memory (dynamic, learned over time) for the most capable agents.
• Reference files instead of inlining large content — keep CLAUDE.md lean.
• Update CLAUDE.md as the project evolves — treat it as living documentation, not a write-once config.

Memory Tool

from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition

# Enable the Memory Tool (file-based, you own storage)
message = client.messages.create(
    model="claude-opus-4-6",
    tools=[{"type": "memory_20250818", "name": "memory"}],
    messages=[...]
)Copy

Subagent with Persistent Memory

# Subagent with persistent memory
agents={
    "researcher": AgentDefinition(
        description="Research agent with persistent memory",
        tools=["Read", "Write", "Glob", "Grep"],
        model="sonnet",
        memory="user",  # Persists across projects
    ),
}Copy

Context Editing

# Context Editing (84% token reduction in 100-turn tests)
response = client.beta.messages.create(
    model="claude-opus-4-6",
    context_management={
        "edits": [
            {"type": "clear_tool_uses_20250919"},
            {"type": "clear_thinking_20251015",
             "keep": {"type": "thinking_turns", "value": 2}}
        ]
    }
)Copy

Key Concepts

• Memory Tool: Claude makes CRUD calls against your storage backend — files, a database, or S3. You control persistence.
• CLAUDE.md: Project-level persistent memory files. Loaded automatically, editable by the agent.
• Subagent memory scopes: user (cross-project), project (team-shared), local (personal per-agent).
• Context Editing + Memory Tool together: +39% performance improvement in complex multi-turn sessions.

Configuration

// ~/.openclaw/openclaw.json
{
  agents: {
    defaults: {
      memorySearch: {
        provider: "openai",  // OpenAI-compatible endpoint
        remote: {
          baseUrl: "http://localhost:1234/v1/",  // LM Studio
          apiKey: "lm-studio",
          batch: { enabled: false }
        },
        fallback: "none",
        model: "text-embedding-qwen3-embedding-0.6b",
        query: {
          minScore: 0.25,
          hybrid: {
            enabled: true,
            vectorWeight: 0.6,
            textWeight: 0.4,
            candidateMultiplier: 4,
            mmr: { enabled: false },
            temporalDecay: { enabled: false }
          }
        },
        experimental: { sessionMemory: true },
        sources: ["memory", "sessions"],
        extraPaths: ["TOOLS.md", "USER.md", "SOUL.md", "AGENTS.md"]
      }
    }
  }
}Copy

Agent Capabilities

• memory_search: Semantic recall — query past memories with natural language, returns ranked results with hybrid BM25 + vector scoring.
• memory_get: Targeted read — fetch specific memory files by path when you know what you need.
• Pre-compaction flush: Automatic reminder triggers the agent to save durable memories before context compaction discards working memory.
• Session transcript indexing: Past conversation turns are indexed and searchable, enabling cross-session memory without explicit logging.
• QMD backend (experimental): BM25 + vectors + reranking sidecar for advanced retrieval pipelines.

Automated Extraction + Consolidation

# Automated extraction + consolidation pipeline
# Runs as: python -m memory_pipeline extract|consolidate|status

# Daily: extract novel facts from sessions
$ python -m memory_pipeline extract
# → Scans sessions, embeds chunks, compares against memory
# → Sends novel chunks to Opus for fact extraction
# → Writes to memory/YYYY-MM-DD.md

# Weekly: consolidate and deduplicate
$ python -m memory_pipeline consolidate --apply
# → Clusters similar memories, identifies duplicates
# → Opus merges and resolves contradictions
# → Promotes high-value entries to MEMORY.mdCopy