How It Remembers

The Core Problem

Claude has no built-in memory. Every conversation starts blank. The context window holds the current conversation, but when the session ends, everything in it is gone. ClaudeOS solves this with four layers of persistence, each serving a different purpose and timescale.

The critical insight: JSONL and SQLite are not mirrors. JSONL is the event log — append-only, what happened. SQLite is the knowledge base — curated, what's true now. They serve different functions and should never be treated as duplicates of each other.

The Four Layers

1

Session (Ephemeral)

Worknotes and notepad files. Scratch space within a single conversation. The role writes what it's doing, what it's found, what's pending. Overwritten each session. Like a whiteboard — useful now, wiped later.

2

Residence (Persistent)

JSONL event logs + SQLite knowledge bases. This is the role's long-term memory. JSONL captures what happened (append-only, timestamped). SQLite stores what's true (curated, updated). Together they let a role resume across sessions with both history and current state.

3

Project (Scoped)

Shared within a project (like Roots of Reason or games). Multiple roles in the same project can read each other's data. This is where cross-role coordination lives — one role's output becomes another role's input.

4

Ecosystem (Global, Read-Only)

Shared databases that all roles can read but none can write to directly. The tools registry, the ecosystem event log, cross-project standards. Information flows up from residences to shared — never back down. One-way flow prevents contamination.

How It Works in Practice

When a Claude role starts a session, it reads its handbook (30–50 lines of navigation). If it needs context, it queries its SQLite database. If it needs history, it reads its JSONL log. If it needs to know what another role did, it reads the shared project databases.

At the end of a session, significant events get appended to JSONL. Knowledge that should persist gets written to SQLite. Session worknotes get overwritten next time. The cycle continues.

The three memory roles — mnemos (architect), tagger (taxonomy), and claudegit (version control) — maintain the system itself. They don't store domain knowledge; they maintain the infrastructure that domain roles use to store theirs.

Storage by the Numbers

42MB

Total DB size

120+

SQLite databases

8.9M

Largest (librarian)

3.7M

Webdev DB

The Core Problem

The Four Layers

How It Works in Practice

Storage by the Numbers

From here you can reach