Memors

What memors MCP server does

The memors MCP server provides a local knowledge base for agents and people working with the same stored information. Documents are saved as markdown with provenance, while atomic facts can include evidence and validity dates. Records receive stable memo:// addresses, so an agent can cite a document, passage, source, or fact in later responses.

It belongs in the 🧠 Knowledge & Memory category and is suited to private notes, technical material, conversations, and other content that should remain on the machine. A read-only loopback web UI exposes search, provenance, history, facts, entity neighborhoods, derived pages, status, lint results, and the query log.

How it works

The memors MCP server stores each knowledge base in a SQLite file. Search combines word-based FTS5 matching, whole-identifier matching for code-like queries, and locally computed semantic similarity. Results are fused into one ranked list, with scope filters applied before ranking. Search can also route questions about known entities through an entity index and mention graph. Fact and page granularity provide access to those record types directly.

Search results include provenance and relevance information. An explain response adds retrieval-arm ranks, score contributions, recency effects, exclusions, cutoff details, and the query trace. Weak semantic-only matches can be rejected, helping empty or unrelated questions return no noisy page of results.

The MCP prompt ask turns a conversation into a knowledge-base query and requires claims to cite memo:// addresses. The same addresses are available as MCP resources, including compact indexes for session startup.

Setup and configuration

Run memors-mcp serve for a stdio session, or memors-mcp serve --http when multiple clients or processes need to share a server. Each process opens the selected knowledge base. The database is stored at ~/.memors-mcp/kb/<name>.db, or beneath $MEMORS_HOME/kb/ when that location is configured. MEMORS_KB selects the knowledge-base name.

The first start downloads the configured embedding model from Hugging Face and caches it under ~/.cache/memors-mcp/models. The default model is granite-small-r2, a 384-dimensional IBM Granite embedding model running through a pure-Go ONNX backend. Available alternatives can be listed with memors-mcp model ls, including the static potion model.

Use memors-mcp ui to start the local read-only interface. The command-line interface also supports search explanations, exports, status checks, and other operator workflows. Exported indexes can be placed in agent instruction files such as AGENTS.md or CLAUDE.md.

Tools and capabilities

The server exposes tools for:

• Ingesting documents with revision handling and duplicate detection.
• Searching passages, pages, facts, identifiers, and semantic matches.
• Reading complete documents or selected passages under a token budget.
• Recording, superseding, and retiring facts or documents with evidence.
• Requesting human trust promotion without allowing the tool to perform it autonomously.
• Exploring entity relationships through mentions and graph evidence.
• Proposing compaction work and submitting pages or conflict decisions.
• Reporting namespaces, vectors, jobs, graph counts, and page counts.

Derived pages cite the passages used to create them. Submission supports a dry run and checks for facts omitted from the proposed page.

Limitations and notes

The memors MCP server does not fetch URLs; the agent must retrieve content and pass the text to ingestion. After the initial embedding-model download, the system makes no outbound network calls. Forgotten records are excluded from search, including historical as_of queries, although their addresses resolve to a retirement explanation.

Tool calls cannot directly promote trust. Clients that cannot show a human dialog receive a command for an operator to run instead. The web UI is read-only, and the server never writes pages during compaction; page creation requires a later submission step. The optional macOS MemoRS Tray application is a separate binary and is the only component built with cgo.