跳到主要内容
印格

Agent 记忆库 MCP

通过 Model Context Protocol（Streamable HTTP）在 Cursor、Claude Desktop 等 MCP 客户端中调用记忆库。REST 说明见记忆库 API 文档。

集成版本 v1.9.0

REST API
v1.6.0
MCP
v1.9.0
Agent Skill
v1.9.0
记忆引擎
v0.5.0

响应头: X-Engra-Memory-Mcp-Version, X-Engra-Memory-Engine-Version · 亦见于 MCP initialize 的 serverInfo.version

MCP 端点

推荐边缘端点 https://mcp.engra.ai/api/v1/memory/mcp（Cloudflare Worker，不经 Vercel）。兼容旧路径 https://engra.ai/api/v1/memory/mcp。默认无状态 JSON-only：RPC 走 POST（JSON 响应）；GET SSE 监听返回 405（可用 MEMORY_MCP_JSON_ONLY=false 恢复）。

https://mcp.engra.ai/api/v1/memory/mcp

兼容旧路径：https://engra.ai/api/v1/memory/mcp

鉴权

MCP 与 REST 共用同一套控制台 API Key（前缀 inf_）。必须使用租户级密钥；本地 .env 占位 Key 不能用于生产 MCP。

创建 API Key

  1. 打开控制台 → API 密钥（/dashboard/keys）
  2. 在「权限（多选）」中勾选所需 Scope（Gateway / Memory 两组）
  3. 快捷预设：MCP 只读、MCP 读写、Gateway 默认
  4. 只读 Agent：仅勾选 memory:read
  5. 需要 memory_save_atom：同时勾选 memory:write
  6. Memory MCP 通常无需绑定 Gateway；Gateway 场景可选绑定
  7. 生成后立即复制 inf_… 密钥，并按下方 Cursor 示例配置 mcp.json（含 Authorization、Accept、Content-Type）

Scope 对照

  • memory:read — memory_list_libraries / search / recall / wake-up / list_atoms
  • memory:write — memory_save_atom、memory_correct_atom、POST/PATCH /atoms

请求头

  • Authorization: Bearer inf_xxxxxxxx（推荐）
  • Accept: application/json, text/event-stream（必需；缺省常见 HTTP 406）
  • Content-Type: application/json
  • X-API-Key: inf_xxxxxxxx
  • 勿使用上游 Gemini/OpenAI Key — 那是 Gateway 上游配置，不是平台 API Key

传输

  • 协议：MCP Streamable HTTP（2025-11-25）
  • 模式：无状态 + enableJsonResponse（单次 POST 返回 JSON；默认不提供 GET SSE 长连接）
  • mcp.json 仍须带 Accept: application/json, text/event-stream（规范要求；缺省常见 HTTP 406）
  • 除 tools/call 外，initialize、tools/list 等标准 MCP 方法均支持

推荐工作流

  1. 先调用 memory_list_libraries 获取 memoryLibraryId（看 description / writableTargets）；需要时用 memory_suggest_write_library
  2. 检索类任务使用 memory_retrieve（组合层）或 memory_search / memory_recall / memory_wake_up；需要全可访问库时传 allAccessible: true
  3. 会话中出现可跨会话复用的知识时，主动调用 memory_save_atom（决策、约定、偏好、根因修复等；写入前先 search 去重）；跨团队目标须 sourceMemoryLibraryId + write grant；同一轮多条独立事实可分别 save，允许并行 tool call
  4. 检索命中过时内容时调用 memory_correct_atom（勿对同一事实重复 save）；多条过时命中可分别 correct，允许并行 tool call
  5. 写工具默认异步（202 + job.id），快速返回、后台落盘；勿指望立刻 search 命中刚写入内容
  6. 写入需 memory:write；MCP instructions 默认注入 SAVE MEMORY POLICY 引导 Agent 落盘
  7. 除 list_libraries / suggest_write_library 外，其余工具均需在参数中传入 memoryLibraryId 或 memoryLibraryLabel

工具一览

