smart_brain 0.1.2 → 0.2.0

data/example.rb

@@ -1,91 +1,91 @@
-# frozen_string_literal: true
-
-require 'logger'
-require 'json'
-
-# Follow smart_agent/test.rb style: load SmartPrompt first, then SmartAgent.
-require 'smart_prompt'
-require 'smart_agent'
-require_relative 'lib/smart_brain'
-require_relative 'lib/smart_brain/adapters/smart_rag/direct_client'
-
-begin
-  require 'smart_rag'
-rescue LoadError => e
-  warn "SmartRAG load failed: #{e.message}"
-  warn 'Please install SmartRAG dependencies (especially sequel/pg) before running this example.'
-  exit 1
-end
-
-rag_config = SmartRAG::Config.load("./config/smart_rag.yml")
-# SmartRAG config may include database.extensions with pgvector.
-# For Sequel, pgvector should be loaded globally via Sequel.extension.
-db_cfg = (rag_config[:database] || {}).dup
-db_exts = Array(db_cfg.delete(:extensions)).map(&:to_s)
-if db_exts.include?('pgvector')
-  require 'sequel'
-  Sequel.extension 'pgvector'
-end
-# SmartRAG currently passes database config into EmbeddingService.
-# Inject SmartPrompt config path here so EmbeddingService can boot correctly.
-db_cfg[:config_path] = File.expand_path('./config/example_llm.yml', __dir__)
-rag_config = rag_config.merge(database: db_cfg)
-
-rag = SmartRAG::SmartRAG.new(rag_config)
-rag_client = SmartBrain::Adapters::SmartRag::DirectClient.new(rag: rag)
-
-SmartBrain.configure(smart_rag_client: rag_client)
-engine = SmartAgent::Engine.new('./config/example_agent.yml')
-agent = engine.build_agent(:brain_assistant)
-
-session_id = 'smartagent-smartbrain-demo'
-user_messages = [
-  '请记住：SmartRAG 作为 SmartBrain 的底层基础库，提供存储与检索服务',
-  '继续这个话题，SmartBrain 默认使用哪种数据库？'
-]
-
-def build_worker_input(context, user_message)
-  {
-    context_id: context[:context_id],
-    working_summary: context[:working_summary],
-    recent_turns: context[:recent_turns],
-    evidence: context[:evidence],
-    latest_user_message: user_message,
-    constraints: context[:constraints]
-  }.to_json
-end
-
-user_messages.each_with_index do |user_message, idx|
-  # 1) SmartBrain composes context (will call SmartRAG when planner enables resource retrieval).
-  context = SmartBrain.compose_context(
-    session_id: session_id,
-    user_message: user_message,
-    agent_state: { agent: 'SmartAgent', turn: idx + 1 }
-  )
-
-  # 2) SmartAgent executes the real call_worker flow.
-  assistant_message = agent.please(build_worker_input(context, user_message))
-
-  # 3) SmartBrain commits this turn.
-  commit = SmartBrain.commit_turn(
-    session_id: session_id,
-    turn_events: {
-      messages: [
-        { role: 'user', content: user_message },
-        { role: 'assistant', content: assistant_message.to_s }
-      ],
-      decisions: (idx.zero? ? [{ key: 'decision:smartbrain:storage', decision: 'Use Postgres by default' }] : [])
-    }
-  )
-
-  resource_hits = Array(context[:evidence]).count { |e| e[:source] == 'resource' }
-  memory_hits = Array(context[:evidence]).count { |e| e[:source] == 'memory' }
-
-  puts "\n=== Turn #{idx + 1} ==="
-  puts "context_id: #{context[:context_id]}"
-  puts "request_id: #{context.dig(:debug, :trace, :request_id)}"
-  puts "plan_id: #{context.dig(:debug, :trace, :plan_id)}"
-  puts "commit_id: #{commit[:commit_id]}"
-  puts "evidence(memory/resource): #{memory_hits}/#{resource_hits}"
-  puts "assistant: #{assistant_message}"
-end
+# frozen_string_literal: true
+
+require 'logger'
+require 'json'
+
+# Follow smart_agent/test.rb style: load SmartPrompt first, then SmartAgent.
+require 'smart_prompt'
+require 'smart_agent'
+require_relative 'lib/smart_brain'
+require_relative 'lib/smart_brain/adapters/smart_rag/direct_client'
+
+begin
+  require 'smart_rag'
+rescue LoadError => e
+  warn "SmartRAG load failed: #{e.message}"
+  warn 'Please install SmartRAG dependencies (especially sequel/pg) before running this example.'
+  exit 1
+end
+
+rag_config = SmartRAG::Config.load("./config/smart_rag.yml")
+# SmartRAG config may include database.extensions with pgvector.
+# For Sequel, pgvector should be loaded globally via Sequel.extension.
+db_cfg = (rag_config[:database] || {}).dup
+db_exts = Array(db_cfg.delete(:extensions)).map(&:to_s)
+if db_exts.include?('pgvector')
+  require 'sequel'
+  Sequel.extension 'pgvector'
+end
+# SmartRAG currently passes database config into EmbeddingService.
+# Inject SmartPrompt config path here so EmbeddingService can boot correctly.
+db_cfg[:config_path] = File.expand_path('./config/example_llm.yml', __dir__)
+rag_config = rag_config.merge(database: db_cfg)
+
+rag = SmartRAG::SmartRAG.new(rag_config)
+rag_client = SmartBrain::Adapters::SmartRag::DirectClient.new(rag: rag)
+
+SmartBrain.configure(smart_rag_client: rag_client)
+engine = SmartAgent::Engine.new('./config/example_agent.yml')
+agent = engine.build_agent(:brain_assistant)
+
+session_id = 'smartagent-smartbrain-demo'
+user_messages = [
+  '请记住：SmartRAG 作为 SmartBrain 的底层基础库，提供存储与检索服务',
+  '继续这个话题，SmartBrain 默认使用哪种数据库？'
+]
+
+def build_worker_input(context, user_message)
+  {
+    context_id: context[:context_id],
+    working_summary: context[:working_summary],
+    recent_turns: context[:recent_turns],
+    evidence: context[:evidence],
+    latest_user_message: user_message,
+    constraints: context[:constraints]
+  }.to_json
+end
+
+user_messages.each_with_index do |user_message, idx|
+  # 1) SmartBrain composes context (will call SmartRAG when planner enables resource retrieval).
+  context = SmartBrain.compose_context(
+    session_id: session_id,
+    user_message: user_message,
+    agent_state: { agent: 'SmartAgent', turn: idx + 1 }
+  )
+
+  # 2) SmartAgent executes the real call_worker flow.
+  assistant_message = agent.please(build_worker_input(context, user_message))
+
+  # 3) SmartBrain commits this turn.
+  commit = SmartBrain.commit_turn(
+    session_id: session_id,
+    turn_events: {
+      messages: [
+        { role: 'user', content: user_message },
+        { role: 'assistant', content: assistant_message.to_s }
+      ],
+      decisions: (idx.zero? ? [{ key: 'decision:smartbrain:storage', decision: 'Use Postgres by default' }] : [])
+    }
+  )
+
+  resource_hits = Array(context[:evidence]).count { |e| e[:source] == 'resource' }
+  memory_hits = Array(context[:evidence]).count { |e| e[:source] == 'memory' }
+
+  puts "\n=== Turn #{idx + 1} ==="
+  puts "context_id: #{context[:context_id]}"
+  puts "request_id: #{context.dig(:debug, :trace, :request_id)}"
+  puts "plan_id: #{context.dig(:debug, :trace, :plan_id)}"
+  puts "commit_id: #{commit[:commit_id]}"
+  puts "evidence(memory/resource): #{memory_hits}/#{resource_hits}"
+  puts "assistant: #{assistant_message}"
+end

