Gemini CLI

前置条件

使用具备经审查的 settings.json MCP 配置和浏览器 OAuth 支持的 Gemini CLI 开发者工具。支持仅适用于 Gemini CLI 开发者工具，并不意味着集成了 Gemini 消费者网页聊天 (gemini.google.com) 或获得了官方扩展商店批准。

• 端点：https://xmemo.dev/mcp.
• 认证模式: OAuth.
• 配置文件: ~/.gemini/settings.json.
• 传输协议: Streamable HTTP (托管 endpoint 使用 httpUrl)。
• 扩展仓库: github:yonro/xmemo-gemini-cli (清单 0.1.0；已记录 GitHub 安装，未推断官方扩展商店批准)。

安装 / 设置

使用 Gemini CLI extensions 命令安装扩展，或者手动将 XMemo 配置块合并到 ~/.gemini/settings.json 的 mcpServers 下。

• 扩展命令: gemini extensions install https://github.com/yonro/xmemo-gemini-cli (锚定至 yonro/xmemo-gemini-cli @ 39e25b185b README)。
• 手动后备方案: 将 XMemo 块合并到 ~/.gemini/settings.json，保留 httpUrl 和身份头。

gemini extensions install https://github.com/yonro/xmemo-gemini-cli

设置凭据

无需 key——重启 Gemini CLI 后完成浏览器 OAuth。不要将 XMEMO_KEY 或 Authorization header 放入 settings.json。

No XMEMO_KEY
Complete browser OAuth in Gemini CLI

生成 / 确认 XMEMO_AGENT_INSTANCE_ID

每个本地 Gemini CLI install 生成一个非机密值，将它保存在 git 外，并在重启后复用，使 attribution 保持稳定。

export XMEMO_AGENT_INSTANCE_ID='<stable-local-instance-id>'

保留现有 config block

使用本页面渲染的现有 Gemini CLI XMemo configuration block。保留 httpUrl 和非机密 identity headers；不要添加 Authorization 或 XMEMO_KEY。

{
  "mcpServers": {
    "XMemo": {
      "httpUrl": "https://xmemo.dev/mcp",
      "headers": {
        "X-Memory-OS-Agent-ID": "gemini-cli",
        "X-Memory-OS-Agent-Instance-ID": "${XMEMO_AGENT_INSTANCE_ID}"
      }
    }
  }
}

重启客户端

保存 settings.json 后重启 Gemini CLI，使其加载 endpoint 和当前 instance identity，然后完成 OAuth consent。

使用真实 recall call 测试

第一次 MCP call 应为只读。这是实际的 recall invocation，不是 health-check placeholder，也不会写入 memory。

recall({ query: "connection check", limit: 1 })

预期响应（literal shape）

成功调用会返回下面的公开 ranked text shape；reference 和 content 是来自已授权 memory space 的真实值。

### XMemo Memory Results:
1. Reference: <opaque-memory-id> | Location: <location>
   > <memory content>

常见错误

Gemini CLI OAuth failures 使用 hosted OAuth error contract。

• invalid_grant — OAuth authorization code 无效、已过期或已被使用：重新连接 Gemini CLI 并再次授权。
• invalid_target — OAuth resource 与此 MCP server 不匹配：使用 https://xmemo.dev/mcp 并重新连接。
• 403 insufficient_scope — grant 不包含 memory:read：批准请求的 scope 并重新连接。