Architecture

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

One Python package, one SQLite file, five stages. No service, no server, no dependencies.

 ~/.claude/projects/<project>/*.jsonl            the raw stream (Claude Code transcripts)
            │
            ▼  remem ingest          transcripts.py → ingest.py
 ┌─────────────────────────────┐
 │  ~/.remem/memory.db    │  episodes (session / error / correction / surprise / environment / note), sessions,
 │                             │  lessons, predictions            store.py, embed.py
 └─────────────────────────────┘
      │              │
      │ recall       │ sleep (nightly)      sleep.py: decay → lessons → verify → predict
      ▼              ▼
  recall.py      render.py ──▶ ~/.claude/projects/<project>/memory/   om-<id>.md + a section of MEMORY.md
  (CLI, MCP)                ──▶ ~/.remem/lessons.jsonl           the wire format
                            ──▶ ~/.remem/morning.md              the owner's report

Components

The store

Five tables in memory.db (SCHEMA in store.py):

Timestamps are ISO 8601 UTC with microseconds, so "created after this prediction was made" is unambiguous.

Data flow in detail

1. Ingest lists every top-level *.jsonl under every project folder (subagent transcripts in subfolders are skipped). For each file whose mtime is new, parse() builds turns: user text (meta lines and slash-command records stripped), assistant text and tool calls merged across the streamed records of one turn, and tool results attached to the assistant turn that made the call. episodes_of() yields one session episode and one per surprise. Each episode's embedding is of its title and gist, except a correction's, which is of the person's words alone; one batch per transcript.
2. Recall scores every unarchived episode and every lesson: 0.6·cosine + 0.25·2^(−age/30d) + 0.15·min(strength,2)/2, returns the top k, and touches the episodes it returned (+0.1 strength, +1 recall).
3. Sleep first embeds again whatever is not in the current space, then runs decay (strength × 2^(−days since last touch / 45); below 0.15 → archived), consolidation (surprises join the lesson whose sources they resemble, by mean cosine ≥ 0.62 in a model's space or 0.55 hashed, or cluster into a new one; one correction suffices, an error or a stated surprise must repeat; environment episodes are never consolidated), merging (lessons of one kind whose sources mean the same thing, by average linkage, become one theme; the others become aliases), verification (open predictions matched against episodes of the lesson's kind that happened since, cosine ≥ 0.5 hashed or the same-surprise cut; failed after 14 days), prediction (one per lesson with strength ≥ 1 and no open prediction).
4. Render writes one remem-<id>.md per lesson into each project's memory folder (lessons with no cwd go everywhere) and rewrites only the section of MEMORY.md between the markers. written.json records what was written; a lesson whose file is missing on the next render is added to vetoed.json.

Where it runs

On the person's machine only. The CLI runs on demand; sleep is meant for cron; serve is started by the agent (Claude Code) as an MCP server; ingest --quiet is meant for the agent's SessionEnd hook. See OPERATIONS.md.

What is designed but not built

The commons (sharing lessons between agents under verification), compiled memory (lessons as a model's attention state) and the raw stream beyond the terminal are described in the paper §5, §6 and §3.2, the protocol in PROTOCOL.md, and the order of work in ROADMAP.md.