data/examples/01_memory_basic.rb

@@ -0,0 +1,57 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+#
+# 场景一：纯 memory 后端，零外部依赖。
+# 演示 SmartBrain 最小闭环：commit_turn → compose_context → search_memory → brief → diagnostics。
+# 进程内存储（重启即丢）；持久化见 03_postgres_persistence.rb。
+#
+# 运行： ruby examples/01_memory_basic.rb
+
+$LOAD_PATH.unshift(File.expand_path('../lib', __dir__))
+require 'smart_brain'
+
+def hr(title) = puts("\n=== #{title} ===")
+
+SmartBrain.configure
+sid = "mem-#{Process.pid}"
+
+hr '1) commit_turn：写一轮对话 + 结构化记忆 + KG 边'
+SmartBrain.commit_turn(
+  session_id: sid,
+  turn_events: {
+    messages: [{ role: 'user', content: '我们用 Postgres 做持久化，配 memory_chunks FTS' }],
+    decisions: [{ key: 'decision:db:storage', decision: '默认用 Postgres 持久化' }],
+    goals: [{ key: 'goal:ship:p2', goal: '完成 P2 知识图谱' }],
+    tasks: [{ key: 'task:kg', title: '实现 KG', status: 'doing' }],
+    entities: [{ key: 'entity:db:pg', name: 'Postgres', canonical: 'postgres', kind: 'db', remember: true }],
+    edges: [{ subject: 'postgres', predicate: 'uses', object: 'jsonb' }]
+  }
+)
+puts '✓ 已写入（decisions / goals / tasks / entities / kg_edge）'
+
+hr '2) compose_context：装配上下文（召回证据 + 摘要 + trace）'
+# 注：memory 后端用子串召回；FTS（pg 后端）对中文按字 unigram 命中更准。
+ctx = SmartBrain.compose_context(session_id: sid, user_message: 'Postgres 持久化方案')
+puts "working_summary:\n#{ctx[:working_summary]}"
+puts "evidence 命中 #{ctx[:evidence].size} 条："
+ctx[:evidence].first(5).each do |e|
+  puts "  - [#{e[:mode]}] #{e[:title]}  score=#{e[:score].round(2)}  tier=#{e[:tier]}"
+end
+puts "trace: #{ctx.dig(:debug, :trace).inspect}"
+
+hr '3) search_memory：直接搜记忆'
+puts "搜 'Postgres' → #{SmartBrain.search_memory(session_id: sid, query: 'Postgres').size} 条"
+
+hr '4) brief：citation-first 认知快照'
+b = SmartBrain.brief(session_id: sid)
+puts "key_facts #{b[:key_facts].size} 条，首条带引用："
+kf = b[:key_facts].first
+puts "  #{kf[:key]}  (tier=#{kf[:tier]}, source_turn=#{kf[:source_turn_id][0,8]}…, memory_item=#{kf[:memory_item_id][0,8]}…)"
+puts "unresolved=#{b[:unresolved].size}  next_actions=#{b[:next_actions].size}"
+
+hr '5) diagnostics：可观测性'
+d = SmartBrain.diagnostics
+puts "backend=#{d[:backend]}  compose_p95=#{d[:metrics][:compose_p95_ms]}ms  " \
+     "mem/res=#{d[:metrics][:memory_resource_ratio]}  over_budget=#{d[:metrics][:token_over_budget_rate]}"
+
+puts "\n✅ 场景一完成。memory 后端进程内存储，重启即丢 —— 想要持久化请看 03_postgres_persistence.rb。"

