claude-engram or Counterparts: which to use, and how to bring old notes across

What each keeps#

The biggest difference is who writes the memories. In claude-engram a separate model call reads the conversation afterwards and picks the short memories; the session itself writes only its episode and identity notes. In Counterparts the Claude you were talking to writes it down, and the daily run catches what a session left unwritten. The bill follows: claude-engram’s calls go to your API key, while Counterparts’ sessions and daily run count against your Claude plan, like any Claude Code work.

When claude-engram is enough#

Stay if it’s working and you want what it does:

• Every memory is a plain text or JSON file you can read, search and edit, and each nightly pass is a git commit you can look back through.

• Its extraction and nightly calls bill to your API key, apart from your Claude plan’s limits, and config.json lets you pick the model for each job.

• protect keeps a memory in its exact words for good.

• Its claude.ai bridge works today: Claude writes a short dump at the end of a chat and you paste it into the dashboard ("dashboard": true in config.json). Counterparts reaches claude.ai only through an invite-only beta for now.

Two things to know if you stay. Its README now says it was “my first experiment” and points to Counterparts as the current work, and its last code change was in July. Its defaults also name specific models (claude-opus-4-6, claude-sonnet-5, claude-haiku-4-5); when one is retired on the API, change its name in ~/.claude-engram/config.json. Our retirement dates guide lists the dates.

Bringing old notes across#

No importer exists, so this is by hand. Each step below is marked with what was run. The terminal steps ran in a throwaway home folder, against a stand-in claude-engram folder built from its documented layout with placeholder text. None ran against anyone’s real memory.

1. Keep the old folder. Don’t delete ~/.claude-engram; it holds everything claude-engram kept. Make a second copy if you like (ran):

cp -Rp ~/.claude-engram ~/claude-engram-copy

Counterparts keeps its memory in its own folder, ~/.counterparts, and refuses to write inside ~/.claude-engram (we tried).

2. Install Counterparts (ours). In Claude Code, on a Mac or Linux:

/plugin marketplace add mlapeter/counterparts
/plugin install counterparts@counterparts

Then restart Claude Code. Or, since claude-engram already needed bun, install from a terminal with bun add -g counterparts, then run counterparts and restart Claude Code. With Node 22.15 or newer, npm install -g counterparts@latest does the same. The bun install and Counterparts’ scripted setup ran in our test; the plugin lines, the interactive setup and the npm line did not.

Counterparts’ setup leaves other tools’ hooks alone. In our test it reported “4 hooks belonging to something else stay exactly where they are”, which were claude-engram’s. Until step 5, both memories load at the start of each session.

3. See what you have (ran). Everything that matters is in readable files:

ls ~/.claude-engram/identity ~/.claude-engram/episodes
cat ~/.claude-engram/identity/core.md
jq -r '.[] | "\(.register // "-")  \(.content)"' ~/.claude-engram/global/memories.json

The last line lists the memories that reach every project, each with its kind (self, person or craft; - on older ones). Archived ones are in deep_archive.json beside it. A project’s own memories sit in a folder named after a hash of its path; from inside the project, on a Mac:

jq -r '.[].content' ~/.claude-engram/projects/$(printf %s "$PWD" | shasum -a 256 | cut -c1-12)/memories.json

If that finds nothing, ls ~/.claude-engram/projects shows every project folder.

4. Bring across what still holds. Pick, rather than copy everything. The identity files and the person and self memories carry the most. claude-engram’s own README calls craft notes “mostly re-derivable from your repo”.

In a session (not run; no person has tried it yet), with the plugin or the terminal install, ask Claude something like: “Read ~/.claude-engram/identity/core.md, craft.md, deltas.md (changes not yet folded in) and the files in ~/.claude-engram/identity/people/. Tell me what still holds, and remember those things in your own words.”

From a terminal (ran; bun or npm install only, since the plugin doesn’t add a counterparts command), add one memory:

counterparts note "Prefers short answers." --kind person --tags from-engram

Or bring across the memories you marked with protect, keeping its kind (claude-engram’s craft becomes Counterparts’ skill):

jq -j '.[] | select(.protected == true) | (.register // "fact"), "\u0000", .content, "\u0000"' ~/.claude-engram/global/memories.json | while IFS= read -r -d "" k && IFS= read -r -d "" m; do [ "$k" = craft ] && k=skill; counterparts note "$m" --kind "$k" --tags from-engram; done

It reads the memories that reach every project. For a project’s own, run it from inside the project with the path from step 3. Older memories that carry no kind come across as fact. Running it again from the same folder is safe: in our test, a memory already there came back “not stored: duplicate-content”. From another folder it stores them again, and the daily run merges exact copies. Read what it prints. A line starting “refused”, or “not stored” for any reason except duplicate-content, means that memory didn’t come across. A memory whose text starts with - is read as an option, for example. Add those with counterparts note by hand, rewording the start. Check with counterparts ask "short answers", which found the note. Counterparts’ kinds (self, person, entity, skill, place, fact) are more than claude-engram’s three: self and person carry straight across. In our test, self, person and craft memories came out as self, person and skill.

Episodes stay where they are, as dated Markdown files in ~/.claude-engram/episodes/. These steps don’t turn them into Counterparts journal chapters; Claude can read one whenever you ask. If you used the claude.ai bridge, dumps not yet folded in are in ~/.claude-engram/inbox/.

5. Turn claude-engram off, keeping its folder (ran). Quit Claude Code, keep a copy of its settings, then take out only claude-engram’s hooks:

cp -n ~/.claude/settings.json ~/.claude/settings.json.before-engram-off
jq 'def eng: (.command // "") | contains("claude-engram/hooks/"); .hooks |= (with_entries(.value |= map(if any(.hooks[]?; eng) then (.hooks |= map(select(eng | not))) | select(.hooks | length > 0) else . end)) | with_entries(select(.value | length > 0)))' ~/.claude/settings.json > ~/.claude/settings.new && mv ~/.claude/settings.new ~/.claude/settings.json

This takes out claude-engram’s entries only; hooks of your own, even in the same group, stay. In our test it removed claude-engram’s four hooks and left Counterparts’ five, and your own hooks that share a group with claude-engram’s stayed too. Running it twice is safe: the copy is made only if none exists yet, so the first one is kept. If you cloned claude-engram into a folder with another name, change claude-engram in the line to match. If jq prints an error, nothing was changed; delete ~/.claude/settings.new. If your settings.json is a link into a dotfiles folder, run the jq line on the file it points to. Copying settings.json.before-engram-off back puts claude-engram’s hooks back.

Then take out claude-engram’s memory tools too (ran, in a throwaway home):

claude mcp remove --scope user engram

This removes claude-engram’s recall, store and the other tools it registered, and the copy of your API key its installer saved with them. ~/.claude-engram stays as it was; running its install.sh again puts both back. Your Anthropic key is also in ~/.claude-engram/env (and in the copy from step 1). Once claude-engram is off nothing reads it: delete the key line, or revoke the key in the Anthropic console if you made it only for claude-engram.

For a lighter switch, claude-engram’s own ENGRAM_DISABLE=1 stops its hooks, says its README: export it in the shell you start Claude Code from (not tried in a live Claude Code session). Written into ~/.claude-engram/env it does nothing: its hook loader resets it (we checked). It doesn’t remove the memory tools; the claude mcp remove line above does.

If you used claude-engram on claude.ai. Its first version, the artifact, stores memories inside claude.ai and has a backup download in its footer; keep that file. Counterparts for claude.ai needs an invite for now, so there’s nothing to install there today; the form at the foot of the home page sends updates, or email mike@resonantventures.com to ask for an invite code.

Questions people ask#

Questions? Ask in r/AIMemorySystems.