feat(mem0-agent): read path, hooks, maintenance, CLI and skills
- pack.py: single-call context pack, budgeted, sanitized, cached, with served-id tracking that turns a citation into POSITIVE feedback - assist.py: error-signature lookup (never raw stdout, which returned 0 results in v1) - maintain.py: transactional consolidation (add merged -> verify -> delete sources) - transcript.py: JSONL parsing into non-overlapping windows via a cursor - cli.py: the twelve commands the hooks invoke; detached assist queues a block that the next prompt hook drains, keeping the hot path network-free - hooks generated from one spec; plugin manifest, MCP wiring, five skills Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Deshraj Yadav
co-authored by
Claude Fable 5
Claude Fable 5
parent
e102b21180
commit
3ea00cf88c
@@ -0,0 +1,140 @@
|
||||
# mem0-agent
|
||||
|
||||
Coding memory for Claude Code and friends, built on the [Mem0](https://mem0.ai) platform.
|
||||
|
||||
It remembers the things that change how an assistant should behave next time — your
|
||||
preferences, the decisions you made and why, the team conventions that live nowhere in
|
||||
the repo, the gotchas you root-caused, the procedures you verified. It deliberately does
|
||||
not remember what you did today.
|
||||
|
||||
Zero runtime dependencies (stdlib only; `keyring` is optional). Every hook fails open —
|
||||
if the API is down, your session is unaffected.
|
||||
|
||||
## Install
|
||||
|
||||
```bash
|
||||
pip install 'mem0-agent[keyring]' # keyring extra stores the API key in the OS keychain
|
||||
mem0-agent onboard # asks for a key, picks a memory mode, pushes project config
|
||||
```
|
||||
|
||||
Onboarding never reads your shell rc files and never writes a key into a `.env`. The key
|
||||
comes from `MEM0_API_KEY` or the OS keychain; a key you type at the prompt goes to the
|
||||
keychain and nowhere else. Get one at <https://app.mem0.ai/dashboard/api-keys>.
|
||||
|
||||
To wire the hooks into Claude Code, point your plugin/settings config at the generated
|
||||
manifest:
|
||||
|
||||
```
|
||||
hooks/generated/claude-code.hooks.json
|
||||
```
|
||||
|
||||
Non-interactive install (CI, dotfiles, provisioning):
|
||||
|
||||
```python
|
||||
from mem0_agent.onboard import run_onboard
|
||||
run_onboard(interactive=False, memory_mode="dual", capture="conservative")
|
||||
```
|
||||
|
||||
## The two memory modes
|
||||
|
||||
Chosen once per project at onboard, stored per project in `~/.mem0/v2/settings.json`.
|
||||
The default is DUAL when the repo already has memory files (`CLAUDE.md`, `AGENTS.md`,
|
||||
`.cursorrules`, `MEMORY.md`, `.claude/memory/`), FULL when it has none.
|
||||
|
||||
| | DUAL | FULL |
|
||||
|---|---|---|
|
||||
| Repo memory files | authoritative for repo-local notes | not used |
|
||||
| mem0 holds | durable, cross-machine, cross-repo knowledge | everything |
|
||||
| MEMORY.md write-blocker | off | on |
|
||||
| Native auto-memory | leave it on | turn it off |
|
||||
|
||||
DUAL is the honest default for a repo that already documents itself: two memory layers
|
||||
that each know their job. FULL is for people who want one place to look, and it installs
|
||||
a write gate so the assistant stops appending to `MEMORY.md` behind your back.
|
||||
|
||||
Change it later:
|
||||
|
||||
```bash
|
||||
mem0-agent config set memory_mode dual|full
|
||||
```
|
||||
|
||||
## The two aggressiveness dials
|
||||
|
||||
```bash
|
||||
mem0-agent config set capture conservative|balanced|aggressive
|
||||
mem0-agent config set retrieval conservative|balanced|aggressive
|
||||
```
|
||||
|
||||
- **capture** — how eagerly a moment becomes a candidate memory. `conservative` stores
|
||||
only explicit "remember this" style signals; `aggressive` also stores inferred
|
||||
decisions and conventions.
|
||||
- **retrieval** — how much context is injected at session start (roughly 600 / 1500 /
|
||||
2500 characters) and how confident an error match must be before it is surfaced.
|
||||
`conservative` disables error assist entirely.
|
||||
|
||||
## How the write gate works
|
||||
|
||||
Nothing is stored just because it happened. A candidate has to survive three gates:
|
||||
|
||||
1. **Trigger** — a local, network-free detector on `UserPromptSubmit` decides whether the
|
||||
moment is even a candidate. This runs on the hot path of every turn, so it is
|
||||
local-only by contract and enforced with `MEM0_LOCAL_ONLY=1` in the generated hook.
|
||||
2. **Turn boundary** — candidates are buffered and judged at `Stop`, `PreCompact` and
|
||||
`SessionEnd`, when it is finally clear how the turn ended. One turn costs at most one
|
||||
write, and all three writes are backgrounded so they are never on your critical path.
|
||||
3. **Platform policy** — the project's custom instructions are the real gate. They name
|
||||
the six types (`preference`, `decision`, `convention`, `insight`, `runbook`,
|
||||
`session_state`) and explicitly exclude progress updates, status heartbeats, file and
|
||||
commit lists, repo file contents, session-only facts, one-off instructions and
|
||||
secrets. `mem0-agent onboard` pushes them and verifies the round-trip; the policy
|
||||
version is stamped into every memory's metadata so a quality regression can be traced
|
||||
back to the revision that caused it.
|
||||
|
||||
Reads are pinned to the project and always `latest_only`, so a superseded memory never
|
||||
comes back beside the one that replaced it.
|
||||
|
||||
## Hooks are generated, not hand-written
|
||||
|
||||
`hooks/hooks.spec.yaml` is the single source of truth. It declares each hook's event,
|
||||
matcher, command, timeout, background/blocking flags, local-only contract, and one line
|
||||
of *why*.
|
||||
|
||||
```bash
|
||||
python3 hooks/generate.py # write hooks/generated/claude-code.hooks.json
|
||||
python3 hooks/generate.py --check # exit 1 if the committed manifest drifted (run in CI)
|
||||
```
|
||||
|
||||
| Event | Matcher | Command | Behavior |
|
||||
|---|---|---|---|
|
||||
| SessionStart | `startup\|resume\|compact` | `context` | blocking, injects project knowledge + open threads |
|
||||
| UserPromptSubmit | — | `observe --source prompt` | blocking, **local-only, no network** |
|
||||
| PostToolUse | `Bash` | `assist-error` | detached; a hit lands in the session buffer |
|
||||
| Stop | — | `flush` | detached |
|
||||
| PreCompact | — | `flush --reason precompact` | detached |
|
||||
| SessionEnd | — | `flush --reason end` | detached |
|
||||
|
||||
Cursor, Codex and Antigravity are declared in the spec as unsupported rather than
|
||||
deleted, so the gap stays visible instead of turning back into a hand-maintained file.
|
||||
|
||||
## Why v2
|
||||
|
||||
v1 wrote roughly **98 memories a day**, and almost all of it was heartbeat spam: "started
|
||||
task X", "80% complete", "modified 3 files", "opened PR #123" — activity you can already
|
||||
get from git, restated in a memory store where it drowned out the things you actually
|
||||
wanted back. Retrieval got worse the longer you used it.
|
||||
|
||||
v2 targets **under 15 memories a day**, all durable knowledge. The changes that get it
|
||||
there:
|
||||
|
||||
- The write gate above, validated against the real polluted v1 corpus.
|
||||
- Writes at turn boundaries in batches, instead of one write per tool call.
|
||||
- No network call on the per-prompt hot path.
|
||||
- Session state per session ID under `~/.mem0/v2/`, not `/tmp` keyed by `$USER`, so
|
||||
concurrent sessions stop corrupting each other's counters.
|
||||
- Project and org pinned in the request body, so coding memories can no longer leak into
|
||||
whatever project the API key happens to default to.
|
||||
- One hook spec, generated manifests, drift caught by CI.
|
||||
|
||||
## License
|
||||
|
||||
Apache-2.0
|
||||
Reference in New Issue
Block a user