smart_brain 0.1.2 → 0.2.0

data/docs/evidence_pack.md

@@ -0,0 +1,190 @@
+## 1. 目的
+
+EvidencePack 用于将一次检索的结果，以**可复现、可解释、可融合**的方式返回给 SmartBrain，避免：
+- 只返回片段文本，无法追溯来源与评分构成
+- 多模式检索融合过程不可观测，难以调试/评估
+- 跨源融合（memory vs resource）时缺少统一格式
+
+EvidencePack 不包含“最终 prompt”，只包含候选证据与必要的元信息。
+
+---
+
+## 2. 顶层结构
+
+```json
+{
+  "version": "0.1",
+  "plan": { },
+  "plan_id": "uuid",
+  "request_id": "uuid",
+  "generated_at": "2026-02-20T12:00:00Z",
+
+  "evidences": [],
+  "stats": { },
+  "explain": { },
+  "warnings": []
+}
+```
+
+字段说明：
+
+* `version`：协议版本（必填）
+* `plan`：原始 RetrievalPlan（可选但强烈建议保留，用于复现）
+* `plan_id`：执行方生成的唯一 id（建议必填）
+* `request_id`：来自 RetrievalPlan.request_id（建议必填）
+* `generated_at`：生成时间（必填）
+* `evidences`：证据列表（必填，可能为空）
+* `stats`：执行统计（候选数、耗时、返回数等）
+* `explain`：融合/重排/过滤的解释信息（强烈建议）
+* `warnings`：忽略字段、降级策略等提示（可选）
+
+---
+
+## 3. EvidenceItem 结构
+
+```json
+{
+  "id": "string",
+  "kind": "resource_section|resource_doc|memory_chunk|other",
+
+  "document_id": "string",
+  "section_id": "string",
+
+  "title": "string",
+  "source_uri": "string",
+  "source_type": "url|file|manual|memory_snapshot|other",
+
+  "snippet": "string",
+  "snippet_policy": "l2|l1|l0|auto",
+  "language": "zh|en|other",
+
+  "signals": {
+    "vector_score": 0.0,
+    "vector_rank": 0,
+    "fts_score": 0.0,
+    "fts_rank": 0,
+    "rrf_score": 0.0,
+    "rerank_score": 0.0,
+    "tag_score": 0.0,
+    "topic_score": 0.0,
+    "recency_score": 0.0
+  },
+
+  "provenance": {
+    "mode": "exact|semantic|hybrid|relational|associative",
+    "query_text": "string",
+    "query_index": 0,
+    "retrieved_at": "2026-02-20T12:00:00Z"
+  },
+
+  "metadata": {
+    "chunk_index": 12,
+    "offset_start": 1234,
+    "offset_end": 1567,
+    "page": 3,
+    "section_title": "string"
+  },
+
+  "raw": {
+    "content_ref": "section:l2",
+    "content_hash": "sha256:...",
+    "debug_payload": { }
+  }
+}
+```
+
+### 3.1 必填字段（v0.1 最低要求）
+
+* `id`
+* `source_uri`
+* `snippet`
+* `provenance.mode`
+* `signals` 至少包含：`rrf_score`（若使用融合）或 `vector_score/fts_score` 之一
+* `generated_at`（在顶层）
+
+### 3.2 推荐字段
+
+* `document_id/section_id`：用于去重与回源
+* `signals` 全量：用于解释与回归评估
+* `metadata`：用于展示与定位（标题、页码、chunk 位置）
+* `plan`：用于复现
+
+> 说明：如果某些字段后端暂不支持，应置空/省略，并在 `warnings` 或 `explain.ignored_fields` 中说明。
+
+---
+
+## 4. stats（统计）
+
+```json
+{
+  "candidates": 200,
+  "returned": 30,
+  "took_ms": 128,
+  "by_mode": {
+    "exact": { "candidates": 50, "returned": 10 },
+    "semantic": { "candidates": 100, "returned": 10 },
+    "hybrid": { "candidates": 200, "returned": 30 }
+  }
+}
+```
+
+---
+
+## 5. explain（解释）
+
+```json
+{
+  "fusion": {
+    "method": "rrf|weighted_sum|none",
+    "rrf_k": 60,
+    "weights": { "exact": 1.0, "semantic": 1.0 }
+  },
+  "rerank": { "enabled": true, "model": "qwen3-reranker", "top_n": 50 },
+  "filters_applied": {
+    "tag_ids": ["..."],
+    "topic_ids": ["..."],
+    "time_range": { "from": "...", "to": "..." }
+  },
+  "diversity": {
+    "by_document": 3,
+    "by_source": 10,
+    "applied": true
+  },
+  "ignored_fields": [
+    "global_filters.language not supported",
+    "diversity.by_source not supported"
+  ]
+}
+```
+
+说明：
+
+* `filters_applied`：最终实际生效的过滤条件（非常重要）
+* `ignored_fields`：执行方未支持字段，必须显式说明，方便调用方调整策略
+
+---
+
+## 6. warnings（可选）
+
+`warnings` 是字符串数组，用于快速提示调用方问题，例如：
+
+* `time_range filter ignored due to missing created_at index`
+* `rerank disabled because model not configured`
+
+---
+
+## 7. 去重与稳定性建议（给执行方）
+
+为了让 SmartBrain 可靠装配上下文，SmartRAG（执行方）建议：
+
+* `id` 稳定可重现（例如 `doc_id:section_id:chunk_index`）
+* 对相同 section 的不同 query 命中：保留最高分，并在 provenance 中记录最强来源（或保留多个 provenance）
+* `snippet` 应受 `output.max_snippet_chars` 约束，避免塞爆 token
+* 返回顺序应是“最终排序结果顺序”（已融合/已 rerank）
+
+---
+
+## 8. 版本与兼容
+
+* v0.1：新增字段仅可选；执行方忽略未知字段
+* 如需破坏性变更，升级 major 版本并提供迁移说明

