数据库架构

Claude-Mem uses SQLite 3 and the bun:sqlite native module for persistent storage, and uses FTS5 for full-text search.

数据库位置

路径: ~/.claude-mem/claude-mem.db

该数据库使用 SQLite 的 WAL（写前日志）模式来进行并发读写。

数据库实现

Main implementation: bun:sqlite（原生 SQLite 模块）

使用者：SessionStore 和 SessionSearch
格式：具有更好性能的同步 API
注意：Database.ts（使用 bun:sqlite）是遗留代码

核心表

1. sdk_会话

跟踪活动和已完成的会话。

sql

CREATE TABLE sdk_sessions (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  sdk_session_id TEXT UNIQUE NOT NULL,
  claude_session_id TEXT,
  project TEXT NOT NULL,
  prompt_counter INTEGER DEFAULT 0,
  status TEXT NOT NULL DEFAULT 'active',
  created_at TEXT NOT NULL,
  created_at_epoch INTEGER NOT NULL,
  completed_at TEXT,
  completed_at_epoch INTEGER,
  last_activity_at TEXT,
  last_activity_epoch INTEGER
);

索引：

idx_sdk_sessions_claude_session 于 claude_session_id
idx_sdk_sessions_project 于 project
idx_sdk_sessions_status 于 status
idx_sdk_sessions_created_at 于 created_at_epoch DESC

2. 观察

具有层级结构的单个工具执行。

sql

CREATE TABLE observations (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  session_id TEXT NOT NULL,
  sdk_session_id TEXT NOT NULL,
  claude_session_id TEXT,
  project TEXT NOT NULL,
  prompt_number INTEGER,
  tool_name TEXT NOT NULL,
  correlation_id TEXT,

  -- Hierarchical fields
  title TEXT,
  subtitle TEXT,
  narrative TEXT,
  text TEXT,
  facts TEXT,
  concepts TEXT,
  type TEXT,
  files_read TEXT,
  files_modified TEXT,

  created_at TEXT NOT NULL,
  created_at_epoch INTEGER NOT NULL,

  FOREIGN KEY (sdk_session_id) REFERENCES sdk_sessions(sdk_session_id)
);

观察类型：

decision - 建筑或设计决策
bugfix - 错误修复和更正
feature - 新功能或新能力
refactor - 代码重构与清理
discovery - 关于代码库的学习
change - 一般变更和修改

索引：

idx_observations_session 于 session_id
idx_observations_sdk_session 于 sdk_session_id
idx_observations_project 于 project
idx_observations_tool_name 于 tool_name
idx_observations_created_at 于 created_at_epoch DESC
idx_observations_type 于 type

3. 会议摘要

AI生成的会话摘要（每个会话多个）。

sql

CREATE TABLE session_summaries (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  sdk_session_id TEXT NOT NULL,
  claude_session_id TEXT,
  project TEXT NOT NULL,
  prompt_number INTEGER,

  -- Summary fields
  request TEXT,
  investigated TEXT,
  learned TEXT,
  completed TEXT,
  next_steps TEXT,
  notes TEXT,

  created_at TEXT NOT NULL,
  created_at_epoch INTEGER NOT NULL,

  FOREIGN KEY (sdk_session_id) REFERENCES sdk_sessions(sdk_session_id)
);

索引：

idx_session_summaries_sdk_session 于 sdk_session_id
idx_session_summaries_project 于 project
idx_session_summaries_created_at 于 created_at_epoch DESC

4. 用户提示

使用 FTS5 搜索的原始用户提示（自 v4.2.0 起）。

sql

CREATE TABLE user_prompts (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  sdk_session_id TEXT NOT NULL,
  claude_session_id TEXT,
  project TEXT NOT NULL,
  prompt_number INTEGER,
  prompt_text TEXT NOT NULL,
  created_at TEXT NOT NULL,
  created_at_epoch INTEGER NOT NULL,

  FOREIGN KEY (sdk_session_id) REFERENCES sdk_sessions(sdk_session_id)
);

索引：

idx_user_prompts_sdk_session 于 sdk_session_id
idx_user_prompts_project 于 project
idx_user_prompts_created_at 于 created_at_epoch DESC

传统表格

会话：传统会话跟踪（v3.x）
内存：遗留压缩内存块（v3.x）
概览：旧版会话摘要（v3.x）

FTS5 全文搜索

SQLite FTS5（全文搜索）虚拟表能够在观察、摘要和用户提示中实现快速全文搜索。

FTS5 虚拟表

观察_fts

sql

