CogSession

🌳 CogSession

AI コーディングエージェント向けのセッションメモリです。 コンテキストウィンドウがいっぱいになると、エージェントはすべてを忘れてしまいます。CogSession は、残しておく価値のある情報を記憶し、それが事実でなくなったときに知らせます。

問題

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

コードベースについてまた説明します。エージェントは、すでに失敗した方法を試します。セッション1で合意した制約は、セッション3では忘れ去られています。

よくある答えは「もっとよいメモを書く」ですが、あらゆるドキュメントが失敗するのと同じ理由でうまくいきません。書いたときには正しくても、正しくなくなったことに誰も気づかないのです。

CogSession の機能

3つあります。3つ目は、ほかにはない機能です。

1. 頼まれなくても記録します。 セッションは自動的に開始します。決定事項、行き詰まった方法、前提、エラーを発生時に記録し、それぞれにローカル時刻と発生時のリポジトリの状態を付与します（main@a1b2c3d+2 の場合、+2 は変更済みファイルを表します）。

2. 読み込まずに検索できるようにします。 各セッションには session.md があり、追記専用で、イベントごとに1つのブロックを作り、各エントリーの行だけで内容がわかるようになっています。そのため、ファイルをコンテキストに読み込まなくても、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

モデルによる判断は関与しません。何かを証明したコマンドを保存して再実行します。何も通知がなければ、すべての内容は引き続き有効です。

3つ目の機能が重要な理由

3週間、毎日使う中で発生した大きな失敗は、すべて1つの文に集約されます。書いたときには正しかったことが、正しくなくなっていた。 コードにはもう存在しないスキーマを説明するプルリクエストの説明文。変更された制約を示すコメント。実装から削除された形状を検証するテスト。自身の関数と矛盾するドックストリング。

エージェントはトランスクリプトからそれに気づけません。人間がレビューで気づくころには、対応にコストがかかります。保存された証明なら、コストをかけずに気づけます。

お探しのものはこれですか？

次のような理由でここにたどり着いたのではないでしょうか。

• Claude Code がコンテキスト制限に達し、次のセッションでは前回のことが何もわからない
• 失敗したことが記録されていないため、エージェントがすでに失敗した方法を再試行する
• あるセッションで合意した制約が、3セッション後には忘れ去られている
• 毎回セッションの開始時に、同じコードベースについて何度も説明している
• コメント、ドキュメント、PR の説明文が以前のコードの内容を記述しており、自分ではなくレビューで指摘される

最初の4つは、どのエージェントメモリツールにも求められる機能です。5つ目こそ、CogSession が解決するために作られた問題であり、前述のクレーム機能を備えている理由です。

メモを書くだけの場合との違い

メモは気づかれないまま古くなります。それが問題のすべてです。どれだけ注意を払っても解決しません。何かを書き忘れたことが問題なのではなく、書いた内容が事実でなくなったのに、誰も知らせてくれないことが問題だからです。

クレームは、証明を添えたメモです。証明が通らなくなると、通知されます。

エージェントに組み込まれたメモリとの違い

組み込みのメモリは、何を残すかを判断します。CogSession は起きたことを、自分が所有するプレーンなファイルに記録し、リポジトリのディレクトリに保存します。使い慣れたツールで grep できます。出力はベンダー独自のストアではなく Markdown と JSONL なので、今日のエージェントが Claude Code でも、来年は別のものでも、同じように機能します。

セッションがディスク上でどのように見えるか

.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 に対応したエージェント。Claude Code 向けに構築されていますが、Codex でも使用できます（下記参照）
• git は任意です。git がなくても、ジャーナルには no-git と記録され、有用な状態を保ちます

インストール

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

意図的に2つのコマンドに分けています。最初のコマンドで MCP サーバーをインストールし、2つ目でフックを設定します。フックによって、CogSession は指示されなくても記録できるようになります。パッケージから ~/.claude/settings.json に書き込むことはできないため、2つ目のコマンドを実行しない場合、手動で呼び出す必要がある11個のツールは使えますが、記録機能は使えません。

cogsession-admin install は、まず設定をバックアップし、既存の設定を残したまま6つのフックを追加します。また、すでに設定されているステータス行を上書きすることはありません。

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

インストーラーは uv で依存関係を同期し、MCP サーバーを Claude Code に登録し、指示されなくてもセッションを監視できるようにするフックを書き込みます。変更するのは ~/.claude/settings.json だけで、プロジェクト内のファイルには触れません。

Git が追跡するファイルには書き込みません。 引き継ぎ情報は CLAUDE.local.md に保存されます。このファイルは CLAUDE.md と同じように自動で読み込まれますが、コミットされることはありません。リポジトリでこのファイル名が追跡対象になっている場合、CogSession は作業ツリーを変更しないよう書き込みを拒否し、代わりに引き継ぎ情報の保存先をディスク上で知らせます。.gitignore に .cogsessions/ を追加してください。

ツール

4つのグループに分かれた11個の MCP ツールです。

さらに、記録を自動で行う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 があり、追記専用で、イベントごとに1つのブロックを記録します。各ヘッダーには、そのイベントのローカルタイムスタンプ、イベントの種類、発生時のリポジトリの状態（branch@commit+dirty）が含まれます。これにより、1回の 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 が役立ちます。一致した行から、いつ、どの種類のイベントが、どのコードの状態に対して起きたのかが分かり、前後をスクロールする必要はありません。ツール呼び出しは意図的に含めていません。1セッションに何百件もあると、誰かが実際に探している判断が埋もれてしまうためです。ツール呼び出しは 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 は、エージェントフックとトランスクリプトの検査を通じて自動的に動作します。トークンの割合を手動で報告したり、ツールを呼び出したりする必要はありません。

1. コンテキストの自動測定：Claude Code のセッショントランスクリプトから、コンテキストの使用量を直接読み取ります（input_tokens + cache_creation + cache_read + output_tokens）。
2. 自動挿入：
   • SessionStart：L0 マニフェストと L1 引き継ぎ情報を、プロンプトなしで挿入します。
   • UserPromptSubmit：65%～74%で注意を促し、75%～79%で推奨し、$\ge$80%でチェックポイントを必須にします。プロンプトに関連する行き止まりや危険領域も提示します。
   • PreToolUse：記録済みの危険領域を対象とするファイル編集をブロックします。
3. 決定論的な要約：LLM の推測に頼らず、ファイル編集、Git 操作、コマンド、テスト失敗を追跡します。

他との違い

接続

CogSession は MCP stdio サーバーです。エージェントの実行環境に 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.

CogSession ツールを実行する前に、Codex が承認を求めることがあります：

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."