kireo

@kireo/mcp-server

为任何兼容 MCP 的 AI 工具（Claude Code、Cursor、Windsurf、Cline、Zed、Continue 等）提供长期记忆。

什么是 Kireo memory MCP？

Kireo memory MCP 是一个模型上下文协议服务，可为 Claude Code、Cursor、Cline、 Windsurf 和其他任何 MCP 客户端提供长期记忆。保存一次决策，即可在之后的任何会话、 任何设备上找回。基于 LanceDB 的语义与关键词混合搜索、12 个 MCP 工具，以及 本地代码索引。免费测试版——只需一个 API 密钥。

如何安装 Kireo memory MCP？

Claude Code 只需一行命令，其他所有客户端只需一个 JSON 代码块。两者都需要从 https://app.kireo.app/app/api-keys 获取免费密钥（ki_sk_…）。

# Claude Code — add --scope user to get it in every project
claude mcp add kireo --scope user --env KIREO_API_KEY=ki_sk_xxx -- npx -y --package=@kireo/mcp-server kireo-mcp

其他所有客户端使用相同的服务条目；只需放入不同的文件：

{
  "mcpServers": {
    "kireo": {
      "command": "npx",
      "args": ["-y", "--package=@kireo/mcp-server", "kireo-mcp"],
      "env": { "KIREO_API_KEY": "ki_sk_xxx" }
    }
  }
}

客户端	代码块放置位置
Claude Code	项目根目录中的 .mcp.json（或使用上面的 claude mcp add 命令）
Cursor	~/.cursor/mcp.json，或单个代码库对应的 <workspace>/.cursor/mcp.json
Cline	MCP Servers → Configure MCP Servers（cline_mcp_settings.json）
Claude Desktop	claude_desktop_config.json（Settings → Developer → Edit Config）
Windsurf	~/.codeium/windsurf/mcp_config.json
Zed / Continue / 任何 MCP 宿主	该宿主用于存放 MCP 服务列表的位置——使用相同的三个字段

之后重启客户端。PATH 中必须有 Node.js ≥ 20，才能使用 npx。

它提供哪些工具？

通过 MCP stdio 提供 12 个工具：memory_save、memory_search、memory_recall、memory_get、 memory_update、memory_delete、memory_list_namespaces、memory_health、context_save、 context_load、project_info 和 context_archive。所有客户端看到的工具都相同。先调用 memory_health，确认密钥可用。

它会让我的提示词变得臃肿吗？

不会——记忆是按需拉取的，而不是主动推送的。系统提示词中不会注入任何内容。Agent 只有在判断 之前的上下文值得检索时才会调用 memory_search，并获取数量有限的排序结果（默认 10 条，硬性上限为 50 条），因此令牌消耗按查询计算，而不是按轮次计算。

它和 CLAUDE.md / .cursorrules 文件有什么区别？

规则文件是静态文本，每次会话都会完整重读，而且无法共享。Kireo memory MCP 按需查询，由 Agent 在工作过程中写入，支持语义搜索，并通过命名空间在项目、会话和设备之间共享。

它能索引我的代码库吗？

可以。npx -y -p @kireo/mcp-server kireo index ./ --repo my-app 会提取函数/类/方法， 并将其写入 code-<repo> 命名空间，供 memory_search 检索。索引采用增量方式——重新运行时 只会发送已更改的文件，服务会对相同符号去重，因此可以安全重试。

我的代码会被上传吗？

紧凑命令会上传你要求归档的对话摘要。context_save 会上传交接内容；memory_save 会上传提供的内容；kireo index 会上传提取的代码 符号。这些操作会将内容发送到你的 Kireo 账户。设置 KIREO_TELEMETRY=0，还可删除 X-Device-Id 请求头。

费用如何？

免费测试版。前往 https://app.kireo.app 注册并创建密钥即可——无需信用卡。

对话压缩（0.3.0）

Kireo 插件会在 Claude Code 中添加 /kireo:compact，并在 Codex 中添加 $kireo-compact： 它会总结当前可见的对话，写入 <directory-name>.md，并将文件上传到你的 Kireo 账户， 支持离线重试和带版本信息的文件元数据。 安装插件。

MCP 现在还提供 project_info、context_save、context_load 和 context_archive，以及下方的八个通用记忆工具。

快速入门

1. 在 https://app.kireo.app/app/api-keys 获取 API 密钥（ki_sk_…）。
2. 将此 MCP 服务添加到你的宿主。Claude Code — 运行：

claude mcp add kireo --scope user --env KIREO_API_KEY=ki_sk_xxx -- npx -y --package=@kireo/mcp-server kireo-mcp

