New advertisers: 50% off your first month with code FIRSTMONTHSee slots
jatingargiitk avatar

claude-rem

jatingargiitk/claude-rem

Cross-tool session memory that compiles past sessions into a briefing, verified against git.

version
0.3.3
GitHub stars
4
View on GitHub

What it does

  • Adds hooks.json session-start and per-prompt injection hooks plus a Stop-hook harvest for Claude Code, Cursor, and Codex
  • Covers the full memory loop: each session is distilled into a ~100-line STATE briefing that is rewritten on every harvest
  • Enforces verification by checking every recorded claim against your git repos, so commits outrank what an agent reports
  • Designed for developers who run parallel sessions across several projects and want corrections to persist in every tool

Session memory for AI coding agents: every session compiled into a current-truth briefing your next session starts with

Add marketplace

/plugin marketplace add jatingargiitk/claude-rem

Run it inside Claude Code once, then install the plugin below.

Install

/plugin install claude-rem@claude-rem

Run it inside Claude Code after adding the marketplace.

Files

Discovered from source

Readme


🧠
claude-rem

A brain that remembers everything. One memory for all your AI coding tools.

npm License Node No API key

Claude Code Cursor Codex CLI

Quick Start • Works With • What It Looks Like • How It Works • Commands • FAQ • License

claude-rem reads each session after it ends, distills what mattered into a briefing of your workspace, verifies it against your repos, and hands it to your agent the moment the next session starts. Tell it something once, anywhere; every tool remembers it.


One brain, every tool. Your transcripts are the richest record of your work that exists, and today they evaporate when the session ends. Claude Code, Cursor, and Codex all feed and read the same store, so that record works for you, not for any one platform. No vendor will compile a competitor's transcripts for you.

Evidence over claims. Agents confidently report things that didn't happen, so everything is checked against your repos before it becomes memory. If the session says "built the API" and git disagrees, the brain believes git. Every fact traces back to a session digest and a commit.

Why "rem"? REM sleep is when a brain consolidates the day into long-term memory. Same job here: replay the session, verify it, consolidate what mattered, brief the next one.

I built claude-rem because I run a 40-project workspace with sessions in parallel across Claude Code and Cursor, and I was the memory: every new session started ignorant and I re-taught it. Today my brain holds 100+ compiled sessions across 24 projects and the rules my agents follow everywhere. This README was written by an agent running on it.


claude-rem dashboard

An example workspace — the same two-service project used throughout this README.

Quick Start

cd ~/your-workspace        # the directory you open your coding agent in
npx claude-rem init

Or from the plugin marketplace inside Claude Code:

/plugin marketplace add jatingargiitk/claude-rem
/plugin install claude-rem

Init scans your past sessions (with your consent) and compiles a real starting brain, so it remembers your history from day one:

Brain compiled: 43 session digest(s), 14 project note(s) in 434s.

A few minutes, once per workspace, ever. It runs on the Claude subscription you already pay for and prints its own cost receipt. From then on everything is automatic.

Key Features:

  • 🎯 Relevance-gated injection: full briefing on the first prompt; after that, only the note your prompt is about, or silence
  • 🧠 Compiled, not appended: every harvest rewrites a ~100-line STATE of what's true right now; the store gets cleaner as it grows
  • 🔁 Corrections that stick: correct it once and it becomes a rule every future session obeys, in every tool
  • 📊 Self-measuring: ab and eval run blind brain-vs-no-brain comparisons with an impartial judge
  • 📁 Plain files + git: markdown you can read and diff; one commit per harvest, anything wrong is one revert away
  • 🔒 Local and private: no server, no telemetry, no API key; <private>...</private> never reaches a model
  • 🪶 No daemon, no vector DB, no heavy deps: hooks fire, do their job, exit; atomic writes under one shared lock

Works With

ToolReads the brainFeeds the brain
Claude Codesession-start + per-prompt injection hooksStop-hook harvest
Cursorsession-start + per-prompt injection hooksstop-hook harvest (cursor-agent engine fallback)
Codex CLImanaged block in AGENTS.md (markers only)notify-hook harvest
npx claude-rem init --cursor --codex

What It Looks Like

