marm-mcp-server

marm-memory v2.60.1 - 60 秒内为你的 AI Agent 提供永久记忆

欢迎贡献！浏览待处理议题参与贡献，或加入 MARM Discord，分享工作流、获取设置帮助并与其他构建者交流。

重要说明

项目状态：短暂的个人休整

我暂时离开了活跃开发，专注处理项目之外的事务。本项目仍在持续维护，我计划很快回来，继续开发和完善项目。

感谢你的耐心、支持和持续关注。我很快会恢复工作，并随着进展分享最新动态。

目录

• 快速开始
• 为什么选择 MARM Memory
• MARM 控制台
• 性能与扩展基准测试
• MCP 客户端设置
• 运行时 CLI 命令
• 完整 MCP 工具套件
• 使用 MARM：直接对话，无需调用工具
• 了解 MARM Memory
• 知识图谱：代码与概念
• 架构与内部机制
• 故障排除
• 参与贡献
• 项目文档

快速开始

1. 使用你偏好的 Agent 配置文件进行安装和初始化：

pip install marm-mcp-server
marm-memory init --g-claude --g-codex --g-antigravity

另有以下选项：--g-cursor、--g-grok、--g-hermes、--g-opencode、--g-devin、--g-cline、--g-qwen、--g-kiro 和 --g-zed。不带标志运行时，会安装到当前项目文件夹，而不是主目录

1. 将任务交给你的 AI 伙伴。告诉你的 Agent：

“使用 marm-init 技能来设置 MARM。”

1. 开始互动：你的 Agent 会直接在聊天中以交互方式处理整个设置过程（Python/Docker、HTTP/STDIO、密钥和客户端配置）。

手动设置

更喜欢自行配置：

将“agent”替换为客户端的 CLI 命令（例如 claude、agy 或 qwen）。对于 Codex，请改用 codex mcp add marm-memory --url http://localhost:8001/mcp。

• ⚡ **最快的 HTTP 启动方式：**运行 marm-memory fast-start-http，即可启动本地运行时、打开控制台并立即在浏览器中访问。
• 🖥️ **Web 控制台：**运行 marm-memory console，即可立即查看本地 UI 应用（无需 Node.js）。
• ⚙️ **生命周期管理：**使用 status、logs --follow、restart 和 stop 管理后台守护进程。
• 💡 **快速标志：**使用 --no-console 或 --no-browser 限制启动行为。运行 marm-memory --help 查看完整命令列表。

为什么选择 MARM Memory

你的 AI 会忘记一切。MARM Memory 不会。

marm-memory 为你的 Agent 提供私有共享记忆，用于保存通常会在不同聊天之间丢失的上下文：决策、研究、修复、笔记和项目历史。切换到 Codex 或 Gemini，告别 Claude Code，也不会丢失已收集的上下文。

它整合了三项功能：

• 🧠 **核心记忆（8 个工具）**用于存储对话、笔记、笔记本条目和摘要，方便随时搜索。
• 💻 **代码图谱（6 个工具）**用于映射代码仓库，让 Agent 查找符号、追踪代码路径并理解项目，而不必重新通读所有代码。只需指定一次代码仓库，它就会在你工作时持续更新。
• 🧩 **概念图谱（2 个工具）**用于关联已存储记忆中的人物、决策、错误和想法，并在可能时链接到相关代码。随着记忆的存储，它会自动构建。

全部 16 个工具均支持 HTTP 和 STDIO。你的 Agent 可以跨会话共享同一本地记忆，而不必每次都从头开始。随附的控制台应用提供本地控制面板，可用于管理记忆、图谱、代码上下文、提炼、运行时控制和集成终端。为代码仓库建立索引后，会创建独立的代码图谱；即使尚未存储任何记忆，也可以通过“知识图谱”→“代码浏览器”探索该图谱。

工作原理

如需了解检索延迟、并发和写入成本数据，请参阅性能与扩展基准测试；如需了解各层背后的机制，请参阅架构与内部机制。

MARM 控制台：您的本地控制平面

运行 marm-memory console，即可在 http://127.0.0.1:8002 打开捆绑的 Web 应用。它随 MARM 一同提供，无需安装 Node.js，始终运行在您的机器上，并使用与 Agent 相同的本地存储和 MCP 运行时。

运行时 CLI 命令

marm-memory 是随 Python 软件包安装的本地运行时管理器。这些是常用的运维命令；如需查看标志和特定命令示例，请使用 marm-memory <command> --help。

日常运行时操作

marm-memory fast-start-http                # start HTTP, Console, and open the browser
marm-memory fast-start-http --client cursor # also connect one client (add --transport stdio for STDIO)
marm-memory start                          # start or reuse the managed HTTP runtime
marm-memory start --profile swarm          # shared multi-agent preset
marm-memory stop                           # stop the managed runtime safely
marm-memory restart                        # restart the managed runtime
marm-memory status                         # inspect runtime, database, queue, and graph status
marm-memory logs --follow                  # follow bounded runtime logs
marm-memory console                        # start or reuse the bundled local Console

传输方式与设置

marm-memory http                           # run HTTP in the foreground
marm-memory stdio                          # run the strict local MCP STDIO transport
marm-memory init                           # install the MARM skill into detected agents (project scan)
marm-memory init --g-claude                # install the skill into the home-folder claude directory
marm-memory doctor                         # diagnose the local install
marm-memory key init                       # create or reuse ~/.marm/.env without displaying the key
marm-memory key path                       # print the managed key-file path
marm-memory key reveal                     # explicitly display the managed key
marm-memory console --import-key           # open an authenticated local Console session
marm-memory upgrade --check                # compare the installed package with PyPI
marm-memory uninstall                      # preview package removal; always preserves ~/.marm

知识、项目与维护

marm-memory knowledge status               # Indexers, models, and how far behind automatic indexing is
marm-memory knowledge build --all          # Rebuild the whole concept graph (new memories index themselves)
marm-memory knowledge auto off             # Stop indexing memories automatically (on, off, status)
marm-memory projects list                  # List all tracked workspaces
marm-memory projects index <path>          # Add a repo to the code graph (kept current after that)
marm-memory projects status                # Inspect target repo graph readiness
marm-memory projects auto off              # Stop re-indexing repos automatically (on, off, status)
marm-memory maintenance status             # Check internal database optimization state
marm-memory maintenance embeddings migrate # Upgrade old 384-dim vectors to 512-dim
marm-memory maintenance chunks rechunk     # Recalibrate long memory text splits

Docker 命令单独记录在下文，因为它们需要明确选择数据挂载、网络暴露方式和密钥处理方式。

性能与扩展性基准测试

MARM 优先针对快速回忆进行调优，即使记忆不断增长，并在幕后将长记忆分块，也能保持快速回忆。

这些测量使用由 fastembed 提供支持的 jinaai/jina-embeddings-v2-small-en 编码器和临时本地 SQLite 数据库。每条计时路径都调用已发布的 MARMMemory 代码，而非基准测试专用的重新实现。第 1 至第 4 节的数据来自在本地硬件上单次运行 scripts/benchmarking/performance/bench_hotpath.py 的计时结果；绝对毫秒数因机器而异，因此应关注扩展趋势。第 5 节是单独的准确率基准测试（run_eval.py），衡量的是检索效果而非速度；其中最新一行是受控的前后对比，具体说明见该节。

