Agent Memory MCP

agent-memory-mcp

面向工程 Agent 的记忆、文档和代码库上下文层。

agent-memory-mcp 帮助 Agent 使用实时工程上下文，而不只是孤立的笔记。它结合了类型化记忆、文档检索和代码库感知工具，让 Claude、Cursor、Codex 及其他 MCP 客户端能够回忆决策、搜索运维手册、检查项目文档，并在不同会话间复用运维知识。

它专为以下工程工作流设计：

• DevOps 和平台运维
• 基础设施变更和回滚规划
• 运维手册、变更日志、RFC 和事后复盘
• 与代码库保持关联的项目级记忆

适用对象

• 在真实代码库、文档和运维工作流中使用 AI Agent 的团队
• 需要的不只是聊天记录的 DevOps、平台和基础设施工程师
• 希望今天使用本地优先记忆、之后再接入共享服务的项目

为什么不只用记忆工具

大多数记忆 MCP 服务专注于“存储一条笔记，再回忆一条笔记”。

agent-memory-mcp 面向更广泛的工程上下文层：

• 用于决策、事实、模式和工作上下文的类型化记忆
• 为项目文档、变更日志和知识文件建立 RAG 索引
• 用于读取和搜索允许访问的项目路径的代码库/文件工具
• 本地 SQLite 存储；目前支持 stdio，需要共享时可使用 HTTP/JSON-RPC

当 Agent 需要回答以下问题时，它会更加适用：

• “我们为什么要在这个服务上禁用 HPA？”
• “最近有哪些变更可能解释这次回归？”
• “哪份运维手册或 RFC 与这次事件相符？”

目录

• 适用对象
• 为什么不只用记忆工具
• 功能
• 为用户带来的改进
• 3 分钟内本地启动
• 仅本地模式
• 用 2 条命令为代码库建立索引
• 之后将其改为团队服务
• 安装选项 — Homebrew、二进制文件、源码、Docker
• CLI 模式
• MCP 客户端配置 — Claude Desktop、Cursor、Codex
• 推荐的工作流片段 — 可粘贴到 CLAUDE.md / .cursorrules 的内容
• CLI 命令
• MCP 工具参考 — 以及 docs/MCP_TOOLS.md 中的 JSON 示例
• 配置 — 环境变量、热重载、索引安全
• 安全与运维
• 架构
• macOS 服务安装
• 故障排除 / 常见问题
• 开发

参考文档：HOOKS · MCP_TOOLS · SHARED_SERVICE · STEWARDSHIP · SEDIMENTATION · BACKUP_RESTORE · SECURITY · THREAT_MODEL · CONTRIBUTING · CHANGELOG

功能

• 自动捕获会话内容 — Claude Code 钩子会在会话结束时自动捕获知识，在上下文压缩前保存检查点，并在会话开始时整理待处理的摘要
• 带类型的持久化记忆，分为 4 种类型：情景记忆、语义记忆、程序记忆、工作记忆
• 混合检索，结合嵌入向量与类似关键词/BM25 的排序
• RAG 索引，用于项目文档、变更日志和知识档案（在 stdio/CLI 模式下默认启用；在 Homebrew 服务预设中默认禁用 — 参见安装选项）
• 支持仓库感知的文件工具，用于列出、读取和搜索允许访问的路径
• 知识维护 — 自动执行维护任务：检测重复内容、解决冲突、识别过时内容、扫描偏差，并提供审核收件箱
• 时序知识模型 — 跟踪知识的有效时间，构建取代链，并查询“时间 T 时哪些内容为真”
• 双传输方式：为 MCP 客户端提供 stdio，为 API 和共享设置提供 HTTP/JSON-RPC
• 使用 SQLite 存储记忆和向量索引——无需外部数据库
• 自动索引，通过文件监视器支持长时间运行的本地模式或服务模式

为用户带来的改进

• 降低内存用量：记忆存储现在直接从 SQLite 读取，而不是将所有内容加载到 RAM 中——大型记忆库不再有 OOM 风险
• 明确的单人本地配置：一种推荐布局、一个数据目录、一条快速冒烟测试路径
• 自动加载 .env：从项目根目录运行，无需手动加载环境变量
• 仅限本地的嵌入模式：保持托管服务提供商处于禁用状态，仅将文本发送到本地 Ollama 端点
• 更安全的语义检索：来自不同嵌入模型的记忆不再产生误导性匹配
• 明确的迁移流程：切换模型后，使用 agent-memory-mcp reembed 迁移记忆，使用 agent-memory-mcp index 重建 RAG 索引
• 更清晰的可见性：stats 和 memory_stats 会显示属于各嵌入模型的记忆数量，并列出任何语义查询都无法触及的记录——编码器明确拒绝的记录，以及仅根据其开头生成嵌入的记录
• 即用型 MCP 客户端配置：为 Claude Desktop、Cursor 和 Codex 生成可直接复制粘贴的配置片段
• 更安全的索引默认设置：内置目录排除规则、可选的逐路径排除 glob，以及文档建立索引前的机密信息脱敏
• 感知来源的检索：对文档、ADR、RFC、变更日志、运行手册、事后复盘、CI 配置、Helm、Terraform 和 K8s 文件进行分类，并附带来源元数据
• 混合搜索排序：语义相似度现在会结合关键词匹配、时效性和来源权重，而不再只依赖余弦相似度
• 感知可信度的检索：记忆和文档结果现在会公开 source_type、confidence、freshness、owner 和 last_verified_at，排序也会考虑可信度和时效性，而不再只依据相似度
• 可解释的检索：启用调试输出后，每条结果都会显示筛选条件、评分组成部分和应用的加权项
• DevOps 优先的工具：使用面向特定领域的 MCP 工具存储决策、事件、运行手册和事后复盘，而不是调用通用记忆工具
• 记忆生命周期：记忆会经历不同状态——active、outdated、superseded、canonical，因此过时知识会自动降低排名，不再污染检索结果
• 手动整合工作流：合并重复项、标记过时笔记、提升规范条目，并检查冲突组，同时保留历史记录
• 明确的规范知识层：单独列出和检索已确认知识，并在项目摘要中优先显示规范上下文
• 项目记忆库视图：按类别查看整理后的知识——决策、运行手册、事件、注意事项、迁移、审核队列——而不是平铺的记忆列表
• 会话结束流程：会话结束时，系统会分析、分类并将记忆与现有知识整合，而不是不加判断地直接追加
• 可解释的整合：会话结束报告会展示将要新增、合并、标记过时或提升的内容，并为每项操作提供决策轨迹和风险等级
• DevOps 会话模式：close-session 会根据会话类型调整行为——事件和迁移会话采用更严格的优先审核策略，编码会话则会自动应用低风险更新
• 共享服务打包：提供可运行的 Docker Compose 配置、共享环境模板、nginx 反向代理示例，以及专门的共享部署指南
• 内置检索控制台：通过 /console 上的轻量级 HTTP UI 检查混合排序、可信度，以及普通和调试模式下的检索结果
• 更安全的 HTTP 默认设置：HTTP 模式默认绑定到 127.0.0.1；绑定到非回环地址时必须进行身份验证，除非明确选择不安全的无身份验证访问
• 一致的 CLI 和 MCP 行为：记忆类型验证、标签规范化、查询/内容限制和可信度摘要现在在两个接口中遵循相同策略
• 知识维护：steward_run 通过一条命令执行完整维护周期——检测重复项、解决冲突、扫描过时条目，并找出规范条目候选项
• 维护收件箱：维护运行、漂移扫描和会话整合中需要审核的操作会进入同一个可处理队列，而不是被悄然应用或丢失
• 漂移检测：drift_scan 会将记忆条目与实时仓库文件和文档进行比对，找出过时、缺失或已更改的引用
• 验证模型：verify_entry 和 verification_candidates 让 Agent 和用户能够跟踪知识上次验证的时间，以及哪些内容需要关注
• 规范知识健康诊断：维护运行现在会为规范条目提供健康摘要，标出过时、未经验证、存在冲突和支持度较低的条目
• 由策略管理的自动化：可通过 steward_policy 和环境变量配置维护阈值、自动应用规则和调度
• 时态知识：记忆可以带有 valid_from / valid_until 时间戳，recall_as_of 可以检索在特定时间点有效的知识
• 替代链：使用替代条目标记过时条目时，mark_outdated 会自动建立双向链接（superseded_by / replaces）并设置时间边界
• 知识时间线：knowledge_timeline 显示某个主题的知识随时间演变的情况
• 考虑年龄的检索（可选）：检索评分可以应用指数年龄衰减，让过时记忆排名下降，同时保留规范知识和特征/身份信息——默认关闭，因为 T121 的测量结果显示，在旧的 30 天设置下，Hit@5 从 0.7217 降至 0.1942。使用 MCP_RECALL_HALFLIFE_DAYS 启用，并注意 MCP_RECALL_DECAY_TYPES（默认值为 working）决定哪些类型会随时间衰减——类型维度比衰减速率更重要
• 自我修复式重复项清理：维护程序可以自动合并置信度高、几乎相同的重复项组，而不只是将它们加入审核队列——此功能需显式启用，并受内容相似度阈值保护，避免归档任何独特内容（在 steward_policy 中设置 auto_merge_duplicate_min_confidence）
• 不再生成重复的会话结束记录：结束任务时，系统会将自动捕获的会话摘要合并到最终记录中，而不是针对每个 slug 再写入一条几乎相同的记忆，从而减少维护程序过去误报为虚假矛盾的重复项对

3 分钟启动本地服务

建议的步骤是：先在本地运行，在一个仓库中验证价值，然后再扩展。

