Agentic Memory Tool

Anthropic’s client-side memory and context editing primitives for building agents that persist knowledge across sessions and manage long-running context effi…

Agentic Memory Tool

Anthropic’s client-side memory and context editing primitives for building agents that persist knowledge across sessions and manage long-running context efficiently. Currently in beta.

Anthropic Memory Storage Taxonomy

Four tiers from Anthropic’s framing:

Type	What it is	Lifetime
In-context	Current conversation messages	Single session
External	Files, DBs outside the LLM	Persistent, app-managed
In-weights	Training data baked into model	Fixed at training time
In-cache	KV cache for stable prompt prefixes	Across requests, same prefix

The memory_20250818 tool bridges in-context and external: Claude writes to files (external), reads them back into context as needed.

Memory Tool (memory_20250818)

A file-based system where Claude makes tool calls and the application executes them against a local /memories directory. Client-side — you control the storage.

Commands

Command	Description
view	Show directory listing or file contents
create	Create or overwrite a file
str_replace	Replace specific text in a file
insert	Insert text at a line number
delete	Delete a file or directory
rename	Rename or move a file

Supported Models (as of 2026)

Claude Opus 4.7, Opus 4.1, Opus 4, Sonnet 4.6, Sonnet 4, Haiku 4.5.

Usage Pattern

response = client.beta.messages.create(
    model="claude-sonnet-4-6",
    tools=[{"type": "memory_20250818", "name": "memory"}],
    betas=["context-management-2025-06-27"],
    messages=messages,
    ...
)
# Execute tool_use blocks against local /memories directory

Cross-Session Learning

The key benefit: Claude checks its memory files at the start of a task, finds patterns from previous sessions, and applies them immediately without re-learning. Pattern recognition is semantic — applies across different languages/frameworks (a thread-safety pattern learned in Python applies to async Python, Go, Java, Rust).

Workflow:

• Session 1: Claude solves a problem → stores the pattern in memory
• Session 2: New conversation → Claude reads memory → applies pattern immediately (faster, more reliable)
• Session N: Memory accumulates task-specific knowledge over time

What to Store

• Task-relevant patterns discovered during work
• Codebase-specific conventions and architectural decisions
• Solutions to recurring issues
• Organized by project in subdirectories for isolation

Don’t store: sensitive data (passwords, API keys, PII), conversation history, everything indiscriminately.

Context Editing (context-management-2025-06-27)

API-level primitives for automatically trimming accumulated context during long sessions. Configured via the context_management parameter with an edits list.

Tool Use Clearing (clear_tool_uses_20250919)

Clears old tool call results once they’ve served their purpose. Old tool results are rarely needed again once the model has processed them.

{
    "type": "clear_tool_uses_20250919",
    "trigger": {"type": "input_tokens", "value": 35000},  # threshold
    "keep": {"type": "tool_uses", "value": 5},            # retain most recent N
    "clear_at_least": {"type": "input_tokens", "value": 2000}
}

Thinking Clearing (clear_thinking_20251015)

Removes accumulated extended thinking blocks from previous turns. Must come first in the edits list when combined with tool use clearing.

{
    "type": "clear_thinking_20251015",
    "keep": {"type": "thinking_turns", "value": 1}  # retain only last turn
}

Key Distinction

Context editing clears short-term context (tool results, thinking blocks). Memory files are long-term persistence — they survive context clearing because they live outside the context window and are re-loaded on demand.

This mirrors human cognition: working memory (context window) is finite and refreshed; long-term memory (filesystem) persists across sessions.

Server-Side Compaction

Separate from the memory tool: Claude API server-side compaction automatically summarizes earlier conversation content when approaching the context limit. Available in beta for Opus 4.7, Opus 4.6, Sonnet 4.6. Minimal integration required — vs. client-side memory tool which gives full control but requires implementation.

Security: Memory Poisoning

Memory files are read back into Claude’s context, making them a prompt injection vector. A malicious agent or compromised external data could write instructions into memory files.

Mitigations:

