Memors

memors-mcp

A local MCP server that gives agents a measurable, explainable knowledge base: one Go binary, no cloud, no CGo, one SQLite file per knowledge base. Documents and facts go in with provenance; searches come back as one ranked list from four retrieval arms, each result with its address, trust and a reason for its rank. A human reads the same knowledge base from the terminal or as exported markdown.

It began as a Go rewrite of obra/private-journal-mcp and was rebuilt from scratch as a knowledge base in 2026-10. Version 1.0 fixes the contract: tool names and parameters, the memo:// addresses, the explain fields and the export format. How search decides is written down in docs/architecture.md; the plan for the research layers (graph, compaction, web UI) is docs/roadmap.md; the research behind it is docs/knowledge-base-sota.md.

What it does

Claude (or any MCP client) gets ten tools over one knowledge base:

On macOS, the optional menu-bar app MemoRS Tray (tray/, a separate binary; the only part built with cgo) shows the clients connected to each memors-mcp serve --http server, opens a server's Live page in a window, and starts and stops servers. Its setup assistant downloads, verifies and installs memors-mcp from the GitHub releases and sets up a first knowledge base, and its settings window covers the rest (launch at login, servers, embedding model). See docs/guide/user/menu-bar.md.

For a human there is memors-mcp ui: a read-only web page on loopback with the same search (and the same explain table the agent gets), documents and passages with provenance and history, the facts timeline, entity neighbourhoods, agent-written pages, status, lint and the query log. Nothing on it can change the knowledge base.