data/docs/gap_vs_mempal.md

@@ -0,0 +1,161 @@
+# SmartBrain + SmartRAG 与 mempal 的差距分析
+
+> 对照基准：`MEMPAL_GUIDE.md`（mempal v0.9.0，2026-07-09）
+> 分析对象：smart_brain（v0.1.2，记忆运行时 + 上下文编排器）+ smart_rag（资源 RAG 后端）
+> 生成日期：2026-07-31
+
+---
+
+## 0. 定位差异（决定了所有差距的性质）
+
+> **mempal** 是一个「单二进制 + 单 SQLite 文件」的**一体化记忆工具**，把存储、检索、知识治理、多 Agent 协作、MCP/CLI 全部打包进一个进程，any coding agent 装上即用。
+>
+> **smart_brain + smart_rag** 是「两个 Ruby gem、进程内嵌入」的**分层架构**：smart_brain 做记忆运行时 + 上下文装配，smart_rag 做资源 RAG 后端，靠 `DirectClient` / `HttpClient` 适配器串联。
+
+因此差距分两类：
+
+- **A 类**：mempal 有、smart_brain 这层压根没有的能力。
+- **B 类**：smart_brain 设计文档承诺了、但代码没兑现（doc-code gap）。
+
+---
+
+## 1. 能力对照总表
+
+| 能力域 | mempal | smart_brain | smart_rag | 差距 |
+|---|---|---|---|---|
+| 持久化存储 | SQLite + sqlite-vec 单文件 | **仅内存**（SQL schema 是死代码） | Postgres（Sequel） | 🔴 严重 |
+| 资源混合检索 | BM25 + 向量 + RRF | — | 向量 + FTS + RRF + rerank ✅ | smart_rag 已覆盖 |
+| 记忆侧检索 | 统一进同一索引 | **子串词重叠**（无 FTS / 无向量） | — | 🔴 严重 |
+| 记忆侧语义检索 | sqlite-vec | 无（SemanticRetriever 未实现） | — | 🔴 |
+| 思维分层 Mind Model | dao_tian / ren / shu / qi / evidence | 扁平 9 种 type | — | 🔴 |
+| 知识生命周期 | distill / gate / promote / demote | 仅 active / superseded / retracted | — | 🔴 |
+| Knowledge Card（Phase-2） | card + evidence link + events | 无 | — | 🔴 |
+| Phase-3 自进化 | runtime adoption evidence | 无 | — | 🔴 |
+| 知识图谱 KG | 三元组 + 时态有效性 | entities / mentions（无谓词 / 无时态） | topic 关系（部分） | 🟠 |
+| 事实核查 Fact-check | SimilarName / Relation / StaleFact | 无 | — | 🟠 |
+| MCP Server | 26 个工具 + MEMORY_PROTOCOL 注入 | **无** | 无 | 🔴 |
+| CLI | 全套命令 | **无 `bin/`** | 仅 migrate | 🔴 |
+| 多 Agent Cowork | bus / session / channel / handoff | 无 | — | 🟠 |
+| AAAK 格式化 | compress + 中文 jieba | 无 | — | 🟡 |
+| 跨项目 / 命名空间 | wing / room / projects / resume | 仅 session_id | topics / tags | 🟠 |
+| Tunnels / Taxonomy 路由 | 有 | 无 | — | 🟡 |
+| Brief / wake-up | citation-first brief / L0L1 唤醒 | 无（只有 compose_context） | — | 🟠 |
+| Agent Diary | 约定（OBSERVATION / LESSON / PATTERN） | 无 | — | 🟡 |
+| Bench / 评估 | LongMemEval | 仅回归 spec | — | 🟡 |
+| 可观测追踪 | status / doctor | **request_id → plan_id → context_id 全链路 + P95** | search_logs | 🟢 相对优势 |
+
+---
+
+## 2. 第一类差距：阻塞真正可用 🔴
+
+### 2.1 没有持久化 —— SQL schema 是「死代码」
+
+`db/migrate/001_init.sql` 定义了完整的 Postgres schema（sessions / turns / messages / memory_items / memory_chunks / entities / summaries …），但运行时 `lib/smart_brain/runtime.rb` 里写死的是：
+
+```ruby
+event_store  = EventStore::InMemory.new
+memory_store = MemoryStore::InMemory.new
+```
+
+进程一重启，所有对话记忆与结构化记忆全部丢失。这是与 mempal「单文件持久、跨 session 带出处找回历史决策」最根本的差距。`docs/coding_todo.md` 里「Postgres 优先」其实从未落地。
+
+### 2.2 记忆侧检索是玩具级
+
+`lib/smart_brain/retrievers/exact_retriever.rb` 的核心是子串包含计数：
+
+```ruby
+hits = terms.count { |t| haystack.include?(t) }
+hits.to_f / terms.length
+```
+
+既不是 BM25，也没用 FTS，更没有向量。讽刺的是 schema 里 `memory_chunks.tsv + USING GIN` 全文索引、以及 `docs/memory_types.md` 第 7 节的 chunk 文本化规则都设计好了，但**没有任何代码往 memory_chunks 写数据或查询**。`lib/smart_brain/retrievers/relational_retriever.rb` 也只是 entity / ref 名字的子串匹配。
+
+结果：smart_brain 自己的记忆检索质量远低于 smart_rag 的资源检索，也远低于 mempal 的 BM25 + 向量 + RRF。
+
+### 2.3 没有 CLI、没有 MCP —— Agent 用不上
+
+mempal 的核心价值主张是「any coding agent 在 10 秒内带出处找回历史决策」，靠的就是 `mempal serve --mcp`（26 个工具）+ 一套 CLI + MEMORY_PROTOCOL 自动注入。
+
+smart_brain 当前是**纯库**，只能 `SmartBrain.commit_turn` / `compose_context` 嵌进 Ruby 进程。没有 `bin/`，没有 MCP server，没有 HTTP server（smart_rag 有 API 文档但同样没有 MCP）。这意味着 Claude Code / Codex / 其它 agent 根本无法把 smart_brain 当工具调用——而这恰恰是 mempal 的全部卖点。
+
+---
+
+## 3. 第二类差距：「记忆宫殿」的知识治理深度几乎为零 🔴
+
+mempal 的「palace」灵魂在于记忆是有**生命周期、有层级、可证伪、可治理**的。smart_brain 这一层基本是空白：
+
+| mempal 治理机制 | smart_brain 现状 |
+|---|---|
+| 思维分层 `dao_tian → dao_ren → shu → qi → evidence`，context 按层装配 | 扁平 type，compose 按固定槽位（system / summary / recent / evidence / user） |
+| `distill`（evidence → candidate） | 无 |
+| `gate`（promotion 门槛检查） | 无 |
+| `promote` / `demote`（evidence-backed） | 无 |
+| Knowledge Card（supports / contradicts / teaches + lifecycle events） | 无 |
+| Phase-3 runtime adoption（used / accepted / rejected / miss / rollback） | 无 |
+| KG 三元组 + `valid_from / valid_to` 时态 | 只有 entities 表，无谓词、无时态 |
+| Fact-check（同名冲突 / 关系矛盾 / 过期事实） | 无 |
+| publish-anchor（worktree → repo → global 作用域） | 无（仅 session 作用域） |
+
+smart_brain 的冲突处理只做到 `superseded / retracted` 两个状态（`lib/smart_brain/memory_store/in_memory.rb`），距离 mempal 的「evidence → candidate → gate → promoted → demoted / retired」全流程差一整套治理层。
+
+---
+
+## 4. 第三类差距：Agent 生态与跨项目能力 🟠
+
+- **MEMORY_PROTOCOL**：mempal 把 18 条规则塞进 MCP `initialize.instructions`，客户端连上即学。smart_brain 无任何 agent 引导协议。
+- **Cowork / 多 Agent**：mempal 有 legacy cowork、multi-agent bus、team session、channel、handoff、capture。smart_brain 完全没有多 agent 协作原语。
+- **跨项目管理**：mempal 用 wing / room / drawer / source_file 四级作用域 + `projects` / `resume` / `tunnels` / `taxonomy`。smart_brain 只有 `session_id` 一个维度，无命名空间、无路由关键词、无跨项目跳转。
+- **Brief / wake-up**：mempal 有确定性的 citation-first brief 和 L0 / L1 wake-up 唤醒。smart_brain 只有 `compose_context` 一条路。
+- **AAAK 格式化 / Agent Diary / Bench**：均无。
+
+---
+
+## 5. 第四类差距：设计文档承诺了、代码没兑现 🟡
+
+这是 smart_brain 内部的 doc-code gap：
+
+1. **LLM 集成全部缺位**。`docs/smartbrain_design.md` 第 9 节明写 ModelProvider（ollama Qwen3：planner / extractor / summarizer / reranker / embedding），`docs/coding_todo.md` 也列了 `model_provider/` 目录——但**代码里根本不存在 ModelProvider 模块**：
+   - `lib/smart_brain/retrieval_planner/planner.rb` 是关键词规则（`RESOURCE_HINTS` 字符串匹配），不是 LLM 意图分析；
+   - `lib/smart_brain/memory_extractor/extractor.rb` 是规则门控，不是 LLM 抽取；
+   - `lib/smart_brain/consolidator/working_summary.rb` 是**填模板**（拼 `"- #{key}"`），不是 LLM 摘要；
+   - `lib/smart_brain/fusion/merger.rb` 的 rerank 是 `score + 词重叠 * 0.05`，不是 qwen3-reranker。
+2. **9 种记忆类型只实现 6 种**。`docs/memory_types.md` 定义了 profile / preferences / goals / tasks / decisions / entities / events / cases / patterns，但 `lib/smart_brain/memory_extractor/extractor.rb` 只处理 tasks / decisions / goals / events / preferences / entities / retractions——**profile、cases、patterns 三种 type 没有抽取逻辑**。
+3. **契约校验形同虚设**。`lib/smart_brain/contracts/*.rb` 三个类只检查「必填 key 存在」，不做结构 / 类型校验（`coding_todo` 说要用 dry-validation，实际没引入）。
+
+---
+
+## 6. smart_brain 已经做得不错的地方（重构时别丢掉）🟢
+
+对照下来 smart_brain 也有 mempal 没明显强调的相对优势，路线规划时应保留：
+
+1. **全链路追踪**：`request_id → plan_id → context_id` 三连 ID 贯穿 Plan → Retrieve → Fuse → Compose，`lib/smart_brain/observability/tracker.rb` 还提供 P95 / memory-resource 比 / token 超预算率——这套可观测性比 mempal 的 status / doctor 更细。
+2. **融合层设计扎实**：`lib/smart_brain/fusion/merger.rb` 的去重 key 设计（resource 用 document + section + chunk，memory 用 item_id 或 turn + message）、多样性约束、memory / resource 比例切分，思路清晰，只是缺真实 rerank 分。
+3. **smart_rag 资源侧已达标**：向量 + FTS + RRF + rerank + chunking + topics / tags 这条资源 RAG 链路，已经覆盖了 mempal 资源检索的部分，不用重做。
+4. **写入门控策略可配置**：confidence 三档 + entity gate（频率 / 结构信号）+ 覆盖 / 撤回，策略对象和生效点分离得干净。
+
+---
+
+## 7. 建议的优先级路线（从「能用」到「像 mempal」）
+
+如果目标是追平 mempal，建议按「先解锁可用性、再补治理深度、最后做生态」推进：
+
+1. **P0 持久化 + 记忆检索落地** ✅ 已完成（2026-08）：`EventStore` / `MemoryStore` 各有 InMemory / Postgres 两套同接口实现，`Runtime.build` 按 `config/brain.yml` 的 `storage.backend`（或 `SMARTBRAIN_BACKEND`）选择；`memory_chunks` 的 FTS 真正接通——写入时建 `simple` 配置的 TSVECTOR（CJK 按字符 unigram 切分），检索用 `to_tsquery` OR 语义 + `ts_rank`。跨进程重启可召回。新增 `lib/smart_brain/db.rb`、`event_store/postgres.rb`、`memory_store/postgres.rb`、迁移 `db/migrate/002_turn_events_payload.sql`；集成测试 `spec/integration_postgres_spec.rb`（`SMARTBRAIN_PG=1`）。
+2. **P0 Agent 工具面** ✅ 已完成（2026-08）：三件套齐全——stdio MCP server（`lib/smart_brain/server/mcp_server.rb`，零依赖 JSON-RPC，4 工具 + initialize.instructions）、Sinatra/Puma HTTP API（`server/http_app.rb`）、CLI `exe/smart_brain`（serve/mcp/commit/compose/search/status/migrate）。三者共享 `Server::Service` 门面。接入说明见 `docs/mcp.md`。
+3. **P1 LLM 兑现承诺** ✅ 已完成（2026-08）：补齐 `ModelProvider`（`lib/smart_brain/model_provider/`：Stub 默认 / Ollama / OpenAI 兼容 + factory）。默认 Stub（确定性、零网络）；切 ollama/openai 后 `working_summary` 走真摘要（带模板兜底 + `summary_method` 标注）、`Fusion::Merger` 走 LLM rerank（`rerank_enabled` 默认关，避免每轮延迟）。runtime 注入 provider。真实 Ollama（llama2 快路径 + qwen3）端到端验证通过；qwen3-thinking 慢/截断属模型侧问题，代码层面优雅降级。注：planner/extractor 仍为规则（本轮只做 summary+rerank+distill 起草）。
+4. **P1 思维分层 + 知识生命周期** ✅ 已完成（2026-08）：引入 mempal 思维分层 `dao_tian/dao_ren/shu/qi/evidence`（`governance/tiers.rb`，memory_items 加 `tier` 列，extractor 按 type 赋默认 tier；ContextComposer 按 tier 优先级装配 + dao_tian 配额）。Stage-1 生命周期 `Governance::Lifecycle`：`distill → candidate → gate → promote → demote`（dao_ren/qi 可蒸馏，gate 门槛 `min_supporting_refs`，evidence-backed 转换，`knowledge_events` 审计表）。补齐 extractor 的 profile/cases/patterns 三类。四个 knowledge 工具暴露到 Service/CLI(`knowledge`)/MCP/HTTP。lifecycle 与冲突 `status` 正交。
+5. **P2 KG + Fact-check + Brief / wake-up** ✅ 已完成（2026-08）：
+   - **KG**：`kg_edges` 表（subject/predicate/object + `valid_from`/`valid_to` 时态 + active/invalidated + best-effort 实体链接，迁移 `004_kg_edges.sql`）；`Governance::KnowledgeGraph`（add/query/timeline/invalidate/stats）；三元组由 `turn_events[:edges]` 规则抽取（commit_turn 落库）；RelationalRetriever 匹配 entity 时拉其边作 `mode:'graph'` 证据。与 lifecycle 正交。
+   - **Fact-check**：`Governance::FactCheck` 纯 Ruby 离线只读——SimilarNameConflict（Levenshtein，`support/levenshtein.rb`）、RelationContradiction（否定 cue × active triple）、StaleFact（invalidated 边被引用）。零 LLM。
+   - **Brief / wake-up**：`Governance::Briefing` 确定性、citation-first、不写 DB——brief（summary/key_facts/evidence/entities/unresolved/uncertainty/next_actions，每条带引用）+ wake_up（L0 identity + L1 goals/decisions）+ resume（session 模糊匹配）。
+   - 前端：Service/CLI（`kg`/`fact-check`/`brief`/`wake-up`）/MCP（+6 工具，共 14）/HTTP（`/kg/*`/`/fact-check`/`/brief`/`/wake-up`）。
+6. **P3 Cowork / Phase-3 自进化 / AAAK / Bench**。
+
+---
+
+## 8. 参考索引
+
+- 基准：`MEMPAL_GUIDE.md`
+- smart_brain 设计：`docs/smartbrain_design.md`、`docs/policies.md`、`docs/memory_types.md`、`docs/coding_todo.md`
+- smart_brain 运行时：`lib/smart_brain/runtime.rb`、`lib/smart_brain/memory_store/in_memory.rb`、`lib/smart_brain/retrievers/*.rb`、`lib/smart_brain/fusion/merger.rb`、`lib/smart_brain/consolidator/working_summary.rb`
+- smart_brain schema（未接线）：`db/migrate/001_init.sql`
+- smart_rag 检索链路：`/root/smart_rag/lib/smart_rag/retrieve.rb`、`/root/smart_rag/lib/smart_rag.rb`

