engrava

Engrava MCP

Engrava 的 Model Context Protocol 服务——通过 stdio 将 Agent 记忆数据库提供给任何 MCP 客户端（Claude Desktop、Claude Code、Cursor、Windsurf、VS Code，……）。

engrava-mcp 是一个独立、可运行的软件包，使用 Engrava 的公共 API。它是以记忆服务的形式运行 Engrava 的唯一方式；engrava 库本身不包含 MCP 代码。

uv tool install engrava-mcp   # recommended for daily use: a persistent install
engrava-mcp                   # spawned by your MCP client over stdio

uvx engrava-mcp 无需安装即可运行，也可以使用 pip install engrava-mcp。uvx 会将其环境保存在缓存中。缓存为空时，首次启动需要等待下载；对于下载量最大的 [local] 附加项，请参阅可选提供程序。

安装 engrava-mcp 会传递安装 engrava，因此你也能在同一环境中使用 import engrava 库。

兼容性

engrava-mcp 的版本与 Engrava 保持对应：engrava-mcp X.Y.z 面向 engrava X.Y，并要求 engrava >=X.Y,<X.(Y+1)。这是为了便于理解而采用的单向版本映射——并非步调一致：Engrava 按自己的节奏发布，而 engrava-mcp 的补丁版本独立发布。

engrava-mcp	兼容的 engrava
0.5.x	>=0.5,<0.6
0.6.x	>=0.6,<0.7
0.7.x	>=0.7,<0.8

依赖范围是准确信息来源。正常安装会自动解析兼容的 engrava；如果你自行固定 engrava 版本，请确保其处于该范围内。如果某个 engrava 版本比表格最后一行更新，但尚无对应的 engrava-mcp，则该组合尚未验证／支持，并非不可用；请先使用受支持的组合，直到对应的 engrava-mcp 发布。

我应该选择哪个软件包？

目标	安装
基于 Engrava Python API 构建（在自己的代码中使用记忆数据库）	pip install engrava
将 Engrava 作为 MCP 客户端的记忆服务运行	uvx engrava-mcp（或 pip install engrava-mcp）

没有第三种选择。

从 engrava[mcp] 迁移

该服务过去作为 engrava[mcp] 附加项和 engrava 内置的 engrava-mcp 命令随 Engrava 一起发布。从 Engrava 0.5.0 起，它改由此软件包提供。

之前	之后
pip install "engrava[mcp]"	pip install engrava-mcp（或 uvx engrava-mcp）
engrava-mcp（由 engrava 安装）	engrava-mcp（由此软件包安装）
客户端 mcp.json："command": "engrava-mcp"	客户端 mcp.json："command": "uvx", "args": ["engrava-mcp"]

• **注意：**在 Engrava 0.5 上执行 pip install "engrava[mcp]" 不会报错——pip 会忽略现在未知的附加项，并静默安装基础版 engrava，因此看起来像是安装了服务，实际却没有。请改为安装 engrava-mcp。
• 将所有固定的依赖字符串（engrava[mcp]>=...）改为依赖 engrava-mcp，而不只是重新安装。
• 你的存储配置无需更改——相同的 engrava.yaml／环境变量仍可照常使用（请参阅配置）。

配置

服务按以下优先级从环境变量解析存储：

变量	含义
ENGRAVA_MCP_CONFIG	engrava.yaml 的路径。使用完整配置构建，包括嵌入提供商、向量后端、日志和 TTL。在此处配置思维/边关系日志：设置 journal: enabled: true 即可启用。推荐。
ENGRAVA_DB_PATH	裸 SQLite 数据库文件的路径。请使用绝对路径：相对路径会根据服务的工作目录解析，而工作目录由客户端选择。这是零配置快速启动方式；未配置嵌入提供商，因此语义（向量）搜索不可用，但全文搜索、图谱和 MindQL 仍可正常工作。此方式构建的存储不带日志；如需日志，请使用 ENGRAVA_MCP_CONFIG。“零配置”指采用 Engrava 的默认搜索策略，因此此方式下也会遵循 search_memory 的 recency_now——新近度会根据你提供的时间戳计算，并使用 Engrava 的默认搜索权重。
ENGRAVA_MCP_READ_ONLY	设置为 1 / true / yes 时，不会注册写入工具，任何读取也不会自行写入——包括启用了访问跟踪的存储原本会缓冲并在关闭时刷新的延迟访问计数更新。因此，在此模式下，无论采用何种配置方式，每个工具的 readOnlyHint 注解都准确无误。只读模式约束的是工具，而不是数据库的打开方式。启动时，服务仍会以读写方式打开文件，在文件不存在时创建文件，并将其架构升级到该 Engrava 版本所使用的架构，因此服务也无法在此模式下使用无法写入的数据库文件。

**推荐：**为 MCP 服务提供与你的应用相同的 engrava.yaml。 只有在 yaml 中才能声明嵌入提供商（及其模型 / 密钥），而服务在搜索时需要用它为新查询生成嵌入，以进行语义搜索。如果只设置了 ENGRAVA_DB_PATH，服务会发出启动警告，提示语义搜索不可用，并指引你使用 ENGRAVA_MCP_CONFIG。

搜索时，服务会使用此 yaml 声明的提供商为查询生成嵌入。此服务执行的写入是否会生成嵌入，则由同一 yaml 中的 embeddings.auto_embed 决定；Engrava 默认关闭此选项。关闭时，通过 store_thought 创建的思维不会生成嵌入，因此 search_memory 的向量排名无法匹配它——但关键词排名仍然可以；update_thought 也会保留思维已有的嵌入，不会刷新。开启时，创建思维或更改其 essence 或 content 也会调用提供商。

