smart_brain 0.1.2 → 0.2.0

data/docs/multi_scope_memory_refactor_plan.md

@@ -0,0 +1,483 @@
+# SmartBrain 多级记忆域改造计划
+
+> 目标版本：SmartBrain 0.2.0
+> 文档状态：已实施（2026-08-03）
+> 改造范围：SmartBrain 核心、存储、治理、检索、SmartRAG adapter、Ruby/HTTP/MCP/CLI 契约
+
+## 1. 背景
+
+SmartBrain 0.1.x 使用 `session_id` 同时承担对话隔离和长期记忆隔离。该模型适合单会话 Agent，但无法自然表达以下共享关系：
+
+- 全局记忆：跨项目、跨专家、跨任务共享；
+- 项目记忆：同一项目的不同任务共享；
+- 专家记忆：同一专家跨项目、跨任务复用；
+- 任务记忆：只在当前任务内生效；
+- 会话事件：只属于一次连续对话。
+
+如果通过拼接 `session_id` 或向多个 session 复制记忆模拟这些层级，会引入重复数据、冲突不一致、治理链断裂和召回难以解释等问题。因此，0.2.0 将长期记忆归属从 session 中拆出，引入 domain 和 memory scope。
+
+## 2. 目标与非目标
+
+### 2.1 目标
+
+1. 支持 `global/project/expert/task` 四类业务记忆 scope。
+2. 保持 turns、messages、tool calls、refs 和 working summary 的 session 隔离。
+3. 一次 compose 可以联合检索多个 scope，并统一去重、冲突消解、排序和裁剪。
+4. 支持记忆在 scope 之间受控提升，并保留证据与审计链。
+5. 支持 domain 级数据隔离，禁止跨 domain 召回。
+6. InMemory 与 PostgreSQL 后端保持行为一致。
+7. Ruby、HTTP、MCP、CLI 旧调用在兼容期内继续工作。
+8. SmartRAG 资源检索遵循相同的 domain/scope 边界。
+
+### 2.2 非目标
+
+- 本阶段不实现组织级 RBAC 或远程租户鉴权。
+- 不自动推断调用方有权访问哪些 scope；调用方负责提供 scope context，SmartBrain 负责契约校验和 domain 隔离。
+- 不在本阶段实现任意 DAG 形式的 scope 继承。
+- 不允许模型将未经验证的记忆自动提升到 global、project 或 expert scope。
+- 不在本阶段移除 0.1.x 的 session-only API。
+
+## 3. 核心概念
+
+### 3.1 Domain
+
+`domain_id` 是最外层数据隔离边界，可对应一个用户、租户或 Agent 应用实例。同一请求引用的 session 和 scope 必须属于同一 domain。
+
+注意：知识生命周期接口现有的 `domain` 字段表示知识主题，不承担隔离职责。新字段始终命名为 `domain_id`。
+
+### 3.2 Memory Scope
+
+Memory Scope 表示长期记忆的归属与共享范围：
+
+| scope_type | 含义 | 示例 |
+|---|---|---|
+| `global` | domain 内全局共享 | `global:default` |
+| `project` | 项目内共享 | `project:project-001` |
+| `expert` | 专家跨任务复用 | `expert:coding` |
+| `task` | 当前任务私有 | `task:task-030` |
+| `session` | 兼容旧数据的内部私有 scope | `session:conv-001` |
+
+`session` scope 是兼容设施，不属于面向业务的四级记忆模型。
+
+### 3.3 Session
+
+Session 继续表示一次连续对话。以下数据仍以 `session_id` 为主归属：
+
+- turns/messages/tool_calls/refs；
+- recent turns；
+- rolling working summary；
+- commit/compose trace。
+
+长期记忆记录 `scope_id`，同时通过 `source_session_id` 保留来源会话。
+
+### 3.4 ScopeRef 与 ScopeContext
+
+ScopeRef 的公共结构：
+
+```ruby
+{ type: 'project', id: 'project-001' }
+```
+
+ScopeContext 的公共结构：
+
+```ruby
+{
+  read: [
+    { type: 'global', id: 'default' },
+    { type: 'project', id: 'project-001' },
+    { type: 'expert', id: 'coding' },
+    { type: 'task', id: 'task-030' }
+  ],
+  write: [
+    { type: 'project', id: 'project-001' },
+    { type: 'task', id: 'task-030' }
+  ],
+  default_write: { type: 'task', id: 'task-030' }
+}
+```
+
+`read` 必须去重，且所有 scope 必须属于请求的 `domain_id`。`write` 必须是 `read` 的子集，`default_write` 必须包含在 `write` 中。省略 `write` 时默认仅允许写入 `default_write`。
+
+## 4. 目标数据模型
+
+### 4.1 新表
+
+```text
+domains
+- id text primary key
+- metadata_json jsonb
+- created_at timestamptz
+- updated_at timestamptz
+
+memory_scopes
+- id text primary key
+- domain_id text not null references domains(id)
+- scope_type text not null
+- external_id text not null
+- parent_scope_id text null references memory_scopes(id)
+- metadata_json jsonb
+- created_at timestamptz
+- updated_at timestamptz
+- unique(domain_id, scope_type, external_id)
+
+session_scope_links
+- session_id text not null references sessions(id)
+- scope_id text not null references memory_scopes(id)
+- access_mode text not null
+- priority integer not null
+- created_at timestamptz
+- primary key(session_id, scope_id)
+```
+
+`access_mode` 初期支持 `read` 和 `read_write`。`priority` 只用于稳定排序和诊断，不能绕过冲突策略。
+
+### 4.2 现有表调整
+
+- `sessions` 增加 `domain_id`；
+- `memory_items` 增加 `scope_id`、`source_session_id`；
+- `entities` 增加 `scope_id`、`source_session_id`；
+- `kg_edges` 增加 `scope_id`、`source_session_id`；
+- `knowledge_events` 继续通过 memory item 追踪 scope；
+- `summaries`、`turns`、`messages`、`refs` 保持 session 归属。
+
+新增主要索引：
+
+```text
+memory_items(scope_id, status, lifecycle_status)
+memory_items(scope_id, type, key)
+kg_edges(scope_id, status)
+entities(scope_id, canonical, kind)
+sessions(domain_id)
+```
+
+0.2.0 不立即删除旧 `memory_items.session_id` 和 `kg_edges.session_id`，先作为兼容字段保留，并在后续版本评估移除。
+
+## 5. 公共 API 设计
+
+### 5.1 Commit
+
+```ruby
+SmartBrain.commit_turn(
+  domain_id: 'default',
+  session_id: 'conv-001',
+  scope_context: scope_context,
+  turn_events: turn_events
+)
+```
+
+单条结构化记忆允许覆盖默认写 scope：
+
+```ruby
+decisions: [{
+  key: 'decision:db:storage',
+  decision: '项目使用 PostgreSQL',
+  scope_ref: { type: 'project', id: 'project-001' }
+}]
+```
+
+messages 和 refs 忽略 `scope_ref`，始终写入 session。entities 和 edges 默认跟随 `default_write`，显式指定时必须通过 scope 写权限检查。
+
+### 5.2 Compose
+
+```ruby
+SmartBrain.compose_context(
+  domain_id: 'default',
+  session_id: 'conv-001',
+  scope_context: scope_context,
+  user_message: '继续实现数据库迁移',
+  agent_state: {}
+)
+```
+
+compose 使用当前 session 的 recent turns 和 summary，使用 `scope_context.read` 检索长期记忆与 KG。
+
+### 5.3 Search、Brief、KG 与治理
+
+以下接口同步增加 `domain_id` 和 scope 参数：
+
+- `search_memory`；
+- `brief`、`wake_up`；
+- `fact_check`；
+- `kg_add`、`kg_query`、`kg_stats`、`kg_timeline`；
+- `distill`、`promote`、`demote`、`retract`。
+
+按 ID 操作 memory item 时从记录解析 domain/scope，并校验调用上下文，不依赖调用方重复提供正确归属。
+
+## 6. Commit 写入策略
+
+commit 的目标执行顺序：
+
+1. 规范化 `domain_id`、`session_id` 和 `scope_context`；
+2. 确保 domain、session、scope 和 session-scope link 存在；
+3. 将 messages、tool calls 和 refs 写入 session EventStore；
+4. Extractor 生成结构化记忆候选；
+5. Scope Resolver 为每条候选解析目标 scope；
+6. MemoryStore 在目标 scope 内执行 upsert 和冲突记录；
+7. entities、KG edges 使用同一 scope 解析规则；
+8. Consolidator 更新当前 session 的 working summary；
+9. commit explain 记录每条数据的 scope、来源和拒绝原因。
+
+默认写入策略保持保守：自动抽取只写 `default_write`。写入 global/project/expert 必须由调用方显式指定，或通过跨 scope promotion 完成。
+
+## 7. 多 Scope 检索与冲突消解
+
+compose 的目标流程：
+
+```text
+resolve scopes
+  -> retrieve per scope
+  -> lifecycle/status filter
+  -> resolve same-key conflicts
+  -> KG expansion
+  -> optional SmartRAG retrieval
+  -> memory/resource fusion
+  -> tier order and token budget
+  -> ContextPackage
+```
+
+### 7.1 同 Key 冲突
+
+对相同 `type + key` 的 active 记忆采用以下规则：
+
+1. 钉入的 `dao_tian` 原则不被普通记忆覆盖；
+2. 普通记忆按 `task > project > expert > global` 选择；
+3. 同 scope 内使用现有 active/superseded/retracted 规则；
+4. 未选中的候选进入 `debug.shadowed`，保留覆盖原因；
+5. 没有稳定 key 的 evidence 不做 scope shadow，仅参与相关性排序。
+
+项目约束默认高于专家习惯。例如项目明确要求 MySQL 时，不能因为 coding expert 偏好 PostgreSQL 而改变当前项目决策。
+
+### 7.2 排序与预算
+
+scope specificity 只能作为排序信号之一，不能完全取代 query relevance。Composer 仍以 mind-model tier 控制原则优先级，并为每个 scope 设置可配置上限，防止某个 scope 独占上下文。
+
+建议新增配置：
+
+```yaml
+policies:
+  scopes:
+    allowed_types: [global, project, expert, task, session]
+    conflict_priority: [task, project, expert, global, session]
+    max_items_per_scope: 10
+    require_explicit_elevated_write: true
+```
+
+## 8. 跨 Scope 治理
+
+新增接口：
+
+```ruby
+SmartBrain.promote_to_scope(
+  memory_item_id: memory_item_id,
+  target_scope: { type: 'project', id: 'project-001' },
+  verification_refs: refs,
+  reason: '项目决策已确认',
+  reviewer: 'human'
+)
+```
+
+跨 scope promotion 不移动或原地修改源记录，而是在目标 scope 创建新记录，并保存：
+
+- source memory item ID；
+- source scope；
+- target scope；
+- supporting/verification refs；
+- reviewer 与 reason；
+- promotion event ID。
+
+目标记录必须能沿 provenance 回溯到源 session。后续需支持 `demote_from_scope`、retract 和 promotion lineage 查询。
+
+## 9. SmartRAG Scope 传播
+
+RetrievalPlan 增加 scope 上下文：
+
+```ruby
+{
+  debug: {
+    caller: {
+      app: 'smart_brain',
+      domain_id: 'default',
+      session_id: 'conv-001'
+    }
+  },
+  scope_context: scope_context
+}
+```
+
+SmartRAG adapter 负责将 scope 映射为 SmartRAG 的 `topic_ids`、`document_ids` 或其他过滤条件。SmartBrain 不在核心层绑定具体 topic 命名规则。
+
+若 SmartRAG 无法应用某个 scope 过滤，adapter 必须返回 warning，并写入 `explain.ignored_fields`。生产配置可选择在过滤无法应用时 fail closed，避免跨项目或跨 domain 召回。
+
+## 10. ContextPackage 与可观测性
+
+Memory evidence 增加：
+
+```ruby
+{
+  scope: { type: 'project', id: 'project-001' },
+  source_session_id: 'conv-001'
+}
+```
+
+ContextPackage debug 增加：
+
+- `scopes_read`；
+- `scope_stats`；
+- `shadowed`；
+- `scope_budget`；
+- `scope_filter_warnings`。
+
+diagnostics 增加：
+
+- 每种 scope 的写入量和召回量；
+- shadow/conflict 数量；
+- 跨 scope promotion 数量；
+- domain/scope 校验失败数量；
+- SmartRAG scope filter 失败数量。
+
+## 11. 兼容与迁移策略
+
+### 11.1 旧 API
+
+未传 `domain_id` 和 `scope_context` 的调用使用：
+
+```text
+domain_id = legacy
+read/default_write = session:<session_id>
+```
+
+这样旧 session 之间仍保持隔离，不会因升级意外共享记忆。
+
+### 11.2 PostgreSQL 数据迁移
+
+迁移脚本为每个旧 session：
+
+1. 创建或复用 `legacy` domain；
+2. 创建 `session:<session_id>` 内部 scope；
+3. 建立 session-scope link；
+4. 回填 memory items、entities 和 KG edges 的 `scope_id` 与 `source_session_id`；
+5. 迁移完成后执行 orphan 和跨 domain 一致性检查。
+
+迁移必须幂等，且不删除旧字段或旧数据。
+
+## 12. 分阶段实施
+
+### Phase A：契约与骨架
+
+- 增加 ScopeRef、ScopeContext contracts；
+- 增加 domain/scope 配置；
+- 定义兼容映射；
+- 补充契约和序列化测试。
+
+验收：新旧参数均可校验；非法 scope type、重复 scope、跨 domain 引用被拒绝。
+
+### Phase B：数据库与 Store
+
+- 增加 005 migration；
+- 实现 scope registry/resolver；
+- 改造 InMemory Store；
+- 改造 PostgreSQL Store；
+- 完成旧数据回填。
+
+验收：两个后端在 CRUD、隔离、upsert 和查询上行为一致。
+
+### Phase C：Commit 路由
+
+- Runtime 接受 domain/scope context；
+- Extractor 保留或透传 scope_ref；
+- memory/entity/KG 写入目标 scope；
+- explain 增加写入路由信息。
+
+验收：默认写 task，显式写 project/expert/global，messages 始终只写 session。
+
+### Phase D：Compose 与冲突处理
+
+- 实现多 scope retrieval；
+- 实现 Scope ConflictResolver；
+- 改造 memory retriever、KG expansion、Fusion、Composer；
+- 增加 scope 预算与 debug。
+
+验收：四级联合召回可用，task/project/expert/global 冲突结果稳定且可解释。
+
+### Phase E：治理能力
+
+- 实现 promote_to_scope；
+- 扩展 knowledge events 与 provenance；
+- 扩展 brief、wake_up、fact_check、KG；
+- 增加 demote/retract 行为测试。
+
+验收：高层记忆有证据与审计链，能够回溯源 scope 和 session。
+
+### Phase F：SmartRAG、协议与工具面
+
+- 扩展 RetrievalPlan 和 adapter；
+- 更新 Ruby/HTTP/MCP/CLI；
+- 更新用户指南和 examples；
+- 增加 scope diagnostics。
+
+验收：所有调用面支持新参数，SmartRAG scope filter 可验证且默认不泄漏。
+
+### Phase G：兼容与发布
+
+- 运行完整旧测试套件；
+- 增加迁移演练和回滚验证；
+- 增加 PostgreSQL 集成测试；
+- 发布 0.2.0 和迁移说明。
+
+验收：0.1.x 旧调用继续通过，升级前后 session-only 行为一致。
+
+## 13. 测试矩阵
+
+必须覆盖：
+
+1. domain A 无法读取 domain B 的 session、memory、entity 和 KG；
+2. 同一 domain 的多个 session 可以共享 project/expert/global scope；
+3. task scope 不会泄漏到同项目其他任务；
+4. project 记忆覆盖 expert/global 的同 key 普通记忆；
+5. task 记忆覆盖 project 记忆；
+6. dao_tian 原则不被普通 task 记忆覆盖；
+7. lifecycle candidate/demoted 仍不会进入自动 context；
+8. promotion 保留 source memory、scope、session 和 evidence；
+9. InMemory/PostgreSQL 返回顺序和 shadow 结果一致；
+10. 旧 API 和旧 PostgreSQL 数据迁移后行为不变；
+11. MCP/HTTP/CLI 的 schema、参数和错误响应一致；
+12. SmartRAG filter 未应用时产生 warning 或按配置 fail closed。
+
+## 14. 发布门槛
+
+SmartBrain 0.2.0 发布前必须满足：
+
+- 所有 0.1.x 自动化测试继续通过；
+- scope 新测试在 InMemory 和 PostgreSQL 后端全部通过；
+- migration 可重复运行，且有旧数据校验报告；
+- compose evidence 能解释 scope 和 source session；
+- 未传新参数的客户端无需修改即可运行；
+- SmartRAG 不会在过滤失败时静默跨 scope 返回资源；
+- 文档包含升级、回滚和兼容期说明。
+
+## 15. 建议的代码改动边界
+
+主要新增或修改位置：
+
+```text
+lib/smart_brain.rb
+lib/smart_brain/runtime.rb
+lib/smart_brain/configuration.rb
+lib/smart_brain/contracts/
+lib/smart_brain/scopes/
+lib/smart_brain/event_store/
+lib/smart_brain/memory_store/
+lib/smart_brain/memory_extractor/
+lib/smart_brain/retrievers/
+lib/smart_brain/fusion/
+lib/smart_brain/context_composer/
+lib/smart_brain/governance/
+lib/smart_brain/adapters/smart_rag/
+lib/smart_brain/server/
+db/migrate/005_domains_and_memory_scopes.sql
+spec/
+docs/
+examples/
+```
+
+实施时应先完成契约和存储层，再修改 Runtime；不要在 Store 尚未具备双后端一致性之前接入 SmartRAG 或上层应用。

