memkeeper
memkeeper is a local-first, durable memory engine for AI agents that stores, ranks, and retrieves context on-device using SQLite (BM25/FTS) with optional semantic (ONNX) retrieval.
Memory Lifecycle
remember— Write a single atomic memory (fact, decision, preference, lesson) with rich metadata: tags, confidence, validity windows, scope, supersession, and more.forget— Soft-delete a memory by ID; usemode='correct'to record a factual correction signal.verify— Re-confirm an existing memory is still accurate, updating its last-verified timestamp.get— Fetch one memory by ID, optionally including version history and provenance.memory_list— Browse recent memories in reverse-chronological order with optional filters.
Retrieval & Context Assembly
search— Relevance-ranked retrieval using semantic (embedding) search with BM25/FTS fallback and optional cross-encoder reranking.pack— Assemble a compact, prompt-ready context block from one or more queries, with character budgeting, graph expansion, and query expansion options.
Entity Knowledge Graph
entity_upsert/entity_search— Create, update, or search entities (persons, projects, concepts) with canonical names, aliases, and metadata.relationship_upsert— Create or update directed relationships between entities.graph_neighbors— Traverse the graph outward from a starting entity to a bounded depth.graph_context— Build a prompt-ready context block centered on one entity, including neighbors and linked memories.dream_graph— Dry-run preview of entity/relationship extractions and merges without writing anything.
Human-Review Queue
candidate_submit— Queue a proposed memory for human review instead of writing it directly to recall.candidate_list— List pending, approved, or rejected review candidates.
Store Inspection
stats— Report memory counts, breakdowns by space/silo/status/kind, schema version, DB size, and health rollups.
All operations are local-first (embedded SQLite), require no network for lexical search, and optionally use on-device ONNX models or an OpenAI-compatible API for semantic embeddings.
Allows using OpenAI's embedding API for semantic memory retrieval, as an alternative to on-device models.
memkeeper
Local-first memory for AI agents. A fast, embeddable memory engine that stores, ranks, and retrieves an agent's durable context, entirely on your machine, with no required network or LLM calls.
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.
ℹ️ Generated release mirror. This repo is generated from a private development repo and published as releases. The
mainbranch may be regenerated, so pin to tagged releases (or the release artifacts) rather than to arbitrarymaincommits — tagged releases are stable. See CONTRIBUTING.md for how to contribute; issues, security reports, and design feedback are the best paths today.
Local-first. A single SQLite database. No server, no cloud, no telemetry.
Fast at prompt time. Deterministic BM25/FTS retrieval with optional ONNX semantic embeddings and a cross-encoder reranker.
Durable by design. Atomic writes, schema-versioned storage, and a retention model that promotes recurring, high-signal memories to a durable tier.
Status: pre-release (v0.5.3). APIs and the wire protocol may change before 1.0.
Quickstart
# Install the latest release binary (macOS arm64 / Linux x86_64) to ~/.local/bin.
# It's self-contained — nothing else to install.
curl -fsSL https://raw.githubusercontent.com/teflon07/memkeeper/main/install.sh | bash
# Optional, one-time: fetch on-device semantic models. Lexical search works without it.
memkeeper pull-models
# Create a store, remember something, search it back.
memkeeper init
memkeeper remember --json '{"content":"memkeeper stores memories in a local SQLite database"}'
memkeeper search --json '{"query":"where are memories stored","limit":3}'That's the whole install: a self-contained binary, no runtime network/LLM/API key.
Prefer not to pipe a script to your shell? Grab a binary from the
releases page and verify its
.sha256, or build from source. The store defaults to
~/.memkeeper/store.sqlite when --store is omitted; a --json value can also be
@<file> or - (stdin) instead of an inline string, which avoids shell-quoting
pitfalls (handy in Windows PowerShell).
Related MCP server: SharedBrain
Upgrade from v0.2.x
v0.3.0 introduced the schema 5 to schema 6 upgrade; v0.4.0 through v0.5.3 keep
schema 6 unchanged. The migration is transactional, but schema 6 stores cannot
be opened by v0.2.x. Stop any long-running memkeeper process and keep a
schema 5 backup until you verify the upgrade.
Back up the store with your v0.2.x binary before installing the current release:
STORE=~/.memkeeper/store.sqlite
memkeeper backup --store "$STORE" --output "$STORE.schema5.bak" --jsonInstall the current release, run the migration explicitly, and verify the result before restarting any long-running process:
curl -fsSL https://raw.githubusercontent.com/teflon07/memkeeper/main/install.sh | bash
memkeeper init --store "$STORE" --json
memkeeper doctor --store "$STORE" --jsoninit is safe to rerun. If you need to roll back, restore the schema 5 backup
before starting the older binary.
Use it from your agent (MCP)
memkeeper speaks MCP (JSON-RPC 2.0 over stdio), so any MCP client — Claude Code, Cursor, and others — can read and write memory during a session. Point your client's MCP config at the native binary (no Python, no extra deps):
{ "mcpServers": { "memkeeper": { "command": "memkeeper", "args": ["mcp"] } } }The agent calls remember to capture a durable fact and search to recall it later,
across separate sessions, with the same retrieval as the CLI.
What to store
memkeeper holds self-contained memories: facts, decisions, preferences,
lessons. Each remember is one memory written to stand on its own, with its
context and intent intact (store "the user likes pineapple on pizza," not just
"pineapple"). Atomic means one idea per memory, not a stripped keyword.
Retrieval, dedup, supersession, and the entity graph all work best at that grain.
Two ends to avoid:
Too small: a bare keyword or fragment that drops the point.
Too large: a whole document. The curated memory tier has no chunking, and the embedder sees only the first ~512 tokens of an entry, so loading long files (for example, an entire markdown library) gives weak semantic recall on those entries (lexical BM25 still indexes the full text). To bring whole documents in, don't store them as memories — use the document store, memkeeper's separate RAG tier that chunks and embeds files into an isolated space (the
memkeeper-ingestadd-on imports whole folders this way). Or distill the document down to its takeaways and store those as memories.
Capturing memories
memkeeper is curated memory you populate deliberately — not an automatic transcript logger. Memories get in two ways:
Directly —
memkeeper remember --json '{"content":"…"}', from the CLI or a script.From an agent — the native MCP server lets an MCP client (Claude and other agents) call
rememberduring a session, so durable facts are captured as they come up. When a confirmed memory names entities or states a relationship, the MCP tool asks the agent to include a bounded graph projection in the same call. memkeeper validates and commits the memory, exact aliases, and typed relationships atomically. The one memory ID is the relationship evidence.
memkeeper does not run a second LLM or background extractor for this. The MCP host
agent supplies the structured graph fields while making the normal remember
call. Raw CLI callers can supply the same graph object explicitly.
On the retrieval side, memkeeper hook retrieve is a Claude Code
UserPromptSubmit hook client that injects relevant memories into the prompt — so an
agent recalls without an explicit search. It retrieves; capture stays a deliberate
remember.
Semantic retrieval (default)
memkeeper has three retrieval modes. Local semantic is the default and the
recommended, fully on-device mode. Pick one up front — the embedding backend is
recorded in the store, so changing it means re-embedding (reindex --embed), not a
flip.
Mode | Network | Setup |
Local semantic (default) | none | install binary, then |
Lexical only | none | works out of the box; just skip |
Off-device semantic | embeds via an API | set |
Privacy: off-device semantic sends your memory text to the embeddings provider to be vectorized. Use it only where that is acceptable; the two on-device modes never send memory content anywhere.
Local semantic (default)
The release binary ships semantic-capable (the ONNX runtime is statically bundled), so there's no rebuild — it just needs the embed + rerank models, which aren't downloaded automatically. Fetch them once:
# Needs curl; ~2.1GB, or --quantized for ~0.6GB (slightly lower recall).
memkeeper pull-modelspull-models writes to ~/.memkeeper/models/ (override with MEMKEEPER_MODELS_DIR
or --dir) — exactly where memkeeper looks by default. So semantic turns on with
no env vars to set: run a search afterward and it's active.
If the models are missing, memkeeper does not degrade silently: it logs their
absence and points you at pull-models, marks results semantic-unavailable
(e.g. "semantic":{"attempted":false,"reason":"missing_embedding"}), and falls
back to lexical (BM25/FTS) so search keeps working. Set
MEMKEEPER_REQUIRE_SEMANTIC=1 to fail closed instead — refuse the request
rather than serve degraded results — in any deployment that must never silently
run lexical-only.
Embeddings are computed when a memory is written. Memories you stored before the models were present (for example, the one from the Quickstart above) are lexical-only until embedded. Backfill existing memories once with:
memkeeper reindex --embedNew memories written with the models in place are embedded automatically.
Lexical only
Skip pull-models and the release binary runs deterministic, model-free
lexical-only (BM25/FTS) retrieval — zero network, zero models. Building from
source with --no-default-features produces a leaner binary that omits the ONNX
runtime entirely (see Build from source).
Off-device semantic (no model download)
Prefer not to download the ONNX models? Point memkeeper at an OpenAI-compatible
embeddings API (OpenAI, OpenRouter, or any compatible proxy) instead. This mode
embeds and reranks over the network rather than loading the local models, so it
needs no pull-models:
# Embeddings (required for semantic): any OpenAI-compatible /embeddings endpoint.
export MEMKEEPER_EMBED_PROVIDER=openai # "openai" = the OpenAI-compatible API dialect
export MEMKEEPER_EMBED_BASE_URL=https://api.openai.com/v1/embeddings # or your provider, e.g. OpenRouter
export MEMKEEPER_EMBED_API_KEY=sk-...
export MEMKEEPER_EMBED_MODEL=text-embedding-3-small
export MEMKEEPER_EMBED_DIMS=1536
# Reranking (optional, recommended): Cohere /rerank dialect, which OpenRouter speaks.
export MEMKEEPER_RERANK_PROVIDER=openrouter
export MEMKEEPER_RERANK_API_KEY=sk-...
export MEMKEEPER_RERANK_MODEL=cohere/rerank-v3.5The prebuilt release binaries support all three modes (--features semantic,api):
run pull-models for fully on-device local semantic (the default and recommended
mode), configure an API key for off-device semantic, or configure neither and they
serve lexical (BM25/FTS). MEMKEEPER_REQUIRE_SEMANTIC=1 makes them refuse rather
than serve degraded.
Prebuilt binaries are published for macOS (Apple Silicon) and Linux x86_64.
Windows is experimental — there's no prebuilt binary, but it builds and runs
from source; see docs/windows.md. (serve --socket is Unix-only
there; the http dashboard and stdio serve are cross-platform.)
How pack combines semantic and graph retrieval
pack uses one retrieval path. Semantic and lexical matches supply memory
seeds, exact entity and alias matches supply graph seeds, and bounded
evidence-backed graph traversal joins both sets on canonical memory IDs. Every
candidate then competes in the same cross-encoder rerank pool. Graph candidates
receive no reserved slots or automatic demotion, and there is no production
graph on/off mode. A store with no eligible graph route simply returns the
semantic and lexical pool unchanged.
Switching the embedding model
The embedding backend is recorded per store, and memkeeper refuses to mix vectors from different models (they live in different vector spaces). To switch — local↔ off-device, or between models — change the embedding env vars, then re-embed every memory under the new model in one step:
./target/release/memkeeper reindex --embed --store ~/.memkeeper/store.sqliteThis wipes the old vectors, records the new active model, and re-embeds all active memories in one transaction. It is the supported way to change models; there is no partial mix.
Document store (RAG)
Alongside curated memories, memkeeper can hold a separate tier of ingested
document chunks for retrieval-augmented use. Chunks live in their own space
(default documents), isolated from the curated memory tier, so they never
receive supersession, dedup, graph, or promotion treatment.
ingest— store a document source as embedded, isolated chunks. Re-ingesting the samesource_pathrepairs that chunk's provenance in place; identical content under a different path is kept as an independent chunk.document-search— hybrid (BM25 + vector) search over the chunks, with a citation back tosource_pathand chunk index.document-get— fetch a document's chunks by path, or one chunk by id.document-duplicates— surface exact-content duplicate chunks (the same content held under different sources) as clusters.statsalso reports adocument_duplicate_clusterscount so you know when there are duplicates worth reviewing.document-prune— delete the specific chunks you choose (supportsdry_run). Deletion is always explicit: review duplicates, decide which copies to keep, then prune the rest.promotion-candidates/mark-extracted— rank chunks that earned retrieval traffic, and mark a chunk extracted once it has been promoted into a memory.
Run memkeeper schema <command> for each command's accepted JSON fields. Over
serve --http, reads (search/get/duplicates) are available on the read-only
dashboard. Writes (ingest, document-prune) are disabled unless you set a
write token: start the server with MEMKEEPER_HTTP_WRITE_TOKEN=<secret> in the
environment, then send it on write requests as Authorization: Bearer <secret>.
With no token set, the HTTP server is read-only.
The dashboard
memkeeper serve --http starts a read-only local dashboard (default
http://127.0.0.1:7777) for browsing memories and the entity graph. Point it at a
store with --store <path> (or MEMKEEPER_STORE); it uses the default store
otherwise.
A fresh store starts empty — that's expected. Two views, populated differently:
The memory list fills as you
remember.The graph visualizes entities and relationships, which are a separate layer from raw memories. Native MCP
remembercaptures bounded entities, aliases, and typed relationships with a confirmed memory when the host agent supplies them. Raw CLI callers can pass the same graph structure, or curate it withentity-upsert/relationship-upsert. Thedream graphtask may add genericrelated_tolinks for visualization, but those links are not retrieval evidence. Plain memories without graph fields still fill the list without adding graph edges.
Benchmarks
On LoCoMo (10 multi-session dialogues, 1,982 evidence-bearing questions), memkeeper's default semantic retrieval scores:
Metric | Score |
recall@20 | 0.768 |
hit@20 | 0.880 |
MRR | 0.668 |
Prompt-time search on a warm serve daemon (ONNX models loaded once) runs in
~25 ms p50/p95, about 32× faster than a cold per-call binary that reloads the
models on every query.
Full methodology, per-config results (including the late-interaction upgrade), and a reproduction script are in docs/benchmarks.md.
Build from source
Building is optional — the Quickstart binary is self-contained.
Build from source to track the latest main, produce a leaner lexical-only binary,
or develop.
Prerequisites: a Rust toolchain (stable, via rustup;
edition 2021, Rust 1.56+) and a C toolchain for the native deps (bundled SQLite
plus the ONNX runtime for semantic search). macOS: Xcode Command Line Tools
(xcode-select --install); Debian/Ubuntu: build-essential. Building fetches
crates from crates.io the first time; after that a clean build is offline.
# Semantic build (default): local embeddings + cross-encoder rerank.
cargo build --release
# ...or lexical-only — omits the ONNX runtime and models entirely:
cargo build --release --no-default-features
# The binary lands at ./target/release/memkeeper (not on PATH). To install it:
cargo install --path crates/memkeeper-cli # then a bare `memkeeper` worksThen memkeeper pull-models to enable semantic, exactly as in the Quickstart.
Workspace layout
Crate | Role |
| Core types and retrieval policy |
| SQLite storage, schema, indexing, promotion |
| ONNX embeddings + cross-encoder reranker |
| Wire protocol ( |
| The |
Editor/agent integrations live under adapters/ (an MCP bridge and a thin
extension client).
Further reading
Design notes and benchmarks on the memkeeper blog:
Local-first memory for AI agents: why the default should be your own machine, not a hosted vector DB.
Why hybrid retrieval beats pure vector search: what BM25, dense embeddings, and a cross-encoder each cover.
A memory that says "I don't know": abstention, and the number we publish to prove it.
Benchmarking agent memory on LoCoMo: the method and a script to reproduce the numbers.
Where memkeeper fits: an honest comparison to mem0, Zep, and Graphiti.
Getting started in ten minutes: from install to recall, including MCP wiring.
Memkeeper family
Warden is a companion capability broker and execution gate: it decides whether an agent's requested action (a shell command, a file read/write) is allowed by a declared, auditable policy, and logs every decision. memkeeper remembers; Warden guards.
License
Dual-licensed under either of MIT or Apache-2.0 at your option.
Contributing
See CONTRIBUTING.md. Contributions require signing the project Contributor License Agreement — the CLA bot prompts you on your first pull request. You keep the copyright to your contributions.
Available Tools
16 toolscandidate_listA
List memories in the human-review queue, filtered by review status. Read-only. Use to see what has been proposed via candidate_submit and its disposition; approving or rejecting candidates is a human action in the CLI/dashboard.
Inputs: limit, space, status.
candidate_submitA
Queue a proposed memory for human review instead of writing it to recall directly. Mutating: adds an item to the review queue (it does not enter recall until a human approves it via CLI/dashboard). Use this for plausible-but-unverified inferences; use remember when the fact is confirmed and should be recallable immediately.
Inputs: content (required), kind, silo, tags, +12 more.
dream_graphA
Preview the graph-maintenance pass in dry-run (proposal-only) mode: surfaces the entity and relationship extractions and merges the nightly dream job would make, without writing anything. Read-only; no side effects. Use to inspect what graph changes are pending before they are applied.
Inputs: space, max_memories.
entity_searchA
Search the entity graph by key, canonical name, alias, or type (substring match). Read-only. Returns entity records, not memories — use it to resolve an entity_key or canonical name from a partial term. For memory content use search; to traverse outward from a known entity use graph_neighbors or graph_context.
Inputs: limit, query, entity_key, entity_type, +1 more.
entity_upsertA
Create or update one entity in the graph projection (register it, rename it, or add aliases). Mutating. The graph is a rebuildable projection over memories, which remain the source of truth — use this to curate entity identity, not to store facts (use remember for facts).
Inputs: entity_key (required), canonical_name (required), space, status, +6 more.
forgetA
Retire one specific memory by id. Mutating: tombstones the memory (a soft delete that preserves audit history), so it stops surfacing in recall; it is not a hard delete. Set mode='correct' when retiring a memory because it is WRONG (e.g. a surfaced/recalled fact the user contradicted), as opposed to routine cleanup: this records a distinct correct event with the memory's provenance, and if you pass corrected_by (the id of the memory holding the right answer) it also records a contradicts link. Use mode='correct' for factual corrections so the signal is captured explicitly rather than inferred later.
Inputs: memory_id (required), mode, reason, dry_run, +1 more.
getA
Fetch one memory by its exact id (for example, an id returned by search or memory_list). Read-only. Use when you already have the id and want the full record; use search to find a memory by its content.
Inputs: memory_id (required), include_source, include_history.
graph_contextA
Build a compact, prompt-ready context pack centered on an entity: the entity, its graph neighbors, and the most relevant linked memories, budgeted to a character limit. Read-only. Use when an agent needs ready-to-inject context about one specific entity; use pack for query-driven context, or graph_neighbors for raw graph edges.
Inputs: entity_key (required), depth, max_chars, max_edges, +2 more.
graph_neighborsA
Traverse the entity graph outward from a starting entity, returning connected entities and the relationships between them up to a bounded depth. Read-only. Use to explore how an entity connects to others (raw graph structure); use graph_context if you want a prose, prompt-ready context pack instead of edges.
Inputs: entity_key (required), depth, max_edges, include_source, +1 more.
memory_listA
List recent memories in reverse-chronological order for review or cleanup, optionally filtered. Read-only. Use to browse or audit what is stored (including stale or superseded entries); use search or pack for relevance-ranked retrieval against a query.
Inputs: limit, space, status, entity_key, +2 more.
packA
Assemble a compact, prompt-ready context block from one or more queries: retrieves, reranks, and budgets the top memories into injectable text. Read-only. This is the retrieval path for putting memory into an agent's prompt; use search instead when you want individual scored records rather than an assembled block.
Inputs: queries (required), tags, space, title, +15 more.
relationship_upsertA
Create or update one directed relationship in the graph: subject --relation_type--> object. Mutating. Identify each endpoint by entity_key (preferred) or internal entity_id. The graph is a rebuildable projection over memories — curate structure here, store facts with remember.
Inputs: relation_type (required), space, status, metadata, +11 more.
rememberA
Write one durable memory the agent should be able to recall later. Mutating: persists a memory (set dry_run to validate without writing). Store exactly one atomic, self-contained fact, decision, preference, or lesson per call — include enough context that it stands alone ("the user deploys from the release branch, never main", not just "release branch"). Do not store secrets or raw transcripts. For a plausible-but-unverified inference, use candidate_submit instead so a human approves it first.
Inputs: content (required), kind, mode, silo, +20 more.
searchA
Find individual memories ranked by relevance to a query. Semantic-primary when embedding models are loaded, falling back to deterministic BM25/FTS keyword search otherwise; cross-encoder reranked by default. Read-only. Returns scored, individual memory records (with ids) — use this to locate or inspect specific memories. To assemble a prompt-ready context block, use pack instead; to browse recent memories without a query, use memory_list.
Inputs: query (required), tags, limit, space, +5 more.
statsA
Report store statistics: total/active memory counts, breakdowns by space, silo, status, and kind, schema version, and database size. Read-only; no side effects. Use to inspect the store's overall state and health, not to retrieve memories (use search or pack for that).
Inputs: include_health, include_indexes.
verifyA
Re-confirm that an existing memory is still accurate as of now, stamping its last-verified time. Mutating: updates verification metadata only — it does NOT change the memory's content or promote it to a durable tier. If the value has CHANGED, do not verify; write a new memory with remember and supersede the old one instead.
Inputs: memory_id (required), verified_against.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 16 tools
Every tool has a distinct role: memory retrieval, memory writes, graph traversal/curation, candidate review, and stats are clearly separated. Where overlap could occur (get vs search, pack vs graph_context, remember vs candidate_submit), the descriptions explicitly call out when to use which.
Names are readable and consistently snake_case, but they mix single-word verbs (get, remember, forget, verify, pack), object_verb forms (memory_list, entity_search, candidate_submit), and noun phrases (graph_context, dream_graph, graph_neighbors). This makes the naming functional but not predictably patterned.
At 16 tools, the set is slightly above the ideal 3–15 range, but the count is justified by the server's multiple subdomains: memory recall, memory mutation, graph projection, candidate review, and stats. Each tool earns its place without feeling redundant.
The server covers the full memory lifecycle for its design: write, retrieve, list, soft-delete, verify, and candidate-driven human review, plus graph curation and maintenance preview. Content updates are intentionally handled via writing a new memory and forgetting the old one; candidate approval/hard deletion are left to human/external channels, which is a reasonable boundary.
Maintenance
Related MCP Connectors
Persistent memory for AI agents. Search and store durable facts, preferences and decisions.
Persistent memory for AI agents. Semantic search, memory graph, W3C DID identity.
Universal memory for AI agents and tools. Save, organize and search context anywhere.
Persistent memory for AI agents. Search, store, and recall across sessions.
Related MCP Servers
AlicenseAqualityDmaintenanceSelf-hosted Mem0 MCP server integrating Qdrant, Neo4j, and Ollama for semantic memory search, graph entity relationships, and memory management via OpenMemory API.64MIT- AlicenseNot gradedqualityBmaintenanceLocal-first, multi-user shared memory for AI agents with semantic search, offline support, and team synchronization.MIT

Geniro Graphiti MCPofficial
AlicenseNot gradedqualityDmaintenanceA Model Context Protocol server that provides Claude CLI with a Graphiti knowledge-graph memory backed by Neo4j, featuring synchronous writes and no silent ingestion failures.Apache 2.0- AlicenseNot gradedqualityDmaintenanceLightweight persistent memory for AI agents using a single SQLite file with hybrid search (keywords + semantics). Zero to 12MB install, no cloud or server required.9MIT