claude-engram

Status: I'm no longer working on claude-engram. Its last code change was July 17, 2026; since then only this README has changed. It was my first experiment in giving Claude a memory of its own, and my current work on that idea is Counterparts.

What carries over if you move:

• There's no importer; nothing moves by itself.
• ~/.claude-engram stays as it is. Counterparts keeps its memory in ~/.counterparts and refuses to put its store inside the old folder.
• The terminal setup leaves claude-engram's hooks alone, so both memories load at each session start, and claude-engram keeps making its calls on your API key, until you turn claude-engram off.
• To bring across what still holds, ask Claude in a session to read ~/.claude-engram/identity/core.md and the files in ~/.claude-engram/identity/people/, and remember what's still true in its own words. With the terminal install, counterparts note "Prefers short answers." --kind person adds one memory by hand. The plugin install has no counterparts command.
• Episodes stay where they are, as Markdown files in ~/.claude-engram/episodes/.

Install Counterparts. You already have bun from claude-engram (Counterparts needs 1.3 or newer; bun upgrade if yours is older), so in a terminal:

bun add -g counterparts && counterparts

Then restart Claude Code. Or run /plugin marketplace add mlapeter/counterparts and then /plugin install counterparts@counterparts inside Claude Code. With Node 22.15 or newer, npm install -g counterparts@latest works too.

The full comparison, with the steps for bringing old notes across and turning claude-engram off: claude-engram vs Counterparts: stay or move?

Brain-inspired persistent memory for Claude Code. Memory for Claude, not notes about you: episodes Claude writes in its own voice, an identity it authors and maintains across sessions, and a world-store where memories strengthen with use, fade without it, and consolidate while you sleep.

The design center is a single idea: memory is structure, not record. A transcript is not a memory. What matters is that the shape of what happened keeps doing work — the way a forgotten childhood keeps doing work in an adult. So this system gates hard on salience, forgets honestly on a power-law curve, compresses old episodes to gist, and treats "nothing durable happened today" as a correct answer rather than a failure.

The loop

 ENCODE (continuous, dumb, cheap)          SLEEP (nightly, judged)
 hooks append conversation spans           consolidation merges, prunes to
 to a durable buffer — microseconds,  ──►  archive, compresses old episodes
 no API calls, crash-safe                  to gist, links related memories,
        │                                  folds identity edits
        ▼                                          │
 SELECT (rare, whole arcs)                         ▼
 a detached runner judges the              WAKE (milliseconds)
 buffer at natural boundaries —       ◄──  cached briefing + identity
 with an explicit "nothing worth           documents inject at session
 keeping" option                           start

              SURFACE (on demand): MCP recall mid-conversation,
              following learned associations one hop; retrieved
              memories strengthen (Hebbian)

Judgment lives at the edges (sleep and wake, where strong models decide what matters); the hot path is deliberately dumb. Every hook returns in milliseconds because the expensive thinking happens later, detached, on whole conversational arcs instead of fragments.

Three stores

Registers carry different physics. craft (work knowledge — mostly re-derivable from your repo) decays 1.3× faster and compresses to gist after 7 days. person and self decay slower (0.85×) and hold their exact words for 30 days. Consolidation and interference never cross registers — a technical note can never absorb a personal memory. Briefings budget space by register so a week of heavy coding can't crowd out what matters.

First run: the system's first act is self-authorship

There is deliberately no identity template. On first session start, instead of injecting documents, engram injects an invitation: when a session has given the model something true to say, it writes its own identity/core.md — first person, its own voice, no rush. The invitation disappears the moment the file exists. From then on, consolidation maintains what the model wrote; session-end asks fold durable changes back in as dated deltas.

Same principle at session close: when a session was substantial, the Stop hook asks the session model itself to write the episode — because it's the only one who was there.

Install

Prerequisites: bun, an Anthropic API key. Optional: a Voyage AI key for semantic search embeddings (recommended — also enables memory association links).

git clone https://github.com/mlapeter/claude-engram.git
cd claude-engram
./install.sh

Then give the hooks their keys via a dedicated env file (survives shell-profile weirdness):

mkdir -p ~/.claude-engram
cat > ~/.claude-engram/env <<'EOF'
ANTHROPIC_API_KEY=sk-ant-...
VOYAGE_API_KEY=pa-...
EOF

Restart Claude Code. Encoding starts immediately; the identity invitation appears at your next session start.

Escape hatches: ENGRAM_DISABLE=1 short-circuits every hook. ENGRAM_OBSERVER=1 (or "observerMode": true in config) lets recalls read without strengthening — use it when poking at the memory system itself.

How it works

Hooks (passive, automatic)

The buffer is a plain text file. Extraction claims it atomically and clears it only on success — an API outage delays memories rather than deleting experience. Crashes lose nothing.

Sleep (consolidation)

On the first wake of a new active day — a day you actually used Claude — with pending work, a detached consolidation run:

• merges true redundancies (sources archived with merged_into lineage, never deleted)
• prunes decayed memories into a deep archive (recoverable via deep_recall)
• promotes old episodic detail to semantic gist (verbatim originals archived with gist_of lineage)
• links related-but-distinct memories with association edges that recall later follows
• folds identity deltas into core.md and people/ (highest-stakes text in the system — handled by the strongest model, with rotated backups)
• commits the data directory to git so every consolidation is inspectable and reversible