data/docs/multi_scope_migration.md

@@ -0,0 +1,65 @@
+# SmartBrain 0.2.0 Multi-Scope Migration
+
+## Upgrade
+
+Back up the PostgreSQL database before upgrading. Then run:
+
+```bash
+SMARTBRAIN_BACKEND=postgres bundle exec smart_brain migrate
+```
+
+Migration `005_domains_and_memory_scopes.sql` is idempotent. It preserves the
+legacy `session_id` columns, creates `legacy/session:<session_id>` scopes, and
+backfills memory, entity, and KG provenance. Calls that omit `domain_id` and
+`scope_context` continue to use the isolated legacy session scope.
+
+Validate the upgrade with:
+
+```sql
+SELECT count(*) FROM memory_items WHERE scope_id IS NULL OR source_session_id IS NULL;
+SELECT count(*) FROM entities WHERE scope_id IS NULL OR source_session_id IS NULL;
+SELECT count(*) FROM kg_edges WHERE scope_id IS NULL OR source_session_id IS NULL;
+```
+
+All three counts must be zero.
+
+## Rollback
+
+Application rollback is supported during the compatibility period because the
+old `session_id` columns and data remain intact. Stop 0.2 writers, deploy the
+0.1 application, and switch clients back to session-only calls.
+
+Do not drop `domains`, `memory_scopes`, `session_scope_links`, or the new
+columns during an operational rollback. Removing them is a separate destructive
+cleanup after all 0.2 data has been exported or mapped back to legacy sessions.
+
+## New Context
+
+New clients should provide explicit read and write scopes:
+
+```ruby
+scope_context = {
+  read: [
+    { type: 'global', id: 'default' },
+    { type: 'project', id: 'project-001' },
+    { type: 'task', id: 'task-030' }
+  ],
+  write: [
+    { type: 'project', id: 'project-001' },
+    { type: 'task', id: 'task-030' }
+  ],
+  default_write: { type: 'task', id: 'task-030' }
+}
+```
+
+Per-item `scope_ref` writes are accepted only when the target appears in
+`scope_context.write`.
+
+## Validation Record
+
+The 2026-08-03 local PostgreSQL rehearsal completed successfully:
+
+- migration `005` was run repeatedly through the migration command and the PostgreSQL test setup;
+- the full suite passed with `92 examples, 0 failures` with PostgreSQL enabled;
+- `memory_items`, `entities`, and `kg_edges` each reported zero rows with missing `scope_id` or `source_session_id`;
+- legacy session-only persistence/recall and scoped ordering, shadow diagnostics, governance, and promotion provenance passed after runtime restart.