smart_brain 0.1.1 → 0.2.0

data/README.en.md

@@ -101,10 +101,10 @@ SmartBrain.configure(smart_rag_client: client)
 ### 3) DirectClient (used in `example.rb`)
 
 ```ruby
-require '/home/mlf/smart_ai/smart_rag/lib/smart_rag'
+require 'smart_rag'
 require_relative 'lib/smart_brain/adapters/smart_rag/direct_client'
 
-rag_config = SmartRAG::Config.load('/home/mlf/smart_ai/smart_rag/config/smart_rag.yml')
+rag_config = SmartRAG::Config.load(ENV.fetch('SMARTRAG_CONFIG_PATH'))
 rag = SmartRAG::SmartRAG.new(rag_config)
 client = SmartBrain::Adapters::SmartRag::DirectClient.new(rag: rag)
 

data/README.md

@@ -1,38 +1,37 @@
 # SmartBrain
 
-SmartBrain 是一个面向 Agent 的记忆运行时（Memory Runtime）与上下文编排器（Context Composer）。
+SmartBrain（v0.2.0）是一个面向 Agent 的**记忆运行时（Memory Runtime）与上下文编排器（Context Composer）**。
 
-它的核心职责：
-- `commit_turn`：记录事件真相并沉淀结构化记忆
-- `compose_context`：在每轮请求前组装最小充分上下文
-- 联动 SmartRAG：对话记忆由 SmartBrain 管理，资源检索由 SmartRAG 提供
+在多轮 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
-- 融合层：去重、规则重排、多样性、预算截断
-- 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/`：设计与协议文档
+- `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 回归）
 
 ## 安装
 
@@ -40,14 +39,239 @@ SmartBrain 是一个面向 Agent 的记忆运行时（Memory Runtime）与上下
 bundle install
 ```
 
-如遇本地权限或 shared gem 污染，建议：
+如遇本地权限或 shared gem 污染：
 
 ```bash
 bundle config set --local path 'vendor/bundle'
 bundle config set --local disable_shared_gems 'true'
 ```
 
-## 快速开始（仅 SmartBrain）
+## 核心 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'
@@ -77,13 +301,73 @@ 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` 时，资源证据为空，仅使用记忆侧证据。
+不配置 `smart_rag_client` 时，资源证据为空，仅使用记忆侧证据。适合纯对话记忆场景。
+
+```ruby
+SmartBrain.configure  # 无需额外配置
+```
 
-### 2) HttpClient
+### 2) HttpClient（HTTP 远程）
+
+通过自定义 transport lambda 调用远端 SmartRAG 服务，支持超时降级。
 
 ```ruby
 transport = lambda do |plan, timeout_seconds:|
@@ -94,80 +378,90 @@ transport = lambda do |plan, timeout_seconds:|
   }
 end
 
-client = SmartBrain::Adapters::SmartRag::HttpClient.new(transport: transport, timeout_seconds: 2)
+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（当前示例使用）
+### 3) DirectClient（进程内直接调用）
+
+直接依赖 `smart_rag` gem，进程内调用。需要配置 PostgreSQL 连接和 LLM。
 
 ```ruby
-require '/home/mlf/smart_ai/smart_rag/lib/smart_rag'
+require 'smart_rag'
 require_relative 'lib/smart_brain/adapters/smart_rag/direct_client'
 
-rag_config = SmartRAG::Config.load('/home/mlf/smart_ai/smart_rag/config/smart_rag.yml')
+rag_config = SmartRAG::Config.load(ENV.fetch('SMARTRAG_CONFIG_PATH'))
 rag = SmartRAG::SmartRAG.new(rag_config)
-client = SmartBrain::Adapters::SmartRag::DirectClient.new(rag: rag)
+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)
 ```
 
-## example.rb 说明（已更新）
+Mapper 返回的 `filters` 会作为 `scope_filters` 发送给 SmartRAG。业务 scope 存在时，后端必须返回 `scope_filter_applied: true`；mapper 缺失、映射失败或后端未确认时，adapter 默认 fail closed，丢弃资源证据并在 `warnings` 和 `explain.ignored_fields` 中说明原因。
 
-`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`
+### example.rb
 
-运行：
+SmartBrain + SmartAgent + SmartPrompt + SmartRAG 联动示例（2 轮对话）。
 
 ```bash
 bundle exec ruby example.rb
 ```
 
