User guide

Last verified against the code: 2026-10-21 (first commit)

Open Memory 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/openmemory ~/Strange/openmemory
cd ~/Strange/openmemory && uv tool install .      # `openmemory` is now on your PATH
openmemory status                                 # says what to run next

Then wire it into Claude Code (openmemory hook prints all three):

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

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

2. Let the agent recall mid-task: claude mcp add openmemory -- openmemory serve
3. Sleep every night: (crontab -l; echo "0 4 * * * openmemory sleep") | crontab -

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 ("no, use uv"), with what the agent had just said.
• A note: something the agent chose to remember through the MCP tool.

Errors and corrections are surprises. Surprises that repeat become lessons. A lesson is always an observation about what has happened, never a rule: "The user corrected the agent for installing with pip; this project uses uv." The agent reads it at the start of the next session and decides what to do with it.

The morning report

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

# Open Memory: 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.

Vetoing a lesson

Every lesson is a file in the project's memory folder (openmemory paths shows it; the files are named om-<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 openmemory recall can still find them.

The agent's tools

With the MCP server added, Claude Code has two tools:

• recall(query, k): memories matching the query. The agent is told to use it before repeating something risky.
• remember(text, cwd): save one observation for future sessions.

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. openmemory status shows which model it found. Set OPENMEMORY_LLM_URL and OPENMEMORY_LLM_MODEL if the server is elsewhere (OPERATIONS.md).

FAQ

Does anything leave my machine? No. Everything is in ~/.openmemory 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 om-*.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 ~/.openmemory and the om-*.md files; run openmemory ingest again.

Troubleshooting