CREATE VIRTUAL TABLE observations_fts USING fts5(
  title,
  subtitle,
  narrative,
  text,
  facts,
  concepts,
  content='observations',
  content_rowid='id'
);

会话摘要_全文检索

sql

CREATE VIRTUAL TABLE session_summaries_fts USING fts5(
  request,
  investigated,
  learned,
  completed,
  next_steps,
  notes,
  content='session_summaries',
  content_rowid='id'
);

用户提示_fts

sql

CREATE VIRTUAL TABLE user_prompts_fts USING fts5(
  prompt_text,
  content='user_prompts',
  content_rowid='id'
);

自动同步

FTS5 表通过触发器保持同步：

sql

-- Insert trigger example
CREATE TRIGGER observations_ai AFTER INSERT ON observations BEGIN
  INSERT INTO observations_fts(rowid, title, subtitle, narrative, text, facts, concepts)
  VALUES (new.id, new.title, new.subtitle, new.narrative, new.text, new.facts, new.concepts);
END;

-- Update trigger example
CREATE TRIGGER observations_au AFTER UPDATE ON observations BEGIN
  INSERT INTO observations_fts(observations_fts, rowid, title, subtitle, narrative, text, facts, concepts)
  VALUES('delete', old.id, old.title, old.subtitle, old.narrative, old.text, old.facts, old.concepts);
  INSERT INTO observations_fts(rowid, title, subtitle, narrative, text, facts, concepts)
  VALUES (new.id, new.title, new.subtitle, new.narrative, new.text, new.facts, new.concepts);
END;

-- Delete trigger example
CREATE TRIGGER observations_ad AFTER DELETE ON observations BEGIN
  INSERT INTO observations_fts(observations_fts, rowid, title, subtitle, narrative, text, facts, concepts)
  VALUES('delete', old.id, old.title, old.subtitle, old.narrative, old.text, old.facts, old.concepts);
END;

FTS5 查询语法

FTS5 支持丰富的查询语法：

简单: "error handling"
和: "error" AND "handling"
或: "bug" OR "fix"
不是: "bug" NOT "feature"
短语: "'exact phrase'"
列: title:"authentication"

安全

从 v4.2.3 起，所有 FTS5 查询都已正确转义以防止 SQL 注入：

双引号被转义：query.replace(/"/g, '""')
包含332个注入攻击测试的综合测试套件

数据库类

会话存储

会话、观察、总结和用户提示的增删改查操作。

位置: src/services/sqlite/SessionStore.ts

方法：

createSession()
getSession()
updateSession()
createObservation()
getObservations()
createSummary()
getSummaries()
createUserPrompt()

会话搜索

FTS5 全文搜索，提供 8 种专用搜索方法。

位置: src/services/sqlite/SessionSearch.ts

方法：

searchObservations() - 在观测中进行全文搜索
searchSessions() - 在摘要中进行全文搜索
searchUserPrompts() - 跨用户提示的全文搜索
findByConcept() - 按概念标签查找
findByFile() - 按文件引用查找
findByType() - 按观测类型查找
getRecentContext() - 获取最近的会话上下文
advancedSearch() - 组合过滤器

迁移

数据库模式通过 src/services/sqlite/migrations.ts 中的迁移来管理。

迁徙历史：

迁移 001：初始模式（会话、记忆、概览、诊断、转录事件）
迁移 002：分层记忆字段（标题、子标题、事实、概念、涉及的文件）
迁移 003：SDK 会话和观察
迁移 004：会议摘要
迁移 005：多提示会话（prompt_counter，prompt_number）
迁移 006：FTS5 虚拟表和触发器
迁移 007-010：各种改进和用户提示表

性能考虑

索引：所有外键和经常查询的列都已建立索引
FTS5：全文搜索比 LIKE 查询快得多
触发器：自动同步的开销很小
连接池：bun:sqlite 高效地重用连接
同步 API：bun:sqlite 使用同步 API 以获得更好的性能

故障排除

请参阅故障排除 - 数据库问题] 以获取常见问题和解决方案。

数据库架构 ​

数据库位置 ​

数据库实现 ​

核心表 ​

1. sdk_会话 ​

2. 观察 ​

3. 会议摘要 ​

4. 用户提示 ​

传统表格 ​

FTS5 全文搜索 ​

FTS5 虚拟表 ​

观察_fts ​

会话摘要_全文检索 ​

用户提示_fts ​

自动同步 ​

FTS5 查询语法 ​

安全 ​

数据库类 ​

会话存储 ​

会话搜索 ​

迁移 ​

性能考虑 ​

故障排除 ​