teflon07/memkeeper

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 main branch may be
> regenerated, so **pin to tagged releases** (or the release artifacts) rather
> than to arbitrary main commits — 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.
Real CLI output, formatted for readability via scripts/mkfmt . The search query shares no keywords with the memory it surfaces.
> Status: pre-release (v0.5.3). APIs and the wire protocol may change before 1.0.
Quickstart
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
@ or - (stdin) instead of an inline string, which avoids shell-quoting
pitfalls (handy in Windows PowerShell).
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:
Install the current release, run the migration explicitly, and verify the result
before restarting any long-running process:
init 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):
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.
Real memkeeper mcp JSON-RPC round-trips, formatted for readability via scripts/mcpfmt .
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-ingest
add-on imports whole folders this way). Or distill the document down to its
takeaways and store those as memories.