Skip to main content
Glama

mem

Local long-term memory for Claude Code, served over MCP.

mem keeps what you tell Claude (decisions, preferences, facts about people and projects) in SQLite files on your own machine, and gives it back when it matters, in as few tokens as possible. Nothing leaves the machine: the models run on your GPU and the stores are local files.

  • Hybrid retrieval. SQLite FTS5 (keywords) and a vector index (sqlite-vec, Qwen3-Embedding-0.6B embeddings) are fused, then a cross-encoder reranker (bge-reranker-v2-m3) orders the candidates.

  • A calibrated gate. The reranker's score is turned into a probability; rows below the cut are dropped, and when nothing clears it the whole answer is one line: no relevant memories (best .22). mem would rather say "I don't know" than return plausible filler.

  • History, not overwrites. A changed fact supersedes the old one; the old row stays as history and recall can answer "what did I think then?" (as_of).

  • A typed graph. Memories are about subjects (people, projects, organisations, topics, places); edges say supersedes, duplicate_of, relates_to, same_as.

  • Cleaner saving. remember asks when a name is ambiguous, shows possible conflicts with older memories, rejects secrets, and quarantines text that reads like instructions to an AI.

  • Obsidian. Import a vault so notes are searchable next to memories; render the stores back to Markdown (and git) as a one-way mirror.

  • Encrypted backups, a bearer-token-protected endpoint, and an optional Tailscale setup for a second machine.

Requirements

  • Linux with a systemd user session.

  • Python 3.12 and uv.

  • An NVIDIA GPU with CUDA and at least 4 GB of free VRAM. Serving on the CPU is not supported.

  • Nothing to sign up for: both models (Qwen3-Embedding-0.6B and bge-reranker-v2-m3) are Apache-2.0 and not gated on Hugging Face, so the download needs no account and no hf auth login.

  • A coding harness: Claude Code (claude), or Codex CLI, Gemini CLI, Cursor or VS Code (docs/harnesses.md). Plain mem setup and mem setup --uninstall need claude on PATH; without Claude Code, add --no-mcp to both (the other harnesses are still set up and undone).

Related MCP server: Agent Memory Engine

Quickstart

git clone https://github.com/wildthingz/mem-memory.git mem && cd mem   # 1. get it
uv tool install ".[models]"                        # 2. puts `mem` on your PATH
mem setup                                          # 3. shows the plan, asks once, runs it, then checks itself
claude                                             # 4. say: "Remember in my personal memory: I prefer espresso. Subject: me."

No Claude Code? Step 3 is mem setup --no-mcp, and step 4 opens your harness (codex, gemini, Cursor or VS Code).

mem setup checks the GPU, downloads the two models, writes the config, makes a token, starts the systemd user service, registers the MCP servers and the skill in Claude Code (and in Codex CLI, Gemini CLI, Cursor and VS Code when they are installed), runs mem doctor and a self-test, and prints self-test: PASS. Run it again any time: it skips what is done. mem setup --dry-run shows the plan and changes nothing; mem setup --uninstall (with --no-mcp if you set up with it) puts every edited config back byte for byte. Then, in another session, ask "What do you remember about my coffee?"

The package carries a relevance gate fitted on public data, so there is nothing to calibrate. If your checkout has no src/mem/shipped/serving_gate.json, mem doctor says so and gives the one-off gate fit (docs/install.md). Model downloads depend on your connection. Something failed? docs/troubleshooting.md maps each mem doctor failure to its fix. A second machine: docs/two-machines.md.

Plugin instead of mem setup's MCP step: run mem setup --no-mcp, set MEM_TOKEN from ~/.config/mem/token, then claude plugin marketplace add <path to this checkout> and claude plugin install mem. Details in docs/install.md.

The MCP tools

Two servers, mem-personal and mem-work (separate stores), each with the same six tools:

Tool

Purpose

recall

search memories and notes; filters about, type, kinds, since, until, as_of, include_history

get

full text by id or continuation token

remember

save one atomic memory about a subject

link

add or remove a typed edge (supersedes, duplicate_of, relates_to, same_as)

subjects

list or search people, projects and other subjects

forget

retract a memory (kept as history, never recalled)

The skill

skills/mem/SKILL.md teaches Claude when to recall (before answering about people, projects, past decisions or your preferences), what to save and what never to save, how to word a memory, and how to resolve ambiguous names and conflicts. mem setup copies it to ~/.claude/skills/mem; the plugin carries it as well.

