smart_brain 0.1.1 → 0.2.0

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`

data/exe/smart_brain

@@ -0,0 +1,168 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# SmartBrain CLI — drive the memory runtime from the shell or as an agent tool.
+#
+#   smart_brain status
+#   smart_brain migrate                         (postgres backend only)
+#   smart_brain commit   --data '{"session_id":..,"turn_events":{..}}'
+#   smart_brain compose  --data '{"session_id":..,"user_message":..}'
+#   smart_brain search   --data '{"session_id":..,"query":..}'
+#   smart_brain serve    [--host 0.0.0.0] [--port 9292] [--config PATH]
+#   smart_brain mcp      [--config PATH]        (stdio JSON-RPC, for Claude Code / Cursor)
+
+$LOAD_PATH.unshift(File.expand_path('../lib', __dir__))
+
+require 'optparse'
+require 'json'
+require 'smart_brain'
+require 'smart_brain/server/service'
+require 'smart_brain/server/http_app'
+require 'smart_brain/server/mcp_server'
+
+module SmartBrain
+  module CLI
+    module_function
+
+    def run(argv)
+      config_path = ENV['SMARTBRAIN_CONFIG']
+      global = OptionParser.new do |opts|
+        opts.banner = 'Usage: smart_brain <command> [options]'
+        opts.on('--config PATH', 'Path to brain.yml') { |p| config_path = p }
+        opts.on('--version', 'Print version and exit') { puts SmartBrain::VERSION; exit 0 }
+        opts.on('-h', '--help', 'Show this help') { puts opts; exit 0 }
+      end
+      global.order!(argv)
+
+      command = argv.shift
+      abort(global.to_s) unless command
+
+      case command
+      when 'status'  then print_json(Server::Service.build(config_path: config_path).status)
+      when 'migrate' then print_json(ok: Server::Service.build(config_path: config_path).migrate)
+      when 'commit', 'compose', 'search', 'fact-check', 'brief', 'wake-up'
+        data_cmd(command, argv, config_path)
+      when 'knowledge' then knowledge_cmd(argv, config_path)
+      when 'kg' then kg_cmd(argv, config_path)
+      when 'serve'   then serve(argv, config_path)
+      when 'mcp'     then mcp(config_path)
+      else
+        warn "unknown command: #{command}"
+        warn global.to_s
+        exit 1
+      end
+    end
+
+    def data_cmd(command, argv, config_path)
+      options = {}
+      parser = OptionParser.new do |opts|
+        opts.on('--data JSON', 'JSON payload (or read from stdin)') { |j| options[:data] = j }
+        opts.on('-h', '--help') { puts opts; exit 0 }
+      end
+      parser.parse!(argv)
+
+      payload = read_payload(options[:data])
+      service = Server::Service.build(config_path: config_path)
+      result =
+        case command
+        when 'commit' then service.commit(**payload.slice(:domain_id, :session_id, :scope_context, :turn_events).merge(turn_events: payload[:turn_events] || {}))
+        when 'compose' then service.compose(**payload.slice(:domain_id, :session_id, :scope_context, :user_message, :agent_state).merge(agent_state: payload[:agent_state] || {}))
+        when 'search' then service.search(**payload.slice(:domain_id, :session_id, :scope_context, :query, :limit))
+        when 'fact-check' then service.fact_check(**payload.slice(:domain_id, :session_id, :scope_context, :text))
+        when 'brief' then service.brief(**payload.slice(:domain_id, :session_id, :scope_context, :query))
+        when 'wake-up' then service.wake_up(**payload.slice(:domain_id, :session_id, :scope_context))
+        end
+      print_json(result)
+    end
+
+    def knowledge_cmd(argv, config_path)
+      options = {}
+      OptionParser.new do |opts|
+        opts.banner = 'usage: smart_brain knowledge <distill|gate|promote|demote|retract|promote-to-scope|lineage|events> --data JSON'
+        opts.on('--data JSON', 'JSON payload (or read from stdin)') { |j| options[:data] = j }
+        opts.on('-h', '--help') { puts opts; exit 0 }
+      end.parse!(argv)
+
+      action = argv.shift
+      abort 'usage: smart_brain knowledge <distill|gate|promote|demote|retract|promote-to-scope|lineage|events> --data JSON' unless action
+
+      payload = read_payload(options[:data])
+      service = Server::Service.build(config_path: config_path)
+      result =
+        case action
+        when 'distill' then service.distill(**payload.slice(:domain_id, :session_id, :scope_context, :statement, :content, :tier, :supporting_refs, :domain, :field, :reviewer, :key))
+        when 'gate' then service.gate(**payload.slice(:memory_item_id, :domain_id, :session_id, :scope_context))
+        when 'promote' then service.promote(**payload.slice(:memory_item_id, :domain_id, :session_id, :scope_context, :verification_refs, :reason, :reviewer, :force))
+        when 'demote' then service.demote(**payload.slice(:memory_item_id, :domain_id, :session_id, :scope_context, :evidence_refs, :reason, :reason_type, :reviewer))
+        when 'retract' then service.retract(**payload.slice(:memory_item_id, :domain_id, :session_id, :scope_context, :evidence_refs, :reason, :reviewer))
+        when 'promote-to-scope' then service.promote_to_scope(**payload.slice(:memory_item_id, :target_scope, :domain_id, :session_id, :scope_context, :verification_refs, :reason, :reviewer))
+        when 'lineage' then service.promotion_lineage(**payload.slice(:memory_item_id, :domain_id, :session_id, :scope_context))
+        when 'events' then service.knowledge_events(**payload.slice(:memory_item_id, :domain_id, :session_id, :scope_context))
+        else abort "unknown knowledge action: #{action}"
+        end
+      print_json(result)
+    rescue SmartBrain::Governance::LifecycleGateError, ArgumentError => e
+      warn "#{e.class}: #{e.message}"
+      exit 1
+    end
+
+    def kg_cmd(argv, config_path)
+      options = {}
+      OptionParser.new do |opts|
+        opts.banner = 'usage: smart_brain kg <add|query|timeline|invalidate|stats> --data JSON'
+        opts.on('--data JSON', 'JSON payload (or read from stdin)') { |j| options[:data] = j }
+        opts.on('-h', '--help') { puts opts; exit 0 }
+      end.parse!(argv)
+      action = argv.shift
+      abort 'usage: smart_brain kg <add|query|timeline|invalidate|stats> --data JSON' unless action
+
+      payload = read_payload(options[:data])
+      service = Server::Service.build(config_path: config_path)
+      result =
+        case action
+        when 'add' then service.kg_add(**payload.slice(:domain_id, :session_id, :scope_context, :scope_ref, :subject, :predicate, :object, :confidence, :source_turn_id))
+        when 'query' then service.kg_query(**payload.slice(:domain_id, :session_id, :scope_context, :subject, :predicate, :object, :include_invalid))
+        when 'timeline' then service.kg_timeline(**payload.slice(:domain_id, :session_id, :scope_context, :subject))
+        when 'invalidate' then service.kg_invalidate(**payload.slice(:edge_id, :reason, :domain_id, :session_id, :scope_context))
+        when 'stats' then service.kg_stats(**payload.slice(:domain_id, :session_id, :scope_context))
+        else abort "unknown kg action: #{action}"
+        end
+      print_json(result)
+    end
+
+    def serve(argv, config_path)
+      options = { host: '127.0.0.1', port: 9292 }
+      OptionParser.new do |opts|
+        opts.on('--host HOST') { |h| options[:host] = h }
+        opts.on('--port PORT', Integer) { |p| options[:port] = p }
+        opts.on('-h', '--help') { puts opts; exit 0 }
+      end.parse!(argv)
+
+      service = Server::Service.build(config_path: config_path)
+      Server::HttpApp.service = service
+      warn "[smart_brain] HTTP on http://#{options[:host]}:#{options[:port]} (backend: #{service.backend})"
+      Server::HttpApp.run!(host: options[:host], port: options[:port], server: :puma) do |server|
+        # Puma-specific tuning can go here.
+      end
+    end
+
+    def mcp(config_path)
+      service = Server::Service.build(config_path: config_path)
+      Server::McpServer.new(service: service).run
+    end
+
+    def read_payload(raw)
+      return {} if raw.nil? && $stdin.tty?
+      raw ||= $stdin.read
+      raw.to_s.strip.empty? ? {} : JSON.parse(raw, symbolize_names: true)
+    rescue JSON::ParserError => e
+      abort "invalid JSON payload: #{e.message}"
+    end
+
+    def print_json(payload)
+      puts JSON.generate(payload)
+    end
+  end
+end
+
+SmartBrain::CLI.run(ARGV)

data/lib/smart_brain/adapters/smart_rag/direct_client.rb

@@ -1,16 +1,26 @@
 # frozen_string_literal: true
 
+require_relative 'scope_filter'
+
 module SmartBrain
   module Adapters
     module SmartRag
       class DirectClient
-        def initialize(rag:)
+        include ScopeFilter
+
+        def initialize(rag:, scope_mapper: nil, fail_closed: true)
           @rag = rag
+          @scope_mapper = scope_mapper
+          @fail_closed = fail_closed
         end
 
         def retrieve(plan)
-          response = rag.retrieve(plan: plan)
-          normalize_pack(response, request_id: plan[:request_id])
+          scoped_plan, required, ignored, warnings = prepare_scoped_plan(plan)
+          return scope_failure_pack(plan, ignored, warnings, prefix: 'scope-blocked') unless scoped_plan
+
+          response = rag.retrieve(plan: scoped_plan)
+          pack = normalize_pack(response, request_id: plan[:request_id])
+          enforce_scope_confirmation(pack, required: required, ignored: ignored, warnings: warnings)
         rescue StandardError => e
           {
             version: '0.1',
@@ -26,7 +36,7 @@ module SmartBrain
 
         private
 
-        attr_reader :rag
+        attr_reader :rag, :scope_mapper, :fail_closed
 
         def normalize_pack(response, request_id:)
           pack = response.is_a?(Hash) ? response : {}
@@ -38,7 +48,8 @@ module SmartBrain
             evidences: Array(pack[:evidences]),
             stats: pack[:stats] || { candidates: Array(pack[:evidences]).size, returned: Array(pack[:evidences]).size, took_ms: 0 },
             explain: pack[:explain] || { ignored_fields: [] },
-            warnings: Array(pack[:warnings])
+            warnings: Array(pack[:warnings]),
+            scope_filter_applied: pack[:scope_filter_applied] == true
           }
         end
       end

data/lib/smart_brain/adapters/smart_rag/http_client.rb

@@ -1,18 +1,28 @@
 # frozen_string_literal: true
 
+require_relative 'scope_filter'
+
 module SmartBrain
   module Adapters
     module SmartRag
       class HttpClient
-        def initialize(transport:, timeout_seconds: 2)
+        include ScopeFilter
+
+        def initialize(transport:, timeout_seconds: 2, scope_mapper: nil, fail_closed: true)
           @transport = transport
           @timeout_seconds = timeout_seconds
+          @scope_mapper = scope_mapper
+          @fail_closed = fail_closed
         end
 
         def retrieve(plan)
           started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-          raw = transport.call(plan, timeout_seconds: timeout_seconds)
-          build_pack(raw: raw, request_id: plan[:request_id], took_ms: elapsed_ms(started_at))
+          scoped_plan, required, ignored, warnings = prepare_scoped_plan(plan)
+          return scope_failure_pack(plan, ignored, warnings, prefix: 'scope-blocked') unless scoped_plan
+
+          raw = transport.call(scoped_plan, timeout_seconds: timeout_seconds)
+          pack = build_pack(raw: raw, request_id: plan[:request_id], took_ms: elapsed_ms(started_at))
+          enforce_scope_confirmation(pack, required: required, ignored: ignored, warnings: warnings)
         rescue Timeout::Error
           {
             version: '0.1',
@@ -28,7 +38,7 @@ module SmartBrain
 
         private
 
-        attr_reader :transport, :timeout_seconds
+        attr_reader :transport, :timeout_seconds, :scope_mapper, :fail_closed
 
         def build_pack(raw:, request_id:, took_ms:)
           ignored = []
@@ -48,7 +58,8 @@ module SmartBrain
             explain: {
               ignored_fields: ignored + Array(raw.dig(:explain, :ignored_fields))
             },
-            warnings: Array(raw[:warnings])
+            warnings: Array(raw[:warnings]),
+            scope_filter_applied: raw[:scope_filter_applied] == true
           }
         end
 

data/lib/smart_brain/adapters/smart_rag/null_client.rb

@@ -5,6 +5,9 @@ module SmartBrain
     module SmartRag
       class NullClient
         def retrieve(plan)
+          business_scoped = Array(plan.dig(:scope_context, :read)).any? do |ref|
+            (ref[:type] || ref['type']).to_s != 'session'
+          end
           {
             version: '0.1',
             plan_id: "local-#{plan[:request_id]}",
@@ -12,8 +15,10 @@ module SmartBrain
             generated_at: Time.now.utc.iso8601,
             evidences: [],
             stats: { candidates: 0, returned: 0, took_ms: 0 },
-            explain: { ignored_fields: [] },
-            warnings: ['smart_rag client not configured; returned empty evidences']
+            explain: { ignored_fields: business_scoped ? ['scope_context.read'] : [] },
+            warnings: [business_scoped ? 'smart_rag scope filter unavailable: client not configured; failed closed' :
+              'smart_rag client not configured; returned empty evidences'],
+            scope_filter_applied: !business_scoped
           }
         end
       end

data/lib/smart_brain/adapters/smart_rag/scope_filter.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module SmartBrain
+  module Adapters
+    module SmartRag
+      module ScopeFilter
+        private
+
+        def prepare_scoped_plan(plan)
+          refs = Array(plan.dig(:scope_context, :read)).reject { |ref| (ref[:type] || ref['type']).to_s == 'session' }
+          return [plan, false, [], []] if refs.empty?
+
+          unless scope_mapper
+            warning = 'smart_rag scope filter unavailable: no scope mapper configured'
+            return [nil, true, ['scope_context.read'], [warning]] if fail_closed
+            return [plan, true, ['scope_context.read'], [warning]]
+          end
+
+          mapped = scope_mapper.call(
+            domain_id: plan.dig(:debug, :caller, :domain_id),
+            scopes: refs
+          )
+          applied = mapped.fetch(:applied, true)
+          filters = mapped[:filters] || mapped.reject { |key, _value| %i[applied warnings ignored_fields].include?(key) }
+          warnings = Array(mapped[:warnings])
+          ignored = Array(mapped[:ignored_fields])
+          return [nil, true, ignored + ['scope_context.read'], warnings + ['smart_rag scope mapper did not apply filters']] if !applied && fail_closed
+
+          [plan.merge(scope_filters: filters), true, ignored, warnings]
+        rescue StandardError => e
+          warning = "smart_rag scope mapping failed: #{e.message}"
+          fail_closed ? [nil, true, ['scope_context.read'], [warning]] : [plan, true, ['scope_context.read'], [warning]]
+        end
+
+        def scope_failure_pack(plan, ignored, warnings, prefix:)
+          {
+            version: '0.2', request_id: plan[:request_id], plan_id: "#{prefix}-#{plan[:request_id]}",
+            generated_at: Time.now.utc.iso8601, evidences: [],
+            stats: { candidates: 0, returned: 0, took_ms: 0 },
+            explain: { ignored_fields: ignored }, warnings: warnings,
+            scope_filter_applied: false
+          }
+        end
+
+        def enforce_scope_confirmation(pack, required:, ignored:, warnings:)
+          confirmed = pack[:scope_filter_applied] == true
+          pack[:explain] ||= { ignored_fields: [] }
+          pack[:explain][:ignored_fields] = Array(pack.dig(:explain, :ignored_fields)) + ignored
+          pack[:warnings] = Array(pack[:warnings]) + warnings
+          return pack unless required && !confirmed
+
+          pack[:explain][:ignored_fields] << 'scope_context.read'
+          pack[:warnings] << 'smart_rag did not confirm scope filter application'
+          pack[:evidences] = [] if fail_closed
+          pack
+        end
+      end
+    end
+  end
+end