CogSession

🌳 CogSession

面向 AI 编码 Agent 的会话记忆。 上下文窗口满了，Agent 就会忘记一切。CogSession 会记住值得保留的内容，并在这些内容不再成立时提醒你。

问题

Session 1 (context fills) → Session 2 starts fresh → Session 3 starts fresh
    Everything lost.          Repeats the mistakes.   Starts blind again.

你再次解释代码库。Agent 又尝试了已经失败过的方法。你在第 1 次会话中商定的约束，到第 3 次会话时已经不复存在。

通常的答案是“写更好的笔记”，但这和所有文档一样行不通：写下时内容确实属实，但后来内容不再成立时，却没人会注意到。

CogSession 的作用

它做三件事，第三件是其他地方没有的。

1. 无需提醒即可记录。 会话会自动开启。决策、失败的尝试、假设和错误都会在发生时写入，每条记录都带有本地时间戳，以及发生时的仓库状态（main@a1b2c3d+2，其中 +2 表示有 2 个未提交文件）。

2. 让你无需加载内容即可搜索。 每个会话都会保留一个 session.md：只追加内容，每个事件对应一个区块，每条记录的行文都能自我说明。因此，一个 grep 就能回答问题，无需将文件载入上下文。

grep -A4 "dead_end"      .cogsessions/*/session.md   # what already failed
grep "2026-08-27 01:"    .cogsessions/*/session.md   # what happened that hour
grep "main@a1b2c3d"      .cogsessions/*/session.md   # what happened at that commit

3. 当你写下的内容不再成立时提醒你。 记录一条声明，并附上能够证明它的命令。它监视的文件发生变化时，就会重新运行验证：

[CogSession] 1 claim(s) no longer hold:
  ✗ the composite key includes the tenant column
    expected '1', got '0'
    asserted in: PR description, line 26
    proof: grep -c 'UNIQUE (a, b, c)' migrations/007_schema.sql

这不涉及模型判断。它会保存证明某件事的命令，并重新运行。没有消息，就意味着一切依然成立。

第三件事为何重要

三周的日常使用中，每一次代价高昂的失败都归结为一句话：某件事写下时是真的，后来却不再成立。 拉取请求描述解释的架构，代码中早已不存在。注释提到的约束已经变了。测试断言的结构已被实现移除。文档字符串与函数自身相矛盾。

Agent 无法从对话记录中发现这些问题。人类会在审查时发现，那是代价高昂的环节。保存下来的验证可以免费发现它们。

你要找的是这个吗？

你可能是因为以下某个原因来到这里：

• Claude Code 达到上下文限制，下一次会话对上一场会话一无所知
• 你的 Agent 重试了已经失败过的方法，因为没有记录它曾经失败
• 你在一次会话中商定的约束，三次会话后就不见了
• 你总是在每次会话开始时重新解释同一个代码库
• 一条注释、一份文档或一段 PR 描述描述的是代码过去的样子，结果是审查时发现了问题，而不是你提前发现

前四项是任何 Agent 记忆工具都能解决的问题。第五项才是 CogSession 真正要解决的问题，也是上文声明功能的由来。

与单纯写笔记有何不同

笔记会悄无声息地过时。这正是问题所在，再多的自律也无法解决，因为问题不是你忘了记下某件事，而是你写下的内容后来不再成立，却没有任何东西告诉你。

声明就是附有验证依据的笔记。当验证不再通过时，你就会收到提醒。

与 Agent 内置记忆有何不同

内置记忆会决定保留什么。CogSession 会记录发生过的事，并将内容保存在你自己的纯文本文件中，放在仓库目录下，可用你已有的工具搜索。无论今天用的是 Claude Code，还是明年换成其他工具，它的工作方式都一样，因为输出格式是 markdown 和 JSONL，而不是某个供应商的存储格式。

会话在磁盘上的样子

.cogsessions/
├── sess_001_discover/
│   ├── session.md          ← greppable timeline, every entry timestamped + git-stamped
│   ├── handoff.md          ← the brief the next session reads first
│   ├── claims.json         ← assertions with the commands that prove them
│   ├── dead_ends.md        ← what failed and why, so it is not retried
│   ├── assumptions.md      ← what was assumed but never verified
│   ├── tasks.json          ← done / remaining / blocked
│   ├── decisions.json      ← flagged when made under high context pressure
│   ├── environment.json    ← the commands that restore a working state
│   ├── architecture.mermaid← auto-generated dependency diagram
│   └── session_log.jsonl   ← append-only machine log
├── sess_002_auth/          (parent: sess_001)
└── sess_003_payments/      (parent: sess_001, sibling of sess_002)

会话构成一棵树，就像树枝一样，因为工作本来就是如此。session_tree 会显示这棵树；session_log 则是跨所有会话的 git log --oneline。

要求

• Python 3.11+
• 用于安装脚本的 uv
• 支持 MCP 的 Agent。基于 Claude Code 构建；也可用于 Codex（见下文）
• git 为可选项。没有它，日志会记录 no-git，仍然有用

安装

pip install cogsession        # or: uv tool install cogsession
cogsession-admin install

特意分成两条命令。第一条安装 MCP 服务；第二条配置钩子，让 CogSession 无需请求就能记录。软件包无法自行写入 ~/.claude/settings.json，因此如果不运行第二条命令，你就只能手动调用这 11 个工具，而且不会有任何自动记录。

cogsession-admin install 会先备份你的设置，再添加 6 个钩子，并保留已有的其他设置，不会覆盖你已经设置的状态栏。

git clone https://github.com/premanand8800/cogsession.git
cd cogsession
uv sync
uv run cogsession-admin install --repo .

安装程序会使用 uv 同步依赖，在 Claude Code 中注册 MCP 服务，并写入钩子，让它无需请求就能观察会话。它只会修改 ~/.claude/settings.json，不会触碰项目中的任何文件。

**它不会写入任何由 git 跟踪的文件。**交接内容会写入 CLAUDE.local.md。该文件会像 CLAUDE.md 一样自动加载，但永远不会提交。如果你的仓库恰好跟踪了这个文件名，CogSession 会拒绝写入，以免弄脏你的工作树，并告知交接文件在磁盘上的位置。请将 .cogsessions/ 添加到 .gitignore。

工具

共 11 个 MCP 工具，分为 4 组：

另有 6 个钩子（SessionStart、UserPromptSubmit、PreToolUse、PostToolUse、PreCompact、SessionEnd），负责自动记录，无需你主动请求。

它不会做什么

有必要直说，因为这是人们最先会想到的：

**CogSession 不会存储你的对话。**它只读取对话记录来衡量上下文窗口的占用情况。它保留的是结论——决策、走过的弯路、假设、声明——以及钩子记录的机械事件。这是有意为之：由每一句对话组成的记忆，没有人会回头重读。但这也意味着，会话记忆的质量取决于是否能在作出决定时及时记录下来。

用法

每次会话开始时：无需操作。 SessionStart 钩子会自动开启会话并加载上次的交接内容。依赖某人记得开启的跟踪机制，最终只会悄无声息地失效。

知道会话的主题后，为其命名——焦点行是唯一无法由工具推断的部分：

session_update(type="focus", content="auth module")

session_init 仍然可用，适用于你想主动开启的会话，或想关联到父会话的情况：

session_init(project_root="/your/project", focus="auth module")
session_load(project_root="/your/project")   # load a previous handoff by hand

整个会话期间：

session_update(type="decision", content="Use python-jose for JWT", reasoning="Handles RS256 edge cases")
session_update(type="dead_end", content="Using httpx for auth", why_failed="Breaks streaming in /login", use_instead="Use requests library")
session_update(type="assumption", content="users table has hashed_password column", risk_level="HIGH", how_to_verify="Run \\d users in psql")
session_update(type="task_complete", content="Build /register endpoint")
session_update(type="task_add", content="Build /refresh endpoint")
session_update(type="danger_zone", content="Don't touch middleware.py — custom CORS order line 45")
session_status(context_pct=67)

上下文用量达到 70-80% 时：

session_checkpoint(context_pct=78, one_liner="Built JWT auth. Refresh token next.")

查找信息，但不加载任何内容。 每个会话都会保留一个 session.md：只追加内容，每个事件对应一个区块，每个标题都包含自身的本地时间戳、事件类型，以及事件发生时的代码库状态（branch@commit+dirty）。因此，一条 grep 就能回答问题：

grep -n -A4 "dead_end"  .cogsessions/<session>/session.md   # what already failed
grep -n "2026-08-27 01:" .cogsessions/<session>/session.md   # what happened that hour
grep -n "main@a1b2c3d"   .cogsessions/<session>/session.md   # what happened at that commit

每条记录都能独立说明自身信息，因此直接使用 grep 就很有用：匹配结果会告诉你时间、类型，以及对应的代码状态，无需滚动查找上下文。工具调用会被刻意排除在外——每个会话数百条调用会淹没人们真正想查找的决策；它们保存在 session_log.jsonl 中。

像查看 git log 一样扫描历史记录：

session_log()                        # newest first, all sessions
session_log(type_filter="dead_end")  # what has already failed here

when                       what         repo                   session
2026-08-27 01:43:57 +0545  error        master@3d4d1fd+2       sess_20260827_...
2026-08-27 01:43:57 +0545  dead_end     master@3d4d1fd+1       sess_20260827_...

先扫描，再用 grep 在日志中查找相关记录。提交 ID 可关联回真实的 git log，因此可以将某项决策与产生该决策时的代码状态对应起来。

声明——适用于你记录的任何可能过时的内容：

claim_record(
  claim="the composite key includes the tenant column",
  verified_by="grep -c 'UNIQUE (a, b, c)' migrations/007_schema.sql",
  expect="1",
  watches=["migrations/007_schema.sql"],
  asserted_in="PR description, line 26",
)
claim_check()          # re-runs the proofs whose files moved

声明会保存证明它的命令，而不是关于如何检查的备注。文件发生变化时，下一个会话会获知哪些陈述已不再成立、它们记录在哪里，以及如何验证。没有提示就表示一切仍然成立。

之所以需要这个功能，是因为代价最高的失败并非决策错误，而是正确的决策悄然失效——例如，描述了代码中已不存在的架构的说明、提到了已变更约束的注释，或断言了实现已不再支持的结构的测试。

探索历史记录：

session_tree(project_root="/your/project")
session_search(project_root="/your/project", query="httpx", type_filter="dead_end")
session_diagram(project_root="/your/project")

工作原理：反转控制（观察者优先）

CogSession 通过 Agent 钩子和会话记录检查自动运行。你无需手动报告令牌百分比或调用工具。

1. 自动测量上下文：直接从 Claude Code 会话记录中读取上下文用量（input_tokens + cache_creation + cache_read + output_tokens）。
2. 自动注入：
   • SessionStart：主动注入 L0 清单和 L1 交接内容。
   • UserPromptSubmit：在 65%–74% 时提醒，在 75%–79% 时提出建议，并在 $\ge$80% 时强制要求创建检查点。显示与提示词相关的失败尝试和危险区域。
   • PreToolUse：阻止针对已记录危险区域的文件编辑。
3. 确定性提炼：跟踪文件编辑、git 操作、命令和测试失败，不依赖大模型猜测。

有何不同

连接

CogSession 是一个 MCP stdio 服务。如果在 Agent 运行的环境中安装了 cogsession，请使用 uv run cogsession 注册它。

Codex CLI：

codex mcp add cogsession -- uv run cogsession

如果直接从本地源代码检出目录运行 CogSession，请将 uv 指向该目录：

codex mcp add cogsession -- uv --directory /path/to/cogsession run cogsession

验证服务是否已注册：

codex mcp list
codex mcp get cogsession

添加 MCP 服务后，重启 Codex。Codex 会在新的 Codex 会话启动时加载 MCP 工具。

Claude Code：

claude mcp add cogsession -- uv run cogsession

对于本地源代码检出目录：

claude mcp add cogsession -- uv --directory /path/to/cogsession run cogsession

Cursor（.cursor/mcp.json）：

{"mcpServers": {"cogsession": {"command": "uv", "args": ["run", "cogsession"]}}}

对于本地源代码检出目录：

{
  "mcpServers": {
    "cogsession": {
      "command": "uv",
      "args": ["--directory", "/path/to/cogsession", "run", "cogsession"]
    }
  }
}

为某个项目禁用：

echo '{"enabled": false}' > .cogsession.json

在 Codex 中使用 CogSession

CogSession 是项目本地的。它会将会话数据存储在目标项目中：

/your/project/.cogsessions/

从你希望记住的项目中启动 Codex：

cd /your/project
codex

然后用自然语言让 Codex 使用 CogSession：

load the session and handoff from cogsession

也可以明确说明：

Use cogsession to load the latest handoff for this project.

如果这是该项目的第一个会话：

Use cogsession to initialize a session for this project with focus "initial setup".

工作过程中，记录重要信息：

Use cogsession to record a decision: "Use the existing service layer for account updates" because "It keeps validation and audit logging in one place".

Use cogsession to record a dead end: "Calling the external API directly from the route handler" because "It bypassed retries and request tracing" and use instead "Call the existing API client wrapper".

停止之前，为会话创建检查点：

Use cogsession to checkpoint this session with context 64% and summary "Implemented account update flow; remaining work is integration tests."

Codex 示例

developer@workstation:~/projects/example-app$ codex
╭───────────────────────────────────────────────╮
│ >_ OpenAI Codex (v0.130.0)                    │
│                                               │
│ model:     gpt-5.5   /model to change         │
│ directory: ~/projects/example-app             │
╰───────────────────────────────────────────────╯

› load the session and handoff from cogsession

• Called
  └ cogsession.session_load({
      "project_root": "/home/developer/projects/example-app",
      "load_level": "handoff"
    })

[CogSession] Handoff from sess_20260513_101500_account_updates_a1b2:

# Handoff: sess_20260513_101500_account_updates_a1b2

**Focus:** Account update flow
**Closed:** 64% context | 2026-05-13 23:33
**Parent:** root

## Summary
Account update flow is implemented, validation is wired through the existing
service layer, and lint/type checks are passing. Remaining work is integration
test coverage for error cases.

加载交接内容后，Codex 可以利用已保存的上下文继续工作：

I implemented the account update flow using the existing service layer:

- Added src/services/account_service.py for update orchestration.
- Updated src/api/account_routes.py to call the service layer.
- Added validation in src/schemas/account.py.
- Documented required environment variables in .env.example.

Verification:
pytest             passed
ruff check .       passed
mypy src           passed

Remaining work:
- Add integration tests for validation failures.
- Confirm production environment variables before release.

项目本地与全局

CogSession 默认不会使用统一的全局记忆存储。每个项目都有自己的 .cogsessions/ 目录。

对于此项目：

/home/developer/projects/example-app/.cogsessions/

对于另一个项目：

/home/developer/projects/admin-tool/.cogsessions/

这些是相互独立的历史记录。若要检查特定项目，请询问 Codex：

Use cogsession to show the session tree for /home/developer/projects/example-app.

Codex 运行 CogSession 工具之前，可能会显示审批提示：

Allow the cogsession MCP server to run tool "session_tree"?

1. Allow
2. Allow for this session
3. Always allow
4. Cancel

如果想减少提示，请选择 Allow for this session 或 Always allow。

实用的 Codex 提示词

Use cogsession to load the latest handoff for this project.

Use cogsession to initialize a new session for this project with focus "auth fixes".

Use cogsession to show the session tree for this project.

Use cogsession to search this project for "account update".

Use cogsession to checkpoint this session with context 70% and summary "Implemented auth changes and recorded build blocker."