memory-schema

name	memory-schema
description	三层租户隔离 SQL 模式、pgvector 记忆表、遥测时序(TimescaleDB)与特征库(Feast)、迁移规范。编写数据库相关代码时使用。见 ADR-0004/0010/0013。

数据 Schema & 租户隔离规范

隔离边界 = Account（ADR-0004）。设备/遥测/观测数据按 tenant_id+account_id 隔离；个人记忆再叠 user_id。

存储分工（ADR-0010/0013）

数据	存储	说明
Mastra 记忆	pgvector schema platform_memory	对话/语义记忆，Mastra 自动管理
业务/观测	Postgres public	设备、Twin、观测，参数化查询
历史遥测	TimescaleDB（hypertable）	时序，藏在可切换 repo 接口后，高容量可切 ClickHouse
特征	Feast（online/offline）	entity key 带 tenant_id+account_id，喂垂类模型

三层租户隔离 SQL 模式

业务表必须含 tenant_id + account_id 列并有联合索引（个人化数据再加 user_id）：

CREATE TABLE device_events (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  tenant_id TEXT NOT NULL,
  account_id TEXT NOT NULL,          -- 数据归属单元 = 隔离边界
  device_id TEXT NOT NULL,
  raw_event_id TEXT NOT NULL UNIQUE, -- 幂等
  event_type TEXT NOT NULL,
  payload JSONB,
  captured_at TIMESTAMPTZ NOT NULL,
  created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
  embedding vector(1024)
);

CREATE INDEX idx_device_events_tenant_account ON device_events(tenant_id, account_id);
CREATE INDEX idx_device_events_device ON device_events(tenant_id, account_id, device_id);

• 所有跨租户查询必须带 WHERE tenant_id = $1 AND account_id = $2；个人记忆类再叠 AND user_id = $3
• 租户上下文只从服务端 requestContext / resourceId 取，绝不信客户端传入（防串号，ADR-0014）
• 删除/被遗忘权按 Account 级联（ADR-0013）

向量索引

• HNSW（m=16, ef_construction=64）
• Mastra 1.36 SemanticRecall bug（忽略 user indexConfig），保留 createIndex workaround

迁移规范

• 迁移文件 src/mastra/runtime/migrations.ts，启动时 applyPendingMigrations() 自动运行
• 幂等（IF NOT EXISTS / DO $$ ... END $$）
• 旧两层（tenant_id+user_id）数据需迁到三层（加 account_id 维度，ADR-0004）