CogSession

🌳 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

Session 1 (context fills) → Session 2 starts fresh → Session 3 starts fresh

Everything lost. Repeats the mistakes. Starts blind again.

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.

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

[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

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

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

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+
• uv for the install script
• An MCP-capable agent. Built against Claude Code; also usable from Codex (see below)
• git is optional. Without it the journal records no-git and stays useful

Install

pip install cogsession        # or: uv tool install cogsession

cogsession-admin 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)

git clone https://github.com/premanand8800/cogsession.git

cd cogsession uv sync uv run cogsession-admin install --repo .

--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:

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_update(type="focus", content="auth module")

session_init still exists for a session you want to start deliberately, or to attach to a parent:

session_init(project_root="/your/project", focus="auth module")

session_load(project_root="/your/project") # load a previous handoff by hand

Throughout the session:

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)

At 70-80% context:

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

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:

grep -n -A4 "dead_end"  .cogsessions/<session>/session.md   # what already failed

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

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`:

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

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:

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

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.