Configuration

~/.config/mem/config.yaml, written by mem setup. Sections embedder, reranker, retrieval (candidate counts, rows returned, token budget), ingest (resolve_dates, new_checks_existing), read (list_mode, list_fill, window_boost), models (embedder: qwen3-embedding-0.6b or embeddinggemma-300m), device, and vault.routes. All but the last two are fingerprinted: change them and mem serve refuses to start until the vectors and gate match again. The defaults are the configuration the shipped gate was fitted on. See docs/use.md.

Benchmark results (summary)

End-to-end question answering at the shipped configuration: claude-sonnet-5-5 answers from what recall returns and grades with each benchmark's judge prompt. One run each, on one machine (RTX 4080 SUPER), October 2026. Per-type tables, the component measurements, the targets that were missed and how to reproduce everything: docs/benchmarks.md.

Benchmark

Score

95% CI

LongMemEval-S (500 questions)

82.6% (no memory: 7.6%; gold sessions only: 92.4%)

79.2–85.6

LoCoMo (categories 1–4, 1,540 questions)

82.4%

80.5–84.2

LongMemEval-M (500 questions, ~500 sessions each)

73.8%

70.0–77.2

Recall latency, warm p95: 452 ms on a 5,000-chunk store, 540 ms on 50,000 chunks. A typical answer is about 90 tokens. Weakest areas: preference questions (67% on S) and evidence spread over hundreds of sessions (multi-session 59% on M).

Limitations

  • GPU only. Linux and systemd only; no macOS or Windows. The models need about 4 GB of VRAM.

  • One writer. One server owns the SQLite files. A second machine connects to it (docs/multi-machine.md); syncing the files between machines is not supported.

  • Two fixed stores, personal and work. One person, not a team.

  • Changing models or retrieval settings needs a gate fit (the shipped gate belongs to the shipped config; a one-off LongMemEval download and about ten minutes of GPU, in docs/install.md).

  • Encryption at rest is your disk's job (LUKS or gocryptfs); mem doctor checks it. Backups are encrypted by mem (docs/backups.md).

  • Young. Measured on one machine by one person; see docs/benchmarks.md for the component targets it still misses.

  • History references. Code comments, tests and decision records cite the original design documents (architecture-v2 §…, benchmarks-v2 …, phases P1–P7), the task ids they came from (MEM2-…) and runbooks that are not part of this repository. They are kept as provenance; the architecture overview is the public map.

Contributing

Read AGENTS.md first (written for human contributors and coding agents alike): layout, commands, the invariants the tests guard, and how a change is made. The short version: uv sync, uv run pytest -q (CPU only, no network, no GPU), uv run ruff check and ruff format, and a decision record in docs/decisions/ for any change to behaviour or defaults.

Docs

Architecture · Install · Use · Vault import and render · Backups and encryption · Two machines · Multiple machines (server side) · Other harnesses · Troubleshooting · Benchmarks · Design decisions

Licence

MIT, see LICENSE. Models and datasets have their own terms, listed in THIRD_PARTY.md. Both default models are Apache-2.0 and are downloaded by you, from Hugging Face; no weights are in this repository. (EmbeddingGemma, the embedder before, is still selectable with models.embedder: embeddinggemma-300m; its Gemma terms then apply, and its repository is gated.)

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      A
      maintenance
      Provides persistent memory for AI coding agents via MCP, enabling agents to store and semantically recall facts, events, and lessons across sessions, all running locally without cloud dependencies.
      Apache 2.0
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to store and recall durable facts, decisions, and lessons over MCP using hybrid semantic and keyword search, typed memories, graph relations, sessions, and time-travel queries. Runs locally with no server process or API key, persisting everything to files that both agents and a CLI can share.
      20 npm
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Gives coding assistants a local-first SQLite store for project and global lessons with evidence, immutable replacements, retrieval tracking, and agent feedback, searched by keyword out of the box or by optional local semantic search. It runs over MCP stdio with launch-bound workspace scopes and write permissions disabled by default, so assistants can save, supersede, archive, retrieve, and rate memories entirely on the local machine.
      6
      MIT
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables AI coding agents to read and write persistent, local-first memory over MCP, storing decisions, preferences, error patterns, research, and cross-project guidelines in SQLite with semantic search. Agents can recall relevant context before tasks and store new learnings mid-session, keeping knowledge across sessions and projects without any external API calls.
      -