data/examples/02_governance.rb

@@ -0,0 +1,63 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+#
+# 场景二：记忆治理 —— 思维分层 + 知识生命周期 + KG + Fact-check + Brief。
+# memory 后端，零外部依赖。演示「记忆宫殿」的治理能力。
+#
+# 运行： ruby examples/02_governance.rb
+
+$LOAD_PATH.unshift(File.expand_path('../lib', __dir__))
+require 'smart_brain'
+
+def hr(title) = puts("\n=== #{title} ===")
+
+SmartBrain.configure
+sid = "gov-#{Process.pid}"
+
+hr '0) 先写几条 evidence（用作 distill 的支撑）'
+3.times do |i|
+  SmartBrain.commit_turn(session_id: sid, turn_events: {
+    decisions: [{ key: "decision:ev:#{i}", decision: "观察 #{i}：持久化用 Postgres 更稳" }]
+  })
+end
+refs = SmartBrain.search_memory(session_id: sid, query: '持久化 Postgres').map { |h| h[:id] }
+puts "✓ 写入 3 条 evidence，召回 #{refs.size} 条作为支撑"
+
+hr '1) distill：把 evidence 蒸馏成一条候选知识（tier=dao_ren）'
+d = SmartBrain.distill(session_id: sid, statement: '新存储默认走 Postgres',
+                       content: '所有新 store 实现都以 PG 为目标', tier: 'dao_ren',
+                       supporting_refs: refs)
+mid = d[:memory_item][:id]
+puts "✓ candidate id=#{mid[0,8]}…  tier=#{d[:memory_item][:tier]}  lifecycle=#{d[:memory_item][:lifecycle_status]}"
+
+hr '2) gate → promote：检查门槛并提升'
+gate = SmartBrain.gate(memory_item_id: mid)
+puts "gate ready=#{gate[:ready]}  (refs=#{gate[:checks][:supporting_refs]}, min=#{gate[:checks][:min_required]})"
+promoted = SmartBrain.promote(memory_item_id: mid, verification_refs: refs, reason: '多次验证一致')[:memory_item]
+puts "✓ promote → lifecycle=#{promoted[:lifecycle_status]}"
+
+hr '3) KG：加三元组、查询、失效'
+SmartBrain.kg_add(session_id: sid, subject: 'smart_brain', predicate: 'persists_via', object: 'postgres')
+puts "kg_query(persists_via)=#{SmartBrain.kg_query(session_id: sid, predicate: 'persists_via').map { |e| "#{e[:subject]}→#{e[:object]}" }.inspect}"
+edge = SmartBrain.kg_query(session_id: sid, subject: 'smart_brain').first
+SmartBrain.kg_invalidate(edge_id: edge[:id], reason: '换方案')
+puts "✓ invalidate 一条 → stats=#{SmartBrain.kg_stats(session_id: sid).inspect}"
+
+hr '4) fact_check：离线矛盾检测'
+SmartBrain.commit_turn(session_id: sid, turn_events: {
+  entities: [{ key: 'entity:p', name: 'Postgres', canonical: 'postgres', remember: true }],
+  edges: [{ subject: 'postgres', predicate: 'uses', object: 'jsonb' }]
+})
+r = SmartBrain.fact_check(session_id: sid, text: '我们停用了 postgres 的 jsonb')
+puts "findings=#{r[:counts].inspect}"
+r[:findings].each { |f| puts "  - [#{f[:type]}] #{f[:detail]}" }
+
+hr '5) knowledge_events：审计时间线'
+events = SmartBrain.knowledge_events(memory_item_id: mid)
+puts "事件链：#{events.map { |e| e[:event_type] }.inspect}"
+
+hr '6) wake_up：L0/L1 恢复负载'
+w = SmartBrain.wake_up(session_id: sid)
+puts "L0 identity=#{w[:l0][:identity].size}  L1 goals_decisions=#{w[:l1][:goals_decisions].size}"
+
+puts "\n✅ 场景二完成。distill→promote→demote 全流程 + KG 时态 + Fact-check + Brief 均可用。"