The first prompt of a session gets the full briefing, with a receipt naming exactly what was injected:

🧠 brain → STATE.md · 14 projects indexed (harvest 33m ago)

Later prompts only get the note they're about, or nothing:

🧠 brain → tiny-api

Behind the receipt sits STATE.md. Real output, compiled from real sessions on a two-service workspace:

## Active projects
- **webhook-relay** (`relay.py`): verifies Stripe HMAC-SHA256 signatures
  (constant-time compare), forwards to an internal queue, retries
  1s/2s/4s/8s/16s then dead-letters. Queue changed from unbounded to
  bounded (maxsize 1000) with HTTP 429 backpressure on 2026-08-12,
  root-caused as the fix for a same-day incident where a traffic spike
  OOM-killed the process and dropped in-flight events.
- **tiny-api** (`app.py`): Flask items API confirmed working both from
  shell and under launchd, on port 5057. DB path changed from relative to
  absolute, which resolved 500s that occurred only under launchd.

## Conventions
- webhook-relay: payload bodies are never logged (may contain customer
  PII) — only event ID + status, per explicit user instruction.
- tiny-api: port 5057 instead of 5000 — macOS AirPlay Receiver occupies
  5000, causing "address already in use".

## Open threads
- Cross-project gotcha: launchd-run processes do not share the shell's
  working directory. This caused the tiny-api DB bug; webhook-relay has
  NOT yet been audited for the same relative-path assumption.
- Cross-project gotcha: an unbounded internal queue is a silent OOM risk
  that surfaces only under load. This caused the webhook-relay incident;
  other queues have not been checked for the same pattern.

Three things worth noticing. The PII rule exists because the user said it once, mid-session. The incident entry keeps root cause and fix rationale together, not just the final code state. And the cross-project gotchas are what grep can never give you: the brain generalized each incident into a pattern and flagged the other service as unaudited for it. That is the difference between storing your history and remembering it.

The dashboard

npx claude-rem ui

A local dashboard (127.0.0.1 only, no daemon; it runs while you look at it):

  • Your brain, live: an interactive map of your projects. Node size tracks how much it knows; amber halos mark what the briefing is worried about. Click any project to see exactly what it remembers, its loose ends, and the sessions behind it.
  • Where you left off / Recent wins / Heads up: a model-written briefing of your workspace, rewritten after every save.
  • Ask your brain: ranked search over everything it knows, with a ⌘K command palette.
  • Latest sessions: every session digest on a timeline, click to read.
  • The topbar tells the truth: green watching · saved 4m ago while hooks are live, amber stale when nothing has been saved for a day.

It Measures Itself

npx claude-rem ab "why is the deploy failing?"   # one question, blind vs brain
npx claude-rem eval                              # your whole question set, judged blind

eval answers every question twice, brain injected vs brain physically hidden from disk, then a third model grades both blind, order randomized. Latest run on my own workspace: 6-3-1 for the brain, and zero wrong-frame answers against three for the no-brain arm (the blind agent confidently answered the wrong question three times; the brain never did). The honest parts: it ties where the answer is already well documented, loses where a strong agent can just read the code, and a brain-plus-cheap- model does not beat a strong model without one (measured, not assumed). The brain wins where the answer exists only in history: decisions, incidents, dead ends. Every failure found became a fix. As far as I know it's the only memory system that ships its own falsification harness.


How It Works

session ends ──► condense transcript (no LLM, <private> stripped)
             ──► evidence snapshot (git status of your repos)
             ──► ONE model call: returns digest + topic + STATE as text
             ──► claude-rem applies the files itself (atomic, path-jailed)
             ──► git commit
session starts ─► receipt + briefing injected; later prompts get
                  relevance-matched project notes, or silence

The model never touches your disk. One single-turn call per debounced session-end (~40KB of new transcript), in the background, never blocking you. The brain lives at <workspace>/.claude-rem/:

STATE.md          # the ~100-line briefing, injected at session start
topics/<slug>.md  # rolling per-project detail, rewritten in place
sessions/         # immutable session digests (raw history)
RULES.md          # learned conventions, promoted from your corrections
evals.json        # your blind-eval question set
.git/             # one commit per harvest

