Saket Aryan
df70d7833f
Six defects in 0.3.x plugin telemetry. Defects 1, 2 and 6 were not three bugs: they were one spool protocol getting three properties wrong. Identity was decided by the wrong process. `harness` was stamped in record(), correctly, but `source` was read from a module global in flush() — so whichever process drained the spool named every event in it. Two processes never call init(): mcp_server.py, and the detached `python3 telemetry.py` sender that spawn_flush() starts. record() now stamps source beside harness, and the build generates core/_harness_id.py per host so identity resolves with no init() call at all. That also unifies two defaults that disagreed (`<host>_plugin` vs `MEM0_<HOST>_PLUGIN`), which could yield three source values for one plugin. Ownership was inferred, not held. Path.replace is os.rename, which preserves mtime, so a claim made after a quiet minute inherited the spool's age and was stealable the instant it existed. Claims are touched on creation and the per-batch rewrite doubles as a lease heartbeat. Progress was not durable. flush() returned on the first failed batch without truncating, so the retry re-posted from index 0 — 150 events delivered 250 times. It now rewrites the claim with the unsent remainder after every batch, bounding a crash to one repeated batch, and each event carries a uuid. Parked batches starved. They were only reachable when no spool existed, and because sessions keep recording there usually was one, so a batch parked by a failed send waited until the 7-day expiry deleted it unsent — despite its own presence being what starts the sender. flush() drains them in the same run, and expiry now applies only after a genuine retry has failed. code.install counted upgrades and repeat sessions. is_first_run() read the identity file, which only a successful flush writes, so an offline user recorded an install every session forever. A dedicated install-state.json is claimed atomically at record time; a non-empty data directory reads as an upgrade. The docs called this anonymous. Every event carries the account email, and the hashes were unsalted SHA-256 over a git remote URL or an absolute path containing the username. READMEs, the module docstring and a new docs section now say what the code does, and repo/session digests are salted per install. A cached email outlived an API key change. It is now re-resolved when the key's fingerprint differs, and $identify aliases anonymous->email only — aliasing one account to another merges person profiles irreversibly. All six shipped green because the shared core's only tests lived under one host, behind a conftest that calls init() at import. Core behaviour was never exercised uninitialised. Adds agent-plugin-core/tests with no init, including subprocess tests and coverage for the portable plugin, which has no flush worker and would pass a native-only test vacuously. Also puts the three surface headers on the SDKs, CLIs and integrations, and corrects a README claiming ZAPIER/STRANDS were already in the platform allowlist. Verified: 59 core tests, 203 claude-code, 11 cursor, 5 codex, 2 kimi, 6 antigravity. ruff and compileall clean. --check clean for all six hosts. TypeScript changes are not typechecked locally (deps not installed). Claude-Session: https://claude.ai/code/session_01C7tEmH86HAr7GoAAKCEHZb
208 lines
11 KiB
Markdown
208 lines
11 KiB
Markdown
# Mem0 for Claude Code
|
|
|
|
Persistent cross-session memory for Claude Code, plus a Sonnet sidekick agent for delegated work.
|
|
|
|
Claude Code forgets everything between sessions. This plugin fixes that: hooks capture session details locally, a background worker turns them into Mem0 memories, and Claude automatically gets the relevant ones back at the start of later sessions.
|
|
|
|
Current bundle version: `0.3.1`.
|
|
|
|
## Prerequisites
|
|
|
|
- Python 3.10+ and Git.
|
|
- A Claude Code version that supports plugin agents, worktree isolation for agents, and the `SubagentStart`, `SubagentStop`, and `PostToolUseFailure` hook events.
|
|
- A [Mem0 Platform API key](https://app.mem0.ai/dashboard/api-keys) (starts with `m0-`).
|
|
|
|
## Install
|
|
|
|
```bash
|
|
export MEM0_API_KEY='your-mem0-api-key'
|
|
claude plugin marketplace add mem0ai/mem0
|
|
claude plugin install mem0@mem0-plugins --scope user --config api_key="$MEM0_API_KEY"
|
|
unset MEM0_API_KEY
|
|
```
|
|
|
|
Restart Claude Code (or run `/reload-plugins`), then open a Git repository and work normally.
|
|
|
|
To update:
|
|
|
|
```bash
|
|
claude plugin marketplace update mem0-plugins
|
|
claude plugin update mem0@mem0-plugins --scope user
|
|
```
|
|
|
|
To remove:
|
|
|
|
```bash
|
|
claude plugin uninstall mem0@mem0-plugins
|
|
```
|
|
|
|
For local development, verify and load the self-contained plugin directory:
|
|
|
|
```bash
|
|
python3 integrations/agent-plugin-core/build/build.py claude-code --kind native --check
|
|
claude --plugin-dir integrations/claude-code-plugin
|
|
```
|
|
|
|
## How it works
|
|
|
|
### Memory
|
|
|
|
1. **Capture.** Hooks save the main agent's activity locally: user messages, Claude's answers, changed file paths, and short test/build results. Capture does not call a model. Sidekick assignments and completed responses are recorded separately as supporting evidence.
|
|
|
|
2. **Flush.** After every five completed exchanges, a detached background worker sends that batch to Mem0. Large exchanges flush sooner. Ending or compacting the session flushes anything remaining. The session-end worker sends the conversation already collected by hooks without recording the final answer again. If idle, an auto-flush runs after five minutes (configurable with `MEM0_CODE_IDLE_FLUSH_SECONDS`). The worker survives Claude Code exiting.
|
|
|
|
3. **Extract.** Each flush sends one or more `add` calls with `agent_id` (the project identity), `user_id` (you), `app_id` (the repository), and `run_id` (the session). Mem0 classifies each extracted memory as either:
|
|
- **Shared project memory** (`agent_id`): one namespace per repo, scoped by `app_id`. Stores conventions, decisions, constraints, working commands, and failed commands with their fixes. Everyone on the repo reads and writes the same pool. Never carries a `user_id`. Directory information is stored in metadata for directory-scoped searches.
|
|
- **Personal memory** (`user_id`): your preferred tools, style, habits, and anything you asked to be remembered. Scoped to the repo by `app_id`. Private to you.
|
|
|
|
4. **Recall.** On the next session's first prompt, if it has at least 20 characters, the plugin searches automatically and supplies up to five relevant memories. No model is called to write the query.
|
|
|
|
Captured prompts and responses retain their full text after secret redaction. Oversized extraction input is split across requests without discarding message text. Search results and tool evidence still have separate size limits.
|
|
|
|
After that first search, Claude can call `search_memories` with a specific question, and you can run `/mem0:search` yourself. Explicit searches return up to 3 results by default (configurable to 20), capped at 4,000 characters.
|
|
|
|
### Sonnet sidekick agent
|
|
|
|
Sidekick is available only in this plugin. The shared core handles memory and subagent tracking.
|
|
|
|
`mem0:sidekick` is a Sonnet coding agent that runs in a separate Git worktree. It can investigate, implement, test, debug, or review something instead of the main (Opus/Fable) session doing the same work, reducing cost when the main agent doesn't need to repeat it.
|
|
|
|
The main agent reviews the result. Corrections go back to the same sidekick so it keeps what it learned. Changes stay in the sidekick's worktree until the main agent reviews and copies them over.
|
|
|
|
Mem0 never blocks normal Claude Code work when a hook fails. It does not proxy Claude traffic, rewrite tool output, edit `CLAUDE.md`, force Claude to use the sidekick, or change how Claude implements the user's request.
|
|
|
|
## Use
|
|
|
|
Work in Claude Code normally. Memory is captured and recalled automatically.
|
|
|
|
```text
|
|
/mem0:search Why does the ODS serializer keep dates timezone-naive?
|
|
/mem0:search What parser failures were fixed? --top-k 5 --category problems_and_fixes
|
|
/mem0:search Do I prefer pnpm or npm? --scope mine
|
|
```
|
|
|
|
To use the sidekick:
|
|
|
|
```text
|
|
Ask Mem0's sidekick to investigate and implement this in its separate worktree.
|
|
Review its result and send any corrections back to the same sidekick.
|
|
```
|
|
|
|
By default the worktree branches from the repo's default branch. Set `worktree.baseRef` to `"head"` in your Claude settings to branch from the current commit instead. Uncommitted changes are not copied into the sidekick's worktree.
|
|
|
|
## Commands
|
|
|
|
| Command | What it does |
|
|
| --- | --- |
|
|
| `/mem0:search` | Search memories from earlier sessions. Accepts `--top-k <n>`, `--category <name>`, `--scope <repo\|dir\|mine>`, and `--run-id <session-id>`. |
|
|
| `/mem0:status` | Check config, capture state, pending flushes, and API key validity. |
|
|
| `/mem0:forget` | Delete your memories for this repo (shared project memory stays unless you pass `--include-project-memory`). |
|
|
| `/mem0:pause` | Pause memory capture. |
|
|
| `/mem0:resume` | Resume capture after a pause. |
|
|
| `/mem0:remember` | Tell Claude to capture something specific in its reply. |
|
|
|
|
Categories for `--category`: `project_knowledge`, `decisions_and_constraints`, `workflows`, `problems_and_fixes`, `results`.
|
|
|
|
## Search scope
|
|
|
|
| Scope | What you get |
|
|
| --- | --- |
|
|
| `repo` (default) | All project memory across every subdirectory, plus your preferences |
|
|
| `dir` | Project memory from the current directory (and children), plus your preferences |
|
|
| `mine` | Your personal preferences only |
|
|
|
|
Set the default with the `search_scope` setting or `MEM0_CODE_SEARCH_SCOPE`. Pass optional `run_id` to `search_memories` (or `--run-id` to `/mem0:search`) with any scope to search memories saved in that session. Omit it to search across sessions. This filters the returned memories; it does not identify the session making the request. Use a known session ID.
|
|
|
|
New Git repository memories use a hash of the remote identity in `agent_id`. Searches also include the previous unhashed ID under the same repository `app_id`, so shared memories remain available after upgrading. Older IDs retain their original limitation: matching owner/repository names on different Git hosts share that legacy namespace. Local folders keep their path-based namespaces.
|
|
|
|
Explicit shared-memory deletion with `--include-project-memory` covers both repository IDs. Default deletion preserves shared memories.
|
|
|
|
## Settings
|
|
|
|
| Setting | Default | What it controls |
|
|
| --- | --- | --- |
|
|
| `api_key` | required | Mem0 Platform API key |
|
|
| `user_id` | local account name | User ID for memory storage. Resolved from: setting, `MEM0_CODE_USER_ID`, `MEM0_USER_ID`, `MEM0_RESOLVED_USER_ID`, `$USER`, `%USERNAME%`, then `default`. Set explicitly to share across machines. |
|
|
| `top_k` | `3` | Max memories per explicit search (1 to 20) |
|
|
| `max_context_chars` | `4000` | Max characters returned per search (1,000 to 10,000) |
|
|
| `search_scope` | `repo` | Default scope: `repo`, `dir`, or `mine` |
|
|
|
|
## What is stored and sent
|
|
|
|
Local data lives in `${CLAUDE_PLUGIN_DATA}`:
|
|
|
|
- `api-key`: the configured Mem0 key (readable only by the local user)
|
|
- `evidence.sqlite3`: session details and records of memory creation/search
|
|
- `pending/`: sessions waiting to be sent to Mem0 (retried after interruption)
|
|
- `flush-worker.log`: whether memory creation succeeded
|
|
- `plugin-errors.log`: hook errors (no credentials)
|
|
- `telemetry.jsonl` / `telemetry-identity.json`: usage events and the id they are sent under
|
|
|
|
Mem0 receives captured user messages, Claude's answers, sidekick assignments and completed responses, and changed file paths. When a failed command is recorded, extraction can also include bounded command details and results. Complete files and general tool output stay on your machine. Values that look like credentials are redacted before anything is sent.
|
|
|
|
## Telemetry
|
|
|
|
Usage events (which hook ran, timing, result counts, failure types) so Mem0 can identify what's used and what's breaking.
|
|
|
|
**These events are not anonymous.** When an API key is configured — which installing the plugin requires — events are sent under your Mem0 account email, the same way the Python SDK and the CLI attribute theirs. Without a key they are sent under a random per-machine id.
|
|
|
|
What each event carries: the event name, the plugin version, the harness it ran in, your OS and Python version, timings, counts, and a coarse failure label. Repository and session identifiers are hashed with a random salt generated on your machine and never sent, so they cannot be linked back to a repository name or path.
|
|
|
|
Prompts, memory text, queries, file paths, repository names, and API keys are never sent.
|
|
|
|
Turn it off:
|
|
|
|
```bash
|
|
export MEM0_TELEMETRY=false
|
|
```
|
|
|
|
## Five-minute memory test
|
|
|
|
Run this in a Git repository after installing:
|
|
|
|
1. Tell Claude:
|
|
```text
|
|
Remember for future work that this repository's acceptance marker is cobalt-orchid-731.
|
|
```
|
|
|
|
2. End the session. Start a new one in the same repo and run:
|
|
```text
|
|
/mem0:search What is the acceptance marker?
|
|
```
|
|
|
|
3. Check that the result contains `cobalt-orchid-731`.
|
|
|
|
Memory creation runs in the background. If the first search is empty, wait a moment and try again.
|
|
|
|
## Upgrading from 0.2.x
|
|
|
|
Breaking update. Memories carry over, most local config does not.
|
|
|
|
- **Memories carry over.** Same user and repo scoping, including `~/.mem0/project_map.json`.
|
|
- **Old memories searchable, not by category.** Category filters only work on new memories.
|
|
- **Commands replaced.** Old commands replaced by `/mem0:search`, `/mem0:status`, `/mem0:forget`, `/mem0:pause`, `/mem0:resume`, `/mem0:remember`.
|
|
- **MCP server replaced.** Nine read/write tools replaced by the single read-only `search_memories` tool.
|
|
- **`~/.mem0/settings.json` ignored.** All keys stop applying: `auto_save`, `auto_search`, `search_limit`, `confidence_threshold`, `retention_session_days`, `global_search`, `debug`.
|
|
- **Per-project `mem0.md` files ignored.**
|
|
- **Most `MEM0_*` env vars ignored.** Only `MEM0_API_KEY`, `MEM0_USER_ID`, `MEM0_RESOLVED_USER_ID`, and `MEM0_PROJECT_ID` are still read. Run `/mem0:status` to see what is active.
|
|
|
|
## Troubleshooting
|
|
|
|
| Problem | Fix |
|
|
| --- | --- |
|
|
| Missing key | Reinstall with `--config api_key="$MEM0_API_KEY"` while the var is set. |
|
|
| `401 Unauthorized` | API key is invalid or expired. Run `/mem0:status`. |
|
|
| No memory after ending a session | Extraction runs in the background. Wait a moment, then search again. |
|
|
| Sidekick won't start | Must be in a Git repo with a Claude Code version supporting plugin agents and worktrees. |
|
|
| Remove the plugin | `claude plugin uninstall mem0@mem0-plugins` |
|
|
|
|
## Development checks
|
|
|
|
Run from the repository root:
|
|
|
|
```bash
|
|
python3 -m pytest integrations/claude-code-plugin/tests -q --ignore=integrations/claude-code-plugin/tests/integration
|
|
python3 -m ruff check integrations/agent-plugin-core/python integrations/claude-code-plugin
|
|
claude plugin validate --strict integrations/claude-code-plugin
|
|
```
|