在项目根目录运行这些命令。

前提条件

通过以下任一方式安装二进制文件：

# Homebrew (macOS/Linux) — recommended, auto-configures Claude Code hooks
brew tap ipiton/tap
brew install agent-memory-mcp

# go install
go install github.com/ipiton/agent-memory-mcp/cmd/agent-memory-mcp@latest

然后配置一个嵌入提供方：

• 使用 Jina AI API key，快速完成托管配置
• 使用 OpenAI API key 或其他兼容 OpenAI 的端点
• 使用 Ollama 和 bge-m3，进行本地配置

1. 配置本地模式

cp .env.example .env
# Edit .env:
# - keep the solo-local defaults unless you need to change them
# - enable at least one embedding provider
#   JINA_API_KEY, OPENAI_API_KEY, or OLLAMA_BASE_URL

二进制文件会自动从当前目录加载 .env，因此无需运行 source .env。

建议的单人本地预设会将所有运行时状态保存在同一个目录中：

.agent-memory/
  rag-index/
  memory-store/
  logs/

仅本地模式

如果希望使用嵌入功能，又不想将文本发送到托管 API，请使用仅本地模式。

cp .env.example .env
# Then set:
# MCP_EMBEDDING_MODE=local-only
# JINA_API_KEY=
# OPENAI_API_KEY=

在 local-only 模式下：

• agent-memory-mcp 不会调用 Jina AI
• agent-memory-mcp 不会调用兼容 OpenAI 的嵌入 API
• 仅通过本地后端生成嵌入：Ollama 或 llama.cpp

仍会使用网络的部分：

• 本地 Ollama HTTP 端点，通常为 http://localhost:11434
• 或本地 llama.cpp 服务，通常为 http://127.0.0.1:8080/v1

如果没有正在运行的本地后端，或没有可用的受支持本地模型，嵌入请求会失败，并返回仅本地模式专属错误，提示你启动后端或禁用 MCP_EMBEDDING_MODE=local-only。

备选本地后端：llama.cpp

如果你已经在运行 llama.cpp（Apple Silicon 原生支持，使用 GGUF 模型），可以将服务指向其兼容 OpenAI 的 /v1/embeddings 端点，而不必安装 Ollama。此功能需显式启用——设置 LLAMACPP_BASE_URL 即可启用。设置后，它会加入 Ollama 之前的回退链（Jina → OpenAI → llama.cpp → Ollama），并可在 local-only 模式下使用。

# Start llama.cpp with an embedding model
llama-server -m bge-m3.gguf --embedding --pooling cls -c 8192 -ub 8192

# Then configure the MCP server
LLAMACPP_BASE_URL=http://127.0.0.1:8080/v1
LLAMACPP_EMBEDDING_MODEL=bge-m3
MCP_EMBEDDING_MODE=local-only

llama.cpp 返回模型的原生嵌入维度，因此请确保 MCP_EMBEDDING_DIMENSION 与之匹配（bge-m3 为 1024）——维度不匹配会在召回时被拒绝。

在速度较慢的自托管硬件上（例如低核心数或 ARM VPS 上运行带有 bge-m3 的 Ollama），单个文本块的嵌入可能需要 4-7 秒，默认的 5s 超时会反复触发。请提高限制：

MCP_EMBEDDING_TIMEOUT=30s      # default 5s
MCP_EMBEDDING_MAX_RETRIES=3    # default 1

无效值会回退到默认值，因此服务仍可启动。

启用自动索引 / 文件监视器时的并发调优

单槽 llama-server 会严格串行处理请求。启用 MCP_RAG_AUTO_INDEX / MCP_RAG_FILE_WATCHER 后，后台重新索引批次（每批 50 个文本块）会独占唯一槽位数十秒，导致交互式 recall / semantic_search / index_documents 排在它们后面并触发 context deadline exceeded——即使吞吐量正常，服务看起来也会“性能下降”。为嵌入服务增加并行槽位，让交互式调用能够与批次并行执行：

llama-server -m bge-m3.gguf --embedding --pooling cls \
  -c 32768 -b 8192 -ub 8192 \   # 8192 ctx PER SLOT (see note) — fits the largest chunk
  -np 4 -cb \                   # 4 slots + continuous batching: interactive calls don't wait for the batch
  --metrics                     # exposes Prometheus /metrics; /slots shows live slot occupancy

-np 会拆分上下文。 每个槽位的上下文大小为 ctx_size / n_parallel。bge-m3 是编码器——每个文本块必须完整放入一个槽位，并且 -b/-ub 必须大于或等于最大文本块的 token 数，否则会失败并显示“input too large to process”。因此，使用 -np 4 时，需要设置 -c 32768，以便每个槽位保留 8192；增加槽位时，不要将 -c、-b 或 -ub 调低到单槽配置的值以下。

测得的效果（Apple Silicon，bge-m3 Q8_0）：50 个输入组成的批次处理时间从约 50s 降至约 5s；批次负载下的交互式探测从 8–20s 降至约 0.03s。

对于经常编辑的大型文件，也要缓解重新索引时的突发负载（每次编辑都会对整个文件重新分块，可能在周期中途再次触发）：

MCP_RAG_DEBOUNCE=2m         # default 30s — collapses bursts of edits into one reindex
MCP_RAG_WATCH_INTERVAL=5m   # periodic full-scan cadence

2. 启动本地服务

适用于 Claude Desktop、Cursor 或 Codex 等 MCP 客户端：

agent-memory-mcp

如需直接使用 CLI，同一二进制文件无需 MCP 客户端也可运行：

agent-memory-mcp store -content "Ingress rollback uses previous Helm revision" -type procedural -tags "helm,rollback"
agent-memory-mcp recall "helm rollback"
agent-memory-mcp stats

3. 运行冒烟检查

agent-memory-mcp store -content "Solo local smoke check" -type working -tags "smoke,local"
agent-memory-mcp recall "solo local smoke"
agent-memory-mcp index
agent-memory-mcp search "agent memory"

如果你使用的是源代码检出目录，可以通过以下命令运行相同流程：

make local-smoke

用 2 条命令为你的仓库建立索引

在项目中运行本地模式后，为文档建立索引并进行搜索：

agent-memory-mcp index
agent-memory-mcp search "recent ingress change"

通常价值较高的来源包括：

• docs/
• README.md
• CHANGELOG.md
• RFC / ADR 文件夹
• 运维手册和事故记录

之后将其转变为团队服务

本地模式证明有用后，分 3 步进行迁移：

1. 个人本地使用
2. 团队成员的笔记本电脑，启用自动索引和文件监视
3. 共享服务，启用 HTTP 模式、身份验证令牌和反向代理

最快的共享服务方案：

cd deploy/docker
cp .env.shared.example .env.shared
# edit MCP_HTTP_AUTH_TOKEN and MCP_PROJECT_ROOT
docker compose --env-file .env.shared up -d --build

这样既能保留相同的检索栈，又能将其打包供团队使用。

参考文档：

• 共享服务指南
• 安全策略
• 备份与恢复

安装选项

Homebrew（推荐用于 macOS）

brew tap ipiton/tap
brew install agent-memory-mcp
brew services start agent-memory-mcp

此操作会安装二进制文件、创建默认配置，并在 127.0.0.1:18080 上启动服务，同时启用记忆功能。RAG 文档搜索默认处于禁用状态——编辑配置以启用它：

# Edit config
nano $(brew --prefix)/etc/agent-memory-mcp/config.env

设置 MCP_RAG_ENABLED=true、MCP_ROOT=/path/to/your/project 和 MCP_INDEX_DIRS=docs,README.md。更改会在约 30 秒内自动生效，也可以通过 kill -HUP $(pgrep agent-memory-mcp) 强制重新加载。

管理服务：

brew services restart agent-memory-mcp
brew services stop agent-memory-mcp
brew services info agent-memory-mcp

如果你之前通过 Cask 安装，现在想使用 brew services：

brew uninstall --cask agent-memory-mcp
brew install ipiton/tap/agent-memory-mcp

下载二进制文件

从 发布页面 下载预构建的归档文件。

发布归档文件名中包含版本号，因此请先解析最新标签：

# Resolve latest version once
VERSION=$(curl -fsSL https://api.github.com/repos/ipiton/agent-memory-mcp/releases/latest \
  | grep '"tag_name"' | head -1 | cut -d'"' -f4 | sed 's/^v//')

# macOS (Apple Silicon)
curl -fsSL "https://github.com/ipiton/agent-memory-mcp/releases/download/v${VERSION}/agent-memory-mcp-${VERSION}-darwin-arm64.tar.gz" | tar xz
sudo mv agent-memory-mcp /usr/local/bin/

# macOS (Intel)
curl -fsSL "https://github.com/ipiton/agent-memory-mcp/releases/download/v${VERSION}/agent-memory-mcp-${VERSION}-darwin-amd64.tar.gz" | tar xz
sudo mv agent-memory-mcp /usr/local/bin/

# Linux (x86_64)
curl -fsSL "https://github.com/ipiton/agent-memory-mcp/releases/download/v${VERSION}/agent-memory-mcp-${VERSION}-linux-amd64.tar.gz" | tar xz
sudo mv agent-memory-mcp /usr/local/bin/

# Linux (arm64)
curl -fsSL "https://github.com/ipiton/agent-memory-mcp/releases/download/v${VERSION}/agent-memory-mcp-${VERSION}-linux-arm64.tar.gz" | tar xz
sudo mv agent-memory-mcp /usr/local/bin/

从源代码构建

git clone https://github.com/ipiton/agent-memory-mcp.git
cd agent-memory-mcp
go build -o bin/agent-memory-mcp ./cmd/agent-memory-mcp