1. 检索延迟扩展性

端到端 recall_similar 延迟（包括查询编码）。

在较小的 $N$ 下，不同运行之间的波动大于相邻规模之间的差异，因此这里 N = 250 的耗时高于 N = 500。应将 N = 1,000 及以上的趋势视为真实信号。

2. 编码器与并发

• 冷启动模型加载： 893ms
• 热启动编码： 中位数 3.8ms，p95 4.3ms
• 并发回忆： 10 次汇集执行的回忆耗时 151.5ms，而串行执行耗时 176.0ms（gather/serial = 0.86）。不要将其解读为并行执行：同一基准测试的多次运行结果介于 0.63 到 0.86 之间，因此该比率不够稳定，不能据此宣称提速。按照设计，这条路径会在共享编码器和 SQLite 操作处串行执行；任何看似的提升都是测量噪声。

3. 写入时的摄取开销

• 关闭整合： 中位数 6.5ms，p95 7.6ms
• 开启整合： 中位数 58.1ms，p95 106.5ms
• 权衡： 写入时去重／聚类会增加 9.0x 的中位开销，以确保回忆速度快，并让存储内容随时间推移保持整洁。整合默认关闭。

4. 回忆扩展性：全量扫描与生产混合方案

回忆为何能在记忆增长时保持稳定：生产环境中的回忆不会扫描每个向量，而是先通过 FTS 关键词预筛选缩小候选池，再使用语义 + BM25 + 时间的混合评分重新排序。基准测试的两列都代表真实的异步代码路径，并使用预先计算的向量，以便将检索速度与原始编码开销分离。测试交替执行，以确保缓存条件完全无偏。

全量扫描的耗时随 $N$ 大致线性增长，而混合方案的回忆耗时增长慢得多，因此会话规模越大，优势仍会进一步扩大。在非常小的 $N$ 下，预筛选带来的收益不足以抵消开销，因此混合方案反而更慢。

5. LoCoMo 检索准确率

通过 marm_log_entry 导入全部 10 段 LoCoMo 对话（5,882 条记忆），然后将 marm_smart_recall 的前 5 条结果与 1,977 个带有证据标注的问题进行评分。不涉及答案生成模型或大模型评判，因此衡量的是能否检索到正确记忆，而不是 Agent 能否据此正确作答。

最后一行是受控对比：使用相同构建和数据，唯一变量是日志通道。该通道此前会将整个查询与日志主题和摘要进行子串匹配，因此自然语言问题永远无法匹配，在全部 1,977 个问题上的得分为 0.0%。现在它会对查询进行分词，单独运行时得分达到 53.3%。结果以范围而非单一数值呈现，因为语义通道在不同运行之间会有约半个百分点的波动，因此小于一个百分点的差异并不能说明问题。

多跳类别仍然最弱，得分为 44.9%；单跳证据召回率为 36.6%，而命中任一证据的比率为 66.2%，因此该通道经常只能检索到问题所需证据的一部分。使用 run_eval.py 重现结果。该脚本还会报告排序后语义通道的 MRR 和 nDCG@k；请在服务端设置 MARM_RECALL_REFERENCE_TIME，确保两次运行对相近的结果采用相同排序。

6. 与竞品对比：架构

MARM 面向特定细分场景：为连接 MCP 的编码 Agent 提供本地优先记忆，而不是通用个性化记忆或完整的 Agent 运行时。以下是它在架构上与 AI Agent 记忆领域知名产品的区别：

免责声明与准确性： 竞品格局变化迅速。上表反映的是截至 2026 年第三季度的核心架构特征，依据公开文档和 README 编制，并非对每个系统进行内部测试后的结论。如果任何关于其他框架的数据有所变化或表述有误，请提交 issue 或 Pull Request 更新此表。我们非常欢迎同行维护者提出更正。

MCP 客户端 HTTP 和 STDIO 配置

手动 pip 安装

pip install marm-mcp-server

使用以下经验法则选择配置方式

• 本地 HTTP/STDIO = 单机配置最快捷。
• Docker HTTP = 共享/常驻服务（需要密钥）。
• Docker STDIO = 私有容器化本地使用（无需 HTTP 密钥）。 **Swarm / 多 Agent 说明：**写入队列默认启用，通过一个工作进程串行处理记忆写入。对于共享的 HTTP 部署，请使用 marm-memory start --profile swarm（200 RPM）或 --profile swarm-max（600 RPM）。--profile trusted 会完全禁用速率限制，适用于私有部署。私有的单 Agent / 本地使用场景仍以 STDIO 为佳。完整表格请参见 Swarm 和多 Agent 预设。

pip install marm-mcp-server
marm-memory start
# Stuck on client setup? Open a Q&A thread: https://github.com/Lyellr88/marm-memory/discussions
# most agents use this --transport command
"agent" mcp add --transport http marm-memory http://localhost:8001/mcp
codex mcp add marm-memory --url http://localhost:8001/mcp

pip install marm-mcp-server
python -m marm_mcp_server.server_stdio
# most agents use this --transport command
"agent" mcp add --transport stdio marm-memory-stdio marm-mcp-stdio
codex mcp add marm-memory-stdio -- marm-mcp-stdio

# HTTP shared server, normal multi-agent use
marm-memory start --profile swarm

# HTTP shared server, heavier private swarm
marm-memory start --profile swarm-max

# HTTP trusted private lab/server, rate limiting disabled
marm-memory start --profile trusted

# STDIO remains keyless/private and does not use swarm flags
marm-mcp-stdio

marm-memory docker command                 # preview the exact HTTP command
marm-memory docker run                     # create the managed HTTP container
marm-memory docker stdio-command           # print a Docker STDIO client command
marm-memory docker status
marm-memory docker logs --follow
marm-memory docker stop

# Optional: mount repositories read-only for code indexing.
marm-memory docker run --repo /absolute/path/to/repository

# Optional: preview or explicitly write a Compose configuration.
marm-memory docker compose
marm-memory docker compose --yes

# Shared local server with a custom data path and two repositories for indexing.
marm-memory docker command \
  --profile swarm \
  --data-dir /srv/marm-data \
  --repo /srv/projects/api \
  --repo /srv/projects/web

# Execute the reviewed command, pulling the image first.
marm-memory docker run --profile swarm --data-dir /srv/marm-data --pull

# Step 1: generate key (do not add < > around the key)
docker run --rm lyellr88/marm-mcp-server:latest --generate-key

# Step 2: run server
docker pull lyellr88/marm-mcp-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=your-generated-key \
  -v ~/.marm:/home/marm/.marm \
  lyellr88/marm-mcp-server:latest

# Step 3: connect client
"agent" mcp add --transport http marm-memory http://localhost:8001/mcp --header "Authorization: Bearer your-generated-key"

# PowerShell: set this before starting/restarting 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

# Quick auth smoke test
curl -i -H "Authorization: Bearer $env:MARM_API_KEY" http://127.0.0.1:8001/mcp

# --swarm: write queue on, 200 RPM - recommended for multi-agent shared servers
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

$env:MARM_API_KEY="test"

# The second -v line mounts your repo; adjust the host path to your project
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

marm_graph_index(repo_path="/workspace/marm-memory")