data/examples/03_postgres_persistence.rb

@@ -0,0 +1,63 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+#
+# 场景三：Postgres 持久化 —— 跨「重启」召回。
+# 演示：进程 A 写记忆 → 进程 B（新 Runtime，同一 DB）经 FTS 召回。
+#
+# 前置：本地 PG + smart_brain 角色/库。若没建，脚本会打印步骤并退出。
+#   sudo -u postgres createuser -d smart_brain
+#   sudo -u postgres psql -c "ALTER USER smart_brain PASSWORD 'smart_brain';"
+#   sudo -u postgres createdb -O smart_brain smart_brain_test
+#
+# 运行： SMARTBRAIN_DB_NAME=smart_brain_test ruby examples/03_postgres_persistence.rb
+
+$LOAD_PATH.unshift(File.expand_path('../lib', __dir__))
+require 'smart_brain'
+require 'smart_brain/db'
+
+def hr(title) = puts("\n=== #{title} ===")
+
+ENV['SMARTBRAIN_BACKEND'] = 'postgres'
+ENV['SMARTBRAIN_DB_NAME'] ||= 'smart_brain_test'
+
+config = SmartBrain::Configuration.load
+unless SmartBrain::DB.reachable?(config)
+  warn "✗ 连不上 Postgres（#{config.database_config[:host]}:#{config.database_config[:port]}/#{config.database_config[:database]}）。"
+  warn "  先建库：见脚本顶部注释或 docs/user_guide.md §10。"
+  exit 1
+end
+
+# 清场（保证可重复运行）
+db = SmartBrain::DB.connect(config)
+SmartBrain::DB.migrate(db)
+db.run('TRUNCATE kg_edges, knowledge_events, memory_chunks, memory_items, summaries, messages, ' \
+       'refs, tool_calls, turns, sessions, entities, entity_mentions RESTART IDENTITY CASCADE')
+SmartBrain::DB.disconnect!
+
+sid = 'pg-demo'
+
+hr '1) 进程 A：commit_turn 写入（含中文决策 + KG 边）'
+SmartBrain.configure
+SmartBrain.commit_turn(
+  session_id: sid,
+  turn_events: {
+    messages: [{ role: 'user', content: '记一下：SmartBrain 用 Postgres 做持久化' }],
+    decisions: [{ key: 'decision:pg:persist', decision: 'SmartBrain 用 Postgres 持久化记忆' }],
+    entities: [{ key: 'entity:db:pg', name: 'Postgres', canonical: 'postgres', remember: true }],
+    edges: [{ subject: 'smart_brain', predicate: 'persists_via', object: 'postgres' }]
+  }
+)
+puts '✓ 进程 A 写完，退出（模拟进程结束）'
+
+hr '2) 进程 B：全新 Runtime（同一 DB）—— 验证持久化'
+SmartBrain.configure # 模拟重启：构造全新的 Runtime，共享同一个 Postgres
+puts "backend=#{SmartBrain.storage_backend}"
+hits = SmartBrain.search_memory(session_id: sid, query: '持久化')
+puts "FTS 搜 '持久化' → #{hits.size} 条（mode=#{hits.first&.dig(:mode)}）"
+puts "kg_query → #{SmartBrain.kg_query(session_id: sid, subject: 'smart_brain').map { |e| "#{e[:predicate]} #{e[:object]}" }.inspect}"
+
+ctx = SmartBrain.compose_context(session_id: sid, user_message: '持久化方案是什么？')
+mem = ctx[:evidence].select { |e| e[:source] == 'memory' }
+puts "compose_context 召回 memory 证据 #{mem.size} 条（跨重启仍命中）"
+
+puts "\n✅ 场景三完成。记忆、KG 边、摘要均跨进程持久化。"

