cogmem

cogmem

面向 AI 编码 Agent 的自我改进、可验证记忆层。

面向 AI 编码 Agent 的自我改进、可验证记忆层。

cogmem 会在多个会话中学习你的工作方式，让 Agent 随着时间推移变得越来越准确、越来越自主：它不再重复犯错，持续维护每个项目的实时模型，并在恰当时机呈现正确的经验教训。每条记忆都经过加密签名且可检测篡改，因此，在遭到投毒或修改的记忆影响 Agent 之前，就能检测并拒绝它。

由 WritersLogic 开发——优先本地的记忆回溯；你的记忆和身份密钥都保留在自己的设备上（参见隐私）。

安装

从 PyPI 安装

pip install cogmem            # CLI + MCP server + verifiable-memory tools
pip install 'cogmem[recall]'  # add local semantic recall (fastembed)
cogmem init                   # wire the Claude Code hooks + build the index

运行 pip install cogmem 即可获得 cogmem CLI 和 MCP 服务（cogmem mcp，或按需运行 uvx cogmem mcp）——可验证记忆工具只需核心安装即可使用。添加 [recall] 附加组件以启用本地语义记忆回溯，然后运行 cogmem init，将完整学习闭环（SessionStart/UserPromptSubmit/Stop hooks 和索引）接入 Claude Code。cogmem init 可幂等运行；随时可以重新运行。

克隆安装程序（开箱即用，包含常驻守护进程）

克隆安装程序会完成 pip install + cogmem init 的所有工作，还会将常驻记忆回溯守护进程（launchd/systemd）设置为托管服务：

git clone https://github.com/writerslogic/cogmem.git
cd cogmem
./install.sh

也可以用一行命令完成：

curl -fsSL https://raw.githubusercontent.com/writerslogic/cogmem/main/install.sh | bash

install.sh 可幂等运行——随时重新运行即可原地升级。它会在 ~/.claude/cogmem 下安装代码，创建包含依赖项的独立虚拟环境，将 cogmem CLI 添加到 PATH，设置 Claude Code hooks，并启动常驻记忆回溯守护进程 （在 macOS 上作为 launchd 代理运行，在 Linux 上作为 systemd --user 服务运行）。需要 Python 3.12+；语义记忆回溯使用本地模型（fastembed，无需外部 API）。传入 --no-daemon 或 --no-hooks 可跳过相应步骤；设置 COGMEM_HOME 可安装到其他位置——CLI、引擎和 hooks 都会在运行时解析该路径，因此 非默认安装也能让记忆和身份信息完全独立保存在本地。

自定义安装

安装到其他目录

设置 COGMEM_HOME，将 cogmem 安装到默认路径 ~/.claude/cogmem 以外的位置：

COGMEM_HOME=/opt/cogmem ./install.sh

也可以使用单行命令：

curl -fsSL https://raw.githubusercontent.com/writerslogic/cogmem/main/install.sh | COGMEM_HOME=/opt/cogmem bash

安装程序会复制代码、创建虚拟环境，并将 CLI 符号链接到 ~/.local/bin/cogmem（或 COGMEM_BIN 指定的位置）。

CLI 路径

设置 COGMEM_BIN，以指定 cogmem CLI 符号链接的放置位置：

COGMEM_BIN=$HOME/.cargo/bin COGMEM_HOME=/opt/cogmem ./install.sh

如果 COGMEM_BIN 不在你的 PATH 中，安装程序会打印一条警告。你始终可以直接从 $COGMEM_HOME/cogmem 调用 cogmem。

数据目录和身份密钥的解析方式

运行时，CLI 和引擎会从环境中读取 COGMEM_HOME。如果未设置，则回退到 ~/.claude/cogmem。所有运行时数据都存放在 vault/ 子目录下：

首次运行时（通过 cogmem status 或任何引擎操作），系统会生成身份密钥，并将其保存在 $COGMEM_HOME/vault/identity/agent.key。对应的 did:key 根据 Ed25519 公钥派生。将 cogmem 移动或重新安装到新的 COGMEM_HOME 会创建新的身份，除非你迁移 vault/ 目录。

使用非默认安装位置的 MCP 客户端

标准 MCP 客户端配置不受 COGMEM_HOME 影响，因为 cogmem CLI 会在运行时解析该环境变量：

{
  "mcpServers": {
    "cogmem": { "command": "cogmem", "args": ["mcp"] }
  }
}

如果 CLI 不在你的 PATH 中，请使用完整路径：

