CogSession README
The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the CogSession listing page.
🌳 CogSession
Session memory for AI coding agents. Your agent forgets everything when the context window fills. CogSession remembers the parts worth keeping, and tells you when they stop being true.
The problem
You explain the codebase again. The agent tries the approach that already failed. The constraint you agreed on in session 1 is gone by session 3.
The usual answer is "write better notes", which fails for the same reason all documentation fails: it is true when written and nobody notices when it stops being true.
What CogSession does
Three things, and the third is the one that does not exist elsewhere.
1. It records without being asked. A session opens on its own. Decisions, dead ends,
assumptions and errors are written as they happen, each stamped with the local time and the
repo state it happened at (main@a1b2c3d+2, where +2 is dirty files).
2. It makes that searchable without loading it. Every session keeps a session.md:
append-only, one block per event, every entry line self-describing. So one grep answers a
question without pulling a file into context.
3. It tells you when what you wrote stops being true. Record a claim with the command that proves it. When the files it watches change, the proof is re-run:
No model judgement involved. It stores the command that proved something and re-runs it. Silence means everything still holds.
Why the third one matters
Every expensive failure in three weeks of daily use reduced to one sentence: something was true when it was written and stopped being true. A pull request description explaining a schema the code no longer had. A comment naming a constraint that moved. A test asserting a shape the implementation had dropped. A docstring contradicting its own function.
An agent cannot notice that from a transcript. A human notices it in review, which is the expensive place. A stored proof notices it for free.
Is this the thing you are looking for?
You are probably here because of one of these:
- Claude Code hit its context limit and the next session knows nothing about the last one
- Your agent retried an approach that already failed, because nothing recorded that it failed
- A constraint you agreed on in one session was gone three sessions later
- You keep re-explaining the same codebase at the start of every session
- A comment, a doc or a PR description described the code as it used to be, and review caught it rather than you
The first four are what any agent-memory tool is for. The fifth is the one CogSession was actually built to solve, and it is the reason for the claims feature above.
How this differs from just writing notes
Notes go stale silently. That is the entire problem, and no amount of discipline fixes it, because the failure is not that you forgot to write something down — it is that what you wrote stopped being true and nothing told you.
A claim is a note with a proof attached. When the proof stops passing, you hear about it.
How this differs from your agent's built-in memory
Built-in memory decides what to keep. This records what happened, in a plain file you own, in your repo's directory, greppable with tools you already have. It works the same whether the agent is Claude Code today or something else next year, because the output is markdown and JSONL rather than a vendor's store.
What a session looks like on disk
Sessions form a tree, like branches, because work does. session_tree shows it; session_log
is a git log --oneline across all of them.
Requirements
- Python 3.11+
uvfor the install script- An MCP-capable agent. Built against Claude Code; also usable from Codex (see below)
gitis optional. Without it the journal recordsno-gitand stays useful
Install
Two commands on purpose. The first installs the MCP server; the second wires the
hooks, which is what makes CogSession record without being asked. A package
cannot write to ~/.claude/settings.json on its own, so without the second command
you get eleven tools you must call by hand and none of the recording.
cogsession-admin install backs up your settings first, adds the six hooks
alongside anything already there, and will not overwrite a status line you
already set.
Installing from a clone instead (for working on CogSession itself)
--repo points the hooks at your checkout through uv, so edits take effect
without reinstalling.
The installer syncs dependencies with uv, registers the MCP server with Claude Code, and
writes the hooks that let it observe a session without being asked. It touches
~/.claude/settings.json and nothing inside your projects.
It will not write to a file git tracks. The handoff goes to CLAUDE.local.md, which is
auto-loaded the same way CLAUDE.md is but never committed. If that filename happens to be
tracked in your repo, CogSession refuses to write rather than dirtying your tree, and tells
you where the handoff is on disk instead. Add .cogsessions/ to your .gitignore.
The tools
Eleven MCP tools, in four groups:
| Group | Tools |
|---|---|
| Lifecycle | session_init · session_checkpoint · session_load · session_status |
| Recording | session_update |
| Searching | session_search · session_log · session_tree · session_diagram |
| Claims | claim_record · claim_check |
Plus six hooks (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse,
PreCompact, SessionEnd) that do the recording you never have to ask for.
What it does not do
Worth saying plainly, because it is the first thing people assume:
CogSession does not store your conversations. It reads the transcript only to measure how full the context window is. What it keeps is conclusions — decisions, dead ends, assumptions, claims — plus the mechanical events from the hooks. That is deliberate: a memory made of every word said is a memory nobody re-reads. But it does mean the quality of a session's memory depends on things being recorded as they are decided.
Usage
Start of every session: nothing. The SessionStart hook opens a session and
loads the previous handoff on its own. Tracking that depends on someone
remembering to turn it on is tracking that silently does not happen.
Name the session when you know what it is about — the focus line is the only part a tool cannot infer:
session_init still exists for a session you want to start deliberately, or to
attach to a parent:
Throughout the session:
At 70-80% context:
Look something up without loading anything. Every session keeps a
session.md: append-only, one block per event, each header carrying its own
local timestamp, event type, and the repo state it happened at
(branch@commit+dirty). So one grep answers a question:
Every entry line is self-describing, which is what makes a bare grep useful:
a match tells you when, what kind, and against which state of the code, with no
need to scroll for context. Tool calls are deliberately left out — hundreds per
session would bury the decisions someone is actually searching for; they stay in
session_log.jsonl.
Scan history like git log:
Scan, then grep the journal for the entry that matters. The commit id is the
join back to real git log, so a decision can be lined up with the state of
the code that produced it.
Claims — for anything you write down that could go stale:
A claim stores the command that proved it, not a note about how to check it. When the file changes, the next session is told which statements stopped being true, where they were asserted, and how they were checked. Silence means everything still holds.
This exists because the most expensive failure is not a wrong decision. It is a right one that quietly stopped being true — a description of a schema the code no longer has, a comment naming a constraint that moved, a test asserting a shape the implementation dropped.
Explore history:
How It Works: Inverted Control (Observer-First)
CogSession operates automatically via agent hooks and transcript inspection. You don't need to manually report token percentages or call tools.
- Automatic Context Measurement: Context load is read directly from Claude Code session transcripts (
input_tokens + cache_creation + cache_read + output_tokens). - Automatic Injection:
SessionStart: Injects L0 manifest & L1 handoff unprompted.UserPromptSubmit: Nudges at 65%–74%, recommends at 75%–79%, and mandates checkpoints at $\ge$80%. Surfaces prompt-relevant dead ends and danger zones.PreToolUse: Blocks file edits targeting recorded danger zones.
- Deterministic Distillation: Tracks file edits, git operations, commands, and test failures without relying on LLM guesses.
What Makes It Different
| Feature | Other Systems | CogSession |
|---|---|---|
| Dead ends tracking | ❌ | ✅ Automatic extraction of failed approaches & reasons |
| Context load measurement | ❌ Guesswork | ✅ Ground truth token measurement from transcript |
| Decision quality flags | ❌ | ✅ Automatically flagged if made at >75% context |
| Tree structure | ❌ linear | ✅ Branches like git |
| Token-aware warnings | ❌ | ✅ Automatic: 65% nudge, 75% alert, 80% mandate |
| Auto CLAUDE.md handoff | ❌ | ✅ Handoff written automatically at checkpoint |
| Architecture diagram | ❌ | ✅ Auto-generated Mermaid |
| Environment snapshot | ❌ | ✅ Exact start commands, ports, env vars |
Connect
CogSession is an MCP stdio server. If cogsession is installed in the
environment where your agent runs, register it with uv run cogsession.
Codex CLI:
If you are running CogSession directly from a local source checkout, point uv
at that checkout:
Verify the server is registered:
Restart Codex after adding the MCP server. Codex loads MCP tools when a new Codex session starts.
Claude Code:
For a local source checkout:
Cursor (.cursor/mcp.json):
For a local source checkout:
Disable for a project:
Using CogSession with Codex
CogSession is project-local. It stores session data inside the target project:
Start Codex from the project you want to remember:
Then ask Codex to use CogSession in plain language:
or be explicit:
If this is the first session for the project:
During work, record important facts:
Before stopping, checkpoint the session:
Codex Example
After loading the handoff, Codex can continue with the saved context:
Project-Local vs Global
CogSession does not use one global memory store by default. Each project gets
its own .cogsessions/ directory.
For this project:
For another project:
Those are separate histories. To inspect a specific project, ask Codex:
Codex may show an approval prompt before running a CogSession tool:
Choose Allow for this session or Always allow if you want fewer prompts.