docker run --rm -i \
  -v ~/.marm:/home/marm/.marm \
  --entrypoint python \
  lyellr88/marm-mcp-server:latest \
  -m marm_mcp_server.server_stdio

连接客户端

启动服务（python -m marm_mcp_server），然后按照下文配置客户端。每个代码块都假设使用默认本地安装（无需密钥）。对于 Docker 或已公开的服务，请添加每个客户端折叠内容中所示的 Authorization: Bearer 标头。

claude mcp add --transport http marm-memory http://localhost:8001/mcp

{
  "inputs": [
    {
      "type": "promptString",
      "id": "marm-api-key",
      "description": "MARM API Key for Docker or exposed server mode",
      "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}"
      }
    }
  }
}

{
  "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}"
      }
    }
  }
}

# Direct Python install - no key needed
codex mcp add marm-memory --url http://localhost:8001/mcp

# Docker or SERVER_HOST=0.0.0.0 - key required (set MARM_API_KEY in your shell first)
codex mcp add marm-memory --url http://localhost:8001/mcp --bearer-token-env-var MARM_API_KEY

[mcp_servers."marm-memory"]
url = "http://localhost:8001/mcp"
enabled = true
bearer_token_env_var = "MARM_API_KEY"

# Direct Python install - no key needed
grok mcp add --transport http marm-memory http://localhost:8001/mcp

[mcp_servers.marm-memory]
url = "http://localhost:8001/mcp"
bearer_token_env_var = "MARM_API_KEY"

# STDIO - no key needed
hermes mcp add marm-memory --command marm-mcp-stdio

# HTTP, direct Python install - no key needed
hermes mcp add marm-memory --url http://localhost:8001/mcp

mcp_servers:
  marm-memory:
    url: "http://localhost:8001/mcp"
    headers:
      Authorization: "Bearer ${MARM_API_KEY}"

{
  "mcp": {
    "marm-memory": {
      "type": "local",
      "command": ["marm-mcp-stdio"]
    }
  }
}

{
  "mcp": {
    "marm-memory": {
      "type": "remote",
      "url": "http://localhost:8001/mcp",
      "oauth": false
    }
  }
}

{
  "mcp": {
    "marm-memory": {
      "type": "remote",
      "url": "http://localhost:8001/mcp",
      "oauth": false,
      "headers": {
        "Authorization": "Bearer {env:MARM_API_KEY}"
      }
    }
  }
}

# STDIO - no key needed
devin mcp add -s user marm-memory -- marm-mcp-stdio

# HTTP, direct Python install - no key needed
devin mcp add -s user marm-memory http://localhost:8001/mcp

{
  "mcpServers": {
    "marm-memory": {
      "url": "http://localhost:8001/mcp",
      "headers": {
        "Authorization": "Bearer your-generated-key"
      }
    }
  }
}

{
  "context_servers": {
    "marm-memory": {
      "command": "marm-mcp-stdio",
      "args": []
    }
  }
}

{
  "context_servers": {
    "marm-memory": {
      "url": "http://localhost:8001/mcp"
    }
  }
}

{
  "context_servers": {
    "marm-memory": {
      "url": "http://localhost:8001/mcp",
      "headers": {
        "Authorization": "Bearer your-generated-key"
      }
    }
  }
}

# STDIO - no key needed
cline mcp install marm-memory --yes -- marm-mcp-stdio

# HTTP, direct Python install - no key needed
cline mcp install marm-memory --yes --transport http http://localhost:8001/mcp

{
  "mcpServers": {
    "marm-memory": {
      "type": "streamableHttp",
      "url": "http://localhost:8001/mcp",
      "headers": {
        "Authorization": "Bearer your-generated-key"
      }
    }
  }
}

# Direct Python install - no key needed
agy mcp add marm-memory --type http http://localhost:8001/mcp

# Docker or SERVER_HOST=0.0.0.0 - key required
agy mcp add marm-memory --type http http://localhost:8001/mcp --header "Authorization: Bearer your-generated-key"

{
  "mcpServers": {
    "marm-memory": {
      "serverUrl": "http://localhost:8001/mcp",
      "headers": {
        "Authorization": "Bearer your-generated-key"
      }
    }
  }
}

# Direct Python install - no key needed
qwen mcp add --transport http marm-memory http://localhost:8001/mcp

# Docker or SERVER_HOST=0.0.0.0 - key required
qwen mcp add --transport http marm-memory http://localhost:8001/mcp --header "Authorization: Bearer your-generated-key"

{
  "mcpServers": {
    "marm-memory": {
      "httpUrl": "http://localhost:8001/mcp",
      "headers": {
        "Authorization": "Bearer your-generated-key"
      }
    }
  }
}

{
  "type": "mcp",
  "server_url": "https://your-marm-domain.example.com/mcp",
  "server_label": "marm-memory",
  "authorization": "Bearer your-generated-key"
}

完整的平台操作指南、密钥设置和特定操作系统的说明：Windows · macOS · Linux · Docker/密钥模式 · 其他平台

使用的客户端不在列表中？提交问题并告诉我们；客户端适配器是我们优先考虑的功能请求。

curl http://localhost:8001/health

完整 MCP 工具套件（16 个工具）

💡 专业提示： 无需手动调用这些工具！只需用自然语言告诉你的 AI Agent 你想做什么：

• “Claude，将此会话记录为‘Project Alpha’，并将此对话添加为‘database design discussion’”
• “将这段代码片段记到你的笔记本里，以便以后使用”
• “搜索我们昨天关于身份验证的讨论内容”

AI Agent 会自动使用相应的工具。希望直接控制的高级用户也可以手动调用工具。

🧠 核心记忆（8 个工具）

🕸️ 代码图（6 个工具）

🧩 概念图谱（2 个工具）

全部 16 个工具均可通过 HTTP 和 STDIO 使用。在工具接口背后，服务会自动处理生命周期设置、协议刷新、文档索引、日期上下文、摘要缓存维护、写入队列处理、概念索引、代码随代码库变化而重新索引、项目／平台归属以及健康检查；这些操作都不会占用 Agent 的注意力或 token。两个图引擎会在首次使用时按需启动，即使启动失败，也不会阻塞 8 个核心记忆工具。有关这些机制，请参阅架构与内部机制。

使用 MARM：直接交流，不必调用工具

MARM 会在内部处理生命周期相关工作。文档和会话状态会在首次实际调用工具时初始化，随附的文档会索引到 marm_system 记忆命名空间，并跟踪源文件哈希，因此 Agent 可以直接从记忆中回答 MARM 使用相关的问题。

示例工作流：跨 AI 研究项目

通过一个实际工作流展示 MARM 的运作方式。**场景：**你正在使用多个 AI 客户端，为一个新项目研究身份验证模式。

阶段 1：路由会话（Claude）

You: "Claude, create a MARM session called 'auth-research-2025-01'"
Claude calls: marm_log_entry(entry="Session: auth-research")
Result: Session routed to auth-research-[today]. MARM lifecycle/docs initialize automatically.

阶段 2：记录研究内容（Claude）

You: "Summarize OAuth2 vs JWT for API authentication and save it"
Claude calls: marm_log_entry(entry="Research: OAuth2 is token-based with refresh cycles, better for delegated access. JWT is stateless, good for microservices...", session_name="auth-research-2025-01")
Result: Research captured in the active session log and marked for summary-cache refresh

