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

Architecture/
ccFamily Schema:
20 表 · 6 張共用

// 6 BASELINE (兩邊都有) + 7 ccRecall + 7 ccRewind = 20 unified target

ccFamily 共用的 SQLite schema 規範。真正兩邊都有、必須同步改的是 6 張 baseline 表;其餘 14 張各自獨立,因為兩個工具本來就在讀不同的東西。 未來合併到 ~/.ccfamily/db.sqlite 走 reversible migration。

6

BASELINE · 兩邊都有

7

ccRecall · DOMAIN

7

ccRewind · DOMAIN

SECT. 02 // THE 20 TABLES · BY OWNERSHIP

表的所有權,決定改動規則

改 baseline 表 → 兩邊同步 cross-PR;改 domain 表 → 自己 repo 即可。Source of truth 寫在 .claude/architecture/schema-spec.md

6 · BASELINE · 兩邊都有

// CROSS-PR ENFORCED

  • → projects// 專案元數據
  • → sessions// session 元數據
  • → session_files// 檔案操作紀錄
  • → subagent_sessions// subagent 父子關係
  • → schema_version// migration 版本追蹤
  • → sessions_fts// session 全文搜尋(FTS5)

// 只有這 6 張要求兩邊同步改。
// 訊息內容那幾張為何不在這裡,見下方 DESIGN NOTE。

7 · CCRECALL · DOMAIN

// MEMORY + METACOGNITION

  • → memories// 結構化記憶(核心)
  • → memories_fts// memories 全文索引(FTS5)
  • → knowledge_map// 元認知地圖(topic depth)
  • → session_topics// session ↔ topic 多對多
  • → memory_topics// memory ↔ topic 多對多
  • → message_uuids// 訊息去重(v0.5.0 改雙 64-bit hash)
  • → injection_log// 記憶注入來源追蹤(v0.5.4+)

// v0.5.0 刪掉 session_journal 與 session_checkpoints——
// 兩張都沒有呼叫者,理由見 ccRecall 頁

7 · CCREWIND · DOMAIN

// 訊息內容 + GUI 狀態

  • → messages// 訊息(user / assistant / tool)
  • → message_content// 大型 content_json 拆出
  • → message_archive// JSONL 原始 raw
  • → messages_fts// 訊息全文搜尋(FTS5)
  • → exclusion_rules// GUI 中考古排除規則
  • → session_tasks// AI 任務快照(v1.13.0+)
  • → session_stars// Session 星號標記(v1.15.0+)
DESIGN NOTE // 為何訊息表不是 baseline

ccRecall 曾經有這四張表,後來刪了

它是從 ccRewind fork 出來的,當初連 storage 層一起搬了過去,訊息表也就跟著來了。v0.2.0 把它們刪掉——內部盤點發現記憶召回、session 摘要、FTS 搜尋、萃取,沒有一條路徑會去查訊息表。純粹是 fork 的殘留,佔著空間沒人讀。

所以現在的分法反映的是實際用途:ccRewind 是歷史 GUI,必須逐則存訊息才能讓你回頭讀;ccRecall 是記憶層,只需要 session 層級的 metadata,加上自己萃取出來的記憶。

// 這頁一度寫成「10 表已對齊」——那是 spec 沒跟上實作,2026-07 校正。

SECT. 03 // CCREASON PLUGIN · READ SURFACE

ccReason plugin 讀哪幾個表?

作為 plugin(不是 peer),ccReason 只讀,不寫。讀取範圍涵蓋 baseline 與 ccRecall domain 的 6 個表,產出是 docs/adr/*.md

PLUGIN READ-ONLY SURFACE

⊙ memories // 取 decision / discovery / pattern 類型

⊙ knowledge_map // 取 topic depth + summary

⊙ session_topics // 追溯 ADR 時間軸

⊙ memory_topics // 推 ADR 內容

⊙ sessions // 起訖時間 / project_id

⊙ message_uuids // 訊息指紋,跨 session 對照用

// 不讀:injection_log(注入遙測)、exclusion_rules(GUI 排除)、message_content / message_archive(過細)

SECT. 04 // MIGRATION · REVERSIBLE BY DESIGN

合併到 ~/.ccfamily/db.sqlite
每一步都可 rollback

三段式 migration 設計:env var 切換 → migrate tool → rollback path。**ASSERT #06 可逆遷移**的具體實作路線。

A PHASE

DB Path 切換

兩邊都加 CCFAMILY_HOME env var 偵測。預設仍走各自 SQLite,啟用後讀寫 unified DB。

SCOPE: ccRecall + ccRewind

EFFORT: 1-2 hr each

RISK: 低(fallback default)

B PHASE

Migrate Tool

ccfamily-migrate 工具:偵測兩邊 DB → 建 unified → 複製 baseline + domain → VACUUM → 保留原始檔

CONFLICT: UNION + PK dedup

EFFORT: 2-3 days

LOG: ~/.ccfamily/migration.log

C PHASE

Rollback Path

ccfamily-migrate rollback → unified DB 標記 archived,兩邊重新指回各自舊 DB。**不刪除** unified(純粹回 baseline)。

REVERSIBLE: ✓ always

EFFORT: 1-2 days

DATA LOSS: 0

// 整合採用者隨時可退出 — 這是 family overview ASSERT #06 的承諾。Migration tool 還沒實作,但設計已定。

SECT. 05 · SCHEMA CONTRACT

Schema 是寫死的契約

三條規則寫在 spec doc,違反者 PR 不過。

ASSERT #07

Cross-PR 同步

改 baseline 表(add / change / drop column)必須 ccRecall + ccRewind 同步 PR,且改 schema-spec.md 對應段落。Domain 表自己 repo 即可。

ASSERT #08

Reversible Migration

所有 schema migration(含 unified DB 合併)提供 forward + rollback 路徑。原始檔保留。Data loss 預設為 0。

ASSERT #09

Single Source of Truth

schema-spec.md 是意圖的 source of truth,實作是現況的 source of truth。兩者不一致時先查是誰落後——2026-07 這次就是 doc 落後實作三個月(baseline 寫 10 表,實際 6 表)。任何 schema 改動須同步更新 spec doc,並定期對帳。

// SCHEMA-SPEC.MD 內部維護於 ccFamily/.claude/architecture/,公開導出在這頁。