Memkeeper

What teflon07/memkeeper MCP server does

teflon07/memkeeper is a local memory engine for AI agents. It keeps durable, self-contained facts, decisions, preferences, and lessons in a SQLite database on the machine running the binary. An agent can call remember to capture a memory and search to retrieve relevant memories in a later session.

The project is intended for curated memory rather than automatic transcript logging. Each entry should express one complete idea with enough context to stand alone. The repository describes a retention model that can promote recurring, high-signal memories to a durable tier.

How it works

The MCP interface uses JSON-RPC 2.0 over stdio. An MCP client starts the native memkeeper executable with the mcp argument, then uses the same memory store and retrieval path exposed by the command-line interface.

Retrieval has a lexical baseline based on BM25 and full-text search. Optional local semantic retrieval uses ONNX embedding models, and a cross-encoder reranker can refine results. Lexical search works without downloaded models; running pull-models enables the default local semantic mode. The embedding backend is recorded in the store, so changing it requires re-embedding with reindex --embed.

The store uses atomic writes and schema-versioned storage. Memory records can also include validated aliases and typed relationships supplied by the calling agent as a bounded graph projection. The graph data and memory commit together when provided through the MCP request.

Setup and configuration

Install a tagged release binary, use the provided install script, download models if semantic retrieval is wanted, and initialize the store:

memkeeper pull-models
memkeeper init

The default database path is ~/.memkeeper/store.sqlite. A different path can be selected with --store. JSON command input can be passed inline, read from a file using @<file>, or read from standard input.

For MCP, configure the client to launch the native binary:

{
  "mcpServers": {
    "memkeeper": {
      "command": "memkeeper",
      "args": ["mcp"]
    }
  }
}

The teflon07/memkeeper MCP server has no required Python runtime, hosted service, API key, or separate server process. The project is pre-release, and its APIs and wire protocol may change before version 1.0. Tagged releases are recommended instead of arbitrary main commits.

Tools and capabilities

• remember stores a durable memory from an MCP client or script.
• search retrieves memories using the configured retrieval pipeline.
• init creates or initializes a store and can be rerun safely.
• pull-models downloads the local semantic models.
• reindex --embed re-embeds memories after an embedding backend change.
• backup creates a copy of the SQLite store.
• doctor checks the initialized store.
• hook retrieve provides a Claude Code UserPromptSubmit hook that injects relevant memories into prompts.

Whole documents are not automatically chunked in the curated memory tier. The README points to a separate document-store RAG tier for files and folders, while short distilled takeaways can be stored as memories.

Limitations and notes

Memory capture is deliberate: memkeeper does not run a background extractor or automatically log transcripts. The host agent supplies structured graph fields when relationships are recorded.

Long entries can have weaker semantic recall because the embedder processes only roughly the first 512 tokens, although lexical BM25 indexes the full text. The project currently describes itself as pre-release. Upgrading from older schema versions requires attention to the documented migration and backup process; schema 6 stores cannot be opened by v0.2.x binaries.