MCP工具

memem

Persistent, self-evolving memory for Claude Code. Stop re-explaining your project every session.

For LLM/AI tool discovery, see llms.txt.

  ███╗   ███╗███████╗███╗   ███╗███████╗███╗   ███╗
  ████╗ ████║██╔════╝████╗ ████║██╔════╝████╗ ████║
  ██╔████╔██║█████╗  ██╔████╔██║█████╗  ██╔████╔██║
  ██║╚██╔╝██║██╔══╝  ██║╚██╔╝██║██╔══╝  ██║╚██╔╝██║
  ██║ ╚═╝ ██║███████╗██║ ╚═╝ ██║███████╗██║ ╚═╝ ██║
  ╚═╝     ╚═╝╚══════╝╚═╝     ╚═╝╚══════╝╚═╝     ╚═╝
  persistent memory for Claude Code

What's new in v2.4.0 (passive mode + episode catalog + telemetry)

v2.4.0 flips the default injection mode from auto to tool: Claude no longer receives memory context on every prompt automatically. Instead, it pulls memory on demand via memory_search, memory_get, and active_memory_slice. This eliminates ~85% per-turn noise that was masking v2.3.0's ranking improvements. At session start, Claude now receives a ## Episode index section listing up to 50 episodic memories by title — a clean menu without a full content dump. Every retrieval is logged to ~/.memem/.recall_log.jsonl; run python3 -m memem.server --analyze-recalls to inspect recall patterns. All 5 MCP tool descriptions have been rewritten to be trigger-explicit so Claude knows when to call each tool. Existing users with MEMEM_INJECTION_MODE=auto in their shell profile are unaffected; see the CHANGELOG breaking change banner to restore old behavior.

What's new in v2.3.0 (hybrid retrieval)

