Metronix Memory

Self-hosted memory infra for AI agents — MCP-native, local-model friendly: hybrid RAG + temporal knowledge graph & ontology layer, durable memory, freshness checks, agent-scoped context.

Metronix gives agents a memory backend they can actually call: 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.

git clone https://github.com/mtrnix/metronix-memory.git
cd metronix-memory
cp .env.example .env
printf '\nMETRONIX_MCP_API_KEY=%s\n' "$(openssl rand -hex 32)" >> .env
docker compose up -d --build
curl http://localhost:8000/health

[Install](#install) | [Runtime Guides](#choose-your-runtime-guide) | [Benchmarks](#benchmarks) | [Docs](#documentation)

---

Why Not Just...

| Option | What it gives you | What Metronix adds | | --- | --- | --- | | Vector DB | Similarity search over embedded chunks | Ingestion, MCP tools, durable agent memory, sparse retrieval, graph context, and operational APIs | | Long context | More tokens in one prompt | Persistent memory across sessions, agent/workspace scoping, retrieval, and freshness checks | | Chat history | Transcript recall | Structured facts, preferences, pinned memory, temporal knowledge, and reusable context for any MCP-native agent |

Benchmarks

Directional N=1 results under benchmark-protocol v1.0: same answer model (deepseek-v4-flash, T=0), same blind judge (deepseek-v4-pro), same volume, and both retrieval + end-to-end layers.

| Benchmark | Scope | Layer B result | Retrieval / signal | | --- | --- | --- | --- | | LoCoMo | 1,982 / 1,982 QA pairs | 52.8% | Recall@10 85.3% | | LongMemEval-S | 500 / 500 questions | 59.0% | Recall@10 95.4%; reproducible harness in [benchmarks/longmemeval](benchmarks/longmemeval) | | MemoryAgentBench | 2,800 / 2,800 tasks | 63.6% | Accurate Retrieval 84.7%; EventQA blended 86.8% | | EventQA | MAB EventQA 65K + 131K | 86.8% blended | 98.0% at 65K; 94.8% at 131K | | BEAM 100K | 400 / 400 questions | 32.1% | Recall@10 2.9%; Layer B is the meaningful figure for this tier |

Metronix leads the equal-conditions comparison on LoCoMo and MemoryAgentBench, while Mem0 leads narrowly on LongMemEval-S and BEAM 100K. The recurring pattern is retrieval ahead of generation: relevant evidence is usually found, but answer synthesis, conflict resolution, and preference following remain the hard parts.

Integrations

| Agent/runtime | Path | | --- | --- | | Hermes | [Hermes Agent guide](docs/integrations/hermes-agent.md) | | Cursor | [Cursor guide](docs/integrations/cursor.md) | | Claude Desktop | [Claude Desktop guide](docs/integrations/claude-desktop.md) | | Claude Code | [Claude Code guide](docs/integrations/claude-code.md) | | OpenCode | [OpenCode guide](docs/integrations/opencode.md) | | LangChain | [LangChain guide](docs/integrations/langchain.md) |

⭐ Star us if you build agents with memory.

---

Architecture

Metronix Core uses a strict one-way dependency architecture - each layer only imports downward.

L6  api/            REST + OpenAI-compatible API + MCP HTTP mount
L5  channels/       Legacy Telegram, Discord, Slack integrations
L4  agent/          Intent router and compatibility shims
L3  services        Connectors, LLM, MCP, memory, auth, workspaces, knowledge
L2  processing      Ingestion, retrieval, freshness pipeline
L1  storage/        PostgreSQL, Qdrant, Neo4j, Redis clients
L0  core/           Config, models, events, plugin interfaces

[Open interactive architecture diagram](docs/architecture-diagram.html) - works offline in your browser.

Key Pipelines

| Pipeline | Flow | What it does | | ------------- | ------------------------------------------------------------ | -------------------------------------------------------------------------------------------- | | Ingestion | Fetch -> Parse -> Chunk -> Embed -> Store | Incremental sync from connectors and files. PDF, HTML, Office, text, and tabular processors. | | Retrieval | Classify -> Expand -> Recall -> Rerank -> Score -> Answer | Dense vectors + SPLADE sparse retrieval + graph context + source citations. | | Freshness | Linker -> Reconciler -> Monitor -> Curator -> DecisionEngine | Detects stale or conflicting memory and knowledge records. | | Memory | Store -> Search -> Review -> Assemble | Persistent agent memory scoped by workspace and agent. |

---

Install

Get a backend running in four steps. This is the shortest path; for the full guide (prerequisites, Open WebUI, ports, troubleshooting) see [install.md](install.md).

> Requirements: Docker with ≥6 GB RAM (8 GB recommended) and ~15 GB free disk. The > default Docker Desktop allotment (~2 GB) is too small for the full stack plus the local > graph model and will OOM-kill syncs — raise it under Settings → Resources → Memory.

1. Clone

git clone https://github.com/mtrnix/metronix-memory.git
cd metronix-memory

Quick install — one script replaces steps 2–4: checks Docker, writes .env, builds and starts the stack, health-checks the API, and optionally wires Hermes.

./install.sh                              # agent memory (default)
./install.sh --mode answers --chat-url https://api.deepseek.com/v1 \
  --chat-model deepseek-chat --openwebui -y   # chat UI + answer generation

Flags: --mode memory|answers, --chat-url, --chat-model, --chat-api-key, --openwebui, --connect-hermes, --reconfigure, -y (./install.sh --help).

Prefer manual setup? Continue with step 2 below.

2. Configure: set the MCP key in .env

cp .env.example .env

For agent memory over MCP (Hermes, Cursor, …) you only need the MCP auth key. Embeddings for ingest come from the bundled Ollama container (nomic-embed-text), and a small graph model (qwen2.5:3b) is pulled alongside it for knowledge-graph extraction — both on first docker compose up. No external chat LLM is required in .env.

METRONIX_MCP_API_KEY=...   # generate: openssl rand -hex 32

Optional — only if you run Open WebUI or want Metronix to generate answers itself:

LLM_PROVIDER=custom
LLM_PROVIDER_URL=https://your-llm-endpoint/v1   # e.g. https://api.deepseek.com/v1
LLM_PROVIDER_API_KEY=your-key
LLM_PROVIDER_MODEL=deepseek-chat                # model the endpoint serves

3. Launch (first run builds images + pulls embedding model, ~10–15 min)

docker compose up -d --build

4. Verify

curl http://localhost:8000/health

A healthy backend exposes the REST API, the OpenAI-compatible API at :8000/v1, and the MCP endpoint at :8000/mcp (default on the host: http://localhost:8000/mcp — the metronix-full-api container, path /mcp; from Docker network: http://metronix-core:8000/mcp). If you have installed the KnowledgeBase-UI (e.g. http://localhost:3000), log in with your Metronix credentials. Default credentials:

login: admin@metronix.local
pass: metronix

5. Quick Validation

Verify the full memory lifecycle (store and retrieve) using either the REST API or the native MCP Streamable HTTP interface.

Option A: REST API

Step A — Authenticate (get a JWT token) using the default admin credentials (admin@metronix.local / metronix):

• Linux/macOS (Bash):

``bash TOKEN=$(curl -s -X POST -H "Content-Type: application/json" -d '{"email": "admin@metronix.local", "password": "metronix"}' http://localhost:8000/api/v1/auth/login | jq -r '.token') ``

• Windows PowerShell:

``powershell $response = Invoke-RestMethod -Method Post -Uri "http://localhost:8000/api/v1/auth/login" -ContentType "application/json" -Body '{"email": "admin@metronix.local", "password": "metronix"}' $TOKEN = $response.token ``

Step B — Store a memory record for an agent:

• Linux/macOS (Bash):

``bash curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{"content": "The agent prefers dark mode and custom keybindings.", "agent_id": "agent-123", "scope": "per_agent", "kind": "fact"}' http://localhost:8000/api/v1/memory/records ``

• Windows PowerShell:

``powershell Invoke-RestMethod -Method Post -Headers @{ Authorization = "Bearer $TOKEN" } -Uri "http://localhost:8000/api/v1/memory/records" -ContentType "application/json" -Body '{"content": "The agent prefers dark mode and custom keybindings.", "agent_id": "agent-123", "scope": "per_agent", "kind": "fact"}' ``

Step C — Search/retrieve the memory and confirm it comes back:

• Linux/macOS (Bash):

``bash curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{"query": "dark mode", "agent_id": "agent-123"}' http://localhost:8000/api/v1/memory/search ``

• Windows PowerShell:

``powershell Invoke-RestMethod -Method Post -Headers @{ Authorization = "Bearer $TOKEN" } -Uri "http://localhost:8000/api/v1/memory/search" -ContentType "application/json" -Body '{"query": "dark mode", "agent_id": "agent-123"}' ``

Option B: MCP interface (Python client)

MCP uses a stateful stream (SSE for server→client) plus HTTP POST for client→server, so the standard way to talk to /mcp is the official mcp SDK or an MCP client (Cursor, Claude Desktop, …). End-to-end example exercising the real tools (metronix_memory_store and metronix_memory_search):

import asyncio
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

async def main():
    # If METRONIX_MCP_API_KEY is set in your .env, pass it as a Bearer token:
    # headers = {"Authorization": "Bearer "}
    headers = {}

    async with streamablehttp_client("http://localhost:8000/mcp", headers=headers) as (r, w, _):
        async with ClientSession(r, w) as session:
            await session.initialize()

            print("Storing memory via MCP...")
            store_res = await session.call_tool("metronix_memory_store", {
                "content": "The agent prefers standard python logging for audits.",
                "agent_id": "agent-xyz",
                "workspace_id": "MTRNIX",
                "scope": "per_agent",
                "kind": "fact",
            })
            print("Store Result:", store_res.content[0].text)

            print("\nRetrieving memory via MCP...")
            search_res = await session.call_tool("metronix_memory_search", {
                "query": "python logging",
                "agent_id": "agent-xyz",
                "workspace_id": "MTRNIX",
            })
            print("Search Result:", search_res.content[0].text)

if __name__ == "__main__":
    asyncio.run(main())

To run it: make sure the backend is up (docker compose up -d), install the SDK (pip install mcp), then run the script (python mcp_client_test.py).

Next steps:

• [install.md](install.md) — full installation info: prerequisites, Open

WebUI, ports, and troubleshooting.

• [connectingtoagent.md](connectingtoagent.md) — connect an agent over MCP and give it

durable memory.

• [prompts.md](prompts.md) — the agent setup prompts, ready to paste.

---

Choose Your Runtime Guide

After the backend is running, start with the generic MCP setup guide, then pick the client or runtime you actually want to use.

First step: [Connecting To An Agent](connectingtoagent.md) — a self-contained MCP setup prompt that works with any agent runtime. Run this, and your agent can configure Metronix Memory automatically.

Then pick your integration (full list in [docs/README.md](docs/README.md#runtime-guides)):

• [Hermes Agent](docs/integrations/hermes-agent.md)
• [OpenClaw](docs/integrations/openclaw.md)
• [Cursor](docs/integrations/cursor.md)
• [Claude Desktop](docs/integrations/claude-desktop.md)
• [Ollama + GLM or Qwen](docs/integrations/ollama-local-models.md)
• [Open WebUI + Ollama](docs/integrations/atomic-chat.md)
• [Claude Code](docs/integrations/claude-code.md)
• [Codex](docs/integrations/codex.md)
• [OpenCode](docs/integrations/opencode.md)
• [LangChain](docs/integrations/langchain.md)
• [Python SDK](docs/integrations/sdk-python.md)
• [Go SDK](docs/integrations/sdk-go.md)
• [n8n](docs/integrations/n8n.md)
• [NanoClaw](docs/integrations/nanoclaw.md)
• [NanoBot](docs/integrations/nanobot.md)

---

Web Console (KB Admin)

The optional KB Admin Console is the open-source web UI for administering Metronix: add and sync data connectors (Jira, Confluence, GitHub, Google Drive, Notion, Slack), register chat-bot channels (Telegram, Discord, Slack), upload files, and watch service and database health. It is presentation-only — everything runs through the metronix-core REST API.

It ships as an optional service behind the kb Docker Compose profile:

docker compose --profile kb up -d --build   # → http://localhost:3000

See [frontend/README.md](frontend/README.md) for development, build, and configuration details.

> The full operational Control Center (agent registry, workflow builder, memory inspector, > FinOps) is a separate product and is not part of this repository.

---

Demo: ingest a sprint backlog and query it

A quick end-to-end check that Metronix ingests attached files and answers from memory:

1. Connect an agent to Metronix MCP (see [Connecting To An Agent](connectingtoagent.md)).
2. Attach the sample sprint backlog — [examples/tasks.multi-agent-demo.json](examples/tasks.multi-agent-demo.json) — and ask the agent to ingest it into Metronix (via the KB Admin upload UI, the upload API, or the agent's metronix_* memory tools).
3. Ask:

> Based on metronix memory: What is the main focus tasks for the development team?

The agent should answer from ingested knowledge — Sprint 14 (Orchestration & Reliability), with active work on the orchestrator release candidate, supervisor loop, agent messaging, shared memory compaction, observability, and two open blockers (LLM vendor contract and security sign-off).

You can also upload the same file in the KB Admin Console (Sources → Upload) instead of attaching it in chat.

---

Quick Reference

Development Commands

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
make eval             # search quality eval

For architecture and product boundaries, see [docs/reference/architecture.md](docs/reference/architecture.md) and [docs/product/open-core-boundaries.md](docs/product/open-core-boundaries.md).

Hermes users: Metronix Memory integrates as an MCP server, not a Hermes-native memory provider. See [Hermes Agent guide](docs/integrations/hermes-agent.md).

External Ports

External ports from docker-compose.yml:

| Service | Port | | --------------- | ------- | | API | 8000 | | PostgreSQL | 5433 | | Qdrant HTTP | 6335 | | Qdrant gRPC | 6336 | | Neo4j HTTP | 7475 | | Neo4j bolt | 7688 | | Redis | 6380 | | Ollama | 11435 | | SPLADE | 8080 | | Embedding proxy | 8002 | | Open WebUI | 3080 |

Important URLs

| Surface | URL | | --------------------- | --------------------------------------------------------------------------------- | | API health | http://localhost:8000/health

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: mtrnix
• Source: mtrnix/metronix-memory
• License: Apache-2.0
• Homepage: https://mtrnix.com

Install and usage instructions live in the source repository linked above.