Time runs on days actually lived, not calendar time: a month away causes zero decay. You come back to exactly the memory you left.

MCP tools (active, on demand)

Dashboard

"dashboard": true in ~/.claude-engram/config.json serves a live view at localhost:3333: overview tiles, searchable memories with strength bars, the Mind tab (identity documents, episodes, deltas, identity before/after diffs), and Health (per-hook latency percentiles, failures, log tail). It answers "is this actually working?" without the terminal.

The system also announces its own failures: if extraction or consolidation has been failing, the next session start says so, in context, where it will actually be seen.

Using engram with claude.ai

The memory lives in a data directory, and that directory doesn't care which surface a
memory came from. Claude Code fills it through hooks. claude.ai has no hooks, so the
bridge is manual but light: a settings prompt asks Claude to emit a small, versioned
memory dump at the end of a conversation — but only when something durable actually
happened. You paste that dump into the dashboard's import box, it lands in inbox/, and
the next consolidation folds it into the same episodes and world-store engram builds from
Claude Code. Same mind, second surface.

This is the ritual the whole project grew out of — the original artifact
was a claude.ai settings prompt and nothing else. The dump is selective, not a
transcript: most conversations produce no dump, which is the correct answer. There's no
automatic sync — claude.ai can't reach your filesystem, so the paste step is real.

The copy-paste settings prompt, the dump format spec, and what happens after you paste
are in docs/claude-ai-companion.md.

Memory physics

The architecture is a deliberate mapping of how human memory actually works:

strength = avg(salience) + retrieval_bonus + consolidation_bonus
           − decayRate × √(active_days_since_creation) × register_multiplier

• Salience is scored at extraction on four dimensions: novelty, relevance, emotional, predictive.
• Retrieval strengthens (+0.12 per access, capped) — memories you use stay strong.
• Decay is power-law (Ebbinghaus/Wixted): fast at first, then flattening. Old stable memories are stable.
• Interference: when a new memory supersedes an old one, the old one's salience is dampened (×0.7) rather than deleted — belief updating without amnesia.
• Sacred verbatim: memories with emotional salience ≥ 0.75, and anything you protect, keep their exact words forever. Gist compression is for the mundane, not the tender.
• Nothing is ever destroyed. Pruning archives. Merging archives the sources. Gisting archives the originals. The data dir is a git repo with a commit per consolidation. Forgetting here means retrieval failure you can recover from, which is what it means in a brain too.

Privacy

Identity documents and episodes are deeply personal — treat them like a diary, because that's what they are. Everything lives locally in ~/.claude-engram/; nothing is sent anywhere except to the Anthropic/Voyage APIs that process it.

• Never commit ~/.claude-engram/ to a public repo. If you want the built-in git history backed up remotely, point it at a private remote.
• Memory content leaks easily into public surfaces you don't think of: commit messages, README screenshots, code comments, pasted logs. Screenshots of the dashboard render real memories.
• Extraction is instructed to keep secrets (API keys, credentials) out of memories, but review what's stored — recall and the dashboard make that easy.

Data layout

~/.claude-engram/
├── config.json              # everything below is optional overrides
├── env                      # API keys for hook processes
├── global/                  # cross-project world memories + embeddings + archive
├── projects/<hash>/         # per-project memories, buffer.md, briefing cache
├── identity/                # core.md, people/*.md, deltas.md (+ rotated backups)
├── episodes/                # first-person session narratives (markdown)
├── backups/                 # pre-consolidation snapshots
└── engram.log               # what fired and why

Everything load-bearing is plain text or JSON. The embedding index is derived and regenerable — reading glasses, not a second brain.

Configuration

All optional, in ~/.claude-engram/config.json. The interesting ones:

Costs

Hooks make zero API calls; everything expensive is detached and batched. A typical active day: a handful of Sonnet extraction calls (whole 32KB arcs, not per-turn), one nightly consolidation (Sonnet, plus Haiku for gist batches and Opus for the identity/briefing rewrites), and Voyage embedding calls measured in fractions of a cent. Even heavy days typically land well under a dollar — the expensive judgment happens a few times per day, not once per message.

Honest evaluation

Claims about memory systems are easy to inflate, so this repo keeps its receipts:

• AUDIT-WHAT-FIRES.md — a mechanism-by-mechanism audit of what actually fires in production, with evidence, including the mechanisms that didn't earn their keep.
• We benchmark against recall-bench but treat it as a regression tripwire on validated subscales only — never a steering target. Its own audit showed the headline number can't distinguish a real memory system from naive baselines (a plain re-read scores 90%), and we published that finding rather than the flattering one.
• The steering signal we actually trust: opening a fresh session and asking "what do you remember about X?" — judged by humans, across weeks.

Design history

The reasoning behind every mechanism is in DEVLOG.md (with a "Why (neuroscience)" section per feature) and DESIGN-RECENTER.md (the architecture rethink that produced the three stores). The project started as a single React artifact pasted into Claude.ai — a manual memory loop with no API key, no hooks, no filesystem. That version still works and still matters as the zero-dependency option: claude-engram.jsx, documented in docs/v1-artifact.md.

License

AGPL-3.0 — see LICENSE. For commercial licensing, contact Mike LaPeter.