ToolScopeDescription
memory_list_librariesmemory:read列出当前团队可用的记忆库（含 Common Knowledge；`label` / `description` / `writableTargets` / `readableTargets`；readableTargets 为检索资格目录，非每次自动 merge）
memory_suggest_write_librarymemory:read按 description/label 关键词对主库与 writableTargets 排序，辅助选写入库
memory_searchmemory:readL3 深度语义搜索（默认可合并 Common Knowledge；跨库 extras 须 defaults 或显式 labels/ids，grant 目标可纳入资格）
memory_recallmemory:readL2 按需召回（跨库规则同 search；readableTargets 不会自动全量并入）
memory_retrievememory:read组合 L2+L3 一次返回；支持 allAccessible（与 Ids/Labels 互斥）
memory_wake_upmemory:readL0+L1 会话唤醒上下文（可追加 ## Shared common knowledge 块）
memory_save_atommemory:write异步写入 Atom（202 + job id；跨团队目标须 `sourceMemoryLibraryId` + write grant）
memory_correct_atommemory:write异步修正 Atom（202 + job id；跨团队规则同 save）
memory_list_atomsmemory:read分页列出 Atom

Cursor 配置示例

{
  "mcpServers": {
    "engra-memory": {
      "url": "https://mcp.engra.ai/api/v1/memory/mcp",
      "headers": {
        "Authorization": "Bearer inf_xxxxxxxx",
        "Accept": "application/json, text/event-stream",
        "Content-Type": "application/json"
      }
    }
  }
}

库绑定 MCP 端点（可选）

除团队级 /api/v1/memory/mcp 外，每个记忆库有独立端点 /api/v1/memory/libraries/{libraryId}/mcp。连接库绑定 URL 后，initialize 返回的 server instructions 与该库策略对齐；写/读工具中 memoryLibraryId 变为可选（默认绑定库）。Key 仍须有权访问该库（控制台 Key 可限制 memoryLibraryId 白名单）。

/api/v1/memory/libraries/{libraryId}/mcp

{
  "mcpServers": {
    "engra-memory": {
      "url": "https://mcp.engra.ai/api/v1/memory/libraries/YOUR_LIBRARY_ID/mcp",
      "headers": {
        "Authorization": "Bearer inf_xxxxxxxx",
        "Accept": "application/json, text/event-stream",
        "Content-Type": "application/json"
      }
    }
  }
}

MCP Agent 策略（server instructions）

MCP initialize 响应中的 server instructions 由平台组装，引导 Agent 何时检索、何时落盘、何时修正。可在控制台配置（软约束，无法 100% 强制模型执行）：

唤醒策略 mcp_wake_policy
off（默认自行检索）| session（新会话首条回复前 memory_wake_up）| every_turn（每条用户消息前 search/wake_up）。库级可覆盖团队默认。
落盘策略 mcp_save_policy
off | proactive（默认，会话中主动 memory_save_atom；同一轮多条事实可分别 save，允许并行 tool call）| session_end（额外要求会话结束前结构化摘要落盘）。
自动修正 autoCorrectEnabled
记忆库 Settings 开关；开启且库绑定 MCP 时，instructions 注入 CORRECT MEMORY POLICY，引导 Agent 对过时命中调用 memory_correct_atom 而非重复 save；多条过时命中可分别 correct，允许并行 tool call。
默认记忆库 / Key 覆盖
团队 Settings 或 API Key 的 mcp_default_library_id；库绑定端点则 implicit 固定为该库。
自定义指令 mcp_custom_instructions
团队级追加文案（≤2000 字符），append 到 server instructions。

配置入口：各记忆库 → Settings → MCP Agent 策略；团队 Memory Settings → MCP 默认库与补充指令；/dashboard/keys → Key 级默认记忆库。

HTTP 集成

若自建 MCP 客户端，请遵循 MCP Streamable HTTP 规范：POST 时 Accept 需包含 application/json 与 text/event-stream；本服务端点以 application/json 响应为主（JSON-only 默认不开放 GET SSE）。Cursor 等客户端请在 mcp.json 的 headers 中显式加入 Accept 与 Content-Type，否则可能返回 HTTP 406。完整示例见 skills/engra-memory/mcp.example.json。

Common Knowledge 共享常识库 · API 密钥配置（完整说明） · Agent Skills（20+ Agent 通用） · ← 记忆库 REST API · API 密钥管理 · 记忆库控制台