memo-mcp operator guide

This guide is for the people who install, configure, tune and run memo-mcp. It is written for readers comfortable with a terminal, SQLite, environment variables and Prometheus.

memo-mcp is a single, pure-Go binary. It exposes a knowledge base to AI agents over the Model Context Protocol (MCP) on stdio. It stores everything in one SQLite file per knowledge base, and it ships with a CLI and a read-only web UI over the same store. There is no daemon to deploy, no external database and no network dependency after a one-time model download.

What you will find here

Conventions

• Commands are shown as memo-mcp <command>. Every command reads the same environment (MEMO_HOME, MEMO_KB, …), so set it the same way the MCP client does.
• “Knowledge base” (KB) means one SQLite file. A “namespace” is a label inside one file.
• Addresses such as memo://chunk/42 identify records; every CLI command and the UI accept them.
• Defaults quoted here are the shipped values for v1.4. memo-mcp profiles show and memo-mcp --help print the live values for your build.

Deeper references

This guide states what to do and what it costs. The design documents explain why:

• Architecture: the 1.x contract, formulas and defaults.
• Schema: every table and column, trust transitions, time rules.
• Eval reports: measured quality and cost per release.

Looking for the non-technical introduction? See the user guide.

Part I: How it works

Four short chapters give you the mental model the rest of the guide assumes.

• System overview: one binary, three ways to run it, one file per knowledge base.
• Data model: layers, addresses, trust and the two clocks.
• The search pipeline: arms, fusion, cutoff, abstention and explain.
• Security model: what is exposed, what leaves the machine, who may change what.

System overview

One binary, three processes

memo-mcp is one statically linked Go binary (CGO_ENABLED=0, about 30 MB). The same binary runs in three roles, which are separate processes that share only the database file:

Each MCP client session usually starts its own server process. Several processes can hold the same file open at once; SQLite WAL mode and a 5-second busy timeout serialise writers.

 MCP client ── stdio ──▶ memo-mcp serve ─┐
 operator ── browser ──▶ memo-mcp ui ────┼──▶ $MEMO_HOME/kb/<name>.db  (SQLite, WAL)
 operator ── shell ────▶ memo-mcp <cmd> ─┘
                                          └─▶ ~/.cache/memo-mcp/models  (embedding models)

Inside the process

The ten MCP tools

* search writes only to the opt-in query log.