阶段 3：添加可复用参考资料（Claude）

You: "Save a JWT validation code snippet to my notebooks as 'jwt-validation-pattern'"
Claude calls: marm_notebook(action="add", name="jwt-validation-pattern", data="def verify_jwt(token):\n  # validation logic...")
Result: Reusable snippet stored for future projects

阶段 4：回忆上下文（Gemini）

You: "Gemini, what authentication approaches did we research? Activate the JWT pattern."
Gemini calls: marm_smart_recall("authentication patterns", search_all=True)
Gemini calls: marm_notebook(action="use", names="jwt-validation-pattern")
Result: Gemini sees previous research + has JWT code available as context

阶段 5：综合与总结（Qwen）

You: "Qwen, pull everything from the auth research and create a summary"
Qwen calls: marm_smart_recall("authentication", session_name="auth-research-2025-01", limit=20)
Qwen calls: marm_summary(session_name="auth-research-2025-01")
Result: Qwen generates an implementation guide from all captured research

阶段 6：结束会话（Claude）

You: "Log final decision - we're using JWT for APIs, and OAuth2 for user auth"
Claude calls: marm_log_entry(entry="DECISION: JWT for API auth, OAuth2 for user flows. Rationale: stateless APIs + delegated user access", session_name="auth-research-2025-01")
Result: Decision logged and searchable by all future AI clients

结果：三个不同的 AI 客户端协作研究了一个主题、分享见解并记录决策，全程无需向每个新 AI 重复介绍项目情况。

高级模式

Project Structure:
├── project-name-planning/          # Initial design and requirements
├── project-name-development/       # Implementation details
├── project-name-testing/           # QA and debugging notes
├── project-name-deployment/        # Production deployment
└── project-name-retrospective/     # Lessons learned

两次搜索，两种截然不同的问题，一个工具：

User: "I discussed machine learning algorithms yesterday"
MARM Search: Finds related memories about "ML models", "neural networks", "AI training"

User: "What was the COMPACTION_TRIGGER_COUNT setting?"
MARM Search: Finds the exact config memory even if the rest of the text differs

第一个查询关乎含义，因此 MARM 使用本地向量嵌入对候选结果重新排序——采用 RAG 风格的语义搜索，无需托管向量数据库。第二个查询具有语法特征（配置键），因此 MARM 会自动识别，并将其路由到确定性的精确匹配。这个精确检索通道，正是能在演示中奏效的记忆系统与能回答开发者实际问题的记忆系统之间的区别：配置键、CLI 标志、文件路径、API 名称、错误字符串。纯语义记忆系统恰恰无法处理这些查询。

记忆类型与分类

1. 上下文日志 - 自动分类的对话记忆
2. 手动条目 - 明确保存的重要信息
3. 笔记本条目 - 可复用的指令和知识
4. 会话摘要 - 压缩后的对话历史

MARM 会在写入时自动对内容分类：代码（编程片段和技术讨论）、项目（工作对话和规划）、书籍（文学作品、学习材料、研究）和通用（其他所有内容）。

项目与平台归属

MARM 会在记忆、日志条目和笔记本条目中存储可为空的 project 和 platform 列。项目根据工作目录检测，平台根据连接的客户端（Claude Code、VS Code、Cursor，……）检测；MARM_PROJECT 和 MARM_PLATFORM 可覆盖检测结果。marm_smart_recall(project=..., platform=...) 可限定召回范围，同时不改变默认的无筛选行为，因此一个共享服务可以存储多个项目，且彼此不会相互干扰。

将对话提炼为记忆

存储记忆是一种明确的行为，因此值得保留的内容，都是有人记得要保留的内容。marm_distill 则反其道而行：将一段原始对话交给它，它会从中提议值得长期保存的事实。

marm_distill(action="propose", session_name="release-notes", text="<the conversation so far>")
marm_distill(action="review")                       → the staged proposals and their verdicts
marm_distill(action="apply", proposal_id="...")     → writes that one as a memory
marm_distill(action="discard", proposal_id="...")   → rejects it, permanently

每条提议都会与已存储的内容进行比对，并附带一个判定：new、duplicate 或 near。near 是需要人工处理的情况：它与某条已存储的记忆足够相似，可能有关联，但相似度分数无法判断它是在补充这条记忆、与之矛盾，还是仅仅相关。提议会与它相似的记忆并列显示，供审核者决定如何处理。

默认情况下，它只提出建议，不会写入。 propose 会将提议放入审核队列，只有 apply 才会创建记忆；唯一的可选例外是开启操作者的自动应用开关后使用 review_mode="guardrails"，此时只有所有确定性检查都通过，才会应用提议。这与 marm_compaction 的设计有意保持一致，原因也相同：相似度分数不足以作为无人值守写入记忆的依据，而仅凭这种分数就写入的任何机制，都会让存储中充斥似是而非的内容，速度远快于积累事实的速度。已丢弃的提议绝不会再次出现，这一点由唯一性约束强制保证，而不是靠约定——再次提供审核者已经否决的内容，会让审核队列变得无人问津。这样一来，对同一段文本重复运行 propose 也不会产生任何操作，因此可以安全地在每次会话结束时调用它。

文本的编写方式。 如果无法连接本地模型，它会筛选本身就像长期事实的句子并将其规范化，而不是编写新句子——因此，分散在三轮对话中的事实，或有所暗示但从未明确说出的内容，都不会成为提议。它会找出明确说出的内容，而非言外之意。这是一个实际的限制，同时也算合理的取舍：MARM 记忆是一条标题，而标题通常就是某人已经写下的句子。若启用本地生成且模型可访问，并指定 (use_llm=true)，它就会改为编写事实，同时保留对应的原文片段；提议的 mode 会显示实际采用了哪种方式。请参阅可选的本地生成。

提议尚未审核时，MARM 可以在工具响应中附带审核请求，而不必等用户提出要求。请求会指定一条提议，并要求对其作出决定——apply 或 discard；每个冷却窗口内，全服务器最多附带一条请求，因此一批提议不会导致每个响应都附带请求。设置 MARM_DISTILL_NUDGE=0 可关闭此功能；冷却时间和预算可在配置参考中调整。

知识图谱：代码与概念

MARM 附带两个与记忆存储互补的图谱系统：一个理解代码库结构的代码图谱，以及一个理解已存储记忆主题的概念图谱。为同一项目同时建立索引后，概念实体会与代码符号交叉链接。

代码图谱：代码库索引与代码查询

marm-graph 已集成到两种传输方式中。它只需对代码库建立一次索引，之后 Agent 就能询问代码结构相关的问题，无需反复扫描文件：

Use marm_graph_index to index this repository.
Then use marm_code_context when the question is how something works or what a change would touch.
Use marm_code_lookup when you need a specific symbol, file, or source snippet.
Use marm_graph_trace for call paths, marm_graph_architecture for an overview, and marm_graph_impact for change-risk checks.

推荐的 Agent 工作流：先建立一次索引，然后针对具体任务使用 marm_code_context，在大范围读取文件前使用 marm_code_lookup，在调用方／被调用方或数据流上下文很重要时使用 marm_graph_trace，使用 marm_graph_architecture 了解整体情况，并在高风险重构前使用 marm_graph_impact。一次图谱查询可以取代数十轮 grep／读取操作，节省的 token 就来自这里。

