marm-memory

align="center"> <picture> <img src="https://raw.githubusercontent.com/Lyellr88/marm-memory/MARM-main/assets/marm-logo.png" alt="MARM：为AI智能体提供持久化本地内存的MCP服务器" width="800" height="200"> </picture> <h1 align="center">MARM: 面向MCP客户端的本地优先持久化多智能体内存层 v2.20.0</h1> [](https://github.com/Lyellr88/marm-memory/blob/MARM-main/LICENSE) [](https://www.python.org/) [](https://fastapi.tiangolo.com/) [](https://hub.docker.com/r/lyellr88/marm-mcp-server) [](https://pepy.tech/projects/marm-mcp-server) [](https://pypi.org/project/marm-mcp-server/) [](https://registry.modelcontextprotocol.io/?q=marm-mcp) [](https://discord.gg/nhyJWPz2cf) [](https://github.com/Lyellr88/marm-memory/actions/workflows/publish-mcp.yml) [](https://github.com/Lyellr88/marm-memory/security/code-scanning) [](https://glama.ai/mcp/servers/Lyellr88/marm-memory) > 欢迎贡献！浏览 [开放问题](https://github.com/Lyellr88/marm-memory/issues) 开始贡献，或加入 [MARM Discord](https://discord.gg/nhyJWPz2cf) 分享工作流，获取安装帮助，并与其他开发者交流。 </div> ## 目录 - [为什么选择MARM MCP](#为什么选择MARM-MCP) - [性能和扩展基准](#性能和扩展基准) - [快速入门](#快速入门) - [完整的MCP工具套件](#完整的MCP工具套件) - [使用MARM：对话，而非调用工具](#使用MARM-对话-而非调用工具) - [理解MARM内存](#理解MARM内存) - [知识图谱：代码与概念](#知识图谱-代码与概念) - [MARM仪表盘](#MARM仪表盘) - [架构与内部机制](#架构与内部机制) - [故障排除](#故障排除) - [贡献](#贡献) - [项目文档](#项目文档) ## 为什么选择MARM MCP **您的AI会忘记一切。而MARM MCP不会。** Claude Code、Codex、Gemini、Qwen、Cursor、VS Code智能体等所有MCP客户端都共享同一个内存服务器，这样决策、上下文、笔记本和代码结构在会话、智能体和项目之间得以保存。跨会话上下文是关键：长期运行的多智能体工作不会因为每个智能体都记住相同的历史而失效。 MARM围绕三个核心功能构建：**7种核心内存工具**用于日常智能体上下文，**5种代码图工具**用于仓库智能，**2种概念图工具**将存储的记忆转换为可查询的知识图谱。所有14种工具都通过HTTP和STDIO传输捆绑在一起。服务器负责这些工具的繁重工作：协议交付、混合语义+全文检索、序列化写入、速率限制预设、写入时合并、智能体辅助压缩和延迟图启动。智能体获得一个紧凑的内存工作流，以及代码库和概念查找功能，而无需重新阅读整个项目或用重复的上下文淹没模型。 ### 工作原理 | 层 | 功能 | 重要性 | |-------|--------------|----------------| | **内存模型** | 会话、结构化日志、笔记本、摘要和语义记忆 | 使项目历史可搜索，而不是困在一次聊天中 | | **扩展层** | SQLite WAL模式、连接池、序列化写入队列和HTTP速率限制预设 | 让一个服务器支持单用户、多智能体工作和类似集群的突发 | | **智能层** | FTS过滤器、语义重新排序、有限语义回退、自动分类、写入时合并和压缩候选 | 保持回忆在内存增长时仍然有用，而不是让重复项堆积 | | **代码图层** | 仓库索引、符号查找、调用跟踪、架构概述和变更影响分析 | 在不重新阅读整个代码库的情况下，为智能体提供项目结构 | | **概念图层** | 从存储的记忆中提取实体和关系，并链接回代码图 |之间连接决策、错误、工具和人员，而不是将它们留作平淡的文本 | | **令牌层** | 轻量级7工具核心表面（工具总计），检索前的语义重新排序重复数据删除回忆时减少发送到模型的令牌，并且随着内存扩展，成本保持可预测 | | **部署层** | Pip、Docker、STDIO、`--swarm`、`--swarm-max`和`--trusted` | 允许您运行私有本地内存或共享多智能体内存，并具有相同的MCP表面 | 参见 [性能和扩展基准](#性能和扩展基准)，获取检索延迟、并发性和写入成本的数字，并参见 [架构与内部机制](#架构与内部机制)，了解每层的机制。 ### 立即开始 **推荐：使用`marm-init`进行引导设置** 安装MARM最简单的方法是让您的智能体与您一起进行设置。`marm-init`将通常的MCP设置混乱变成了一个有引导的对话：Python或Docker，HTTP或STDIO，本地或远程服务器，API密钥，配置路径，仪表盘启动和多智能体链接，适用于Claude、Codex、Gemini、Qwen、Cursor、VS Code等MCP客户端。无需在安装文档中查找，无需猜测哪个配置文件是客户端使用的，也无需为每个智能体重写相同的连接。 ```bash npx degit Lyellr88/marm-memory/skills ``` 然后告诉您的智能体：**“使用marm-init技能设置MARM。”** **手动pip安装** ```bash pip install marm-mcp-server ``` | 如果你是... | 启动服务器 | 连接您的MCP客户端 | |---------------|------------------|-------------------------| | **独立开发者/研究人员** | `python -m marm_mcp_server` | `"agent" mcp add --transport http marm-memory http://localhost:8001/mcp` | | **私有本地STDIO用户** | `marm-mcp-stdio` | `"agent" mcp add --transport stdio marm-memory-stdio marm-mcp-stdio` | | **多个智能体共享内存** | `python -m marm_mcp_server --swarm` | `"agent" mcp add --transport http marm-memory http://localhost:8001/mcp` | | **私有高量集群** | `python -m marm_mcp_server --swarm-max` | `" mcp add --transport http marm-memory http://localhost:8001` | | **可信私有实验室/服务器** | `python -m marm_mcp_server -- | `"agent" add --transport http http://localhost:/mcp` | ## 性能和扩展基准 MARM针对快速回忆进行了优化，即使在内存增长和长期记忆在后台被分割时也是如此。 ### 1. 检索延迟扩展 | 会话大小（$N$） | 最小延迟 | 中位数延迟 | 95%延迟 | | :--- | :--- | :--- | :--- | | **$N = 100$** | 12.3毫秒 | 13.8毫秒 | 15.0毫秒 | | **$N = 500$** | 13.3毫秒 | 14.1毫秒 | 16.4毫秒 | | **$N = 1,000$** | 14.5毫秒 | 16.2毫秒 | 17.1毫秒 | | **$N = 2,000$** | 15.9毫秒 | 18.4毫秒 | 20.8毫秒 | | **$N = 4,000$** | 17.6毫秒 | 20.8毫秒 | 22.5毫秒 | ### 2. 编码器+并发性 - **冷模型加载：** `972毫秒` - **热编码：** 中位数`10.3毫秒`，95%`11.2毫秒` - **并发回忆：** 10次收集的回忆在`394.7毫秒`内完成，而串行则为`436.6毫秒`。当前路径故意序列化共享编码器/SQLite工作，因此在负载下稳定，而不是真正的并行加速。 ### 3. 写入时摄入成本 - **关闭合并：** 中位数`10.3毫秒`，95%`11.6毫秒` - **开启合并：** 中位数`42.0毫秒`，95%`46.3毫秒` - **权衡：** 写入时重复数据删除/聚类增加了`4.1倍`的中位数成本，因此回忆保持快速和清洁。 ### 4. 混合搜索扩展 | 会话大小（$N$） | 纯语义 | 生产混合 | FTS过滤器->重新排序 | 速度提升 vs 纯粹 | | :--- | :--- | :--- | :--- | :--- | | **$N = 100$** | 4毫秒 | 15.1毫秒 | 2.2毫秒 | 1.1倍 | | **$N = 1,000$** | 23.6毫秒 | 16.2毫秒 | 2.7毫秒 | 8.8倍 | | **$N = 4,000$** | 93.8毫秒 | 18.3毫秒 | 4.9毫秒 | 19.0倍 | | **$N = 10,000$** | 242.7毫秒 | 19.7毫秒 | 5.4毫秒 | 45.1倍 | 基准测试使用了一个一次性实际SQLite数据库和基于`all-MiniLM-L6-v2`的实时fastembed编码器在本地硬件上运行。重现它们：[`marm-mcp-server/scripts/bench_hotpath.py`](marm-mcp-server/scripts/bench_hotpath.py) ### 5. 与竞争对手比较：架构 MARM针对特定领域：MCP连接的编码智能体的本地优先内存，而非通用个性化内存或完整的智能体运行时。以下是它与AI智能体内存中已确立的名称在架构上的不同之处： | | MARM | Mem0 | Letta (MemGPT) | Zep / Graphiti | agentmemory | |---|---|---|---|---|---| | **类型** | 内存引擎，MCP原生 | 内存层API | 完整的智能体运行时 | 时间知识图谱 | 内存引擎，MCP原生 | | **所需基础设施** | 无需单独的数据服务（嵌入式SQLite） | 向量数据库（Qdrant/pgvector） | Postgres + 向量数据库 | Neo4j | 单独的`iii-engine`运行时 | | **部署** | 默认本地优先；Docker用于共享/远程 | 云API或自托管 | 自托管或云 | 云或自托管 | 本地优先 | | **检索模型** | 混合：FTS5 BM25精确通道+语义重新排序 | 向量+图+键值 | 向量存档存储+智能体管理的核心内存 | 时间知识图谱（事实有效性窗口） | BM25 + 向量 + 图（RRF融合） | | **写入捕获** | 来自连接智能体的显式工具调用 | 显式`add()`调用（某些集成自动提取） | 智能体自我编辑其内存 | 显式API调用 | 基于钩子，自动（无需显式调用） | | **代码结构感知** | 捆绑代码图+概念图，与内存融合 | 未内置 | 未内置 | 未内置 | 未内置（与单独项目配对） | | **框架锁定** | 无（任何MCP客户端） | 无 | 高（必须在Letta内运行） | 无 | 无（任何MCP客户端） | **免责声明和准确性：**竞争格局迅速演变。上述矩阵反映了截至2026年第三季度核心架构特征，基于公开文档和README，而不是对每个系统的内部测试。如果关于替代框架的任何数据点已更改或被误表示，请打开问题或提交拉取请求以更新表格。我们积极欢迎同行维护者的更正。 ## 🚀 快速入门（MCP的HTTP和STDIO） **手动pip安装** ```bash pip install marm-mcp-server ``` | 如果你是... | 启动服务器 | 连接您的MCP客户端 | |---------------|------------------|-------------------------| | **独立开发者/研究人员** | `python -m marm_mcp_server` | `"agent" mcp add --transport http marm-memory http://localhost:8001/mcp` | | **私有本地STDIO用户** | `marm-mcp-stdio` | `"agent" mcp add --transport stdio marm-memory-stdio marm-mcp-stdio` | | **多个智能体共享内存** | `python -m marm_mcp_server --swarm` | `"agent" mcp add --transport http marm-memory http://localhost:8001/mcp` | | **私有高吞吐量集群** | `python -m marm_mcp_server --swarm-max` | `"agent" mcp add --transport http marm-memory http://localhost:8001/mcp` | | **可信私有实验室/服务器** | `python -m marm_mcp_server --trusted` | `"agent" mcp add --transport http marm-memory http://localhost:8001/mcp` | ### 使用此快速规则选择您的设置 - 本地HTTP/STDIO = 最快的单机设置。 - Docker HTTP = 共享/始终在线的服务器（需要密钥）。 - Docker STDIO = 私有容器化本地使用（无需HTTP密钥）。 **集群/多智能体注意：** 默认启用写入队列，以通过一个工作线程序列化内存写入。对于共享HTTP部署，在启动服务器时使用`--swarm`（200 RPM）或`--swarm-max`（600 RPM）。`--trusted`完全禁用速率限制，适用于私有部署。STDIO仍然是私有单智能体/本地使用的最佳选择。参见[集群和多智能体预设](#集群和多智能体预设)，获取完整表格。 <details> <summary><strong>本地pip HTTP（零配置）</strong></summary> > “agent”指的是claude、gemini、grok、qwen或任何MCP客户端。Codex使用--url而不是--transport来添加MCP工具。 ```bash pip install marm-mcp-server python -m marm_mcp_server # 卡在客户端设置？打开一个Q&A线程：https://github.com/Lyellr88/marm-memory/discussions # 大多数智能体使用此--transport命令 "agent" mcp add --transport http marm-memory http://localhost:8001/mcp codex mcp add marm-memory --url http://localhost:8001/mcp ``` 默认pip/本地启动是零配置的：MARM绑定到localhost，不需要密钥，除非您使用`SERVER_HOST=0.0.0.0`将其暴露出来。 </details> <details> <summary><strong>本地pip STDIO</strong></summary> ```bash pip install marm-mcp-server python -m marm_mcp_server.server_stdio # 大多数智能体使用此--transport命令 "agent" mcp add --transport stdio marm-memory-stdio marm-mcp-stdio codex mcp add marm-memory-stdio -- marm-mcp-stdio ``` 将`marm-mcp-stdio`替换为`python -m marm_mcp_server.server_stdio`，如果使用虚拟环境或基于路径的设置。与Claude Code、Cursor、VS Code、Qwen和Gemini CLI有效。STDIO保持为单个本地进程，无需端口和API密钥，并暴露相同的14种工具作为HTTP。 </details> <details> <summary><strong>本地Python集群模式（HTTP和STDIO）</strong></summary> 使用HTTP时，多个智能体需要共享一个实时MARM服务器。STDIO仍然是私有单智能体使用的最佳选择，因为每个客户端都拥有自己的本地进程。 ```bash # HTTP共享服务器，普通多智能体使用 python -m marm_mcp_server --swarm # HTTP共享服务器，私有集群负载更高 python -m marm_mcp_server --swarm-max # HTTP可信私有实验室/服务器，禁用速率限制 python -m marm_mcp_server --trusted # STDIO保持无密钥/私有，不使用集群标志 marm-mcp-stdio ``` </details> --- <details> <summary><strong>Docker HTTP（需要密钥）</strong></summary> > Docker HTTP需要API密钥，因为它将MARM暴露为网络服务器；而STDIO则保持在客户端进程本地，不需要密钥。 ```bash # ：生成密钥（不要在<>周围添加密钥） docker run lyellr88/marm-mcp-server:latest --generate-key # ：运行服务器 lyellr88/marm-server:latest docker run -d --name marm-mcp-server \ p 127.0.0.1:8001:8001 \ -e SERVER_HOST=0.0.0.0 \ e MARM_API_KEY= -v ~/.:/home/marm/.m lyellr88/mcp-server:latest # ：连接客户端 "agent" mcp add --transport http marm-memory http://localhost:8001/mcp --header "Authorization: Bearer your" # PowerShell：在启动Codex之前设置此环境变量 $env:MARM_API_KEY="your-generated-key" codex mcp add marm-memory --url http://localhost:8001/mcp --bearer-token-env-var MARM_API_KEY # 快速身份验证测试 curl -i -H "Authorization: Bearer $env:MARM_API_KEY" http://127.0.0:8001/mcp ``` `--bearer-token-env-var环境变量名称，而不是原始密钥。在设置 `$env:MARM_API_KEY，从同一shell启动或重启Codex。对于本地Docker烟雾测试，`MARM_API_KEY=test` 就可以了，避免了shell转义问题；为实际部署使用生成的密钥。来自烟雾测试 `GET /mcp` 的 `406 Not Acceptable` 表示身份验证已达到MCP端点；`401 Unauthorized` 表示密钥丢失或不匹配。 </details> <details> <summary><strong>Docker HTTP集群模式</strong></summary> ```bash # --swarm：写入队列开启，200 RPM - 推荐用于多智能体共享服务器 docker run -d --name marm-mcp-server \ -p 127.0.0.1:8001:8001 \ -e SERVER_HOST=0.0.0.0 \ -e MARM_API_KEY=your-generated-key \ -v ~/.marm:/home/marm/.marm \ lyellr88/marm-mcp-server:latest --swarm ``` </details> <details> <summary><strong>Docker图形索引：挂载仓库</strong></summary> Docker图形工具在容器内运行，因此如果您在 `docker run` 时不挂载它们，它们就无法看到主机路径。 ```powershell $env:MARM_API_KEY="test" ``` # 第二部分 ## 第二个 `-v` 行挂载您的存储库；调整主机路径到您的项目 ```bash docker run -d --name marm-mcp-server ` -p 127.0.0.1:8001:8001 ` -e SERVER_HOST=0.0.0.0 ` -e MARM_API_KEY=$env:MARM_API_KEY ` -v ~/.marm:/home/marm/.marm ` -v C:\Users\lyell\Desktop\marm-memory:/workspace/marm-memory ` lyellr88/marm-mcp-server:latest ``` 然后索引容器路径，而不是 Windows 主机路径： ```text marm_graph_index(repo_path="/workspace/marm-memory") ``` 图形工具必须使用容器路径。无法将挂载添加到已经运行的容器；当您需要 Docker 图形索引时，请停止并重新启动带有存储库挂载的容器。 </details> <details> <summary><strong>Docker STDIO（无 HTTP 密钥）</strong></summary> Docker STDIO 包含相同的内置 marm-graph 工具；不需要额外的镜像或安装步骤。 ```bash docker run --rm -i \ -v ~/.marm:/home/marm/.marm \ --entrypoint python \ lyellr88/marm-mcp-server:latest \ -m marm_mcp_server.server_stdio ``` </details> --- <details> <summary><strong>支持说明</strong></summary> - Docker HTTP 需要密钥；Docker STDIO 不需要。 - 如果您遇到 `401`，请验证密钥匹配并在环境变量更改后重启客户端。 - 有关完整的密钥设置、轮换和故障排除，请参阅：[INSTALL-DOCKER.md](docs/INSTALL-DOCKER.md) </details> ### 连接您的客户端 启动服务器（`python -m marm_mcp_server`），然后连接您的客户端。下面每个块都假设默认的本地安装（无密钥）。对于 Docker 或公开的服务器，请添加所示的 `Authorization: Bearer` 头。 <details> <summary><strong>Claude 代码</strong></summary> ```bash claude mcp add --transport http marm-memory http://localhost:8001/mcp ``` Claude Code 支持 HTTP、SSE 和 STDIO 通过 `claude mcp add`；使用 HTTP for MARM。对于 STDIO：`claude mcp add --transport stdio marm-memory-stdio marm-mcp-stdio`。 </details> <details> <summary><strong>VS Code / GitHub Copilot 代理</strong></summary> 在工作区的 `.vscode/mcp.json` 中添加。使用 `marm-memory-local` 进行直接 Python 安装；使用 `marm-memory-docker` 进行 Docker 或公开/密钥模式。 ```json { "inputs": [ { "type": "promptString", "id": "marm-api-key", "description": "Docker 或公开服务器模式的 MARM API 密钥", "password": true } ], "servers": { "marm-memory-local": { "type": "http", "url": "http://localhost:8001/mcp" }, "marm-memory-docker": { "type": "http", "url": "http://localhost:8001/mcp", "headers": { "Authorization": "Bearer ${input:marm-api-key}" } } } } ``` 打开 `.vscode/mcp.json`，点击您要启动的服务器上方的 **Start**，然后使用 Copilot Agent 或任何使用 VS Code 原生 MCP 注册表的扩展。 </details> <details> <summary><strong>Cursor</strong></summary> 在工作区的 `.cursor/mcp.json` 中添加。Cursor 使用 `mcpServers`，而不是 VS Code 的 `servers` 根目录。 ```json { "mcpServers": { "marm-memory-local": { "type": "http", "url": "http://localhost:8001/mcp" }, "marm-memory-docker": { "type": "http", "url": "http://localhost:8001/mcp", "headers": { "Authorization": "Bearer ${env:MARM_API_KEY}" } } } } ``` 对于 Docker/密钥模式，在环境中设置 `MARM_API_KEY` 后启动 Cursor。 </details> <details> <summary><strong>Codex CLI</strong></summary> Codex 使用 `codex mcp add` 或 `~/.codex/config.toml` 中的 TOML 配置（Windows 上为 `%USERPROFILE%\.codex\config.toml`）。 ```bash # 直接 Python 安装 - 不需要密钥 codex mcp add marm-memory --url http://localhost:8001/mcp # Docker 或 SERVER_HOST=0.0.0.0 - 需要密钥（首先在 shell 中设置 MARM_API_KEY） codex mcp add marm-memory --url http://localhost:8001/mcp --bearer-token-env-var MARM_API_KEY ``` ```toml [mcp_servers."marm-memory"] url = "http://localhost:8001/mcp" enabled = true bearer_token_env_var = "MARM_API_KEY" ``` </details> <details> <summary><strong>Gemini CLI</strong></summary> ```bash # 直接 Python 安装 - 不需要密钥 gemini mcp add --transport http marm-memory http://localhost:8001/mcp # Docker 或 SERVER_HOST=0.0.0.0 - 需要密钥 gemini mcp add --transport http marm-memory http://localhost:8001/mcp --header "Authorization: Bearer your-generated-key" ``` 等效的 `~/.gemini/settings.json`（用户范围）或项目 `.gemini/settings.json`： ```json { "mcpServers": { "marm-memory": { "httpUrl": "http://localhost:8001/mcp", "headers": { "Authorization": "Bearer your-generated-key" } } } } ``` </details> <details> <summary><strong>Qwen 代码</strong></summary> ```bash # 直接 Python 安装 - 不需要密钥 qwen mcp add --transport http marm-memory http://localhost:8001/mcp # Docker 或 SERVER_HOST=0.0.0.0 - 需要密钥 qwen mcp add --transport http marm-memory http://localhost:8001/mcp --header "Authorization: Bearer your-generated-key" ``` 等效的 `.qwen/settings.json`（项目）或 `~/.qwen/settings.json`（用户）： ```json { "mcpServers": { "marm-memory": { "httpUrl": "http://localhost:8001/mcp", "headers": { "Authorization": "Bearer your-generated-key" } } } } ``` </details> <details> <summary><strong>xAI / Grok 远程 MCP</strong></summary> xAI 从其自己的基础设施连接，因此 `localhost` 将不起作用。将 MARM 暴露在 HTTPS 后，并设置 `MARM_API_KEY`。 ```json { "type": "mcp", "server_url": "https://your-marm-domain.example.com/mcp", "server_label": "marm-memory", "authorization": "Bearer your-generated-key" } ``` </details> 完整平台演练、密钥设置和特定于操作系统的说明：[Windows](docs/INSTALL-WINDOWS.md#client-connections) · [Linux](docs/INSTALL-LINUX.md#client-connections) · [Docker/密钥模式](docs/INSTALL-DOCKER.md#client-connections) · [其他平台](docs/INSTALL-PLATFORMS.md) > 使用未列出的客户端？[打开问题](https://github.com/Lyellr88/marm-memory/issues/new/choose) 并让我们知道；客户端适配器是一个优先考虑的功能请求。 <details> <summary><strong>系统要求、数据位置和备份</strong></summary> **要求** - **Python**：3.10 或更高 - **SQLite3**：包含在 Python 中（不需要单独安装） - **存储**：~100MB 最低初始设置，根据内存数据库大小扩展 - **RAM**：512MB 最低（根据并发客户端和数据库大小而异） - **操作系统**：Windows、macOS、Linux **数据位置** - **位置**：`~/.marm/`（Linux/macOS）或 `%USERPROFILE%\.marm\`（Windows） - **内容**：包含所有记忆、会话和笔记本的 SQLite 数据库；概念图存在于其自己的 `~/.marm/index/` 数据库中 - **备份**：复制整个 `~/.marm/` 目录以保留所有数据 - **隐私**：所有内容都保留在您的机器上，无需云同步或外部存储 **验证安装** 使用 MARM 仪表板状态面板进行最简单的实时检查。它轮询 MCP 服务器健康端点，并显示可达性、版本、状态、延迟和上次检查时间。对于终端验证： ```bash curl http://localhost:8001/health ``` 预期输出包括服务器版本、功能可用性（语义搜索状态）、数据库连接状态和服务健康状态。 </details> ### MARM 演示 <https://github.com/user-attachments/assets/dabfe44f-689d-404f-a2c7-dcf8fa4ef0c1> MARM 为 AI 代理提供持久的长期记忆、共享的跨会话上下文、写入队列安全性、群集预设和混合语义 + 精确召回，以便命令、配置密钥和项目含义都保持可访问。 ## 完整的 MCP 工具套件（14 个工具） **💡 专业提示：** 您不需要手动调用这些工具！只需用自然语言告诉您的 AI 代理您想要什么： - *"Claude，将此会话记录为 'Project Alpha' 并将此对话添加为 '数据库设计讨论'"* - *"记住此代码片段以备后在笔记本中引用"* - *"搜索我们昨天讨论的身份验证问题"* AI 代理将自动使用适当的工具。手动工具访问适用于想要直接控制的强用户。 ### 🧠 核心记忆（7 个工具） | 工具 | 功能 | 关键参数 | |------|--------------|----------------| | `marm_smart_recall` | 混合召回：确切的配置键、命令和文件路径；语义重新排序用于自然语言查询 | `query`、`limit`、`session_name`、`search_all`、`detail=1/2/3`、`project`、`platform`、`exact_mode` | | `marm_log_entry` | 添加结构化的会话日志条目；路由和缓存维护由服务器处理 | `entry`、`session_name` | | `marm_log_show` | 显示所有条目和会话，并支持筛选 | `session_name` | | `marm_delete` | 删除日志会话、日志条目或笔记本条目 | `type`、`target`、`session_name` | | `marm_summary` | 缓存的、可粘贴的会话摘要，智能截断 | `session_name` | | `marm_notebook` | 可重用的指令和知识片段 | `action="add"\|"use"\|"show"\|"status"\|"clear"`、`name`、`data` | | `marm_compaction` | 代理辅助的内存清理，具有可审查的审计轨迹 | `action="status"\|"candidates"\|"review"\|"stage"\|"apply"\|"discard"` | ### 🕸️ 代码图（5 个工具） | 工具 | 功能 | 关键参数 | |------|--------------|----------------| | `marm_graph_index` | 将存储库索引到代码结构图中，检查状态或列出项目 | `repo_path`、`project` | | `marm_code_lookup` | 查找符号、文本模式或符号的源；代替 grep/glob | `kind="auto"\|"symbol"\|"text"\|"snippet"` | | `marm_graph_trace` | 跟踪函数的数据流和调用路径 | `direction`、`mode` | | `marm_graph_architecture` | 架构概览：模块、节点/边分解、模式 | `project` | | `marm_graph_impact` | 代码更改的辐射范围：git diff → 影响符号 + 风险 | `since`、`base_branch`、`depth` | ### 🧩 概念图（2 个工具） | 工具 | 功能 | 关键参数 | |------|--------------|----------------| | `marm_concept_build` | 从存储的记忆中提取实体和类型化关系 | `session_name`、`project` 或 `search_all=True`（一个必填） | | `marm_concept_recall` | 查询实体、关系和链接的代码符号 | `query`、`depth`（1-5）、`direction`、`project` | 所有 14 个工具都可在 HTTP 和 STDIO 上使用。在工具表面下，服务器自动处理生命周期设置、协议刷新、文档索引、日期上下文、摘要缓存维护、写入队列处理、项目/平台归属和健康检查；这些都不消耗代理的注意力或令牌。两个图形引擎在第一次使用时延迟启动，如果启动失败，从不阻塞 7 个核心内存工具。有关机制，请参见 [架构和内部](#architecture--internals)。 ## 使用 MARM：交谈，而不是调用工具 MARM 在内部处理生命周期工作。文档和会话状态在第一次实际工具调用时初始化，包装的文档被索引到 `marm_system` 内存命名空间中，并带有源文件哈希跟踪，以便您的代理可以从内存本身回答 MARM 使用问题。 ### 示例工作流：跨 AI 研究项目 一个现实的工作流，展示 MARM 的实际应用。**场景：** 您正在使用多个 AI 客户端研究新项目中的身份验证模式。 #### 阶段 1：路由会话（Claude） ``` markdown 您： "Claude，创建一个名为 'auth-research-2025-01' 的 MARM 会话" Claude 调用：marm_log_entry(entry="会话：auth-research") 结果：会话路由到 auth-research-[today]。MARM 生命周期/文档自动初始化。 ``` #### 阶段 2：捕获研究（Claude） ``` markdown 您： "总结 OAuth2 与 JWT 的 API 身份验证并保存它" Claude 调用：marm_log_entry(entry="研究：OAuth2 是基于令牌的，具有刷新周期，更适合委托访问。JWT 是无状态的，适用于微服务...", session_name="auth-research-2025-01") 结果：研究被捕获在活动会话日志中，并标记为摘要缓存刷新 ``` #### 阶段 3：添加可重用参考（Claude） ``` markdown 您： "将 JWT 验证代码片段保存到我的笔记本中，命名为 'jwt-validation-pattern'" Claude 调用：marm_notebook(action="add", name="jwt-validation-pattern", data="def verify_jwt(token)：\n # 验证逻辑...") 结果：可重用片段存储以供未来项目使用 ``` #### 阶段 4：回忆上下文（Gemini） ``` markdown 您： "Gemini，我们研究了哪些身份验证方法？激活 JWT 模式。" Gemini 调用：marm_smart_recall("身份验证模式", search_all=True) Gemini 调用：marm_notebook(action="use", names="jwt-validation-pattern") 结果：Gemini 看到以前的研究 + 有 JWT 代码作为上下文 ``` #### 阶段 5：合成和摘要（Qwen） ``` markdown 您： "Qwen，提取所有身份验证研究并创建摘要" Qwen 调用：marm_smart_recall("身份验证", session_name="auth-research-2025-01", limit=20) Qwen 调用：marm_summary(session_name="auth-research-2025-01") 结果：Qwen 从所有捕获的研究中生成实现指南 ``` #### 阶段 6：结束会话（Claude） ``` markdown 您： "记录最终决定 - 我们将为 API 使用 JWT，为用户身份验证使用 OAuth2" Claude 调用：marm_log_entry(entry="决定：API 身份验证使用 JWT，用户流程使用 OAuth2。理由：无状态 API + 委托用户访问", session_name="auth-research-2025-01") 结果：决策已记录，可供所有未来的 AI 客户端搜索 ``` **结果**：三个不同的 AI 客户端协同研究了一个主题，共享了洞察力和文档记录了决策。所有这些都无需向新的 AI 解释项目。 ### 高级模式 <details> <summary><strong>项目内存架构和知识库开发</strong></summary> ```txt 项目结构： ├── project-name-planning/ # 初始设计和需求 ├── project-name-development/ # 实现细节 ├── project-name-testing/ # QA 和调试笔记 ├── project-name-deployment/ # 生产部署 └── project-name-retrospective/ # 经验教训 ``` 知识库循环： 1. **捕获**：使用 `marm_log_entry` 进行结构化会话学习 2. **组织**：为知识领域创建主题会话 3. **合成**：定期 `marm_summary` 进行知识整合 4. **应用**：将摘要转换为 `marm_notebook(action="add", ...)` 条目 多 AI 协作：每个 AI 在其优势领域工作，使用 `marm_smart_recall` 建立在其他 AI 的工作基础上，然后协作会话结合洞察力。 </details> <details> <summary><strong>专业提示和最佳实践</strong></summary> - **会话命名**：包括 LLM 名称以进行交叉引用 - **战略日志记录**：关注关键决策、解决方案、发现、配置 - **全局搜索**：使用 `search_all=True` 搜索所有会话 - **自然语言搜索**：“身份验证问题与 JWT 令牌”优于“身份验证错误” - **分层召回深度**：`detail=1` 返回简短的摘要视图（~200 字符），`detail=2` 返回更大的上下文视图（~500 字符），`detail=3` 返回完整的内存内容 - **笔记本堆叠**：组合多个条目以实现复杂的工作流程 - **压缩**：让 MARM 显示压缩候选项，然后使用 `marm_compaction` 阶段、审查、应用或丢弃摘要 - **会话生命周期**：启动 → 工作 → 引用 → 审查暂存的压缩，当 MARM 询问时 </details> ## 理解 MARM 内存 两种搜索，两个非常不同的问题，一个工具： ```txt 用户：”我昨天讨论了机器学习算法“ MARM 搜索：找到关于“ML 模型”、“神经网络”、“AI 训练”的相关记忆 用户：”COMPACTION_TRIGGER_COUNT 设置是什么?“ MARM 搜索：找到确切的配置记忆，即使其他文本不同 ``` 第一个查询是关于**含义**，所以 MARM 使用局部向量嵌入重新排序候选项——一种类似 RAG 的语义搜索，无需托管向量数据库。第二个查询是**语法形状**（一个配置键），所以 MARM 自动检测并通过确定性精确匹配路由。这一精确检索通道是内存系统在演示中可行与能回答开发者实际问题的区别：配置键、CLI 标志、文件路径、API 名称、错误字符串。纯语义内存系统在这些查询中恰好失败。 <details> <summary><strong>召回管道的工作原理</strong></summary> MARM 使用 **过滤→重新排序混合召回** 加上精确检索通道： 1. **精确通道** (`exact_mode="auto"`，默认)：检测并通过确定性 FTS5 BM25 与 LIKE 回落路由配置键、CLI 标志、文件路径、API/工具名称、带点命名空间、HTTP 路由、URL 和引用的命令字符串。不涉及嵌入，结果稳定且字面。 2. **过滤→重新排序通道**：自然语言查询首先从 FTS 索引中提取有限的候选集（`FTS_CANDIDATE_LIMIT`，默认为 50），然后语义嵌入重新排序这些候选项以获取含义。保守的时间权重给予更新的记忆在匹配相同时适度的提升。 3. **有界语义回落**：当 FTS 覆盖较弱或无法使用时，MARM 回落到有界语义扫描（`RECALL_SCAN_LIMIT`）。如果响应包含 `recall_scan_truncated=true`，则回落达到上限；缩小会话/查询或提高环境变量以适应更大的存储。 4. **分段感知评分**：长记忆（大约 180 字以上）内部嵌入为重叠的分段行，召回将分段分数折叠回一个父记忆，使用最佳匹配的分段。重新排序通道和回落通道都感知分段。 这就是为什么召回延迟随着存储的增长保持几乎不变（如 [基准测试](#性能-缩放基准测试) 所示）：语义重新排序始终对有限集进行评分，而不是扫描每个嵌入。 **精确召回控制：** `exact_mode="auto"` 通常是正确的。使用 `exact_mode="exact"` 当查询必须匹配字面文本，如 `RECALL_SCAN_LIMIT`、`--generate-key` 或 `settings.py`。使用 `exact_mode="semantic"` 当语法形似的查询仍应被视为基于含义的召回。 </details> ### 记忆类型和分类 1. **上下文日志** - 自动分类的对话记忆 2. **手动条目** - 显式保存的重要信息 3. **笔记本条目** - 可重复使用的指令和知识 4. **会话摘要** - 压缩的对话历史 MARM 在写入时自动将内容分类为：**代码**（编程片段和技术讨论）、**项目**（工作对话和规划）、**书籍**（文学、学习材料、研究）和 **常规**（其他所有内容）。 ### 项目和平台归属 MARM 在记忆、日志条目和笔记本条目上存储可为空的 `project` 和 `platform` 列。项目从工作目录检测，平台从连接的客户端（Claude Code、VS Code、Cursor 等）检测；`MARM_PROJECT` 和 `MARM_PLATFORM` 覆盖检测。`marm_smart_recall(project=..., platform=...)` 在不更改默认未过滤行为的情况下限定召回，因此一个共享服务器可以容纳多个项目而不会相互污染。 ## 知识图谱：代码和概念 MARM 配备两个图谱系统，它们与内存存储互补：一个 **代码图谱**，它理解您的仓库结构，以及一个 **概念图谱**，它理解您存储的记忆内容。当两者都为同一个项目编制索引时，概念实体会链接到代码符号。 ### 代码图谱：仓库索引和代码查找 `marm-graph` 捆绑在两个传输中。它对仓库进行一次索引，然后让代理询问代码结构问题，而无需重复扫描文件： ```text 使用 marm_graph_index 索引此仓库。 然后在需要符号、文件或源代码片段时使用 marm_code_lookup。 使用 marm_graph_trace 获取调用路径，marm_graph_architecture 获取概览，marm_graph_impact 进行变更风险检查。 ``` 推荐的代理工作流程：索引一次，然后在广泛读取文件之前使用 `marm_code_lookup`，在调用者/被调用者或数据流上下文相关时使用 `marm_graph_trace`，在定位时使用 `marm_graph_architecture`，在风险 refactor 之前使用 `marm_graph_impact`。在有意义的代码更改后重新索引。一次图查询取代了数十次 grep/read 循环，这就是节省令牌的地方。 在底层，引擎是 [codebase-memory-mcp](https://github.com/DeusData/codebase-memory-mcp) （MIT），一个零依赖的静态二进制文件，它通过 tree-sitter 解析 158 种语言，并具有混合 LSP 类型解析功能，对于主要语言，它索引平均仓库的时间为秒级，结构查询的回答时间小于毫秒级。MARM 固定了一个特定的发布版本，在启动时验证其工具模式，并通过 5 个专注的 MCP 工具路由其 14 个上游工具，因此模型表面保持较小。图后端在第一次图工具使用时惰性启动，因此内存、日志、笔记本和摘要工具仍然快速启动。在 Docker 中，引擎二进制文件被烘焙到镜像中；本地 pip 安装在第一次图形使用时获取它（约 269MB，一次）。 **降级模式：** 如果图形引擎无法启动（第一次运行下载时没有网络，磁盘已满，模式漂移）或设置了 `GRAPH_ENABLED=false`，则图形工具返回 `{"status": "error", "message": "graph backend unavailable"}`，而其他 9 个工具正常工作。图形失败永远不会导致内存宕机。 ### 概念图谱：关于你的记忆 MARM 可以从您已经存储的记忆中提取知识图谱。`marm_concept_build` 在存储的记忆内容上运行实体和关系提取，生成类型化的实体（**概念、决策、模式、错误、工具、人员、组织**）通过类型化的关系（**修复、实现、依赖于、使用、导致、替换、扩展**）连接。`marm_concept_recall` 然后回答诸如： ```text marm_concept_recall(query="write queue") → 实体、其关系、链接的代码符号 marm_concept_recall(query="related to SQLite", depth=3) → 多跳遍历所有连接的内容 ``` 如何使用它： - **首先构建**：在 `session_name`、`project` 或 `search_all=True` 上调用 `marm_concept_build`。在构建至少运行一次后才有数据。构建是显式且按需的，而不是写入路径的实时钩子；在记录重要新记忆后重新运行。 - **设计限定**：每个构建都有限定行数（`CONCEPT_BUILD_ROW_CAP`，默认为 500），因此巨大的存储库无法将一个工具调用转换为失控的作业。 - **代码交叉链接**：当代码图谱已索引相同的项目时，匹配代码符号的概念实体将链接起来，将“我们决定什么”连接到“它在代码中的位置”。 - **可选依赖**：实际提取需要 `[concepts]` 额外（`pip install marm-mcp-server[concepts]` 加 `python -m spacy download en_core_web_sm`）。没有它，两个概念工具都保持注册并返回 `entities_extracted: 0` 而不是错误。基本安装不携带任何 spaCy 依赖。 - **隔离存储**：概念图谱存在于其自己的 SQLite 数据库（`~/.marm/index/marm_index.db`）中，其自己的连接池，因此概念图谱的写入永远不会阻塞或损坏生产内存数据库。 这填补了扁平内存搜索留下的跨会话结构差距：会话组织记忆，但概念图谱 *连接* 它们，因此“什么依赖于写入队列？”即使答案跨越三个不同代理的五个会话，也能得到回答。 ## MARM 仪表盘 一个用于浏览和管理 MARM 内存的本地 Web UI。它与 `marm-mcp-server` 捆绑在一起，并在 HTTP 服务器启动时挂载到 `/dashboard`： | 你能得到什么 | 它是如何工作的 | |-------------------|-------------| | 浏览/搜索/编辑所有记忆 | 直接访问同一个 `~/.marm/marm_memory.db` 的 SQLite 数据库 | | 管理会话和协议日志 | 在 `:8001` 上的 MCP 端口旁边打开 `http://localhost:8001/dashboard` | | 笔记本 CRUD 及内联编辑器 | 与 MCP 服务器相同的 `MARM_API_KEY` 身份验证模型 | | 删除所有并确认计数 | 包含在统一的 pip 包和 Docker 镜像中 | | 实时查看写入队列 | 从写入队列中提取实时数据 | | 实时服务器健康面板 | 轮询健康端点：可达性、版本、延迟、最后检查 | 启动 MARM HTTP，然后打开仪表盘： ```bash python -m marm_mcp_server # 浏览器：http://localhost:8001/dashboard ``` Docker 使用相同的统一镜像和密钥： ```bash docker run -d --name marm-mcp-server \ -p 127.0.0.1:8001:8001 \ -e MARM_API_KEY=your-key \ -v ~/.marm:/home/marm/.marm \ lyellr88/marm-mcp-server:latest # 浏览器：http://localhost:8001/dashboard ``` ## 架构和内部 以上所有内容都运行在少数几个刻意的机制上。本节是完整的地图，因此您（或您的代理）永远不必猜测服务器正在做什么。 ### 存储引擎 - **WAL 模式下的 SQLite**，位于 `~/.marm/marm_memory.db`，带有连接池（5 个连接）。WAL 在写入期间保持读取者不受阻塞，这在多个代理回忆时很重要，而一个写入者正在写入。 - **FTS5 全文索引** (`memories_fts`) 作为外部内容表在记忆表上，支持精确通道（BM25）和混合召回的过滤阶段。 - **分段存储**：超过 ~180 个字的记忆被分成重叠的 150 个令牌分段（50 个令牌重叠）在 `memory_chunks` 表中，每个分段都有自己的嵌入。召回分数分段并折叠到父记忆。 - **嵌入** 来自快速嵌入支持的 `all-MiniLM-L6-v2` 编码器，在第一次语义使用时惰性加载，并在序列化后锁定以防止并发编码相互损坏。如果编码器不可用，写入仍然成功；记忆没有嵌入，直到加载。 - **概念图谱有自己的数据库** (`~/.marm/index/marm_index.db`) 和自己的连接池，重用相同的连接池实现，但从不与内存存储共享连接。刻意隔离：实验性图构建不能阻塞生产 WAL。 ### 写入路径 - **序列化写入队列** （默认启用）：所有内存写入通过一个内部异步工作线程，消除多代理负载下的 SQLite 编写者争用。队列是通用的；压缩应用通过相同的 worker，因此无论哪个子系统正在写入，都只有一个写入者。`MAX_QUEUE_SIZE` 限制它。 - **写入时间合并** （可选，`CONSOLIDATION_ENABLED=1`）在内存落地前运行两个层： - **层 1，精确重复消除**：标准化内容的 SHA-256 哈希在会话内检查；哈希命中在实际内容验证之前被验证以防止重复，如果哈希冲突，则存储新行而不是静默合并不同内容。 - **层 2，语义合并**：超过 `CONSOLIDATION_THRESHOLD` 余弦相似度的近似重复项被合并而不是累积。这永远不会阻塞写入；如果编码器不可用，写入会继续不合并。 - 权衡是衡量的并公布的：大约 4 倍的中位写入成本（仍然是 ~42ms），换来一个保持清洁的存储库，因为读取主导内存工作负载。 - **压缩** （可选，`COMPACTION_ENABLED=1`）是第 3 层：在会话中写入足够多的内容后，背景传递使用余弦相似度和联合查找连接组件来检测相关记忆簇，门控最小簇大小，最小年龄和活动会话宽限期，因此它永远不会压缩正在进行的作业。然后 MARM 注入一个有界请求，询问连接的代理总结每个簇：`candidates` → `stage` → `review` → `apply` 或 `discard`。源内存 ID 在应用时保留，因此压缩的摘要可以追溯到原始内容。暂存的摘要过期（`COMPACTION_STAGING_TTL_HOURS`），提示被限制和冷却限制，注入有字节预算。设计是诚实的关于 LLMs 的用途：MARM 检测，代理总结，人类审查阶段/应用/丢弃循环控制破坏步骤。 ### 召回路径 在 [理解 MARM 内存](#理解-marm-内存) 中涵盖：精确通道（FTS5 BM25 + LIKE 回落），过滤→重新排序（有限 FTS 候选项 → 批量语义重新排序 → 时间混合），带有显式截断标志的有界语义回落，以及分段折叠评分。召回深度 (`detail=1/2/3`) 控制返回的每个内存的多少，每个 MCP 响应通过 **1MB 响应限制器**，该限制器智能地截断内容而不是破坏协议。 ### 代码图谱子进程协议 捆绑的图引擎作为一个受监督的子进程运行，而不是导入： - **传输**：子进程的标准输入/输出上的换行分隔的 JSON-RPC 2.0，具有验证的握手（初始化 → 捕获服务器版本 → 初始化通知）。 - **信封护理**：响应被扫描以获取第一个可解析的 JSON 内容项，而不是假设索引 0，因为上游二进制文件可以预先添加更新通知。工具错误作为 `result.isError` 到达，而不是 JSON-RPC 错误，并转换为干净的 `{"status": "error"}` 字典，并带有上游自己的修复提示。 - **序列化**：一个锁保护每个写入 + 读取回合在单个 stdin 管道上；异步调用者通过 `asyncio.to_thread` 进行，以便事件循环永远不会在子进程 IO 上阻塞。 - **崩溃恢复**：stderr 在后台线程上排空，检测子进程 EOF/崩溃，并子进程在下一次调用时透明地重新生成。超时 **不** 被视为崩溃；长时间的索引运行可能仍在工作，杀死它会销毁正在进行的作业。 - **监督**：一个惰性单例监督器拥有进程生命周期。启动由第一个图工具调用触发，从未提升到 MCP 层，并在启动时验证固定的二进制文件工具模式，以便在启动时捕获上游漂移而不是在调用中间。 ### 安全和速率限制 - **双模式身份验证门控**：在环回地址 (`127.0.0.1`) 上无密钥，在服务器网络暴露时需要 `MARM_API_KEY`（Bearer） (`SERVER_HOST=0.0.0.0`，Docker）。`--generate-key` 生成一个。本地默认为安全，无需设置摩擦。 - **基于 IP 的速率限制** 带有滑动窗口和临时块，通过 CLI 预设调整（下表）。 - **本地优先**：所有内容都位于 `~/.marm/` 下；无云同步，无遥测，无外部存储。 - **优雅关闭**：SIGTERM/SIGINT 处理程序干净地排空和关闭连接池，一个内部事件系统运行自动化回调，每个回调都有回调错误隔离和超时，因此一个坏钩子不会阻塞服务器。 ### 群集和多代理预设 | 标志 | 速率限制 | 写入队列 | 使用时 | |------|------------|-------------|----------| | *(无)* | 80 RPM | 启用 | 正常本地使用和小型 3-5 代理设置 | | `--swarm` | 200 RPM | 启用 | 共享 HTTP 服务器，大约 15-30 代理，取决于写入样式 | | `--swarm-max` | 600 RPM | 启用 | 更重的本地/私有群集，大约 50-100 代理，取决于写入样式 | | `--trusted` | 禁用 | 启用 | 仅限私有/受信任的部署 | | `--rate-limit-rpm N` | N RPM | 不变 | 自定义覆盖；0 禁止限制 | 写入队列无论预设如何都序列化内存写入；群集标志在 HTTP 速率限制之上调整。队列控制写入排序；合并和压缩是单独的内存维护层。该堆栈（WAL + 池化 + 序列化写入器 + RPM 预设）故意限定为“SQLite，许多代理，一个机器”；分布式多节点内存是当前设计范围之外。 ### 自我维护文档 打包文档在启动时索引到 `marm_system` 内存命名空间，并在 50 个工具调用后刷新，带有源文件哈希跟踪，以便不变的文档被跳过而更改或删除的行被重新索引。连接的代理可以使用 `marm_smart_recall` 而不是您将文档粘贴给他们来回答 MARM 使用问题。 ### 配置参考 <details> <summary><strong>环境变量（括号中为默认值）</strong></summary> | 变量名 | 默认值 | 控制内容 | | --- | --- | --- | | `SERVER_HOST` | `127.0.0.1` | 绑定地址；`0.0.0.0` 暴露服务器，使 `MARM_API_KEY` 成为必填项 | | `SERVER_PORT` | `8001` | HTTP 端口 | | `MARM_API_KEY` | *(空)* | 网络暴露部署的 Bearer 密钥 | | `MARM_DB_PATH` | `~/.marm/marm_memory.db` | 内存数据库位置 | | `MARM_CONCEPT_DB_PATH` | `~/.marm/index/marm_index.db` | 概念图数据库位置 | | `MARM_PROJECT` / `MARM_PLATFORM` | *(自动检测)* | 覆盖项目/平台属性 | | `MARM_RATE_LIMIT_RPM` | `80` | 每分钟每个 IP 的请求数（预设覆盖） | | `WRITE_QUEUE_ENABLED` | `1` | 通过一个工作线程序列化写入 | | `FTS_CANDIDATE_LIMIT` | `50` | 语义重新排序前获取的 BM25 候选数；对于关键词重叠较弱的存储库，提高此值 | | `RECALL_SCAN_LIMIT` | `10000` | 语义回落扫描的上限；响应中的 `recall_scan_truncated=true` 表示已达到上限 | | `HYBRID_SEARCH_TEXT_WEIGHT` | `0.35` | 混合评分中文本与语义的权重 | | `TEMPORAL_WEIGHT` / `TEMPORAL_HALF_LIFE_DAYS` | `0.1` / `30` | 最近度提升的强度和衰减 | | `CONSOLIDATION_ENABLED` | `0` | 写入时去重 + 语义合并 | | `CONSOLIDATION_THRESHOLD` | `0.92` | 合并近似重复的相似度要求 | | `COMPACTION_ENABLED` | `0` | 背景集群检测 + 代理辅助压缩 | | `COMPACTION_TRIGGER_COUNT` | `5` | 每个会话压缩前的写入次数 | | `COMPACTION_SIMILARITY_THRESHOLD` / `COMPACTION_MIN_CLUSTER_SIZE` / `COMPACTION_MIN_AGE_HOURS` | `0.88` / `3` / `24` | 集群检测门控 | | `COMPACTION_STAGING_TTL_HOURS` | `168` | 暂存摘要的过期时间 | | `GRAPH_ENABLED` | `true` | 5 个代码图工具的启用开关 | | `CONCEPT_BUILD_ROW_CAP` | `500` | 每个概念图构建的最大内存行数 | | `MARM_SIGNUP_PROMPT_ENABLED` | `1` | MARM 邮件列表的一次性注册提示；设为 `0` 以禁用 | </details> ## 故障排除 <details> <summary><strong>服务器问题</strong></summary> **服务器无法启动** - 检查 Python 版本：`python --version`（必须为 3.10+） - 验证端口 8001 未被占用：`lsof -i :8001`（macOS/Linux）或 `netstat -ano | findstr :8001`（Windows） - 检查家目录中是否存在权限错误（`~/.marm/` 必须可读/可写） - 参考平台特定的故障排除指南：[INSTALL-DOCKER.md](docs/INSTALL-DOCKER.md)、[INSTALL-WINDOWS.md](docs/INSTALL-WINDOWS.md)、[INSTALL-LINUX.md](docs/INSTALL-LINUX.md) **STDIO 连接失败** - 验证 `marm-mcp-stdio` 是否在您的 PATH 中：`marm-mcp-stdio --help` - 替代方案：`python -m marm_mcp_server.server_stdio` - 检查 AI 客户端文档中的 STDIO 传输要求 - 直接执行以查看错误信息：`python -m marm_mcp_server.server_stdio` </details> <details> <summary><strong>连接与集成</strong></summary> **AI 客户端无法连接到 MARM** - 验证服务器是否在仪表盘健康面板中运行，或使用 `curl http://localhost:8001/health` - 检查防火墙是否阻止端口 8001 - 对于 STDIO：使用 `marm-mcp-stdio`（控制台脚本）或 `python -m marm_mcp_server.server_stdio` - 重启服务器和 AI 客户端 **工具未出现在 AI 客户端中** - 验证仪表盘健康面板中的 HTTP 模式，或使用 `curl http://localhost:8001/health` - 检查服务器日志中的初始化错误 - 断开并重新连接 AI 客户端以刷新工具列表 - HTTP 和 STDIO 都暴露了 14 个工具：7 个核心内存/日志/笔记本/压缩工具、5 个捆绑代码图工具和 2 个概念图工具 **图工具返回 `graph backend unavailable`** - 确认 `GRAPH_ENABLED` 未设置为 `false`（影响 HTTP 和 STDIO；图工具在两种传输方式下都有完全的对等性） - 首次使用图可能需要更长时间，因为固定的代码库内存引擎启动或下载本地文件 - 在 Docker 中，图引擎二进制文件被编译到镜像中；本地 pip 安装可能会在首次使用图时获取它 - 核心内存工具在图启动失败时继续工作 **概念工具返回 `entities_extracted: 0`** - 真实提取需要可选的额外依赖：`pip install marm-mcp-server[concepts]` 加上 `python -m spacy download en_core_web_sm` - 没有它，工具仍然注册但不存储任何内容；这是设计使基本安装保持轻量 </details> <details> <summary><strong>内存和数据问题</strong></summary> **内存无法保存** - 验证 `~/.marm/` 目录存在且具有写入权限 - 检查可用磁盘空间 - 使用简单内存测试：要求 AI 保存一行并使用 `marm_log_show` 检查 - 对于 HTTP 模式，验证仪表盘健康面板中的服务器健康，或使用 `curl http://localhost:8001/health` **搜索结果为空** - 验证内存存在：使用 `marm_log_show` 列出条目 - 使用 `search_all=True` 搜索所有会话 - 尝试更简单、更通用的搜索查询 - 等待几秒钟；首次语义搜索加载 ML 模型 **内存出现后消失** - 检查 MARM 是否已重启或崩溃（数据保存在 `~/.marm/` 中） - 验证磁盘空间是否已满 - 检查系统日志中的数据库错误 **丢失或损坏的数据** - 立即停止服务器 - 检查 `~/.marm/` 目录中是否有备份副本（如果您创建了它们） - 从备份恢复：将备份的 `~/.marm/` 复制回主目录 - 重启服务器 **数据库锁定错误** - 关闭所有 AI 客户端连接 - 停止服务器：`Ctrl+C` - 备份整个数据库目录：`cp -r ~/.marm ~/.marm.backup` - 检查持有数据库锁定的进程：`lsof ~/.marm/marm_memory.db`（macOS/Linux）或检查任务管理器（Windows） - 如果进程持有锁定，请终止它 - 验证数据库完整性：`sqlite3 ~/.marm/marm_memory.db "PRAGMA integrity_check;"` - 如果完整性检查失败，请从备份恢复 - 如果完整性检查通过，锁定应该被释放；重启服务器 </details> <details> <summary><strong>性能</strong></summary> **搜索结果缓慢** - 首次搜索较慢（模型从磁盘加载）；后续搜索更快 - 大型数据库（1000+ 内存）可能需要几秒钟 - 限制搜索：使用 `limit=10` 代替无限结果 - 使用 `marm_summary` 压缩旧会话 **服务器内存使用过多** - 笔记本中的许多条目可能会累积；使用 `marm_notebook(action="clear")` 清除活动条目 - 关闭未使用的 AI 客户端连接 - 启用压缩时，使用 `marm_compaction(action="review")` 检查暂存的压缩摘要 </details> <details> <summary><strong>常见错误信息</strong></summary> | 错误信息 | 原因 | 解决方案 | | --- | --- | --- | | `address already in use` | 端口 8001 已被占用 | 终止占用端口 8001 的进程或使用其他端口 | | `permission denied: ~/.marm/` | 数据库目录不可写 | `chmod 755 ~/.marm/` 或检查所有权 | | `module not found: core.memory` | 缺少依赖 | 从 `marm-mcp-server/` 重新安装：`pip install -e ".[dev]"` | | `database is locked` | 多个进程访问数据库 | 关闭其他连接，重启服务器 | | `embedding model not found` | 语义搜索模型未下载 | 首次运行需要时间；请耐心等待并检查互联网连接 | </details> 有关内存行为、传输、支持的客户端、压缩和备份的疑问，请参阅 [FAQ](marm-mcp-server/marm-docs/FAQ.md)。 ## ⭐ 给项目点赞 如果 MARM 能满足您的 AI 内存需求，请给仓库点赞以支持开发！ <div align="center"> <a href="https://star-history.com/#Lyellr88/marm-memory&Date"> <img src="https://api.star-history.com/svg?repos=Lyellr88/marm-memory&type=Date" width="700" height="400" alt="MARM 系统星历史图表"> </a> </div> ## 贡献 MARM 欢迎各个层次的贡献者。代码贡献有帮助，但文档、设置说明、客户端测试、错误报告、基准测试和来自每天使用 AI 工具的用户的实际工作流反馈也同样重要。 贡献领域： - 使用更多的 MCP 客户端、IDE 代理和操作系统测试 MARM - 改进文档、截图、示例和平台特定的设置说明 - 报告错误或不清晰的安装步骤，并提供清晰的重现细节 - 分享内存工作流、代理习惯和工具想法 - 查看开放的 [问题](https://github.com/Lyellr88/marm-memory/issues) > 💡 想出现在这个列表中？查看我们的 [CONTRIBUTING.md](https://github.com/Lyellr88/marm-memory/blob/MARM-main/CONTRIBUTING.md) 指南，开始贡献！ ## 加入 MARM 社区 **帮助构建 AI 内存的未来 - 无需编码！** **连接：** [MARM Discord](https://discord.gg/nhyJWPz2cf) | [GitHub 讨论](https://github.com/Lyellr88/marm-memory/discussions) ## 许可证和用法声明 版权 © 2026 Ryan A. Lyell。MARM 在 [Apache 2.0 许可证](LICENSE) 下发布（参见 [NOTICE](NOTICE) 中的版权声明），欢迎进行分支、实验和集成。MARM 还封装了第三方开源组件，例如 `codebase-memory-mcp`，遵循 MIT 许可证；参见 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) 以了解属性。如果您在此基础上构建，请使非官方版本易于与官方版本区分开来。 ## 项目文档 ### **使用指南** - **[README.md](https://github.com/Lyellr88/marm-memory/blob/MARM-main/README.md)** - 本文件：完整的使用指南、工具参考、工作流和架构 - **[PROTOCOL.md](https://github.com/Lyellr88/marm-memory/blob/MARM-main/docs/PROTOCOL.md)** - MCP 操作协议 - **[FAQ.md](https://github.com/Lyellr88/marm-memory/blob/MARM-main/marm-mcp-server/marm-docs/FAQ.md)** - 常见问题的答案 ### **MCP 服务器安装** - **[INSTALL-DOCKER.md](https://github.com/Lyellr88/marm-memory/blob/MARM-main/docs/INSTALL-DOCKER.md)** - Docker 部署（推荐） - **[INSTALL-WINDOWS.md](https://github.com/Lyellr88/marm-memory/blob/MARM-main/docs/INSTALL-WINDOWS.md)** - Windows 安装指南 - **[INSTALL-LINUX.md](https://github.com/Lyellr88/marm-memory/blob/MARM-main/docs/INSTALL-LINUX.md)** - Linux 安装指南 - **[INSTALL-PLATFORMS.md](https://github.com/Lyellr88/marm-memory/blob/MARM-main/docs/INSTALL-PLATFORMS.md)** - 平台安装指南 ### **项目信息** - **[CONTRIBUTING.md](https://github.com/Lyellr88/marm-memory/blob/MARM-main/CONTRIBUTING.md)** - 如何为 MARM 做出贡献 - **[CHANGELOG.md](https://github.com/Lyellr88/marm-memory/blob/MARM-main/CHANGELOG.md)** - 版本历史和更新 - **[ACKNOWLEDGMENTS.md](https://github.com/Lyellr88/marm-memory/blob/MARM-main/docs/ACKNOWLEDGMENTS.md)** - 贡献者和致谢 - **[ROADMAP.md](https://github.com/Lyellr88/marm-memory/blob/MARM-main/docs/ROADMAP.md)** - 计划的功能和开发路线图 - **[LICENSE](https://github.com/Lyellr88/marm-memory/blob/MARM-main/LICENSE)** - Apache 2.0 许可证条款