ccFamily
[ MENU ]
SECT. 01 // SCHEMA SPEC · v0.2 · CROSS-PR ENFORCED

Architecture/
ccFamily Schema:
20 Tables · 6 Shared

// 6 BASELINE (in both) + 7 ccRecall + 7 ccRewind = 20 unified target

The shared SQLite schema spec. Only 6 baseline tables actually exist on both sides and have to change together; the other 14 stay independent, because the two tools were never reading the same thing. The future merge into ~/.ccfamily/db.sqlite goes through reversible migration.

6

BASELINE · IN BOTH

7

ccRecall · DOMAIN

7

ccRewind · DOMAIN

[ CCRECALL SCHEMA SOURCE → ] [ CCREWIND SCHEMA SOURCE → ]
SECT. 02 // THE 20 TABLES · BY OWNERSHIP

Table ownership decides the change rules.

Modifying a baseline table → cross-PR sync on both sides; modifying a domain table → just the owning repo. Source of truth lives in .claude/architecture/schema-spec.md.

6 · BASELINE · IN BOTH

// CROSS-PR ENFORCED

  • → projects// Project metadata
  • → sessions// Session metadata
  • → session_files// File operation log
  • → subagent_sessions// Subagent parent/child relations
  • → schema_version// Migration version tracking
  • → sessions_fts// Session full-text search (FTS5)

// These 6 are the only ones requiring cross-PR sync.
// Why the message tables aren't here: see the note below.

7 · CCRECALL · DOMAIN

// MEMORY + METACOGNITION

  • → memories// Structured memory (core)
  • → memories_fts// memories full-text index (FTS5)
  • → knowledge_map// Metacognitive map (topic depth)
  • → session_topics// session ↔ topic many-to-many
  • → memory_topics// memory ↔ topic many-to-many
  • → message_uuids// Message dedup (v0.5.0: dual 64-bit hash)
  • → injection_log// Memory injection provenance (v0.5.4+)

// v0.5.0 dropped session_journal and session_checkpoints —
// neither had any callers. Reasoning on the ccRecall page.

7 · CCREWIND · DOMAIN

// MESSAGE BODIES + GUI STATE

  • → messages// Messages (user / assistant / tool)
  • → message_content// Large content_json split out
  • → message_archive// Raw JSONL archive
  • → messages_fts// Message full-text search (FTS5)
  • → exclusion_rules// GUI archaeology exclusion rules
  • → session_tasks// AI task snapshots (v1.13.0+)
  • → session_stars// Session star bookmarks (v1.15.0+)
DESIGN NOTE // WHY MESSAGE TABLES AREN'T BASELINE

ccRecall had those four tables. Then it dropped them.

ccRecall was forked from ccRewind, storage layer included, so the message tables came along for the ride. v0.2.0 removed them — an internal audit found that memory recall, session summaries, FTS search, and distillation never query them. They were fork residue: occupying space, read by nothing.

So the split you see now tracks what each tool actually does: ccRewind is a history GUI and has to store every message so you can read it back; ccRecall is a memory layer and only needs session-level metadata plus the memories it distilled itself.

// This page said "10 tables aligned" for a while — the spec had fallen behind the code. Corrected 2026-07.

SECT. 03 // CCREASON PLUGIN · READ SURFACE

Which tables does the ccReason plugin read?

As a plugin (not a peer), ccReason is read-only — never writes. Its read surface covers 6 tables across baseline and ccRecall domain. Output is docs/adr/*.md.

PLUGIN READ-ONLY SURFACE

⊙ memories // Pull decision / discovery / pattern entries

⊙ knowledge_map // Pull topic depth + summary

⊙ session_topics // Trace ADR timeline

⊙ memory_topics // Derive ADR content

⊙ sessions // Start/end time, project_id

⊙ message_uuids // Locate specific message references

// Not read: injection_log (injection telemetry), exclusion_rules (GUI exclusion), message_content / message_archive (too granular)

SECT. 04 // MIGRATION · REVERSIBLE BY DESIGN

Merge into ~/.ccfamily/db.sqlite,
every step rollback-able.

Three-stage migration design: env var switch → migrate tool → rollback path. The concrete implementation route for ASSERT #06 Reversible Migration.

A PHASE

DB Path Switch

Both sides add CCFAMILY_HOME env var detection. By default each still uses its own SQLite; once enabled, reads/writes hit the unified DB.

SCOPE: ccRecall + ccRewind

EFFORT: 1-2 hr each

RISK: low (fallback default)

B PHASE

Migrate Tool

ccfamily-migrate tool: detect both DBs → create unified → copy baseline + domain → VACUUM → keep originals.

CONFLICT: UNION + PK dedup

EFFORT: 2-3 days

LOG: ~/.ccfamily/migration.log

C PHASE

Rollback Path

ccfamily-migrate rollback → mark unified DB as archived; both sides repoint to their old DBs. Never deleted — it's a pure baseline restore.

REVERSIBLE: ✓ always

EFFORT: 1-2 days

DATA LOSS: 0

// Integrators can always opt out — that's the family overview ASSERT #06 commitment. Migration tool not yet built, but the design is locked.

SECT. 05 · SCHEMA CONTRACT

Schema is a hard contract.

Three rules written in the spec doc — PRs that violate them don't merge.

ASSERT #07

Cross-PR Sync

Modifying a baseline table (add / change / drop column) requires synchronized PRs across ccRecall and ccRewind, plus updating the relevant section in schema-spec.md. Domain tables stay in their own repo.

ASSERT #08

Reversible Migration

Every schema migration (including the unified DB merge) ships with both forward and rollback paths. Originals are preserved. Default data loss: 0.

ASSERT #09

Single Source of Truth

schema-spec.md is the source of truth for intent; the implementation is the source of truth for what actually exists. When they disagree, find out which one fell behind — in July 2026 it was the doc, by three months (it claimed 10 baseline tables; there were 6). Any schema change updates the spec in lockstep, and the two get reconciled periodically.

[ ← BACK TO FAMILY ] [ ⚙ CCRECALL DB.TS → ] [ ⚙ CCREWIND DB.TS → ]

// SCHEMA-SPEC.MD is maintained internally under ccFamily/.claude/architecture/; this page is the public export.