metronix-memory

<p align="center"> <img src="docs/metronix-banner.svg" alt="Metronix Memory" width="600"> </p> **自主托管的 AI 智能体记忆基础设施 — MCP 原生、本地模型友好：混合 RAG + 时间知识图谱和本体层，可持续记忆，更新检查，智能体范围上下文。** Metronix 为智能体提供了一个可调用的记忆后端：摄取文件和 SaaS 知识，检索时带稠密 + 稀疏 + 图形上下文，存储智能体特定的持久事实和偏好，并保持长期知识的新鲜度。 <p align="center"> <img src="docs/metronix-agent-memory-demo.gif" alt="Metronix demo: an agent remembering across sessions" width="720"> </p> ```bash 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 ``` **[安装](#安装)** | [运行时指南](#选择你的运行时指南) | [基准测试](#基准测试) | [文档](#文档) --- ## 为什么不直接…… | 选项 | 提供的内容 | Metronix 新增功能 | | --- | --- | --- | | 向量数据库 | 基于嵌入块的相似性搜索 | 摄取、MCP 工具、持久智能体记忆、稀疏检索、图形上下文和操作 API | | 长上下文 | 一个提示中更多 token | 跨会话的持久记忆、智能体/工作区范围、检索和更新检查 | | 聊天记录 | 转录回忆 | 结构化事实、偏好、固定记忆、时间知识和可重用的上下文，供任何 MCP 原生智能体使用 | ## 基准测试 `benchmark-protocol v1.0` 下的有向 N=1 结果：相同的答案模型 (`deepseek-v4-flash`, T=0)，相同的盲评测模型 (`deepseek-v4-pro`)，相同的体积，以及检索 + 端到端层。 | 基准测试 | 范围 | 层 B 结果 | 检索 / 信号 | | --- | --- | --- | --- | | LoCoMo | 1,982 / 1,982 个 QA 对 | **52.8%** | 回忆率@10 **85.3%** | | LongMemEval-S | 500 / 500 个问题 | **59.0%** | 回忆率@10 **95.4%**；[benchmarks/longmemeval](benchmarks/longmemeval) 中的可复制工具 | | MemoryAgentBench | 2,800 / 2,800 个任务 | **63.6%** | 准确检索 **84.7%**；EventQA 混合 **86.8%** | | EventQA | MAB EventQA 65K + 131K | **86.8%** 混合 | 65K 处 98.0%；131K 处 94.8% | | BEAM 100K | 400 / 400 个问题 | **32.1%** | 回忆率@10 2.9%；层 B 是该层级的有意义指标 | Metronix 在 LoCoMo 和 MemoryAgentBench 中领先，而 Mem0 在 LongMemEval-S 和 BEAM 100K 中领先。重复的模式是检索优于生成：通常会找到相关证据，但答案合成、冲突解决和偏好遵循仍然是难点。 ## 集成 | 智能体/运行时 | 路径 | | --- | --- | | Hermes | [Hermes 智能体指南](docs/integrations/hermes-agent.md) | | Cursor | [Cursor 指南](docs/integrations/cursor.md) | | Claude Desktop | [Claude Desktop 指南](docs/integrations/claude-desktop.md) | | Claude Code | [Claude Code 指南](docs/integrations/claude-code.md) | | OpenCode | [OpenCode 指南](docs/integrations/opencode.md) | | LangChain | [LangChain 指南](docs/integrations/langchain.md) | **⭐ 如果你使用记忆构建智能体，请给我们点赞。** --- ## 架构 Metronix Core 使用严格的单向依赖架构 - 每个层级仅向下导入。 ```text L6 api/ REST + OpenAI 兼容 API + MCP HTTP 挂载 L5 channels/ 旧版 Telegram、Discord、Slack 集成 L4 agent/ 意图路由器和兼容性适配器 L3 services 连接器、LLM、MCP、记忆、身份验证、工作区、知识 L2 processing 摄取、检索、新鲜度流水线 L1 storage/ PostgreSQL、Qdrant、Neo4j、Redis 客户端 L0 core/ 配置、模型、事件、插件接口 ``` **[打开交互式架构图](docs/architecture-diagram.html)** - 在浏览器中离线运行。 ### 关键流水线 | 流水线 | 流程 | 功能 | | ------------- | ------------------------------------------------------------ | -------------------------------------------------------------------------------------------- | | **摄取** | 获取 -> 解析 -> 分块 -> 嵌入 -> 存储 | 来自连接器和文件的增量同步。PDF、HTML、Office、文本和表格处理器。 | | **检索** | 分类 -> 扩展 -> 回忆 -> 重排序 -> 评分 -> 答案 | 稠密向量 + SPLADE 稀疏检索 + 图形上下文 + 来源引用。 | | **新鲜度** | 连接器 -> 调节器 -> 监视器 -> 管理员 -> 决策引擎 | 检测过期或冲突的记忆和知识记录。 | | **记忆** | 存储 -> 搜索 -> 审查 -> 组装 | 持久智能体记忆，按工作区和智能体范围。 | --- ## 安装 四步快速搭建后端。这是最短的路径；有关完整指南（前提条件、Open WebUI、端口、故障排除），请参阅 [install.md](install.md)。 > **要求：** 带有 **≥6 GB RAM** （推荐 8 GB）和约 15 GB 空闲磁盘空间的 Docker（默认 Docker Desktop 分配的 ~2 GB 太小，无法运行完整的堆栈和本地图形模型，可能会导致 OOM-kill 同步 — 在设置中将资源 → 资源调整为内存）。 ### 1. 克隆 ```bash git clone https://github.com/mtrnix/metronix-memory.git cd metronix-memory ``` **快速安装** — 一个脚本替代步骤 2-4：检查 Docker，写入 `.env`，构建并启动堆栈，健康检查 API，并可选地连接 Hermes。 ```bash ./install.sh # 智能体记忆（默认） ./install.sh --mode answers --chat-url https://api.deepseek.com/v1 \ --chat-model deepseek-chat --openwebui -y # 聊天 UI + 答案生成 ``` 标志：`--mode memory|answers`，`--chat-url`，`--chat-model`，`--chat-api-key`，`--openwebui`， `--connect-hermes`，`--reconfigure`，`-y` (`./install.sh --help`)。 * 更喜欢手动设置？继续执行步骤 2。 ### 2. 配置：在 `.env` 中设置 MCP 密钥 ```bash cp .env.example .env ``` 对于 **通过 MCP 的智能体记忆** （Hermes、Cursor、…），您只需要 MCP 身份验证密钥。摄取的嵌入来自捆绑的 Ollama 容器 (`nomic-embed-text`)，并且在第一次 `docker compose up` 时会拉取一个小型图形模型 (`qwen2.5:3b`) 用于知识图谱提取 - 两者都在 `.env` 中。 ```bash METRONIX_MCP_API_KEY=... # 生成：openssl rand -hex 32 ``` 可选 - 仅当您运行 **Open WebUI** 或希望 Metronix 自身生成答案时： ```bash LLM_PROVIDER=custom LLM_PROVIDER_URL=https://your-llm-endpoint/v1 # 例如：https://api.deepseek.com/v1 LLM_PROVIDER_API_KEY=your-key LLM_PROVIDER_MODEL=deepseek-chat # 端点提供的模型 ``` ### 3. 启动（首次运行构建镜像 + 拉取嵌入模型，约 10-15 分钟） ```bash docker compose up -d --build ``` ### 4. 验证 ```bash curl http://localhost:8000/health ``` 健康的后端公开 REST API、OpenAI 兼容的 API 和 MCP 端点。如果您已安装 KnowledgeBase-UI（例如 [http://localhost:3000](http://localhost:3000)），请使用您的 Metronix 凭证登录。 默认凭证： ```bash login: admin@metronix.local pass: metronix ``` ### 5. 快速验证 使用 REST API 或原生 MCP 流式 HTTP 接口验证完整的记忆生命周期（存储和检索）。 #### 选项 A：REST API **步骤 A — 身份验证（获取 JWT token）** 使用默认管理员凭证 （`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 ``` **步骤 B — 存储记忆** 记录用于智能体： - **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"}' ``` **步骤 C — 搜索/检索记忆** 并确认它返回： - **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"}' ``` #### 选项 B：MCP 接口（Python 客户端） MCP 使用有状态流（SSE 用于服务器→客户端）和 HTTP POST 用于客户端→服务器，因此 与 `/mcp` 交互的标准方式是官方 `mcp` SDK 或 MCP 客户端（Cursor、 Claude Desktop，…）。端到端示例锻炼真实工具 (`metronix_memory_store` 和 `metronix_memory_search`）： ```python import asyncio from mcp import ClientSession from mcp.client.streamable_http import streamablehttp_client async def main(): # 如果 `.env` 中设置了 METRONIX_MCP_API_KEY，请将其作为 Bearer token 传递： # headers = {"Authorization": "Bearer <your-mcp-key>"} 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("通过 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_res.content[0].text) print("\n通过 MCP 检索记忆...") search_res = await session.call_tool("metronix_memory_search", { "query": "python logging", "agent_id": "agent-xyz", "workspace_id": "MTRNIX", }) print("搜索结果：", search_res.content[0].text) if __name__ == "__main__": asyncio.run(main()) ``` 运行它：确保后端启动 (`docker compose up -d`)，安装 SDK （`pip install mcp`），然后运行脚本（`python mcp_client_test.py`）。 **下一步：** - [install.md](install.md) — 完整安装信息：前提条件、Open WebUI、端口和故障排除。 - [connecting_to_agent.md](connecting_to_agent.md) — 通过 MCP 连接智能体并为其提供 持久记忆。 - [prompts.md](prompts.md) — 智能体设置提示，准备粘贴。 --- ## 选择你的运行时指南 后端运行后，首先使用通用 MCP 设置指南，然后选择您实际要使用的客户端或运行时。 **第一步：** [连接到智能体](connecting_to_agent.md) — 自包含的 MCP 设置提示，适用于任何智能体运行时。运行此提示，您的智能体可以自动配置 Metronix Memory。 **然后选择你的集成**（完整列表见 [docs/README.md](docs/README.md#runtime-guides)): - [Hermes 智能体](docs/integrations/hermes-agent.md) - [OpenClaw](docs/integrations/openclaw.md) - [Cursor](docs/integrations/cursor.md) - [Claude Desktop](docs/integrations/claude-desktop.md) - [Ollama + GLM 或 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 控制台（KB Admin） 可选的 **KB Admin 控制台** 是用于管理 Metronix 的开源 Web UI：添加和 同步 **数据连接器**（Jira、Confluence、GitHub、Google Drive、Notion、Slack）、注册 **聊天机器人通道**（Telegram、Discord、Slack）、上传文件，并查看服务和数据库 健康状况。它仅用于展示 - 所有内容都通过 `metronix-core` REST API 进行。 它作为可选服务提供，使用 `kb` Docker Compose 配置文件： ```bash docker compose --profile kb up -d --build # → http://localhost:3000 ``` 参见 [frontend/README.md](frontend/README.md) 以获取开发、构建和配置详细信息。 > 完整的 **控制中心**（agent registry、workflow builder、memory inspector、 FinOps）是单独的产品，不属于此存储库。 --- ### 演示：摄取冲刺 backlog 并查询 快速端到端检查，验证 Metronix 摄取附件文件并从内存中回答： 1. **连接一个智能体** 到 Metronix MCP（参见 [连接到智能体](connecting_to_agent.md)）。 2. **附加示例冲刺 backlog** — [examples/tasks.multi-agent-demo.json](examples/tasks.multi-agent-demo.json) — 并要求智能体将其摄取到 Metronix（通过 KB Admin 上传 UI、上传 API 或智能体的 `metronix_`* 内存工具）。 3. **提问：** > 根据 Metronix 记忆：开发团队的主要任务重点是什么？ 智能体应从摄入的知识中回答 - Sprint 14（**编排和可靠性**），正在进行的工作包括编排器候选版本、监督循环、智能体消息传递、共享内存压缩、观测性和两个开放的阻塞点（LLM 供应商合同和安全签批）。 您也可以在 KB Admin 控制台（**来源 → 上传**）中上传相同的文件，而不是在聊天中附加。 --- ## 快速参考 ### 开发命令 ```bash make dev # uvicorn --reload make test # pytest 单元测试 make lint # ruff check + 格式检查 make typecheck # mypy src/metronix/ make migrate # alembic upgrade head make eval # 搜索质量评估 ``` 有关架构和产品边界，请参阅 [docs/reference/architecture.md](docs/reference/architecture.md) 和 [docs/product/open-core-boundaries.md](docs/product/open-core-boundaries.md)。 **Hermes 用户：** Metronix Memory 作为 **MCP 服务器** 集成，而不是 Hermes 原生 记忆提供程序。参见 [Hermes 智能体指南](docs/integrations/hermes-agent.md). ### 外部端口 `docker-compose.yml` 中的外部端口： | 服务 | 端口 | | --------------- | ------- | | API | `8000` | | PostgreSQL | `5433` | | Qdrant HTTP | `6335` | | Qdrant gRPC | `6336` | | Neo4j HTTP | `7475` | | Neo4j bolt | `7688` | | Redis | `6380` | | Ollama | `11435` | | SPLADE | `8080` | | 嵌入代理 | `8002` | | Open WebUI | `3080` | ### 重要网址 | 界面 | URL | | --------------------- | --------------------------------------------------------------------------------- | | API 健康检查 | `http://localhost:8000/health` | | REST API | `http://localhost:8000/api/v1/*` | | MCP 端点 | `http://localhost:8000/mcp` (`metronix-full-api` / `metronix-core:8000` + `/mcp`) | | OpenAI 兼容 API | `http://localhost:8000/v1` | | KB Admin 控制台 | `http://localhost:3000` (配置文件 `kb`) | | Open WebUI | `http://localhost:3080` (配置文件 `openwebui`) | 使用以下命令： ```bash docker compose logs metronix-core docker compose down docker compose up -d --build --force-recreate ``` --- ## 文档 - [install.md](install.md) - 完整安装：前提条件、提供商、端口、故障排除。 - [frontend/README.md](frontend/README.md) - KB Admin 控制台：运行、构建、配置。 - [connecting_to_agent.md](connecting_to_agent.md) - 通过 MCP 连接智能体（基于提示或手动）。 - [prompts.md](prompts.md) - 智能体设置提示，准备粘贴。 - [docs/README.md](docs/README.md) - 文档索引。 - [docs/MCP_API.md](docs/MCP_API.md) - MCP 工具参考。 - [docs/API.md](docs/API.md) - REST API 参考。 - [docs/reference/api-openai-compat.md](docs/reference/api-openai-compat.md) - OpenAI 兼容 API 参考。 - [docs/product/legacy.md](docs/product/legacy.md) - 旧版和兼容性接口。 - [docs/product/open-core-boundaries.md](docs/product/open-core-boundaries.md) - 开源边界。 - [docs/benchmarks/longmemeval.md](docs/benchmarks/longmemeval.md) - LongMemEval-S 智能体记忆基准。 --- ## Metronix 对比 请参阅 [docs/reference/architecture.md](docs/reference/architecture.md) 和 [docs/product/open-core-boundaries.md](docs/product/open-core-boundaries.md)。 ### 对比向量数据库 | | 向量数据库 | Metronix | | ------------------ | -------------- | ------------------------------------- | | 存储向量 | 是 | 是，通过内部使用Qdrant | | 稀疏检索 | 通常为附加功能 | 内置SPLADE稀疏检索 | | 知识图谱 | 否 | Neo4j图谱上下文 | | 文档摄入 | 自带 | 包含连接器和处理器 | | 代理内存 | 否 | 内置内存记录和生命周期 | | MCP原生 | 否 | 内置MCP服务器 | 如果你从头开始构建自定义RAG堆栈，请单独使用向量数据库。如果你希望在一个系统中实现摄入、检索、图谱上下文、内存和代理访问，请使用Metronix。 ### 对比RAG框架 | | RAG框架 | Metronix | | -------------------- | ---------------- | -------------------------------------------------- | | RAG管道 | 需要自行构建 | 内置且可配置 | | 连接器 | 社区集成 | 原生连接器框架 | | 代理内存 | 需要额外服务 | 内置 | | API服务器 | 需要自行构建 | 包含REST、OpenAI兼容接口和MCP接口 | | 首个答案时间 | 数天或数周 | 单个Docker Compose栈 | RAG框架提供构建块，而Metronix提供用于代理知识和内存的运营后端。 ### 对比代理内存平台 | | 内存平台 | Metronix | | -------------------------- | --------------- | ---------------------------- | | 持久内存 | 是 | 是 | | 混合RAG | 通常有限 | 密集 + SPLADE + 图谱 | | 企业数据连接器 | 通常有限 | 包含连接器框架 | | 自托管部署 | 各不相同 | Docker Compose首选 | | MCP工具 | 各不相同 | 内置MCP服务器 | ## 功能 ### 混合RAG - 密集向量 + SPLADE稀疏向量 + Neo4j图谱上下文。 - 查询扩展、分类、重排序和来源多样性。 - 基于来源的答案，附带引用。 ### 连接器和摄入 - 用于Confluence、Jira、Notion、GitHub、Google Drive、Slack历史记录和本地文件的原生连接器框架。 - 用于直接摄入的文件上传API。 - 用于存储和同步外部来源的MCP工具。 ### 代理内存 - `fact`、`preference`和`pinned`内存记录。 - 工作空间和代理范围。 - 审查队列、快照、健康检查和新鲜度生命周期支持。 ### Hermes内存：重要区别 如果你正在使用 **Hermes Agent**，请勿从Hermes的“内存提供者”屏幕开始，并期望Metronix出现在那里。 Hermes目前有两种不同的集成概念： - **内存提供者** — Hermes原生提供者插件，如`honcho`、`mem0`、`hindsight`等，通过Hermes自己的内存设置流程配置 - **MCP服务器** — Hermes可以调用的外部后端，作为工具 **Metronix当前作为MCP服务器与Hermes集成，而不是作为Hermes原生内存提供者插件。** 这意味着： - 当你希望Hermes通过`metronix_search_fast`、`metronix_memory_search`和`metronix_memory_store`等MCP工具搜索知识库或读写内存时，请使用Metronix - 当你特别希望使用Hermes内置提供者插件系统时，请使用Hermes内存提供者 - 如果你希望使用Hermes原生内存和Metronix作为更丰富的外部知识和内存后端，请同时使用两者 **今日推荐路径：** 通过`/mcp`将Hermes连接到Metronix。 参见： - **[Hermes集成指南](docs/integrations/hermes.md)** — Hermes的精确MCP设置（包括基于提示的设置所需的工具权限） - **[Hermes内存提供者文档](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory-providers)** — Hermes对“内存提供者”的理解 - **[Hermes工具](https://hermes-agent.nousresearch.com/docs/user-guide/features/tools)** — 启用`file`、`terminal`和`code_execution`（如果缺失） ## 贡献 Metronix Core是开源的。欢迎提交错误报告、添加连接器、改进文档和有针对性的拉取请求。 参见 [CONTRIBUTING.md](CONTRIBUTING.md)。 ## 星历史 <a href="https://www.star-history.com/?repos=mtrnix%2Fmetronix-memory&type=timeline&logscale=&legend=top-left"> <picture> <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=mtrnix/metronix-memory&type=timeline&theme=dark&legend=top-left" /> <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=mtrnix/metronix-memory&type=timeline&legend=top-left" /> <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=mtrnix/metronix-memory&type=timeline&legend=top-left" /> </picture> </a> ## 许可证 Apache License 2.0。参见 [LICENSE](LICENSE)。