{
  "markdown": "<p align=\"center\">\n  <img src=\"assets/logo.png\" alt=\"memkeeper logo\" width=\"180\" height=\"180\" />\n</p>\n\n<p align=\"center\"><em>Most software has the memory of a goldfish. This one doesn&rsquo;t.</em></p>\n\n<p align=\"center\">\n  <a href=\"https://github.com/teflon07/memkeeper/actions/workflows/ci.yml\"><img src=\"https://github.com/teflon07/memkeeper/actions/workflows/ci.yml/badge.svg\" alt=\"CI status\" /></a>\n  <a href=\"https://github.com/teflon07/memkeeper/releases\"><img src=\"https://img.shields.io/github/v/release/teflon07/memkeeper?sort=semver\" alt=\"Latest release\" /></a>\n  <a href=\"#license\"><img src=\"https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-blue\" alt=\"License: MIT OR Apache-2.0\" /></a>\n  <a href=\"https://glama.ai/mcp/servers/teflon07/memkeeper\"><img src=\"https://glama.ai/mcp/servers/teflon07/memkeeper/badges/score.svg\" alt=\"memkeeper MCP server quality score on Glama\" /></a>\n</p>\n\n# memkeeper\n\nLocal-first memory for AI agents. A fast, embeddable memory engine that stores,\nranks, and retrieves an agent's durable context, entirely on your machine, with\nno required network or LLM calls.\n\n> Memkeeper is the open-source, local-first control plane that AI agents run on: durable memory, project context, coordinated task handoffs, and deny-by-default permissions, all deterministic and on your own machine. *This repo is the memory engine at its core.*\n\n> ℹ️ **Generated release mirror.** This repo is generated from a private\n> development repo and published as releases. The `main` branch may be\n> regenerated, so **pin to tagged releases** (or the release artifacts) rather\n> than to arbitrary `main` commits — tagged releases are stable. See\n> [CONTRIBUTING.md](CONTRIBUTING.md) for how to contribute; issues, security\n> reports, and design feedback are the best paths today.\n\n- **Local-first.** A single SQLite database. No server, no cloud, no telemetry.\n- **Fast at prompt time.** Deterministic BM25/FTS retrieval with optional ONNX\n  semantic embeddings and a cross-encoder reranker.\n- **Durable by design.** Atomic writes, schema-versioned storage, and a\n  retention model that promotes recurring, high-signal memories to a durable tier.\n\n<p align=\"center\">\n  <img src=\"assets/hero.gif\" alt=\"memkeeper demo: store two memories, then a semantic search whose query shares no keywords with the stored memory still surfaces the right one\" width=\"820\" />\n</p>\n\n<p align=\"center\"><sub>Real CLI output, formatted for readability via <a href=\"scripts/mkfmt\"><code>scripts/mkfmt</code></a>. The search query shares no keywords with the memory it surfaces.</sub></p>\n\n> Status: pre-release (v0.5.3). APIs and the wire protocol may change before 1.0.\n\n## Quickstart\n\n```sh\n# Install the latest release binary (macOS arm64 / Linux x86_64) to ~/.local/bin.\n# It's self-contained — nothing else to install.\ncurl -fsSL https://raw.githubusercontent.com/teflon07/memkeeper/main/install.sh | bash\n\n# Optional, one-time: fetch on-device semantic models. Lexical search works without it.\nmemkeeper pull-models\n\n# Create a store, remember something, search it back.\nmemkeeper init\nmemkeeper remember --json '{\"content\":\"memkeeper stores memories in a local SQLite database\"}'\nmemkeeper search   --json '{\"query\":\"where are memories stored\",\"limit\":3}'\n```\n\nThat's the whole install: a self-contained binary, no runtime network/LLM/API key.\nPrefer not to pipe a script to your shell? Grab a binary from the\n[releases page](https://github.com/teflon07/memkeeper/releases) and verify its\n`.sha256`, or [build from source](#build-from-source). The store defaults to\n`~/.memkeeper/store.sqlite` when `--store` is omitted; a `--json` value can also be\n`@<file>` or `-` (stdin) instead of an inline string, which avoids shell-quoting\npitfalls (handy in Windows PowerShell).\n\n## Upgrade from v0.2.x\n\nv0.3.0 introduced the schema 5 to schema 6 upgrade; v0.4.0 through v0.5.3 keep\nschema 6 unchanged. The migration is transactional, but schema 6 stores cannot\nbe opened by v0.2.x. Stop any long-running `memkeeper` process and keep a\nschema 5 backup until you verify the upgrade.\n\nBack up the store with your v0.2.x binary before installing the current release:\n\n```sh\nSTORE=~/.memkeeper/store.sqlite\nmemkeeper backup --store \"$STORE\" --output \"$STORE.schema5.bak\" --json\n```\n\nInstall the current release, run the migration explicitly, and verify the result\nbefore restarting any long-running process:\n\n```sh\ncurl -fsSL https://raw.githubusercontent.com/teflon07/memkeeper/main/install.sh | bash\nmemkeeper init --store \"$STORE\" --json\nmemkeeper doctor --store \"$STORE\" --json\n```\n\n`init` is safe to rerun. If you need to roll back, restore the schema 5 backup\nbefore starting the older binary.\n\n## Use it from your agent (MCP)\n\nmemkeeper speaks MCP (JSON-RPC 2.0 over stdio), so any MCP client —\nClaude Code, Cursor, and others — can read and write memory during a session. Point\nyour client's MCP config at the **native binary** (no Python, no extra deps):\n\n```json\n{ \"mcpServers\": { \"memkeeper\": { \"command\": \"memkeeper\", \"args\": [\"mcp\"] } } }\n```\n\nThe agent calls `remember` to capture a durable fact and `search` to recall it later,\nacross separate sessions, with the same retrieval as the CLI.\n\n<p align=\"center\">\n  <img src=\"assets/mcp.gif\" alt=\"memkeeper over MCP: an agent connects, calls remember to store a fact, then in a later session calls search and recalls it via semantic retrieval\" width=\"820\" />\n</p>\n\n<p align=\"center\"><sub>Real <code>memkeeper mcp</code> JSON-RPC round-trips, formatted for readability via <a href=\"scripts/mcpfmt\"><code>scripts/mcpfmt</code></a>.</sub></p>\n\n## What to store\n\nmemkeeper holds **self-contained memories**: facts, decisions, preferences,\nlessons. Each `remember` is one memory written to stand on its own, with its\ncontext and intent intact (store \"the user likes pineapple on pizza,\" not just\n\"pineapple\"). Atomic means one idea per memory, not a stripped keyword.\nRetrieval, dedup, supersession, and the entity graph all work best at that grain.\n\nTwo ends to avoid:\n\n- **Too small:** a bare keyword or fragment that drops the point.\n- **Too large:** a whole document. The curated memory tier has no chunking, and\n  the embedder sees only the first ~512 tokens of an entry, so loading long files\n  (for example, an entire markdown library) gives weak semantic recall on those\n  entries (lexical BM25 still indexes the full text). To bring whole documents in,\n  don't store them as memories — use the [document store](#document-store-rag),\n  memkeeper's separate RAG tier that chunks and embeds files into an isolated\n  space (the [`memkeeper-ingest`](https://github.com/teflon07/memkeeper-ingest)\n  add-on imports whole folders this way). Or distill the document down to its\n  takeaways and store those as memories.\n\n## Capturing memories\n\nmemkeeper is **curated** memory you populate deliberately — not an automatic\ntranscript logger. Memories get in two ways:\n\n- **Directly** — `memkeeper remember --json '{\"content\":\"…\"}'`, from the CLI or a\n  script.\n- **From an agent** — the native [MCP server](#use-it-from-your-agent-mcp) lets an MCP\n  client (Claude and other agents) call `remember` during a session, so durable facts\n  are captured as they come up. When a confirmed memory names entities or states a\n  relationship, the MCP tool asks the agent to include a bounded graph projection\n  in the same call. memkeeper validates and commits the memory, exact aliases, and\n  typed relationships atomically. The one memory ID is the relationship evidence.\n\nmemkeeper does not run a second LLM or background extractor for this. The MCP host\nagent supplies the structured graph fields while making the normal `remember`\ncall. Raw CLI callers can supply the same `graph` object explicitly.\n\nOn the *retrieval* side, `memkeeper hook retrieve` is a Claude Code\nUserPromptSubmit hook client that injects relevant memories into the prompt — so an\nagent recalls without an explicit search. It retrieves; capture stays a deliberate\n`remember`.\n\n## Semantic retrieval (default)\n\nmemkeeper has three retrieval modes. **Local semantic is the default and the\nrecommended, fully on-device mode.** Pick one up front — the embedding backend is\nrecorded in the store, so changing it means re-embedding (`reindex --embed`), not a\nflip.\n\n<p align=\"center\">\n  <img src=\"assets/retrieval.gif\" alt=\"memkeeper retrieval: the deterministic BM25/FTS floor returns an exact-keyword match with zero models, then with the ONNX models loaded a semantic query that shares no keywords still finds the right memory\" width=\"820\" />\n</p>\n\n<p align=\"center\"><sub>The deterministic floor (zero models, zero network) and semantic + rerank on top — same store, same query path. Real output via <a href=\"scripts/mkfmt\"><code>scripts/mkfmt</code></a>.</sub></p>\n\n| Mode | Network | Setup |\n|---|---|---|\n| **Local semantic** (default) | none | install binary, then `pull-models` |\n| **Lexical only** | none | works out of the box; just skip `pull-models` |\n| **Off-device semantic** | embeds via an API | set `MEMKEEPER_EMBED_PROVIDER=openai` + base URL + key |\n\n> **Privacy:** off-device semantic sends your memory **text** to the embeddings\n> provider to be vectorized. Use it only where that is acceptable; the two on-device\n> modes never send memory content anywhere.\n\n### Local semantic (default)\n\nThe release binary ships semantic-capable (the ONNX runtime is statically\nbundled), so there's no rebuild — it just needs the embed + rerank models, which\naren't downloaded automatically. Fetch them once:\n\n```sh\n# Needs curl; ~2.1GB, or --quantized for ~0.6GB (slightly lower recall).\nmemkeeper pull-models\n```\n\n`pull-models` writes to `~/.memkeeper/models/` (override with `MEMKEEPER_MODELS_DIR`\nor `--dir`) — exactly where memkeeper looks by default. So semantic turns on with\n**no env vars to set**: run a `search` afterward and it's active.\n\nIf the models are missing, memkeeper does not degrade *silently*: it logs their\nabsence and points you at `pull-models`, marks results semantic-unavailable\n(e.g. `\"semantic\":{\"attempted\":false,\"reason\":\"missing_embedding\"}`), and **falls\nback to lexical (BM25/FTS)** so search keeps working. Set\n`MEMKEEPER_REQUIRE_SEMANTIC=1` to **fail closed** instead — refuse the request\nrather than serve degraded results — in any deployment that must never silently\nrun lexical-only.\n\nEmbeddings are computed when a memory is **written**. Memories you stored before\nthe models were present (for example, the one from the Quickstart above) are\nlexical-only until embedded. Backfill existing memories once with:\n\n```sh\nmemkeeper reindex --embed\n```\n\nNew memories written with the models in place are embedded automatically.\n\n### Lexical only\n\nSkip `pull-models` and the release binary runs deterministic, model-free\n**lexical-only** (BM25/FTS) retrieval — zero network, zero models. Building from\nsource with `--no-default-features` produces a leaner binary that omits the ONNX\nruntime entirely (see [Build from source](#build-from-source)).\n\n### Off-device semantic (no model download)\n\nPrefer not to download the ONNX models? Point memkeeper at an OpenAI-compatible\nembeddings API (OpenAI, OpenRouter, or any compatible proxy) instead. This mode\nembeds and reranks over the network rather than loading the local models, so it\nneeds no `pull-models`:\n\n```sh\n# Embeddings (required for semantic): any OpenAI-compatible /embeddings endpoint.\nexport MEMKEEPER_EMBED_PROVIDER=openai     # \"openai\" = the OpenAI-compatible API dialect\nexport MEMKEEPER_EMBED_BASE_URL=https://api.openai.com/v1/embeddings   # or your provider, e.g. OpenRouter\nexport MEMKEEPER_EMBED_API_KEY=sk-...\nexport MEMKEEPER_EMBED_MODEL=text-embedding-3-small\nexport MEMKEEPER_EMBED_DIMS=1536\n\n# Reranking (optional, recommended): Cohere /rerank dialect, which OpenRouter speaks.\nexport MEMKEEPER_RERANK_PROVIDER=openrouter\nexport MEMKEEPER_RERANK_API_KEY=sk-...\nexport MEMKEEPER_RERANK_MODEL=cohere/rerank-v3.5\n```\n\nThe **prebuilt release binaries support all three modes** (`--features semantic,api`):\nrun `pull-models` for fully on-device local semantic (the default and recommended\nmode), configure an API key for off-device semantic, or configure neither and they\nserve lexical (BM25/FTS). `MEMKEEPER_REQUIRE_SEMANTIC=1` makes them refuse rather\nthan serve degraded.\n\nPrebuilt binaries are published for **macOS (Apple Silicon)** and **Linux x86_64**.\n**Windows is experimental** — there's no prebuilt binary, but it builds and runs\nfrom source; see [docs/windows.md](docs/windows.md). (`serve --socket` is Unix-only\nthere; the http dashboard and stdio serve are cross-platform.)\n\n### How `pack` combines semantic and graph retrieval\n\n`pack` uses one retrieval path. Semantic and lexical matches supply memory\nseeds, exact entity and alias matches supply graph seeds, and bounded\nevidence-backed graph traversal joins both sets on canonical memory IDs. Every\ncandidate then competes in the same cross-encoder rerank pool. Graph candidates\nreceive no reserved slots or automatic demotion, and there is no production\ngraph on/off mode. A store with no eligible graph route simply returns the\nsemantic and lexical pool unchanged.\n\n### Switching the embedding model\n\nThe embedding backend is recorded per store, and memkeeper refuses to mix vectors\nfrom different models (they live in different vector spaces). To switch — local↔\noff-device, or between models — change the embedding env vars, then re-embed every\nmemory under the new model in one step:\n\n```sh\n./target/release/memkeeper reindex --embed --store ~/.memkeeper/store.sqlite\n```\n\nThis wipes the old vectors, records the new active model, and re-embeds all active\nmemories in one transaction. It is the supported way to change models; there is no\npartial mix.\n\n## Document store (RAG)\n\nAlongside curated memories, memkeeper can hold a separate tier of ingested\ndocument chunks for retrieval-augmented use. Chunks live in their own space\n(default `documents`), isolated from the curated memory tier, so they never\nreceive supersession, dedup, graph, or promotion treatment.\n\n- `ingest` — store a document source as embedded, isolated chunks. Re-ingesting\n  the same `source_path` repairs that chunk's provenance in place; identical\n  content under a different path is kept as an independent chunk.\n- `document-search` — hybrid (BM25 + vector) search over the chunks, with a\n  citation back to `source_path` and chunk index.\n- `document-get` — fetch a document's chunks by path, or one chunk by id.\n- `document-duplicates` — surface exact-content duplicate chunks (the same\n  content held under different sources) as clusters. `stats` also reports a\n  `document_duplicate_clusters` count so you know when there are duplicates worth\n  reviewing.\n- `document-prune` — delete the specific chunks you choose (supports `dry_run`).\n  Deletion is always explicit: review duplicates, decide which copies to keep,\n  then prune the rest.\n- `promotion-candidates` / `mark-extracted` — rank chunks that earned retrieval\n  traffic, and mark a chunk extracted once it has been promoted into a memory.\n\nRun `memkeeper schema <command>` for each command's accepted JSON fields. Over\n`serve --http`, reads (search/get/duplicates) are available on the read-only\ndashboard. Writes (`ingest`, `document-prune`) are disabled unless you set a\nwrite token: start the server with `MEMKEEPER_HTTP_WRITE_TOKEN=<secret>` in the\nenvironment, then send it on write requests as `Authorization: Bearer <secret>`.\nWith no token set, the HTTP server is read-only.\n\n## The dashboard\n\n`memkeeper serve --http` starts a read-only local dashboard (default\n`http://127.0.0.1:7777`) for browsing memories and the entity graph. Point it at a\nstore with `--store <path>` (or `MEMKEEPER_STORE`); it uses the default store\notherwise.\n\n**A fresh store starts empty — that's expected.** Two views, populated\ndifferently:\n\n- The **memory list** fills as you `remember`.\n- The **graph** visualizes *entities and relationships*, which are a separate layer\n  from raw memories. Native MCP `remember` captures bounded entities, aliases, and\n  typed relationships with a confirmed memory when the host agent supplies them.\n  Raw CLI callers can pass the same graph structure, or curate it with\n  `entity-upsert` / `relationship-upsert`. The `dream graph` task may add generic\n  `related_to` links for visualization, but those links are not retrieval\n  evidence. Plain memories without graph fields still fill the list without\n  adding graph edges.\n\n## Benchmarks\n\nOn [LoCoMo](https://github.com/snap-research/locomo) (10 multi-session dialogues,\n1,982 evidence-bearing questions), memkeeper's default semantic retrieval scores:\n\n| Metric | Score |\n|---|---|\n| recall@20 | 0.768 |\n| hit@20 | 0.880 |\n| MRR | 0.668 |\n\nPrompt-time search on a warm `serve` daemon (ONNX models loaded once) runs in\n**~25 ms** p50/p95, about 32× faster than a cold per-call binary that reloads the\nmodels on every query.\n\nFull methodology, per-config results (including the late-interaction upgrade), and\na reproduction script are in [docs/benchmarks.md](docs/benchmarks.md).\n\n## Build from source\n\nBuilding is optional — the [Quickstart](#quickstart) binary is self-contained.\nBuild from source to track the latest `main`, produce a leaner lexical-only binary,\nor develop.\n\n**Prerequisites:** a **Rust toolchain** (stable, via [rustup](https://rustup.rs);\nedition 2021, Rust 1.56+) and a **C toolchain** for the native deps (bundled SQLite\nplus the ONNX runtime for semantic search). macOS: Xcode Command Line Tools\n(`xcode-select --install`); Debian/Ubuntu: `build-essential`. Building fetches\ncrates from crates.io the first time; after that a clean build is offline.\n\n```sh\n# Semantic build (default): local embeddings + cross-encoder rerank.\ncargo build --release\n# ...or lexical-only — omits the ONNX runtime and models entirely:\ncargo build --release --no-default-features\n\n# The binary lands at ./target/release/memkeeper (not on PATH). To install it:\ncargo install --path crates/memkeeper-cli   # then a bare `memkeeper` works\n```\n\nThen `memkeeper pull-models` to enable semantic, exactly as in the Quickstart.\n\n## Workspace layout\n\n| Crate | Role |\n|---|---|\n| `memkeeper-core` | Core types and retrieval policy |\n| `memkeeper-store` | SQLite storage, schema, indexing, promotion |\n| `memkeeper-embed` | ONNX embeddings + cross-encoder reranker |\n| `memkeeper-protocol` | Wire protocol (`memkeeper.v0.1`) |\n| `memkeeper-cli` | The `memkeeper` binary (CLI + daemon) |\n\nEditor/agent integrations live under `adapters/` (an MCP bridge and a thin\nextension client).\n\n## Further reading\n\nDesign notes and benchmarks on the [memkeeper blog](https://memkeeper.ai/blog/):\n\n- [Local-first memory for AI agents](https://memkeeper.ai/blog/local-first-memory-for-ai-agents): why the default should be your own machine, not a hosted vector DB.\n- [Why hybrid retrieval beats pure vector search](https://memkeeper.ai/blog/hybrid-retrieval-vs-vector-search): what BM25, dense embeddings, and a cross-encoder each cover.\n- [A memory that says \"I don't know\"](https://memkeeper.ai/blog/memory-that-says-i-dont-know): abstention, and the number we publish to prove it.\n- [Benchmarking agent memory on LoCoMo](https://memkeeper.ai/blog/benchmarking-agent-memory-locomo): the method and a script to reproduce the numbers.\n- [Where memkeeper fits](https://memkeeper.ai/blog/where-memkeeper-fits): an honest comparison to mem0, Zep, and Graphiti.\n- [Getting started in ten minutes](https://memkeeper.ai/blog/getting-started-with-memkeeper): from install to recall, including MCP wiring.\n\n## Memkeeper family\n\n[Warden](https://github.com/teflon07/memkeeper-warden) is a companion capability\nbroker and execution gate: it decides whether an agent's requested action (a\nshell command, a file read/write) is allowed by a declared, auditable policy, and\nlogs every decision. memkeeper remembers; Warden guards.\n\n## License\n\nDual-licensed under either of [MIT](LICENSE-MIT) or\n[Apache-2.0](LICENSE-APACHE) at your option.\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md). Contributions require signing the project\n[Contributor License Agreement](docs/CLA.md) — the CLA bot prompts you on your\nfirst pull request. You keep the copyright to your contributions.\n",
  "bytes": 20260,
  "sha": "edb48a3f7ddce85d6a5742915929555f577bb5b539a3b086447a5c384b2f2353",
  "repo_slug": "teflon07/memkeeper",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_teflon07_memkeeper_cfbed7cb/readme"
}