Skip to content
Back to search

metronix-memory

Self-hosted AI agent memory — MCP memory server with durable recall for agents

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/mtrnix/metronix-memory with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/mtrnix/metronix-memory'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/mtrnix--metronix-memory/badge.svg)](/listings/mtrnix--metronix-memory)

HTML

<a href="/listings/mtrnix--metronix-memory"><img src="/api/listings/mtrnix--metronix-memory/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

Requirements: Docker with **≥6 GB RAM** (8 GB recommended) and ~15 GB free disk.

# One-liner (latest tagged release)
curl -fsSL https://mtrnix.com/install.sh | bash

# Or clone and install
git clone https://github.com/mtrnix/metronix-memory.git
cd metronix-memory
./install.sh                              # agent memory (default)
# ./install.sh --mode answers --openwebui -y   # optional chat UI + answers
curl http://localhost:8000/health
# {"status":"ok"}

Then connect an agent: **[Connecting to an agent](connecting_to_agent.md)**.

Full install (prerequisites, `.env`, ports, troubleshooting): **[install.md](install.md)**.

**⭐ Star us if you build agents that remember.**

<p align="center"> </p>

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 315 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Metronix Memory
  2. <p align="center">
  3. <img src="docs/metronix-banner.svg" alt="Metronix Memory — self-hosted AI agent memory" width="600">
  4. </p>
  5. **Self-hosted AI agent memory — an MCP memory server with durable recall, hybrid RAG, and Neo4j graph context.**
  6. 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.
  7. <p align="center">
  8. <img alt="License: Apache-2.0" src="https://img.shields.io/badge/License-Apache--2.0-blue.svg">
  9. <img alt="Docker" src="https://img.shields.io/badge/Docker-ready-2496ED?logo=docker&logoColor=white">
  10. <img alt="MCP" src="https://img.shields.io/badge/MCP-native-111111">
  11. <img alt="Python" src="https://img.shields.io/badge/Python-3.12--3.13-3776AB?logo=python&logoColor=white">
  12. </p>
  13. ## What you get
  14. - **Durable memory for every agent** — facts, preferences, and pinned context with workspace and agent scoping
  15. - **Hybrid knowledge retrieval** — dense + SPLADE sparse + Neo4j graph context, with source citations
  16. - **Self-hosted control** — Docker Compose stack, bundled local models, optional external answer generation
  17. - **One integration surface** — MCP memory server today; REST and OpenAI-compatible APIs when you need them
  18. ## Quick start
  19. Requirements: Docker with **≥6 GB RAM** (8 GB recommended) and ~20 GB free disk.
  20. ```bash
  21. git clone https://github.com/mtrnix/metronix-memory.git && cd metronix-memory && ./scripts/quickstart.sh
  22. ```
  23. That one command, with no prompts:
  24. 1. generates every secret into one `.env` (database passwords, admin password, keys),
  25. 2. pulls and builds the images and starts the stack, showing progress,
  26. 3. waits until `/ready` is green: migrations applied, stores up, embedding model pulled,
  27. 4. issues a personal `mtk_` key for your agent (`METRONIX_AGENT_KEY` in `.env`),
  28. 5. prints ready-to-paste MCP configs for **Claude Desktop, Cursor and VS Code**
  29. (also saved in `client-configs/`),
  30. 6. runs an end-to-end smoke test (store a fact, restart the API, recall it) and ends with
  31. `SMOKE TEST PASSED`, then prints the generated credentials.
  32. The ~2 GB knowledge-graph model is not downloaded (memory does not need it); it is pulled on
  33. the first document ingest, or now with `./scripts/quickstart.sh --with-graph-model`.
  34. It exits non-zero at the first failing step. A first run pulls images, Python packages and
  35. models (about 17 GB on disk afterwards), so its duration is set by your bandwidth; with images
  36. already cached it takes about a minute. Re-running it is safe: it reuses `.env`, the running
  37. stack and a still-valid agent key.
  38. Or without cloning (installs the latest release into `~/.metronix/metronix-memory`):
  39. ```bash
  40. curl -fsSL https://mtrnix.com/install.sh | bash -s -- -- --quickstart
  41. ```
  42. Use the personal key from the printed configs. The shared `METRONIX_MCP_API_KEY` in `.env` only
  43. opens `/mcp`; every `metronix_memory_*` tool returns `AUTH_REQUIRED` with it.
  44. Other agents (Claude Code, Codex, Hermes, OpenClaw) and the interactive installer
  45. (`./install.sh`): **[Connecting to an agent](connecting_to_agent.md)**.
  46. Full install (prerequisites, `.env`, ports, troubleshooting): **[install.md](install.md)**.
  47. ## Example in 5 minutes: store and find a memory
  48. 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.
  49. **1. Check the stack.**
  50. ```bash
  51. curl http://localhost:8000/health
  52. # {"status":"ok"}
  53. ```
  54. **2. Load the personal key that `scripts/quickstart.sh` issued.** It is stored in `.env` as
  55. `METRONIX_AGENT_KEY` (run `scripts/provision_agent.sh` to issue one for an install made with
  56. `./install.sh`). The memory tools and the REST memory API need this personal key; the shared
  57. `METRONIX_MCP_API_KEY` only opens `/mcp`.
  58. ```bash
  59. MTK=$(grep '^METRONIX_AGENT_KEY=' .env | cut -d= -f2-)
  60. echo "key prefix: ${MTK:0:4}"
  61. # key prefix: mtk_
  62. ```
  63. **3. Over MCP (the path agents use): store, search, list.**
  64. ```bash
  65. mcp() { curl -fsS -X POST http://localhost:8000/mcp \
  66. -H "Authorization: Bearer $MTK" -H "X-Agent-Id: my-agent" \
  67. -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
  68. -d "$1" | sed -n 's/^data: //p' | jq '.result.structuredContent'; }
  69. mcp '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"metronix_memory_store","arguments":{"agent_id":"my-agent","workspace_id":"MTRNIX","content":"The staging database password rotates every 30 days.","tags":["quickstart"]}}}'
  70. # {
  71. # "id": "30424ce432bd4302929a73c41eaaaa15",
  72. # "content_hash": "b5b6e76c2b41604dc86792982a55d4bac4b774098da6d9d8ebaccab01a9cb092",
  73. # "deduped": false
  74. # }
  75. mcp '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"metronix_memory_search","arguments":{"agent_id":"my-agent","workspace_id":"MTRNIX","query":"how often does the staging password change","top_k":3}}}' \
  76. | jq '.results[] | {score, content: .record.content}'
  77. # {
  78. # "score": 0.75,
  79. # "content": "The staging database password rotates every 30 days."
  80. # }
  81. mcp '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"metronix_memory_list","arguments":{"agent_id":"my-agent","workspace_id":"MTRNIX","limit":5}}}' \
  82. | jq '.records[] | {id, kind, content}'
  83. # {
  84. # "id": "30424ce432bd4302929a73c41eaaaa15",
  85. # "kind": "fact",
  86. # "content": "The staging database password rotates every 30 days."
  87. # }
  88. ```
  89. `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`.
  90. **4. Over REST: store, search, list.** The same key works for the REST memory API, and both paths see the same records:
  91. ```bash
  92. curl -fsS -X POST "http://localhost:8000/api/v1/memory/records?workspace_id=MTRNIX" \
  93. -H "Authorization: Bearer $MTK" -H 'Content-Type: application/json' \
  94. -d '{"content":"Production deploys happen on Tuesdays.","agent_id":"my-agent","scope":"per_agent","kind":"fact","tags":["quickstart"]}' \
  95. | jq '{id, workspace_id, agent_id, scope, kind, content, status}'
  96. # {
  97. # "id": "c131d23f7361448a9b8f8d9712663b86",
  98. # "workspace_id": "MTRNIX",
  99. # "agent_id": "my-agent",
  100. # "scope": "per_agent",
  101. # "kind": "fact",
  102. # "content": "Production deploys happen on Tuesdays.",
  103. # "status": "active"
  104. # }
  105. curl -fsS -X POST "http://localhost:8000/api/v1/memory/search?workspace_id=MTRNIX" \
  106. -H "Authorization: Bearer $MTK" -H 'Content-Type: application/json' \
  107. -d '{"query":"when do production deploys happen","agent_id":"my-agent","top_k":3}' \
  108. | jq '.results[] | {score, content: .record.content}'
  109. # {
  110. # "score": 0.75,
  111. # "content": "Production deploys happen on Tuesdays."
  112. # }
  113. # {
  114. # "score": 0.15,
  115. # "content": "The staging database password rotates every 30 days."
  116. # }
  117. curl -fsS "http://localhost:8000/api/v1/memory/records?workspace_id=MTRNIX&agent_id=my-agent&limit=5" \
  118. -H "Authorization: Bearer $MTK" | jq '.records[] | {id, kind, content}'
  119. # {
  120. # "id": "c131d23f7361448a9b8f8d9712663b86",
  121. # "kind": "fact",
  122. # "content": "Production deploys happen on Tuesdays."
  123. # }
  124. # {
  125. # "id": "30424ce432bd4302929a73c41eaaaa15",
  126. # "kind": "fact",
  127. # "content": "The staging database password rotates every 30 days."
  128. # }
  129. ```
  130. Two differences from [docs/API.md](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.
  131. **⭐ Star us if you build agents that remember.**
  132. <p align="center">
  133. <img src="docs/metronix-agent-memory-demo.gif" alt="Metronix demo: an AI agent remembering across sessions with self-hosted MCP memory" width="720">
  134. </p>
  135. ## Why Metronix
  136. | Option | What it gives you | What Metronix adds |
  137. | --- | --- | --- |
  138. | Vector DB | Similarity search | Ingestion, MCP tools, durable agent memory, sparse + graph retrieval |
  139. | Long context | More tokens in one prompt | Persistent memory across sessions, scoping, freshness |
  140. | Chat history | Transcript recall | Structured facts/preferences, temporal knowledge, reusable MCP context |
  141. | RAG framework | Building blocks | Operational backend: connectors, APIs, MCP, memory lifecycle |
  142. ## Benchmarks
  143. Headline gate: **LongMemEval-S Recall@10 95.4%** under `benchmark-protocol v1.0` (directional N=1; same answer model, same blind judge).
  144. | Benchmark | Scope | Layer B | Retrieval / signal | Status |
  145. | --- | --- | --- | --- | --- |
  146. | LoCoMo | 1,986 QA in the pinned dataset¹ | **52.8%** | Recall@10 **85.3%** | directional, results not committed in this repo · [harness](benchmarks/locomo) |
  147. | LongMemEval-S | 500 questions | **59.0%** | Recall@10 **95.4%** | directional, results not committed in this repo · [harness](benchmarks/longmemeval) |
  148. | MemoryAgentBench | 2,800 tasks | **63.6%** | Accurate Retrieval **84.7%** · EventQA blended **86.8%** | external, not reproduced in this repo |
  149. | EventQA | MAB 65K + 131K | **86.8%** blended | 98.0% @ 65K · 94.8% @ 131K | external, not reproduced in this repo |
  150. | BEAM 100K | 400 questions | **32.1%** | Recall@10 2.9% · Layer B is the meaningful figure | external, not reproduced in this repo |
  151. Pattern: retrieval usually finds the evidence; answer synthesis and preference following remain the hard part. Details: [docs/benchmarks/longmemeval.md](docs/benchmarks/longmemeval.md).
  152. *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.
  153. ¹ `locomo10.json` at upstream commit `3eb6f2c`, SHA-256 as pinned in [benchmarks/locomo/README.md](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.
  154. ### Retrieval (passage recall@5), reproducible
  155. Multi-hop passage retrieval on the HippoRAG evaluation sets. Per-question results are committed in [`benchmarks/musique/results/2026-09-27/`](benchmarks/musique/results/2026-09-27/); the values below are recomputed from those files.
  156. | Configuration | MuSiQue R@5 (500 held-out) | 2Wiki R@5 (1,000) |
  157. | --- | --- | --- |
  158. | Production defaults (BFS graph channel, `signal` fusion) | 58.25 | 71.85 |
  159. | Opt-in learned "ppr+" (PPR channel + learned fusion) | 62.80 | 85.65 |
  160. Caveats:
  161. - "ppr+" and the learned fusion are **off by default** (`METRONIX_RETRIEVAL_GRAPH_PPR_ENABLED=false`, `METRONIX_RETRIEVAL_FUSION_MODE=signal`).
  162. - This measures **retrieval recall**, not answer accuracy: no EM/F1 was run.
  163. - 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](benchmarks/musique/REPORT.md) 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](benchmarks/musique/findings/2026-09-26-fusion-research-note.md) §5.10). That slice is too small to size the gain on graphs Metronix extracts itself.
  164. - The 2Wiki title-mention graph **structurally favours the gold passages**, so the 2Wiki gain is optimistic.
  165. - The learned fusion was fitted on the other 500 MuSiQue questions; single run on CPU.
  166. - Both configurations are **below HippoRAG 2** (74.7 / 90.4 as quoted in the [research note](benchmarks/musique/findings/2026-09-26-fusion-research-note.md) §5.8) and below plain NV-Embed-v2 on MuSiQue. Not a state-of-the-art claim.
  167. Commands and verification: [docs/benchmarks/multihop-retrieval.md](docs/benchmarks/multihop-retrieval.md).
  168. ## Connect an agent
  169. | Runtime | Guide |
  170. | --- | --- |
  171. | Any MCP client | [Connecting to an agent](connecting_to_agent.md) · [prompts.md](prompts.md) |
  172. | Hermes | [Native provider](https://github.com/mtrnix/hermes-memory-metronix) · [MCP guide](docs/integrations/hermes-agent.md) |
  173. | Cursor · VS Code (Copilot) | [Cursor](docs/integrations/cursor.md) · [VS Code](docs/integrations/vscode-copilot.md) |
  174. | Claude Desktop / Code | [Desktop](docs/integrations/claude-desktop.md) · [Code](docs/integrations/claude-code.md) |
  175. | OpenCode · Codex · OpenClaw | [OpenCode](docs/integrations/opencode.md) · [Codex](docs/integrations/codex.md) · [OpenClaw](docs/integrations/openclaw.md) |
  176. | LangChain · LangGraph · LlamaIndex | [LangChain](docs/integrations/langchain.md) · [LangGraph](docs/integrations/langgraph.md) · [LlamaIndex](docs/integrations/llamaindex.md) |
  177. | SDKs · n8n | [Python](docs/integrations/sdk-python.md) · [Go](docs/integrations/sdk-go.md) · [n8n](docs/integrations/n8n.md) |
  178. Full index: [docs/README.md](docs/README.md).
  179. ## Architecture
  180. One-way layers — each level only imports downward:
  181. ```text
  182. L6 api/ REST + OpenAI-compatible API + MCP HTTP mount
  183. L5 channels/ Legacy Telegram, Discord, Slack integrations
  184. L4 agent/ Intent router and compatibility shims
  185. L3 services/ Connectors, LLM, MCP, memory, auth, workspaces, knowledge
  186. L2 processing/ Ingestion, retrieval, freshness pipeline
  187. L1 storage/ PostgreSQL, Qdrant, Neo4j, Redis clients
  188. L0 core/ Config, models, events, plugin interfaces
  189. ```
  190. | Pipeline | What it does |
  191. | --- | --- |
  192. | **Ingestion** | Fetch → parse → chunk → embed → store (connectors + files) |
  193. | **Retrieval** | Classify → expand → recall → rerank → score → answer (dense + sparse + graph) |
  194. | **Freshness** | Detect stale or conflicting memory and knowledge |
  195. | **Memory** | Store → search → review → assemble (workspace / agent scoped) |
  196. Interactive diagram (offline): [docs/architecture-diagram.html](docs/architecture-diagram.html).
  197. ## Admin console (optional)
  198. Open-source web UI for connectors, uploads, channels, and health — presentation-only over the REST API:
  199. ```bash
  200. docker compose --profile admin up -d --build # → https://localhost:3000
  201. ```
  202. Details: [frontend/README.md](frontend/README.md). The broader Control Center product is separate and not in this repo.
  203. ## Documentation
  204. | Doc | Purpose |
  205. | --- | --- |
  206. | [install.md](install.md) | Full install, ports, troubleshooting |
  207. | [connecting_to_agent.md](connecting_to_agent.md) | MCP setup for any agent |
  208. | [prompts.md](prompts.md) | Paste-ready agent setup prompts |
  209. | [docs/MCP_API.md](docs/MCP_API.md) | MCP tool reference |
  210. | [docs/API.md](docs/API.md) | REST API reference |
  211. | [docs/README.md](docs/README.md) | Documentation index |
  212. | [CONTRIBUTING.md](CONTRIBUTING.md) | How to contribute |
  213. ## Development
  214. ```bash
  215. make dev # uvicorn --reload
  216. make test # pytest unit tests
  217. make lint # ruff check + format check
  218. make typecheck # mypy src/metronix/
  219. make migrate # alembic upgrade head
  220. ```
  221. ## FAQ
  222. **Is Metronix hosted?**
  223. No — it is self-hosted. You run the backend and choose where data lives.
  224. **Can multiple agents share one backend without leaking memory?**
  225. Yes. Memory is scoped by workspace and `agent_id`. Share a workspace for org knowledge; keep private memory per agent.
  226. **Is this for Raspberry Pi or zero-latency voice loops?**
  227. No. Metronix is a server-side backend. Run it on a machine with enough RAM, and have edge clients connect over REST/MCP.
  228. **Native Hermes provider vs MCP?**
  229. Use the [native provider](https://github.com/mtrnix/hermes-memory-metronix) for automatic prefetch/write-through; use MCP for explicit knowledge-base tools. They complement each other — see [Hermes MCP guide](docs/integrations/hermes-agent.md).
  230. **How does MCP authentication work?**
  231. Local/self-hosted installs use `AUTH_ENABLED=false` and a personal per-agent `mtk_` key (`METRONIX_AGENT_KEY`, issued by `scripts/quickstart.sh`); the shared `METRONIX_MCP_API_KEY` opens `/mcp` but not the memory tools. Hosted deployments with `AUTH_ENABLED=true` require a user JWT instead — see [install.md](install.md) and [connecting_to_agent.md](connecting_to_agent.md).
  232. **How do I verify memory actually works?**
  233. 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](install.md) verify steps and [connecting_to_agent.md](connecting_to_agent.md).
  234. ## Contributing & support
  235. Bug reports and PRs welcome — see [CONTRIBUTING.md](CONTRIBUTING.md).
  236. Issues: [github.com/mtrnix/metronix-memory/issues](https://github.com/mtrnix/metronix-memory/issues).
  237. ## License
  238. Apache License 2.0. See [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.