Docker

docker build -f deploy/docker/Dockerfile -t agent-memory-mcp .
docker run -p 18080:18080 \
  -v memory-data:/data \
  -e MCP_HTTP_MODE=http \
  -e MCP_HTTP_HOST=0.0.0.0 \
  -e MCP_HTTP_AUTH_TOKEN=replace-with-long-random-token \
  agent-memory-mcp

也可以使用 docker compose：

cd deploy/docker
cp .env.shared.example .env.shared
docker compose --env-file .env.shared up -d --build

MCP HTTP 端点将在 http://localhost:18080/mcp 上可用。

现在，裸机 HTTP 模式默认绑定到 127.0.0.1。对于共享部署或容器部署，请设置 MCP_HTTP_HOST=0.0.0.0 和 bearer token。

CLI 模式

此二进制文件也可以作为独立 CLI 使用：

# Memory operations
agent-memory-mcp store -content "Project uses chi router" -type procedural -tags "go,chi"
agent-memory-mcp recall "router middleware"
agent-memory-mcp list -type procedural
agent-memory-mcp delete <memory-id>

# RAG search
agent-memory-mcp search "authentication flow"
agent-memory-mcp search -source-type runbook "ingress rollback"
agent-memory-mcp search -source-type runbook -debug "ingress rollback"
agent-memory-mcp index

# Project bank and session close
agent-memory-mcp project-bank canonical_overview
agent-memory-mcp close-session -summary "Updated payments rollback runbook after fixing ingress timeout" -context payments-api -service payments-api
agent-memory-mcp review-session -mode incident -stdin < notes/session.txt
agent-memory-mcp accept-session -summary "Added migration caveat for billing schema rename" -mode migration -context billing -service billing-api
agent-memory-mcp accept-session -raw-only -summary "Exploratory notes that are too noisy for consolidation"

# Utilities
agent-memory-mcp stats
agent-memory-mcp config claude-desktop
agent-memory-mcp reembed
agent-memory-mcp export > backup.json
agent-memory-mcp import backup.json

# JSON output for scripting
agent-memory-mcp recall "test" -json
agent-memory-mcp stats -json

运行 agent-memory-mcp <command> -help 可查看任意命令的详细信息。

CLI 记忆命令和 MCP 记忆工具现在共用相同的验证和规范化规则：

• 无效的记忆类型会被一致地拒绝
• 逗号分隔的标签会以相同方式去除空格并去重
• 在 CLI 和 MCP 输出中，值为零的 verified 时间戳不会显示在信任摘要中

未提供命令（或标志以 - 开头）时，此二进制文件会像以前一样启动 MCP 服务——完全向后兼容。

MCP 客户端配置

使用内置生成器创建项目本地配置，从仓库根目录启动服务。

推荐使用此方式，因为它：

• 无需将设置重复添加到每个 MCP 客户端，就能让 .env 加载正常工作
• 使 .agent-memory/ 相对于项目根目录
• 为每个客户端提供一段可复制粘贴的配置

你可以使用 -root 和 -command 覆盖检测到的项目根目录或二进制文件路径。

Claude Desktop

粘贴到 ~/Library/Application Support/Claude/claude_desktop_config.json：

agent-memory-mcp config claude-desktop

生成的输出示例：

{
  "mcpServers": {
    "memory": {
      "command": "/bin/sh",
      "args": [
        "-lc",
        "cd '/path/to/your/project' && exec '/absolute/path/to/agent-memory-mcp'"
      ]
    }
  }
}

Cursor

粘贴到 ~/.cursor/mcp.json：

agent-memory-mcp config cursor

生成的输出示例：

{
  "mcpServers": {
    "memory": {
      "command": "/bin/sh",
      "args": [
        "-lc",
        "cd '/path/to/your/project' && exec '/absolute/path/to/agent-memory-mcp'"
      ]
    }
  }
}

Codex

粘贴到 ~/.codex/config.toml：

agent-memory-mcp config codex

生成的输出示例：

[mcp_servers.memory]
command = "/bin/sh"
args = ["-lc", "cd '/path/to/your/project' && exec '/absolute/path/to/agent-memory-mcp'"]

重命名服务或覆盖路径

agent-memory-mcp config claude-desktop \
  -name engineering-memory \
  -root /path/to/your/project \
  -command /absolute/path/to/agent-memory-mcp

推荐的工作流片段

如果不添加这些片段，Agent 只会使用基本的 store_memory 和 recall_memory。若要启用会话结束处理、工程记忆类型、项目知识库和整合功能，请将相关片段添加到 Agent 的指令中。

添加位置：

• Claude Code — 粘贴到项目根目录下的 CLAUDE.md
• Cursor — 粘贴到项目根目录下的 .cursorrules
• Codex — 粘贴到系统提示词或 AGENTS.md 中
• Claude Desktop — 粘贴到项目设置中的系统提示词字段

选择与你的工作流相匹配的片段。从“会话开始时回顾”和“编码结束”开始——它们涵盖了最常见的用例。

会话开始时的回忆

Before you start, recall the project context for this task.
Then recall recent changes related to the service or component I am touching.
Search for relevant runbooks, RFCs, changelog notes, or incident notes.
Prefer `summarize_project_context` or `project_bank_view view=canonical_overview` for the first pass and then drill into `search_runbooks` or `recall_similar_incidents`.
Summarize the constraints, caveats, and likely risks before making changes.

编码结束

When the coding session ends, call `close_session` with a concise summary, service, and context.
Review the proposed `new`, `update`, `merge`, and `raw_only` actions plus the decision trace.
If the plan looks low risk, use `accept_session_changes`.
If the report is noisy or mostly exploratory, keep `save_raw_only` as the fallback.
Prefer `project_bank_view` at the next session start to confirm what became maintained knowledge.

事件处理结束

When incident work stabilizes, call `close_session` or `review_session_changes` with `mode=incident`.
Expect stricter review-first behavior for updates, merges, and anything touching canonical operational knowledge.
Capture impact, mitigation, rollback, and unresolved follow-ups in the summary.
Apply only the low-risk actions automatically and leave ambiguous runbook or incident changes in review.
Follow up with `recall_similar_incidents` and `project_bank_view view=incidents` if you need to compare against existing knowledge.

迁移结束

When a migration session ends, call `close_session` with `mode=migration`, affected service, and the migration summary.
Prefer explicit notes about prerequisites, sequencing, rollback, and post-deploy verification.
Treat runbook replacements, caveat changes, and supersede proposals as review-first even when the textual match looks strong.
Use `accept_session_changes` only after checking the report for stale or superseded knowledge.
Finish by checking `project_bank_view view=migrations` to see the maintained migration notes.

仅原始记忆的回退方案

If the session was exploratory, ambiguous, or too noisy, skip consolidation and save only the raw summary.
Use `close_session` / `review_session_changes` to inspect the plan first, then pick `save_raw_only`.
In CLI mode, `agent-memory-mcp accept-session -raw-only ...` is the explicit override.
This keeps the raw trace without forcing weak knowledge updates into the project bank.

更改基础设施前的检查

Before making infra or platform changes, recall similar fixes, migrations, incidents, and known caveats.
Search for runbooks, postmortems, changelog notes, and recent project context related to this component.
Summarize blast radius, rollback options, and operational risks before editing files.

管理运行

When memory has grown or a session just ended, run `steward_run` with `dry_run=true` to see what needs attention.
Review the report for duplicates, conflicts, stale entries, and canonical promotion candidates.
Check `steward_inbox` for pending review items and resolve them with `steward_inbox_resolve`.
Use `drift_scan` periodically to catch memories that reference files or docs that have changed.
Use `verification_candidates` to find knowledge that has not been verified recently.

时间回溯

When you need to understand what was true at a specific point in time, use `recall_as_of` with an RFC3339 timestamp.
To trace how knowledge about a topic evolved over time, use `knowledge_timeline`.
When superseding an old decision or runbook, use `mark_outdated` with the superseding entry ID to build a proper chain.

HTTP 模式（Docker、远程服务、共享实例）

以 HTTP 模式启动服务：

# Standalone
MCP_HTTP_MODE=http \
MCP_HTTP_HOST=127.0.0.1 \
MCP_HTTP_PORT=18080 \
MCP_HTTP_AUTH_TOKEN=replace-with-long-random-token \
agent-memory-mcp

# Or with Docker
cd deploy/docker
docker compose --env-file .env.shared up -d --build

然后将支持 HTTP 的 MCP 客户端或代理指向：

http://localhost:18080/mcp

/mcp 端点支持 MCP Streamable HTTP 传输：JSON-RPC 请求通过 POST 发送；需要服务器推送通道的客户端（Cursor 及类似客户端）通过 GET 和 Accept: text/event-stream 打开该通道。服务器会定期发送 keepalive 注释，以保持流连接。若使用不带 SSE Accept 请求头的普通 GET，仍会返回 405。

curl -N -H "Accept: text/event-stream" \
  -H "Authorization: Bearer $MCP_HTTP_AUTH_TOKEN" \
  http://localhost:18080/mcp

若要在浏览器中检查检索结果，请打开：

http://localhost:18080/console

该控制台是一个轻量级界面，可用于：

• 运行文档、原始记忆和规范知识查询
• 对比文档检索的普通模式与调试模式
• 检查来源类型、可信度/新鲜度和分数明细

在共享模式下，页面本身是静态的，但通过控制台进行实时查询仍需使用与 /mcp 相同的 Bearer 令牌。

对于共享 HTTP 模式：

