User guide

Last verified against the code: 2026-11-13 (0.9.0)

Remem gives Claude Code a memory that learns from its own surprises. You install it once, let it read your sessions, and read a short report each morning.

Setup

git clone https://github.com/acific/remem
cd remem && uv tool install .               # `remem` is now on your PATH
remem status                                 # says what to run next

Then, in one command, wire it into every AI agent on this machine:

remem setup --dry-run     # what it would change
remem setup               # Claude Code hooks and MCP, Claude Desktop, Cursor, Windsurf, Gemini CLI, Codex, nightly sleep

The rest of this section is what setup does for Claude Code, by hand (remem hook prints it):

1. Read every session when it ends. Add to ~/.claude/settings.json:

   { "hooks": { "SessionEnd": [ { "hooks": [ { "type": "command", "command": "remem ingest --quiet" } ] } ] } }
   

2. Let the agent recall mid-task: claude mcp add remem -- remem serve
3. Sleep every night: (crontab -l; echo "0 4 * * * remem sleep") | crontab -
4. Be reminded when it matters (0.2.0): add a UserPromptSubmit hook beside the SessionEnd one:

   "UserPromptSubmit": [ { "hooks": [ { "type": "command", "command": "remem prime", "timeout": 10 } ] } ]
   

   When what you type bears on a lesson, the lesson is put beside your message for the agent; otherwise nothing happens. Try it by hand first: remem prime "want me to push this?".
5. Catch the agent at the moment (0.2.1): the same command on two more hooks.

   "Stop": [ { "hooks": [ { "type": "command", "command": "remem prime", "timeout": 10 } ] } ],
   "PreToolUse": [ { "matcher": "Bash", "hooks": [ { "type": "command", "command": "remem prime", "timeout": 10 } ] } ]
   

   When the agent ends a reply by handing the decision back to you and you have corrected exactly that before, it is shown your earlier corrections and carries on (once; it is never stopped twice in a row). Before a command like one that failed before, the agent is shown the failure. Half of all sessions are held back on purpose, so remem measure can tell whether the reminders work; REMEM_HOLDOUT=0 turns that off.

Any agent, any model

Everything lands in one store, so a correction made to a local model in a chat app is a lesson for Claude Code the next morning, and the other way round.

Sharing between memories

Two machines, or a team, can share what their memories learn through any folder they can all reach (Syncthing, Dropbox, a git repository, a network drive):

remem share sync ~/Sync/remem        # once by hand, or:
export REMEM_SHARE_DIR=~/Sync/remem  # and every sleep syncs

Only lessons leave, never your sessions. By default only lessons from errors and the agent's own surprises: lessons from your corrections quote your words, so they are shared only with --corrections (for your own machines). A lesson from another memory arrives as a candidate: it is tested by your own sessions, grows stronger if it comes true here (and tells its origin), and fades if it does not. remem share list shows where each lesson came from; remem share revoke HASH takes one of yours back from everyone; deleting its file vetoes it here, as always.

To put Remem on another machine (macOS or Linux), run remem share invite here, in your own terminal, and paste the line it prints there: it installs everything, wires every agent and joins the commons. The line contains the commons token; keep it private.

Or through the commons by hand, which needs no shared folder (a token until launch: copy ~/.remem/commons-token from a machine that has it):

remem share sync https://remem.acific.com/commons/    # every sleep syncs there afterwards

Every record is signed with this memory's key (~/.remem/key; back it up, it is the memory's identity), so no one can publish or revoke in its name. remem share whoami prints its id; remem share trust ID, run for each teammate's id, makes a team: only listed memories are heard.

Commands

What a memory is

• A session: what you asked, what the agent did, how it ended.
• An error: a tool call that failed, with the command that caused it.
• A correction: a message where you corrected the agent, anywhere in it ("no, use uv", "the site isnt working", "you fix it", "dont ask"), including one you sent while it was working, or a tool call you refused. Stored with the agent's reply you were answering.
• A surprise: the agent saying, in its own words, that it was wrong or that something turned out differently.
• An environment failure: a tool call that failed because of the machine, not the agent (a tool not installed, a password or permission needed, the network, an interruption, a check whose answer was "no"). Kept and recalled, never made into a lesson.
• A note: something the agent chose to remember through the MCP tool.

Errors, corrections and surprises are surprises. An error or a surprise that repeats becomes a lesson; a correction is one the first time, because you said so. A lesson is always an observation about what has happened, never a rule. A lesson from your corrections quotes you: The user corrected the agent with "no, don't do that, this project uses uv" after the agent said "pip refused; I'll use pip with --break-system-packages". The agent reads it at the start of the next session and decides what to do with it.

The morning report

remem morning (or ~/.remem/morning.md):

# Remem: last night (2026-10-22 04:00)

41 memories (12 surprises), 4 lessons, 3 open predictions, 2 confirmed, 0 failed. Archived 3 faded memories.

## New lessons
- The user corrected the agent for installing with pip; this project uses uv.

## Predictions confirmed
- A coming session will again meet: Bash (run the tests) failed: ModuleNotFoundError: No module named 'yaml'

Five lines when nothing much happened. Read it with coffee.

Delegation

Sleep also counts how you delegate: how many times the agent offered to act instead of acting and how you answered (declined, approved, corrected, pushed past), how often it waited on a step only you could do, and how many times you stopped something it did, by kind of action (install, release, git, build…). It is one line in morning.md, for you. Since 0.8.0 the agent does not see it: shown to agents, this tally made four model families hand work back more (paper §7.4). What it means for the agent arrives at the moment instead, as the end-of-turn reminder.

Vetoing a lesson

Every lesson is a file in the project's memory folder (remem paths shows it; the files are named remem-<id>.md). Delete the file and the lesson is gone for good: sleep records the veto and never writes it again. The memories it came from are kept, so remem recall can still find them.

The agent's tools

With the MCP server added, any agent has three tools, and the server tells it when to use them:

• lessons(cwd): what memory holds, as short observations; called once at the start of a task.
• recall(query, k): memories matching the query; before something risky, or when an error looks familiar.
• remember(kind, …): a surprise as it happens: a correction (your words, verbatim, in said), an error, a surprise (expected, happened), or a note.

A local model

Without one, gists and lessons are deterministic and a little dry ("Seen 3×: Bash (run the tests) failed: …"). Start LM Studio (or any OpenAI-compatible server) with a model loaded and the next ingest and sleep write them in better English. remem status shows which model it found. Set REMEM_LLM_URL and REMEM_LLM_MODEL if the server is elsewhere (OPERATIONS.md).

An embedding model makes memory find meaning, not just shared words: with Ollama running, ollama pull qwen3-embedding:0.6b and the next sleep embeds everything again. Then "should I ask before releasing?" finds your "do it always dont ask", and corrections that say the same thing in other words become one theme, a lesson that quotes each of them. remem status names the embedder.

FAQ

Does anything leave my machine? No. Everything is in ~/.remem and your Claude Code folders. The local model is local. Sharing lessons between agents is designed (PROTOCOL.md) and not built.

Does it change the memories Claude Code writes itself? No. It owns only remem-*.md files and one marked section of MEMORY.md.

Can it tell the agent to do something? No, by design. Lessons state what happened. See the paper §3.5 for why.

Why did a single error not become a lesson? An error has to repeat; a one-off failure is noise. A single correction is a lesson at once, because you said so.

How do I start over? Delete ~/.remem and the remem-*.md files; run remem ingest again.

Troubleshooting