接入你的智能体
發布者自己的指令。不是 PlugMCP 端點。
用我們的金鑰與日誌託管一份副本。
mcpb https://github.com/kKEo/memory-find/releases/download/v1.5.0/memo-mcp_1.5.0_linux_amd64.tar.gzClaude Code 沒有本機指令的安裝連結。複製下方指令並在終端機中執行。
MEMO_KB=<value> MEMO_HOME=<value> MEMO_MODEL=<value> claude mcp add io.github.kkeo-memory-find -- mcpb https://github.com/kKEo/memory-find/releases/download/v1.5.0/memo-mcp_1.5.0_linux_amd64.tar.gz在終端機中執行。
{ "mcpServers": { "io.github.kkeo-memory-find": { "command": "mcpb", "args": [ "https://github.com/kKEo/memory-find/releases/download/v1.5.0/memo-mcp_1.5.0_linux_amd64.tar.gz" ], "env": { "MEMO_KB": "<value>", "MEMO_HOME": "<value>", "MEMO_MODEL": "<value>" } } }}claude_desktop_config.json
遠端 URL 還是本機指令？ 兩種安裝方式的差異
來自發布者
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.
Local, explainable knowledge base for AI agents: hybrid search with provenance over SQLite.
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.
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.
search runs up to three retrieval arms over the same pre-filtered set of live passages and fuses them:
useCallback, net/http, ERR_CONN_RESET). Added automatically when the query looks like code.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 "<q>" --explain and memors-mcp explain "<q>" memo://chunk/<n>.
One SQLite file per MEMORS_KB name, at ~/.memors-mcp/kb/<name>.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.
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.
Running the binary with no arguments starts the MCP server on stdio. From the terminal:
memors-mcp ingest <file|dir|-> [--ns --kind --uri --title --library --version --trust --context --embed=false] — add markdown documents; identical content is a no-op, changed content becomes a new revisionmemors-mcp search "<query>" [--mode auto|hybrid|keyword|exact|semantic --ns --library --version --kind --limit --format table|json|md --explain --no-model] — search; --explain adds why each result rankedmemors-mcp explain "<query>" <memo://chunk/n> — the full explanation for one resultmemors-mcp log tail|calls|show <id>|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 corpusmemors-mcp metrics [--json --since 24h] — knowledge-base gauges and per-tool call statistics from the opt-in logmemors-mcp remember "<fact>" [--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 <memo://...> --reason "<why>" [--redact] — retire a document or fact; the reason is kept and shownmemors-mcp facts ls [--ns --as-of YYYY-MM-DD --history] — list facts, or what was believed on a datememors-mcp trust ls | promote <uri> --to user|curated | demote <uri> --to agent|user — the human channel for trust; every change is auditedmemors-mcp explore <name> [--ns --hops 1|2 --as-of --json] — walk the graph index from one entity: its passages and the entities mentioned alongside it, with evidence addressesmemors-mcp graph merges [--state open|merged|rejected|all] | merge <id> | reject <id> | rebuild [--ns] — the review queue of near-duplicate entity names (nothing is merged without a human decision); rebuild re-extracts mentions for files written before the graph layer or after an extraction changememors-mcp compact [--ns --kinds page,stale,conflict,merge,duplicate --lint --json] — propose compaction work; --executor ollama [--apply] writes the page items with a local model (MEMORS_OLLAMA_URL, MEMORS_OLLAMA_MODEL; dry run unless --apply)memors-mcp submit <item-id> [--content-file page.md | --keep <memo://fact/..> | --accept|--reject | --skip] [--reason ..] [--dry-run] — the human side of a work itemmemors-mcp lint [--ns] — contradictions, orphan entities, missing or stale pages, expired facts; changes nothingmemors-mcp pages ls [--ns --stale] — list curated pagesmemors-mcp read <memo://doc/...> [--history] — print a document, chunk, source or fact with its provenance, or its revision chainmemors-mcp ls [--ns --kind --since --json] — list live documents, newest firstmemors-mcp export --md <dir> [--ns] — write markdown files with front-matter provenance (opens in Obsidian; re-importing yields no new revisions)memors-mcp export --index [--ns --library x@v --max-bytes 8192] — print a compact index (title, address, kind, version, trust per document; facts summarised) sized for AGENTS.md/CLAUDE.md; lines that do not fit are counted in a footermemors-mcp migrate — bring a file written by an older binary to the current schema (read-only commands such as status, ui and search refuse an out-of-date file and say this)memors-mcp verify [--repair] — check chunks, vectors and indexesmemors-mcp backfill — embed chunks whose vectors are pendingmemors-mcp status — print knowledge-base statistics (read-only; never creates a file)memors-mcp ui [--addr 127.0.0.1:0 --no-model] — the read-only web face: search with the explain table, documents and passages with provenance and history, the facts timeline, entity neighbourhoods, pages with their sources, status, lint, the query log and the eval report. Loopback only unless --allow-remote; no mutating route existsThe lab:
memors-mcp eval [--models hash,minilm,potion,granite-small-r2 --profiles default,all --corpus notes|kb|all --format table|md|json --explain-failures --rerank --agent-proxy] — load the fixture corpora into a throwaway knowledge base with each model, run the labelled queries under each profile, print quality (recall, MRR, nDCG, abstention) next to cost (latency, tokens). hash is the deterministic test embedder; other ids download real models.memors-mcp model ls | smoke <id>|--all | pull <id> | use <id> | redownload [<id>] — the embedding-model registry: list candidates with licences, prove which ones load under the pure-Go backend and how fast, download, or make one the knowledge base's default.memors-mcp reindex [--model <id>] — embed every passage that lacks a vector for a model ("re-embed, don't re-chunk"); vectors for several models coexist, so switching back is free.memors-mcp profiles show [<name>] — print every ranking constant of a profile with its derivation. Profiles: default, precise (deeper fetch, cross-encoder rerank when attached), recency, code, minmax (score fusion instead of rank fusion), and the ablations keyword-only, semantic-only. Overrides live in $MEMORS_HOME/profiles.json.memors-mcp version — print the build version, the MCP protocol version, the Go version and the model directorymemors-mcp model redownload — force a fresh model download, discarding any cached copy, and exitThe old spellings --stats and --redownload-model still work for one release and print a deprecation warning.
Everything stays on the machine. Metrics are pulled from a loopback address, logs go to the server's stderr, and the opt-in call log lives in your own SQLite file.
memors-mcp serve --metrics-addr 127.0.0.1:9469 (or MEMORS_METRICS_ADDR) exposes GET /metrics in the Prometheus text format: tool calls by tool and outcome with latency and result-size histograms, searches by mode and outcome with per-arm latency and candidate counts, abstentions, degraded searches, cutoff kinds, graph-cache hits, embedding latency by model and role, store writes by operation, plus gauges for every table count (memors_kb_documents_live, memors_kb_pages_stale, memors_kb_pending_embeddings{model}, …), Go runtime stats and memors_build_info. The endpoint refuses non-loopback addresses, answers only GET, and checks the Host header. The UI serves its own /metrics too. The registry is about 300 lines of standard library, so a dashboard can read every line it depends on; names follow Prometheus conventions and map one to one onto OpenTelemetry names if a bridge is ever wanted.log/slog on stderr, MEMORS_LOG_FORMAT=text|json, MEMORS_LOG_LEVEL. One line per tool call (tool, client, latency, outcome, error class, results, tokens) and one per search (mode, resolved arms, cutoff, degraded reason, latency). The MCP logging capability is not advertised: it is deprecated on the protocol version this server speaks, and Claude Code shows a stdio server's stderr anyway.MEMORS_QUERY_LOG=1 every tool call is recorded next to every search: memors-mcp log calls, memors-mcp log tail, the UI /log page. Arguments are summarised through an allowlist; written content and returned text are never stored.memors-mcp metrics [--json] [--since 24h] prints the table-count gauges and, from the opt-in log, per-tool calls, errors and p50/p95 latency plus search aggregates. Live counters are per process, so it says where to scrape them.MEMORS_LOG_FORMAT=json memors-mcp serve --metrics-addr 127.0.0.1:9469 2> memors.log
curl -s http://127.0.0.1:9469/metrics | grep memors_mcp_tool_calls_total
Claude Code ships with its own memory (Auto Memory, and the API-level file-based memory tool for custom agents). Those are good defaults and, for most people, probably the right choice.
memors-mcp exists as something different: a small, fully local, fully readable retrieval system you can inspect and measure, not a black box. Every ranking constant is a named profile field with a written derivation (memors-mcp profiles show), every result can explain its rank (response_format: explain, memors-mcp explain), every record carries where it came from and who vouched for it, and the eval harness in internal/eval/ records a baseline that every change is checked against query by query. If you want to understand why a memory system returns what it returns, or experiment with retrieval strategies on your own data, that's what this is for.
.github/workflows/docs.yml; make docs builds them locally.docs/architecture.md: layers, the write and read paths, the formulas, profiles, the explain contract, the address scheme.docs/schema.md: every table and column in plain words; trust transitions; what as_of can see.docs/eval/: one measured report per tag.articles/: one article per phase, written for beginners: why rebuild instead of migrate, designing the knowledge schema, search that explains itself, the embedder is the biggest lever, provenance, trust and time, designing tools for agents, shipping a pure-Go MCP server, graph as an index, not an oracle.articles/compaction-without-a-server-llm.md: how the agent writes the wiki and the server keeps it honest.articles/a-knowledge-base-you-can-read.md: the read-only web face and why its numbers are the agent's numbers.articles/measuring-the-server-itself.md: metrics and logs without telemetry.CHANGELOG.md.The articles, eval reports and spike notes were written before the project was renamed to memors and use the old names (memo-mcp, memo-tray, MEMO_*, ~/.memo-mcp); memo:// addresses did not change.
/metrics binds loopback and is pull-only, logs go to stderr, and the opt-in call log lives in your own SQLite file.promote uses MCP elicitation: the client shows a dialog with the excerpt, source and target level, and only an accepted dialog applies the change. A hook or setting that auto-accepts elicitation dialogs removes that protection; if you configure one, treat user and curated records as no more trusted than agent ones.degraded), and documents written in that state get their vectors when memors-mcp backfill or the next server start runs.1.0: the core knowledge base is complete and measured. What is stable, and what 1.x added (graph as an index, compaction and pages, a read-only web UI, local observability), is in docs/roadmap.md. Not planned: a server-side LLM, importing the v0 journal files. Contributions and issues welcome.
MIT — see LICENSE. Derived from obra/private-journal-mcp, also MIT.
Local, explainable knowledge base for AI agents: hybrid search with provenance over SQLite.
{ "mcpServers": { "io.github.kkeo-memory-find": { "command": "mcpb", "args": [ "https://github.com/kKEo/memory-find/releases/download/v1.5.0/memo-mcp_1.5.0_linux_amd64.tar.gz" ], "env": { "MEMO_KB": "<value>", "MEMO_HOME": "<value>", "MEMO_MODEL": "<value>" } } }}工具
尚無工具清單。遠端伺服器會在首次健康檢查後取得工具清單。
常見問題
在本頁複製適用於 Cursor、Claude Desktop、Claude Code 或 VS Code 的 stdio 設定。它使用發布者的安裝方式，而不是 PlugMCP 代理伺服器。
發布者列出了以下環境變數：MEMO_KB, MEMO_HOME, MEMO_MODEL。
Memory Find 透過 stdio 在本機執行。
上次檢查時間：2026-11-09。 Local, explainable knowledge base for AI agents: hybrid search with provenance over SQLite.