Adding memory to Muse Code

one command for the MCP server, the hooks and the skill

Muse Code keeps every session on disk and opens the next one empty. What you worked out last week is still there, and so is the work you did in whichever other agent you had open at the time.

What Muse Code already has

Sessions live under ${XDG_DATA_HOME:-~/.local/share}/muse/sessions/YYYY/MM/DD/<id>/, one directory per session under the day it started, with the transcript in session.jsonl — the same home-relative path on macOS, Linux and Windows. DEJA_MUSE_ROOTS, a path list, replaces the roots deja reads. muse resume <id> reopens one. Complete, and unread by anything — including by Muse's next session.

A subagent's run sits inside its parent at <id>/subagent/<child>/session.jsonl. deja reads it as its task, its edits and its last turns; DEJA_INCLUDE_SUBAGENTS=1 indexes the whole run, and =0 skips subagents. The rest of the session directory — cron.db, goals.db and the tool-outputs/ spill directory — is not a transcript, so deja skips it and deja doctor does not count it as unread.

Adding recall

deja install muse-auto

That needs the binary:

brew install deja-vu
# or
curl -fsSL https://raw.githubusercontent.com/vshulcz/deja-vu/main/install.sh | sh

Without hooks, deja install muse writes only the MCP server and the skill, and the agent searches when it decides to.

What gets wired

Both commands write into ${XDG_CONFIG_HOME:-~/.config}/muse/settings.json, next to whatever else is in it. deja install muse adds one MCP server named deja, which the model sees under Muse's mcp__deja namespace. Muse also still reads an older mcp_servers key, but with both keys in the file it loads no MCP server at all, so deja writes into whichever key the file already has and refuses a file that has both.

deja install muse-auto adds these hooks in Claude Code's format:

  • The project digest on SessionStart: what this project's past sessions settled, before you type anything.
  • Recall on UserPromptSubmit, silent when the history has no answer.
  • A line about the file on PreToolUse before a bash, edit_file or write_file, and the repair for a failed command on PostToolUse and PostToolUseFailure after bash.
  • Compaction recovery on PreCompact: Muse compacts in the middle of a turn, so the task comes back on the next tool call or prompt.
  • SessionEnd, so the session you just quit is one the next session's recall can answer.

The deja-history skill goes into ~/.agents/skills, the shared directory Muse reads user skills from, and Muse lists it in its slash menu: /deja-history <query> runs it with the query.

deja resume <id> prints muse resume <id> from the session's workspace, since Muse takes the directory it runs in as the workspace. A subagent cannot be resumed on its own, so deja points you to its parent's id instead.

The part that is not about this harness

The index covers every agent's transcripts on the machine — forty-three of them today, each in its own format — so a fix found in one tool answers a question asked in another, including sessions from before any of this was installed. That is the reason to index rather than to capture.

Nothing here writes memories, so there is nothing to hallucinate into your history; indexing and search are local, and credentials are stripped as the index is built (privacy). What memory costs has the measured comparison.

Getting started · How Muse Code's store is read · Resuming a session

Found this useful? Star deja-vu on GitHub.