# Should I use CLAUDE.md or JEVMEM.md?

Use both: keep in `CLAUDE.md` what you want to write and edit by hand, such as how to build and test the project, and let jevmem keep `JEVMEM.md`, the decisions, rules and failed approaches that come up in your chats, which it saves as you work, brings back when a prompt needs them, and checks Claude's commands against.

Last updated: 2026-11-17 · jevmem 0.7.8 · [Install](https://avinash-jetwani.github.io/jevmem/install/) · [Source on GitHub](https://github.com/Avinash-jetwani/jevmem)

In 72 real Claude Code sessions, Claude followed the project's saved decision in 66 with jevmem (66/72) and in 67 with the same lines in a hand-written `CLAUDE.md` (67/72), against 28 with no project memory (28/72) ([no memory and CLAUDE.md](https://github.com/Avinash-jetwani/jevmem/blob/main/results/ab-2026-09-28.json), [jevmem](https://github.com/Avinash-jetwani/jevmem/blob/main/results/ab-jevmem-2026-09-29-3b.json); [method and limits](https://avinash-jetwani.github.io/jevmem/results/#does-claude-act-on-the-saved-line)). So the two did about as well; the difference is who writes the file and what reads it.

## Side by side

| | `CLAUDE.md` | `JEVMEM.md` |
|---|---|---|
| Who writes it | You, by hand | jevmem, from your chats; you can add, retire and mark lines |
| What goes in it | Anything you choose | One line per decision, rule, failed approach, bug or to-do |
| When Claude Code gets it | The whole file, at the start of each session | The lines a prompt needs, on every prompt; always-on rules at the start of each session |
| Checked before a command or edit runs | No | Yes, by the guard |
| Written for | Claude Code | Claude Code, Cursor and Codex, and Claude Desktop over MCP |
| Shared with your team | Through git | Through git |
| Needs a key | No | A paid TypeSafe API key |

## When CLAUDE.md alone is enough

If you already keep a `CLAUDE.md` up to date and work alone in Claude Code, it covers the decisions you remember to write down. jevmem helps when rules come up in chats and never reach the file, when teammates or other tools need the same rules, and when you want commands checked against them before they run.

## Already have a CLAUDE.md?

`jevmem import` splits `CLAUDE.md`, `AGENTS.md` and `.cursor/rules/*` into statements, puts each through the same check as a chat turn, and prints what it would add; `--apply` writes them. The source files are only read, so your `CLAUDE.md` stays as it is ([install](https://avinash-jetwani.github.io/jevmem/install/)).

## Rules every change must follow

A rule like "every new string goes through `t()`" applies to work whose prompt never mentions it. `CLAUDE.md` is in every session, so it reaches Claude. jevmem marks such a rule always-on (since 0.7.1) and sends it at the start of every session: on six held-out tasks written for that case, Claude followed the convention in 18 of 18 sessions with 0.7.1, as with the same lines in a hand-kept `CLAUDE.md` ([results](https://github.com/Avinash-jetwani/jevmem/blob/main/results/ab-alwayson-v2-2026-10-13-v071.json)).

## jevmem next to CLAUDE.md and Claude Code's auto memory

There are two kinds of memory besides Jevmem, and it replaces neither. Auto memory is per tool and per machine. Project instruction files are per repository, and one of them is not tied to a tool: `AGENTS.md` is read by Claude Code (2.1.277 or later), Cursor and Codex. What Jevmem adds is a file that is kept current for you and read per prompt.

| | Built-in auto memory (e.g. Claude Code's, under `~/.claude/projects/…` on your machine) | Project instruction files (`CLAUDE.md`, `AGENTS.md`, `.cursor/rules/`) | Jevmem |
|---|---|---|---|
| Scope | Per tool, per machine. Claude Code's is on by default, machine-local, and one folder per repository (its worktrees share it) | Per repo. `AGENTS.md` is read by Claude Code (v2.1.277 and later; by default only when there is no `CLAUDE.md`), Cursor and Codex; `CLAUDE.md` by Claude Code; `.cursor/rules/` by Cursor | One `JEVMEM.md` per repo, read by Claude Code, Cursor, Codex and Claude Desktop |
| Shared with the team | No | Yes, committed files reviewed in PRs | Yes, a committed file reviewed in PRs |
| What a session sees | Claude Code: the first 200 lines or 25 KB of its `MEMORY.md` index at the start of every session; the notes it points to when Claude opens them | The whole file (Claude Code: up to 4 MiB), at the start of every session | The lines Jev judges relevant to each prompt, at most five ([The read side](https://github.com/Avinash-jetwani/jevmem/blob/main/docs/how-it-works.md#the-read-side-one-call-per-prompt-srcrecallts)), and since 0.7.1 the lines marked always-on, at the start of every session ([Always-on rules](https://github.com/Avinash-jetwani/jevmem/blob/main/docs/how-it-works.md#always-on-rules-071)) |
| Who keeps it current | The tool (Claude Code: Claude, when it judges a note worth keeping) | You, by hand | Jevmem, after every Claude Code turn (and Codex turns under `watch`, and agent `add_memory` calls) |
| Why a line exists | No per-line scores that we know of | You wrote it | Per-line scores on the machine that saved it: `jevmem why <id>` shows every noul, the kind distribution, importance, and which threshold it cleared |
| What happens on a reversal | Claude rewrites the note, or its index line, in place (the docs do not say; in the 0.7.7 comparison it rewrote or removed the old index line and rewrote the old note in 12 of 12 changed decisions) | You edit it (history if the file is in git) | The old line stays, tagged `[superseded] … → id:new`, so history and blame survive (0.7.7 comparison: superseded in 6 of 12 changed decisions with jevmem alone, 9 of 12 with auto memory on too) |
| Measured side by side (0.7.7) | Followed a line taught in an earlier session in 47 of 54 sessions (49 after reading every miss by hand) | The same line written into `CLAUDE.md`: 45 of 54 (46) | 40 of 54 (40) alone, 45 of 54 (48) with auto memory on; no forbidden change left in the code. [Every row](https://github.com/Avinash-jetwani/jevmem/blob/main/docs/benchmark.md#against-claude-codes-auto-memory-077) |
| Corrections | Edit its files | Edit the file | `right` / `wrong` / `missed` labels, and `fit` retunes the thresholds to your judgement; since 0.7.0 `jevmem forget` retires a line in place and `jevmem trust` marks one you wrote as verified; since 0.7.1 `jevmem always` marks a rule for every change |

Claude Code's auto memory and instruction files are described at https://code.claude.com/docs/en/memory (read 2026-09-28, and again on 2026-10-24 for Claude Code 2.1.306: every fact in the table still held; since then the docs add the switches `autoMemoryEnabled`, `CLAUDE_CODE_DISABLE_AUTO_MEMORY` and `--bare`, and an error when a write leaves `MEMORY.md` over its 200 lines or 25 KB, and say nothing on what happens to a note when a decision changes; its [AGENTS.md section](https://code.claude.com/docs/en/memory#agents-md), read 2026-09-29, gives v2.1.277 and when `AGENTS.md` loads instead of `CLAUDE.md`). `AGENTS.md` in Cursor: https://cursor.com/docs/context/rules; in Codex: https://developers.openai.com/codex/guides/agents-md; the format: https://agents.md (all read 2026-09-29). The instruction files are shareable today; Jevmem's difference is that it **maintains** its file automatically and **scores** each line. Both can run at once; the end-to-end harness checks that Jevmem behaves the same with Claude Code's auto-memory present or cleared.

**Rules that must apply to every task: always-on since 0.7.1.** Jevmem puts a line in front of Claude when Jev judges it relevant to the prompt at hand, so a rule that holds for a whole class of changes, with nothing in a given prompt pointing at it, was missed: in the outcome A/B, the convention that every user-facing string goes through `t()` was never injected for a prompt to add a button, and Claude followed it in 0 of 3 sessions; with the same line in `CLAUDE.md` it did in 3 of 3 ([Benchmark](https://github.com/Avinash-jetwani/jevmem/blob/main/docs/benchmark.md#outcome-ab-does-claude-act-on-the-memory)). Since 0.7.1 such a line is marked always-on, by Jev when it is saved or by `jevmem always <id>`, and reaches Claude at the start of every session ([Always-on rules](https://github.com/Avinash-jetwani/jevmem/blob/main/docs/how-it-works.md#always-on-rules-071)): on six held-out tasks written for that gap, Claude followed the convention in 14 of 18 sessions with 0.7.0 and 18 of 18 with 0.7.1, as with the same lines in `CLAUDE.md` ([Benchmark](https://github.com/Avinash-jetwani/jevmem/blob/main/docs/benchmark.md#always-on-rules-071)). `CLAUDE.md` or `AGENTS.md`, which the tools load at the start of every session, still hold what you write by hand; the two work side by side. Leave the rest to Jevmem: the decisions, dead ends, bugs and facts that pile up as you work, which change as the project moves, are soon too many to load whole, and matter only when a prompt touches them. Jevmem neither reads nor changes `CLAUDE.md` (only `jevmem import` reads it, when you run it).

The same comparison with other memory tools: [jevmem compared](https://avinash-jetwani.github.io/jevmem/compare/).

## The limits, in short

- jevmem needs a TypeSafe API key ([where to get one, and the install steps](https://avinash-jetwani.github.io/jevmem/install/)).
- Message text is sent to TypeSafe to be scored, with common secrets scrubbed first ([what leaves your machine](https://avinash-jetwani.github.io/jevmem/privacy/)).
- It is automatic in Claude Code and, since 0.7.4, in Cursor (as a Cursor plugin since 0.7.6, whose rule sits in every chat), automatic in Codex while `jevmem watch` runs, and in Claude Desktop only when the agent calls it; in Cursor, bringing lines back is still the agent's call ([what each tool does](https://avinash-jetwani.github.io/jevmem/install/#works-with)).
- Rules every task must follow reach every session only when they are marked always-on (0.7.1), by Jev's reading or yours ([jevmem next to CLAUDE.md](https://avinash-jetwani.github.io/jevmem/compare/)).
- The guard is a backstop, not a sandbox ([what it misses](https://avinash-jetwani.github.io/jevmem/guard/#limits)).
- The side pane is Claude Code only, 2.1.299 or newer: Cursor has no pane, and Claude Code for VS Code draws none yet ([the pane](https://avinash-jetwani.github.io/jevmem/pane/)).

Every limit, with the numbers: [the FAQ](https://avinash-jetwani.github.io/jevmem/faq/#what-are-jevmems-limits).