组合上下文：marm_code_context

其余 5 个工具各回答一个问题，Agent 通常会将它们串联起来：搜索名称、追踪调用者、读取每个文件，然后查找记忆中记录的相关内容。marm_code_context 会在服务端执行这条调用链，并将结果作为一个数据包返回：

marm_code_context(task="how does the write queue serialise concurrent writes?")

共 6 个步骤：先通过词法和语义搜索播种，再沿着调用者和被调用者关系扩展，接着用个性化 PageRank 对该子图进行排名，然后从磁盘读取排名靠前的源码，召回与它们关联的记忆和“记忆→符号”链接，最后将结果压缩到字符数上限以内，并把关键内容放在前面。

第三步是普通搜索无法做到的。词法搜索回答的是“哪些符号提到了这些词”，但这并不是 Agent 要问的问题；一个既无人调用、也无人引用的符号，即使同样提到了这些术语，其排名也会低于相关邻域中心的符号。第五步则是纯代码索引在结构上无法做到的——它保留了代码为何如此的原因，而不只是代码写了什么。

detail 用大小换取结构。1（默认值）返回 Markdown 和说明：提供 Agent 所需内容，不重复。2 会添加符号和记忆元数据——名称、文件、行号、分数，以及记录符号是从任务中播种还是沿调用边引入的 provenance——但不会重复 Markdown 中已有的源码。3 还会将源码和记忆文本作为结构化字段添加，这正是渲染器所需的内容，也是 Console 的请求方式。MARM_CODE_CONTEXT_DETAIL 可以一次性更改所有 Agent 的默认值。include_graph 是另一个维度上的独立开关，默认关闭：它会返回用于可视化的排名边列表，其他功能都不会读取该列表。

需要了解的一项限制：追踪会按限定名称解析。如果一个裸名称匹配两个符号，返回结果会是 status: "ambiguous"，且不包含任何边，而不是猜测一个结果。这样一来，排名就无内容可处理，最终结果会退化为普通搜索顺序。

answer=true 更进一步，仅根据组合后的上下文用文字回答任务——参见可选本地生成。

仓库建立索引后，MARM 会自动保持索引最新。文件系统监视器会检测保存、提交、分支切换或合并，并在短暂延迟后重新建立索引；它会进行防抖处理，将一连串更改合并为一次处理，而不是每个文件处理一次。定期协调任务会捕获监视器事件遗漏的更改，也是非 git 仓库的唯一触发方式。要改为仅按需建立索引：

marm-mcp-server projects auto off

Agent 也可以通过 marm_graph_index(action="auto_off") 执行相同操作，而 action="auto_status" 会报告正在监视的内容，以及每个项目上次建立索引的时间。此开关会跨重启保留，且优先级高于 GRAPH_AUTO_INDEX 环境变量。

底层引擎是 codebase-memory-mcp（MIT），这是一个零依赖静态二进制程序，通过 tree-sitter 解析 158 种语言，并为主要语言提供 Hybrid LSP 类型解析。它可在数秒内为平均规模的仓库建立索引，并在远低于 1 秒的时间内完成符号搜索和调用追踪。在 MARM 持有的持久连接上，对包含 149,107 个节点的图进行测量：符号搜索耗时 146ms，调用追踪耗时 67ms，完整架构概览耗时 1.23s；只有这项查询超过了 1 秒。MARM 固定使用特定版本，启动时会验证其工具架构，并将上游工具集路由到 6 个专用 MCP 工具，使模型接口保持精简。图后端会在首次使用图工具时延迟启动，因此记忆、日志记录、笔记本和摘要工具仍能快速启动。在 Docker 中，引擎二进制文件已打包进镜像；本地 pip 安装会在首次使用图功能时下载该文件（约 269MB，仅需一次）。 **降级模式：**如果图引擎启动失败（首次下载时没有网络、磁盘已满、架构漂移），或设置了 GRAPH_ENABLED=false，图工具会返回 {"status": "error", "message": "graph backend unavailable"}，而其他 10 个工具仍可正常工作。图功能故障绝不会导致记忆功能中断。

概念图谱：记忆的内容

MARM 会从你存储的记忆中提取知识图谱，生成带类型的实体（概念、决策、模式、错误、工具、人员、组织），并通过带类型的关系（修复、实现、依赖于、使用、导致、替换、扩展）将它们连接起来。整个过程会自动进行：存储记忆后，系统会将其加入队列，后台工作进程约 30 秒后将其添加到图谱中。marm_concept_build 仍可用于完整重建或按范围重建。图谱构建完成后，marm_smart_recall 会以 graph_context 附加信息的形式，添加数量受限的相关实体、关系和关联代码，同时不改变主要记忆的排序。你仍可使用 marm_concept_recall 显式探索图谱：

marm_concept_recall(query="write queue")            → the entity, its relationships, linked code symbols
marm_concept_recall(query="related to SQLite", depth=3) → multi-hop traversal of everything connected

使用方法：

• 默认自动运行：新记忆无需调用工具即可进入图谱。设置 CONCEPT_AUTO_INDEX=false 可恢复为仅手动构建；这会停止工作进程，但仍会记录队列行，因此重新启用后，会处理关闭期间写入的所有内容；CONCEPT_INDEX_DEBOUNCE_SECONDS（30）和 CONCEPT_INDEX_BATCH_SIZE（20）用于控制处理速度。
• 同时适用于两种传输方式，安全可靠：记忆数据库中的租约锁可防止一个进程重建时删除图谱表，而另一个进程正在写入这些表。如果图谱正忙，构建会说明情况，而不会发生冲突。
• 失败绝不会影响你的记忆：索引在写入路径之外通过持久化队列运行。提取出错时会重试；多次失败的记忆会连同错误信息一起搁置，而记忆本身始终可以正常存储和召回。
• 关联代码会显示变更状态：每个关联符号都会带有 freshness 状态。当代码与 MARM 首次建立关联时的代码不同时，状态为 changed，表示相关记忆可能已过时；代码未变时为 unchanged；无法安全获取指纹时为 unknown。指纹计算会忽略空格、空行和重新缩进，因此它是一种实用的源码变更信号，而非语义等价判断；changed 表示代码可能已有变化，不代表记忆有误。只有重新索引完成后才会计算关联项的指纹，并且只有在索引开始后文件未被保存过时才会计算；状态一旦变为 changed，便会保持不变。
• 清空积压队列会降低一些召回速度：实体提取受 CPU 限制，因此工作进程处理队列期间，在真实的 768 条记忆语料库上测得的召回中位数会从约 8ms 增至约 16ms。写入不受影响。只有在积压队列清空期间才会出现这种情况；对大多数人来说，这通常只会在升级后重建时发生一次。可通过 scripts/benchmarking/performance/bench_concept_worker.py --from-live 复现。
• 为积压内容构建索引：对 session_name、project 限定范围，或设置 search_all=True 的 marm_concept_build，会为自动索引功能推出前存储的记忆建立索引，并在升级需要时重建索引。
• 目前已升级两次：在支持平台归属之前，或在以压缩来源取代摘要作为索引行之前构建的图谱，需要运行 marm_concept_build(search_all=True)。完整构建会备份并重置仅包含派生数据的概念数据库；定向构建则不会擅自推断平台归属。
• 旧名称会被标记，而不会被改写：在提取流程停止保留 Markdown 之前构建的图谱，仍可能包含 **apply** 之类的名称。Concept Graph Manager 会通过只读检查统计这些名称，并提供 Rebuild graph 选项，该选项会执行常规重置，然后进行全局构建。不会就地重命名任何内容。
• 完整范围，分页读取：构建会读取范围内的每条记忆。CONCEPT_BUILD_ROW_CAP（默认值为 500）是每页大小；降低该值会让构建读取更多更小的页面，而不是跳过剩余内容。
• 已压缩的会话：原始记忆会建立索引，生成的摘要则不会，因此概念仍会归属于实际表述它们的位置。
• 召回遇到问题时会继续运行：缺失、为空、不兼容或不可用的概念图谱都不会阻止正常记忆召回。响应会单独报告图谱状态。
• 代码交叉关联：当代码图谱已为同一项目建立索引时，与代码符号匹配的概念实体会被关联起来，将“我们做出的决定”与“它在代码中的位置”连接起来。
• 内置提取运行时：spaCy 运行时和英文提取模型随 MARM 一同提供，但只有在首次提取时才会加载；现在，首次提取会在存储第一条记忆后不久自动发生，而不是等到运行构建时才发生。如果安装损坏或不完整，导致无法使用这两者，概念工具会平稳降级，而核心记忆功能仍可使用；运行 marm-memory knowledge status，然后在需要时重新安装 MARM。
• 存储隔离：概念图谱存储在独立的 SQLite 数据库（~/.marm/index/marm_index.db）中，并使用独立的连接池，因此概念图谱写入绝不会阻塞或损坏生产记忆数据库。
• 控制台图谱：Knowledge Graph 会打开一个紧凑且确定性的连通样本，便于快速导航。需要完整图谱时，选择 Render all N nodes。完整图谱模式会隐藏后台关系线，直到你悬停或选择某个节点；这样无需一次性绘制整张蜘蛛网，也能清晰查看该节点的直接连接。 这弥补了扁平记忆搜索留下的跨会话结构缺口：会话用于组织记忆，而概念图则将它们连接起来，因此即使答案涉及来自 3 个不同 Agent 的 5 个会话，也能回答“写入队列依赖什么？”

