CogSession MCP server

<!-- mcp-name: io.github.premanand8800/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

Shortened. The full README is on GitHub.