该命令中的两个细节至关重要，均已于 2026-08-03 使用 claude 2.1.220 和 npm 11 验证：

• 使用 --package=@kireo/mcp-server kireo-mcp，而不是 @kireo/mcp-server。 此软件包提供两个二进制文件（kireo、kireo-mcp），两者都没有使用软件包名称，因此 npx -y @kireo/mcp-server 无法选择其中一个，并会报错 could not determine executable to run。
• 使用 --package=，而不是简写 -p。 在 -- 后的裸 -p 会被 claude mcp add 选项解析器吞掉，随后解析器会拒绝自己的标志：claude mcp add kireo --env … -- npx -y -p @kireo/mcp-server kireo-mcp 会报错 unknown option '--env'。长格式可以正常解析。

如果只想在当前项目中使用，请移除 --scope user。或者，在仓库根目录中提交项目作用域的 .mcp.json，并使用相同结构（在 JSON args 中可以使用简写 -p，它会直接传给 npx，不会经过 claude 解析器）：

// .mcp.json (project root)
{
  "mcpServers": {
    "kireo": {
      "command": "npx",
      "args": ["-y", "--package=@kireo/mcp-server", "kireo-mcp"],
      "env": { "KIREO_API_KEY": "ki_sk_xxx" }
    }
  }
}

3. 重启宿主。现在，AI 可以使用 12 个工具：

工具	用途
memory_save	保存长期记忆
memory_search	混合语义和关键词搜索
memory_recall	重现近期或重要记忆
memory_get	按 ID 获取
memory_update	更新字段
memory_delete	软删除或硬删除
memory_list_namespaces	列出命名空间
memory_health	检查服务状态

配置

配置来源按以下顺序合并：CLI 参数 > 环境变量 > ~/.kireo/config.json。

环境变量 / CLI	默认值	说明
KIREO_API_KEY / --api-key	必填	Bearer 令牌（ki_sk_…）。
KIREO_API_URL / --api-url	https://api.kireo.app	用于可自托管部署的 URL 覆盖值。
KIREO_REQUEST_TIMEOUT_MS / --timeout	60000	单次请求超时时间，单位为 ms，最大值为 300000（环境变量别名：KIREO_TIMEOUT_MS）。
KIREO_RETRY_MAX_ATTEMPTS	3	5xx/429 重试次数（别名：KIREO_RETRY_MAX）。
KIREO_RETRY_BASE_MS	200	指数退避的基准时间。
KIREO_TELEMETRY	1	设为 0 可禁用设备 ID 标头。
KIREO_LOG_LEVEL	info	debug / info / warn / error / silent。
KIREO_PROXY_URL	无	HTTP(S) 代理。
KIREO_ACCEPT_LANGUAGE	en	错误提示所用的语言区域。

所有平台（macOS、Linux、Windows）的日志都写入 ~/.kireo/logs/。

为本地代码编制索引

将仓库中的符号（函数 / 类 / 方法）编入 code-<repo> 命名空间，以便 AI 通过 memory_search 找到它们：

export KIREO_API_KEY=ki_sk_xxx
npx -y -p @kireo/mcp-server kireo index ./ --repo my-app

索引采用增量方式 — 后续运行时只会重新发送有更改的文件。

标志	默认值	说明
--repo <name>	目录基名	仓库名称 → code-<name> 命名空间。
--batch-size <n>	100	每批上传的符号数（1..100）。如果批次超时，请调低此值。
--timeout <ms>	60000	单次请求超时时间（最大值为 300000）。
--api-key / --api-url / --namespace / --log-level / --no-telemetry	—	与上方配置表相同；CLI 标志优先于环境变量。

运行 kireo --help 查看完整用法。--help 和 --version 不会访问网络或文件系统，也不需要 API 密钥。如果批量上传超时，可以安全地重新运行相同命令：服务端会对相同符号去重，因此重试不会产生重复项。

宿主配置

• Claude Code
• Cursor
• Windsurf

隐私

设置 KIREO_TELEMETRY=0 可移除 X-Device-Id 标头。我们绝不会读取你的代码；只有你明确传给 memory_save 的内容才会发送到 API。

故障排除

• AUTH_INVALID_KEY → 在 https://app.kireo.app/app/api-keys 轮换密钥。
• QUOTA_EXCEEDED → 升级套餐或等待下一个计费周期。
• 宿主中缺少工具 → 运行 npx @modelcontextprotocol/inspector node $(npm root -g)/@kireo/mcp-server/bin/kireo-mcp.cjs 以在本地验证。

许可证

MIT