# Auto-Coder Gateway 接入

让 Claude Code、Codex、WorkBuddy 和其他工具使用 Sparse Agent Memory 的云端记忆。通过 CLI、MCP 或 Skill 查询历史经验、读取来源、保存已确认的事实；网页与工具使用同一个项目。此接入提供记忆操作，不代替工具自身运行代码。

## 设备授权登录（需配套更新后的 CLI）

无需复制凭据，也可以直接登录：

```sh
sparse-memory auth login
# 项目名可选，只用于预选；仍需在网页核对并允许。
sparse-memory auth login --project Default
```

在普通浏览器中打开终端给出的链接，用 Auto-Coder.Chat 登录，核对授权码与主机名，再选择已有项目并允许或拒绝。默认只读、30 天；可选择读写和 1–365 天。签发的凭据带客户端与主机名，出现在原来的「设置 → CLI / MCP」列表，可单独撤销。

Agent 场景可以分两步完成：

```sh
sparse-memory auth login --no-wait
sparse-memory auth finish --wait 600s
sparse-memory auth status
sparse-memory auth logout
```

设备请求十分钟过期。等待超时退出码为 7，Ctrl+C 为 130，都会保留待完成授权，可再执行 `auth finish`；拒绝或过期后清除。`auth status` 显示凭据来源、账号、项目、名称和到期时间，不显示秘密。到期通过新授权续用。下方原有 `login` 继续使用隐藏输入粘贴凭据。

两种登录共用原私密配置文件，最近一次成功登录替换该配置。设备秘密仅保存于 `<配置路径>.pending`，文件 0600、目录 0700，Windows 使用当前用户 ACL，终端不输出。stdio MCP 直接复用同一登录。全局 `--config 私密文件` / `--url HTTPS源站` 放在命令前，auth 子命令也可放在后面。凭据优先级：显式 `--config` > `SPARSE_MEMORY_TOKEN` > 已保存登录；`SPARSE_MEMORY_CONFIG` 选择默认文件。`SPARSE_MEMORY_URL` 可指定源站，但不会将已保存凭据发往另一个服务。没有明文 Token 参数。

`auth logout`（或 `logout`）撤销当前服务端凭据并删除本地登录和待完成授权；撤销无法确认时仍删除本地，明确提示到网页撤销，并返回非零退出码。确实只想删本机登录时使用 `auth logout --local-only`。父进程里的 `SPARSE_MEMORY_TOKEN` 需另行 unset。网页退出仍不会撤销独立工具凭据。

## 1. 选择项目并创建接入密钥