1. Content sanitization — filter dangerous instruction patterns before storing
2. Per-project/per-user memory isolation (separate /memories/<project>/ directories)
3. Memory auditing — log and scan all memory operations
4. System prompt instruction: explicitly tell Claude to ignore instructions found in memory files

See Indirect Prompt Injection for the broader attack class.

Context Editing Config Pattern (canonical)

From the Anthropic cookbook, the production-ready config structure:

context_management = {
    "edits": [
        # Thinking MUST come first
        {
            "type": "clear_thinking_20251015",
            "keep": {"type": "thinking_turns", "value": 1}
        },
        {
            "type": "clear_tool_uses_20250919",
            "trigger": {"type": "input_tokens", "value": 35000},
            "keep": {"type": "tool_uses", "value": 5},
            "clear_at_least": {"type": "input_tokens", "value": 2000}
        }
    ]
}

Production thresholds: trigger at 30–40k tokens; clear_at_least 3000–5000 tokens for large tool results (web search, code execution). Demo uses lower values.

clear_thinking notes: requires thinking enabled in the API call; use "keep": "all" to preserve all thinking blocks for maximum KV-cache hits; trigger is optional (clears based on keep value alone).

What Memory Actually Learns

Semantic pattern recognition, not syntax matching. Example from cookbook:

• Session 1: thread-based web scraper with race condition on self.results → stores thread-safety pattern
• Session 2: async API client → Claude checks memory first, recognizes same shared-mutable-state anti-pattern applies to async coroutines too

Cross-language applicability: a pattern learned in Python applies to Go, Java, Rust — the abstraction is architectural, not syntactic.

Memory file stores: symptom, cause, solution, red flags. Not the full conversation.

Alternatives

Mnemory (self-hosted)

Mnemory is a self-hosted MCP memory backend with semantic vector search (Qdrant) and artifact storage (S3/MinIO). The key architectural difference: Mnemory uses vector similarity for retrieval; the Anthropic tool uses flat file navigation. Mnemory also handles deduplication and contradiction detection automatically within a single LLM call.

Cloudflare Agent Memory (managed service)

Cloudflare Agent Memory is a managed memory-as-a-service for agents. Key architectural differentiator: 5-channel retrieval with RRF fusion (full-text, exact key, HyDE, direct vector, raw message search). Memory types: Facts / Events / Instructions / Tasks — keyed deduplication via version chain rather than overwrite.

Primary use case: agents running in Cloudflare Workers; also available via REST API for external agents. Integrates with compaction lifecycle: ingest is called when a harness compacts context, preserving knowledge that would otherwise be discarded.

Key distinction: constrained API (not raw filesystem access) makes it superior for reasoning tasks involving temporal logic and supersession.

Comparison

Dimension	Mnemory	memory_20250818	Cloudflare Agent Memory
Retrieval	Semantic vector (Qdrant)	Flat file read	5-channel RRF (FTS+key+HyDE+vector+message)
Deduplication	Automatic (vector proximity)	Manual (agent-written)	Content-addressed ID + key-based supersession
Contradiction handling	Automatic flagging	Manual	Supersession chain (keyed facts)
Memory taxonomy	None	None	Facts/Events/Instructions/Tasks
Vendor lock-in	None (self-hosted)	Anthropic API only	Cloudflare platform
Setup cost	High (Qdrant + S3)	Low (flat files)	Low (managed)
Cross-vendor support	Yes	No	Yes (REST API)

For simple projects and single-vendor setups: memory_20250818 is lower friction. For cross-vendor workflows (Claude + Codex + Cursor on the same project) or projects needing semantic retrieval: Mnemory. For managed retrieval with memory taxonomy and compaction integration: Cloudflare Agent Memory.

Related Pages

• Context Engineering — the discipline that this tool implements (compaction, note-taking)
• Context Window — the fundamental constraint this tool works around
• Context Compression Strategies — compression strategies; server-side compaction is one lever
• Indirect Prompt Injection — security risk in memory files
• Mnemory — OSS self-hosted parallel to this tool
• Cloudflare Agent Memory — managed memory service with 5-channel retrieval