data/examples/04_ollama_llm.rb

@@ -0,0 +1,69 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+#
+# 场景四：Ollama LLM —— 真摘要 + rerank。
+# 演示 ModelProvider 接真实本地模型后：working_summary 走真摘要、Fusion 走 LLM rerank。
+#
+# 前置：本机 ollama 已起、装了某模型（默认用 llama2 —— 快、非思维链；qwen3 更强但慢）。
+#   ollama serve &  ollama pull llama2
+#
+# 运行： ruby examples/04_ollama_llm.rb
+#   换模型： SMARTBRAIN_LLM_MODEL=qwen3 ruby examples/04_ollama_llm.rb
+
+$LOAD_PATH.unshift(File.expand_path('../lib', __dir__))
+require 'smart_brain'
+require 'smart_brain/model_provider'
+require 'smart_brain/memory_store/in_memory'
+require 'smart_brain/consolidator/working_summary'
+
+def hr(title) = puts("\n=== #{title} ===")
+
+base_url = ENV.fetch('SMARTBRAIN_LLM_BASE_URL', 'http://localhost:11434')
+model = ENV.fetch('SMARTBRAIN_LLM_MODEL', 'llama2')
+
+unless system("curl -s -m 2 #{base_url}/api/tags >/dev/null 2>&1")
+  warn "✗ 连不上 ollama（#{base_url}）。先 ollama serve 并 ollama pull #{model}。"
+  exit 1
+end
+
+provider = SmartBrain::ModelProvider::Ollama.new(
+  model: model, base_url: base_url, temperature: 0.2, timeout_seconds: 180, think: false
+)
+puts "provider=#{provider.class} model=#{model} llm?=#{provider.llm?}"
+
+hr '1) complete：让模型回答'
+r = provider.complete(prompt: '用一句话说明 PostgreSQL 的 FTS。', max_tokens: 120)
+puts "回答：#{r[:text].strip[0, 200]}"
+
+hr '2) rerank：LLM-as-judge 重排候选'
+docs = [
+  '埃菲尔铁塔在巴黎。',
+  'PostgreSQL 支持 JSONB 与全文检索（FTS）。',
+  'Ruby 是一种动态语言。'
+]
+ranked = provider.rerank(query: '关系型数据库的全文检索', documents: docs)
+puts '按相关性重排：'
+ranked.each { |x| puts "  [#{x[:index]}] score=#{x[:score].round(2)} :: #{docs[x[:index]][0, 40]}" }
+
+hr '3) working_summary：真摘要（带模板兜底）'
+store = SmartBrain::MemoryStore::InMemory.new
+store.upsert(session_id: 's', items: [
+  { type: 'decisions', key: 'decision:db', value_json: { decision: '用 Postgres 持久化' },
+    confidence: 0.8, status: 'active', tier: 'dao_ren', lifecycle_status: 'raw', updated_at: Time.now.utc.iso8601 },
+  { type: 'tasks', key: 'task:mcp', value_json: { title: '加 MCP server' },
+    confidence: 0.9, status: 'active', tier: 'shu', lifecycle_status: 'raw', updated_at: Time.now.utc.iso8601 }
+])
+ws = SmartBrain::Consolidator::WorkingSummary.new(
+  config: SmartBrain::Configuration.load, clock: -> { Time.now.utc },
+  memory_store: store, model_provider: provider
+)
+summary = ws.update(
+  session_id: 's', turn_count: 1, stage_event: true,
+  recent_turns: [{ role: 'user', content: '用 Postgres' }, { role: 'assistant', content: '好，持久化到 memory_chunks' }],
+  memory_items: store.active_items(session_id: 's')
+)
+puts "summary_method=#{summary[:summary_method]}"
+puts "摘要：\n#{summary[:text]}"
+
+puts "\n✅ 场景四完成。stub→ollama 后 summary/rerank 走真实模型（超时/截断自动降级到模板/词法）。"
+puts "   注：思维链模型（qwen3/deepseek-r1）同步较慢，本示例默认 llama2；换 qwen3 用 SMARTBRAIN_LLM_MODEL=qwen3。"