存储钩子扩展需要配置路径

挂接到存储的 Engrava 扩展——即通过 engrava.yaml 的 hooks: 部分接入的扩展——仅会在通过 ENGRAVA_MCP_CONFIG 启动时挂载。ENGRAVA_DB_PATH 会打开一个裸数据库，不携带任何配置，因此使用 Engrava 的默认钩子运行，且无法挂载存储钩子扩展。这是有意为之：它是一个刻意精简的读写接口。

因此，安装此类扩展后通过 ENGRAVA_DB_PATH 启动，该扩展的存储钩子在此服务中仍不会挂载。如果已安装的软件包声明了任何扩展，服务会发出启动警告并指出其名称——它报告的是已声明的内容，而非各扩展的功能，因为服务本身不会加载它们——这样你就能区分“没有任何声明”和“已声明但未在此处接入”。如果读取已安装软件包的元数据时发生常规错误，服务会尝试记录该错误，然后继续启动。这两类情况都会通过 Python 的 logging 处理，因此是否显示以及显示位置取决于你的日志配置。若要接入存储钩子，请通过 ENGRAVA_MCP_CONFIG 启动，并将其指向包含 hooks: 部分的 engrava.yaml：

hooks:
  class: "my_package.hooks.MyHooks"

示例 engrava.yaml

database:
  path: /absolute/path/to/memory.db
embeddings:
  provider: openai-compatible # or: ollama, sentence-transformer, huggingface
  model: text-embedding-3-small
  api_key: ${OPENAI_API_KEY}

相对路径 database.path 会相对于服务进程的工作目录解析，而 MCP 客户端选择的是该目录，并非 yaml 所在的文件夹。

客户端设置

将 MCP 客户端指向通过 stdio 运行的服务。例如，典型的 mcp.json 条目：

{
  "mcpServers": {
    "engrava": {
      "command": "engrava-mcp",
      "env": {
        "ENGRAVA_MCP_CONFIG": "/absolute/path/to/engrava.yaml"
      }
    }
  }
}

engrava.yaml 中的 ${VAR} 值（例如 ${OPENAI_API_KEY}）会从服务自身的环境中读取，因此请将该变量添加到同一个 env 块中，除非确认客户端会传递自身的环境变量。

此处假设已运行 uv tool install engrava-mcp。如果客户端找不到该命令，请提供其绝对路径；uv tool dir --bin 会打印该目录。 若未安装，请使用 "command": "uvx", "args": ["engrava-mcp"]。

零配置快速入门请使用 ENGRAVA_DB_PATH，而不是 ENGRAVA_MCP_CONFIG；对于应用写入、Agent 读取的部署，请添加 "ENGRAVA_MCP_READ_ONLY": "1"。

不使用 uvx 运行

engrava-mcp                  # console script
python -m engrava_mcp        # module run
python -m engrava_mcp.server # module run (server module directly)

可选提供方

对于 MCP 部署，优先选择在服务进程外运行的嵌入提供方：Ollama（provider: ollama）或兼容 OpenAI 的端点（provider: openai-compatible）。默认安装已包含这两种支持，因此服务本身不会加载嵌入模型。

默认安装支持向量后端和基于 HTTP 的嵌入提供方（OpenAI / Ollama），配置 yaml 后即可使用。更重量级的提供方是选择性安装的额外组件，与 Engrava 自身的额外组件相对应：

uvx --from "engrava-mcp[local]"  engrava-mcp   # sentence-transformers (local model)
uvx --from "engrava-mcp[hf]"     engrava-mcp   # HuggingFace Inference API
uvx --from "engrava-mcp[openai]" engrava-mcp   # OpenAI-compatible embeddings deps
uvx --from "engrava-mcp[ollama]" engrava-mcp   # Ollama embeddings deps

[local] 会在服务进程内运行模型并安装 PyTorch，可能会增加数 GB 的体积。首次启动时，如果 uvx 缓存为空，需要等待下载；之后的启动会复用缓存。运行 uv tool install "engrava-mcp[local]" 会在安装时一次性完成下载。首次加载尚未存在于本地模型缓存中的模型时，会下载该模型。

功能概览

• 工具（13 个）： get_thought、search_memory、search_keywords、list_memory、query_memory、memory_stats、get_edges、list_edges（读取）；store_thought、update_thought、link_thoughts、delete_thought、delete_edge（写入，由 ENGRAVA_MCP_READ_ONLY 控制）。
• 资源（3 个）： engrava://thought/{thought_id}、engrava://stats、engrava://recent。
• 提示词（3 个）： summarize_recent_memory、find_related、reflect_on_topic。

query_memory 仅接受 MindQL FIND 查询；原始 SQL 和所有其他命令都会被拒绝。最多返回 5000 行。limit 参数会替换查询自身的 LIMIT；若未指定，则会拒绝 1–5000 以外的 LIMIT。

get_edges 按方向（IN / OUT / BOTH）遍历某个 thought 的边；指定 limit 时，最多返回指定数量的边，并优先返回权重最高的边；未指定时则返回所有边。list_edges 可按类型、来源或元数据浏览边。

link_thoughts 接受可选的边 metadata（JSON 字段，可供 list_edges 筛选）。search_memory 接受可选的 recency_now（ISO-8601 时间戳），用于指定衡量时效性的时刻（事务时间）；只有传入该参数时，时效性才会参与排名。

开发

pip install -e ".[dev]"
ruff check src/ tests/
ruff format --check src/ tests/
mypy --strict src/
pytest --cov --cov-fail-under=90

许可证

MIT