claude-mem v13.35.0 发布：渐进式记忆检索与原生记忆笔记

Official release notes (https://github.com/thedotmack/claude-mem/releases/tag/v13.35.0) ## New: progressive memory search, curated tool replies, and native memory notes Claude-Mem 13.35.0 gives agents one memory search tool, `mem_search`, that discloses memory in bounded steps: a compact index, the context around chosen anchors, and then one batch of selected details. The local worker MCP and the hosted cmem.ai MCP run the same search engine and return the same model-facing text. Tool replies are now short, readable text written for the question being answered, so agents no longer receive raw JSON dumps. This release also adds `save_memory` for explicit notes, a hook bridge that supplements Claude Code and Codex native memory lookups, and an opt-in watcher that imports Markdown note folders. ### `mem_search`: guided and automatic progressive disclosure - **Guided mode** (the default) labels each reply `mem-search step 1 of 3` (index), `step 2 of 3` (context around up to `maxDetails` chosen IDs), and `step 3 of 3` (one detail batch). Each reply ends with a readable next-call instruction and a short **Continue with:** cursor. Agents can stop early when the titles or context already answer the question. - **Automatic mode** (`mode: "auto"`) runs the same three bounded stages in one call using ranked lexical retrieval. It picks anchors by how many query terms appear in each index title, ignoring stop words and prompts. If no title matches, it retries once with the stop-word-stripped query. It makes no LLM calls. - **Opaque continuations.** A cursor is 27 characters (`ms_` plus 24 URL-safe characters). The search scope, the original options and the set of IDs already disclosed stay in bounded server-side state, which expires after 15 minutes. Agents no longer carry serialized search rows between calls. A cursor cannot be reused with changed options, and `selectedIds` must come from the previous reply. Expired or foreign cursors return a plain-language error that asks for a new query. - **Bounds.** `limit` is capped at 20 index rows, `maxDetails` defaults to 3 with a maximum of 5, and `depthBefore`/`depthAfter` default to 2 with a maximum of 3. Queries are limited to 500 characters and 1 KiB of UTF-8. - **One contract, local and hosted.** Local and hosted MCP share the same portable engine source and the same model-visible output in both modes. Under `CLAUDE_MEM_RUNTIME=server`, the local `mem_search` points callers to the hosted MCP connection and does not query the local worker. - `search`, `timeline` and `get_observations` remain available for older clients and advanced filters. Their descriptions now point agents to `mem_search`, and only `mem_search` enforces the progression. ### Curated, purpose-specific tool replies - MCP replies for search, context, selected records, raw tool uses, corpus build/list/prime/query, server observations, events and job lookups now return concise readable text: indexes, selected evidence, write receipts and summaries. Internal HTTP data stays available to code. Model-facing replies no longer include pretty-printed JSON envelopes or duplicated `structuredContent`. - Authored JSON and code examples inside a memory's own prose are preserved when it is selected. Summary evidence keeps its edited-file references, and untitled server notes get useful labels plus a supported context follow-up. - Worker and server errors are short plain-language messages and do not echo raw transport payloads. - Retrieval no longer re-observes its own output. Calls to claude-mem's own search and context tools, plus native `memory_*` lookups, are excluded from observation capture, so searching memory does not create new memories about searching. An explicit `save_memory` write keeps its receipt without also generating a second observation of the same note. ### `save_memory` and durable-note instructions - New `save_memory({ text, title?, project?, metadata? })` MCP tool for worker runtime. It records explicit preferences, corrections, decisions, handoffs and reusable lessons into the active checkout's project unless another project is named, and returns a short write receipt. - Under server runtime, `save_memory` refuses before it calls the local worker and points to `observation_add` for the selected server project. Server-mode notes cannot touch the local worker. - SessionStart context now includes short memory-use instructions. They tell agents to search with `mem_search` before saving to avoid duplicate or conflicting notes, to keep notes concise and separate verified facts from guesses, to leave out credentials and private material, and to use `work_state_write` for to-do lists when that tool is available. Hosted read-only connections may expose search without write tools, so the instructions say to call only tools that are actually present. Set `CLAUDE_MEM_MEMORY_INSTRUCTIONS_ENABLED=false` to turn them off. - The bundled `mem-search` skill has been rewritten around `mem_search` guided and automatic modes. ### Native memory lookup bridge (Claude Code and Codex) - The `PreToolUse` hook now recognizes native memory lookups: `memory_search`, read commands of a local `memory` tool, and Read/Grep/Glob/Bash (`cat`, `head`, `tail`, `sed`, `grep`, `rg`) reads scoped to Claude Code's per-project `memory` folders, a configured `autoMemoryDirectory`, Codex's `memories` folder, or configured note roots. When one runs, the hook adds an automatic `mem_search` result for the same topic as extra context. The native tool still runs normally and its result follows. - Added context is capped at 10,000 characters. It is framed as retrieved data that must not supply instructions, and only curated text is ever injected; JSON-looking replies from an older worker are dropped. claude-mem's own tools are excluded to prevent recursive searches. If the worker is unavailable, the hook steps aside and the native lookup proceeds unchanged. - A read inside an explicitly mapped note folder searches that folder's configured project, even when another checkout reads it. Other reads use the checkout's project scope. - Hosted connectors' internal memory retrieval and background native-memory generation have no verified plugin interception API, so they are not intercepted. The instructions tell agents to call `mem_search` directly when they need its result. - The bridge runs only under worker runtime. When claude-mem settings select `server`, or the legacy `server-beta` value, it steps aside even if the server configuration is incomplete. It never queries or starts a local worker for those sessions, and the native tool continues normally. - Disable the bridge with `CLAUDE_MEM_MEMORY_SEARCH_HOOK_ENABLED=false`. Existing native-memory enable/disable choices are not changed. ### Opt-in Markdown note watcher - Set `CLAUDE_MEM_MEMORY_WATCH_ROOTS` to a JSON string of up to 8 `{ "path", "project", "platformSource"? }` entries, each with an absolute (or `~/`) path and an explicit project. The worker imports Markdown notes from those folders into the mapped project. The default is empty, so nothing is imported, and the watcher never scans all native projects or global Codex memories on its own. - The watcher polls, waits for stable contents, and imports nothing until a file has stopped changing. It skips hidden files, symlinks and files over 64 KiB. Each read is bound to the exact file that was checked inside the configured root, so a file outside that root cannot be imported through a link, a move or a swapped parent folder. It never rewrites source files and makes no model calls. - Edits are stored as distinct revisions. Exact content fingerprints deduplicate replays across worker restarts and simultaneous processes. Deleting a source note does not delete its archived revisions. Imported notes follow your existing cloud-sync settings. - While a watcher is configured, the worker's idle-exit timer stays off so external note changes are still captured. - Restart the local worker after changing the setting. See [docs/native-memory-bridge.md](https://github.com/thedotmack/claude-mem/blob/main/docs/native-memory-bridge.md) for configuration details. ### Safety and integration fixes - **Runtime routing.** `mem_search`, `save_memory` and the native memory bridge honor `CLAUDE_MEM_RUNTIME`, including the legacy `server-beta` value and a runtime selected in claude-mem settings. Worker runtime uses the local worker. Server runtime points searches to the hosted MCP connection and note writes to `observation_add`, and the bridge skips supplementation even when the server configuration is incomplete. None of them fall back to the local worker. - **Installation discovery.** The source-checkout activation script (`scripts/activate-progressive-memory-local.mjs`, not shipped in the npm package) discovers the supported Claude Code and Codex installations actually present, including marketplace and matching local cache copies. It respects `CLAUDE_CONFIG_DIR` and `CODEX_HOME`, and a Claude-only or Codex-only machine is enough. It defaults to a read-only plan, records the original bytes and hashes before `--apply`, and `--restore` validates every affected file before rolling any of them back. - **Configured data directory.** Activation uses the worker's own data-directory resolver. It checks an explicit `--memory-data-dir` first, then `CLAUDE_MEM_DATA_DIR` in the environment, then the flat or nested `CLAUDE_MEM_DATA_DIR` setting in the default `~/.claude-mem/settings.json`, and it expands home-relative paths. It updates and backs up the resolved directory's settings and leaves the default redirect file unchanged. Settings files that start with a UTF-8 BOM are accepted. A nested `env` object receives the setting only when it already holds `CLAUDE_MEM_*` settings. - **Watcher file containment.** Watch roots must be absolute and mapped to an explicit project, and symlinked roots and files are skipped. Each file is opened with `O_NOFOLLOW` after its real path is checked inside the canonical root. The opened descriptor must match the checked file's device, inode, size, modification time and change time. The path's location is verified again before and after reading. The read is limited to the checked size, and the import is discarded if anything changed. This closes a race in which a swapped parent folder could open a file outside the root and then be restored. Change detection now also tracks device and change time. - **Chroma vector search starts again on fresh environments** ([#4595](https://github.com/thedotmack/claude-mem/pull/4595), reported in #4593). chroma-mcp 0.2.6 pins `mcp[cli]==1.6.0`, which imports a private pydantic helper that pydantic 2.14.0 removed. Freshly resolved chroma-mcp environments failed on import during prewarm and vector search stayed off. The launcher now caps `pydantic         🇨🇳 中文 • 🇹🇼 繁體中文 • 🇯🇵 日本語 • 🇵🇹 Português • 🇧🇷 Português • 🇰🇷 한국어 • 🇪🇸 Español • 🇩🇪 Deutsch • 🇫🇷 Français • 🇮🇱 עברית • 🇸🇦 العربية • 🇷🇺 Русский • 🇵🇱 Polski • 🇨🇿 Čeština • 🇳🇱 Nederlands • 🇹🇷 Türkçe • 🇺🇦 Українська • 🇻🇳 Tiếng Việt • 🇵🇭 Tagalog • 🇮🇩 Indonesia • 🇹🇭 ไทย • 🇮🇳 हिन्दी • 🇧🇩 বাংলা • 🇵🇰 اردو • 🇷🇴 Română • 🇸🇪 Svenska • 🇮🇹 Italiano • 🇬🇷 Ελληνικά • 🇭🇺 Magyar • 🇫🇮 Suomi • 🇩🇰 Dansk • 🇳🇴 Norsk Persistent memory compression system built for Claude Code. Quick Start • How It Works • Search Tools • Documentation • Configuration • Troubleshooting • License Claude-Mem seamlessly preserves context across sessions by automatically capturing tool usage observations, generating semantic summaries, and making them available to future sessions. This enables Claude to maintain continuity of knowledge about projects even after sessions end or reconnect. --- ## Quick Start Install claude-mem for Grok Bot: ```bash npx claude-mem install --ide grok-bot ``` Grok Bot has no host hooks, so we watch the chat log files. Default is CMEM Pro, the hosted memory. Local observer is opt-in: `--provider host`. Installing this plugin does not install Cursor. **Awareness push pilot (LFG + Orifice):** needle observations (`decision`, `bugfix`, `security_alert`, `sensitive`) are appended as dated `- YYYY-MM-DD [awareness] …` lines into that bot's `memory/log/YYYY-MM.md`. Grok Bot already re-reads the log from disk. This does not write `profile.md`, user-memory, or project memory. Disable with `CLAUDE_MEM_GROK_BOT_AWARENESS_ENABLED=false`. Install with a single command: ```bash npx claude-mem install ``` The installer sets everything up first, then asks you to sign in to claude-mem in your browser (email magic link — no card required). Signing in provisions a memory key for your account and unlocks the **claude-mem observer** with a **30 Day Free Trial**: memory runs off-plan, so you get up to 100% more usage from your plan. When the free trial ends, memory automatically falls back to your Anthropic plan unless you subscribe. After sign-in you pick your memory provider — the claude-mem observer, your own OpenRouter or Gemini key, or your Anthropic plan. Prefer to skip the sign-in? Pass an explicit `--provider` flag, set `CLAUDE_MEM_ONLINE_OPTIN=false`, or run in CI/non-interactive shells — the installer completes without any account interaction. Or install for OpenCode: ```bash npx claude-mem install --ide opencode ``` This works with OpenCode 1.3.4 or later, including OpenCode 2. Restart OpenCode after installing. Or install for **T3 Code** (Codex and Claude Code providers): ```bash npx claude-mem install --ide t3code ``` The installer discovers T3 Code's enabled providers, registers native Claude-Mem plugins in their configured homes, and supports T3-managed Codex. Restart T3 Code, trust the provider's hooks when prompted, and start a new thread. See the [T3 Code integration guide](https://docs.claude-mem.ai/t3code-integration) for custom server settings, status, and removal. Or install for Antigravity CLI ([setup guide](https://docs.claude-mem.ai/antigravity-cli/setup)): ```bash npx claude-mem install --ide antigravity ``` Or install for OMP (Oh My Pi): ```bash npx claude-mem install --ide omp ``` Or install the native Pi extension or DeepSeek Harness plugin: ```bash npx claude-mem install --ide pi npx claude-mem install --ide dsh --dsh-profile tui ``` Pi and DeepSeek Harness use the worker runtime. See [native harness setup](docs/native-harness-integrations.md) for capture, recall, and troubleshooting. Or install from the plugin marketplace inside Claude Code: ```bash /plugin marketplace add thedotmack/claude-mem /plugin install claude-mem ``` Restart Claude Code. Context from previous sessions will automatically appear in new sessions. > **Note:** Claude-Mem is also published on npm, but `npm install -g claude-mem` installs the **SDK/library only** — it does not register the plugin hooks or set up the worker service. Always install via `npx claude-mem install` or the `/plugin` commands above. ### 🦞 OpenClaw Gateway Install claude-mem as a persistent memory plugin on [OpenClaw](https://openclaw.ai) gateways with a single command: ```bash curl -fsSL https://install.cmem.ai/openclaw.sh | bash ``` The installer handles dependencies, plugin setup, AI provider configuration, worker startup, and optional real-time observation feeds to Telegram, Discord, Slack, and more. See the [OpenClaw Integration Guide](https://docs.claude-mem.ai/openclaw-integration) for details. **Key Features:** - 🧠 **Persistent Memory** - Context survives across sessions - 📊 **Progressive Disclosure** - Layered memory retrieval with token cost visibility - 🔍 **Skill-Based Search** - Query your project history with mem-search skill - 🖥️ **Web Viewer UI** - Real-time memory stream at the worker URL printed on startup - 💻 **Claude Desktop Skill** - Search memory from Claude Desktop conversations - 🔒 **Privacy Control** - Use `` tags to exclude sensitive content from storage - ⚙️ **Context Configuration** - Fine-grained control over what context gets injected - 🤖 **Automatic Operation** - No manual intervention required - 🔗 **Citations** - Reference past observations with IDs through the worker API or view all in the web viewer --- ## Documentation 📚 **[View Full Documentation](https://docs.claude-mem.ai/)** - Browse on official website ### Getting Started - **[Installation Guide](https://docs.claude-mem.ai/installation)** - Quick start & advanced installation - **[Usage Guide](https://docs.claude-mem.ai/usage/getting-started)** - How Claude-Mem works automatically - **[Search Tools](https://docs.claude-mem.ai/usage/search-tools)** - Query your project history with natural language - **[Cloud Sync](https://docs.claude-mem.ai/cloud-sync)** - Back up your memories to cmem.ai — no daemon, the worker syncs on write ### Best Practices - **[Context Engineering](https://docs.claude-mem.ai/context-engineering)** - AI agent context optimization principles - **[Progressive Disclosure](https://docs.claude-mem.ai/progressive-disclosure)** - Philosophy behind Claude-Mem's context priming strategy ### Architecture - **[Overview](https://docs.claude-mem.ai/architecture/overview)** - System components & data flow - **[Architecture Evolution](https://docs.claude-mem.ai/architecture-evolution)** - The journey from v3 to v5 - **[Hooks Architecture](https://docs.claude-mem.ai/hooks-architecture)** - How Claude-Mem uses lifecycle hooks - **[Hooks Reference](https://docs.claude-mem.ai/architecture/hooks)** - 7 hook scripts explained - **[Worker Service](https://docs.claude-mem.ai/architecture/worker-service)** - HTTP API & Bun management - **[Database](https://docs.claude-mem.ai/architecture/database)** - SQLite schema & FTS5 search - **[Search Architecture](https://docs.claude-mem.ai/architecture/search-architecture)** - Hybrid search with Chroma vector database ### Configuration & Development - **[Configuration](https://docs.claude-mem.ai/configuration)** - Environment variables & settings - **[Development](https://docs.claude-mem.ai/development)** - Building, testing, contributing - **[Release Branches](https://docs.claude-mem.ai/branches)** - Stable, core-dev, and community-edge branch flow - **[Troubleshooting](https://docs.claude-mem.ai/troubleshooting)** - Common issues & solutions --- ## How It Works **Core Components:** 1. **5 Lifecycle Hooks** - SessionStart, UserPromptSubmit, PostToolUse, Stop, SessionEnd (6 hook scripts) 2. **Smart Install** - Cached dependency checker (pre-hook script, not a lifecycle hook) 3. **Worker Service** - Local HTTP API with web viewer UI and search endpoints, managed by Bun 4. **SQLite Database** - Stores sessions, observations, summaries 5. **mem-search Skill** - Natural language queries with progressive disclosure 6. **Chroma Vector Database** - Hybrid semantic + keyword search for intelligent context retrieval See [Architecture Overview](https://docs.claude-mem.ai/architecture/overview) for details. --- ## MCP Search Tools Claude-Mem provides intelligent memory search through **4 MCP tools** following a token-efficient **3-layer workflow pattern**: **The 3-Layer Workflow:** 1. **`search`** - Get compact index with IDs (~50-100 tokens/result) 2. **`timeline`** - Get chronological context around interesting results 3. **`get_observations`** - Fetch full details ONLY for filtered IDs (~500-1,000 tokens/result) **How It Works:** - Claude uses MCP tools to search your memory - Start with `search` to get an index of results - Use `timeline` to see what was happening around specific observations - Use `get_observations` to fetch full details for relevant IDs - **~10x token savings** by filtering before fetching details **Available MCP Tools:** 1. **`search`** - Search memory index with full-text queries, filters by type/date/project 2. **`timeline`** - Get chronological context around a specific observation or query 3. **`get_observations`** - Fetch full observation details by IDs (always batch multiple IDs) **Example Usage:** ```typescript // Step 1: Search for index search(query="authentication bug", type="bugfix", limit=10) // Step 2: Review index, identify relevant IDs (e.g., #123, #456) // Step 3: Fetch full details get_observations(ids=[123, 456]) ``` See [Search Tools Guide](https://docs.claude-mem.ai/usage/search-tools) for detailed examples. --- ## Release Branches Stable releases ship from `main` and are published to npm. `core-dev` and `community-edge` are source-run branches for early reliability fixes and community integrations. See **[Release Branches](https://docs.claude-mem.ai/branches)** for the branch flow and non-stable run instructions. --- ## System Requirements - **Node.js**: 20.0.0 or higher - **Claude Code**: Latest version with plugin support - **Bun**: JavaScript runtime and process manager (auto-installed if missing) - **uv**: Python package manager for vector search (auto-installed if missing) - **SQLite 3**: For persistent storage (bundled) --- ### Windows Setup Notes If you see an error like: ```powershell npm : The term 'npm' is not recognized as the name of a cmdlet ``` Make sure Node.js and npm are installed and added to your PATH. Download the latest Node.js installer from https://nodejs.org and restart your terminal after installation. --- ## Configuration Settings are managed in `~/.claude-mem/settings.json` (auto-created with defaults on first run). Configure AI model, worker port, data directory, log level, and context injection settings. To include observations from every harness in Claude Code and Codex SessionStart context, set `"CLAUDE_MEM_SESSION_START_INCLUDE_ALL_SOURCES": "true"` in that file, or enable **Include all sources at session start** in the viewer settings. The default is `"false"`, which limits startup context to the current harness. The observation count limit still applies across the selected sources. See the **[Configuration Guide](https://docs.claude-mem.ai/configuration)** for all available settings and examples. ### Mode & Language Configuration Claude-Mem supports multiple workflow modes and languages via the `CLAUDE_MEM_MODE` setting. This option controls both: - The workflow behavior (e.g. code, chill, investigation) - The language used in generated observations #### How to Configure Edit your settings file at `~/.claude-mem/settings.json`: ```json { "CLAUDE_MEM_MODE": "code--zh" } ``` Modes are defined in `plugin/modes/`. To see all available modes locally: ```bash ls ~/.claude/plugins/marketplaces/thedotmack/plugin/modes/ ``` #### Available Modes | Mode | Description | |------------|-------------------------| | `code` | Default English mode | | `code--zh` | Simplified Chinese mode | | `code--ja` | Japanese mode | Language-specific modes follow the pattern `code--[lang]` where `[lang]` is the ISO 639-1 language code (e.g., `zh` for Chinese, `ja` for Japanese, `es` for Spanish). > Note: `code--zh` (Simplified Chinese) is already built-in — no additional installation or plugin update is required. #### After Changing Mode Restart Claude Code to apply the new mode configuration. --- ## Development See the **[Development Guide](https://docs.claude-mem.ai/development)** for build instructions, testing, and contribution workflow. --- ## Troubleshooting If experiencing issues, describe the problem to Claude and the troubleshoot skill will automatically diagnose and provide fixes. See the **[Troubleshooting Guide](https://docs.claude-mem.ai/troubleshooting)** for common issues and solutions. --- ## Bug Reports Create comprehensive bug reports with the automated generator: ```bash cd ~/.claude/plugins/marketplaces/thedotmack npm run bug-report ``` ## Contributing Contributions are welcome! Please: 1. Fork the repository 2. Create a feature branch 3. Make your changes with tests 4. Update documentation 5. Submit a Pull Request Claude-Mem ships from three branches: `main` (stable), `core-dev`, and `community-edge`. Only `main` is published to npm; the others are run from source. See [Release Branches](https://docs.claude-mem.ai/branches) for the strategy and local run instructions. See [Development Guide](https://docs.claude-mem.ai/development) for contribution workflow. --- ## License Claude-Mem is licensed under the Apache License 2.0. We chose Apache-2.0 because durable agentic memory should be easy to embed in developer tools, local agents, MCP servers, enterprise systems, robotics stacks, and production agent harnesses. See the [LICENSE](LICENSE) file for full details. See [docs/license.md](docs/license.md) and [docs/ip-boundary.md](docs/ip-boundary.md) for licensing scope and the open/commercial boundary. **Note on Ragtime**: The `ragtime/` directory is licensed under the **Apache License 2.0**. See [ragtime/LICENSE](ragtime/LICENSE) for details. --- ## Support - **Documentation**: [docs/](docs/) - **Issues**: [GitHub Issues](https://github.com/thedotmack/claude-mem/issues) - **Repository**: [github.com/thedotmack/claude-mem](https://github.com/thedotmack/claude-mem) - **Official X Account**: [@Claude_Memory](https://x.com/Claude_Memory) - **Official Discord**: [Join Discord](https://discord.com/invite/J4wttp9vDu) - **Author**: Alex Newman ([@thedotmack](https://github.com/thedotmack)) --- **Built with Claude Agent SDK** | **Works with Claude Code** | **Made with TypeScript** --- ### What About CMEM? CMEM is a token created by a 3rd party but officially embraced by the creator of Claude-Mem (Alex Newman, @thedotmack). The token acts as a community catalyst for growth and a vehicle for bringing CMEM to the developers and knowledge workers that need it most. Official BASE CA: 0x76b1967eec0ccaeb001bbbb2b40dc4badba31ba3