data/examples/05_smart_rag_integration.rb

@@ -0,0 +1,79 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+#
+# 场景五：SmartBrain + SmartRAG —— 对话记忆 + 资源检索融合。
+# SmartBrain 管对话记忆/治理，SmartRAG 管文档/网页 RAG；compose_context 命中「查资料/引用」
+# 意图时自动调用 SmartRAG，再由 Fusion 统一去重 + rerank + diversity。
+#
+# 前置（缺任一则脚本会打印步骤并优雅退出）：
+#   1) SmartRAG gem 已装（bundle 里已有 smart_rag）。
+#   2) SmartRAG 的数据库可连（默认读下方 env）。
+#   3) （可选）embedding/llm 配置。
+#   完整可运行版见仓库根目录 conversation_demo.rb。
+#
+# 运行：
+#   SMARTBRAIN_RAG_DB_HOST=127.0.0.1 \
+#   SMARTBRAIN_RAG_DB_NAME=smart_rag_development \
+#   SMARTBRAIN_RAG_DB_USER=rag_user SMARTBRAIN_RAG_DB_PASSWORD=rag_pwd \
+#   ruby examples/05_smart_rag_integration.rb
+
+$LOAD_PATH.unshift(File.expand_path('../lib', __dir__))
+require 'smart_brain'
+require 'smart_brain/adapters/smart_rag/direct_client'
+
+def hr(title) = puts("\n=== #{title} ===")
+
+begin
+  require 'smart_rag'
+rescue LoadError => e
+  warn "✗ 加载 smart_rag 失败：#{e.message}"
+  warn "  请先确保 smart_rag gem 可用（bundle 里已声明）。"
+  exit 1
+end
+
+rag_config = {
+  database: {
+    adapter: 'postgresql',
+    host: ENV.fetch('SMARTBRAIN_RAG_DB_HOST', '127.0.0.1'),
+    port: ENV.fetch('SMARTBRAIN_RAG_DB_PORT', '5432').to_i,
+    database: ENV.fetch('SMARTBRAIN_RAG_DB_NAME', 'smart_rag_development'),
+    user: ENV.fetch('SMARTBRAIN_RAG_DB_USER', 'rag_user'),
+    password: ENV.fetch('SMARTBRAIN_RAG_DB_PASSWORD', 'rag_pwd')
+  }
+}
+
+rag =
+  begin
+    SmartRAG::SmartRAG.new(rag_config)
+  rescue StandardError => e
+    warn "✗ SmartRAG 初始化失败：#{e.class}: #{e.message}"
+    warn "  检查上方数据库 env，或参考仓库根目录 conversation_demo.rb 的完整配置（含 llm/embedding）。"
+    exit 1
+  end
+
+# 挂载资源后端
+SmartBrain.configure(smart_rag_client: SmartBrain::Adapters::SmartRag::DirectClient.new(rag: rag))
+sid = "rag-#{Process.pid}"
+
+hr '1) commit_turn：写一轮对话记忆'
+SmartBrain.commit_turn(
+  session_id: sid,
+  turn_events: {
+    messages: [{ role: 'user', content: '帮我查一下 Ruby 命名规范的资料' }],
+    goals: [{ key: 'goal:learn:ruby', goal: '学习 Ruby 规范' }]
+  }
+)
+puts '✓ 对话记忆已写'
+
+hr '2) compose_context：命中「查资料」意图 → 调 SmartRAG + 融合'
+ctx = SmartBrain.compose_context(session_id: sid, user_message: '查一下 Ruby 命名规范并给出引用')
+mem = ctx[:evidence].count { |e| e[:source] == 'memory' }
+res = ctx[:evidence].count { |e| e[:source] == 'resource' }
+puts "evidence：memory=#{mem}  resource=#{res}  (memory/resource 比 = #{SmartBrain.diagnostics[:metrics][:memory_resource_ratio]})"
+puts "资源检索是否触发：#{ctx.dig(:debug, :planner, :purpose) == 'research' ? '是（purpose=research）' : '否'}"
+ctx[:evidence].first(3).each do |e|
+  puts "  - [#{e[:source]}] #{e[:title]}  score=#{e[:score].round(2)}"
+end
+
+puts "\n✅ 场景五完成。SmartBrain 记忆 + SmartRAG 资源在 Fusion 层统一融合。"
+puts "   若上方 resource=0：往 SmartRAG 灌点文档（rag.add_document ...），或换一个明显命中资源检索的 query。"

