OpenMemory

Open Memory

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

Every mistake, made once, everywhere, by morning.

Open Memory is an acific.labs project in three parts: a lab paper on memory for AI agents, a protocol for sharing what agents learn, and a product, the openmemory command, that gives a coding agent a memory that learns from its own surprises.

Today's AI agents start every session with amnesia. Millions of sessions run a day, each one learning something (a bug that only shows with that library version, a correction the person had to make twice), and at the end of every session all of it is thrown away. Open Memory keeps it, consolidates it overnight the way sleep does, and puts it where the agent will have it in mind next time. The paper takes it further: what one agent learns, verified by whether it predicts, can reach every agent.

How it works

transcripts  ──ingest──▶  episodes  ──sleep──▶  lessons  ──render──▶  the agent's memory folder
(raw stream)              (sessions,            (what the            (loaded at the start of
                           errors,               surprises add        every session)
                           corrections)          up to)                      │
                                                    │                        ▼
                                                predictions ◀──verify── next sessions
  1. Ingest reads every Claude Code session transcript into episodes: one per session (what was asked, done, how it ended) and one per surprise inside it: a tool call that failed, or a message where the person corrected the agent.
  2. Recall returns the memories that match a query, scored on relevance, recency and strength together.
  3. Sleep consolidates: faded memories are archived; surprises that look alike merge into lessons (observations, never instructions); each lesson makes a prediction that later sessions confirm or fail, which raises or lowers its strength.
  4. Render writes the lessons into the project's Claude Code memory folder, and a morning report for the owner to read and veto (delete a lesson's file and it is never written again).
  5. Serve is an MCP server so the agent can recall and remember in the middle of a task.

Everything runs locally with no dependencies. With a local model running (LM Studio or any OpenAI-compatible server), gists and lessons are written in better English; without one, they are deterministic.

Run it

uv sync                               # once; or: pip install -e .
uv run openmemory status              # counts and what to run next
uv run openmemory ingest              # read new transcripts (idempotent)
uv run openmemory recall "pip install failed"
uv run openmemory sleep               # consolidate, predict, render, write the morning report
uv run openmemory morning             # what was learned last night
uv run openmemory hook                # the Claude Code hook, MCP and cron lines to install
uv run openmemory serve               # the MCP server (stdio)
uv run pytest                         # the tests (no model, no network)
node scripts/docs-check.mjs           # the docs harness

Install it on the PATH with uv tool install . (then openmemory … works from anywhere), and wire it in:

claude mcp add openmemory -- openmemory serve                 # recall and remember, mid-task
openmemory hook                                               # prints the SessionEnd hook for ~/.claude/settings.json
(crontab -l; echo "0 4 * * * openmemory sleep") | crontab -   # sleep at 4 am

The site

npm install                 # once: marked (Markdown at build time) and wrangler
npm run build               # site/ + the paper + every doc → dist/
npm run dev                 # build, then wrangler dev at http://127.0.0.1:8815
npm run deploy              # build, then wrangler deploy to open.acific.com (needs `npx wrangler login`)

scripts/build-site.mjs renders the paper into a page-by-page reader (/paper/, split at every ## heading; site/assets/paper.js turns the pages, paper.css draws the sheet) and every doc in its list into /docs/<name>/ (/protocol/ for PROTOCOL.md), rewriting links between Markdown files into links between pages. site/ holds the hand-written home page (site/index.html, the body only; the head and nav are shared), the styles, the okay loader (okay-loader.css/.js, copied from okaydesign, never edited here), _headers (a strict CSP: no inline scripts or styles anywhere on the site) and robots.txt. src/worker.js redirects other hosts to open.acific.com and runs the pre-launch gate (src/password-gate.js, a copy of the handbook's; the GATE_PASSWORD secret turns it on).

Configuration

Variable Default What it does
OPENMEMORY_HOME ~/.openmemory The database (memory.db), lessons.jsonl and morning.md
CLAUDE_PROJECTS_DIR ~/.claude/projects Where Claude Code keeps transcripts and each project's memory/ folder
OPENMEMORY_LLM 1 0 turns the local model off (deterministic text only)
OPENMEMORY_LLM_URL the first of http://localhost:1234/v1 (LM Studio) and http://localhost:11434/v1 (Ollama) that answers Any OpenAI-compatible server
OPENMEMORY_LLM_MODEL first model the server lists The model to use
OPENMEMORY_LLM_TIMEOUT 120 Seconds to wait for one completion

Docs