> ## Documentation Index > Fetch the complete documentation index at: https://vietbui.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # 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 ```python theme={null} 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. ```python theme={null} { "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. ```python theme={null} { "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//` 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](/concepts/indirect-prompt-injection) for the broader attack class. ## Context Editing Config Pattern (canonical) From the Anthropic cookbook, the production-ready config structure: ```python theme={null} 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](/entities/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](/concepts/context-engineering) — the discipline that this tool implements (compaction, note-taking) * [Context Window](/concepts/context-window) — the fundamental constraint this tool works around * [Context Compression Strategies](/concepts/context-compression) — compression strategies; server-side compaction is one lever * [Indirect Prompt Injection](/concepts/indirect-prompt-injection) — security risk in memory files * [Mnemory](/entities/mnemory) — OSS self-hosted parallel to this tool * Cloudflare Agent Memory — managed memory service with 5-channel retrieval