架构与内部机制

以上所有功能都基于少数经过深思熟虑的机制运行。本节提供完整概览，让你（或你的 Agent）无需猜测服务在做什么。

存储引擎

• 采用 WAL 模式的 SQLite，数据库位于 ~/.marm/marm_memory.db，并使用连接池（5 个连接）。WAL 可在写入期间避免阻塞读取；当多个 Agent 同时检索记忆、而其中一个 Agent 正在写入时，这一点很重要。
• FTS5 全文索引（memories_fts）作为记忆表上的外部内容表进行维护，为精确通道（BM25）和混合检索的筛选阶段提供支持。
• 分块存储：超过约 180 个词的记忆会被拆分为重叠的 150 个 token 分块（重叠 50 个 token），存储在 memory_chunks 表中，每个分块都有自己的嵌入。检索会为分块评分，再将结果归并到父记忆。
• 嵌入由基于 fastembed 的 jinaai/jina-embeddings-v2-small-en 编码器生成：参数量为 33M，维度为 512，上下文窗口为 8,192 个 token，并采用 Apache-2.0 许可证。它不需要单独的查询或文档文本前缀。编码器会在首次进行语义处理时延迟加载，并通过锁进行串行化，以防并发编码导致数据损坏。如果编码器不可用，写入仍会成功；在编码器加载前，记忆会以无嵌入的形式存储。语义评分通过单次 NumPy 批处理（矩阵余弦计算）运行，而非使用 Python 循环。
• 概念图拥有独立数据库（~/.marm/index/marm_index.db）和独立连接池，复用相同的连接池实现，但绝不与记忆存储共享连接。这种隔离是经过刻意设计的：实验性图构建绝不能阻塞生产环境的 WAL。唯一的例外是索引队列；它按设计存放在记忆数据库中，以便记忆及其索引任务能够一同提交；概念图本身仍然是派生且可丢弃的。

写入路径

• 序列化写入队列（默认启用）：所有记忆写入都会经过一个内部异步工作器，消除多 Agent 负载下 SQLite 写入器的争用。该队列是通用的；压缩操作也会经过同一工作器，因此无论哪个子系统执行写入，都只有一个写入器。MAX_QUEUE_SIZE 用于限制队列大小。
• 写入时整合（可选，CONSOLIDATION_ENABLED=1）会在记忆写入前执行两层处理：
  • 第 1 层，精确去重：在会话内检查规范化内容的 SHA-256 哈希；命中哈希后会与实际内容进行比对再去重，因此发生哈希冲突时会存储新行，而不是悄然合并不同内容。
  • 第 2 层，语义合并：余弦相似度超过 CONSOLIDATION_THRESHOLD 的近重复项会被合并，而非不断累积。这不会阻塞写入；如果编码器不可用，写入会继续进行，但不执行整合。
  • 这一权衡经过测量并已公布：写入成本中位数约为原来的 9 倍（58ms，而非 6.5ms），换来的是更整洁的存储，因为记忆工作负载以读取为主。请参阅上文基准测试的第 3 节。
• 概念索引采用持久化发件箱：写入会在与记忆相同的事务中记录索引任务，因此记忆不可能在没有对应任务的情况下存在。后台工作器会处理该队列并写入概念图谱。写入路径上的任何操作都不必等待提取完成；即使进程在提取期间被终止，也不会丢失任务，因为任务以行的形式存储，而非仅存在于内存中的作业。两种传输方式都会运行工作器，因此它们通过记忆数据库中的租约锁进行协调，而不是使用无法跨传输方式生效的进程内锁。
• 压缩（可选，COMPACTION_ENABLED=1）是第 3 层：会话中的写入达到一定数量后，后台处理会检测彼此复述的记忆簇：每对记忆都必须达到余弦相似度阈值并共享大部分词语，同时还要满足最小簇大小、最短存续时间和活动会话宽限期要求，以免压缩进行中的工作。随后，MARM 会注入一条有界请求，要求已连接的 Agent 总结每个记忆簇：candidates → stage → review → apply 或 discard。应用后会保留源记忆 ID，因此压缩后的摘要仍可追溯到原始记忆。暂存的摘要会过期（COMPACTION_STAGING_TTL_HOURS），提醒次数有限且受冷却时间限制，注入内容也有字节预算。该设计清楚界定了 LLM 的作用：MARM 负责检测，Agent 负责总结，并通过可供人工审核的暂存／应用／丢弃流程把关破坏性步骤。

召回路径

详见了解 MARM 记忆：精确通道（FTS5 BM25 + LIKE 回退）、筛选→重排（有界 FTS 候选项 → 批量语义重排 → 时间混合）、带明确截断标志的有界语义回退，以及分块折叠评分。召回深度（detail=1/2/3）决定返回每条记忆的详细程度；每个 MCP 响应都会经过 1MB 响应限制器，由它智能截断内容，而不是破坏协议。

代码图子进程协议

捆绑的图引擎作为受监管的子进程运行，而不是作为导入项：