{
  "mcpServers": {
    "cogmem": { "command": "/opt/cogmem/cogmem", "args": ["mcp"] }
  }
}

或者在 shell 包装脚本中添加 COGMEM_HOME 前缀：

{
  "mcpServers": {
    "cogmem": { "command": "env", "args": ["COGMEM_HOME=/opt/cogmem", "cogmem", "mcp"] }
  }
}

快速开始

cogmem status           # health check, metrics, agent DID
cogmem doctor           # end-to-end learning-loop health (daemon, API key, trust, backlog)
cogmem recall "..."     # surface relevant past lessons for a task
cogmem note "..."       # record a decision or finding mid-task
cogmem verify           # verify every memory's credential + the transparency log
cogmem receipt <id>     # inclusion proof that a memory is committed in the signed log
cogmem statement <id>   # COSE_Sign1 SCITT signed statement (verifiable by HMS too)
cogmem trust            # show the trusted agent identity (warns on a key mismatch)
cogmem trust --rotate   # re-anchor trust after an intentional key change
cogmem review list      # approve always-load rules
cogmem mcp              # run the MCP server (stdio) for any MCP client

MCP 集成

将 cogmem 作为 MCP 服务运行，并连接任意兼容 MCP 的客户端：

{
  "mcpServers": {
    "cogmem": { "command": "cogmem", "args": ["mcp"] }
  }
}

该服务公开了八个工具：recall、note、status、verify、receipt、tree_head、progress、review_pending，以及只读资源（实时用户模型和各项目状态）。

Claude Code 集成

install.sh 会自动将 cogmem 接入 Claude Code（以幂等方式合并到 ~/.claude/settings.json），无需手动调用。五个 hook 会在后台运行记忆循环：

所有 hook 都严格采用故障开放策略：任何错误、超时或未预热的守护进程都不会注入任何内容，也绝不会阻塞你的提示词。脚本位于 ~/.claude/cogmem/hooks/；重新运行 install.sh（或 ./install.sh --no-daemon）即可刷新接入配置。

cogmem verify              # check all memories and the log head
cogmem receipt <memory-id> # prove a memory is in the signed log
cogmem revoke <memory-id>  # revoke a memory (Bitstring Status List)
cogmem status-list         # emit the signed revocation status-list credential

# examples/c2pa-agent-credential/ is a real signed C2PA manifest
# whose agent identity validates in c2patool
./examples/c2pa-agent-credential/verify.sh

cogmem 基于已发布的标准构建，并准确说明了哪些部分是符合标准，哪些部分是*-风格*（结构和加密兼容，但未完全符合配置文件要求）。这些原语是真正的 Ed25519 签名，作用于真正的规范字节结构——这里没有任何模拟实现。

迈向全面符合 SCITT 标准。 有三个范围明确的步骤，无需引入新的密码学技术：（1）将 iss/sub/内容类型从声明负载移至 COSE 受保护头部，作为 CWT_Claims；（2）将包含证明作为 COSE 收据（draft-ietf-cose-merkle-tree-proofs）写入声明的非保护头部；（3）要求外部见证方担任与签发 Agent 分离的透明度服务角色。步骤 1–2 是重新编码；步骤 3 则涉及架构，因为单方日志只是兼容的格式，并不能实现有意义的透明度。

隐私

cogmem 采用本地优先设计。记忆、嵌入向量和身份密钥都保存在你的设备上，语义检索完全在本地进行——嵌入和重排序模型（fastembed）在设备上运行，因此查询记忆时数据不会离开设备。

学习流程并非在本地运行：获取、整合、反馈评估，以及项目/用户模型综合都会将相关会话记录发送至 Anthropic API（ANTHROPIC_API_KEY）。规则正是通过这种方式提取和评分的。如果你需要完全离线运行，可使用 --no-hooks（检索仍可正常工作），直到本地模型提取方案推出。简而言之：检索在本地进行；学习会调用 API。

Agent 溯源技术栈的一部分

cogmem 是 WritersLogic 可验证 Agent 溯源流水线的一个组件——涵盖 Agent 身份、记忆、推理和签名输出，并通过密码学实现端到端绑定。

这四个项目共享同一底层机制——COSE_Sign1 / SCITT 签名语句（Ed25519）和 W3C DID 身份，详见 UNIFIED-PROVENANCE.md。

安全

发现漏洞？请私下报告——参见 SECURITY.md。

许可证

Apache-2.0——参见 LICENSE。