Assertion Memory

Assertion——为代码库打造的第二大脑

为 Claude Code、OpenAI Codex 和 Cursor 提供记忆，记住你决策背后的 原因 和整个项目的策略，并保持记忆最新：如果你推翻了之前的决定，就会用新决定取代旧决定，而不是再次调出旧决定。它会在你工作时自动回忆相关上下文，并将其存入共享的、限定项目范围的树中。读取操作通过托管的 MCP 端点进行（无需本地服务）；轻量级钩子负责捕获和注入上下文。同一代码库服务于全部三个 Agent（逻辑只需维护一份）。由 Assertion AI 提供。

记忆保存的是决策及其原因，而非对话记录或源代码。 记忆存储的内容 →

安装后，只需在浏览器中登录一次。无需复制密钥。需要系统级 python3 （用于标准库钩子）；无需其他依赖。

每种工具的分步指南和故障排除说明：assertion-ai.com/install。

安装 — Claude Code

分步指南：assertion-ai.com/install/claude-code。

已经安装？ 保留你现有的副本。如果你从此仓库安装（assertion@assertion-ai），请勿再从 Claude Code 社区目录安装（assertion@claude-community）。安装两个副本意味着会有两组钩子，因此每轮对话都会被捕获两次。/assertion:upgrade 会更新你安装的副本。

# 1) in Claude Code:
/plugin marketplace add Assertion-AI/assertion
/plugin install assertion@assertion-ai
/reload-plugins

/reload-plugins 会在当前会话中启用插件，无需重启。也可以在启动 Claude Code 前通过终端安装，这样就无需执行此命令： claude plugin marketplace add Assertion-AI/assertion && claude plugin install assertion@assertion-ai

2) 登录：

/assertion:login

浏览器会打开 Assertion Studio；点击 Connect（如果你是新用户，请先在该页面注册）。 记忆会在同一会话中启用：记忆工具和捕获功能都会识别登录状态，无需重启，也无需复制密钥。然后试试 recall <topic>。登录前，每个会话启动时都会显示一行通知，说明记忆功能已关闭。

在没有浏览器的设备上（SSH、服务器），运行 /assertion:login code 会显示一个短代码，你可以在其他设备上确认。运行 /assertion:logout 会让此计算机退出登录并关闭记忆功能。

**要求：**系统级 python3（用于两个标准库钩子）。无需其他依赖—— 记忆工具通过 HTTP 连接。

改用密钥（CI 或共享计算机）：仍可使用 ASSERTION_API_KEY，且优先级高于登录状态。请将其放入 ~/.claude/settings.json，格式为 {"env": {"ASSERTION_API_KEY": "<key>"}}，不要使用 shell export，这样无论你以何种方式启动 Claude Code，插件都能获取该密钥。

**升级：**运行 /assertion:upgrade，然后运行 /reload-plugins。无需重启。

空间：/assertion:space 会列出你的记忆空间，并显示当前会话使用的空间； /assertion:space <name> 仅切换当前会话（运行 /assertion:space personal 可切回个人空间）。

安装 — OpenAI Codex

分步指南：assertion-ai.com/install/codex。

# 1) install the plugin
codex plugin marketplace add Assertion-AI/assertion
codex plugin add assertion@assertion-ai

# 2) sign in in your browser (no key to copy)
python3 "$(ls -d ~/.codex/plugins/cache/*/assertion/*/scripts | sort -V | tail -1)/assertion.py" login --client codex

或者，打开 Codex 后，让它“登录 Assertion”（插件的 assertion-login 技能会执行相同的登录流程；“退出 Assertion”会运行 assertion-logout）。无论采用哪种方式，密钥都会保存供钩子使用，并写入 ~/.codex/config.toml，供记忆工具使用。

3. 以交互模式使用 Codex（在终端中运行 codex，或使用 VS Code 的 Codex 面板——不要 使用 codex exec）。首次运行时，按提示将三个钩子的 Trust 开关打开（只需一次）。

随后，捕获和注入功能便会在 CLI 和 VS Code 中使用同一共享树。Codex 完整详情（recall/expand 配置、开发覆盖）：plugin/codex/README.md。

安装 — Cursor

分步指南：assertion-ai.com/install/cursor。

Cursor 没有插件市场，因此通过一次性脚本安装，由脚本为你配置 hooks.json + mcp.json：

git clone https://github.com/Assertion-AI/assertion
cd assertion/plugin/cursor && python3 install_cursor.py   # signs you in in the browser

然后彻底退出并重新打开 Cursor。安装程序会合并到现有的 Cursor 配置中 （不会改动你的其他钩子或 MCP 服务），会备份所做的更改，并默认使用生产环境和共享的 default 工作区。在 Cursor 中，/assertion-login 会重新登录， /assertion-space 会列出或切换记忆空间，/upgrade 会更新克隆仓库。可用选项 （--key、--workspace、--server、--uninstall）和手动备用方案： plugin/cursor/README.md。

包含内容

• MCP 工具 — 在 Agent 内，通过 https://memory.assertion-ai.com 查询和整理你的记忆：
  • recall — 查找与你当前工作相关的过往工作
  • expand — 展开某个要点，查看其下的详细内容
  • evidence — 查看支持某项主张的详细信息
  • conflicts — 显示记录中自相矛盾之处
  • resolve — 解决冲突并保持记忆内容一致
  • superseded — 查看随着决策变化而被取代的内容
  • unsupersede — 恢复已被取代的内容
• Stop 钩子 — 将每个结束的回合记录到树中。
• SessionStart 钩子 — 将项目的工作集注入上下文。

两个钩子都会放行：如果无法连接后端，不会阻止你的会话。

可选：在 Claude Code 状态栏中显示你的记忆空间

在终端底部永久显示 📁 <space> 指示器，即时、本地且准确反映每个会话。在 ~/.claude/settings.json 中：

"statusLine": {
  "type": "command",
  "command": "python3 ~/.claude/plugins/cache/assertion-ai/assertion/scripts/statusline_space.py"
}

（如果你已经有状态栏命令，请将此命令接在后面。）

许可证

本仓库中的插件依据 Apache License 2.0 授权。详见 NOTICE。

该许可证仅适用于此客户端代码。它所连接的 Assertion 托管服务受服务条款约束，你的数据则受隐私声明约束。“Assertion” 是 Assertion AI, Inc. 的商标。