claude-mem v13.30.0：hooks 不再阻塞 worker，observer 成本下降

Official release notes (https://github.com/thedotmack/claude-mem/releases/tag/v13.30.0) ## Hooks stop waiting on the worker, and the observer costs less Claude Code no longer waits on the claude-mem worker in the middle of a session: hooks save each event to disk and return at once, and SessionStart reads context the worker prepared ahead of time. The observer that writes your memories also costs less. A user prompt no longer gets a model call of its own, the observer's prompts now start with the same fixed instructions so provider prompt caches can reuse them, OpenRouter requests carry session and trace labels that keep a session on the provider holding its cache, observer thinking on the Claude path is really off, and a slow reply is waited for instead of being paid for twice. The release also fixes search, file context, hooks, the CLI, very large transcripts, and sign-in on Linux and Windows. ### Features - **Hooks save and return.** The observation, file-edit, Stop and SessionEnd hooks write each event to a file under `~/.claude-mem/state/hook-spool/` and exit, without waiting on the worker or starting it. The worker picks the files up within moments, and an event delivered twice replaces its file instead of being stored twice. Files still unprocessed after 7 days move to `hook-spool/expired/` and are logged. This replaces the SessionEnd replay queue. (#4368) - **SessionStart context is ready before you start.** The worker prepares SessionStart context in `~/.claude-mem/state/context-cache/`, refreshing it about 2 seconds after anything that could change it, so a new session reads a file instead of waiting on the worker or on a cloud pull of up to 1.5 seconds. A missing or stale (over 24 hours old) file, or a context showing an observer or sync health notice, falls back to the live path. With cloud sync on, the file is used only while live updates are connected and caught up, so a memory deleted on another device is never served from it. (#4368, #4370) - **Observer prompts that providers can cache.** A provider's prompt cache (OpenRouter's, or the cmem.ai gateway's) can only reuse the part of a prompt that starts exactly as before. The observer's first and follow-up prompts now both open with the same block of fixed instructions, which depends only on the mode, followed by the session's context, the user's request and the follow-up text. In the code mode, two sessions' prompts now share their first ~7,260 characters, up from 422 (and from none between a first and a follow-up prompt). Only the order changed, plus one word ("below" became "above") in 33 modes, and the Claude SDK and Codex paths open the same way. (#4415) - **Session and trace labels on OpenRouter requests.** Observer requests that reach OpenRouter, directly or through the cmem.ai gateway, now include a `session_id` (a one-way SHA-256 hash of the Claude Code session id) and a `trace` with a random `trace_id` per observer conversation, `trace_name` `claude-mem observer`, a `generation_name` naming the request (`init`, `observation`, `summary`, `field_compression` or `telegram_wrapup`) and `claude_mem_version`. OpenRouter uses the session id to keep a session on the provider that holds its prompt cache, and OpenRouter Broadcast maps the labels to PostHog's `$ai_session_id`, `$ai_trace_id` and `$ai_span_name`. No path, project name or text you wrote is included, and custom base URLs and `openai-compatible` endpoints get neither field. (#4418) - **One fewer observer call per prompt.** A user prompt used to get an observer request of its own, which nearly always came back as "nothing to record": a full prompt for a nine-token reply. The prompt now goes out with the next observation or summary, in that event's single request, for the HTTP providers and the Claude SDK alike. Set `CLAUDE_MEM_OBSERVE_BARE_PROMPTS=true` (default `false`) to bring back the separate request. (#4336) - **Slow replies are waited for, not paid for twice.** OpenRouter and OpenAI-compatible observer requests now stream behind the scenes, so a slow but working reply is kept alive by its progress (a 90-second idle limit and a 300-second cap) instead of being cut off at a fixed deadline and billed again. `CLAUDE_MEM_LLM_TIMEOUT_MS` now applies only to requests that do not stream: Gemini, Codex, the cmem.ai gateway, and an endpoint that rejects streaming, which is detected once and remembered. A paid request is resent only when the provider provably did no work (a 429 or a refusal before sending); each batch gets at most two paid sends, and a batch that uses them up is parked and logged, never silently dropped. (#4368) - **Worker startup is reported, not guessed.** The worker streams its startup phases (`starting`, `db_ready`, `routes_ready`, then `ready` or `failed`) at `GET /api/ready`. Hooks read that once instead of polling and assuming a worker is stuck once it has been up 300 seconds, and restarts are limited so a failure that repeats on every start cannot cause a restart loop. `CLAUDE_MEM_WEDGED_WORKER_UPTIME_S` now applies only to the launcher's port reclaim. (#4368) - **Long knowledge-base calls stay alive.** When the MCP client asks for it, corpus `prime` and `query` answer as a stream with a heartbeat every 10 seconds, so a long prime can run for up to 15 minutes instead of hitting a 30-second deadline, and the work stops if the client disconnects. (#4368) - **Cloud sync live updates over Supabase Realtime.** For cmem.ai Pro cloud sync, the worker gets live updates from a private Supabase Realtime channel instead of the sync hub's WebSocket and pulls whenever another device announces changes. A server without Realtime leaves the client polling, and `CLAUDE_MEM_CLOUD_SYNC_WS=false` still turns live updates off. (#4368) ### Fixes - **Observer thinking is really off on the Claude path.** #3245 meant to turn it off but used an option name the Agent SDK ignores, so roughly 70% of the observer's output tokens on Claude Sonnet 4.5 went to thinking. The observer now passes the SDK's actual `thinking` option. (#4335) - **Very large transcripts.** The Stop hook reads a transcript backwards from the end in bounded chunks instead of loading the whole file. A transcript over 2 GB no longer fails with `ENOMEM` and loses the session summary, and a large one no longer costs hundreds of milliseconds and gigabytes of memory on every Stop: a 2.16 GB transcript now takes about 1 ms and 27 MB. (#4338) - **Sign-in on Linux and Windows.** claude-mem now reads `~/.claude/.credentials.json` (or the one under `CLAUDE_CONFIG_DIR`), where Claude Code keeps its login, before libsecret or Windows Credential Manager. A leftover Credential Manager entry from another account no longer hides the current login, libsecret is not queried on every observer start, and a libsecret miss no longer logs a misleading warning. A working `CLAUDE_CODE_OAUTH_TOKEN` now wins over an expired stored login. macOS still checks the keychain first. (#4369) - **"Invalid API key" false alarms.** Only the Claude CLI's own invalid-key status line counts as a bad key, so an observer reply that quotes the phrase is no longer treated as an authentication failure. (#4337) - **Worker start on Linux after an unclean shutdown.** An older PID file without a start token is trusted only if that process really is the worker, so a PID reused by another program no longer blocks the worker from starting. (#4349) - **Search.** Underscores and percent signs in file names now match literally instead of acting as wildcards (#4354). Folder search and folder `CLAUDE.md` generation filter to a folder's direct children before paging, so files deeper down no longer crowd out the folder's own files, and the next page no longer repeats ones already shown (#4361). `/api/search/observations` now respects `projects` for Chroma results too, instead of returning observations from every project (#4367). - **File context.** Observations from a worktree that was merged into its parent project now appear in file context (#4351). XML character references in observer output are decoded, so a file written as `src/A&B.ts` is stored and found as `src/A&B.ts`, and titles, facts and summaries no longer keep escape codes (#4360). A shell read that uses `--`, such as `cat -- -notes.md`, is now recognized (#4357). - **Hook input.** Hooks decode their input as UTF-8 across reads, so a character split between two reads (Japanese text, emoji) is no longer stored as replacement characters. (#4356) - **CLI.** `claude-mem search` uses the configured worker address, including a host or port saved in `settings.json` and IPv6 hosts such as `::1` (#4362). Folder `CLAUDE.md` generation handles tracked folders with non-ASCII names and file names that contain newlines (#4355). - **Transcript watcher.** A `transcript-watch.json` config or state file saved with a UTF-8 byte-order mark, as some Windows editors and PowerShell do, now loads in the watcher and in the Codex and Grok Bot installers, instead of failing or silently resetting read positions and replaying transcripts. (#4352) - **Memory edits through the API.** `PATCH /v1/memories/:id` keeps the fields you leave out and clears a field you set to `null`, instead of resetting omitted fields to their defaults. An edit that would leave a memory with no searchable text is rejected with a 400. (#4353) ### Internal changes - **Cloud sync server.** The sync server no longer scans a user's whole change history on every pull, pulls and status checks no longer take a per-user lock, `/health` no longer touches the database, and database sessions get statement, lock and idle-transaction timeouts, passed in a form Neon honors. Together these stop the lock pile-ups that took the only sync machine out of service. A new `FORWARD_ORIGIN` mode forwards sync traffic to the Supabase `cmem-sync` function for the move to Supabase. (#4347, #4368) - **Request ids and error bodies.** HTTP observer requests carry a per-batch `x-client-request-id` in place of the unused `x-claude-mem-prior-request-id`, and error bodies are read up to 64 KiB. (#4368) - **Tests and docs.** A two-device cloud sync end-to-end matrix against Supabase, coverage for the v21 schema repair alongside the v41 origin index, and fixes for leaks and races in the full test suite (#4350, #4368). The cloud sync, configuration and OpenAI-compatible provider docs are updated. **Full Changelog**: https://github.com/thedotmack/claude-mem/compare/v13.29.0...v13.30.0 Repository README (current repository documentation, not release changes)         🇨🇳 中文 • 🇹🇼 繁體中文 • 🇯🇵 日本語 • 🇵🇹 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**: memory that runs off-plan, free for up to 14 days, 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 ``` 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 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