memors-mcp operator guide

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

memors-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 memors-mcp <command>. Every command reads the same environment (MEMORS_HOME, MEMORS_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. memors-mcp profiles show and memors-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

memors-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. Alternatively, memors-mcp serve --http runs one long-lived server that many clients share over HTTP; an operator, a service manager or MemoRS Tray starts it. See One shared server over HTTP. Several processes can hold the same file open at once; SQLite WAL mode and a 5-second busy timeout serialise writers.

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/memors-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.

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 MEMORS_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: memors-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. Valid time is stored and shown with each fact, and memors-mcp lint lists facts whose window has passed. 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:

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 memors_search_degraded_total metric counts it. Writes made in that state queue their vectors. memors-mcp backfill or the next server start embeds them.

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

Security model

memors-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/memors-mcp/models. Avoidable; see Air-gapped installs.
• MemoRS Tray, the optional macOS app, contacts GitHub (api.github.com and the release download hosts) only while its setup assistant shows the Install step, and installs only a download whose SHA-256 matches the release’s checksums.txt.
• 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.
• A running serve --http advertises itself in $MEMORS_HOME/run/serve-<pid>.json (0600): its URL, auth mode and the path of the token file, never the token itself.
• 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: memors-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. memors-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. memors-mcp does not advertise the MCP logging capability; logs stay on stderr, which the host may display or store.

Part II: Install and deploy

memors-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 MEMORS_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.

The optional macOS menu-bar app comes as one more asset, memors-tray_X.Y.Z_darwin_universal.zip, with its own .sha256 file; see MemoRS Tray.

Install

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

memors-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/memors-mcp, or download with curl, which does not set it.

MCP registry

The server is listed in the MCP registry as io.github.kKEo/memors. 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. (This is the memors-mcp binary. MemoRS Tray, the separate macOS app, links AppKit and WebKit.)
• A writable MEMORS_HOME, by default ~/.memors-mcp, and a writable ~/.cache/memors-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 for memors-mcp. The optional macOS menu-bar app (MemoRS Tray) lives in its own module under tray/ and needs the Xcode command-line tools: make tray, make tray-app.

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

make build runs:

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

Cross-compiling is plain Go, for example GOOS=linux GOARCH=arm64 CGO_ENABLED=0 go build ./cmd/memors-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

memors-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 memors --env MEMORS_KB=my-project -- /absolute/path/to/memors-mcp

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

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

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

One shared server over HTTP

Instead of one process per session, run a single long-lived server and point every client at its URL:

MEMORS_KB=my-project memors-mcp serve --http 127.0.0.1:8765
claude mcp add --transport http memors http://127.0.0.1:8765/mcp

The same port serves the web UI at http://127.0.0.1:8765/. In this mode the UI also has a Live page with what only the running process knows: active clients, calls in flight, background backfill, and tool and ingest latency since start. The standalone memors-mcp ui reads the knowledge-base file alone and has no Live page.

Start the server yourself (a terminal, launchd or a systemd --user unit), or from the macOS menu-bar app, MemoRS Tray. Clients do not start it, and its logs go to its own stderr.

For companion apps

Two routes exist for local tools such as MemoRS Tray rather than for people:

• GET /live.json: the Live page’s client list as JSON (schema 1): the server’s instance id, pid, version, knowledge base and model, every client with its name, version, open and stream state, call count and last activity, and the calls in flight. Sessions appear only as a short hashed handle; the session id itself grants access to the session, so it is never shown. New fields may be added; anything else changes schema.
• POST /login-link?next=/live (token mode only): returns a single-use login link, {"url": "/login?code=…&next=%2Flive", "expires_at": …}, for an app that holds the token and opens the UI in a window of its own. Only the Authorization: Bearer header is accepted, not a browser session.

Authentication

One shared secret, the bearer token, protects /mcp, the UI and /metrics. It lives in <MEMORS_HOME>/http-token (mode 0600, created on first use); memors-mcp http-token prints it.

The server refuses any setup that would expose the knowledge base without authentication or send the token unencrypted over the network.

Claude Code sends the token as a header:

claude mcp add --transport http memors https://box.example:8765/mcp \
  --header "Authorization: Bearer $(memors-mcp http-token)"

$(memors-mcp http-token) is expanded once, when you run the command, and the token is stored in Claude Code’s configuration. After memors-mcp http-token --rotate, restart the server and run claude mcp remove memors and the add line again.

Prometheus uses the same header (authorization: { credentials_file: … } in the scrape config).

Browsers cannot send the header. The server prints a login link at startup, …/login?code=…, that works once, within 15 minutes. Opening it sets a session cookie (HttpOnly, SameSite=Strict, Secure over HTTPS, 30 days). Without the link, /login asks for the token. /logout ends the session. Rotating the token logs every browser out. The link appears in the server’s log, so treat that log as sensitive while the link is valid.

A full remote example with a certificate:

memors-mcp serve --http 0.0.0.0:8765 --allow-remote \
  --tls-cert /etc/memors/cert.pem --tls-key /etc/memors/key.pem \
  --public-url https://box.example:8765

mTLS needs a client certificate in every client. Browsers and Prometheus support that. Check your MCP client’s documentation before relying on mTLS alone; with the token on as well (the default), a client that cannot present a certificate cannot connect at all.

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": {
    "memors": {
      "command": "/Users/you/.local/bin/memors-mcp",
      "env": {
        "MEMORS_KB": "my-project",
        "MEMORS_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, resources and one prompt, ask, which turns the conversation into a chat answered from the knowledge base with memo:// citations. The client’s model writes the answers; the prompt only tells it how to search, read and cite. Its one optional argument is a namespace, checked against the knowledge base. The questions follow in the conversation: Claude Code passes the words after a prompt command as the prompt’s arguments, one word each, in order, so a question cannot be an argument. In Claude Code the command is /mcp__<server name>__ask [namespace]. The server does not advertise logging. 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 memors-mcp export --index to CLAUDE.md or AGENTS.md.

Verifying a connection without a client

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

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

MemoRS Tray (macOS menu bar)

MemoRS Tray is an optional macOS companion for shared HTTP servers. It lists the running memors-mcp serve --http servers and their connected clients, opens a server’s Live page in a native window, and starts and stops servers. It is a separate binary in its own Go module (tray/). It is the only part of the project built with cgo (AppKit and WebKit); the memors-mcp binary stays pure Go.

User-facing behaviour is described in the user guide (The menu-bar app). This page covers how it works and what to configure.

Install

Release assets: memors-tray_X.Y.Z_darwin_universal.zip and its .sha256, next to the server archives. The zip holds MemoRS Tray.app: one universal binary (arm64 and x86-64), macOS 12 or newer, ad-hoc signed and not notarized. On first open, allow it under System Settings › Privacy & Security, or remove the quarantine attribute:

shasum -a 256 -c memors-tray_X.Y.Z_darwin_universal.zip.sha256
ditto -x -k memors-tray_X.Y.Z_darwin_universal.zip /Applications
xattr -dr com.apple.quarantine "/Applications/MemoRS Tray.app"

From source (needs the Xcode command-line tools):

make tray        # tray/memors-tray, for this machine
make tray-app    # tray/dist/MemoRS Tray.app and the release zip
make tray-test   # vet and tests of the tray module

Installing memors-mcp from the app

The setup assistant installs memors-mcp on demand. On the Install step it asks the GitHub API for the latest release (api.github.com/repos/kKEo/memors/releases/latest). MemoRS Tray makes no other outbound connection, and makes this one only when you open that step.

Installing works like this:

1. Download checksums.txt and memors-mcp_<version>_darwin_<arch>.tar.gz for this Mac. Only https is accepted, redirects included.
2. Compare the archive’s SHA-256 with its line in checksums.txt. A release without that line is refused.
3. Extract only the regular file memors-mcp from the archive, into a temporary file in the target folder (default ~/.local/bin).
4. Run memors-mcp version on it, and only then rename it over <folder>/memors-mcp. A failure at any step leaves the previous binary untouched.
5. Set memors_binary in tray.json to the new file.

The checksum proves the download is the file the release lists. Like the manual install, it does not protect against a compromised release. Servers that are running keep the old binary until they restart; the last step offers to restart the ones MemoRS Tray started.

Settings window and launch at login

The settings window and the setup assistant are pages that MemoRS Tray serves itself:

• They are served on 127.0.0.1:<random port> and shown in its own WKWebView window.
• A window enters through a link carrying a per-process secret, passed in process. It then holds an HttpOnly, SameSite=Strict cookie.
• Requests with any other Host header, or without the cookie, are refused.
• Form posts must be same-origin.
• Saving checks that tray.json has not changed since the form was opened, and validates everything before writing.

Open MemoRS Tray when you log in writes ~/Library/LaunchAgents/io.github.kkeo.memors-tray.plist (RunAtLoad, the app’s own executable) and turning it off removes the file. It takes effect at the next login. MemoRS Tray refuses while macOS runs it from a temporary copy (App Translocation: move it to Applications first). At each start it updates the path if the app has moved. If memo-tray’s old agent (io.github.kkeo.memo-tray.plist) is still there, MemoRS Tray replaces it with its own, so the setting carries over.

How it finds servers

Every serve --http writes a run file, $MEMORS_HOME/run/serve-<pid>.json (see Files on disk). MemoRS Tray scans that directory every 2 seconds and whenever its menu opens. It ignores the directory if it is not owned by you or is writable by others. It deletes a run file only when the process is gone, or when the pid now belongs to another program: the name is not memors-mcp, or it started after the file was written.

For each server it polls GET /live.json (see For companion apps). In token mode it reads the token from the token_file named in the run file, at every poll, so a rotated token is picked up after the server restarts. It sends the token only to loopback HTTP or to HTTPS, through no proxy, and never follows a redirect. Servers that require a client certificate (mTLS) are listed but cannot be polled or opened in a window.

Only servers on this machine and in this MEMORS_HOME are discovered. MemoRS Tray resolves MEMORS_HOME like memors-mcp; apps launched from Finder see no shell variables, so that means ~/.memors-mcp.

Starting and stopping

A server MemoRS Tray starts runs as:

memors-mcp serve --http 127.0.0.1:<port> [--auth token]

It runs with MEMORS_HOME and MEMORS_KB set. stdin is /dev/null, and stdout and stderr go to $MEMORS_HOME/logs/serve-<kb>.log (0600, moved to .1 above 5 MB). Variables that would change where or how it serves are removed from its environment: MEMORS_HTTP_*, MEMORS_TLS_*, MEMORS_PUBLIC_URL and MEMORS_METRICS_ADDR. Stop sends SIGTERM and kills the process if it is still running after 10 seconds.

A server started elsewhere gets SIGTERM only, and only after MemoRS Tray has checked that the pid is still that server: a memors-mcp process that started before its run file was written, and, if it answers, one whose /live.json reports the same pid and instance id.

MemoRS Tray starts loopback servers only. For remote or proxied servers, keep using a service manager.

tray.json

$MEMORS_HOME/tray.json (0600) is optional. The settings window edits it. MemoRS Tray also rereads it when you change it by hand, and adds an entry the first time you start a knowledge base from the menu. Every write inside MemoRS Tray goes through one lock, from read to write, so the menu and the settings pages never undo each other.

The stats window

The window is a WKWebView in MemoRS Tray’s own process:

• It logs in with a single-use link from POST /login-link, so the token never reaches the web view, a URL or the process arguments.
• It uses a private, non-persistent website data store. The session cookie is never written to disk.
• JavaScript is off; memors-mcp’s UI does not use any.
• It shows only the server’s own origin. A clicked link elsewhere opens in the default browser; any other navigation (redirects off the server, file:, custom schemes) is refused.

Open in Browser passes a single-use login link to the browser through open(1). Like the link the server prints at startup, it is visible to other processes for an instant and becomes useless once it is used.

Files

Knowledge bases and MEMORS_HOME

Where files go

<name> comes from MEMORS_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 MEMORS_KB per project or client:

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

Claude Code’s default local scope ties each entry to its project directory, so the same server name memors 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 memors-mcp status and as the memors_kb_namespace_documents metric.

Separate homes

MEMORS_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:

MEMORS_HOME=/Volumes/secure/memors MEMORS_KB=client-a memors-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.

Older layouts

Before the rename to memors-mcp the base directory was ~/.memo-mcp, and memors-mcp does not look there. Move it once with mv ~/.memo-mcp ~/.memors-mcp (see Upgrading from memo-mcp); the files inside need no conversion. Files from the pre-1.0 journal are not opened or migrated.

Upgrading and migrations

Replacing the binary

Stop or let finish any running memors-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.

Upgrading from memo-mcp

memo-mcp was renamed to memors-mcp, and memo-tray to MemoRS Tray. Knowledge-base files, memo:// addresses, tool names and the export format are unchanged. The names around them changed, and the old ones are not read any more:

1. Quit memo-tray and stop every memo-mcp serve process.
2. Move the data: mv ~/.memo-mcp ~/.memors-mcp. If you set MEMO_HOME, keep that directory and set MEMORS_HOME instead. Optionally mv ~/.cache/memo-mcp ~/.cache/memors-mcp keeps the downloaded models; otherwise they download again.
3. Install memors-mcp (From a release) and delete the old memo-mcp binary.
4. In every client config, point the command at memors-mcp and rename MEMO_* variables to MEMORS_*. The server key (memo) may stay; these guides now use memors (Connecting clients).
5. If tray.json sets memo_binary, rename the key to memors_binary, or delete it and let MemoRS Tray find memors-mcp by itself.
6. Install MemoRS Tray by hand, as described on its page: memo-tray cannot update itself to the renamed release archives. Delete memo-tray.app. “Open at login” carries over on the first start.
7. Rename memo_ to memors_ in Prometheus recording rules, alerts and dashboards (Prometheus).
8. Browsers log in to the web UI once more: the session cookie was renamed.

memors-mcp status then shows the same knowledge base as before.

Schema versions

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

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

What migrates and when

To migrate explicitly before anything else touches the file:

MEMORS_KB=my-project memors-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:

memors-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 memors-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 memors-mcp version:

memors-mcp model pull granite-small-r2     # or the model you will set in MEMORS_MODEL
ls ~/.cache/memors-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/memors-mcp/models/, for the user who runs memors-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:

memors-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, memors-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, memors-mcp backfill or the next server start embeds the backlog.

Part III: Configuration reference

memors-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 memors-mcp creates and where.

Precedence. A flag beats its environment variable, which beats the built-in default. Examples: serve --metrics-addr over MEMORS_METRICS_ADDR, search --profile over MEMORS_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 MEMORS_HOME and MEMORS_KB to see the same file.

Storage and selection

Retrieval

Logging and observability

Compaction executor (CLI only)

Renamed

Before the rename to memors-mcp every variable here was spelled MEMO_* (for example MEMO_KB). The old names are not read any more: rename them in client configs and service files, as described in Upgrading from memo-mcp. The JOURNAL_TOKEN and JOURNAL_PATH aliases are gone as well.

Not configurable

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

Commands and flags

Running memors-mcp with no arguments is the same as memors-mcp serve. memors-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

$MEMORS_HOME/profiles.json changes ranking constants without rebuilding the binary. It is read at start-up by memors-mcp serve and memors-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 MEMORS_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

memors-mcp profiles show team-docs   # built-in profiles only in v1.4; see the note above
memors-mcp ui                        # search there with MEMORS_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 ~/.memors-mcp/kb/default.db '.tables'. Do not write to it by hand: triggers keep the indexes consistent only for writes made through memors-mcp.

Nothing else

Apart from the run files above, memors-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 MEMORS_PROFILE, default default. The CLI takes search --profile <name>. MCP clients cannot pick a profile per request in 1.x.

memors-mcp profiles show            # every profile, every constant, with its derivation
memors-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.

memors-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:

   memors-mcp model pull potion
   memors-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:

   MEMORS_KB=my-project memors-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 MEMORS_MODEL in the MCP client’s server entry:

   MEMORS_KB=my-project memors-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 memors_kb_pending_embeddings{model="potion"} is above zero.

Downloads

• Source: Hugging Face, over HTTPS, into ~/.cache/memors-mcp/models/.
• A completed download writes a .ok marker. An interrupted one is detected and retried.
• memors-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: memors_embed_model_downloads_total{model,outcome}, memors_embed_model_load_seconds, memors_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. memors-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

MEMORS_RERANK=1 MEMORS_PROFILE=precise memors-mcp ui

Watch memors_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 memors-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

memors-mcp eval --models hash,granite-small-r2 --profiles default,precise,code --corpus all
memors-mcp eval --models potion --profiles all --format md > potion.md
memors-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: MEMORS_QUERY_LOG=1.
2. Use the system normally for a while.
3. Export what was asked:

   memors-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 memors-mcp search --profile <p> --format json.

3. Reading one result

memors-mcp explain "how do we rotate credentials"                  # ranking table for every hit
memors-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:

• memors_search_abstentions_total and memors_search_results: is the system answering less?
• memors_search_duration_seconds: did latency move?
• memors_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 memors_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. Audit: one row per write, in the same transaction.
6. 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.

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

memors-mcp ingest ./docs --ns handbook --kind doc
memors-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 | memors-mcp ingest - --kind note --title "Standup 2026-10-03"
memors-mcp ingest ./big-folder --embed=false && memors-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 memors-mcp backfill, or let the server embed in the background. See Capacity and performance.

Observing it

memors_store_ingests_total{outcome=new|revision|dedup|error}, memors_store_ingest_duration_seconds, memors_store_chunks_written_total, memors_store_embed_batches_total{outcome}, and memors_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.

memors-mcp remember "Production runs Postgres 16" --about postgres,production \
  --evidence memo://chunk/812 --valid-from 2026-06-01
memors-mcp facts ls --ns default
memors-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. memors-mcp lint lists facts past their window.
• Retire: memors-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. Valid time does not filter: it is stored and shown with each fact, and memors-mcp lint lists facts whose valid_to has passed.

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

memors-mcp trust ls                                      # everything above agent trust
memors-mcp trust promote memo://doc/0199… --to curated
memors-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 memors-mcp trust promote … command for a human to run.

Outcomes are counted in memors_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 ~/.memors-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

memors-mcp explore "Quorum Replication" --hops 2
memors-mcp graph merges                 # open candidates with their similarity
memors-mcp graph merge 17               # same thing: merge the names
memors-mcp graph reject 18              # different things: keep apart
memors-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 memors-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. memors_graph_cache_total{event=hit|build|build_asof} and memors_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 memors-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

memors-mcp compact --ns default --kinds page,stale --json
memors-mcp submit 42 --content-file page.md --title "Quorum replication" --dry-run
memors-mcp submit 42 --content-file page.md --title "Quorum replication"
memors-mcp submit 43 --keep memo://fact/0199…
memors-mcp submit 44 --accept            # merge item
memors-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

memors-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:

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

• The endpoint is MEMORS_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

memors_kb_work_items_open, memors_kb_pages, memors_kb_pages_stale, memors_store_work_items_total{kind,event} and memors_store_pages_marked_stale_total.

Forget and redact

memors-mcp forget memo://doc/0199… --reason "superseded by the 2026 policy"
memors-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 ~/.memors-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 memors-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 memors_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 memors_ui_*. Like every process, it also serves the memors_kb_* gauges, which are read from the file.
• History across sessions comes from the file: memors-mcp metrics (with MEMORS_QUERY_LOG=1) and the memors_kb_* gauges.

Recommended setups

Naming

• Prefix memors_; 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, memors_mcp_tool_calls_total maps to memors.mcp.tool_calls.

The metrics endpoint

On the MCP server

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

Claude Code example:

claude mcp add memors --env MEMORS_KB=my-project --env MEMORS_METRICS_ADDR=127.0.0.1:9469 -- /path/to/memors-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

memors-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:

MEMORS_KB=my-project memors-mcp ui --addr 127.0.0.1:9470 --no-model
curl -s http://127.0.0.1:9470/metrics | grep memors_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

memors_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 memors_store_status_scrape_errors_total.

Metric catalogue

Every series memors-mcp exposes on master: v1.4 plus the unreleased section of the changelog. 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

tool is one of the ten tool names, or unknown when a client calls a tool the server does not have; such a call has outcome="error". Clients cannot add label values.

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: memors-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: memors-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; memors-mcp itself never pushes.

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

Recording rules

groups:
  - name: memors-recording
    interval: 1m
    rules:
      - record: memors:tool_calls:rate5m
        expr: sum by (kb, tool, outcome) (rate(memors_mcp_tool_calls_total[5m]))
      - record: memors:tool_error_ratio:rate5m
        expr: |
          sum by (kb) (rate(memors_mcp_tool_calls_total{outcome="error"}[5m]))
          /
          sum by (kb) (rate(memors_mcp_tool_calls_total[5m]))
      - record: memors:tool_latency_seconds:p95_5m
        expr: histogram_quantile(0.95, sum by (kb, tool, le) (rate(memors_mcp_tool_call_duration_seconds_bucket[5m])))
      - record: memors:search_latency_seconds:p95_5m
        expr: histogram_quantile(0.95, sum by (kb, le) (rate(memors_search_duration_seconds_bucket[5m])))
      - record: memors:search_abstain_ratio:rate15m
        expr: |
          sum by (kb) (rate(memors_search_total{outcome="abstain", granularity=~"chunk|document"}[15m]))
          /
          sum by (kb) (rate(memors_search_total{granularity=~"chunk|document"}[15m]))
      - record: memors:arm_latency_seconds:p95_5m
        expr: histogram_quantile(0.95, sum by (kb, arm, le) (rate(memors_search_arm_duration_seconds_bucket[5m])))

The abstain ratio counts passage and document searches only. A fact or page search finds nothing whenever no fact or page matches, and the ask prompt runs a fact search for every question.

Alerts

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

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

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

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

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

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

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

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

Dashboard queries

Logs

memors-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 MEMORS_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-memors.log.

• CLI commands print logs to your terminal’s stderr. Every memors-mcp search prints its INFO search line. Use MEMORS_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/memors-mcp "$@" 2>>"$HOME/.memors-mcp/serve.log"
  

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

MCP logging capability

memors-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 MEMORS_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

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

The UI’s /log page shows both tables.

Retention

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

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

For example, with cron:

0 3 * * *  MEMORS_KB=my-project /path/to/memors-mcp log prune

Querying with SQL

sqlite3 -header -column ~/.memors-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 memors-mcp is running (safe online backup)

DB=~/.memors-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 memors-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 memors-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 $MEMORS_HOME/kb/<name>.db, then chmod 600 it.
4. Check it:

   MEMORS_KB=<name> memors-mcp verify
   MEMORS_KB=<name> memors-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

memors-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 memors-mcp, and re-ingesting it creates no new revisions. See Exporting.

Integrity and repair

verify

memors-mcp verify
memors-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 ~/.memors-mcp/kb/my-project.db 'PRAGMA integrity_check'   # expect: ok
sqlite3 ~/.memors-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. memors_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 memors_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

memors-mcp export --md ./kb-export            # all namespaces
memors-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

memors-mcp export --index > kb-index.md                        # ≤ 8 KB, one line per document
memors-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 ~/.memors-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:

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

The client does not show the memors tools

Search returns nothing, or too little

Search is degraded

Slow searches

1. memors-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 memors_graph_cache_total{event="build"}. Repeated builds mean frequent writes.
4. Reranker on? MEMORS_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 memors-mcp migrate”

The file is older than the binary. Run memors-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 memors-mcp trust promote … command for a human to run. memors_mcp_elicitations_total{outcome="unsupported"} counts these.

Reporting a bug

Include memors-mcp version, the status output, the stderr lines from MEMORS_LOG_LEVEL=debug, and, for ranking issues, memors-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 MEMORS_* 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