The same addresses are readable as MCP resources (memo://doc/{id}, memo://chunk/{id}, memo://source/{id}, memo://fact/{id}), and memo://index or memo://ns/{namespace}/index give a one-line-per-document view under 8 KB for the start of a session. The MCP prompt ask turns a conversation into a chat over the knowledge base: the client's model answers from search and read, citing every claim by its memo:// address (in Claude Code: /mcp__memors__ask, then ask as usual). SKILL.md tells an agent how to use the tools well; memors-mcp export --index prints the same index for an AGENTS.md or CLAUDE.md file.

Everything is stored locally. There is exactly one outbound network call in the whole system: downloading the embedding model from Hugging Face on first start. After that, nothing leaves the machine. The server never fetches URLs; the agent fetches and passes the text.

How search works

search runs up to three retrieval arms over the same pre-filtered set of live passages and fuses them:

• Keyword arm — SQLite FTS5 with the Porter stemmer and BM25 scoring, over the passage and its section header. "review" finds "reviewing".
• Exact arm — a second FTS5 index that keeps identifiers whole (useCallback, net/http, ERR_CONN_RESET). Added automatically when the query looks like code.
• Semantic arm — the query and every passage are embedded with the configured model (default granite-small-r2, IBM granite-embedding-small-english-r2, 384 dimensions, run locally via hugot's pure-Go ONNX backend) and compared by cosine similarity in a plain SQLite table. memors-mcp model ls lists the alternatives, including the instant static model potion.

The three ranked lists are combined with reciprocal rank fusion at equal weights (a keyword-only hit at rank 1 ties a vector hit at rank 1, so the keyword arm can add results rather than only reorder them), passages are aggregated to documents by their best passage, notes and conversations get a bounded recency boost (×0.8 to ×1.0, halving every 90 days; versioned docs do not age), the list is cut at the first large score gap, and results are packed to the requested token budget. A passage whose only evidence is a semantic similarity below the weak band (0.30) is dropped, so a question about nothing in the corpus returns zero results with a reason and a hint instead of a page of noise.

Two structural arms join when the question names two or more known things or asks how things relate: the entity arm returns the passages that mention the named entities, and the graph arm walks the mention graph with personalised PageRank from each named entity and returns the passages all the walks agree on, which is how a question about the Billing Service finds the replication page that never names it. explore walks the same graph by hand. Both are routed rather than always on because an always-on entity arm made plain lookups worse.

Curated pages are a third thing to search (granularity: page): markdown an agent wrote from passages through compact and submit, stored as derived, citing the passages it was built from, and marked stale the moment one of those passages' documents is revised or forgotten.

A fourth text arm matches facts recorded with remember and votes for their evidence passage ("facts as extra keys"); granularity: fact returns the facts themselves. as_of answers with what the knowledge base believed at a date: superseded revisions and replaced facts that were current then. Forgotten records are never returned, not even under as_of. Scope filters (namespaces, kinds, sources, library, version, tags, dates, minimum trust) are applied inside every arm's query, before ranking, so a filtered search never loses a result. Each result carries its provenance and a relevance band; with response_format: explain it also carries the per-arm ranks and contributions, the recency factor, and a per-query trace (which arms ran and why, what the scope excluded, where the list was cut). The terminal shows the same numbers: memors-mcp search " " --explain and memors-mcp explain " " memo://chunk/ .

Storage

One SQLite file per MEMORS_KB name, at ~/.memors-mcp/kb/ .db (or under $MEMORS_HOME/kb/ if set). Directories and files memors-mcp creates are restricted to the owner (0700/0600); a directory that already existed with wider permissions is not tightened. WAL mode is on, so two processes touching the same token (e.g. two concurrent Claude Code sessions) don't collide.

The name is explicit rather than inferred from the working directory — set MEMORS_KB per project (in the MCP server config, not the shell) and each project gets its own isolated knowledge base. Inside one file, namespaces are shelves that a search spans by default; separate files are the privacy boundary.

Setup

From a release. Download the archive for your platform from releases, unpack memors-mcp somewhere on your PATH, and run memors-mcp version. Archives exist for macOS and Linux (amd64, arm64) and Windows (amd64). The server is also listed in the MCP registry as io.github.kKEo/memors.

From source. Requires Go 1.26+.

git clone https://github.com/kKEo/memors

cd memors make build

This produces a single memors-mcp binary (CGO_ENABLED=0, ~30MB, no runtime dependencies).

With Claude Code:

claude mcp add memors --env MEMORS_KB=my-project -- /path/to/memors-mcp

Add it to Claude Code or Claude Desktop's MCP config:

{

"mcpServers": { "memors": { "command": "/path/to/memors-mcp", "env": { "MEMORS_KB": "my-project" } } } }

On first start memors-mcp downloads the default embedding model (granite-embedding-small-english-r2, Apache-2.0, about 140MB) into ~/.cache/memors-mcp/models and prints one line to stderr. Until the model is ready, search runs keyword-only and says so (degraded); documents written meanwhile get their vectors when the model arrives. To download ahead of time run memors-mcp model pull granite-small-r2. An interrupted download is detected and retried on the next run.

Commands

Running the binary with no arguments starts the MCP server on stdio. From the terminal:

• memors-mcp ingest [--ns --kind --uri --title --library --version --trust --context --embed=false] — add markdown documents; identical content is a no-op, changed content becomes a new revision
• memors-mcp search " " [--mode auto|hybrid|keyword|exact|semantic --ns --library --version --kind --limit --format table|json|md --explain --no-model] — search; --explain adds why each result ranked
• memors-mcp explain " " — the full explanation for one result
• memors-mcp log tail|calls|show |replay|prune — the opt-in query and call logs (MEMORS_QUERY_LOG=1); calls lists tool calls with timing and outcome; replay prints logged searches as unlabelled eval candidates (one JSON object per line) ready to be labelled and added to a corpus
• memors-mcp metrics [--json --since 24h] — knowledge-base gauges and per-tool call statistics from the opt-in log
• memors-mcp remember " " [--ns --about --valid-from --valid-to --supersedes --evidence --trust user|curated] — record a fact (CLI writes are trust user; curated must be typed)
• `memors-mcp forget --reason "