memem MCP server
Commit Sep 1, 2026Provides Claude Code with persistent memory by storing lessons and decisions as markdown in an Obsidian vault and searching them with SQLite FTS5.
Also known as TT-Wang/memem
- Stars
- 32
- Tools
- 14
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Sep 1, 2026
- License
- MIT
What is memem MCP?
memem provides Claude Code with persistent memory by storing lessons and decisions as markdown in an Obsidian vault and searching them with SQLite FTS5. It exposes 14 tools, such as memory_save, memory_search, memory_get.
Summary generated from the project's README
About memem MCP server
memem provides Claude Code with a persistent, self-evolving memory system that prevents the need to repeat project context in every new session. It functions as a local-first plugin that extracts durable lessons, such as coding conventions, bug fixes, and specific decisions, from your conversations. These insights are automatically stored as human-readable markdown files within an Obsidian vault, ensuring you maintain full ownership of your data without needing cloud services or API keys.
The system uses an event-triggered miner to capture information from conversation turns and organizes it into tiers like user profiles, project profiles, and working rules. It employs a sophisticated retrieval engine combining cosine similarity, BM25, and SQLite FTS5 to surface relevant context. Developers can use tools like active_memory_slice to pull in specific working states or rely on the automatic path-scoped retrieval that derives context from current session files to ensure the most relevant memories are always at hand.
What you can do with it
- 1Automate project context retentionA developer can have the system automatically extract and store coding conventions and project decisions from a coding session.
- 2Retrieve memories based on file pathsAn AI client can automatically pull in relevant memories that match the specific files currently being edited in a session.
- 3Search through past conversation transcriptsA user can perform full-text searches across previous question and answer pairs using a persistent database index.
Written from the project's README. Every use case is checked against a quote from it.
memem MCP tools 14
Detected from the READMEmemory_savememory_searchmemory_getmemory_timelinetranscript_searchactive_memory_slicememory_recallmemory_listmemory_graphmemory_graph_auditmemory_graph_rebuildcontext_assemble
| memory_save | — | |
| memory_search | — | |
| memory_get | — | |
| memory_timeline | — | |
| transcript_search | — | |
| active_memory_slice | — | |
| memory_recall | — | |
| memory_list | — | |
| memory_graph | — | |
| memory_graph_audit | — | |
| memory_graph_rebuild | — | |
| context_assemble | — |
Show all 14 toolsShow fewer tools
memory_importmemory_remind
| memory_import | — | |
| memory_remind | — |
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablett-wang/memem is public and reachablegithub.com/tt-wang/memem ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-09-01github.com/tt-wang/memem ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model14 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubmemem
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 is memem?
memem is a Claude Code plugin that gives Claude persistent memory across sessions. An event-triggered miner (Stop-hook → detached mine_delta subprocess) extracts durable lessons (decisions, conventions, bug fixes, preferences) from each new conversation turn, stores them as markdown in an Obsidian vault, and automatically surfaces relevant ones as an Active Memory Slice working state. An explicit narrative assembly path still exists, but the default runtime context is slice-first.
It's local-first: no cloud services, no API keys required, no vendor lock-in. Everything lives in ~/obsidian-brain/memem/memories/ as human-readable markdown.
What's new in v2.9.1 (Path-Scope Activation)
v2.9.1 activates the path-scoped retrieval that shipped dormant in v2.9.0: recall now auto-derives paths_context from the current session so the paths: bonus actually fires without any caller action. The new recent_session_paths() in memem/transcripts.py resolves session_id → JSONL via a direct CWD-slug stat first (O(1)), falling back to next(base_dir.rglob(...), None) (short-circuit on first match); it then tail-reads the last 512 KB of the file (~5 ms even on a 64 MB session, vs ~390 ms for a full read), walks assistant turns most-recent-first, and extracts the top-N deduplicated file paths from Read/Edit/Write/NotebookEdit file_path inputs and Bash command first-line path tokens via _extract_paths_from_content_blocks(). The auto-derivation is wired into active_memory_slice (MCP tool), the auto-recall.sh UserPromptSubmit hook, and the cli.py slice path; caller-supplied paths_context still wins; derivation failures are logged at debug/warning and never propagate — any exception returns [] silently. No API or schema changes; 12 new tests in tests/test_recent_paths.py cover extraction, recency/dedup/limit, missing/malformed sessions, and end-to-end active_memory_slice integration. See CHANGELOG for full details.
What's new in v2.9.0 (Tool Diet + Transcript FTS5 + Path Scope)
v2.9.0 trims the MCP surface from 14 tools to 6 — removing memory_recall, memory_graph, memory_graph_audit, memory_graph_rebuild, memory_list, memory_import, context_assemble, and memory_remind from the MCP layer (CLI and library equivalents remain for all eight) — and cuts total tool-description schema size 57% (12,827 → 5,474 chars). transcript_search is backed by a persistent FTS5 index at ~/.memem/transcript_fts.db (one row per Q/A turn-pair, index_session() called incrementally from mine_delta; old single-row-per-session indexes auto-migrate; the grep fallback is bounded by size/count/time caps and never silently truncates). Path-scoped memories arrive via a new paths: frontmatter field and a 1.05× w_path bonus in retrieve() for memories whose path globs match paths_context; memory_save gains an optional paths param; active_memory_slice accepts paths_context; and the miner annotates candidates with paths: when ≥2 paths each appear ≥3 times. Telemetry isolation is hardened via MEMEM_TELEMETRY_SOURCE. Closed-loop evaluation tooling is wired: a canary --doctor check, --dual-engine replay, and deferred-gate comments in lessons.py / feedback.py. Benchmark 79.3% (119/150), all acceptance gates pass. See CHANGELOG for full details.
What's new in v2.8.0 (Vault Structure)
v2.8.0 retires the L0–L3 layer system and replaces it with a context model that reflects how memory actually works. The starting point was honest data: 462 memories had been auto-classified L0 ("always relevant"), which was not a layer, it was a full briefing that no session could absorb. The new model has three tiers: (1) profiles — schema-shaped always-injected documents per user (profile_user.md: Preferences / Conventions / Environment) and per project (profile_<project>.md: Identity / Stack & Structure / Conventions), stored at <vault>/memem/profiles/, populated by the miner's new PROFILE reconcile op and bootstrappable from your existing vault via --migrate-layers; (2) working rules — type:procedural memories (failure→fix patterns, corrections) ranked by citation count and injected as a ## Working rules block at session start (≤1200 chars); (3) episode index — the existing 25-entry episodic title index, unchanged. Consolidation logic moves from the deleted consolidation.py into the dreamer's cluster_merge category with a bug fix: only the members listed in supporting_ids are bi-temporally invalidated after a successful merge, not all cluster members unconditionally. The dreamer gains reflection_with_citations (synthesizes type:insight memories from episodic clusters) and tense_rewrite (corrects expired future-tense memories) as additive-safe categories that fire automatically every 25 substantive mining deltas via --dream --safe-auto. The 18-query benchmark improved to 80.0% (120/150) after L0 MMR pre-seeding was removed — the anchor mechanism was penalizing relevance, not helping it (measured during release validation; up from 79.3%/119/150 in v2.7.0). See CHANGELOG for full details.
What's new in v2.7.0 (Write Path + Instrumentation)
v2.7.0 makes the miner smarter about what it writes: instead of adding every extracted candidate blindly, it compares each one against its nearest vault neighbors in a single batched Haiku call and picks ADD, UPDATE, SUPERSEDE, or NOOP with safety rails (protected-target guard, truncation guard, ≤5 destructive ops per delta, global fallback to ADD-all on any exception). The previously unreachable bi-temporal invalidation path (invalid_at / replaced_by) is now exercised by SUPERSEDE ops. Every retrieval is now linked to a session id, and the miner scans assistant text for cited memory ids and writes {"type":"citation"} rows to .recall_log.jsonl — closing the feedback loop so --analyze-recalls shows citation rate per tool and the dreamer demotion guard is live again after sitting inert since v2.5. Additional improvements: key expansion (miner emits up to 8 synonyms/aliases per memory, FTS+BM25 indexed), tool-trace digest (Bash/Edit decisions are now minable), memory_save three-band dedup (merge instead of reject for 0.70–0.92 near-duplicates), --purge-contaminated --exclude, and flock-safe feedback EMA writes. Benchmark unchanged at 79.3%. See CHANGELOG for full details.
What's new in v2.6.0 (One Engine)
v2.6.0 unifies retrieval: a single three-way RRF engine (cosine + BM25 + FTS5) now serves every call path — hook, MCP tools, and CLI. The unbenchmarked heuristic engine that served memory_search/memory_recall since v2.4.0 is deleted (−218 LOC: 5-signal re-ranker, ngram union, file-scan fallback, and a 15% feedback weight reading a file nothing ever wrote). Deprecated and invalidated memories are now excluded from the retrieval index at vault-load time, fixing a leak via the hook path. The scope_id parameter changes from a hard filter to a soft ranking bonus — cross-project results that score well now appear. The 18-query benchmark is maintained at ≥74% precision (79.3%, measured during release validation). See the A/B comparison report for transparency on result-set divergence vs the prior engine, and CHANGELOG for full details.
What's new in v2.5.0 (Repair & Prune)
v2.5.0 is a maintenance release: 24 audited defects fixed and ~2,256 LOC of dead code removed. No new memory capabilities. Key fixes: self-mining contamination guard (stale-sweep now skips headless mining transcripts), RRF/MMR scoring bugs fixed (18-query benchmark measured during release validation: 74.7% → 78.7%), embedding index staleness fixed (incremental upsert + mtime invalidation + cross-process flock), double access-count stores eliminated (telemetry sidecar is now the single store), episode deduplication (one stable-id episode per session). Removed: compaction.py, reaper.py, attribution pipeline, storage.py, 8 dead settings knobs, and hybrid injection mode (was documented but never implemented). New CLI: python3 -m memem.server --purge-contaminated [--apply]. See CHANGELOG for full details.
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 25 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) spawnsmine_deltaas a detached background process on everyStopevent. 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 Haikuextract_from_textfunction, and marks the session in~/.memem/.mined_sessions.- Stale-session sweep — the
SessionStarthook now scans for JSONL files older than 10 min that aren't in.mined_sessionsand spawns up to 3 parallelmine_deltaprocesses. Catches sessions where Stop never fired (Claude crash,kill -9, network drop). - Per-session flock —
mine_deltaacquires anfcntl.flockon 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_textfunction frommining.pyare 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_sliceMCP 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_daemonandMEMEM_AUTO_SLICE_DAEMONremoved. Retrieval is now in-process viamemem.retrieve; the hook spawns python directly per prompt. After upgrade runpkill -f slice_daemononce to clear any old process. - Hook envelope now uses tempfile (avoids ARG_MAX on large prompts).
- Embedding writes are atomic:
embeddings.npyvia tmpfile +os.replace,embedding_ids.jsonwritten 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_texthelper (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=0opts out per-call. Power-loss / NFS-jitter / SIGKILL no longer torn-writes vault data. - WAL on every SQLite DB —
graph.dbandsearch.dbnow usejournal_mode=WAL+synchronous=NORMAL+busy_timeout=5000, matchingsession_state_db.pysince v1.6. Concurrent reads from the slice engine no longer race with miner writes. Newmemem --integrity-checkCLI command (also called from--doctor) runsPRAGMA integrity_checkon all three DBs. - Strict frontmatter validation — files without
---frontmatter are no longer silently ingested withschema_version=0. NewMEMEM_FRONTMATTER_STRICTenv var:quarantine(default — move to~/.memem/quarantine/<hash>_<name>),skip(log + ignore), orraise. - Writeback idempotency cache —
commit_deltashashes(scope_id, dry_run, auto_only, deltas, DELTA_WRITEBACK_VERSION)on entry; matching hits return cached result withdeduped: Truemarkers. Cache at~/.memem/writeback-idempotency.json. Dry-runs and partial-failure batches are not cached.force_writeback=Truebypasses the lookup. RMW guarded byfcntl.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 incrementstimeout_failuresand permanently skips afterMEMEM_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_saveaccepts an optionallayerparam (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, andcontext_assembleall return slice-formatted output via a singlerender_slice_markdowndispatcher.context_assemblecomposes viaactive_memory_slicerather 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.
When should I use memem?
Use memem if:
- You use Claude Code daily and keep re-explaining your project to every new session
- You want durable memory you can browse and edit as markdown
- You like local-first tools with zero vendor lock-in
- You already use Obsidian (memem plugs straight into your vault)
How is memem different from CLAUDE.md?
CLAUDE.md is a single hand-edited file per project. memem gives you:
- Automatic extraction — no manual note-taking, the miner captures lessons from every completed session
- Query-aware context — only the memories relevant to your current question get injected, not a static dump
- Self-evolving — memories merge, update, and deprecate automatically as your project evolves
- Cross-project — works across every Claude Code project you use, not scoped to one repo
- Security scanning — every write is scanned for prompt injection and credential exfiltration
- Browsable — Obsidian vault with graph view and backlinks for free
memem MCP questions
What tools does memem MCP provide?
It exposes 14 tools, including memory_save, memory_search, memory_get, memory_timeline, transcript_search.
Where are the memories stored?
Everything is stored as human-readable markdown in your Obsidian vault.
How does the memory retrieval work?
It uses a three-way RRF engine combining cosine similarity, BM25, and FTS5 for retrieval.