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.
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, jevmem; method and limits). 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).
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).
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), and since 0.7.1 the lines marked always-on, at the start of every session (Always-on rules) |
| 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 |
| 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, 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). 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): 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). 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.
The limits, in short #
- jevmem needs a TypeSafe API key (where to get one, and the install steps).
- Message text is sent to TypeSafe to be scored, with common secrets scrubbed first (what leaves your machine).
- 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 watchruns, 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). - 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).
- The guard is a backstop, not a sandbox (what it misses).
- 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).
Every limit, with the numbers: the FAQ.