data/examples/06_multi_scope_memory.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require 'smart_brain'
+
+SmartBrain.configure
+
+domain_id = 'demo-domain'
+project_ref = { type: 'project', id: 'project-001' }
+task_ref = { type: 'task', id: 'task-030' }
+scope_context = {
+  read: [{ type: 'global', id: 'default' }, project_ref, task_ref],
+  write: [project_ref, task_ref],
+  default_write: task_ref
+}
+
+source = SmartBrain.commit_turn(
+  domain_id: domain_id,
+  session_id: 'writer-session',
+  scope_context: scope_context,
+  turn_events: {
+    decisions: [{ key: 'decision:database', decision: 'Use PostgreSQL for this task' }]
+  }
+).dig(:memory_written, :items).first
+
+promotion = SmartBrain.promote_to_scope(
+  memory_item_id: source[:id],
+  target_scope: project_ref,
+  domain_id: domain_id,
+  session_id: 'writer-session',
+  scope_context: scope_context,
+  verification_refs: ['architecture-review-001'],
+  reason: 'Confirmed as a project-wide decision',
+  reviewer: 'human'
+)
+
+reader_context = {
+  read: [{ type: 'global', id: 'default' }, project_ref, { type: 'task', id: 'task-031' }],
+  write: [{ type: 'task', id: 'task-031' }],
+  default_write: { type: 'task', id: 'task-031' }
+}
+context = SmartBrain.compose_context(
+  domain_id: domain_id,
+  session_id: 'reader-session',
+  scope_context: reader_context,
+  user_message: 'Which database did the project choose?'
+)
+
+puts "Promoted item: #{promotion.dig(:memory_item, :id)}"
+puts "Recalled scopes: #{context[:evidence].map { |item| item[:scope] }.compact.inspect}"
+puts "Lineage: #{SmartBrain.promotion_lineage(memory_item_id: promotion.dig(:memory_item, :id)).map { |item| item[:id] }.inspect}"

