Remem by Acific Labs

Migrations

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

A memory is the one thing a release must never lose. These are the rules a release follows so an existing ~/.remem (~/.openmemory before 0.9.0) and the rendered files keep working, after the handbook's migration standard.

What a release may touch

Thing Rule
memory.db schema Append-only and expand-only: CREATE TABLE IF NOT EXISTS and ALTER TABLE … ADD COLUMN with defaults. A column is never dropped or renamed in the release that stops using it.
Embeddings A change to embed.py (dimension, tokenization) makes every stored vector incomparable with new ones. Such a release re-embeds every row on first run (title + gist for episodes, text for lessons and predictions) and records the embedding version in the row. Not yet needed: 0.1.0 is the first.
Scoring and thresholds Free to change; they affect ranking, not data. The paper's Appendix A changes with them.
Rendered files The remem-<id>.md frontmatter may gain keys. The remem:start/end markers never change (0.9.0 renamed both once, from om-<id>.md and openmemory:start/end, taking the old ones over); written.json and vetoed.json keep their shape (a JSON list of ids).
lessons.jsonl Fields may be added; never removed or renamed. Readers ignore unknown fields. This is the protocol's compatibility rule (PROTOCOL.md).
The CLI Commands and flags are added, not removed; a removed one keeps working one release with a notice.
Hooks and MCP The hook command (openmemory ingest --quiet) and the tool names (recall, remember) and their arguments stay; new arguments are optional.

How a breaking change is done

Expand → backfill → switch → contract, over at least two releases: add the new column or file alongside the old, fill it on first run (idempotent, resumable: a row is skipped when already filled), switch the code to read the new one, and only in a later release stop writing the old one.

Every release

History

Release Migration
0.1.0 None: the first store.
0.9.0 The rename: Open Memory is Remem. Nothing is lost and nothing needs doing by hand beyond reinstalling. The store: the first remem command moves ~/.openmemory to ~/.remem and leaves a link at the old place (only for the default folder; a store placed with REMEM_HOME or the old OPENMEMORY_HOME stays where it is). Settings: every OPENMEMORY_… variable is still read, as its REMEM_… twin, when the new name is not set. Rendered files: the next render renames each om-<id>.md marked managed: openmemory to remem-<id>.md and replaces the section between the old openmemory:start/end markers with one between remem:start/end; vetoes hold (written.json and vetoed.json list ids, not file names). Agents: remem setup rewrites hooks that call openmemory, renames the MCP server in every agent's config and the crontab line; until then the openmemory command still exists as a second name for remem, so old hooks keep working. The proxy still honours x-openmemory: off. Unchanged on purpose: the holdout salt in prime.py, so the same sessions stay held out. On each machine: git pull && uv tool install --reinstall -q . && remem setup.
0.8.1 None.
0.8.0 None in the store. The next sleep (or any render) removes om-delegation.md from each memory folder and the delegation line from other agents' instruction files: agents no longer see the tally (paper §7.4). Experiments are now kept in ~/.openmemory/experiments; copy older --out files there (named behaviour-<date>-<model>.json, with "kind": "behaviour") for openmemory goals to count them.
0.7.0 None in the store. The proxy no longer puts the whole memory in every system prompt by default; set OPENMEMORY_PROXY_MEMORY=first for 0.6's behaviour.
0.6.3 None. openmemory ingest --again records "Agent deferred" in older corrections' context.
0.6.2 None.
0.6.1 None. Reinstall (uv tool install --reinstall -q .): 0.3.0 to 0.6.0 installed as "0.2.3".
0.6.0 Automatic: the origin becomes the SHA-256 fingerprint of the same key (the previous id kept in origin.legacy; local lessons restamped). Every memory sharing a folder or the commons upgrades together. To join the commons, copy ~/.openmemory/commons-token from a machine that has it, then openmemory share sync https://remem.acific.com/commons/.
0.5.0 Automatic: the first share or sleep makes ~/.openmemory/key and replaces the random origin id with the key's fingerprint (the old id is kept in origin.legacy, and local lessons are restamped). Unsigned 0.4.0 records are refused: every memory sharing a folder upgrades together. Back up ~/.openmemory/key: it is this memory's identity.
0.4.0 Automatic: lesson columns origin, hash and origins are added on open, and the next sleep stamps every local lesson with its hash and this memory's origin (~/.openmemory/origin, created once). Nothing is shared until openmemory share is run or OPENMEMORY_SHARE_DIR is set.
0.3.0 None; no schema change. Run openmemory setup to wire the new hooks and every other agent. Episodes from events have ids starting ev; sessions from chats, ids starting chat:.
0.2.3 Automatic: a sessions.offers column is added on open. Run openmemory ingest --again once to fill it for transcripts read before.
0.2.2 None; no schema change. Run openmemory ingest --again once so older corrections gain their "Agent handed back" line; the next sleep writes om-delegation.md.
0.2.1 None; no schema change. ingest --again drops correction episodes that came from compaction summaries. Add the Stop and PreToolUse hooks to use the new moments (openmemory hook).
0.2.0 Automatic. A new aliases table is created on open. The first sleep with an embedding model embeds every episode, lesson and open prediction again in the model's space (reembedded in the morning report) and may merge lessons into themes; a merged lesson's file is removed from the memory folder and its veto carries over. Back up first if the lessons matter (cp ~/.openmemory/memory.db ~/.openmemory/memory.db.before-0.2.0). With no model, nothing changes. OPENMEMORY_EMBED=hash keeps hashed words.
0.1.4 None required; no schema change. Episode ids become stable hashes: the first ingest --again replaces each transcript's episodes, carrying strength, recalls and touches over, and renames the old random ids inside every lesson's sources (matched on kind and title). New kinds surprise and environment are plain values of kind. sleep --rewrite re-words existing lessons.