The brain

brain.db: the event-sourced SQLite file that holds everything Kimetsu remembers, and how it migrates safely.

Everything kimetsu remembers lives in brain.db, a single SQLite file per project at <project>/.kimetsu/brain.db. A global user brain at ~/.kimetsu/brain.db holds memories that follow you across projects (disable with KIMETSU_USER_BRAIN=0 or [kimetsu] use_user_brain = false).

.kimetsu/ stays lean: just brain.db (plus WAL and migration backups) and project.toml. Transient working dirs live under ~/.kimetsu/cache/<project-hash>/, never in your tree.

The brain is event-sourced: the events table is the durable log, and a projector replays it into materialized tables the broker queries fast. kimetsu brain rebuild re-derives every projection from the log. The tables:

• runs: one row per agent run.
• events: every event ever written; the source for rebuild.
• memories: the durable knowledge, with scope, kind, text, confidence, use_count, usefulness_score, and last_useful_at.
• memory_proposals: pending suggestions awaiting review.
• memory_citations: which memories the model cited, in which run.
• memory_conflicts: ingest-time contradiction hits.
• repo_files*, repo_manifests*: file indexes from brain ingest repo.
• memories_fts: FTS5 index for lexical retrieval.
• memory_entities: tags and salient terms per memory, so the graph layer can find "what else mentions this" with an index lookup instead of a scan.
• memory_edges: typed relations between memories (relates_to, supersedes), written as each memory lands and traversed by the graph-lite backend.

Two clocks: what was true, and what we knew

Every memory carries two independent timelines:

• Valid time — when the fact was true in the world (valid_from / valid_to). Default retrieval filters on this: an expired memory is excluded.
• Transaction time — when the brain learned it (created_at) and when it retracted it (invalidated_at, or the loser's stamped valid_to).

Nothing is ever destroyed — supersession, invalidation and automatic contradiction resolution all stamp a tombstone rather than delete — so the brain can answer what it believed at any past moment:

kimetsu brain as-of 2026-03-01                      # the view then
kimetsu brain as-of 2026-06-01 --since 2026-03-01   # what changed between

This is the question that matters when a past decision looks wrong: it separates a bad call from missing information. A memory that has since been retracted still appears in a view from before its retraction, annotated with what became of it, and a memory merged into a survivor still counts as the live belief it was at the time.

Durable upgrades: schema migrations

brain.db carries a schema version, and a forward-only migration runner brings it up to the binary's target on every read-write open. Each migration runs in one transaction, so a crash leaves the DB cleanly stamped at an intermediate version, never half-applied. Before any migration the runner snapshots to a brain.db.bak-* sidecar (three newest kept). A read-only open of an un-migrated brain reports "needs migration" instead of failing.

The DB schema version is decoupled from the project.toml config version, so the database can evolve without rewriting every project's config file.

Memory kinds

Memory scopes