Most software has the memory of a goldfish. This one doesn’t.

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

# 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).

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" --json

Install 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" --json

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):

{ "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.

_{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.

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 remember during 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.

_{The deterministic floor (zero models, zero network) and semantic + rerank on top — same store, same query path. Real output via scripts/mkfmt.}

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-models

pull-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.