• 传输：通过子进程的标准输入输出传输以换行符分隔的 JSON-RPC 2.0，并进行经过验证的握手（initialize → 捕获服务端版本 → initialized 通知）。
• 信封处理：扫描响应，选取第一个可解析为 JSON 的内容项，而不假定其位于索引 0，因为上游二进制文件可能会在前面插入更新通知。工具错误通过 result.isError 返回，而不是 JSON-RPC 错误，并会转换为简洁的 {"status": "error"} 字典，同时附上上游提供的修复提示。
• 序列化：使用一个锁保护单个标准输入管道上的每次写入与读取往返；异步调用通过 asyncio.to_thread 执行，因此事件循环不会因子进程 IO 而阻塞。
• 崩溃恢复：后台线程会持续读取标准错误，检测子进程 EOF 或崩溃，并在下次调用时自动重新启动进程。超时会被有意地视为非崩溃情况；长时间运行的索引任务可能仍在处理中，终止它会破坏进行中的工作。
• 监管：一个惰性单例监管器会在进程的整个生命周期内管理客户端。首次调用图工具，或在引擎二进制文件已下载时由自动索引工作器触发启动；启动失败不会向 MCP 层抛出异常，并会验证固定版本二进制文件的工具架构，以便在启动时而非调用中途发现上游变更。
• 自动重新索引通过文件系统监视，并结合 git 内容签名和协调回退机制：捆绑的监视器会在文件保存、提交、分支切换或合并时唤醒工作器；匹配的事件会经过防抖处理，使一连串事件只触发一次重新索引。对于 git 仓库，触发条件会通过计算与 HEAD 的差异哈希，以及未被忽略的未跟踪文件指纹来确认；此计算在引擎外进行，因此空闲检查不会占用引擎锁，并且能够区分同一个已修改文件的两次不同编辑，而不是将它们误认为相同内容。定期协调检查会捕获遗漏的监视器事件，覆盖无法监视的文件系统，并且是非 git 仓库目录的唯一触发方式。运行 git 时会禁用 core.fsmonitor 并清理环境，因为该设置会指定一个程序，而 git 否则可能会从受监视的仓库中执行该程序。
• 所有存储变更都经过同一个闸门：所有三个接口上的手动索引、自动索引工作器和项目删除，都会通过内存数据库中的同一条带租约记录。HTTP 和 STDIO 是两个独立进程，各自拥有一个引擎子进程，但共用一个引擎存储，因此进程内锁无法覆盖它们。租约会在引擎调用实际返回时释放，而不是在调用方停止等待时释放：已取消的请求无法在引擎仍在写入存储时，就将存储交给另一个进程。

可选的本地生成

MARM 从未内置生成模型。概念提取使用 spaCy，搜索使用句子编码器，两者都在本地运行，因此 marm_distill 会选择句子，而不是撰写句子。这不会改变默认行为——只有在操作员启用生成功能（切换 Console 中的 System → Controls 开关，或设置 MARM_LLM_ENABLED=1）并且本地服务可访问时，才会使用生成。仅仅发现正在运行的模型永远不够，没有模型时一切照常运行。

有两项功能会使用它，但都只在每次调用时明确请求后才会启用，而且两者都会降级处理，而不是失败：

• marm_distill(use_llm=true) 会撰写独立完整的事实，而不是提取句子，并保留每条事实所依据的原文片段。提案的 mode 会说明实际发生了什么：generated 表示模型已作答，selected 表示模型未作答。
• marm_code_context(answer=true) 会完成整个流程，用文字回答任务，且仅以其刚刚整理出的上下文为依据——因此，排序决定了答案可以涉及什么。Console 会通过内部路由流式传输答案，因此在其余内容仍在生成时，文本就会逐步显示。该流就是唯一一次请求：它的第一个事件 context 就是整理结果（marm_code_context 返回的负载，或其 no_project/unavailable 状态），答案也恰好基于该整理结果生成，因此 Console 显示的内容与答案所依据的内容来自同一次检索。每次调用都受操作员配置文件的限制：如果模型未能在令牌上限或时间限制内完成回复，或流连接中断，都不会重试并放宽限制；done 会携带 truncated，截断的答案永远不会通过验证。

强制限制为回环地址，而非仅作说明。 如果主机不是回环地址，系统会直接拒绝，而不是发出警告，因为配置错误将其指向托管端点，会在没有任何其他迹象的情况下，悄悄把对话记录和源代码发送出机器。可使用覆盖项，但必须完整声明意图（MARM_LLM_ALLOW_REMOTE=i-understand-this-leaves-my-machine），拒绝信息中也会指出该设置项。

所有失败都会返回 None，绝不会抛出异常。 模型未就绪、GPU 繁忙、容器已停止或回复格式错误，都会降级为“本次没有模型答案”。调用方会根据 None 分支处理，而不是捕获异常。内存工具不能因为无关的容器被重启就停止工作。

本地证据分析器

marm_code_context(answer=true) 是一个有界的只读分析器。MARM 负责检索；本地模型只读取 MARM 检索到的内容；确定性代码会在返回任何结果前对其进行判断。模型不会搜索、获取更多上下文、写入记忆或调用工具。

• 一份证据包。 组合内容会固化为一个证据包，包含可引用的句柄（符号使用 S1…，记忆使用 M1…）和内容哈希 packet_id。无论调用方请求的 budget 是多少，配置文件都会限制证据包的内容；answer_packet 会报告证据包的大小及限制导致的遗漏。

• 由操作员选择的配置文件。 general 会像以前一样生成一条自由格式答案。small 会通过 5 次调用执行 5 项范围明确的操作：摘要、带有逐字 quote 的有依据事实、调用和记忆关系、缺失的证据，以及低风险的后续步骤（读取、比较、验证或询问）。large 会在一次调用中执行相同的 5 项操作。每项操作都会返回固定架构的 JSON；在支持的情况下，会向服务请求 json_schema 格式，并且无论是否支持都会进行验证；不符合要求的条目会被丢弃并计数，绝不会修补。可在 System > Controls 中设置配置文件，也可使用 MARM_ANALYST_PROFILE 设置，绝不会根据模型推断。

• 硬性限制。 每次调用都会请求配置文件所设的上限，以及答案令牌数和任何推理额度，并且绝不会以更宽松的限制重试。超过时间限制后不会开始任何调用，也不会有调用超时继续运行。answer_model_info 会报告上限、调用次数、耗时以及运行是否提前停止；被截断的答案绝不会经过验证。

• 逐项验证每条结果。 如果被引用的句柄不在证据包中，就会被拒绝。只有当事实的引文在其引用的条目中逐字出现时，该事实才算有依据；只有当证据包中存在对应边时，调用关系才算成立；只有当记忆绑定到符号或提及该符号时，记忆关系才算成立；只有当每项声明所断言的内容都出现在其引用的证据中时，该声明才算成立。若一项声明没有任何可供检查并判定失败的内容，就不算通过验证。只有每项实质性结果都通过验证且所有操作均已完成，答案才标记为 verified；否则标记为 uncertain，并在 answer_status 中报告为 ok、unverified 或 rejected。answer_items 会携带每项结果、其状态以及支持它的依据。

• 代码与记忆不一致。 如果某条记忆描述的调用与证据包图谱相矛盾，或图谱未显示该调用，就会将其列入 answer_disagreements，而不询问模型。

