Memkeeper

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

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

New 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.5

The prebuilt release binaries support all three modes