-## 核心 API
-
-### `SmartBrain.configure(config_path: nil, smart_rag_client: nil, clock: -> { Time.now.utc })`
-初始化运行时并注入 SmartRAG 客户端（可选）。
+依赖的本地文件：
+- `config/example_agent.yml`
+- `config/example_llm.yml`
+- `agents/brain_assistant.rb`
+- `workers/brain_assistant.rb`
+- `templates/brain_assistant.erb`
 
-### `SmartBrain.commit_turn(session_id:, turn_events:)`
-写入事件、抽取记忆、冲突处理、摘要更新。
+### conversation_demo.rb
 
-### `SmartBrain.compose_context(session_id:, user_message:, agent_state: {})`
-生成 `ContextPackage`，内部包含检索计划与证据融合结果。
+完整多轮对话演示（5 轮），包含 SmartRAG 文档存储、检索、SmartAgent LLM 调用和 SmartBrain 记忆沉淀全流程。
 
-### `SmartBrain.diagnostics`
-返回 compose/commit 观测日志与指标快照。
+```bash
+bundle exec ruby conversation_demo.rb
+```
 
 ## 测试
 
 ```bash
-rspec
+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 模型
+- 将 EventStore/MemoryStore 从内存实现切换到 Postgres 持久化实现
+- 接入真实 reranker / embedding 模型（当前为规则分 + 词重叠加分）
 - 完善 SmartRAG ingest 与跨会话评估工具
+- 扩展 `SemanticRetriever`（依赖 pgvector/embedding）
+- 支持 `memory_chunks` 表（FTS 索引 + 可选 embedding 字段）

data/config/brain.yml

@@ -1,4 +1,69 @@
+# SmartBrain 运行时配置（映射 docs/policies.md §6 默认策略）
+#
+# 存储：默认 memory（零依赖，开发/测试/纯库用法）；
+# 切到 postgres 即启用 EventStore/MemoryStore 持久化与 memory_chunks FTS。
+#   backend 也可用环境变量 SMARTBRAIN_BACKEND 覆盖。
+#   数据库连接可用 SMARTBRAIN_DB_{HOST,PORT,NAME,USER,PASSWORD} 覆盖。
+
+storage:
+  backend: memory
+  database:
+    adapter: postgres
+    host: 127.0.0.1
+    port: 5432
+    database: smart_brain_development
+    user: smart_brain
+    password: smart_brain
+    # 用于 search_memory 的 FTS 文本搜索配置（内置 'simple'，零扩展依赖）。
+    # 中文通过分词后的 chunk 文本在 simple 下命中；如装了 pg_jieba 可改为 'jieba'。
+    fts_config: simple
+
+# 本地模型调用（兑现 smartbrain_design.md §9）。
+# 默认 stub：确定性、零网络（summary 走模板、rerank 走词法）。
+# 切 ollama / openai 后，working_summary 走真摘要、merger 走 LLM rerank。
+model_provider:
+  provider: stub            # stub | ollama | openai   (env: SMARTBRAIN_LLM_PROVIDER)
+  model: qwen3
+  base_url: http://localhost:11434
+  api_key: ""               # openai-compatible 提供商需要
+  rerank_model: qwen3       # rerank 走 complete（LLM-as-judge），用同一模型
+  temperature: 0.2
+  timeout_seconds: 120      # 思维链模型较慢，摘要调用给足超时
+  summary_max_tokens: 900
+  think: false              # 关闭思维链（支持的 ollama 版本会更快更干净）
+  rerank_enabled: false     # compose 时是否做 LLM rerank（每轮都跑，默认关；改 true 启用）
+
+# 思维分层（mempal mind model）：dao_tian 天道 / dao_ren 人道 / shu 术 / qi 器 / evidence 证据
+tiers:
+  dao_tian_limit: 1         # 自动装配时 dao_tian（不可变原则）默认最多注入条数
+
+# 知识生命周期（Stage-1）：evidence → distill(candidate) → gate → promote → demote/retire
+lifecycle:
+  min_supporting_refs: 2    # distill/promote 门槛：至少 N 条 evidence 支撑（reviewer=human 可豁免）
+
+# 知识图谱（KG）：三元组 + 时态有效性，与 memory_items/lifecycle 正交
+kg:
+  default_confidence: 0.6
+  expand_retrieval: true    # relational 检索匹配 entity 时是否顺带拉其 KG 边
+
+# 事实核查（离线、零 LLM）
+fact_check:
+  similar_name_distance: 2  # Levenshtein ≤ 此值视为同名冲突
+  negation_cues: ["not", "stopped", "no longer", "replaced", "never", "不", "不再", "停用", "弃用", "替换"]
+
+# Brief / wake-up（确定性、citation-first、不写 DB）
+briefing:
+  key_facts_max: 8
+  uncertainty_threshold: 0.6
+  recent_turns: 6
+
 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
+
   retention:
     summarize_after_turns: 12
     entity_gate:
@@ -8,6 +73,7 @@ policies:
       user_asserted: 0.8
       tool_derived: 0.9
       inferred: 0.6
+
   retrieval:
     enable_resource_retrieval: auto
     top_k: 30
@@ -15,6 +81,7 @@ policies:
     query_expansion:
       enabled: true
       max_queries: 8
+
   composition:
     token_limit: 8192
     system_blocks_max_tokens: 800
@@ -25,7 +92,8 @@ policies:
     diversity:
       by_document: 3
       by_source_uri: 2
-      memory_resource_ratio: '40/60'
+      memory_resource_ratio: "40/60"
+
   observability:
     trace: true
     store_plans: true

data/conversation_demo.rb

@@ -14,7 +14,7 @@ require 'logger'
 require 'json'
 
 # 环境变量配置 - 使用轨迹流动 Kimi-K2.5 模型
-ENV['SMARTRAG_DB_HOST'] ||= 'localhost'
+ENV['SMARTRAG_DB_HOST'] ||= '192.168.1.48'
 ENV['SMARTRAG_DB_PORT'] ||= '5432'
 ENV['SMARTRAG_DB_NAME'] ||= 'smart_rag_development'
 ENV['SMARTRAG_DB_USER'] ||= 'rag_user'
@@ -23,7 +23,7 @@ ENV['EMBEDDING_MODEL'] = 'qwen3-embedding'
 
 # 硅基流动 API 配置
 SILICON_FLOW_API_KEY = ENV['SILICON_FLOW_API_KEY']
-SILICON_FLOW_ENDPOINT = ENV['SILICON_FLOW_ENDPOINT']
+SILICON_FLOW_ENDPOINT = "https://api.siliconflow.cn/v1/"
 SILICON_FLOW_MODEL = 'Pro/moonshotai/Kimi-K2.5'
 
 # 加载依赖
@@ -41,7 +41,7 @@ rescue LoadError
 end
 
 begin
-  require '/home/mlf/smart_ai/smart_rag/lib/smart_rag'
+  require 'smart_rag'
 rescue LoadError => e
   warn "SmartRAG load failed: #{e.message}"
   exit 1
@@ -63,7 +63,7 @@ null_logger = Logger.new(File.open(File::NULL, 'w'))
 rag_config = {
   database: {
     adapter: 'postgresql',
-    host: ENV['SMARTRAG_DB_HOST'] || 'localhost',
+    host: ENV['SMARTRAG_DB_HOST'] || '192.168.1.48',
     port: (ENV['SMARTRAG_DB_PORT'] || '5432').to_i,
     database: ENV['SMARTRAG_DB_NAME'] || 'smart_rag_development',
     user: ENV['SMARTRAG_DB_USER'] || 'rag_user',
@@ -78,7 +78,7 @@ rag_config = {
   },
   # Embedding 配置 - 禁用（轨迹流动暂不支持 embedding）
   embedding: {
-    config_path: '/home/mlf/smart_ai/smart_rag/config/llm_config.yml'
+    config_path: File.expand_path('./config/llm_config.yml', __dir__)
   },
   # 禁用所有 SmartRAG 内部日志输出
   logger: null_logger

data/db/migrate/002_turn_events_payload.sql

@@ -0,0 +1,9 @@
+-- SmartBrain v0.1.1: persist the full per-turn events payload (JSONB).
+--
+-- Why: the runtime computes entity-gate frequencies from the *candidate*
+-- entities a caller passes in each turn_events (before any gating decision).
+-- The normalized tables (messages / refs / entity_mentions) don't capture
+-- that raw input, so we store the normalized turn_events blob here to let
+-- EventStore::Postgres faithfully reproduce EventStore::InMemory semantics.
+
+ALTER TABLE turns ADD COLUMN IF NOT EXISTS events_json JSONB NOT NULL DEFAULT '{}'::jsonb;