Resources mirror the addresses (memo://doc/{id}, memo://chunk/{id}, …), and memo://index returns a one-line-per-document index under 8 KB.

The one network call

The first time a process needs an embedding model that is not cached, it downloads the model files from Hugging Face into ~/.cache/memo-mcp/models. Nothing else in the default configuration opens an outbound connection. The optional Ollama executor and the --metrics-addr listener are explicit opt-ins, and both are loopback-only by default. See Air-gapped installs to avoid even the download.

Design reference: architecture §1–§4.

Data model

One knowledge base is one SQLite file. Inside it, knowledge is stored in layers. Each layer points down to the one it was derived from, so every answer can be traced to its source.

L5  pages       markdown an agent wrote from passages; cites them; marked stale when a source changes
L4  graph       entities, aliases, mentions (entity ↔ passage), merge candidates, typed edges
L3  facts       one-sentence claims with a validity window and an evidence passage
L2  chunks      passages of ~200 estimated tokens, indexed three ways (two FTS5 + vectors)
L1  documents   the text as ingested, one row per revision
L0  sources     where it came from: URI or file, library, version, hash, trust, origin
    bookkeeping namespaces, models, jobs, audit, query_log, call_log

Addresses

Document and fact ids are UUIDv7, which sort by time. Chunk ids are integers. A forgotten record’s address still resolves, to “forgotten on … because …”.

Namespaces and knowledge bases

• A namespace is a label on sources inside one file. A search spans all namespaces unless the request scopes it. Namespaces organise; they do not isolate.
• A knowledge base is a file selected by MEMO_KB. Files are the isolation and privacy boundary: no command or tool reads across files.

Trust and origin

Every source, and therefore every passage and fact, carries two labels:

Only a human can raise trust: memo-mcp trust promote, or an elicitation dialog the client shows for the promote tool. Tool calls may forget or supersede only agent records. Every transition is written to the audit table. See Trust administration.

Two clocks

• Recorded time: when the knowledge base learned something.
• Valid time: when a fact is true in the world (valid_from, valid_to).

as_of queries (“what did we believe on 1 March?”) filter on recorded time, and also on valid time for facts that have a window. Superseded revisions and replaced facts stay readable under as_of. Forgotten records are excluded in both views. See Facts and time.

Full column-by-column reference: schema.md.

The search pipeline

Every search, from the MCP tool, the CLI or the UI, runs the same pipeline in internal/retrieve:

scope filter ─▶ arms (parallel ranked lists) ─▶ fusion ─▶ recency ─▶ abstention
            ─▶ cutoff ─▶ limit ─▶ token budget ─▶ results + why + trace

1. Scope filter

Namespaces, kinds, sources, library, version, tags, dates and minimum trust are applied inside each arm’s SQL, before top-k. A filtered search therefore never loses a result to a candidate that was filtered out later. The live filter excludes superseded and forgotten records. Under as_of, it is replaced by “recorded on or before T and not superseded before T”.

2. Arms

Each arm returns up to fetch_depth candidates (100 by default).

3. Fusion

Weighted reciprocal rank fusion: a passage’s score is the sum over arms of weight / (k + rank), with k = 60. Default weights are semantic 0.5, keyword 0.5, exact 0.3, fact 0.4, entity 0.4 and graph 0.5. The minmax profile uses score fusion instead.

4. Recency

For kinds that age (note, conversation by default), the score is multiplied by floor + (1 − floor) · 0.5^(age_days / half_life), with floor 0.8 and half-life 90 days. Versioned documents and code do not age.

5. Abstention and relevance bands

A candidate whose only evidence is a semantic similarity below semantic_floor is dropped. If nothing survives, the response has zero results, a reason and a hint. That is a deliberate “not in the knowledge base”, not an error.

relevance is the best raw cosine for a result, interpreted against the model’s bands. For the default model, granite-small-r2, strong is 0.88, moderate 0.80 and weak 0.72, because unrelated text already scores about 0.63 under it. score orders one list and is not comparable across queries; relevance is.

6. Cutoff, limit and budget

The list ends at the first result, past min_results (3), whose score drops by more than cutoff_gap (half) from the previous one. It is then capped at limit (default 10, maximum 100), and then packed into max_tokens. The response always reports truncated, the count of ranked results that did not fit, and narrow_hint, the scope field that would shorten the list.

7. Explain and trace

With response_format: explain (MCP) or --explain (CLI), every result carries why: each arm’s rank, raw score and contribution, the fused and final score, relevance band, provenance and freshness. Every response carries a trace: arms run and why, candidates and latency per arm, filter counts, cutoff kind, budget use and degraded state. The UI renders the same structures, and a test asserts that the numbers are identical.

Degraded mode

If the embedding model is not available, because it is downloading, failed to load or has no vectors yet, search runs without the semantic arm. It sets degraded{flag, reason}, and the memo_search_degraded_total metric counts it. Writes made in that state queue their vectors. memo-mcp backfill or the next server start embeds them.

Tuning these constants: Profiles and constants. Full formulas: architecture §5.

Security model

memo-mcp is designed to run on one person’s machine with that person’s privileges. Its security properties come from being local, small and explicit.

Exposure

Outbound traffic

• Model download from Hugging Face on first use of a model, into ~/.cache/memo-mcp/models. Avoidable; see Air-gapped installs.
• Nothing else. The server never fetches URLs. Agents fetch content and pass the text to ingest. There is no telemetry: metrics are pull-only on loopback, logs go to stderr, and the call log is a table in your own file.

Data at rest

• One SQLite file per knowledge base, in plaintext. Directories are created 0700 and files 0600. A pre-existing directory with wider permissions is not tightened; check it.
• Use full-disk encryption if the file may hold sensitive material.
• forget --redact erases a record’s text. Plain forget hides the record but keeps the text in history.

Trust gates

• Trust is set by channel. An agent cannot write a record above agent, and cannot forget or supersede user or curated records.
• Raising trust requires a human: memo-mcp trust promote, or an MCP elicitation dialog that shows the excerpt, the source and the target level. A client configured to auto-accept elicitation removes this protection. In that case, treat user and curated as no stronger than agent.
• Every write and every trust change is recorded in the audit table with its actor and channel.

Prompt injection

Ingested content is data, but agents read it. memo-mcp limits the blast radius: content cannot raise its own trust, cannot delete human records and cannot trigger network calls. Results carry provenance and trust, so an agent, or a human reviewing its answer, can discount agent-trust web content.

The MCP host

Everything an agent writes or searches passes through the MCP host as tool input and output. The knowledge base is as private as that host. memo-mcp does not advertise the MCP logging capability; logs stay on stderr, which the host may display or store.

Part II: Install and deploy

memo-mcp has no installer and no service to register. Installing it means putting one binary on disk and telling an MCP client how to start it.

• Release archives: download, verify and place the binary.
• Build from source: reproducible pure-Go builds.
• Connecting MCP clients: Claude Code, Claude Desktop and any stdio client.
• Knowledge bases and MEMO_HOME: one file per KB, per-project setups.
• Upgrading and migrations: schema versions and what to run after an upgrade.
• Air-gapped installs: no network at runtime, not even the model download.

Release archives

Every tag vX.Y.Z publishes five archives and a checksum file on the releases page:

Each archive contains the binary, LICENSE, README.md and SKILL.md.

Install

VERSION=1.4.0
ARCH=darwin_arm64            # see the table above
curl -LO https://github.com/kKEo/memory-find/releases/download/v${VERSION}/memo-mcp_${VERSION}_${ARCH}.tar.gz
curl -LO https://github.com/kKEo/memory-find/releases/download/v${VERSION}/checksums.txt
shasum -a 256 -c --ignore-missing checksums.txt      # Linux: sha256sum -c --ignore-missing
tar xzf memo-mcp_${VERSION}_${ARCH}.tar.gz
install -m 0755 memo-mcp ~/.local/bin/memo-mcp       # any directory; note the absolute path
memo-mcp version

memo-mcp version prints the build version, the MCP protocol version (2026-07-28), the Go version and the model directory.

macOS Gatekeeper. A binary downloaded by a browser carries a quarantine attribute and is blocked on first run. Clear it with xattr -d com.apple.quarantine ~/.local/bin/memo-mcp, or download with curl, which does not set it.

MCP registry

The server is listed in the MCP registry as io.github.kKEo/memory-find. Its server.json points at the release archives with their checksums, so registry-aware clients can install it directly.

What the binary needs at runtime

• No shared libraries, no CGo, no interpreter.
• A writable MEMO_HOME, by default ~/.memo-mcp, and a writable ~/.cache/memo-mcp/models.
• About 200 MB of disk for the default model, plus the knowledge-base files. See Capacity and performance.
• Network access to huggingface.co once per model, unless you pre-seed the cache.

Build from source

Requirements: Go 1.26 or newer. No C toolchain is needed.

git clone https://github.com/kKEo/memory-find
cd memory-find
make build            # CGO_ENABLED=0, stripped, version from `git describe`
./memo-mcp version

make build runs:

CGO_ENABLED=0 go build -ldflags "-s -w -X main.version=$(VERSION)" -o memo-mcp ./cmd/memo-mcp/

Cross-compiling is plain Go, for example GOOS=linux GOARCH=arm64 CGO_ENABLED=0 go build ./cmd/memo-mcp.

Reproducing a release

make snapshot runs the same GoReleaser configuration as the release workflow without publishing. It writes the five archives and checksums.txt under dist/. Release builds use -trimpath and the commit timestamp, so rebuilding a tag gives the same binaries.

Development targets

Tests use a deterministic hash embedder and need no network or model download.

Connecting MCP clients

memo-mcp speaks MCP over stdio. A client starts the binary, writes JSON-RPC to its stdin and reads responses from its stdout. Configuration is passed through environment variables in the client’s server entry, not the shell. The client starts the process, so your shell profile does not apply.

Claude Code

# In a project directory: this project only, private to you (the default "local" scope)
claude mcp add memo --env MEMO_KB=my-project -- /absolute/path/to/memo-mcp

# Shared with the team through .mcp.json in the repository
claude mcp add memo --scope project --env MEMO_KB=my-project -- memo-mcp

# Available in every project
claude mcp add memo --scope user --env MEMO_KB=personal -- /absolute/path/to/memo-mcp

Add more variables with additional --env flags, for example --env MEMO_QUERY_LOG=1 --env MEMO_LOG_LEVEL=warn. Check the connection with /mcp inside Claude Code. Claude Code shows a stdio server’s stderr, so memo-mcp’s logs appear there.

Claude Desktop

Edit claude_desktop_config.json. On macOS it is in ~/Library/Application Support/Claude/; on Windows, in %APPDATA%\Claude\. Use absolute paths; ~ is not expanded.

{
  "mcpServers": {
    "memo": {
      "command": "/Users/you/.local/bin/memo-mcp",
      "env": {
        "MEMO_KB": "my-project",
        "MEMO_QUERY_LOG": "1"
      }
    }
  }
}

Restart Claude Desktop completely after editing.

Any other stdio client

The generic shape is the same everywhere: a command, optional args and an environment map.

The server implements protocol version 2026-07-28: stateless, with server/discover in place of initialize. It advertises tools and resources. It does not advertise logging or prompts. The promote tool uses elicitation when the client supports it, and otherwise returns the CLI command a human can run.

Teaching the agent

Ship SKILL.md from the release archive with the project, for example as a Claude Code skill, or paste it into the system prompt. It describes the search-then-read loop, scoping, writing facts and how to treat trust. For a static orientation, add the output of memo-mcp export --index to CLAUDE.md or AGENTS.md.

Verifying a connection without a client

MEMO_KB=my-project memo-mcp status      # read-only; fails if the file does not exist yet

A server that starts and immediately exits usually has an invalid MEMO_KB name or an unwritable MEMO_HOME. The reason is on stderr. See the troubleshooting runbook.

Knowledge bases and MEMO_HOME

Where files go

<name> comes from MEMO_KB, default default. It must match ^[A-Za-z0-9._-]{1,64}$ and must not be . or ... The model cache location is fixed and shared by every knowledge base and process of the same user.

One KB per project

Files are the isolation boundary, so the usual pattern is one MEMO_KB per project or client:

cd ~/src/payments  && claude mcp add memo --env MEMO_KB=payments  -- ~/.local/bin/memo-mcp
cd ~/src/analytics && claude mcp add memo --env MEMO_KB=analytics -- ~/.local/bin/memo-mcp

Claude Code’s default local scope ties each entry to its project directory, so the same server name memo opens a different file in each project.

Namespaces within a KB

Use namespaces for topics that may be searched together: docs, decisions, grpc. Writes default to the namespace default. Searches span all namespaces unless scoped. Namespace counts are visible in memo-mcp status and as the memo_kb_namespace_documents metric.

Separate homes

MEMO_HOME moves everything except the model cache. Use it to keep test data apart, run CI against a throwaway directory, or put knowledge bases on an encrypted volume:

MEMO_HOME=/Volumes/secure/memo MEMO_KB=client-a memo-mcp status

Sharing between processes

Several processes may open the same file. WAL mode lets readers proceed during writes, and writers wait up to 5 seconds for each other. Each process serialises its own writes over one connection. Do not put knowledge bases on network file systems such as NFS or SMB: SQLite’s locking is not reliable there.

Legacy variables

JOURNAL_TOKEN and JOURNAL_PATH are accepted for one more release as aliases of MEMO_KB and MEMO_HOME, with a deprecation warning. Files from the pre-1.0 journal are not opened or migrated.

Upgrading and migrations

Replacing the binary

Stop or let finish any running memo-mcp processes, replace the binary, and start the client again. Each MCP session starts its own process, so a new binary is picked up on the next session.

Schema versions

The schema version is SQLite’s user_version. Migrations are additive and run forward only.

memo-mcp status prints the version in its first line, and the metric memo_kb_schema_version exposes it.

What migrates and when

To migrate explicitly before anything else touches the file:

MEMO_KB=my-project memo-mcp migrate

Downgrades are not supported. Back up the file before upgrading across a schema version if you may need to roll back. See Backup and restore.

After upgrading to 1.1 or later from 1.0

Files written before the graph layer have no entity mentions. Populate them once:

memo-mcp graph rebuild            # all namespaces; or --ns <name>

Run it again after any release whose notes mention an extraction change.

After changing the embedding model

A model change is not a schema change. Vectors are stored per model, so the server embeds the missing ones in the background at start, and search reports degraded until it finishes. See Embedding models.

Release notes

Read the changelog and the eval report for the tag, docs/eval/vX.Y.Z.md, before upgrading. The 1.x contract keeps tool names and parameters, memo:// addresses, explain field names and the export format stable.

Air-gapped installs

After the binary is in place, the only network access memo-mcp ever makes is downloading an embedding model the first time it is needed. To run with no network at all, pre-seed the model cache.

Pre-seed the model cache

On a connected machine with the same memo-mcp version:

memo-mcp model pull granite-small-r2     # or the model you will set in MEMO_MODEL
ls ~/.cache/memo-mcp/models/
#   onnx-community_granite-embedding-small-english-r2-ONNX/
#   onnx-community_granite-embedding-small-english-r2-ONNX.ok

Copy both the directory and its .ok marker to the same path on the target machine, ~/.cache/memo-mcp/models/, for the user who runs memo-mcp. The marker records a completed, verified download. Without it, the files are treated as an interrupted download and fetched again.

Then check that the model loads offline:

memo-mcp model smoke granite-small-r2

For the optional reranker, also copy cross-encoder_ms-marco-MiniLM-L6-v2 and its marker.

Choosing a smaller model

See Embedding models for the full registry.

Running with no model at all

If no model is cached and the download fails, memo-mcp keeps working. Search runs on the keyword, exact and fact arms and reports degraded. New passages queue their vectors. When a model becomes available, memo-mcp backfill or the next server start embeds the backlog.

Part III: Configuration reference

memo-mcp is configured through environment variables, command flags and one optional file. There is no configuration file for the server itself.

• Environment variables: every variable, its default and its effect.
• Commands and flags: every command and flag.
• profiles.json: ranking-profile overrides.
• Files on disk: what memo-mcp creates and where.

Precedence. A flag beats its environment variable, which beats the built-in default. Examples: serve --metrics-addr over MEMO_METRICS_ADDR, search --profile over MEMO_PROFILE.

Environment variables

Set these in the MCP client’s server entry for the server, and in your shell for CLI commands. Both must agree on MEMO_HOME and MEMO_KB to see the same file.

Storage and selection

Retrieval

Logging and observability

Compaction executor (CLI only)

Deprecated

Not configurable

• The model cache, ~/.cache/memo-mcp/models, is fixed per user.
• SQLite pragmas are fixed: WAL, synchronous=NORMAL, busy_timeout=5000, foreign keys on.

Commands and flags

Running memo-mcp with no arguments is the same as memo-mcp serve. memo-mcp --help prints the summary. Flags may come before or after positional arguments.

Opens shows how each command opens the knowledge base:

• rw: creates and migrates the file.
• rw, no create: migrates, but refuses a missing file.
• ro: never writes, and refuses a missing or out-of-date file.

Server and UI

Writing

Reading and search

Graph and compaction

Maintenance

Observability

Models, profiles and evaluation

Exit codes and output

• 0 on success. 1 on a runtime error, printed as fatal: … on stderr. 2 on a usage error.
• Results go to stdout, and diagnostics and logs to stderr. --json output is stable enough to script against.
• The legacy flags --stats and --redownload-model still work for one more release, with a deprecation warning.

profiles.json

$MEMO_HOME/profiles.json changes ranking constants without rebuilding the binary. It is read at start-up by memo-mcp serve and memo-mcp ui. A missing file is fine. A malformed file stops the process with the path and the JSON error.

Note. In v1.4, the CLI search, explain and eval commands do not read profiles.json. They only see the built-in profiles. Test an override through the UI, which uses the same pipeline as the server, or by running the server.

Shape

The file is a JSON object mapping a profile name to the fields to change. Only fields that are present are applied.

• An existing name, such as default, is modified in place.
• A new name creates a profile. It starts from base, or from default when base is absent.

{
  "default": {
    "weights": { "exact": 0.4 }
  },
  "team-docs": {
    "base": "precise",
    "weights": { "semantic": 0.6, "keyword": 0.4 },
    "cutoff_gap": 0.4,
    "recency_kinds": [],
    "derivation": "Docs-heavy KB: favour meaning over wording; no recency."
  }
}

Select it with MEMO_PROFILE=team-docs in the server’s environment.

Fields

The reranker switch, its depth and graph routing are not overridable. Use the precise profile as a base to get reranking. A model’s own relevance bands, set in the model registry, take precedence over bands.

Checking an override

memo-mcp profiles show team-docs   # built-in profiles only in v1.4; see the note above
memo-mcp ui                        # search there with MEMO_PROFILE=team-docs set; the trace shows the profile

Before adopting an override, measure it. See Measuring a change.

Files on disk

A directory that already existed with wider permissions is not tightened.

What is inside the database

Every column is described in schema.md. The file is plain SQLite. You can inspect it with the sqlite3 shell, for example sqlite3 ~/.memo-mcp/kb/default.db '.tables'. Do not write to it by hand: triggers keep the indexes consistent only for writes made through memo-mcp.

Nothing else

memo-mcp writes no PID files, no lock files of its own, no logs to disk and no temporary files outside the model cache. Logs go to stderr. Redirect them yourself if you want them on disk.

Part IV: Retrieval tuning

The defaults are measured, not guessed. Each constant has a written derivation, and every release carries an eval report. Tune only when you have a reason, and measure before and after.

• Profiles and constants: the shipped profiles and what each constant does.
• Embedding models: the model registry, switching models, and what it costs.
• The reranker: an opt-in cross-encoder, and why it is off.
• Measuring a change: the eval harness, the query log, and reading explain.

Profiles and constants

A profile is a named set of ranking constants. The server and the UI use MEMO_PROFILE, default default. The CLI takes search --profile <name>. MCP clients cannot pick a profile per request in 1.x.

memo-mcp profiles show            # every profile, every constant, with its derivation
memo-mcp profiles show precise

Shipped profiles

The constants

Worked example: fusion

A passage at keyword rank 1 and semantic rank 2 under default:

keyword   0.5 / (60 + 1) = 0.008197
semantic  0.5 / (60 + 2) = 0.008065
fused                    = 0.016262

A keyword-only hit at rank 1 scores 0.008197, the same as a semantic-only hit at rank 1. Equal weights therefore let either arm put a result on the first page. That is the main reason the default is balanced.

Graph routing

The entity and graph arms run only when the query names two or more known entities, or one entity with relational phrasing (“depends on”, “related to”, …). The trace’s routing_reason says why they ran. Ablations show that routing them on every query hurts single-entity lookups. That is why routing is not a tunable constant.

Customising

Overrides go in profiles.json. The derivations behind each default are in architecture §5–§6 and the eval reports.

Embedding models

The semantic arm needs an embedding model. Models run in-process through a pure-Go ONNX backend (hugot / GoMLX), so no Python, no ONNX Runtime and no GPU are involved. potion is a static lookup table with no neural network at all.

memo-mcp model ls

* p50 query latency including query embedding, measured in docs/eval/v0.7.0.md. Writes cost more: about 0.6 s per passage with granite-small-r2 on this backend.

Each model has its own relevance bands in the registry. For granite-small-r2 they are 0.88 / 0.80 / 0.72, because unrelated text already scores about 0.63 under it.

How vectors are stored

Vectors are stored per passage per model in chunk_vecs(chunk_id, model_id, embedding). Several models can coexist in one file, so switching back is free once both are embedded. Each 384-dimension vector adds about 1.5 KB per passage.

Switching models

1. Pre-download and check, optionally:

   memo-mcp model pull potion
   memo-mcp model smoke potion
   

2. Embed the existing passages. This is optional, because the server does it in the background; doing it ahead avoids a degraded period:

   MEMO_KB=my-project memo-mcp reindex --model potion
   

   reindex is resumable. It only embeds passages that lack a vector for that model.
3. Record the default for the file, and set MEMO_MODEL in the MCP client’s server entry:

   MEMO_KB=my-project memo-mcp model use potion
   

4. Restart the client session. At start, the server runs backfill, then reindex for the current model, in the background. Until that finishes, search reports degraded and memo_kb_pending_embeddings{model="potion"} is above zero.

Downloads

• Source: Hugging Face, over HTTPS, into ~/.cache/memo-mcp/models/.
• A completed download writes a .ok marker. An interrupted one is detected and retried.
• memo-mcp model redownload <id> discards the cache for one model and fetches it again. Always pass the id: without one it re-downloads minilm.
• Metrics: memo_embed_model_downloads_total{model,outcome}, memo_embed_model_load_seconds, memo_embed_model_loaded.

Offline installs: Air-gapped installs.

The reranker

A cross-encoder can re-score the top results by reading the query and each passage together. memo-mcp ships one as an opt-in experiment:

Why it is off by default

It failed its promotion gate. In the bake-off it lowered nDCG@10 by about 0.2 and added 0.7 to 4 seconds per query:

The pure-Go pipeline cannot pass sentence-pair segment ids, so the model’s scores are compressed near zero. Details: spike S8.

If you try it

MEMO_RERANK=1 MEMO_PROFILE=precise memo-mcp ui

Watch memo_search_rerank_duration_seconds and the trace’s rerank{model, top_n, latency_ms}. If the reranker fails to load, the server continues without it. Search then reports degraded with reason reranker_failed.

Measuring a change

Every retrieval change in memo-mcp’s own history was measured against a labelled baseline. Use the same tools before you change a constant, a profile or a model.

1. The built-in benchmark

memo-mcp eval --models hash,granite-small-r2 --profiles default,precise,code --corpus all
memo-mcp eval --models potion --profiles all --format md > potion.md
memo-mcp eval --explain-failures            # one line per missed query, and why

It loads two labelled corpora into a throwaway knowledge base, runs every query under each model and profile combination, and prints quality next to cost:

hash is the deterministic test embedder and needs no download. Other model ids download real models. The corpora are the project’s own fixtures, so they tell you about relative effects (this profile against that one), not about your data.

2. Your own queries

1. Turn on the opt-in log in the server’s environment: MEMO_QUERY_LOG=1.
2. Use the system normally for a while.
3. Export what was asked:

   memo-mcp log replay --n 200 > candidates.jsonl
   

   Each line is an unlabelled eval query, with the query and the addresses that were returned.
4. Label the relevant addresses, then compare runs under different profiles in the UI or with memo-mcp search --profile <p> --format json.

3. Reading one result

memo-mcp explain "how do we rotate credentials"                  # ranking table for every hit
memo-mcp explain "how do we rotate credentials" memo://chunk/812  # the full why for one hit

What to look for:

The UI’s search page shows the same table, with links.

4. In production

After changing a profile or a model, watch these in Prometheus:

• memo_search_abstentions_total and memo_search_results: is the system answering less?
• memo_search_duration_seconds: did latency move?
• memo_search_cutoff_total{kind}: are lists ending differently?

See Prometheus: scrape, rules, alerts.

Part V: Knowledge lifecycle

How records enter, change, gain trust, get connected and summarised, and leave. Agents do most of this through MCP tools; an operator does the parts that need a human through the CLI.

• Ingest and revisions
• Facts and time
• Trust administration
• The graph index
• Compaction and pages
• Forget and redact

Every write in every chapter lands in the audit table: who (actor), through which channel (tool, cli, elicitation, worker), what operation, on which record. The same events increment memo_store_writes_total{op,channel}.

Ingest and revisions

The write path

1. Normalise line endings and whitespace, and hash the content (SHA-256).
2. Deduplicate. If the source’s current revision has the same hash, nothing happens and the result says dedup: true. If the content differs, a new revision is created. The previous revision is marked superseded and stays readable with as_of.
3. Chunk. The text is split by headings, then paragraphs, then sentences, then a hard split. The target is about 200 estimated tokens and the cap 400, clamped to the model’s limit, with about 40 tokens of overlap. Fenced code blocks are never split. Each passage gets a context header title > section path that the keyword index also sees.
4. Index. Both FTS5 indexes are filled by triggers inside the transaction. Entity mentions are extracted and linked.
5. Embed outside the transaction, in batches of 16. If no model is available, the passages are queued as a job, and backfill or the next server start embeds them. A write never reports success it did not get.
6. Audit: one row per write.

A source is identified by its URI, or by its file path for CLI ingests. Re-ingesting the same URI with changed content, or with a new version, creates a new revision of that source.

From the CLI

memo-mcp ingest ./docs --ns handbook --kind doc
memo-mcp ingest page.md --uri https://pkg.go.dev/google.golang.org/grpc \
  --library grpc/grpc-go --version v1.64.0 --context "gRPC-Go API docs for deadlines"
cat notes.md | memo-mcp ingest - --kind note --title "Standup 2026-10-03"
memo-mcp ingest ./big-folder --embed=false && memo-mcp backfill   # fast load, embed later

CLI writes are trust user, or curated with --trust curated. Origin defaults to web when --uri is set, and to user-said otherwise.

Kinds

Costs

For bulk loads, ingest with --embed=false, then run memo-mcp backfill, or let the server embed in the background. See Capacity and performance.

Observing it

memo_store_ingests_total{outcome=new|revision|dedup|error}, memo_store_ingest_duration_seconds, memo_store_chunks_written_total, memo_store_embed_batches_total{outcome}, and memo_kb_pending_embeddings{model} for the backlog.

Facts and time

A fact is one sentence with an optional subject list, an evidence passage and a validity window. Facts are searched by their own arm. A matching fact votes for its evidence passage.

memo-mcp remember "Production runs Postgres 16" --about postgres,production \
  --evidence memo://chunk/812 --valid-from 2026-06-01
memo-mcp facts ls --ns default
memo-mcp facts ls --as-of 2026-05-15 --history

Correcting facts

• Supersede: remember "<new>" --supersedes memo://fact/<old>. The old fact is invalidated, not deleted, and remains visible under as_of and --history. Agents may supersede only agent-trust facts.
• Expire: set --valid-to. memo-mcp lint lists facts past their window.
• Retire: memo-mcp forget memo://fact/<id> --reason "…".

Two clocks

as_of=T, available on the search and explore tools and on facts ls --as-of and explore --as-of in the CLI, shows what was recorded on or before T and not superseded before T. For facts with a window, it also applies valid time.

Conflicts

Two live facts about the same subject, with overlapping windows and differing statements, form a conflict. compact turns each conflict into a work item, together with the rule the server would apply: higher trust wins, then the newer fact. A human or agent settles it with submit <item> --keep memo://fact/<id>. When conflicting facts both match a search and score within 10% of each other, trust breaks the tie.

Trust administration

Commands

memo-mcp trust ls                                      # everything above agent trust
memo-mcp trust promote memo://doc/0199… --to curated
memo-mcp trust demote  memo://fact/0199… --to agent

The promote tool

When an agent calls promote:

1. If the client supports elicitation, it shows the human a dialog with the excerpt, the source and the target level. Accepting it applies the change through the elicitation channel. Declining or cancelling changes nothing.
2. If the client does not support elicitation, the tool returns the exact memo-mcp trust promote … command for a human to run.

Outcomes are counted in memo_mcp_elicitations_total{tool="promote",outcome=asked|accept|decline|cancel|unsupported}.

Warning. Hooks or settings that auto-accept elicitation dialogs defeat this gate. If you run such a client, do not rely on trust levels.

Auditing trust

Every change is an audit row, with op promote or demote and the channel it came through. Inspect it with sqlite3:

sqlite3 ~/.memo-mcp/kb/default.db \
  "SELECT datetime(ts/1000,'unixepoch'), actor, channel, op, target_uri FROM audit WHERE op IN ('promote','demote') ORDER BY ts DESC LIMIT 20"

The graph index

The graph layer is an index, not a source of truth. It records which entities each passage mentions. Search uses it to find passages that connect things the query names, and explore uses it to walk from one name.

Extraction and resolution

• Extraction runs on every ingest, using heuristics only: backticked spans, dotted, camel and snake identifiers, headings and capitalised names. Clients may also declare entities[] and relations[] when they ingest.
• Resolution is deterministic. The same normalised key means the same entity. A near key, with 3-gram Jaccard of at least 0.8, not too short and not differing only in a number, becomes a merge candidate for a human. Anything else is a new entity.

Commands

memo-mcp explore "Quorum Replication" --hops 2
memo-mcp graph merges                 # open candidates with their similarity
memo-mcp graph merge 17               # same thing: merge the names
memo-mcp graph reject 18              # different things: keep apart
memo-mcp graph rebuild --ns default   # re-extract mentions

Nothing is merged without a decision. Agents can propose decisions through compact and submit. Merge precision is gated at 0.95 or better in CI.

When to rebuild

• Once, after upgrading a file written before 1.1.
• After a release whose notes mention an extraction change.
• If memo-mcp lint reports many orphan entities after large deletions.

Rebuild keeps merge decisions. It re-reads every live passage, so on large knowledge bases run it when the system is quiet.

Runtime behaviour

The server keeps an in-memory mention graph per namespace. It is built on first use and reused while the namespace’s count of live mentions is unchanged; any ingest, revision or forget that changes that count triggers a rebuild on the next routed query. as_of queries always build a graph for that point in time and do not cache it. memo_graph_cache_total{event=hit|build|build_asof} and memo_graph_build_duration_seconds show how often this happens and what it costs.

Compaction and pages

The server never writes prose. Compaction is a queue of work items that an agent, or a person, completes. The server checks the result before storing it.

Work items

compact, through the tool or memo-mcp compact, scans a namespace and creates items:

Each item’s payload carries everything needed to do it: the passages, the facts and the previous page. No second call is needed.

Submitting

memo-mcp compact --ns default --kinds page,stale --json
memo-mcp submit 42 --content-file page.md --title "Quorum replication" --dry-run
memo-mcp submit 42 --content-file page.md --title "Quorum replication"
memo-mcp submit 43 --keep memo://fact/0199…
memo-mcp submit 44 --accept            # merge item
memo-mcp submit 45 --skip --reason "not worth a page"

Every page submission reports:

• diff: a line diff against the previous page.
• omission check: recorded facts about the subject whose content words are mostly absent from the page. Less than 75% coverage is flagged.
• corruption check: page sentences that share fewer than half of their content words with any source.

Pages are stored as is_inference = 1, with the passages they cite. They are searchable with granularity: page, and marked stale when a source changes. Raw rows are never modified.

Lint

memo-mcp lint --json

Reports contradictions, orphan entities, missing pages, stale pages and expired facts, with addresses. Lint changes nothing.

The optional Ollama executor

For unattended page writing from the terminal:

MEMO_OLLAMA_MODEL=qwen2.5:7b-instruct memo-mcp compact --kinds page --executor ollama          # dry run
MEMO_OLLAMA_MODEL=qwen2.5:7b-instruct memo-mcp compact --kinds page --executor ollama --apply  # submit

• The endpoint is MEMO_OLLAMA_URL, default http://127.0.0.1:11434. It must be loopback unless --allow-remote is passed.
• Use a non-thinking instruction model. Every page still goes through the same checks.
• No MCP code path can reach the executor.

Observing it

memo_kb_work_items_open, memo_kb_pages, memo_kb_pages_stale, memo_store_work_items_total{kind,event} and memo_store_pages_marked_stale_total.

Forget and redact

memo-mcp forget memo://doc/0199… --reason "superseded by the 2026 policy"
memo-mcp forget memo://fact/0199… --reason "wrong owner" --redact

• --reason is required and is shown to anyone who dereferences the address later.
• MCP tool calls may forget only agent-trust records. The CLI may forget anything.

Reclaiming disk space

SQLite does not shrink the file when rows are cleared. After large redactions, compact it while no process has the file open:

sqlite3 ~/.memo-mcp/kb/my-project.db 'VACUUM'

VACUUM also removes freed pages that might still hold redacted bytes. Run it after redacting secrets.

Part VI: Monitoring and observability

All observability in memo-mcp is local and pull-based. Metrics are served on loopback, logs go to stderr, and the optional call log is a table in your own file. Nothing is pushed anywhere, and there is no telemetry.

• Signals overview: what exists, where, and the per-process caveat.
• The metrics endpoint: enabling /metrics on the server and the UI.
• Metric catalogue: every series, its type, labels and meaning.
• Prometheus: scrape, rules, alerts: ready-to-adapt configuration.
• Logs: format, level, fields, and where they end up.
• Call and query logs: per-call history inside the knowledge base.

Signals overview

The per-process caveat

The MCP server, the UI and each CLI command are separate processes. Counters such as memo_mcp_tool_calls_total live in the memory of the process that served the calls:

• A server process exists only while its client session is open. Its counters start at zero with each session. Scrape it while it runs; Prometheus rate() handles the resets.
• The UI has its own counters, mostly memo_ui_*. Like every process, it also serves the memo_kb_* gauges, which are read from the file.
• History across sessions comes from the file: memo-mcp metrics (with MEMO_QUERY_LOG=1) and the memo_kb_* gauges.

Recommended setups

Naming

• Prefix memo_; counters end in _total; units are suffixes (_seconds, _bytes), and seconds are never milliseconds.
• Labels are bounded enums: tool names, outcomes, arms, models, namespaces. Never query text, ids or paths.
• OpenTelemetry mapping: replace _ with . and drop _total. For example, memo_mcp_tool_calls_total maps to memo.mcp.tool_calls.

The metrics endpoint

On the MCP server

memo-mcp serve --metrics-addr 127.0.0.1:9469
# or, in the client's server entry:  "env": { "MEMO_METRICS_ADDR": "127.0.0.1:9469" }

Claude Code example:

claude mcp add memo --env MEMO_KB=my-project --env MEMO_METRICS_ADDR=127.0.0.1:9469 -- /path/to/memo-mcp

At start, the server logs metrics listening url=http://127.0.0.1:9469/metrics.

Warning: one port, one process. The address is bound when the server starts. If a second session starts with the same entry while the first is running, for example two Claude Code windows on one project, the second fails with fatal: listen tcp 127.0.0.1:9469: bind: address already in use. Until this is relaxed:

• set --metrics-addr on one entry you use for a single long session;
• or give each knowledge base’s entry its own port;
• or leave it off and use the UI’s endpoint for file-level gauges plus the call log for per-call data.

On the UI

memo-mcp ui always serves GET /metrics, under the same guards as the rest of the UI: loopback, GET only, and the Host check. Pin the port to scrape it:

MEMO_KB=my-project memo-mcp ui --addr 127.0.0.1:9470 --no-model
curl -s http://127.0.0.1:9470/metrics | grep memo_kb_documents_live

--no-model keeps a long-running UI light. Its search is then keyword-only, which is fine for a metrics sidecar.

Checking it

curl -s http://127.0.0.1:9469/metrics | head -20
curl -s -o /dev/null -w '%{http_code}\n' -X POST http://127.0.0.1:9469/metrics   # 405
curl -s -o /dev/null -w '%{http_code}\n' -H 'Host: example.com' http://127.0.0.1:9469/metrics  # 403

memo_kb_* gauges are read from the database at scrape time and cached for 5 seconds, so frequent scrapes do not load the file. Read failures increment memo_store_status_scrape_errors_total.

Metric catalogue

Every series memo-mcp exposes, as of v1.4. Types: C counter, G gauge, H histogram. A histogram exposes _bucket{le}, _sum and _count. A family with no observations yet shows only its # HELP and # TYPE lines.

Bucket sets:

MCP server

Search

Store (write path)

Knowledge base (gauges read from the file, cached for 5 s)

All are gauges.

Embedding

Web UI

Runtime and build

Prometheus: scrape, rules, alerts

These are starting points written against the metric catalogue. Adapt the thresholds to your usage. The scrape configuration and both rule groups pass promtool check config and promtool check rules (Prometheus 3.15). Re-check them after you edit them.

Scrape configuration

scrape_configs:
  # Long-lived UI sidecar: knowledge-base gauges, always up.
  - job_name: memo-kb
    scrape_interval: 60s
    static_configs:
      - targets: ["127.0.0.1:9470"]
        labels: { kb: my-project }

  # MCP server: live tool and search metrics; only up while a client session runs.
  - job_name: memo-mcp
    scrape_interval: 15s
    static_configs:
      - targets: ["127.0.0.1:9469"]
        labels: { kb: my-project }

Prometheus must run on the same machine, because both endpoints are loopback-only. A Grafana Alloy or OpenTelemetry Collector agent on the machine can scrape them and forward the samples. That forwarding is your choice; memo-mcp itself never pushes.

Do not alert on up{job="memo-mcp"} == 0. The server exists only while a client session is open, so being down is normal. Alert on up{job="memo-kb"} instead, if you rely on the sidecar.

Recording rules

groups:
  - name: memo-recording
    interval: 1m
    rules:
      - record: memo:tool_calls:rate5m
        expr: sum by (kb, tool, outcome) (rate(memo_mcp_tool_calls_total[5m]))
      - record: memo:tool_error_ratio:rate5m
        expr: |
          sum by (kb) (rate(memo_mcp_tool_calls_total{outcome="error"}[5m]))
          /
          sum by (kb) (rate(memo_mcp_tool_calls_total[5m]))
      - record: memo:tool_latency_seconds:p95_5m
        expr: histogram_quantile(0.95, sum by (kb, tool, le) (rate(memo_mcp_tool_call_duration_seconds_bucket[5m])))
      - record: memo:search_latency_seconds:p95_5m
        expr: histogram_quantile(0.95, sum by (kb, le) (rate(memo_search_duration_seconds_bucket[5m])))
      - record: memo:search_abstain_ratio:rate15m
        expr: |
          sum by (kb) (rate(memo_search_total{outcome="abstain"}[15m]))
          /
          sum by (kb) (rate(memo_search_total[15m]))
      - record: memo:arm_latency_seconds:p95_5m
        expr: histogram_quantile(0.95, sum by (kb, arm, le) (rate(memo_search_arm_duration_seconds_bucket[5m])))

Alerts

groups:
  - name: memo-alerts
    rules:
      - alert: MemoToolErrorsHigh
        expr: memo:tool_error_ratio:rate5m > 0.05
        for: 10m
        labels: { severity: warning }
        annotations:
          summary: "memo-mcp {{ $labels.kb }}: more than 5% of tool calls fail"
          description: "Check memo_mcp_tool_errors_total by class and the server's stderr."

      - alert: MemoSearchSlow
        expr: memo:search_latency_seconds:p95_5m > 2
        for: 15m
        labels: { severity: warning }
        annotations:
          summary: "memo-mcp {{ $labels.kb }}: p95 search latency above 2 s"
          description: "Look at memo:arm_latency_seconds:p95_5m to find the slow arm."

      - alert: MemoSearchDegraded
        expr: sum by (kb, reason) (increase(memo_search_degraded_total[30m])) > 0
        for: 30m
        labels: { severity: warning }
        annotations:
          summary: "memo-mcp {{ $labels.kb }}: searches degraded ({{ $labels.reason }})"
          description: "The embedding model is missing or failing; search is keyword-only."

      - alert: MemoEmbeddingBacklog
        expr: max by (kb, model) (memo_kb_pending_embeddings) > 0
        for: 2h
        labels: { severity: info }
        annotations:
          summary: "{{ $value }} passages lack vectors for {{ $labels.model }}"
          description: "Run memo-mcp backfill, or start a server session to drain the backlog."

      - alert: MemoJobsFailed
        expr: max by (kb) (memo_kb_jobs_failed) > 0
        labels: { severity: warning }
        annotations:
          summary: "memo-mcp {{ $labels.kb }}: background jobs failed"

      - alert: MemoDatabaseGrowth
        expr: delta(memo_kb_db_size_bytes[1d]) > 500e6
        labels: { severity: info }
        annotations:
          summary: "memo-mcp {{ $labels.kb }}: knowledge base grew more than 500 MB in a day"

      - alert: MemoMergeQueueBacklog
        expr: max by (kb) (memo_kb_merge_review_open) > 50
        for: 1d
        labels: { severity: info }
        annotations:
          summary: "{{ $value }} merge candidates waiting for review (memo-mcp graph merges)"

      - alert: MemoKBSidecarDown
        expr: up{job="memo-kb"} == 0
        for: 10m
        labels: { severity: info }
        annotations:
          summary: "memo-mcp UI sidecar for {{ $labels.kb }} is not running"

Dashboard queries

Logs

memo-mcp logs with Go’s log/slog, to stderr only. In server mode, stdout carries the MCP JSON-RPC stream and is never written to by anything else; a test enforces this.

An unknown value falls back to the default and prints one warning.

What is logged

Logs never contain document text, fact statements, or forget reasons. Search log lines do not include the query text.

Example, with MEMO_LOG_FORMAT=json:

{"time":"2026-10-03T16:23:45.136+02:00","level":"INFO","msg":"search","mode":"auto","resolved":"semantic+keyword+fact","granularity":"chunk","outcome":"results","n_results":1,"truncated":0,"cutoff":"none","latency_ms":"461.8","profile":"default"}

latency_ms is a string with one decimal place.

Where logs end up

• Claude Code shows a stdio server’s stderr. Run claude --debug to see it live.

• Claude Desktop writes each server’s stderr to its own log file. On macOS this is ~/Library/Logs/Claude/mcp-server-memo.log.

• CLI commands print logs to your terminal’s stderr. Every memo-mcp search prints its INFO search line. Use MEMO_LOG_LEVEL=warn for quiet interactive use, or 2>/dev/null.

• To capture a server’s logs yourself, wrap the binary in a small script:

  #!/bin/sh
  exec /path/to/memo-mcp "$@" 2>>"$HOME/.memo-mcp/serve.log"
  

  Point the client’s command at the script. Rotate the file with your usual tool.

MCP logging capability

memo-mcp does not advertise the MCP logging capability. It is deprecated in protocol 2026-07-28, and stdio hosts already surface stderr. Do not expect log notifications over the protocol.

Call and query logs

With MEMO_QUERY_LOG=1 in a process’s environment, that process records:

• every search in query_log: arguments, the addresses returned, scores and the trace;
• every MCP tool call in call_log: client, tool, latency, outcome, error class, result count, tokens out and an argument summary.

Both tables live in the knowledge-base file, so they persist across sessions and processes. They are off by default.

What is stored, and what never is

The argument summary is an allowlist per tool, so a new argument is not logged until it is added explicitly. Search queries are stored verbatim. Treat the logs as sensitive as the questions people ask.

Reading the logs

memo-mcp log tail --n 20            # recent searches, then recent tool calls
memo-mcp log calls --n 50           # tool calls: time, client, tool, latency, results, tokens, args
memo-mcp log show 128               # one search with its full trace
memo-mcp log replay --n 200         # searches as JSON lines, for building eval queries
memo-mcp metrics --since 7d         # per-tool calls, errors, p50/p95/max latency; search aggregates
memo-mcp metrics --json | jq .

The UI’s /log page shows both tables.

Retention

The logs are not pruned automatically. Prune them on a schedule:

memo-mcp log prune                  # both logs: keep at most 10,000 rows and nothing older than 30 days

For example, with cron:

0 3 * * *  MEMO_KB=my-project /path/to/memo-mcp log prune

Querying with SQL

sqlite3 -header -column ~/.memo-mcp/kb/my-project.db "
  SELECT tool, COUNT(*) AS calls, SUM(ok = 0) AS errors, ROUND(AVG(latency_ms)) AS avg_ms
  FROM call_log WHERE ts > (strftime('%s','now','-1 day') * 1000)
  GROUP BY tool ORDER BY calls DESC"

ts is in Unix milliseconds. Column reference: schema §5.8.

Part VII: Operations

Day-two work: keeping data safe, checking integrity, planning capacity, getting data out, and fixing things.

• Backup and restore
• Integrity and repair
• Capacity and performance
• Exporting
• Troubleshooting runbook
• Release engineering

Backup and restore

A knowledge base is one SQLite file in WAL mode. Back it up with SQLite’s own tools, not with a plain file copy while processes have it open: a copy of the main file alone can miss committed transactions that are still in the -wal file.

While memo-mcp is running (safe online backup)

DB=~/.memo-mcp/kb/my-project.db
sqlite3 "$DB" ".backup '/backups/my-project-$(date +%F).db'"
# or, which also compacts the copy:
sqlite3 "$DB" "VACUUM INTO '/backups/my-project-$(date +%F).db'"

Both take a consistent snapshot while readers and writers continue. Writers wait at most memo-mcp’s 5-second busy timeout. sqlite3 creates the copy with your umask, typically 0644. Restrict it with chmod 600, because the backup holds everything the knowledge base holds.

While nothing is running

When no memo-mcp process has the file open, -wal and -shm are empty or absent, and copying <name>.db is enough. If a -wal file with content remains, copy it alongside, or run sqlite3 <name>.db 'PRAGMA wal_checkpoint(TRUNCATE)' first.

What to back up

Restore

1. Stop every process using the knowledge base: close the client sessions, the UI and running commands.
2. Remove the stale -wal and -shm files next to the target, if present.
3. Copy the backup to $MEMO_HOME/kb/<name>.db, then chmod 600 it.
4. Check it:

   MEMO_KB=<name> memo-mcp verify
   MEMO_KB=<name> memo-mcp status
   

A backup taken by an older binary is migrated forward on first write. A backup from a newer binary is refused by an older one.

A human-readable copy

memo-mcp export --md <dir> writes every live document as markdown with full provenance front matter. It is not a complete backup: there are no facts, history, graph or logs. But it is readable without memo-mcp, and re-ingesting it creates no new revisions. See Exporting.

Integrity and repair

verify

memo-mcp verify
memo-mcp verify --repair

The command prints ok: no problems found, or one problem: line per finding and one repaired: line per fix.

backfill and reindex

Both are resumable and safe to interrupt. The server runs both in the background at start.

SQLite-level checks

sqlite3 ~/.memo-mcp/kb/my-project.db 'PRAGMA integrity_check'   # expect: ok
sqlite3 ~/.memo-mcp/kb/my-project.db 'PRAGMA user_version'      # schema version

When to run what

Capacity and performance

Numbers measured on an Apple-silicon laptop with the shipped defaults. They are a guide to proportions, not a benchmark of your hardware.

Disk

Example: this project’s docs/ and articles/ folders (756 KB of markdown) became 101 documents and 818 passages, in a 3.6 MB file before vectors. Vectors for one 384-dimension model add about 1.2 MB more.

Time

Query embedding dominates search latency. Retrieval itself is milliseconds at these sizes. memo_search_arm_duration_seconds{arm} shows the split on your data.

Memory

A server process holds the embedding model in memory: a few hundred MB for granite-small-r2, less for potion. It also holds one in-memory mention graph per namespace it has searched with graph routing. go_memstats_sys_bytes shows the total.

Scaling guidance

• Everything is single-file SQLite with exact (brute-force) vector search. Tens of thousands of passages per knowledge base are comfortable. Beyond about 100,000 passages, watch memo_search_arm_duration_seconds{arm="semantic"}, and split knowledge bases by project.
• Bulk loads: ingest with --embed=false, then backfill. Or choose potion for fast, slightly weaker semantics.
• Several sessions on one file are fine. Writes are serialised and short; embedding happens outside the write lock.

Exporting

Markdown with provenance

memo-mcp export --md ./kb-export            # all namespaces
memo-mcp export --md ./kb-export --ns handbook

The layout is <namespace>/<kind>/<slug>-<shortid>.md, plus an _index.md per namespace. Each file has YAML front matter:

---
memo_uri: memo://doc/01a1017e-ec2c-777a-b64a-4b67d1ac8f97
title: Deploy checklist
kind: doc
namespace: default
revision: 1
content_hash: sha256:cf966c40e2f66a5d595ab316004e2875ff5f70aa51679c31669852fc121d7326
fetched_at: 2026-10-03T11:20:57Z
trust: user
origin: user-said
---

Empty fields are left out. source_uri, library, version and context appear when they are set.

The export opens as an Obsidian vault. Re-ingesting it produces zero new revisions, because the content hashes match. Facts, history, graph and logs are not included.

An index for agents

memo-mcp export --index > kb-index.md                        # ≤ 8 KB, one line per document
memo-mcp export --index --library grpc/grpc-go@v1.64.0 --max-bytes 4096

Each line has the title, address, kind, version and trust, and facts are summarised. Lines that do not fit the budget are counted in a footer. Paste the output into CLAUDE.md or AGENTS.md so an agent knows what exists before it searches. The same content is the MCP resource memo://index.

Raw data

The file is standard SQLite, so any tool can read it. For example, every live fact as CSV:

sqlite3 -csv -header ~/.memo-mcp/kb/my-project.db \
  "SELECT id, namespace, statement, trust, valid_from, valid_to FROM facts WHERE invalidated_at IS NULL AND deleted_at IS NULL"

Column names: schema.md.

Troubleshooting runbook

Start with these three commands. They answer most questions:

memo-mcp version                       # which build, protocol, model dir
MEMO_KB=<name> memo-mcp status         # file, schema, counts, model, jobs
MEMO_KB=<name> memo-mcp verify         # integrity

The client does not show memo’s tools

Search returns nothing, or too little

Search is degraded

Slow searches

1. memo-mcp explain "<q>", or the UI: see latency_ms_per_arm in the trace.
2. semantic is slow: query embedding dominates. Consider potion, or accept about 0.2 s.
3. graph is slow on its first call: the namespace graph is built once. Check memo_graph_cache_total{event="build"}. Repeated builds mean frequent writes.
4. Reranker on? MEMO_RERANK=1 adds 0.7–4 s. Turn it off.

Slow writes

Embedding dominates: about 0.6 s per passage with the default model. For bulk loads, use ingest --embed=false, then backfill.

“database is locked”

Another process held the write lock for more than 5 seconds. This is rare, because writes are short and embedding runs outside the lock. Look for a long graph rebuild, VACUUM or a manual sqlite3 session holding a transaction. Never put the file on a network file system.

Read-only commands fail with “run memo-mcp migrate”

The file is older than the binary. Run memo-mcp migrate, or any writing command, once.

The UI is unreachable

• Use the exact URL it printed. The Host header must match the bound address.
• It binds loopback only. From another machine, use an SSH tunnel (ssh -L 9470:127.0.0.1:9470 host) rather than --allow-remote. The UI has no authentication and shows everything in the knowledge base.

Promote never shows a dialog

The client does not support elicitation, so the tool result contains a memo-mcp trust promote … command for a human to run. memo_mcp_elicitations_total{outcome="unsupported"} counts these.

Reporting a bug

Include memo-mcp version, the status output, the stderr lines from MEMO_LOG_LEVEL=debug, and, for ranking issues, memo-mcp explain "<query>". Do not include document text you would not share.

Release engineering

For maintainers and for operators who build their own releases.

Pipelines

Gates a change must pass

• Eval gate: no single query may drop a rank band, and no category mean may fall by more than 0.02 against internal/eval/testdata/baseline.json.
• Tool-surface golden: internal/server/testdata/tools.golden.json must match. Tool names, parameters and descriptions are the 1.x contract.
• Docs check: every MEMO_* variable, command and metric in the code must appear in this guide.

Cutting a release

make check                       # lint + race tests
make eval                        # retrieval against the baseline
make snapshot                    # local GoReleaser dry run into dist/
# write docs/eval/vX.Y.Z.md and the CHANGELOG entry
git tag -a vX.Y.Z -m "vX.Y.Z" && git push origin vX.Y.Z

The release notes footer points at docs/eval/vX.Y.Z.md. Every tag should have one.

Versioning

Semantic versioning over the 1.x contract: tool names and parameters, memo:// addresses, explain field names and the export front matter. Schema migrations are additive and are listed in Upgrading and migrations.

Appendix

• Glossary: the technical terms used in this guide.
• Further reading: design documents, research and history.

Glossary

Further reading

All links point to the repository on GitHub.

Design

• Architecture: the 1.x contract, formulas, explain fields and observability.
• Schema: every table and column, trust transitions, time rules and migrations.
• Roadmap: phases, decisions, verification and the glossary.
• Research: the state of the art behind the design.

Measurements

• Eval reports: one per release.
• Spikes: the vector store, FTS5, embedding models, the graph, elicitation and the reranker.

Articles

One article per development phase, written for newcomers: articles/. Two of them matter most for operators:

• Measuring the server itself
• The embedder is the biggest lever

For agents

• SKILL.md: how an agent should use the tools.

Project

• Changelog
• Issues