• 裸机环境的默认绑定地址为 MCP_HTTP_HOST=127.0.0.1；这是安全的本地默认值
• 对于共享/容器部署，请设置 MCP_HTTP_HOST=0.0.0.0
• 设置 MCP_HTTP_AUTH_TOKEN，以要求访问 /mcp 时提供 Authorization: Bearer <token>
• 绑定到非环回地址时，若未设置 MCP_HTTP_AUTH_TOKEN，启动将失败；除非显式设置 MCP_HTTP_INSECURE_ALLOW_UNAUTHENTICATED=true
• 保留 /health，供负载均衡器或容器健康检查使用
• 在反向代理或负载均衡器处终止 TLS
• 未启用身份验证和 TLS 时，不要将服务直接暴露到公共互联网
• 使用 deploy/nginx/agent-memory-mcp.conf 作为反向代理配置示例的起点
• 使用 docs/SHARED_SERVICE.md 了解完整的 local -> team laptop -> shared service 部署路径

CLI 命令

命令	描述
serve	启动 MCP 服务（stdio/http）——未指定命令时的默认命令
store	存储一条记忆（-content、-title、-type、-tags、-context、-importance、-stdin）
recall	按可信度排序召回记忆（位置参数查询、-type、-tags、-limit、-json）
list	列出记忆（-type、-context、-limit、-json）
delete	按 ID 删除一条记忆（位置参数）
search	使用可信度元数据进行 RAG 混合搜索（位置参数查询、-limit、-source-type、-debug、-json）
index	为 RAG 重新索引文档
close-session	分析会话结束摘要并生成会话结束报告（-summary、-stdin、-mode、-context、-service、-tags、-metadata、-started-at、-ended-at、-raw-only、-json）
review-session	面向审查的 close-session 别名，输入和报告内容相同
accept-session	保存原始摘要并自动应用低风险会话变更（-summary、-stdin、-mode、-context、-service、-tags、-metadata、-started-at、-ended-at、-raw-only、-json）
stats	显示记忆统计信息（-json）
config	生成可直接使用的 MCP 客户端配置片段
project-bank	显示结构化的项目知识库视图（canonical_overview、decisions、runbooks、incidents、caveats、migrations、review_queue）
resolve-review-item	处理待处理的审查队列条目（<id>、-resolution、-note、-owner、-json）
reembed	使用当前模型重新生成记忆嵌入（-json；-truncated 还会重新编码根据正文开头构建的向量）
export	将所有记忆导出为 JSON（-o 文件，默认输出到 stdout）
import	从 JSON 导入记忆（位置参数指定文件或从 stdin 读取）
index-triples	为缺少三元组的记忆补充（主语、关系、宾语）三元组（-resume、-force、-limit、-context、-dry-run、-progress-every、-json）。为 recall_multihop MCP 工具提供支持——参见 MCP_TRIPLE_EXTRACTOR_* 环境变量。
dead-ends-stale	列出早于 -age（默认 12 个月）的 dead_end 记忆以供重新评估（-limit、-json）
setup	在 ~/.claude/settings.json 中自动配置 Claude Code hooks（-command、-dry-run、-force）。参见 docs/HOOKS.md
hooks-config	输出 Claude Code hooks JSON，供手动粘贴到 settings.json（-command、-json）
context-inject	SessionStart hook 负载：近期记忆 + 待处理的原始摘要（-limit、-pending-limit、-context、-service）
auto-capture	SessionEnd hook：从 stdin 读取转录内容，运行提取 → 计划 → 应用流水线（-stdin、-summary、-mode、-context、-service、-tags、-dry-run、-json）
checkpoint	PreCompact hook：在压缩上下文前保存原始会话检查点（-stdin、-summary、-boundary、-context、-service、-tags）
sweep-archive	扫描 MCP_TASK_ARCHIVE_ROOTS，并对每个归档 slug 运行 end-task（T47）
end-task	整合与某个归档任务 slug 关联的工作记忆/流程记忆（T47）
mark-dead-end	记录已放弃的方法及其失败原因（T46）
sediment-cycle	应用记忆沉淀的层级转换：自动应用简单晋升，其余条目加入审查队列（T48）
recount-refs	根据现有的跨记忆边回填 referenced_by_count 元数据（幂等）

MCP 工具参考

记忆工具

工具	描述
store_memory	存储一条记忆，并设置内容、类型、标签和重要性
recall_memory	根据语义或文本查询召回记忆，可选用筛选条件和感知可信度的排序
update_memory	按 ID 更新现有记忆
delete_memory	按 ID 删除记忆
list_memories	列出所有记忆，可选按类型或上下文筛选
memory_stats	获取记忆统计信息（按类型计数）
merge_duplicates	将重复记忆合并到主条目中，并归档其余条目
mark_outdated	将记忆标记为过时或已被取代，使感知可信度的召回降低其排名
promote_to_canonical	将记忆提升为规范知识，并提高其可信度排名
conflicts_report	报告重复候选项、状态冲突以及多个规范条目
list_canonical_knowledge	列出从已确认记忆中提取的规范知识条目
recall_canonical_knowledge	仅召回规范知识，结果中不包含原始记忆
recall_multihop	对（subj、rel、obj）三元组语料执行多跳图遍历召回——返回按聚合路径得分排序的记忆，并附上到达每个结果的三元组链。适用于单跳搜索无法追踪的跨记忆推理查询。需要填入 MCP_TRIPLE_EXTRACTOR_*；可通过 index-triples CLI 回填。

RAG 工具

工具	描述
semantic_search	在已索引文档中进行混合搜索，可选使用 source_type、可信度元数据和 debug 解释模式
index_documents	为 RAG 搜索重新索引文档

文件工具

工具	描述
repo_list	列出允许路径下的文件和文件夹
repo_read	读取允许路径下的文件
repo_search	在允许路径下进行文本搜索

工程工作流工具

工具	描述
store_decision	存储工程决策及其理由、状态和影响
store_incident	存储事件及其影响、根本原因、解决方案、服务和严重程度
store_runbook	存储运行手册及其操作步骤、触发条件、验证和回滚说明
store_postmortem	存储事后复盘及其根本原因和行动项
close_session	将已结束的会话分析为原始摘要元数据、候选知识条目和可安全审核的整合操作
analyze_session	close_session 的兼容别名，具有相同的规划和报告行为
review_session_changes	为已结束的会话生成可解释的审核报告，但不强制写入
accept_session_changes	持久化原始摘要，并仅自动应用低风险整合操作
resolve_review_item	处理待审核队列项，使其从活动收件箱中移除，同时保留审计记录
search_runbooks	搜索运行手册记忆及已编入索引的运行手册文档
recall_similar_incidents	从记忆和已编入索引的事后复盘中检索类似事件
end_task	为已归档的任务标识整合记忆：将工作类／流程类条目标记为过时，并将重要性较高的条目转入审核队列
sweep_archive	对 MCP_TASK_ARCHIVE_ROOTS 执行拉取模式扫描，并对每个已归档的标识运行 end_task
store_dead_end	记录一次失败的尝试（以及失败原因和采用的替代方案），以便检索相关查询时将其作为陷阱警告呈现。对于没有决策背景的独立失败，请使用此工具。如果死胡同属于更大的架构决策，且你希望将两条记录关联成一条完整的推理链（T46），请使用 store_decision -avoided-dead-end-id <id>
promote_sediment	将记忆提升至更高的沉积层（表层 → 情景层 → 语义层 → 特质层）。参见 docs/SEDIMENTATION.md
demote_sediment	将记忆下调一个沉积层
sediment_cycle	运行沉积转换周期——自动应用简单的提升操作，并将非简单操作转入审核队列
summarize_project_context	总结近期决策、运行手册、事件及相关文档
project_bank_view	显示结构化的项目知识库视图，涵盖规范知识、决策、运行手册、事件、注意事项、迁移、审核队列或沉积提升候选项

知识维护工具

工具	描述
steward_run	运行知识维护周期：扫描重复项、冲突、过时条目和规范化提升候选项
steward_report	获取最新的知识维护报告，或通过运行 ID 获取指定报告
steward_policy	获取或更新知识维护策略，以控制检测阈值、自动应用规则和调度
steward_status	显示当前知识维护状态：策略模式、上次运行摘要、待审核数量和下次计划运行时间
drift_scan	将记忆条目与实时来源（仓库文件、文档）进行比较，以检测偏差、缺失的引用和未经验证的过时知识
verification_candidates	按紧急程度排序，列出需要验证的记忆
verify_entry	将记忆标记为已验证，并更新其验证元数据
steward_inbox	列出知识维护收件箱项——来自维护运行、偏差扫描和会话整合的待审核操作
steward_inbox_resolve	通过应用操作处理知识维护收件箱项：合并、标记为过时、提升、验证、抑制或延后

时间知识工具

工具	描述
recall_as_of	检索在特定时间点有效的知识，并按时间有效性进行筛选
knowledge_timeline	展示某个主题的知识演变时间线——各条记录如何创建、被取代并随时间更替

工具分组模式（提高令牌效率）

每个 MCP 客户端都会在 initialize 时加载所有工具的完整 JSON 架构—— 这发生在你发送第一条消息之前。约 40 个工具的架构数据本身就可能占用模型上下文窗口的数十 KB，而且每个会话都会如此。另外还有两项叠加的成本：工具数量超过约 20–40 个时，LLM 选择正确工具的表现会明显变差；频繁重新加载会话则需要再次支付全部成本。

设置 MCP_TOOL_GROUPING=true，将核心工具集折叠为少数几个 分组元工具，每个工具都通过必需的 action 判别参数进行分派：