Most memory tools are diaries: append forever, search the pile, recall degrades as it grows. That is storage, not remembering. claude-rem rewrites its briefing in place, the same consolidation bet OpenAI, Anthropic, and Google all made this year. A bigger pile is not a better memory.

Retrieval has to earn the context it spends. Being named outranks being mentioned; BM25 length normalization stops your biggest note from winning every query by sheer surface area; a note the harvester rewrote mid-session loses its body advantage, so a session can't retrieve its own echo; and the winner has to stand out from the field or nothing is injected at all. Silence is a correct answer — a wrong note costs context and steers the agent at the wrong repo. You can grade all of that yourself in milliseconds, no model call: python3 scripts/retrieval-eval.py .claude-rem. Details in How It Works.


Documentation

  • Installation: quick start, flags, marketplace install, uninstall
  • Commands: every CLI command — you only ever need init
  • How It Works: the harvest loop, the three memory layers, injection
  • Architecture: per-tool hooks, harvest engines, corruption resistance
  • Configuration: config.json keys, env vars, the rules layer
  • Evaluation: the blind ab/eval harness
  • Privacy: what stays local (everything), what leaves (one distill call)
  • Troubleshooting: health checks, failure modes, starting over

FAQ

What does it cost? Nothing beyond the Claude subscription you already pay for. No API key, no separate billing. The starting compile prints its own receipt; after that it's one small single-turn call per session-end, always on the best model the host offers (a cheap model writes confident wrong facts into memory that every later session inherits — pin model in config if you disagree).

Does my code leave my machine? Only to your own Claude subscription for the distill call, which is where your sessions already go. No server of mine, no telemetry, no uploads.

Does it work in claude.ai web / cloud sessions? No, by design it's local. Every local surface works (terminal, VS Code / JetBrains, desktop app, Cursor, Codex CLI); cloud sandboxes can't reach your disk. Your memory stays on your machine; that's the trade.

What if a harvest writes something wrong? Every harvest is a git commit. Revert it.

Why not just write better commits and an AGENTS.md? Do both; they compound. But an instruction file only works while the agent remembers to follow it, and instruction-following decays over a long session. Hooks fire deterministically at session end whether the agent remembers or not, and commits never capture the reasoning behind a change.

Doesn't the brain rot as sessions pile up? No, because nothing piles up. The briefing is rewritten in place every harvest, and digests older than 30 days are consolidated into monthly rollups. The store stays roughly the same size while getting more accurate.

Will the agent ignore the brain and write its own memory files? In Claude Code and Cursor it can't drift far: injection happens in hooks outside the model, so the briefing arrives whether the agent cooperates or not. It never depends on the model choosing to use a tool.

I use Cursor but not Claude Code, does it work? Yes. Harvesting falls back to Cursor's cursor-agent CLI when claude isn't installed, so a Cursor-only machine gets the full loop.


Requirements

macOS or Linux · Node ≥ 18 · python3 · git · the Claude Code CLI logged in to your subscription (or cursor-agent on Cursor-only machines).

Roadmap

A shared team brain: what one engineer's sessions learn, every teammate's agent knows · More transcript readers (Gemini CLI and friends) · MCP server so non-hooked tools can pull from the brain · Windows.

Where This Is Going

A commit shows what changed. It never shows what you tried and rejected, why you picked this approach, or the gotcha that cost two hours. That reasoning is the real operating knowledge of your work. It exists only in your sessions, and today it evaporates when they end.

claude-rem is built on the bet that this knowledge, captured, verified, and compiled, becomes the layer your agents actually run on. First for you, across every tool. Next for teams: what one engineer's sessions learn, every teammate's agent knows, so repo conventions stop drifting and nobody's agent relearns a lesson someone already paid for. The end state is the operating memory of the AI-native company: fifty engineers' agents working from one compounding brain instead of fifty amnesiac ones.

Today ships the first layer. It has to be excellent before the rest matters.

Status

v0.3.x, young and moving fast. Issues and war stories welcome.

License

Apache-2.0

Details

Marketplace
jatingargiitk/claude-rem
Source
.
Category
Community

Similar to claude-rem

More Memory & Context