登录本站，在「我的项目」选择或创建项目，再打开 [设置 → CLI / MCP](/#/settings/clients)。为每个工具单独创建密钥，选择一个项目、只读或读写，以及有效天数。密钥只显示一次，请在终端登录提示中粘贴。密钥不授予管理员或邀请权限。

已有项目可直接使用。邀请制默认关闭，新用户验证 Chat 身份后即可自动注册；管理员开启邀请制后，首次加入才需要邀请码。需要模型检索时，先在「设置 → 查询服务」配置查询模型。

### 使用 Team 共享记忆

也可以在官网 **Team** 中创建团队或申请加入，再在密钥目标中选择 `Team · 名称`。只读密钥只能查询和读取已通过的记忆；读写密钥可以提交记忆，默认需要 Owner 在网页批准后才生效。返回 `state: pending`、`published: false` 表示正在等待审核。更新、删除及审批可在 Team 页面进行。

CLI 1.1.0 也支持提交更新与删除：`sparse-memory save --action update --entry-id entry_ID --expected-version 1 --text "新内容"`；删除使用 `--action delete`，保留 ID 和版本参数。这些命令仍遵循审核策略，不能代替 Owner 审批。

退出或被移出 Team 会撤销对应密钥并撤回待审稿；重新加入需要重新创建密钥。个人项目密钥不会自动获得 Team 权限。

## 2. 安装 CLI

当前 macOS Apple Silicon、Linux x64 / ARM64 与 Windows x64 为 **1.2.0**，支持上面的设备授权命令。Intel Mac 安装器继续提供 **1.1.0**，使用原有 `sparse-memory login` 粘贴凭据；今后的 macOS 新版本只支持 Apple Silicon。完整平台版本与下载摘要见[平台版本索引](/downloads/releases.json)；Intel Mac 旧版摘要保留在 [1.1.0 SHA256SUMS](/downloads/1.1.0/SHA256SUMS)。

macOS / Linux：

```sh
curl -fsS https://memory.sparse-agent.com/install.sh -o /tmp/sparse-memory-install.sh
sh /tmp/sparse-memory-install.sh --client all
```

Windows PowerShell：

```powershell
Invoke-WebRequest https://memory.sparse-agent.com/install.ps1 -OutFile "$env:TEMP\sparse-memory-install.ps1"
powershell -NoProfile -ExecutionPolicy Bypass -File "$env:TEMP\sparse-memory-install.ps1" -Client all
```

安装器校验 SHA-256，安装到用户目录，并保留已有二进制的 `.previous` 副本。支持 macOS Intel / Apple Silicon、Linux x64 / ARM64、Windows x64。打开新终端后运行：

```sh
sparse-memory --help
sparse-memory login
sparse-memory projects
sparse-memory query "这个项目有哪些部署约定？"
sparse-memory save --kind decision --title "部署约定" --text "已确认：发布前先在隔离环境验收。"
```

`login` 会隐藏密钥输入，并保存到系统用户配置目录的 `sparse-memory/config.json`；Unix 权限为 0600，Windows 限定当前用户 ACL。可以用 `SPARSE_MEMORY_CONFIG` 指定独立的配置文件路径。不要把密钥写入命令参数、项目文件或聊天。

离线或手工安装：从 [版本清单](/downloads/releases.json) 中选择系统对应包，对照 [SHA256SUMS](/downloads/1.2.0/SHA256SUMS) 校验后解压，将 `sparse-memory` 放入 PATH。

## 3. 为客户端配置 MCP

推荐使用本地 stdio MCP，复用 CLI 的私密登录，客户端配置里无需放密钥。

Claude Code：

```sh
claude mcp add --transport stdio sparse-memory -- sparse-memory mcp
```

Codex：

```sh
codex mcp add sparse-memory -- sparse-memory mcp
```

WorkBuddy 或其他支持 stdio 的客户端，在 MCP 设置中新建服务器，命令为 `sparse-memory`，参数为 `mcp`。若图形客户端找不到 PATH，填写安装后的可执行文件绝对路径。连接后确认能列出 `memory_projects`、`memory_query`、`memory_read`、`memory_save`、`memory_status` 五个工具。

支持远程 Streamable HTTP 的客户端也可连接 `https://memory.sparse-agent.com/mcp`，在客户端的私密认证设置中使用 Bearer 接入密钥。此入口使用独立密钥认证；需要 OAuth 自动发现的客户端请改用上述 stdio 方式。不要在 URL 中填写密钥。

## 4. 安装 Skill，教会工具使用记忆

```sh
sparse-memory integrate --client codex
sparse-memory integrate --client claude
sparse-memory integrate --client workbuddy
```

Codex 写入 `~/.agents/skills/sparse-memory/SKILL.md`，Claude Code 写入 `~/.claude/skills/sparse-memory/SKILL.md`。WorkBuddy 默认生成导入 ZIP 并显示路径；在当前版本的 Skills 页面导入、启用，再开始新任务。也可下载 [WorkBuddy Skill 包](/downloads/1.2.0/workbuddy-sparse-memory.zip)。只有已确认实际目录时，才使用 `--skills-dir DIR`。`--client all` 一次准备三个客户端；已有内容不同的 Skill 会保留并报告冲突。安装 Skill 不会自动修改客户端 MCP 配置。

Skill 引导工具先查询、再读来源、最后保存确认过的经验。普通对话和工具的私人历史不会自动上传。

## 5. 读取、保存与撤销

查询结果中的相对来源路径可以用 `sparse-memory read "relative/path"` 读取。结果过长时按 `next_offset` 使用 `read --offset N "relative/path"` 继续读取。查询如返回不完整或失败状态，工具应保留该状态，不声称已查遍全部记忆。

保存支持 `intent`、`change`、`howto`、`incident`、`decision`，每条最多 16000 UTF-8 字节；`save --file note.txt` 可保存文本文件。保存追加到所选项目，原有内容保留；相同分类和正文重复提交只保留一份。并发保存由服务端串行合并。超出容量时停止保存，可在网页导出、整理或另建项目。

`sparse-memory logout` 撤销当前凭据并清除本机登录。网页退出不会撤销工具的独立密钥。要让所有副本立即失效，请在「设置 → CLI / MCP」撤销对应密钥；过期、撤销或账号禁用后拒绝访问。只读密钥不能保存。密钥不能访问其他项目、账号、服务器文件或管理接口。

常见问题：找不到命令时打开新终端或使用绝对路径；401 时重新创建密钥并登录；403 时检查读写权限与账号状态；检索失败时检查查询模型设置。不要将密钥、密码、私人对话或未经确认的信息保存为共享记忆。

[云端记忆完整手册](/docs/memory)

连接提前中断时，CLI 会在原有总超时内有限重试；保存重试复用相同正文，服务端继续去重。