memkeeper

<p align="center">
  <img src="assets/logo.png" alt="memkeeper logo" width="180" height="180" />
</p>

<p align="center"><em>Most software has the memory of a goldfish. This one doesn&rsquo;t.</em></p>

<p align="center">
  <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>
</p>

# 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](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.

<p align="center">
  <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" />
</p>

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

> Status: pre-release (v0.5.2). APIs and the wire protocol may change before 1.0.

## Quickstart

```sh
# 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](https://github.com/teflon07/memkeeper/releases) and verify its
`.sha256`, or [build from source](#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.2 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:

```sh
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:

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

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

<p align="center">
  <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" />
</p>

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

## 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](#document-store-rag),
  memkeeper's separate RAG tier that chunks and embeds files into an isolated
  space (the [`memkeeper-ingest`](https://github.com/teflon07/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](#use-it-from-your-agent-mcp) 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.

<p align="center">
  <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" />
</p>

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

| Mode | Network | Setup |
|---|---|---|
| **Local semantic** (default) | none | install binary, then `pull-models` |
| **Lexical only** | none | works out of the box; just skip `pull-models` |
| **Off-device semantic** | embeds via an API | set `MEMKEEPER_EMBED_PROVIDER=openai` + base URL + key |

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

```sh
# 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 Quicksta