// Grouped form                          // Equivalent legacy form
{ "name": "memory",                      { "name": "store_memory",
  "arguments": {                           "arguments": { "content": "…" } }
    "action": "store", "content": "…" } }

分组：repo · memory · memory_admin · engineering · search · session，以及独立的 index_documents 和 project_bank_view—— 默认可见工具数量从 41 个降至 8 个（架构数据约减少 42%）。

• 选择启用，不会造成回归。 默认值为 false；该标志只会改变 tools/list 的返回内容。
• 两种调用形式始终有效。 无论该标志为何值，tools/call 都接受分组形式 （memory + action=store）和旧名称（store_memory），因此现有脚本不会失效。
• 管理和 steward 工具仍保持独立。 它们很少在高频 Agent 运行中列出，而且 steward_inbox_resolve 已使用自己的 action 参数——分组功能有意不将它们分组。

权衡：每次分组调用都需要携带稍大的架构（包含该组所有操作的参数）。 对于高频 Agent 运行，当发现工具的成本占主导时，建议使用分组；对于交互式调试，按名称查看每个工具更清晰，建议关闭分组。政策参考：docs/concepts/lifecycle.md 介绍了相关的归档清理功能。

配置

所有配置均通过环境变量进行。完整列表请参阅 .env.example。

配置文件按以下顺序加载（每个文件只会填充尚未设置的值）：

1. --config /path/to/file（显式路径，跳过配置链；所有命令均可使用，不仅限于 serve）
2. 当前目录中的 .env
3. ~/.config/agent-memory-mcp/config.env（XDG）
4. $(brew --prefix)/etc/agent-memory-mcp/config.env（Homebrew）

在单机本地模式下，将 .env.example 复制为项目根目录中的 .env。对于 brew services，配置文件会自动创建在 $(brew --prefix)/etc/agent-memory-mcp/config.env。

热重载

以服务方式运行时（HTTP 模式），系统每 30 秒检查一次配置文件是否有更改。与 RAG 相关的设置（索引目录、嵌入密钥、启用/禁用状态）无需重启即可生效。HTTP 设置（端口、主机）则需要完全重启。

你也可以强制立即重新加载：

kill -HUP $(pgrep agent-memory-mcp)

关键变量

