Self-hosted AI agent memory — an MCP memory server with durable recall, hybrid RAG, and Neo4j graph context.
Metronix is self-hosted memory infrastructure for AI agents: ingest files and SaaS knowledge, retrieve with dense + sparse + graph context, store durable facts and preferences per agent, and keep long-lived knowledge fresh as projects change.
What you get
Self-hosted AI agent memory — MCP memory server with durable recall for agents
Estrelas
107
Ferramentas
—
Disponibilidade
—
Durable memory for every agent — facts, preferences, and pinned context with workspace and agent scoping
Full install (prerequisites, .env, ports, troubleshooting): install.md.
Example in 5 minutes: store and find a memory
Once the stack is up (the first image build takes 10–15 minutes), this takes a few minutes. The sample output below is from a manual run; IDs and scores will differ on your stack. It needs curl and jq, and is run from the repository root, where .env lives.
2. Set an admin password and restart the API. On a new installation (empty users table), add a password for the built-in [email protected] account (choose your own, at least 8 characters) to .env:
AUTH_PASSWORD=<your-password>
AUTH_PASSWORD only seeds the first admin: at startup the API creates [email protected] when the users table is empty and does nothing otherwise. Changing it later does not change the password of an existing account. If you already have a running installation, skip the .env change and use your current admin credentials in step 3. To change the password of an existing account, an admin can send PATCH /api/v1/users/{user_id} with {"password": "<new-password>"} (admin token required, minimum 8 characters).
On a new installation, recreate only the API container so it picks up .env:
3. Log in and create a personal API key. The shared METRONIX_MCP_API_KEY only opens /mcp. The memory tools and the REST memory API need a user identity, so create a personal mtk_ key (it is shown once):
agent_id in the arguments must match the X-Agent-Id header. With the shared METRONIX_MCP_API_KEY as the Bearer token, metronix_status and metronix_search_fast work, but metronix_memory_* returns AUTH_REQUIRED: metronix_memory_search: unauthorized agent memory access.
5. Over REST: store, search, list. The same key works for the REST memory API, and both paths see the same records:
Two differences from docs/API.md that matter here. scope is lowercase (per_agent, global, session); the uppercase PER_AGENT shown there returns HTTP 422. And workspace_id=default, also shown there, is accepted although no such workspace exists (only MTRNIX is listed), so records land in a separate, unlisted workspace — pass MTRNIX or omit the parameter.
Headline gate: LongMemEval-S Recall@10 95.4% under benchmark-protocol v1.0 (directional N=1; same answer model, same blind judge).
Benchmark
Scope
Layer B
Retrieval / signal
Status
LoCoMo
1,986 QA in the pinned dataset¹
52.8%
Recall@10 85.3%
directional, results not committed in this repo · harness
LongMemEval-S
500 questions
59.0%
Recall@10 95.4%
directional, results not committed in this repo · harness
MemoryAgentBench
2,800 tasks
63.6%
Accurate Retrieval 84.7% · EventQA blended 86.8%
external, not reproduced in this repo
EventQA
MAB 65K + 131K
86.8% blended
98.0% @ 65K · 94.8% @ 131K
external, not reproduced in this repo
BEAM 100K
400 questions
32.1%
Recall@10 2.9% · Layer B is the meaningful figure
external, not reproduced in this repo
Pattern: retrieval usually finds the evidence; answer synthesis and preference following remain the hard part. Details: docs/benchmarks/longmemeval.md.
Directional = single run (N=1); the run files, manifests and the benchmark-protocol v1.0 text are not in this repository, so these numbers cannot be checked from it. External = no harness in this repository.
¹ locomo10.json at upstream commit 3eb6f2c, SHA-256 as pinned in benchmarks/locomo/README.md: 1,986 questions in 10 conversations; categories 1–4 (the harness default) = 1,540, category 5 (abstention) = 446. This table previously said 1,982, which does not match the file; which subset produced 52.8% / 85.3% is not recorded in this repository.
Retrieval (passage recall@5), reproducible
Multi-hop passage retrieval on the HippoRAG evaluation sets. Per-question results are committed in benchmarks/musique/results/2026-09-27/; the values below are recomputed from those files.
Configuration
MuSiQue R@5 (500 held-out)
2Wiki R@5 (1,000)
Production defaults (BFS graph channel, signal fusion)
"ppr+" and the learned fusion are off by default (METRONIX_RETRIEVAL_GRAPH_PPR_ENABLED=false, METRONIX_RETRIEVAL_FUSION_MODE=signal).
This measures retrieval recall, not answer accuracy: no EM/F1 was run.
The MuSiQue graph is the ready-made OpenIE graph released by HippoRAG (extracted by Llama-3.3-70B), not one built by Metronix's own extractor. A graph extracted by Metronix itself (qwen2.5:3b) was measured only on a 30-question MuSiQue slice: it is much sparser (the PPR channel alone reaches the last-hop passage for 9 of 30 questions vs 29 of 30 on an oracle graph, REPORT item 7), and learned "ppr+" is +13.3 R@5 over production there with a 95% CI of 3.3 to 23.3 (research note §5.10). That slice is too small to size the gain on graphs Metronix extracts itself.
The 2Wiki title-mention graph structurally favours the gold passages, so the 2Wiki gain is optimistic.
The learned fusion was fitted on the other 500 MuSiQue questions; single run on CPU.
Both configurations are below HippoRAG 2 (74.7 / 90.4 as quoted in the research note §5.8) and below plain NV-Embed-v2 on MuSiQue. Not a state-of-the-art claim.
make dev # uvicorn --reload
make test # pytest unit tests
make lint # ruff check + format check
make typecheck # mypy src/metronix/
make migrate # alembic upgrade head
FAQ
Is Metronix hosted?
No — it is self-hosted. You run the backend and choose where data lives.
Can multiple agents share one backend without leaking memory?
Yes. Memory is scoped by workspace and agent_id. Share a workspace for org knowledge; keep private memory per agent.
Is this for Raspberry Pi or zero-latency voice loops?
No. Metronix is a server-side backend. Run it on a machine with enough RAM, and have edge clients connect over REST/MCP.
Native Hermes provider vs MCP?
Use the native provider for automatic prefetch/write-through; use MCP for explicit knowledge-base tools. They complement each other — see Hermes MCP guide.
How does MCP authentication work?
Local/self-hosted defaults use AUTH_ENABLED=false with METRONIX_MCP_API_KEY. Hosted deployments with AUTH_ENABLED=true require a user JWT instead — see install.md and connecting_to_agent.md.
How do I verify memory actually works?
Store a distinctive record, then search via REST or metronix_memory_search. Do not rely only on asking an LLM “do you remember X?” — see install.md verify steps and connecting_to_agent.md.
Ainda não há lista de ferramentas. Servidores remotos recebem uma após a primeira verificação de saúde.
Perguntas frequentes
Perguntas
Como instalo Metronix Memory?
Copie nesta página a configuração stdio para Cursor, Claude Desktop, Claude Code ou VS Code. Ela usa a instalação do publicador, não um proxy do PlugMCP.
Metronix Memory precisa de uma chave de API?
Este registro não lista nenhuma variável de ambiente obrigatória.
Qual transporte Metronix Memory usa?
Metronix Memory roda localmente via stdio.
Quando Metronix Memory foi verificado pela última vez?
Última verificação: 2026-11-09. Self-hosted AI agent memory — MCP memory server with durable recall for agents