data/examples/README.md

@@ -0,0 +1,49 @@
+# SmartBrain 示例集
+
+每个脚本都是**自包含、可独立运行**的，从易到难、按需引入外部依赖。
+全部默认零外部依赖即可起步；PG / Ollama / SmartRAG 按场景按需开启。
+
+## 场景速查
+
+| 脚本 | 场景 | 依赖 | 后端 |
+|---|---|---|---|
+| [`01_memory_basic.rb`](01_memory_basic.rb) | 最小闭环：commit→compose→search→brief→diagnostics | 无 | memory |
+| [`02_governance.rb`](02_governance.rb) | 记忆治理：lifecycle + KG + fact_check + brief | 无 | memory |
+| [`03_postgres_persistence.rb`](03_postgres_persistence.rb) | 跨「重启」持久化召回 | PostgreSQL | postgres |
+| [`04_ollama_llm.rb`](04_ollama_llm.rb) | LLM 真摘要 + rerank | Ollama | memory |
+| [`05_smart_rag_integration.rb`](05_smart_rag_integration.rb) | 对话记忆 + 资源 RAG 融合 | SmartRAG | memory |
+| [`06_multi_scope_memory.rb`](06_multi_scope_memory.rb) | project/task 跨会话共享、冲突与 promotion | 无 | memory |
+
+## 运行
+
+```bash
+cd /root/smart_brain
+
+ruby examples/01_memory_basic.rb            # 直接跑，无需任何配置
+ruby examples/02_governance.rb              # 直接跑
+
+SMARTBRAIN_DB_NAME=smart_brain_test \
+  ruby examples/03_postgres_persistence.rb  # 需先建库（见脚本顶部注释）
+
+ruby examples/04_ollama_llm.rb              # 需 ollama serve + ollama pull llama2
+SMARTBRAIN_LLM_MODEL=qwen3 ruby examples/04_ollama_llm.rb   # 换更强的模型（更慢）
+
+SMARTBRAIN_RAG_DB_HOST=... SMARTBRAIN_RAG_DB_NAME=smart_rag_development \
+  ruby examples/05_smart_rag_integration.rb # 需 SmartRAG 实例
+  ruby examples/06_multi_scope_memory.rb
+```
+
+> 没装对应依赖时，03/04/05 会**打印设置步骤并优雅退出**（不会崩）。
+
+## 阅读顺序建议
+
+1. `01_memory_basic.rb` —— 先建立 commit/compose 心智模型。
+2. `02_governance.rb` —— 理解「记忆宫殿」的分层与生命周期。
+3. 按需挑 03/04/05 之一看持久化、LLM、资源检索如何接入。
+
+## 参考文档
+
+- 完整用法：[`../docs/user_guide.md`](../docs/user_guide.md)
+- MCP 接入：[`../docs/mcp.md`](../docs/mcp.md)
+- 设计与契约：`../docs/smartbrain_design.md`、`../docs/memory_types.md`、`../docs/policies.md`
+- 完整 SmartRAG 集成 demo：`../conversation_demo.rb`、`../example.rb`