data/docs/mcp.md

@@ -0,0 +1,93 @@
+# SmartBrain MCP Server
+
+SmartBrain ships a stdio MCP (Model Context Protocol) server so any coding agent
+that speaks MCP — Claude Code, Cursor, etc. — can drive the memory runtime as a
+native tool: persist turns, recall memory, and assemble context.
+
+The server is hand-rolled JSON-RPC 2.0 with **no extra gem dependency**.
+
+## Start it
+
+```bash
+smart_brain mcp            # uses config/brain.yml (default backend: memory)
+# or, against Postgres for durable, cross-session memory:
+SMARTBRAIN_BACKEND=postgres smart_brain mcp
+```
+
+Run `smart_brain migrate` once before using the `postgres` backend.
+
+## Tools exposed
+
+| Tool | What it does |
+|---|---|
+| `commit_turn` | Persist a turn (`messages` + structured events) and extract durable memory. |
+| `compose_context` | Retrieve evidence and assemble a context package for a user message. |
+| `search_memory` | Full-text recall over the session's persistent memory (FTS on Postgres). |
+| `status` | Backend, P95, memory/resource ratio, counts. |
+| `knowledge_distill`, `knowledge_gate`, `knowledge_promote`, `knowledge_demote` | Govern knowledge lifecycle. |
+| `knowledge_promote_to_scope`, `knowledge_retract`, `knowledge_lineage` | Govern cross-scope copies and provenance. |
+| `kg_add`, `kg_query`, `kg_invalidate`, `kg_timeline`, `kg_stats` | Manage and inspect scoped knowledge-graph edges. |
+| `fact_check`, `brief`, `wake_up` | Read scoped knowledge for validation and resume workflows. |
+
+On `initialize` the server returns a short `instructions` block (a lightweight
+MEMORY_PROTOCOL) so the client learns the tools immediately.
+
+All memory, governance, briefing, fact-check, and KG tools accept `domain_id`
+and `scope_context`. New clients should send both together:
+
+```json
+{
+  "domain_id": "tenant-a",
+  "session_id": "conversation-1",
+  "scope_context": {
+    "read": [{"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"}
+  }
+}
+```
+
+`write` must be a subset of `read`, and `default_write` must appear in
+`write`. Calls that omit both new fields retain the 0.1 session-only behavior.
+Cross-scope governance is exposed as `knowledge_promote_to_scope`,
+`knowledge_retract`, and `knowledge_lineage`; KG also exposes `kg_timeline`
+and `kg_stats`.
+
+## Claude Code
+
+Add to `~/.config/claude/claude_desktop_config.json` (or the project's
+`.mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "smart_brain": {
+      "command": "/path/to/smart_brain/exe/smart_brain",
+      "args": ["mcp"],
+      "env": { "SMARTBRAIN_BACKEND": "postgres" }
+    }
+  }
+}
+```
+
+If you installed the gem, `command` can just be `"smart_brain"`.
+
+## Cursor
+
+`Settings → MCP → Add new MCP Server`:
+
+- Type: `stdio`
+- Command: `smart_brain mcp` (or the full `exe/smart_brain` path)
+- Env: `SMARTBRAIN_BACKEND=postgres` (optional)
+
+## Other front-ends
+
+- **HTTP API**: `smart_brain serve --port 9292` then `POST /commit | /compose | /search`, `GET /status`.
+- **CLI one-shots**: `smart_brain commit|compose|search --data '{...}'` (or pipe JSON via stdin).
+
+## Why no ruby MCP SDK?
+
+mempal's value prop is "any agent recalls past decisions in 10 seconds". The MCP
+wire format for the methods clients actually use (`initialize`,
+`notifications/initialized`, `tools/list`, `tools/call`) is small enough that a
+~150-line stdio loop covers it — keeping SmartBrain dependency-light.