active_memory_slice now uses a two-stage hybrid retrieval pipeline: BM25 + cosine Reciprocal Rank Fusion (RRF) builds a top-20 candidate pool, then Maximal Marginal Relevance (MMR, λ=0.7) selects the final 8 results to suppress near-duplicate memories. Access writeback is on by default (MEMEM_WRITEBACK_ENABLED=1); each recall fires a daemon thread that increments access_count in a JSON sidecar at ~/.memem/telemetry.json (NOT in memory frontmatter — deliberate, to keep load_vault_index's mtime cache stable). Net benchmark result: 75.3% precision (+1.3 pp vs v2.0.0 baseline), 133ms warm latency. Recency decay scoring was prototyped but reverted due to a negative-cosine ranking regression — see CHANGELOG for details.

What's new in v2.2.0 (episodic seeds)

Two architectural additions targeting the episodic-query gap vs everme. (a) retrieve.py parses temporal phrases in queries ("yesterday" / "last week" / "N days ago") and re-ranks candidates by created: proximity (+0.2 boost). Zero behavior change for non-temporal queries. (b) mine_delta.py emits one per-session "episode" memory after substantive Stop events (tagged type:episodic, Haiku-generated 100-word narrative). Benchmark is unchanged at 74% in this release — the gains are forward-looking and accrue as the vault accumulates v2.2.0-shaped episodes. Backward-compat is 100%.

What's new in v2.1.0 (event-triggered mining)

The miner daemon is gone. miner_daemon.py, miner-wrapper.sh, miner_circuit_breaker.py, miner_errors.py, and miner_protocol.py (~1,500 LOC) have been deleted. Mining now triggers on every Claude Code Stop event via a detached subprocess.

• Stop hook (hooks/stop-mine.sh) spawns mine_delta as a detached background process on every Stop event. Hook overhead is ~50ms; extraction happens in background after the hook returns.
• memem/mine_delta.py — new module (~200 LOC): reads the JSONL session file from a byte offset tracked per session, filters to new turns since the last invocation, calls the same Haiku extract_from_text function, and marks the session in ~/.memem/.mined_sessions.
• Stale-session sweep — the SessionStart hook now scans for JSONL files older than 10 min that aren't in .mined_sessions and spawns up to 3 parallel mine_delta processes. Catches sessions where Stop never fired (Claude crash, kill -9, network drop).
• Per-session flock — mine_delta acquires an fcntl.flock on a lock file per session so concurrent Stop events on the same session don't race.
• Adaptive empty-streak backoff — if the last 3 consecutive Stop events yielded zero memories, the next 5 Haiku calls are skipped. Resets on any non-empty result.
• Token cost is ~5–20× higher per session vs v2.0.0's session-end batching (many small Haiku calls instead of one big one), but mining feels real-time — memories appear seconds after each conversation turn.
• Extraction quality unchanged — the same Haiku prompt and extract_from_text function from mining.py are used. The 18-query benchmark still passes at ≥70% precision.

What's new in v2.0.0 ("less is more")

BREAKING — schema rebuild from 18 sections → 2 (Working + Relevant). Retrieval pipeline rewritten from ~12,400 LOC to ~210 LOC (POC v3b architecture). Net delete: 87 files, +915 / -19,941 LOC.

• NEW memem/retrieve.py (~145 LOC) + memem/render.py (~65 LOC) — query → embed → cosine top-K + FTS-conditional supplement for version/date literals, then a 2-section renderer. Pure embedding similarity, no scope filter, no kind classifier, no LLM judge, no daemon.
• Slice schema collapsed to 2 sections: ## Working (current state) + ## Relevant (ranked list). The v1.13 schema (Anchors / Episodic / Skills / Cases / Working / Pending) is gone.
• active_memory_slice MCP tool slimmed from 8 params to 2 (query, task_mode). Backward-incompatible.
• Deleted (~14,500 LOC): 15 memem modules (active_slice*, activation, candidate_generation, kind_classifier, slice_daemon, slice_client, slice_history, delta*, working_memory, boundaries, artifact_context, environment_context), 36 legacy test files, all v1.13 env-var flags (MEMEM_USE_LLM_JUDGE, MEMEM_USE_EMBEDDINGS, MEMEM_RENDER_LEGACY, MEMEM_LLM_JUDGE_TIMEOUT, MEMEM_AUTO_SLICE_DAEMON — all no-op now).
• Preserved: all 14 MCP tools (same names + return shapes), all 7 CLI flags, mining pipeline, vault format, embedding model + cache.
• Benchmark (18 queries × 6 categories): 74% precision (vs v1.13's 24% — 3× improvement) | 98ms warm latency (vs v1.13's 675ms — 6× faster) | 24/8 cross-scope hits (lexie/SSH/HFT queries that v1.13 returned 0 results for).
• Daemon retired: slice_daemon and MEMEM_AUTO_SLICE_DAEMON removed. Retrieval is now in-process via memem.retrieve; the hook spawns python directly per prompt. After upgrade run pkill -f slice_daemon once to clear any old process.
• Hook envelope now uses tempfile (avoids ARG_MAX on large prompts).
• Embedding writes are atomic: embeddings.npy via tmpfile + os.replace, embedding_ids.json written first so readers never see torn-write or shape mismatch.

What's new in v1.9.4 (data correctness pass)

Two release pair (v1.9.3 + v1.9.4) targeting silent-corruption paths. All changes are no-ops on the happy path.

• Atomic writes everywhere — shared atomic_write_text helper (tempfile + fsync + os.replace) applied to 5 previously non-atomic data paths (embedding ID map, tournament cache, lesson frontmatter, dreamer output, mined-sessions reset). MEMEM_FSYNC=0 opts out per-call. Power-loss / NFS-jitter / SIGKILL no longer torn-writes vault data.
• WAL on every SQLite DB — graph.db and search.db now use journal_mode=WAL + synchronous=NORMAL + busy_timeout=5000, matching session_state_db.py since v1.6. Concurrent reads from the slice engine no longer race with miner writes. New memem --integrity-check CLI command (also called from --doctor) runs PRAGMA integrity_check on all three DBs.
• Strict frontmatter validation — files without --- frontmatter are no longer silently ingested with schema_version=0. New MEMEM_FRONTMATTER_STRICT env var: quarantine (default — move to ~/.memem/quarantine/<hash>_<name>), skip (log + ignore), or raise.
• Writeback idempotency cache — commit_deltas hashes (scope_id, dry_run, auto_only, deltas, DELTA_WRITEBACK_VERSION) on entry; matching hits return cached result with deduped: True markers. Cache at ~/.memem/writeback-idempotency.json. Dry-runs and partial-failure batches are not cached. force_writeback=True bypasses the lookup. RMW guarded by fcntl.flock.
• Daemon-side subprocess-timeout accounting (v1.9.2) — fixed an infinite-loop where a huge JSONL session would re-queue forever because the daemon's SIGKILL preempted mine_session's in-process timeout cap. Now the daemon itself increments timeout_failures and permanently skips after MEMEM_MAX_SESSION_TIMEOUTS (default 3).

What's new in v1.9 (smart injection gating)

Four layered gating heuristics between the UserPromptSubmit hook and the active-slice engine, plus a new MEMEM_INJECTION_MODE env (auto / hybrid / tool). Hybrid mode reduces hook overhead on trivial turns via: (1) trivial-query regex EN+ZH, (2) per-session turn cadence (MEMEM_INJECT_CADENCE, default 2), (3) empty-streak exponential backoff (MEMEM_EMPTY_STREAK_MAX, default 8), (4) topic-shift cosine via cached query embedding (MEMEM_TOPIC_SHIFT_THRESHOLD, default 0.85). Persistent slice daemon since v1.8 eliminates cold-start cost. See CLAUDE.md for the full tunables table.

What's new in v1.1

• Layered memory becomes real end-to-end. Every memory now lives in one of four layers (L0/L1/L2/L3) at save time, not just at mining time. memory_save accepts an optional layer param (Claude can override) and auto-classifies otherwise. The slice engine pins L0 (project identity) on every prompt and gates L3 (rare archival) behind explicit search.
• Slice as universal recall format. memory_search, memory_get, memory_timeline, memory_recall, and context_assemble all return slice-formatted output via a single render_slice_markdown dispatcher. context_assemble composes via active_memory_slice rather than rolling its own briefing.

What's new in v1.0 (miner hardening)

A 16-module refactor closed the entire spawn-storm class of bugs that had previously taken down hosts. The miner now uses start_new_session=True + os.killpg for process-group cleanup on timeout, an inverted TransientError/PermanentError taxonomy with PermanentError as default, persisted attempt counters with DLQ at MAX_FAILURES, a SIGTERM-drained graceful shutdown, SQLite WAL state storage, a hand-rolled circuit breaker, structured JSON logs with RotatingFileHandler, and a 5-in-60s wrapper crash guard.