jevmem

<picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/Avinash-jetwani/jevmem/main/brand/lockup/svg/jevmem-lockup-horizontal-dark.svg"><img alt="jevmem" src="https://raw.githubusercontent.com/Avinash-jetwani/jevmem/main/brand/lockup/svg/jevmem-lockup-horizontal-light.svg" height="64"></picture>

Automatic project memory for Claude Code. Also works with Cursor and Codex.

**Now in Anthropic's Claude plugin directory:** in the Claude app, Plugins → Discover → jevmem → Add, then follow [the setup steps](#from-the-claude-plugin-directory).

[![npm version](https://img.shields.io/npm/v/jevmem.svg)](https://www.npmjs.com/package/jevmem)
[![license](https://img.shields.io/npm/l/jevmem.svg)](LICENSE)
[![node](https://img.shields.io/node/v/jevmem.svg)](package.json)
[![CI](https://github.com/Avinash-jetwani/jevmem/actions/workflows/ci.yml/badge.svg)](https://github.com/Avinash-jetwani/jevmem/actions/workflows/ci.yml)
[![M8ven Verified](https://m8ven.ai/badge/mcp/avinash-jetwani/jevmem?variant=verified)](https://m8ven.ai/mcp/avinash-jetwani/jevmem)

## What it does

https://github.com/user-attachments/assets/ed77849e-db1c-4c05-9ad8-4cab0b3968a2


- Saves decisions, constraints, bugs, todos and dead ends (an approach that was tried and failed, with the reason) from your Claude Code chats into `JEVMEM.md`, automatically.
- When you change your mind, the old line is marked superseded, not deleted.
- Next session, the relevant lines are added to Claude's context.
- Checks lines added by others before they're added to Claude's context.
- Checks Bash, Edit and Write calls against your saved rules before they run, and has Claude Code ask you when one may be broken (the guard, 0.6.0).

```text
- [superseded] We'll use SQLite as the primary store for now. → id:cuasaq  <!-- id:21ycba ts:2026-09-26T13:46:34.703Z conf:1.00 by:cuasaq -->
- [decision] Switch the primary store to Postgres 16.  <!-- id:cuasaq ts:2026-09-26T13:46:35.240Z conf:1.00 -->
- [constraint] Node 20 is the minimum supported version, and CI runs Node 20 and 22.  <!-- id:tollba ts:2026-09-26T13:46:35.763Z conf:0.90 -->
```

Real lines from 0.5.7's default writer, which 0.5.8 to 0.5.10 did not change ([the run](results/readme-example-2026-09-26.txt), 2026-09-26). It kept one sentence of each turn: the Postgres turn also said "SQLite locks up under concurrent writes", and that reason was left out. Since 0.6.0 the line is made from the sentences Jev picks, the one that states the memory and the one that gives its reason ([What's new](#whats-new)). With `writer` set, an OpenAI or Anthropic model condenses the whole turn instead.

## What's new

**What's new in 0.6** (0.6.0, 2026-09-30; [CHANGELOG](CHANGELOG.md#060---2026-09-30))

- **Dead ends.** jevmem saves an approach that was tried and failed, with the reason, and puts it in front of Claude as "Already tried: …" when a prompt comes back to it. A later turn that shows it works now supersedes it ([docs/dead-ends.md](docs/dead-ends.md)). *Decide's held-out v3 set, 100 turns in five new projects, run on the release build on 2026-09-30 (first run 2026-09-27, before the writer changed): dead ends saved 25 of 25, every one with its reason (25 of 25); reversals of a saved line superseded 10 of 10 ([results](results/dead-ends-heldout-v3-2026-09-30-v060.json)). In the outcome A/B below, Claude never repeated an approach recorded as failed (0 of 15 sessions), against 3 of 15 with no memory; the same lines in `CLAUDE.md`: also 0 of 15.*
- **Recall that finds the lines a prompt needs, and nothing for a prompt that needs none.** Every live line is asked about, each on its own. *Retrieval held-out v2: 90 prompts over three new projects of 20, 80 and 250 lines, run once on 2026-09-28, 0.6 (`48cc67d`, the recall code that ships) against 0.5.9: recall 75/78 against 55/78 (18 of the 78 wanted lines are dead ends, which 0.5.9 cannot read; on the other 60, 0.6 found 57 and 0.5.9 found 55); lines injected that were wanted or fine 96/97 against 88/104; unrelated prompts that got a line 1/18 against 5/18; superseded lines injected 0 of 90 in both. Prompts that need two lines got both in 3 of 6. Cost per prompt $0.000578 against $0.000267, and $0.001002 against $0.000320 on the 250-line file. Above 250 live lines, only the 250 sharing the most words with the prompt are asked about (a 500-line dev file: recall 37/46).*
- **A slow or failed Jev call no longer means no memory.** Past one second, the prompt gets the lines that share the most words with it. *On held-out v2 no call ran late (hook p95 596 ms; 0.5.9's, in the same run, 491 ms), so this served no prompt there. Word match finds lines that share the prompt's words (on dev, as if every prompt had fallen back, 25 of 32 for prompts that name what they need) and seldom the others (3 of 33).*
- **Claude acts on the saved line about as often as with `CLAUDE.md`.** "With jevmem, Claude followed the project's saved line in 66 of 72 sessions; with the same lines in `CLAUDE.md`, in 67 of 72; with no memory, in 28 of 72." *24 tasks in three small projects of 34 to 42 saved lines, 3 runs each, real Claude Code 2.1.281 sessions with `claude-sonnet-5`; the jevmem arm on 0.6 (`48cc67d`, 2026-09-29, the same 66 of 72 as on part 3's build; the recall code that ships), the other two arms in part 3's run (2026-09-28). `CLAUDE.md` did better where nothing in the prompt points at the line (a convention for every user-facing string: 3 of 3 against 0 of 3); rules every task must follow belong there.*
- **The guard, a backstop.** A `PreToolUse` hook checks each Bash, Edit and Write call against your saved rules, and has Claude Code ask you (or blocks the call) when Jev says it may break one ([docs/guardrails.md](docs/guardrails.md)). *In the A/B's 6 constraint tasks (18 sessions, rerun on the release build on 2026-09-30 with Claude Code 2.1.284), recall kept Claude from ever attempting the forbidden change (0 of 18; 10 of 18 with no memory in the 2026-09-28 run), and the guard checked all 78 of those sessions' Bash, Edit and Write calls and asked once: an edit to the output formatter that put a new format behind a new flag, as its rule allows (Jev 0.89); in `claude -p` that ask refused the edit, and the session finished the task another way, 18 of 18 followed the rule and 17 of 18 did the task ([results](results/ab-guard-2026-09-30.json)). On the guard's second held-out set (274 calls in five new projects, written after a day's trial in jevmem's own repository; run once on the 0.6.0 build on 2026-09-30 and once on 0.6.1 the same day): violations caught 66/68 and the check that guards jevmem's own files right on 274/274 calls in both runs, and false asks 3–4 of 206 across the two (the one call that differs is `git add token.secret.example`, which breaks no rule: 0.52 in the 0.6.0 run, then 0.47, either side of the 0.5 threshold; the command has no bracket, so that is Jev's variation between runs, not the fix) ([docs/guardrails.md](docs/guardrails.md#the-test-command-after-a-reserved-word-061)).*
- **Background subagents.** A turn that hands work to a subagent in the background is decided once, when it is over, not while the subagent works, and the subagent's report is never read as your message. *Decide held-out v4: 30 real Claude Code 2.1.281 sessions, 14 with a background subagent, replayed through the release build and 0.5.9 in one run on 2026-09-30 (first run 2026-09-28): lines saved while a turn was still running 0 (0.5.9: 9), lines decided from a subagent's report read as your message 0 (0.5.9: 13), turns saved or skipped right 32 of 33 (0.5.9: 27 of 33) ([results](results/stops-heldout-v4-2026-09-30-v060.json), [0.5.9](results/stops-heldout-v4-2026-09-30-v059.json)). The line is the sentence that states the memory, not the request or hand-off next to it: on a line-text held-out set of 64 saved turns in four new projects (16 of them a memory next to a request or a hand-off to a subagent), run once on 2026-09-29 on the writer that ships, the saved lines stated the fact in 62 of 63 (0.5.9: 41 of 59), kept the reason in 29 of 30 (0.5.9: 5 of 25), and none was a request or a hand-off (0.5.9: 13 of 59).*

- **0.6.1 and 0.6.2 fixed the guard skipping a Bash call with `if [ … ]` or `while [ … ]` in it** (0.6.0's check threw on the `[` and the hook stayed silent, so the call ran unchecked; 0.6.2 is 0.6.1's code, published again): [docs/guardrails.md](docs/guardrails.md#the-test-command-after-a-reserved-word-061), [CHANGELOG: 0.6.1](CHANGELOG.md#061---2026-09-30), [0.6.2](CHANGELOG.md#062---2026-09-30).
- **0.6.3 fixes what you see, not what is saved, recalled or checked:** `jevmem doctor` shows the plugin synced from claude.ai once, its newest copy, where an update had left the previous copy beside it and doctor listed both; the limits and the upgrade notes below say what an open session loses when that plugin updates, and what to do; `scripts/eval.mjs` records the version of the build it measured ([CHANGELOG](CHANGELOG.md#063---2026-09-30)).

**Known limits in 0.6.3**

- **A plain statement can fall under the content threshold.** A rule said without must, never or prefer ("user-facing copy is British English") can be skipped: 2 of the 12 genuine rules on the genuine-rule held-out set, in 0.5.9 too ([docs/benchmark.md](docs/benchmark.md#genuine-rules-and-the-injection-check)).
- **No way to mark your own rules as verified.** A line you add with `jevmem add` or by hand is unverified: the poisoning gate checks it before recall serves it, and the guard asks about it but never denies on it.
- **A line is at most two sentences, and Jev can pick the wrong one** ([docs/benchmark.md](docs/benchmark.md#the-line-part-3c)). Jev picks the sentence that states the memory and the one that gives its reason; a fact told in two sentences keeps one of them, and on the line-text held-out set one rule's line was its consequence without the rule (1 of 63), and one to-do kept "don't start