变量	默认值	描述
MCP_ROOT	当前目录	项目根路径
MCP_ALLOW_DIRS	""（仅 MCP_ROOT）	以逗号分隔的额外仓库相对路径，文件工具（repo_list、repo_read、repo_search）可以读取这些路径。路径必须位于 MCP_ROOT 下；加载配置时会拒绝绝对路径或 .. 遍历。在共享/HTTP 模式下至关重要 — 请将范围设窄
MCP_MAX_FILE_BYTES	2097152	repo_read 返回的最大文件大小（字节）；超过此大小的文件会被拒绝
MCP_MAX_SEARCH_RESULTS	200	repo_search 结果数量的硬上限
MCP_MAX_DEPTH	3	repo_list 的最大目录递归深度
MCP_STDIO_MODE	line	Stdio 分帧方式：line（以换行符分隔）或 lsp（Content-Length 标头）
MCP_TOOL_GROUPING	false	在 tools/list 中将核心工具集折叠为分组元工具，以缩减发现阶段的架构负载（约缩小 42%，工具数从 41 个降至 8 个）。无论如何，tools/call 都同时接受分组名称（memory+action）和旧名称。参见工具分组模式
MCP_MEMORY_ENABLED	true	启用记忆工具
MCP_MEMORY_PREVIEW_RUNES	0	覆盖 MCP 工具响应中记忆内容/摘要字段的各界面截断上限（按字符计）（recall_memory、list_memories、search_runbooks 等）。0 保留内置上限（150/220/300）；正数会在所有界面强制使用同一个上限；负数则禁用截断（返回完整文本）。
MCP_RAG_ENABLED	true	启用 RAG/搜索工具（Homebrew 服务预设会将此项设为 false，直到你设置 MCP_ROOT）
MCP_HTTP_MODE	stdio	传输方式：stdio 或 http
MCP_HTTP_HOST	127.0.0.1	HTTP 绑定主机；在共享/容器部署中设为 0.0.0.0
MCP_HTTP_PORT	18080	HTTP 端口（HTTP 模式下）
MCP_HTTP_AUTH_TOKEN	-	非回环/共享 HTTP 模式所需的 Bearer 令牌
MCP_HTTP_INSECURE_ALLOW_UNAUTHENTICATED	false	在无身份验证的非回环 HTTP 模式下启用明确的不安全覆盖选项
JINA_API_KEY	-	用于嵌入的 Jina AI API 密钥
OPENAI_API_KEY	-	OpenAI API 密钥（或兼容服务：Together、Mistral）
OPENAI_BASE_URL	https://api.openai.com/v1	OpenAI 兼容的基础 URL
OPENAI_EMBEDDING_MODEL	text-embedding-3-small	嵌入模型名称
OLLAMA_BASE_URL	http://localhost:11434	Ollama URL（本地备用）
LLAMACPP_BASE_URL	-	llama.cpp 的 OpenAI 兼容基础 URL（例如 http://127.0.0.1:8080/v1）；留空则禁用
LLAMACPP_EMBEDDING_MODEL	bge-m3	llama.cpp 嵌入模型标签（仅在设置了 LLAMACPP_BASE_URL 时使用）。该标签是派生模型 ID 的一部分，会存储在每条记录中，因此更改它会像更改模型一样使整个库失效 — 参见 docs/EMBEDDING_MIGRATION.md
MCP_EMBEDDING_MODE	auto	嵌入模式：auto 或 local-only
MCP_EMBEDDING_DIMENSION	1024	向量维度（更改后需要重新索引）
MCP_EMBEDDING_TIMEOUT	5s	每次请求的嵌入超时时间；本地后端较慢时请调高
MCP_EMBEDDING_MAX_RETRIES	1	嵌入遇到暂时性故障时的重试次数
MCP_INDEX_DIRS	docs	以逗号分隔的目录和单个文件，用于 RAG 索引。代码中的备用值为 docs；随附的 .env.example 预设会针对常见项目布局设为 docs,README.md,CHANGELOG.md
MCP_RAG_AUTO_INDEX	true	启动时索引文档。代码默认值为 true（适用于 HTTP/服务模式）；单机本地 .env.example 预设会关闭此项，以便你通过显式运行 agent-memory-mcp index 来控制索引
MCP_RAG_FILE_WATCHER	false	监视 MCP_INDEX_DIRS 中的更改并增量重新索引；适用于长期运行的共享/服务实例
MCP_INDEX_EXCLUDE_DIRS	内置默认值	从 RAG 索引中排除的额外目录名称或仓库相对路径
MCP_INDEX_EXCLUDE_GLOBS	-	匹配仓库相对路径的额外 glob 模式，例如 docs/internal/*.md
MCP_REDACT_SECRETS	true	索引文档前对常见的类似密钥内容进行脱敏
MCP_ARCHIVE_SWEEP_ENABLED	true	零运维整合：后台循环会自动将已归档任务的工作记忆标记为过时（或提升持久记忆），无需手动运行。自动发现 <MCP_ROOT>/tasks/archive；若不存在则不执行任何操作。参见零运维整合
MCP_ARCHIVE_SWEEP_INTERVAL	1h	后台归档扫描间隔。0 会禁用循环
MCP_SESSION_TRACKING_ENABLED	true	启用后台会话跟踪、自动原始摘要和低风险的会话关闭编排
MCP_SESSION_IDLE_TIMEOUT	10m	活跃后台会话自动关闭前的空闲超时时间
MCP_SESSION_CHECKPOINT_INTERVAL	30m	活跃会话期间定期生成原始检查点快照的间隔
MCP_SESSION_MIN_EVENTS	2	后台自动关闭运行前所需的最少 MCP 工具调用次数
MCP_DATA_PATH	data	数据存储的基础路径
MCP_RAG_INDEX_PATH	<MCP_DATA_PATH>/rag-index	覆盖 SQLite 向量索引位置
MCP_MEMORY_DB_PATH	<MCP_DATA_PATH>/memory-store/memories.db	覆盖 SQLite 记忆数据库路径
MCP_LOG_PATH	<MCP_DATA_PATH>/logs/mcp-diagnostics.log	覆盖诊断日志文件路径
MCP_STATS_ENABLED	false	追加每次调用的使用记录（jsonl），以便进行自我监测
MCP_STATS_PATH	<MCP_DATA_PATH>/logs/mcp-usage.jsonl	统计数据 jsonl 输出路径
MCP_STATS_SAMPLE_RATE	1.0	启用统计数据时要记录的调用比例（0.0–1.0）
MCP_STEWARD_ENABLED	自动	启用知识管理（在带有记忆功能的 HTTP 模式下自动启用）
MCP_STEWARD_MODE	manual	管理模式：off、manual、scheduled、event_driven
MCP_STEWARD_SCHEDULE_INTERVAL	24h	定期管理运行的间隔
MCP_STEWARD_DUPLICATE_THRESHOLD	0.85	重复项检测的相似度阈值
MCP_STEWARD_STALE_DAYS	30	记忆被视为过时前的天数
MCP_STEWARD_CANONICAL_MIN_CONFIDENCE	0.80	提升为规范知识候选项所需的最低置信度
MCP_CHECKPOINT_DEDUP_THRESHOLD	0.9	Jaccard 相似度阈值；同一上下文中，检查点超过此阈值时会被视为与上一个检查点重复
MCP_CHECKPOINT_DEDUP_WINDOW	10m	去重查询的时间窗口 — 仅比较早于此时间的新检查点
MCP_CHECKPOINT_DEDUP_MIN_CHARS	100	检查点可保存所需的最小内容长度（字符）；更短的内容会被视为空内容并丢弃
MCP_CHECKPOINT_DEDUP_DISABLED	false	应急选项：完全禁用检查点钩子的去重
MCP_TASK_ARCHIVE_ROOTS	-	sweep-archive / end-task 使用的、以冒号分隔的归档根目录（例如 /home/you/tasks/archive）。留空则禁用此功能
MCP_TASK_SLUG_PATTERN	-	可选的正则表达式，用于筛选归档子目录名称；正则表达式无效时会导致配置加载失败
MCP_RERANK_ENABLED	false	混合搜索后神经重排阶段的总开关。必须设为 true，且 MCP_RERANK_PROVIDER 必须为有效服务商（jina），重排器才会运行
MCP_RERANK_PROVIDER	disabled	重排器服务商：jina 或 disabled。设为 disabled（或留空）时，即使 MCP_RERANK_ENABLED=true，流水线也会退化为仅使用混合排序
JINA_RERANKER_MODEL	jina-reranker-v2-base-multilingual	Jina 重排器模型 ID
MCP_RERANK_TIMEOUT	5s	单次重排调用的硬超时时间；超时时会保留混合排序顺序，并在调试信号中添加 rerank_failed:timeout
MCP_RERANK_TOP_N	40	发送给重排器的混合搜索候选项数量上限；调用时最高限制为 100
MCP_RETRIEVAL_STRICT	false	将读取路径上的静默降级转为失败调用：嵌入服务商回退到下一个服务商、重排器超时，或多跳查询没有可遍历的图。适用于测量运行（make eval 会启用此项）以及诊断配置不完整的安装 — 生产环境中请保持关闭，因为较差的答案也胜过没有答案。无论此标志为何值，每个 semantic_search 响应都会包含一个 retrieval 块，指出实际提供结果的路径
MCP_SEDIMENT_ENABLED	false	启用感知层级的检索评分（始终呈现 character 层；除非处于上下文中，否则排除 surface 层）。始终运行架构迁移和回填；此开关仅控制检索权重。参见 docs/SEDIMENTATION.md
MCP_RECALL_CENTERED	true	使用中心化嵌入而非原始余弦相似度对记忆召回进行评分。基于实测效果优势（T76a）采用：在针对实时库的 345 个机器标注查询中，Hit@5 从 0.6232 提高到 0.7217，MRR 从 0.4922 提高到 0.5739。真实语料上的原始余弦相似度具有各向异性 — 无关向量对的中位数为 0.555，因此 minScore 会通过 100% 的候选项，完全无法筛选；中心化后，同一批样本中通过率为 34.1%。嵌入少于 100 个的库会忽略此项并使用原始余弦相似度，因为少量向量的均值会被需要抵消的向量主导。设为 false 可使用早期版本的评分方式
MCP_RECALL_HALFLIFE_DAYS	0	T68 召回评分的年龄指数衰减（以天为单位的半衰期；达到此年龄的卡片得分减半）。0 会禁用衰减 — 这是 T121 测量后采用的默认值：针对 345 个机器标注查询，关闭衰减时 Hit@5 为 0.7217，而之前默认的 30 天半衰期下仅为 0.1942；两者之间的设置结果呈单调变化（365 天为 0.6087，180 天为 0.4609，90 天为 0.2870），且没有任何年龄区间能从衰减中获益。事实的当前版本已通过语义上的替代关系和生命周期状态处理；日历乘数无法区分“写于较久之前”和“已不再属实”。常青条目（规范知识、character 层）永不衰减
MCP_RECALL_DECAY_TYPES	working	启用衰减时，哪些记忆类型会随时间衰减。类型维度对衰减率的影响最大：半衰期相同（30 天）时，所有类型都衰减的 Hit@5 为 0.1942，而仅 working 衰减时为 0.7043 — 旧行为会使模式和事实随时间衰减，而这正是知识库要积累的知识。留空表示所有类型都会衰减
MCP_RAG_KEEP_NOISE	false	T49 应急选项：在索引中保留噪声 Markdown 章节（目录/参考资料/更新日志等），而不是在分块时将其丢弃
MCP_RAG_MAX_CHUNKS_PER_DOC	1	单个文档最多可以占据多少个搜索结果名额。同一文件的相邻分块得分几乎相同，因此未设上限的前 5 条结果在 250 个问题中平均只包含 2.07 个不同文档 — 列表中过半内容都花在已出现文档的更多分块上。每个文档最多 1 个分块时，文档数为 5.00，按文档计算的 R@5 从 0.5104 提高到 0.8676，nDCG@5 从 0.6184 提高到 0.8927，同时首个命中指标保持稳定（Hit@5 从 0.9600 提高到 0.9640，MRR 从 0.9580 提高到 0.9590）；250 个查询中有 207 个得到改善，且没有任何查询变差（T127）。此上限表示优先顺序，而非配额 — 当文档数少于上限时，会补回跳过的分块，不会让结果列表变短。0 会恢复未设上限的排序；2 是折中值（3.11 个文档，R@5 为 0.7648）
MCP_TRIPLE_EXTRACTOR_ENABLED	false	T50 知识图谱层。启用后，每次写入记忆都会异步调用大模型，提取 3–7 个（主语、关系、宾语）三元组，为 recall_multihop 提供支持
MCP_TRIPLE_EXTRACTOR_BASE_URL	-	OpenAI 兼容的 /chat/completions 端点（DeepSeek、Together、Groq、Qwen 等）；留空时回退到 OPENAI_BASE_URL
MCP_TRIPLE_EXTRACTOR_API_KEY	-	提取器的 Bearer 令牌。仅当 MCP_TRIPLE_EXTRACTOR_BASE_URL 为空或等于 OPENAI_BASE_URL 时，才会回退到 OPENAI_API_KEY。如果将提取器指向第三方端点却未提供专用密钥，系统会显示明确提示并禁用提取 — OpenAI 密钥绝不会发送到未获授权使用该密钥的地址
MCP_TRIPLE_EXTRACTOR_MODEL	-	传递给提取器的模型 ID（例如 deepseek-chat、qwen2.5-72b-instruct）
MCP_TRIPLE_EXTRACTOR_TIMEOUT	30s	提取器 HTTP 调用的单次请求超时时间

数据路径

服务器会在 MCP_DATA_PATH 下创建以下目录：

• rag-index/ -- 用于文档搜索的 SQLite 向量索引
• memory-store/ -- 用于 Agent 记忆的 SQLite 数据库

建议的单人本地预设会将它们存储在 .agent-memory/ 下。

索引安全控制

RAG 索引会扫描支持的文档和工程文本文件，但你可以通过明确的控制进一步降低风险：

• 内置排除目录，例如 .git、.agent-memory、node_modules、logs 和 .terraform
• MCP_INDEX_EXCLUDE_DIRS，用于排除相对于仓库路径的目录，例如 docs/private,runbooks/internal
• MCP_INDEX_EXCLUDE_GLOBS，用于按 glob 模式排除文件，例如 docs/internal/*.md
• MCP_REDACT_SECRETS=true，用于在索引前对常见的疑似机密行和私钥块进行脱敏

如果你使用托管的嵌入提供商或共享 HTTP 模式，这一点尤其重要。

自动会话跟踪

MCP 服务使用默认会话跟踪策略运行时，会在后台维护一个轻量级会话缓冲区。

当前行为：

• 成功的 MCP 工具调用会自动归入当前活动会话
• 空闲超时或服务器关闭会在后台触发一次 close_session 运行
• 客户端可以通过 notifications/session_event 和 event=task_done|final_summary|checkpoint|reset 显式刷新或检查点保存当前活动会话
• 原始会话摘要会自动持久化
• 低风险更新可根据现有的 safe_auto_apply 策略自动应用
• 风险较高或含义不明确的更改会存为待审核收件箱条目，而不会悄悄改写已维护的知识
• 定期保存的原始检查点可在长会话期间为崩溃恢复提供线索

若要查看收件箱，请使用 project_bank_view view=review_queue 或 agent-memory-mcp project-bank -view review_queue。 若要在人工审核后关闭某个条目，请使用 resolve_review_item 或 agent-memory-mcp resolve-review-item <id>。

通知负载示例：

{
  "jsonrpc": "2.0",
  "method": "notifications/session_event",
  "params": {
    "event": "task_done",
    "summary": "Incident stabilized, workaround verified, follow-up is to replace the temporary fix.",
    "context": "payments",
    "service": "api",
    "mode": "incident",
    "tags": ["done", "verification"]
  }
}

若要调整或禁用此行为，请使用 MCP_SESSION_TRACKING_ENABLED、MCP_SESSION_IDLE_TIMEOUT、MCP_SESSION_CHECKPOINT_INTERVAL 和 MCP_SESSION_MIN_EVENTS。

索引完整性与恢复

文档索引现在会将分块更新和跟踪元数据视为一个逻辑状态。

• 每次运行都会在更改分块前将索引状态标记为 dirty
• 成功完成最终提交后，会将状态恢复为 ready，并一并更新 indexed_files、embedding_model 和 last_indexed
• 如果运行中断或最终的跟踪状态提交失败，下一次运行 index_documents / agent-memory-mcp index 时会检测到脏状态并强制重建索引

这让增量索引在发生崩溃、提供商中断或存储错误后更加可预测。

来源感知型数据摄取

索引器现在会对工程来源进行分类，并在检索时保留相关元数据。

支持的来源类型：

• docs，适用于 README.md 和常规 Markdown 文档
• adr 和 rfc，适用于架构决策文档和 RFC 风格文档
• changelog，适用于 CHANGELOG.md 和发布说明风格的文档
• runbook 和 postmortem，适用于运维知识
• ci_config，适用于 GitHub Actions、GitLab CI 和 Jenkins 流水线文件
• helm、terraform 和 k8s，适用于具备来源信息的基础设施文件

如果要将检索范围限定为特定类别的知识，请使用 source_type：

agent-memory-mcp search -source-type runbook "ingress rollback"
agent-memory-mcp search -source-type adr "cache invalidation decision"

MCP semantic_search 工具也接受 source_type 和 debug。

混合检索

搜索现在使用多种排名信号，而不再只依赖余弦相似度。

当前的排名信号：

• 基于当前启用的嵌入模型计算语义相似度
• 对分块标题、路径和内容进行类似关键词/BM25 的评分
• 使用 source_type 过滤，以缩小检索范围
• 对近期更新的运营上下文进行新近度加权
• 根据来源进行加权，让操作手册、变更日志、ADR 和其他来源类别在符合查询意图时排名更高

检索流程现在分为两个阶段：

• 从向量索引生成语义 top-K 候选项
• 从预先计算的内存关键词索引生成关键词 top-K 候选项

只有合并后的候选项集合会重新排名。随着索引语料库不断增长，这让共享服务的检索结果更可预测。

这意味着，操作手册或变更日志中的强关键词匹配，排名可以高于语义相似但与任务相关性较低的文档。

可信度感知检索

检索现在会为存储的记忆和已索引文档附带明确的可信度元数据。

每个结果都可以显示：

• source_type
• confidence
• last_verified_at
• owner
• freshness_score

实际效果如下：

• 文本匹配程度相近时，已接受的决策和已验证的操作手册会排在草稿或低可信度笔记之前
• ADR、操作手册、事后复盘和变更日志可以采用不同的可信度权重，即使尚未添加完整的规范层也是如此
• CLI search / recall 和 MCP semantic_search / recall_memory 现在会在人类可读的输出中显示可信度摘要

工程工作流工具还会为存储的条目添加 last_verified_at，让新近的运营知识更容易获得信任并提高排名。

可解释检索

需要了解文档为何被检索到时，可使用调试模式。

CLI：

agent-memory-mcp search -source-type runbook -debug "ingress rollback"

MCP：

• 调用 semantic_search 并设置 debug: true
• 普通的精简响应中，将 debug 留空或设为 false

调试模式会添加：

• 已应用的过滤条件，例如 source_type=runbook
• 响应使用的排名信号
• 候选项数量：已索引、已过滤排除、作为噪声丢弃、已返回
• 每个结果的可信度摘要：source、confidence、freshness、owner、verified
• 每个结果的分数明细：semantic、keyword_raw、keyword_normalized、recency_boost、source_boost、confidence_boost、final_score
• 每个结果应用的加权项，例如 keyword_match 或 source_type:runbook

检索控制台

如果你希望比原始 CLI 或 JSON-RPC 调用更快捷地进行检查，可在 HTTP 模式下使用内置控制台：

/console

适用场景：

• 并排比较普通检索和调试检索
• 在同一处检查文档搜索、原始记忆回忆和规范知识回忆
• 查看来源类型、可信度层级、置信度、新近度、负责人和验证时间
• 打开原始 JSON，查看 UI 正在呈现的同一结构化响应

该控制台刻意保持轻量，不会取代 MCP 工具或 CLI 工作流。

工程工作流工具

这些 MCP 工具将特定领域的工作流映射到现有的记忆和检索后端。

建议从以下工具开始：

• 使用 store_decision 记录架构或运维选择，例如禁用 HPA 或固定 ingress 版本
• 使用 store_incident 记录短期运维事实，以便在活跃调试期间回忆
• 使用 store_runbook 记录操作步骤、回滚说明和验证备注
• 使用 store_postmortem 记录持久的事件经验和行动项
• 需要包含理由、跟踪记录和适合审核的操作的明确会话结束计划时，使用 close_session
• 会话结束报告风险较低，且你想持久保存原始摘要并应用安全更新时，使用 accept_session_changes
• 背景收件箱中已有经过审核的条目，且你想清除该条目但保留审计跟踪时，使用 resolve_review_item
• 需要修复路径，且想同时获取存储在记忆中的操作手册和已索引的操作手册文档时，使用 search_runbooks
• 排查服务中断或回归问题时，使用 recall_similar_incidents
• 在会话开始时使用 summarize_project_context，获取精简的运维简报
• 想按视图而非原始回忆结果查看维护中的知识时，使用 project_bank_view，其中包括用于待处理后台决策的 review_queue

这些工作流工具还会添加验证元数据，使检索能够将新存储的运维知识视为比匿名原始笔记更新、更可信的内容。

记忆整合

记忆层现在支持手动整合工作流，无需删除历史笔记。

当同一项目的知识开始出现偏差时，请使用这些 MCP 工具：

• 使用 merge_duplicates 将重复笔记整合为一条主要记忆，并将其余笔记归档为合并的重复项
• 使用 mark_outdated 降低过时操作手册、已被取代的决策或过时事件笔记的优先级，同时保留这些内容
• 使用 promote_to_canonical 将当前最佳记忆标记为规范知识
• 使用 conflicts_report 显示 duplicate_candidates、status_conflict 和 multiple_canonical 分组

当前行为：

• 合并或归档的记忆仍可访问，但考虑可信度的回忆会降低其优先级
• 规范记忆会获得可信度加成和更高的最低重要性
• 过时或已被取代的记忆会自动归档并降低优先级
• 冲突报告为手动操作且安全：除非你明确选择删除，否则不会删除任何内容

零运维任务记忆整合

每个已关闭的任务都会留下工作记忆（Task started、各阶段 笔记、Session close、自动提取的审核条目）。如果放任不管，这些内容会 线性累积，并在回忆任务时不断浮现，即使任务已经完成也是如此。服务会自动整合这些内容——无需 cron、无需手动清理，也无需配置：

• 后台循环（默认启用，MCP_ARCHIVE_SWEEP_INTERVAL，默认值为 1h） 会扫描已归档的任务：持久条目（流程类或重要性 ≥ 0.70）会被 提升，其余条目会标记为 outdated。循环会在启动后不久执行首次扫描， 同时补处理循环启用前累积的归档内容。
• 零配置。 如果未设置 MCP_TASK_ARCHIVE_ROOTS，则会监视 <MCP_ROOT>/tasks/archive 约定路径；目录不存在时会静默跳过。
• 安全机制内置于设计中。 提升操作会经过来源门控：对话来源的 记忆会转入审核队列，绝不会自动规范化（请参阅记忆投毒防御）。
• end_task 和 sweep_archive 工具默认采用相同的整合 行为，因此显式执行 /end-task 会立即进行整合。

策略详情（状态推导、提升阈值、幂等性、 符号链接／目录遍历防护）：docs/concepts/lifecycle.md。 使用 MCP_ARCHIVE_SWEEP_ENABLED=false 关闭循环。

规范知识层

项目现在提供两个不同的层：

• raw memory：按存储时的原样记录的笔记、事件、决策和流程记忆
• canonical knowledge：从通过 promote_to_canonical 提升的记忆中投射出的已确认条目

这带来的变化：

• list_canonical_knowledge 可让你查看当前已确认的知识集，不受原始内容干扰
• recall_canonical_knowledge 只搜索规范条目
• 存在规范条目时，summarize_project_context 会优先展示规范知识，然后再展示原始记忆部分
• 信任摘要现在会显示 layer=raw、layer=canonical 或 layer=document

迁移说明：

• 现有记忆无需进行架构迁移
• 使用 promote_to_canonical 提升任何有价值的现有记忆
• 仅带有 decision 或 service:api 等标签的旧版工作流记忆仍会被规范层识别

知识维护

维护层提供自动和手动的知识维护功能。

steward_run 可通过一次调用执行完整的维护周期：

• 扫描重复候选项（实体／服务／上下文／主题相匹配的记忆）
• 检测冲突条目（多个规范条目、状态不一致）
• 标记过期条目（在配置的阈值内未验证）
• 建议规范提升候选项（重要性高、处于活动状态且类型为已识别的工程类型）
• 生成包含各项操作理由的结构化报告
• 设置 dry_run=false 时，执行安全操作，并将其余操作发送到维护收件箱

drift_scan 将记忆条目与实时仓库文件进行比较：

• 当引用的文件在记忆上次验证后被修改时，检测 source_changed
• 当引用的文件路径不再存在时，检测 source_missing
• 当条目超过过期阈值时，标记 stale_unverified

verification_candidates 会对需要验证的记忆进行排序：

• 从未验证的规范条目：紧急程度高
• 状态为 verification_failed 或 needs_update 的条目：紧急程度高
• 超过阈值的过期条目：紧急程度中

steward_inbox 是所有需要审核的操作的统一收件箱。使用 steward_inbox_resolve 处理项目，可选择合并、标记为过时、提升、验证、抑制或延后等操作。

在有记忆功能的 HTTP 模式下，维护功能会自动启用。通过 MCP_STEWARD_* 环境变量配置阈值和模式。运行时配置请参阅 steward_policy。

详细指南请参阅 维护指南。

时间性知识

记忆可以包含时间元数据，用于追踪知识的有效时间以及其演变过程：

• valid_from / valid_until — 此知识为真的时间范围
• superseded_by / replaces — 构成替代链的双向链接
• observed_at — 首次观察到知识的时间（可能与 created_at 不同）

recall_as_of 可检索在特定时间戳有效的知识。它适用于回答“我们 1 月份的数据库策略是什么？”或“这两个日期之间发生了哪些变化？”之类的问题。

knowledge_timeline 会按 valid_from 排序，显示与查询匹配条目的时间演变过程。

使用替代条目调用 mark_outdated 时，系统会自动为旧条目设置 valid_until，并为新条目设置 valid_from 和 replaces，从而构建可导航的链。

安全与运维

核心部署指南：

• 个人本地使用：保持 MCP_HTTP_MODE=stdio；如果需要确保数据不会发送出去，优先使用 MCP_EMBEDDING_MODE=local-only
• 共享 HTTP 模式：设置 MCP_HTTP_HOST=0.0.0.0，设置 MCP_HTTP_AUTH_TOKEN，在反向代理处启用 TLS，并严格限定 MCP_ALLOW_DIRS 的范围
• 索引：使用 MCP_INDEX_EXCLUDE_DIRS / MCP_INDEX_EXCLUDE_GLOBS 排除私有操作手册或凭证文档
• 备份：复制 .agent-memory/，或者使用 agent-memory-mcp export 仅备份记忆

参考文档：

• 维护指南
• 安全策略
• 威胁模型
• 备份与恢复
• 共享服务指南

架构

┌──────────────────────────────────────────────────┐
│              MCP Protocol Layer                   │
│            (stdio or HTTP/JSON-RPC)               │
├────────────┬──────────┬───────────┬───────────────┤
│Memory Tools│RAG Tools │File Tools │Steward Tools  │
├────────────┼──────────┼───────────┼───────────────┤
│MemoryStore │RAGEngine │ PathGuard │ Steward       │
│  (SQLite)  │          │           │  Service      │
│            │┌────────┐│           │  Scheduler    │
│ Embedder◄──┤│DocSvc  ││           │  Inbox        │
│            ││VecSvc  ││           │  Drift/Verify │
│            │└────────┘│           │  Policy       │
│            │ (SQLite)  │           │  (SQLite)     │
└────────────┴──────────┴───────────┴───────────────┘

嵌入提供方

服务在 auto 模式下支持三种嵌入提供方：

1. Jina AI（主要提供方）—— jina-embeddings-v3，原生维度为 1024，支持多语言
2. OpenAI（备用提供方）—— text-embedding-3-small 或任何兼容 OpenAI 的 API。原生维度为 1536；服务通过 OpenAI MRL 参数请求 dimensions=1024，以匹配其余技术栈
3. Ollama（本地备用提供方）—— bge-m3，原生维度为 1024，可在本地免费运行

三者都会归一化为相同的向量维度（MCP_EMBEDDING_DIMENSION，默认值为 1024），但它们不能互换：每个模型都有自己的嵌入空间。维度相同并不意味着可以安全地跨不同模型计算余弦相似度——因此，服务会为每条记忆标记其 embedding_model，并在召回时拒绝混用。

实际使用中，auto 模式的含义如下：

• 新记忆或新的 RAG 分块会使用当前可用的第一个提供方
• 现有记忆会保留其创建时使用的 embedding_model
• 语义召回会跳过 embedding_model 与当前查询模型不匹配的记忆，并对这些记录回退到文本匹配
• 如果索引使用了不同的模型，RAG 搜索会拒绝查询该索引，并提示你重新构建索引

这样可以避免提供方回退时返回看似可信、实则错误的语义匹配这一危险情况。

如果你有意更改提供方或模型，请将其视为迁移：

# rebuild document index for the new embedding model
agent-memory-mcp index

# re-embed stored memories for the new embedding model
agent-memory-mcp reembed

# inspect how many memories still belong to older models
agent-memory-mcp stats -json

你可以通过 MCP_EMBEDDING_DIMENSION 增大维度以提高准确性（例如，使用 text-embedding-3-large 时设为 3072），但任何维度或模型更改都需要重新索引和重新生成嵌入。

如果设置 MCP_EMBEDDING_MODE=local-only，则会完全跳过托管提供方，仅使用 Ollama 生成嵌入。

这样做对用户更好

• 你可以继续使用 auto 模式，而不必担心语义召回在无提示的情况下遭到破坏
• 你可以有意迁移到其他嵌入模型，而不会丢失已存储的知识
• 你可以使用 agent-memory-mcp stats 审核模型使用情况
• 你可以优先选择仅本地运行，无需担心回退到托管提供方

macOS 服务安装

Homebrew（推荐）

brew install ipiton/tap/agent-memory-mcp
brew services start agent-memory-mcp

详情及配置位置请参阅安装选项。

手动安装（旧版）

./scripts/install-macos.sh

此操作会构建二进制文件、创建 .env 文件，并安装一个在登录时自动启动的 launchd 服务。

手动控制：

# Status
launchctl list | grep com.agent-memory-mcp

# Start
launchctl load ~/Library/LaunchAgents/com.agent-memory-mcp.plist

# Stop
launchctl unload ~/Library/LaunchAgents/com.agent-memory-mcp.plist

故障排除 / 常见问题

“no embedding provider available” 或 “embedder not configured”

服务会在 auto 模式下依次尝试 Jina → OpenAI → Ollama，并在找到第一个可用提供方后停止。如果这些提供方都无法访问，嵌入（因此也包括语义召回）将被禁用。

• 至少设置 JINA_API_KEY、OPENAI_API_KEY 中的一项，或者运行已拉取 bge-m3 的 Ollama（ollama pull bge-m3）
• 在 MCP_EMBEDDING_MODE=local-only 模式下，只会使用 Ollama；请确认 OLLAMA_BASE_URL（默认值为 http://localhost:11434）能够响应

如果没有嵌入器，CLI 命令 agent-memory-mcp store … 仍会保存记忆，但会跳过向量——在运行 agent-memory-mcp reembed 之前，只能通过文本/关键词搜索检索该记录。

“嵌入模型不匹配 — 索引使用 X 构建，当前使用 Y”

RAG 索引和已存储的记忆都标记了生成它们的嵌入模型。如果你切换了提供方或模型，检索会拒绝混用不同的向量空间：

agent-memory-mcp index            # rebuild RAG index for the new model
agent-memory-mcp reembed          # re-embed stored memories
agent-memory-mcp stats -json      # check how many memories still belong to older models

“地址已被占用” — 端口 18080 已被占用

另一个 agent-memory-mcp（或无关服务）占用了该端口：

lsof -nP -iTCP:18080 -sTCP:LISTEN
brew services list | grep agent-memory-mcp

如果启动了两个实例，请停止其中一个（brew services stop agent-memory-mcp 或 kill <pid>），或更改 MCP_HTTP_PORT。

brew services start agent-memory-mcp 未能启动守护进程

最常见的原因：

• 之前将该 formula 作为 Cask 安装了 — 请先卸载：brew uninstall --cask agent-memory-mcp && brew install ipiton/tap/agent-memory-mcp
• 配置文件格式错误：cat $(brew --prefix)/etc/agent-memory-mcp/config.env
• 日志：tail -f $(brew --prefix)/var/log/agent-memory-mcp/mcp-diagnostics.log

Claude Code 中的钩子未触发

运行 agent-memory-mcp setup 后，重启 Claude Code（钩子会在进程启动时加载）。验证合并结果：

agent-memory-mcp setup --dry-run     # show what would be written
jq '.hooks' ~/.claude/settings.json  # inspect actual config

如果通过 brew upgrade 升级，请重新运行 agent-memory-mcp setup --force，使钩子命令指向新的二进制文件路径。参见 docs/HOOKS.md。

“不允许在没有身份验证的情况下绑定到 0.0.0.0”

在 HTTP 模式下，若未设置 MCP_HTTP_AUTH_TOKEN，服务会拒绝绑定到非回环地址。你可以：

• 设置 bearer token（MCP_HTTP_AUTH_TOKEN=$(openssl rand -hex 32)）——推荐
• 或仅在严格受控的环境中设置 MCP_HTTP_INSECURE_ALLOW_UNAUTHENTICATED=true

记忆数据库持续增长

• 运行 agent-memory-mcp project-bank canonical_overview 和 … review_queue，找出应提升或标记为过时的原始会话摘要
• 启用 stewardship：MCP_STEWARD_MODE=scheduled 会定期触发去重和过时项扫描
• 使用去重窗口清理会话检查点（MCP_CHECKPOINT_DEDUP_THRESHOLD、MCP_CHECKPOINT_DEDUP_WINDOW）
• 先备份：agent-memory-mcp export > backup.json（参见 docs/BACKUP_RESTORE.md）

recall_multihop 返回空结果

多跳图会遍历 (subj, rel, obj) 三元组语料。只有在以下任一情况下，语料才会有内容：

• 启用 MCP_TRIPLE_EXTRACTOR_ENABLED=true 并写入新记忆（每次存储时都会异步提取）
• 使用 agent-memory-mcp index-triples 为现有记忆补建索引（幂等，支持 --resume）

这两种方式都需要设置 MCP_TRIPLE_EXTRACTOR_*（参见关键变量）——提取会调用一个兼容 OpenAI 的 /chat/completions 端点。

HTTP/服务模式下“配置未重新加载”

更改会在约 30 秒内生效。若要立即重新加载：

kill -HUP $(pgrep agent-memory-mcp)

注意：HTTP 主机/端口需要完整重启（brew services restart agent-memory-mcp）。只有与 RAG 相关的设置支持热重载。

开发

# Build
make build

# Run
make run

# Test
make test

# Full quality gate (lint + tests + smoke)
make quality-gates

关于仓库结构、代码风格和 PR 规范，请参见 docs/CONTRIBUTING.md。

许可证

MIT