smart_brain 0.1.2 → 0.2.0

data/README.md

@@ -1,173 +1,467 @@
-# SmartBrain
-
-SmartBrain 是一个面向 Agent 的记忆运行时（Memory Runtime）与上下文编排器（Context Composer）。
-
-它的核心职责：
-- `commit_turn`：记录事件真相并沉淀结构化记忆
-- `compose_context`：在每轮请求前组装最小充分上下文
-- 联动 SmartRAG：对话记忆由 SmartBrain 管理，资源检索由 SmartRAG 提供
-
-## 当前进展
-
-当前仓库已实现并打通：
-- `commit_turn` / `compose_context` 主链路
-- Retention / Consolidation / Retrieval / Composition 策略
-- 检索器：exact + relational
-- 融合层：去重、规则重排、多样性、预算截断
-- SmartRAG 适配器：`NullClient` / `HttpClient` / `DirectClient`
-- 契约与可观测：`request_id` / `plan_id` / `context_id` 全链路追踪
-- RSpec 测试（单元 + 集成 + 回归）
-
-## 项目结构
-
-- `lib/smart_brain.rb`：入口 API
-- `lib/smart_brain/runtime.rb`：主运行时编排
-- `lib/smart_brain/contracts/`：RetrievalPlan / EvidencePack / ContextPackage 校验
-- `lib/smart_brain/observability/`：日志与指标
-- `lib/smart_brain/event_store/`：事件存储（当前内存实现）
-- `lib/smart_brain/memory_store/`：记忆存储（当前内存实现）
-- `lib/smart_brain/retrievers/`：exact/relational 检索
-- `lib/smart_brain/fusion/`：多源融合
-- `lib/smart_brain/context_composer/`：上下文装配
-- `lib/smart_brain/adapters/smart_rag/`：SmartRAG 适配层
-- `config/brain.yml`：策略配置
-- `example.rb`：SmartBrain + SmartAgent + SmartPrompt + SmartRAG 联动示例
-- `docs/`：设计与协议文档
-
-## 安装
-
-```bash
-bundle install
-```
-
-如遇本地权限或 shared gem 污染，建议：
-
-```bash
-bundle config set --local path 'vendor/bundle'
-bundle config set --local disable_shared_gems 'true'
-```
-
-## 快速开始（仅 SmartBrain）
-
-```ruby
-require_relative 'lib/smart_brain'
-
-SmartBrain.configure
-
-SmartBrain.commit_turn(
-  session_id: 'demo',
-  turn_events: {
-    messages: [
-      { role: 'user', content: '请记住：默认数据库是 Postgres。' },
-      { role: 'assistant', content: '已记录。' }
-    ],
-    decisions: [
-      { key: 'decision:smartbrain:storage', decision: 'Use Postgres by default' }
-    ]
-  }
-)
-
-context = SmartBrain.compose_context(
-  session_id: 'demo',
-  user_message: '继续并总结关键结论'
-)
-
-puts context[:context_id]
-puts context.dig(:debug, :trace, :request_id)
-puts context.dig(:debug, :trace, :plan_id)
-```
-
-## SmartRAG 集成方式
-
-### 1) NullClient（默认）
-
-不配置 `smart_rag_client` 时，资源证据为空，仅使用记忆侧证据。
-
-### 2) HttpClient
-
-```ruby
-transport = lambda do |plan, timeout_seconds:|
-  {
-    plan_id: 'p1',
-    supports_language_filter: true,
-    evidences: []
-  }
-end
-
-client = SmartBrain::Adapters::SmartRag::HttpClient.new(transport: transport, timeout_seconds: 2)
-SmartBrain.configure(smart_rag_client: client)
-```
-
-### 3) DirectClient（当前示例使用）
-
-```ruby
-require 'smart_rag'
-require_relative 'lib/smart_brain/adapters/smart_rag/direct_client'
-
-rag_config = SmartRAG::Config.load(ENV.fetch('SMARTRAG_CONFIG_PATH'))
-rag = SmartRAG::SmartRAG.new(rag_config)
-client = SmartBrain::Adapters::SmartRag::DirectClient.new(rag: rag)
-
-SmartBrain.configure(smart_rag_client: client)
-```
-
-## example.rb 说明（已更新）
-
-`example.rb` 演示完整链路：
-1. SmartBrain `compose_context`
-2. SmartAgent 通过 `call_worker` 调用 SmartPrompt worker
-3. SmartBrain `commit_turn`
-4. 打印 `evidence(memory/resource)` 验证 SmartRAG 是否参与
-
-示例依赖的本地文件：
-- `config/example_agent.yml`
-- `config/example_llm.yml`
-- `agents/brain_assistant.rb`
-- `workers/brain_assistant.rb`
-- `templates/brain_assistant.erb`
-
-运行：
-
-```bash
-bundle exec ruby example.rb
-```
-
-## 核心 API
-
-### `SmartBrain.configure(config_path: nil, smart_rag_client: nil, clock: -> { Time.now.utc })`
-初始化运行时并注入 SmartRAG 客户端（可选）。
-
-### `SmartBrain.commit_turn(session_id:, turn_events:)`
-写入事件、抽取记忆、冲突处理、摘要更新。
-
-### `SmartBrain.compose_context(session_id:, user_message:, agent_state: {})`
-生成 `ContextPackage`，内部包含检索计划与证据融合结果。
-
-### `SmartBrain.diagnostics`
-返回 compose/commit 观测日志与指标快照。
-
-## 测试
-
-```bash
-rspec
-```
-
-## 常见问题
-
-### 1) `cannot load such file -- sequel/extensions/pgvector`
-当前示例已在 `example.rb` 做兼容处理（`Sequel.extension 'pgvector'` + 去除 `database.extensions` 连接参数）。
-
-### 2) `Config file not found: config/llm_config.yml`
-`example.rb` 已将 SmartRAG 里 EmbeddingService 的 `config_path` 注入为 `./config/example_llm.yml`。
-
-### 3) `ruby-lsp: not found`
-```bash
-gem install --user-install ruby-lsp debug
-```
-并将用户 gem bin 加入 `PATH`。
-
-## 路线图
-
-- 将 EventStore/MemoryStore 从内存实现切换到 Postgres 实现
-- 接入真实 reranker / embedding 模型
-- 完善 SmartRAG ingest 与跨会话评估工具
+# SmartBrain
+
+SmartBrain（v0.2.0）是一个面向 Agent 的**记忆运行时（Memory Runtime）与上下文编排器（Context Composer）**。
+
+在多轮 Agent 对话中，SmartBrain 解决的核心问题是：如何高效地记录、检索、融合记忆，并装配出"最小充分"的上下文发给 LLM。
+
+## 核心职责
+
+- **`commit_turn`**：记录事件真相并沉淀结构化长期记忆（写链路）
+- **`compose_context`**：在每轮请求前生成最小充分上下文（读 + 装配链路）
+- **联动 SmartRAG**：对话记忆由 SmartBrain 管理（EventStore / MemoryStore），资源检索由 SmartRAG 提供（适配层）
+
+## 架构边界
+
+SmartBrain 把 Agent 的可用信息分为两类，分工明确：
+
+| 类别 | 管理者 | 内容 | 特点 |
+|------|--------|------|------|
+| **对话记忆** (Conversation Memory) | SmartBrain | 原始事件（turn/messages/tool_calls/refs）、结构化记忆（profile/preferences/tasks/decisions/entities/events）、滚动摘要（working_summary） | 强时序、更新频繁、有写入门控与冲突管理 |
+| **资源记忆** (Resource Memory) | SmartRAG | 文档/网页/代码仓库等长期资源 | 相对静态、内容大、需要高质量检索 |
+
+> SmartRAG 是 SmartBrain 的"资源知识库后端"。SmartBrain 不复制 SmartRAG 的索引能力，只通过契约适配层调用它。
+
+## 当前进展
+
+当前仓库已实现并打通：
+
+- `commit_turn` / `compose_context` 主链路
+- Retention / Consolidation / Retrieval / Composition 四类策略
+- 检索器：exact（关键词匹配） + relational（实体/引用关联）
+- 融合层：去重、词重叠加分重排、多样性约束、预算截断、memory/resource 比例控制
+- SmartRAG 适配器：`NullClient`（默认空）/ `HttpClient`（HTTP 远程）/ `DirectClient`（进程内直接调用）
+- 契约与可观测：`request_id` → `plan_id` → `context_id` 全链路追踪
+- RSpec 测试（单元 + 集成 + PostgreSQL 回归）
+
+## 安装
+
+```bash
+bundle install
+```
+
+如遇本地权限或 shared gem 污染：
+
+```bash
+bundle config set --local path 'vendor/bundle'
+bundle config set --local disable_shared_gems 'true'
+```
+
+## 核心 API
+
+SmartBrain 提供以下核心工作流 API：
+
+### `SmartBrain.configure(config_path: nil, smart_rag_client: nil, clock: -> { Time.now.utc })`
+
+初始化运行时并注入 SmartRAG 客户端（可选）。
+
+- `config_path`：策略配置文件路径，默认 `config/brain.yml`
+- `smart_rag_client`：SmartRAG 适配器实例，默认 `NullClient`（资源证据为空）
+- `clock`：时间源函数，默认 `Time.now.utc`
+
+### `SmartBrain.commit_turn(session_id:, turn_events:, domain_id: nil, scope_context: nil)`
+
+写入事件、抽取记忆、冲突处理、摘要更新。返回 `CommitResult`。
+
+**`turn_events` 支持的事件类型：**
+
+| 字段 | 类型 | 说明 | 示例 |
+|------|------|------|------|
+| `messages` | Array | 消息列表，每条含 `role` 和 `content` | `[{ role: 'user', content: '...' }]` |
+| `decisions` | Array | 决策/选择/承诺 | `[{ key: 'decision:pg:pool_size', decision: '...' }]` |
+| `tasks` | Array | 任务，含状态流转 | `[{ key: 'task:brain:mvp', status: 'doing' }]` |
+| `goals` | Array | 长期目标 | `[{ key: 'goal:learn:ruby', goal: '...' }]` |
+| `entities` | Array | 重要实体 | `[{ key: 'entity:lang:ruby', name: 'Ruby', canonical: 'ruby', kind: 'language', remember: true }]` |
+| `preferences` | Array | 偏好，需 `confirmed: true` 才写入长期记忆 | `[{ key: 'pref:writing:tone', value: '...', confirmed: true }]` |
+| `events` | Array | 里程碑/异常等高价值事件 | — |
+| `refs` | Array | 文件/URL/产物引用 | — |
+| `retractions` | Array | 撤回旧记忆 | `[{ type: 'decisions', key: 'decision:old:topic' }]` |
+
+**写入门控策略：**
+- **必写**：`tasks`、`decisions`（confidence: 0.9）
+- **条件写**：`goals`（需显示声明）、`preferences`（需 `confirmed: true`）、`entities`（需出现频率 ≥ 2 或含 URL/路径等结构信号）
+- **不写入**：闲聊、未确认推测
+
+**冲突处理：**
+- 覆盖型（`preferences/goals/tasks`）：新值写入，旧值 → `status=superseded`
+- 多版本并存（`decisions/events`）：保留历史
+- 撤回（`retracted`）：旧条目 → `status=retracted`
+
+**返回值：**
+
+```ruby
+{
+  ok: true,
+  commit_id: "uuid",
+  session_id: "...",
+  turn_id: "uuid",
+  memory_written: { count: 3, items: [...], conflicts: [...] },
+  summary: { triggered: true, trigger_reason: "turn_threshold", text: "..." },
+  explain: { retention: [...], conflicts: [...], summary: {...} }
+}
+```
+
+### `SmartBrain.compose_context(session_id:, user_message:, agent_state: {}, domain_id: nil, scope_context: nil)`
+
+生成 `ContextPackage`，内部执行 5 阶段流水线：
+
+```
+Plan → Retrieve（双路并行）→ Fuse → Compose → ContextPackage
+```
+
+1. **Plan**：`RetrievalPlanner` 分析意图，生成 `RetrievalPlan`（主查询 + 扩展查询），自动判断是否启用资源检索（`enable_resource_retrieval: 'auto'` 时，关键词"查资料/引用/论文/文档/compare/对比/来源"触发）
+2. **Retrieve**：双路并行 —
+   - 记忆侧：`ExactRetriever`（词重叠匹配，支持中英文分词）+ `RelationalRetriever`（实体/引用关联）
+   - 资源侧：通过 SmartRAG 适配器检索文档资源（仅当 planner 启用时）
+3. **Fuse**：`Merger` 归一化 → 去重 → 词重叠加分重排 → 多样性约束（同文档 ≤ 3 条，同来源 ≤ 2 条）→ 预算裁剪（总条数 ≤ `evidence_max_items`，snippet ≤ `max_snippet_chars`）→ memory/resource 比例控制（默认 40/60）
+4. **Compose**：`ContextComposer` 按固定槽位装配：
+   ```
+   system_blocks → developer_blocks → working_summary →
+   recent_turns → evidence → user_message
+   ```
+5. **输出**：`ContextPackage`（经过契约校验）
+
+### 多 Scope 记忆
+
+0.2.0 支持在同一 domain 内联合读取 `global/project/expert/task` 记忆，并将长期记忆写入明确授权的 scope：
+
+```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' }
+}
+
+SmartBrain.commit_turn(
+  domain_id: 'tenant-a', session_id: 'conversation-1', scope_context: scope_context,
+  turn_events: { decisions: [{ key: 'decision:db', decision: 'use PostgreSQL' }] }
+)
+```
+
+`write` 必须是 `read` 的子集，`default_write` 必须包含在 `write` 中。单条结构化记忆可以用 `scope_ref` 覆盖默认写 scope，但目标仍须在 `write` 中。提供 `scope_context` 时必须同时提供 `domain_id`；两者都省略时继续使用隔离的 `legacy/session:<session_id>`，兼容 0.1.x 调用。
+
+**返回值（ContextPackage）：**
+
+```ruby
+{
+  version: '0.1',
+  context_id: "uuid",               # 本次装配唯一 ID
+  session_id: "...",
+  working_summary: "...",           # 滚动摘要文本
+  recent_turns: [...],              # 最近 N 轮对话
+  evidence: [                       # 融合后的证据列表
+    {
+      id: "...",
+      source: 'memory' | 'resource',
+      source_uri: "...",
+      title: "...",
+      snippet: "...",
+      mode: 'exact' | 'relational' | 'hybrid',
+      score: 0.85,
+      ref: { memory_item_id: "..." }
+    }
+  ],
+  user_message: { role: 'user', content: "..." },
+  constraints: {
+    token_budget: { limit: 8000, used_estimate: 1200 },
+    diversity: { by_document: 3, by_source: 2 },
+    truncation: { snippets_max_chars: 800, recent_turns_max: 8 }
+  },
+  debug: {
+    trace: { request_id: "uuid", plan_id: "uuid", context_id: "uuid" },
+    planner: { purpose: "qa", queries: ["..."] },
+    why_selected: ["item-1 score=0.85 source=memory"],
+    ignored: [],
+    dropped: [{ id: "...", reason: "diversity" }]
+  }
+}
+```
+
+### `SmartBrain.diagnostics`
+
+返回 compose/commit 观测日志与指标快照：
+
+```ruby
+{
+  compose_logs: [...],
+  commit_logs: [...],
+  metrics: {
+    compose_p95_ms: 45.2,
+    memory_resource_ratio: "3/2",
+    token_over_budget_rate: 0.0
+  }
+}
+```
+
+全链路追踪：每个请求有 `request_id` → `plan_id` → `context_id` 三连 ID，贯穿 Plan → Retrieve → Fuse → Compose 全流程。
+
+## 策略配置
+
+SmartBrain 的四类策略通过 `config/brain.yml` 配置：
+
+| 策略类别 | 生效点 | 关键参数 |
+|---------|--------|---------|
+| **Retention**（写入门控） | `commit_turn` | `entity_gate: { window_turns: 20, freq_threshold: 2 }`、`confidence: { user_asserted: 0.8, tool_derived: 0.9, inferred: 0.6 }`、`summarize_after_turns: 12` |
+| **Retrieval**（检索） | `compose_context` | `top_k: 30`、`candidate_k: 200`、`enable_resource_retrieval: auto`、`query_expansion: { enabled: true, max_queries: 8 }` |
+| **Composition**（装配） | `compose_context` | `recent_turns_max: 8`、`evidence_max_items: 12`、`max_snippet_chars: 800`、`diversity: { by_document: 3, by_source_uri: 2 }`、`memory_resource_ratio: "40/60"` |
+| **Observability**（可观测） | 全局 | `trace: true` |
+
+## 项目结构
+
+```
+lib/smart_brain.rb                          # Ruby 入口 API
+lib/smart_brain/version.rb                  # 版本号
+lib/smart_brain/configuration.rb            # YAML 配置加载
+lib/smart_brain/runtime.rb                  # 主运行时编排（commit_turn / compose_context）
+lib/smart_brain/contracts/                  # 契约校验
+  retrieval_plan.rb                         #   RetrievalPlan 校验
+  evidence_pack.rb                          #   EvidencePack 校验
+  context_package.rb                        #   ContextPackage 校验
+lib/smart_brain/event_store/
+  in_memory.rb                              # 事件存储（当前内存实现，含 entity_frequencies 统计）
+lib/smart_brain/memory_store/
+  in_memory.rb                              # 记忆存储（当前内存实现，含 upsert 冲突管理）
+lib/smart_brain/memory_extractor/
+  extractor.rb                              # 从事件中抽取结构化记忆（写入门控）
+lib/smart_brain/consolidator/
+  working_summary.rb                        # 滚动摘要维护（turn_threshold / token_pressure / stage_event 触发）
+lib/smart_brain/retrieval_planner/
+  planner.rb                                # 生成 RetrievalPlan（query expansion + 资源检索启停判断 + filter hints）
+lib/smart_brain/retrievers/
+  exact_retriever.rb                        # 词重叠关键词匹配（支持中英文）
+  relational_retriever.rb                   # 实体/引用关联检索
+  memory_retriever.rb                       # 记忆检索门面（exact + relational 合并）
+lib/smart_brain/fusion/
+  merger.rb                                 # 多源融合（归一化 → 去重 → 词重叠加分重排 → 多样性 → 预算截断）
+lib/smart_brain/context_composer/
+  composer.rb                               # 固定槽位上下文装配 + token 估算
+lib/smart_brain/adapters/smart_rag/
+  null_client.rb                            # 默认空适配器（资源证据为空）
+  http_client.rb                            # HTTP 远程调用适配器（支持超时降级）
+  direct_client.rb                          # 进程内直接调用适配器
+lib/smart_brain/observability/
+  tracker.rb                                # 日志与指标（P95 / memory_resource_ratio / token_over_budget_rate）
+config/
+  example_llm.yml                           # LLM 配置示例（ollama + silicon_flow）
+docs/
+  smartbrain_design.md                      # 总体设计文档
+  policies.md                               # 策略规范文档
+  memory_types.md                           # 记忆类型规范（9 种 type + key 规则）
+  context_package.md                        # ContextPackage 协议
+  retrieval_plan.md                         # RetrievalPlan 协议
+  evidence_pack.md                          # EvidencePack 协议
+spec/
+  spec_helper.rb
+  commit_turn_spec.rb                       # commit_turn 单元测试
+  compose_context_spec.rb                   # compose_context 单元测试
+  fusion_merger_spec.rb                     # 融合层测试
+  integration_smart_rag_adapter_spec.rb     # SmartRAG 适配器集成测试
+  observability_metrics_spec.rb             # 可观测性测试
+  planner_policy_spec.rb                    # 检索计划策略测试
+  regression_context_spec.rb                # 回归测试
+example.rb                                  # 简单示例
+conversation_demo.rb                        # 完整多轮对话演示（SmartBrain + SmartRAG + SmartAgent）
+```
+
+## 快速开始
+
+### 仅 SmartBrain（不依赖外部服务）
+
+```ruby
+require_relative 'lib/smart_brain'
+
+SmartBrain.configure
+
+SmartBrain.commit_turn(
+  session_id: 'demo',
+  turn_events: {
+    messages: [
+      { role: 'user', content: '请记住：默认数据库是 Postgres。' },
+      { role: 'assistant', content: '已记录。' }
+    ],
+    decisions: [
+      { key: 'decision:smartbrain:storage', decision: 'Use Postgres by default' }
+    ]
+  }
+)
+
+context = SmartBrain.compose_context(
+  session_id: 'demo',
+  user_message: '继续并总结关键结论'
+)
+
+puts context[:context_id]
+puts context.dig(:debug, :trace, :request_id)
+puts context.dig(:debug, :trace, :plan_id)
+```
+
+### 多轮对话循环（与 SmartAgent + SmartRAG 联动）
+
+```ruby
+require 'smart_brain'
+require 'smart_agent'
+require 'smart_rag'
+require_relative 'lib/smart_brain/adapters/smart_rag/direct_client'
+
+# 1. 初始化 SmartRAG
+rag = SmartRAG::SmartRAG.new(database: {...}, llm: {...})
+client = SmartBrain::Adapters::SmartRag::DirectClient.new(rag: rag)
+
+# 2. 初始化 SmartBrain
+SmartBrain.configure(smart_rag_client: client)
+
+# 3. 初始化 SmartAgent
+engine = SmartAgent::Engine.new('./config/example_agent.yml')
+agent = engine.build_agent(:brain_assistant)
+
+# 4. 多轮对话循环
+session_id = "demo-session"
+user_message = "Ruby 类名应该用什么命名风格？"
+
+# 4a. 获取上下文（内部可能调用 SmartRAG 检索文档资源）
+context = SmartBrain.compose_context(
+  session_id: session_id,
+  user_message: user_message,
+  agent_state: { turn: 1 }
+)
+
+# 4b. 调用 Agent（LLM）生成回复
+response = agent.please(context.to_json)
+
+# 4c. 提交本轮（沉淀记忆）
+commit = SmartBrain.commit_turn(
+  session_id: session_id,
+  turn_events: {
+    messages: [
+      { role: 'user', content: user_message },
+      { role: 'assistant', content: response.to_s }
+    ],
+    decisions: [
+      { key: 'decision:ruby:class_naming', decision: '使用 CamelCase' }
+    ],
+    entities: [
+      { key: 'entity:lang:ruby', name: 'Ruby', canonical: 'ruby', kind: 'language', remember: true }
+    ]
+  }
+)
+
+# 5. 查看诊断信息
+pp SmartBrain.diagnostics
+```
+
+## SmartRAG 集成方式
+
+### 1) NullClient（默认）
+
+不配置 `smart_rag_client` 时，资源证据为空，仅使用记忆侧证据。适合纯对话记忆场景。
+
+```ruby
+SmartBrain.configure  # 无需额外配置
+```
+
+### 2) HttpClient（HTTP 远程）
+
+通过自定义 transport lambda 调用远端 SmartRAG 服务，支持超时降级。
+
+```ruby
+transport = lambda do |plan, timeout_seconds:|
+  {
+    plan_id: 'p1',
+    supports_language_filter: true,
+    evidences: []
+  }
+end
+
+scope_mapper = lambda do |domain_id:, scopes:|
+  { filters: { topic_ids: scopes.map { |scope| "#{domain_id}:#{scope[:type]}:#{scope[:id]}" } } }
+end
+client = SmartBrain::Adapters::SmartRag::HttpClient.new(
+  transport: transport, timeout_seconds: 2, scope_mapper: scope_mapper
+)
+SmartBrain.configure(smart_rag_client: client)
+```
+
+### 3) DirectClient（进程内直接调用）
+
+直接依赖 `smart_rag` gem，进程内调用。需要配置 PostgreSQL 连接和 LLM。
+
+```ruby
+require 'smart_rag'
+require_relative 'lib/smart_brain/adapters/smart_rag/direct_client'
+
+rag_config = SmartRAG::Config.load(ENV.fetch('SMARTRAG_CONFIG_PATH'))
+rag = SmartRAG::SmartRAG.new(rag_config)
+scope_mapper = lambda do |domain_id:, scopes:|
+  { filters: { topic_ids: scopes.map { |scope| "#{domain_id}:#{scope[:type]}:#{scope[:id]}" } } }
+end
+client = SmartBrain::Adapters::SmartRag::DirectClient.new(rag: rag, scope_mapper: scope_mapper)
+
+SmartBrain.configure(smart_rag_client: client)
+```
+
+Mapper 返回的 `filters` 会作为 `scope_filters` 发送给 SmartRAG。业务 scope 存在时，后端必须返回 `scope_filter_applied: true`；mapper 缺失、映射失败或后端未确认时，adapter 默认 fail closed，丢弃资源证据并在 `warnings` 和 `explain.ignored_fields` 中说明原因。
+
+## 运行示例
+
+### example.rb
+
+SmartBrain + SmartAgent + SmartPrompt + SmartRAG 联动示例（2 轮对话）。
+
+```bash
+bundle exec ruby example.rb
+```
+
+依赖的本地文件：
+- `config/example_agent.yml`
+- `config/example_llm.yml`
+- `agents/brain_assistant.rb`
+- `workers/brain_assistant.rb`
+- `templates/brain_assistant.erb`
+
+### conversation_demo.rb
+
+完整多轮对话演示（5 轮），包含 SmartRAG 文档存储、检索、SmartAgent LLM 调用和 SmartBrain 记忆沉淀全流程。
+
+```bash
+bundle exec ruby conversation_demo.rb
+```
+
+## 测试
+
+```bash
+bundle exec rspec
+```
+
+测试覆盖 commit/compose、存储、治理、KG、协议适配、多 scope 隔离以及 PostgreSQL 迁移和持久化。
+
+## 常见问题
+
+### 1) `cannot load such file -- sequel/extensions/pgvector`
+
+当前示例已在 `example.rb` 做兼容处理（`Sequel.extension 'pgvector'` + 去除 `database.extensions` 连接参数）。
+
+### 2) `Config file not found: config/llm_config.yml`
+
+`example.rb` 已将 SmartRAG 里 EmbeddingService 的 `config_path` 注入为 `./config/example_llm.yml`。
+
+### 3) `ruby-lsp: not found`
+
+```bash
+gem install --user-install ruby-lsp debug
+```
+
+并将用户 gem bin 加入 `PATH`。
+
+## 路线图
+
+- 将 EventStore/MemoryStore 从内存实现切换到 Postgres 持久化实现
+- 接入真实 reranker / embedding 模型（当前为规则分 + 词重叠加分）
+- 完善 SmartRAG ingest 与跨会话评估工具
+- 扩展 `SemanticRetriever`（依赖 pgvector/embedding）
+- 支持 `memory_chunks` 表（FTS 索引 + 可选 embedding 字段）