• 三种模式（analyst_mode），每种模式只负责一件事。默认模式 read_only 仅根据证据包作答，不做其他任何事：不检索、不暂存、不写入。manual_review 会将已验证答案中的结果作为 marm_distill 提案暂存，并标记 origin: "analyst"，供人员应用或丢弃。guardrails 会以相同方式暂存这些结果，并允许 MARM 机械地应用可证明的结果，但仅限操作员已开启自动应用时。模型绝不会应用任何内容，审核过程也绝不会向模型询问任何内容：只有验证结果为 verified 的答案才会被暂存，因此不确定的答案无法通过重新表述变为已验证。 仅对可通过机械方式验证的声明自动应用。 每项暂存结果都会标明其声明类型。MARM 会应用 call_edge（由 MARM 根据数据包调用边写入）、identifier_in_range（MARM 自行说明所引用符号的定义位置）、quoted_span 或 verbatim_statement（引用来源或记忆中的完整句子或整行，绝不使用片段，因为片段可能会漏掉对其起限定作用的否定词），并在作出决定前重新检查类型是否与存储的类型一致。其他任何内容，包括引用再充分的转述，都会返回 review_required。其他检查包括：操作员已开启自动应用开关；作出决定时会重新解析提案，且其状态仍为 new；内容为一行，长度为 12 到 300 个字符；内容中没有任何看起来像凭据的内容，无论是带标签的（api_key=），还是采用已知令牌格式的（提供商密钥、Bearer 值、JWT、带密码的 URL）。对 marm_distill 设置 review_mode="guardrails" 后，系统会对提炼出的提案作出相同决定；这类提案的片段必须逐字出现在源文本中。每项决定，无论是否应用，都会在任何写入发生前记录到提案中；如果之后写入未能完成，状态会变为 apply_failed，并附上错误信息。已应用的提案会报告为 applied，不再计入待审核项。

JSON 响应和流共用同一套实现，并返回相同的验证结果。读者关闭流后，生成也会停止。scripts/eval-analyst.py 会在任意配置下，使用运行中的本地模型运行 tests/fixtures/analyst_eval.json 中的评估矩阵。

这就是 marm_code_context(answer=true) 的行为约定；如果模型不可达或未返回任何内容，它会返回 "answer": null。Console 的流式路由无法使用它，因为生成失败时流已经开始：该路由会发出一个 SSE error 事件，其 JSON data 中包含 message；如果完全没有可用模型，还会包含 hint。两种情况的结果都一样——排名后的上下文仍然保留，只是缺少答案——但读取流的客户端会根据事件分支，而不是根据 null 值分支。

端点按以下顺序解析：在 Console 中保存的运行时选项，然后是 MARM_LLM_URL，接着是自动发现，最后是内置默认值。自动发现会扫描常见本地运行时使用的环回地址端口，并报告实际“作出响应”的服务，而不是通常使用该端口的服务，因此 MARM 无需重启或更改配置，就会跟随当前实际提供服务的服务器。显式指定的端点始终优先，因此，如果你设置的地址不可用，系统会如实显示该地址不可用，而不会悄悄替换它。

Console 的 System → Controls 选项卡会显示所有这些信息：哪个服务作出了响应以及如何选定该服务、它提供的模型、在常见本地目录中找到的模型文件，以及一个可将选项固定为持久运行时标志的选择器。

安全与速率限制

• 双模式身份验证：环回地址（127.0.0.1）上无需密钥；服务器一旦暴露到网络（SERVER_HOST=0.0.0.0、Docker），就必须设置 MARM_API_KEY（Bearer）。--generate-key 可生成密钥。默认安全，在本地使用时无需任何设置。
• 基于 IP 的速率限制，采用滑动窗口和临时封禁，可通过 CLI 预设进行调整，无需在复杂配置中摸索（见下表）。
• 本地优先：所有内容都存放在 ~/.marm/ 下；不进行云同步、遥测或外部存储。
• 平滑关闭：SIGTERM/SIGINT 处理程序会排空并干净地关闭连接池；内部事件系统会运行自动化回调，并对每个回调单独隔离错误并设置超时，避免某个异常钩子卡住服务器。

Swarm 和多 Agent 预设

无论使用哪种预设，写入队列都会串行处理内存写入；swarm 标志则在此基础上调整 HTTP 速率限制。队列负责控制写入顺序；整合和压缩属于独立的内存维护层。此技术栈（WAL + 连接池 + 单个串行写入器 + RPM 预设）有意限定在“SQLite、多 Agent、单台机器”的场景；分布式多节点内存不在当前设计的范围内。

自动维护文档

启动时，打包的文档会被索引到 marm_system 内存命名空间中，并每 50 次工具调用刷新一次。系统会跟踪源文件哈希，因此不会重新处理未更改的文档，而更改或删除的条目则会重新索引。连接的 Agent 可以通过 marm_smart_recall 回答 MARM 使用问题，无需你把文档粘贴给它们。

配置参考

故障排除

marm-memory maintenance embeddings migrate

marm-memory maintenance chunks rechunk

有关记忆行为、传输方式、支持的客户端、压缩和备份的问题，请参阅 FAQ。

Star 历史

MARM 欢迎各个层面的贡献者。代码固然有帮助，文档、设置说明、客户端测试、错误报告、基准测试，以及日常使用 AI 工具的人分享的真实工作流反馈，同样重要。

欢迎参与的方式：

• 使用更多 MCP 客户端、IDE Agent 和操作系统测试 MARM
• 改进文档、截图、示例和特定平台的设置说明
• 报告错误或令人困惑的安装步骤，并提供清晰的复现细节
• 分享实际使用中的记忆工作流、Agent 习惯和工具创意
• 查看未解决的问题

💡 想在此列表中留下你的名字吗？请查看我们的 CONTRIBUTING.md 指南，开始参与！

加入 MARM 社区

助力构建 AI 记忆的未来——无需编写代码！

交流： MARM Discord | GitHub 讨论区

许可证与使用声明

版权所有 © 2026 Ryan A. Lyell。MARM 基于 Apache 2.0 License 发布（版权声明请参阅 NOTICE），欢迎分支、实验和集成。MARM 也封装了 codebase-memory-mcp 等第三方开源组件，这些组件采用 MIT 许可证；版权归属信息请参阅 THIRD_PARTY_NOTICES.md。如果你基于 MARM 构建项目，请让非官方版本易于与官方 MARM 仓库发布的版本区分开来，以便用户了解自己安装的是什么。

项目文档

使用指南

• README.md - 本文件：完整使用指南、工具参考、工作流和架构
• PROTOCOL.md - MCP 操作协议
• FAQ.md - 关于使用 MARM 的常见问题解答

MCP 服务安装

• INSTALL-DOCKER.md - Docker 部署（推荐）
• INSTALL-WINDOWS.md - Windows 安装指南
• INSTALL-MACOS.md - macOS 安装指南
• INSTALL-LINUX.md - Linux 安装指南
• INSTALL-PLATFORMS.md - 平台安装指南

项目信息

• CONTRIBUTING.md - 如何为 MARM 做贡献
• CHANGELOG.md - 版本历史和更新
• ACKNOWLEDGMENTS.md - 贡献者和致谢
• ROADMAP.md - 计划中的功能和开发路线图
• LICENSE - Apache 2.0 许可证条款