dsh-memory-eternal 0.4.28 → 0.5.0

package/README.md

@@ -146,7 +146,169 @@ dsh plugin --profile web add F:/MyApp/eternal/dsh-memory-eternal
 > - 要**官方最新**（避免 npmmirror 滞后）：`npm_config_registry=https://registry.npmjs.org/ dsh plugin --profile web add dsh-memory-eternal`。
 > - **profile 是 pnpm workspace**：`cd ~/.dsh/profiles/web && pnpm add dsh-memory-eternal@latest`（`npm install` 会报 `EUNSUPPORTEDPROTOCOL`）。
 
-装完**重启 dsh web**：设置 → 记忆 出现知识库；侧边栏底部出现「记忆」按钮。此后每轮对话自动沉淀。
+装完**重启 dsh web**：设置 → 记忆 出现知识库（iframe 加载 Web 端）；侧边栏底部出现「记忆」按钮。此后每轮对话自动沉淀。
+
+## 🌐 多宿主：装完即用（Claude Code / Codex / Cursor / 浏览器）
+
+从 v0.5 起，本插件不再只属于 DSH——**一个记忆库，所有 Agent 共享**：
+
+```
+┌────────── 核心引擎（vault.js + capture.js，零耦合）──────────┐
+│  ① DSH 原生插件        ② MCP server        ③ Web 端         │
+│     自动沉淀+召回          stdio 零依赖        UI 唯一真源      │
+│     UI=iframe 壳          Claude/Codex/      浏览器直接访问    │
+│                           Cursor             DSH 渲染也走它   │
+└──────────────────────────────────────────────────────────────┘
+```
+
+### 自动挂载（零手动）
+
+插件激活时自动检测本机已装的 Agent，**幂等写入 MCP 配置**（改动前自动备份）：
+
+- **Claude Code** → `~/.claude.json` 的 `mcpServers` + `~/.claude/settings.json` 的 SessionEnd hook（会话结束自动沉淀）
+- **Codex CLI** → `~/.codex/config.toml` 的 `[mcp_servers.memory]`
+- **Cursor** → `~/.cursor/mcp.json`
+
+下次打开对应工具，`memory_recall` / `memory_capture` / `memory_stats` 三个工具直接可用。不想自动配置？设置里关 `autoMcpSetup`，或环境变量 `MEMORY_ETERNAL_SKIP_AUTO=1`。
+
+### Web 端（默认常驻）
+
+插件激活时自动拉起独立 Web server（detached 进程，不占 DSH 宿主），**UI 唯一真源**——DSH 内的设置页与浏览器访问的是同一份：
+
+```bash
+dsh-memory open            # 确保 Web 存活 + 浏览器打开（默认 http://127.0.0.1:7999）
+dsh-memory serve --port 8080   # 前台跑 Web server
+```
+
+### CLI 速查
+
+```bash
+dsh-memory recall "数据库选型"      # 检索
+dsh-memory capture "重要结论..."    # 手动沉淀
+dsh-memory sweep ~/.claude/projects # 挖掘已有会话记录
+dsh-memory setup --dry-run          # 重跑自动挂载（幂等）
+dsh-memory mcp                      # MCP stdio（挂给任意 MCP 客户端）
+```
+
+### 蒸馏 LLM（可选）
+
+MCP / hooks / CLI 的自动蒸馏需要一个 OpenAI 兼容端点（DSH 内免配）：
+
+```bash
+export MEMORY_LLM_BASE_URL=https://api.deepseek.com   # 或 Ollama/vLLM/LM Studio
+export MEMORY_LLM_KEY=sk-xxx
+export MEMORY_LLM_MODEL=deepseek-chat
+```
+
+未配置时：recall 全功能；capture 降级为原文卡（不蒸馏）。
+
+### 单一副本原则（防版本漂移）
+
+MCP/hooks/CLI 全部指向 DSH profile 内那一份代码（`~/.dsh/profiles/web/node_modules/dsh-memory-eternal`）。**更新只需一条命令**：`cd ~/.dsh/profiles/web && pnpm add dsh-memory-eternal@latest`，DSH + MCP + Web 齐步走。纯 Claude Code 用户（无 DSH）可 `npm i -g dsh-memory-eternal`，独立副本独立库。卡格式带 `formatVersion` 守卫，跨版本只向后兼容读，多副本共存不会写坏库。
+
+---
+
+## 📖 使用
+
+> **核心心智模型：一个库（`~/.dsh/memory-vault`，纯 Markdown + 可 git），一群 Agent（DSH / Claude / Codex / Cursor）自动记、随时忆，一个网页（`dsh-memory open`）看全局。**
+
+### DSH 内使用（现状，0 步骤）
+
+```bash
+# 重启 dsh web 后生效新版插件
+```
+
+- **自动沉淀**：每轮对话结束自动把可复用内容蒸馏成知识卡，无需操作
+- **`memory_recall` 工具**：Agent 在需要历史决策/项目背景时主动调用
+- **可视化**：设置 → 记忆 或侧边栏底部「记忆」按钮 → 内嵌打开 Web 端（同一份 UI）
+- **多 Vault**：设置里 `vaultProfiles` 命名分库 + `activeVault` 切换；跨库聚合检索 `?all=1`
+
+### Claude Code 使用
+
+装完即用——MCP 与 SessionEnd hook 都已自动挂载：
+
+- 会话中说「recall 一下数据库选型」→ Claude 自动调 `memory_recall`
+- 会话结束/上下文压缩前 → hook 自动蒸馏入库
+- 想看记了什么：`dsh-memory open`
+
+### Codex CLI / Cursor 使用
+
+重启对应工具后，MCP 已在工具的 MCP 列表里，会话内直接：
+
+```
+用 memory_recall 查一下项目的历史决策
+用 memory_stats 看库内有多少张卡
+```
+
+### Web 端使用
+
+```bash
+dsh-memory open              # 确保 Web 存活 + 浏览器打开（默认 http://127.0.0.1:7999）
+dsh-memory serve --port 8080 # 自定义端口前台运行
+```
+
+打开后所见即所得：统计概览 / 中文片段检索 / 知识卡网格（删除/编辑/合并/导入导出）/ 增强知识图谱（力导向+时间维着色+右键菜单+框选+PNG 导出）。与 DSH 内嵌「记忆」页面渲染同一份 UI（单一真源），数据天然同步。
+
+### CLI 速查
+
+```bash
+dsh-memory recall "数据库选型"      # 检索知识卡（输出 JSON）
+dsh-memory capture "重要结论..."    # 手动沉淀（- 读 stdin）
+dsh-memory sweep ~/.claude/projects # 挖掘已有会话记录
+dsh-memory setup --dry-run          # 预览自动挂载（幂等）
+dsh-memory mcp                      # MCP stdio（手动挂任意 MCP 客户端）
+dsh-memory serve --port 7999        # 前台 Web server
+dsh-memory open                     # 确保 Web 存活 + 浏览器打开
+```
+
+### 蒸馏 LLM（可选）
+
+MCP / hooks / CLI 的自动蒸馏需要一个 OpenAI 兼容端点（DSH 内免配——复用 dsh 的 llm）：
+
+```bash
+export MEMORY_LLM_BASE_URL=https://api.deepseek.com   # 或 Ollama/vLLM/LM Studio
+export MEMORY_LLM_KEY=sk-xxx
+export MEMORY_LLM_MODEL=deepseek-chat
+```
+
+未配置时：recall 全功能；capture 降级为原文卡（不蒸馏，仍可正常用）。
+
+### zcode（智谱）说明
+
+zcode 暂无原生 MCP 支持，可经社区 [zcode-open-bridge](https://github.com/tizerluo/zcode-open-bridge) 转 MCP 后挂载，或直接用 CLI（`dsh-memory capture / recall / sweep`）。
+
+---
+
+## 🔄 更新
+
+**单副本原则**是更新能「一条命令搞定」的根基——所有入口都指向同一份代码。
+
+```bash
+# DSH 用户（最常见）：profile 里更新 → DSH + MCP + Web 齐步走
+cd ~/.dsh/profiles/web
+pnpm add dsh-memory-eternal@latest
+
+# 纯 Claude Code / Cursor 用户（无 DSH）：全局包更新
+npm i -g dsh-memory-eternal@latest
+```
+
+更新完后：
+- **DSH 用户**：重启 dsh web（插件 reload）→ `autoMcpSetup` 自动幂等跳过（配置已是最新），`autoWeb` 进程已是新版
+- **Claude/Codex/Cursor 用户**：重启对应工具，stdin MCP 进程由 agent 重 spawn → 加载新版
+
+不会出现的版本漂移：所有 agent 入口指向同一份代码，不存在「DSH 是新版、Claude Code 是旧版」导致的格式/行为不一致。卡文件 `formatVersion` 字段是最后一道防线，跨版本只向后兼容读。
+
+如果想从 GitHub 拉未发布版（dev/特性分支）：
+
+```bash
+# DSH 用户
+cd ~/.dsh/profiles/web && pnpm add github:EternalNight996/dsh-memory-eternal
+
+# 全局
+npm i -g github:EternalNight996/dsh-memory-eternal
+```
+
+---
 
 ### 🧭 插件发现 / 收录标准
 
@@ -178,6 +340,8 @@ dsh plugin --profile web add F:/MyApp/eternal/dsh-memory-eternal
 | activeVault | '' | 当前激活的 Vault（对应 vaultProfiles 中的 name） |
 | sessionBudgetChars | 80000 | 会话级 token 预算（字符数），供 harness 触发压缩 |
 | recallEmbedding | '' | 语义召回 provider（空=零依赖 bigram + LLM 判定兜底） |
+| autoMcpSetup | 开 | 激活时自动把 MCP 挂到本机已装的 Claude Code/Codex/Cursor（幂等+备份） |
+| autoWeb | 开 | 激活时确保 Web server 常驻（UI 唯一真源，DSH 渲染走 iframe） |
 
 ---
 
@@ -223,6 +387,7 @@ dsh-memory-eternal/
 - **新建卡片 kind 下拉可读背景色**（v0.4.27）
 - **图谱合并/删除即时联动整理建议**（v0.4.27）
 - **一键合并相似按钮从图谱工具栏移到整理建议面板**（v0.4.26）
+- **多宿主**：MCP server + CLI `dsh-memory` + Web 端常驻 + 自动挂载 Claude/Codex/Cursor + SessionEnd hook + `formatVersion` 守卫（v0.5.0）
 
 **待办（核心功能优化）**：
 - [x] ~~多 Vault / 多 Profile~~、~~注入体积可配置~~、~~每日回顾+用量~~、~~自动归档整理~~、~~召回用户反馈~~、~~会话级 token 预算~~（v0.4.5）
@@ -231,11 +396,13 @@ dsh-memory-eternal/
 - [ ] 多 Vault 的**跨库合并/去重**（跨 profile 识别重复卡）
 - [ ] 语义召回**接入外部 embedding provider**（当前为本地零依赖加分）
 - [ ] 每日回顾**主动推送通道**（当前生成文件 + 手动查看，推送需 harness/通知渠道）
+- [ ] **多宿主体验进一步收口**：zcode bridge 内置 / Codex sweep 增字段适配 / Web 端暗色主题微调
 
 ---
 
 ## 📦 发布记录
 
+- **v0.5.0**：**多宿主化**——MCP server 零依赖 stdio（3 工具：recall/capture/stats），CLI 入口 `dsh-memory`（recall/capture/serve/open/mcp/setup/sweep），Web 端常驻（DSH 渲染走 iframe = 单一 UI 真源），自动挂载到 Claude Code/Codex/Cursor（幂等+备份），Claude Code SessionEnd hook 自动沉淀，卡格式 `formatVersion` 守卫，DSH 用户 / Claude Code 用户均「一条命令安装即用」。`api.js` 抽层 + `capture-run.js` 独立沉淀管线复用。
 - **v0.4.28**：侧边栏底部「记忆」按钮**独占一行**——不再与「主题」等 footer 按钮挤在同一行（`flex-wrap` 同时命中直接包含与中间隔 wrapper 两种情况）。
 - **v0.4.27**：新建卡片 kind 下拉可读背景色；图谱合并/删除节点后**即时联动整理建议**面板刷新。
 - **v0.4.26**：一键合并相似按钮从图谱工具栏移到整理建议面板，操作路径更直观。

package/bin/dsh-memory.mjs

@@ -0,0 +1,148 @@
+#!/usr/bin/env node
+// 记忆核心 · CLI（多宿主统一入口）
+//
+// 用法：
+//   dsh-memory recall <query> [--limit N] [--vault DIR]   检索知识卡
+//   dsh-memory capture <text | - > [--source TAG]         手动沉淀（- 读 stdin）
+//   dsh-memory serve [--port N] [--vault DIR]             启动 Web UI（前台常驻）
+//   dsh-memory open [--port N]                            确保 Web 存活并用浏览器打开
+//   dsh-memory mcp                                        MCP stdio server（各 agent 挂载）
+//   dsh-memory setup [--claude-only|--codex-only|--cursor-only] [--dry-run] [--no-hooks]
+//                                                         自动挂载 MCP 到已装的 agent
+//   dsh-memory sweep <dir>                                挖掘 Claude Code 会话 JSONL
+//
+// 环境变量：
+//   MEMORY_VAULT_DIR       vault 目录（默认 ~/.dsh/memory-vault）
+//   MEMORY_LLM_BASE_URL / MEMORY_LLM_KEY / MEMORY_LLM_MODEL   蒸馏 LLM（OpenAI 兼容）
+//   MEMORY_ETERNAL_SKIP_AUTO=1   setup 时不动外部配置
+
+import path from 'node:path'
+import process from 'node:process'
+
+const argv = process.argv.slice(2)
+const cmd = argv[0] || 'help'
+const argOf = (name) => {
+  const i = argv.indexOf(name)
+  return i >= 0 && i + 1 < argv.length ? argv[i + 1] : null
+}
+const has = (name) => argv.includes(name)
+
+/** 取位置参数（跳过子命令、flag 与 flag 的值） */
+const positional = () => {
+  const valuesTaken = new Set(['--limit', '--vault', '--source', '--port'])
+  const out = []
+  for (let i = 1; i < argv.length; i++) {
+    const a = argv[i]
+    if (valuesTaken.has(a)) { i++; continue }
+    if (a.startsWith('--')) continue
+    out.push(a)
+  }
+  return out
+}
+
+async function main() {
+  switch (cmd) {
+    case 'recall': {
+      const query = positional().join(' ')
+      const { search } = await import('../lib/vault.js')
+      const { defaultVaultDir } = await import('../lib/capture-run.js')
+      const root = path.resolve(argOf('--vault') || defaultVaultDir())
+      const limit = Math.min(Math.max(Number(argOf('--limit')) || 5, 1), 20)
+      const hits = await search(root, query, { limit, minScore: 2 })
+      if (!hits.length) {
+        console.log(JSON.stringify({ ok: true, hits: [], note: `记忆库中没有与「${query}」相关的内容` }, null, 2))
+        return
+      }
+      console.log(JSON.stringify({ ok: true, vaultDir: root, hits }, null, 2))
+      return
+    }
+    case 'capture': {
+      const raw = positional().join(' ')
+      let text = raw
+      if (raw === '-' || (!raw && !process.stdin.isTTY)) {
+        text = await new Promise((resolve) => {
+          let buf = ''
+          process.stdin.setEncoding('utf8')
+          process.stdin.on('data', (c) => { buf += c })
+          process.stdin.on('end', () => resolve(buf))
+        })
+      }
+      const { runStandaloneCapture, defaultVaultDir } = await import('../lib/capture-run.js')
+      const root = path.resolve(defaultVaultDir())
+      const out = await runStandaloneCapture(root, text, { source: argOf('--source') || 'cli' })
+      console.log(JSON.stringify({ ...out, vaultDir: root }, null, 2))
+      process.exitCode = out.ok ? 0 : 1
+      return
+    }
+    case 'serve': {
+      const { startWebServer, DEFAULT_WEB_PORT } = await import('../lib/web.js')
+      const { defaultVaultDir } = await import('../lib/capture-run.js')
+      const port = Number(argOf('--port')) || DEFAULT_WEB_PORT
+      const vault = path.resolve(argOf('--vault') || defaultVaultDir())
+      await startWebServer({ port, vaultRoot: vault })
+      process.on('SIGINT', () => process.exit(0))
+      process.on('SIGTERM', () => process.exit(0))
+      return
+    }
+    case 'open': {
+      const { ensureWebServer, DEFAULT_WEB_PORT } = await import('../lib/web.js')
+      const { defaultVaultDir } = await import('../lib/capture-run.js')
+      const port = Number(argOf('--port')) || DEFAULT_WEB_PORT
+      const { url } = await ensureWebServer({ port, vaultRoot: path.resolve(defaultVaultDir()) })
+      console.log(url)
+      const plat = process.platform
+      const { exec } = await import('node:child_process')
+      if (plat === 'win32') exec(`start "" "${url}"`)
+      else if (plat === 'darwin') exec(`open "${url}"`)
+      else exec(`xdg-open "${url}"`)
+      return
+    }
+    case 'mcp': {
+      const { startMcpServer } = await import('../lib/mcp.js')
+      startMcpServer()
+      return
+    }
+    case 'setup': {
+      const { runSetup } = await import('../lib/setup.js')
+      const only = []
+      if (has('--claude-only')) only.push('claude')
+      if (has('--codex-only')) only.push('codex')
+      if (has('--cursor-only')) only.push('cursor')
+      const out = await runSetup({ only, withHooks: !has('--no-hooks'), dryRun: has('--dry-run') })
+      const done = out.results.filter((r) => r.ok).length
+      console.log(`\n记忆库目录：默认 ~/.dsh/memory-vault（MEMORY_VAULT_DIR 可改）`)
+      console.log(`完成：${done}/${out.results.length} 项。Web UI: dsh-memory open`)
+      return
+    }
+    case 'sweep': {
+      const dir = argv[1]
+      if (!dir || dir.startsWith('--')) {
+        console.error('用法：dsh-memory sweep <dir>（如 ~/.claude/projects）')
+        process.exitCode = 1
+        return
+      }
+      const { sweepSessions } = await import('../lib/sweep.js')
+      const out = await sweepSessions(dir)
+      console.log(JSON.stringify(out, null, 2))
+      return
+    }
+    default:
+      console.log(`dsh-memory — 记忆核心 CLI
+
+用法：
+  dsh-memory recall <query> [--limit N]      检索知识卡
+  dsh-memory capture <text | -> [--source T] 手动沉淀（- 读 stdin）
+  dsh-memory serve [--port N]                Web UI（前台）
+  dsh-memory open                            确保 Web 存活并打开浏览器
+  dsh-memory mcp                             MCP stdio server
+  dsh-memory setup [--dry-run] ...           自动挂载 MCP 到已装 agent
+  dsh-memory sweep <dir>                     挖掘会话 JSONL
+
+环境变量：MEMORY_VAULT_DIR / MEMORY_LLM_BASE_URL / MEMORY_LLM_KEY / MEMORY_LLM_MODEL`)
+  }
+}
+
+main().catch((error) => {
+  console.error(String(error?.stack || error))
+  process.exit(1)
+})

package/hooks/claude-session.js

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+// 记忆核心 · Claude Code SessionEnd/PreCompact hook（Windows 友好，纯 node）。
+//
+// Claude Code 在会话结束/压缩前触发，stdin 传入 JSON：
+//   { session_id, transcript_path, hook_event_name, cwd, ... }
+// 本脚本解析 transcript JSONL，提取最近若干轮 user/assistant 文本，蒸馏入库。
+// 由 lib/setup.js 自动注册到 ~/.claude/settings.json 的 hooks.SessionEnd。
+//
+// 特性：静默失败（hook 崩溃不能影响 Claude Code）；幂等（重复跑同一段只追加）。
+
+import { promises as fs } from 'node:fs'
+import path from 'node:path'
+
+async function main() {
+  let input = {}
+  try {
+    const raw = await new Promise((resolve) => {
+      let buf = ''
+      process.stdin.setEncoding('utf8')
+      process.stdin.on('data', (c) => { buf += c })
+      process.stdin.on('end', () => resolve(buf))
+      setTimeout(() => resolve(buf), 2000)
+    })
+    input = JSON.parse(raw || '{}')
+  } catch { /* 静默 */ }
+
+  const transcriptPath = input.transcript_path
+  if (!transcriptPath) return
+  let lines
+  try { lines = (await fs.readFile(transcriptPath, 'utf8')).split('\n').filter(Boolean) } catch { return }
+
+  // 提取尾部对话文本（user 与 assistant 的 message.content 文本部分）
+  const texts = []
+  for (const line of lines.slice(-400)) {
+    let rec
+    try { rec = JSON.parse(line) } catch { continue }
+    const msg = rec?.message
+    if (!msg || !msg.role) continue
+    const content = msg.content
+    let text = ''
+    if (typeof content === 'string') text = content
+    else if (Array.isArray(content)) {
+      text = content.filter((c) => c?.type === 'text').map((c) => c.text).join('\n')
+    }
+    if (text && text.trim().length > 4) texts.push(`${msg.role}: ${text.trim()}`)
+  }
+  const conversation = texts.slice(-30).join('\n\n')
+  if (conversation.trim().length < 120) return
+
+  const { runStandaloneCapture, defaultVaultDir } = await import('../lib/capture-run.js')
+  await runStandaloneCapture(defaultVaultDir(), conversation, {
+    source: `claude-code:${input.session_id || path.basename(transcriptPath)}`,
+  })
+}
+
+main().catch(() => { /* hook 静默失败 */ })

package/index.js

@@ -19,9 +19,9 @@ import path from 'node:path'
 import os from 'node:os'
 import z from '@deepseek-ai/schemastery'
 import { defineTool } from '@deepseek-ai/dsh-tools'
-import { ensureVault, listCards, readCard, search, searchAll, graph, graphAll, overview, exportCards, deleteCard, writeCard, parseCard, stats, optimizeCandidates, readFeedback, addFeedback, dailyBrief, generateDailyBrief, mergeCards, dailyCounts } from './lib/vault.js'
-import { compressExcerpt } from './lib/capture.js'
+import { ensureVault, search, generateDailyBrief } from './lib/vault.js'
 import { summarizeTurn, extractLastTurn, sliceNewEvents, resolveRoute, captureCard, captureUpdate, pickNeighbors } from './lib/capture.js'
+import { createApi, json } from './lib/api.js'
 
 export const name = 'memory-eternal'
 export const inject = ['systemPrompt', 'settings']
@@ -46,6 +46,10 @@ export const Config = z.object({
   recallEmbedding: z.string().default(''),
   // 会话级 token 预算（字符），供 harness 触发压缩/轮换；记忆侧提供估算与阈值
   sessionBudgetChars: z.number().default(80000),
+  // 多宿主：激活时自动把 MCP 挂载到本机已装的 Claude Code/Codex/Cursor（幂等，
+  // MEMORY_ETERNAL_SKIP_AUTO=1 可完全禁用）；web server 默认常驻（UI 唯一真源）。
+  autoMcpSetup: z.boolean().default(true),
+  autoWeb: z.boolean().default(true),
 })
 
 const API_PREFIX = '/memory-eternal/api'
@@ -250,14 +254,24 @@ export function apply(ctx, config) {
   ctx.effect(() => () => clearInterval(briefTimer), 'memory-eternal: daily brief timer')
 
   // -- 3. 知识库 JSON API（客户端设置页数据源） ----------------------------
+  // 多宿主状态：web server 常驻地址（ensureWebServer 的结果，client 壳经
+  // /web-info 读取后用 iframe 渲染 web 端 UI——DSH 渲染也走 web，单一真源）。
+  let webInfo = { url: 'http://127.0.0.1:7999', port: 7999, alive: false }
+  const refreshWebInfo = (info) => { if (info && info.url) webInfo = { ...info, alive: true } }
+
   const webServer = ctx.get('webServer')
   if (webServer !== undefined) {
+    const handleApi = createApi({ vaultDir, vaultRoots, getSettings: settings.get })
     webServer.register({
       kind: 'prefix',
       path: API_PREFIX,
       handler: async (req, res) => {
         try {
-          await handleApi(req, res, vaultDir())
+          const pathname = new URL(req.url, 'http://localhost').pathname
+          if (pathname === API_PREFIX + '/web-info') {
+            return json(res, 200, { ok: true, ...webInfo })
+          }
+          await handleApi(req, res)
         } catch (error) {
           json(res, 500, { ok: false, error: String(error?.message || error) })
         }
@@ -265,175 +279,27 @@ export function apply(ctx, config) {
     })
   }
 
+  // -- 4. 多宿主常驻：自动挂载 MCP + web server 保活 -------------------------
+  // 全部后台异步、静默失败：插件激活不能被外部环境问题卡住。
+  ctx.effect(() => {
+    const cfg0 = settings.get() ?? {}
+    if (cfg0.enabled !== false && cfg0.autoMcpSetup !== false && process.env.MEMORY_ETERNAL_SKIP_AUTO !== '1') {
+      import('./lib/setup.js')
+        .then((m) => m.runSetup({ log: () => {} }))
+        .catch(() => {})
+    }
+    if (cfg0.enabled !== false && cfg0.autoWeb !== false) {
+      import('./lib/web.js')
+        .then((m) => m.ensureWebServer({ vaultRoot: vaultDir() }))
+        .then(refreshWebInfo)
+        .catch((error) => console.error('[memory-eternal] web server failed:', error?.message || error))
+    }
+    return () => {}
+  }, 'memory-eternal: multi-host ensure')
+
   // 首次激活时确保 vault 目录存在。
   ctx.effect(() => {
     const root = vaultDir()
     ensureVault(root).catch((error) => console.error('[memory-eternal] ensureVault failed:', error))
   }, 'memory-eternal: ensure vault')
 }
-
-// -- API -------------------------------------------------------------------
-
-async function handleApi(req, res, vaultRoot) {
-  const url = new URL(req.url, 'http://localhost')
-  const route = url.pathname.slice(API_PREFIX.length).replace(/\/+$/, '') || '/overview'
-  const query = url.searchParams
-
-  switch (route) {
-    case '/overview': {
-      await ensureVault(vaultRoot)
-      json(res, 200, { ok: true, vaultDir: vaultRoot, ...(await overview(vaultRoot)) })
-      return
-    }
-    case '/cards': {
-      const kind = query.get('kind') || ''
-      const q = query.get('q') || ''
-      const limit = Math.min(Number(query.get('limit')) || 200, 500)
-      let cards = await listCards(vaultRoot)
-      if (kind) cards = cards.filter((c) => c.kind === kind)
-      if (q.trim()) {
-        const hits = await search(vaultRoot, q, { limit: 200 })
-        const hitPaths = new Set(hits.map((h) => h.path))
-        cards = cards.filter((c) => hitPaths.has(c.path))
-      }
-      json(res, 200, { ok: true, cards: cards.slice(0, limit) })
-      return
-    }
-    case '/card': {
-      const rel = query.get('path') || ''
-      if (!rel) return json(res, 400, { ok: false, error: '缺少 path' })
-      const text = await readCard(vaultRoot, rel)
-      json(res, 200, { ok: true, path: rel, text })
-      return
-    }
-    case '/search': {
-      const q = query.get('q') || ''
-      if (!q.trim()) return json(res, 200, { ok: true, hits: [] })
-      const all = query.get('all') === '1'
-      const semantic = query.get('semantic') === '1'
-      let hits
-      try { hits = all ? await searchAll(vaultRoots(), q, { limit: 30, semantic }) : await search(vaultRoot, q, { limit: 30, semantic }) }
-      catch (e) { hits = await search(vaultRoot, q, { limit: 30, semantic }) }
-      json(res, 200, { ok: true, hits })
-      return
-    }
-    case '/graph': {
-      await ensureVault(vaultRoot)
-      const all = query.get('all') === '1'
-      let g
-      try { g = all ? await graphAll(vaultRoots()) : await graph(vaultRoot) }
-      catch (e) { g = await graph(vaultRoot) }
-      json(res, 200, { ok: true, ...g })
-      return
-    }
-    case '/todayBrief': {
-      await ensureVault(vaultRoot)
-      const s = await stats(vaultRoot)
-      json(res, 200, { ok: true, today: s.today, brief: dailyBrief(s.todayCards) })
-      return
-    }
-    case '/export': {
-      await ensureVault(vaultRoot)
-      json(res, 200, { ok: true, cards: await exportCards(vaultRoot) })
-      return
-    }
-    case '/delete': {
-      const rel = query.get('path') || ''
-      if (!rel) return json(res, 400, { ok: false, error: '缺少 path' })
-      await deleteCard(vaultRoot, rel)
-      json(res, 200, { ok: true })
-      return
-    }
-    case '/write': {
-      let raw = ''
-      for await (const chunk of req) raw += chunk
-      let body
-      try { body = JSON.parse(raw || '{}') } catch { return json(res, 400, { ok: false, error: 'JSON 解析失败' }) }
-      if (!body.body) return json(res, 400, { ok: false, error: '缺少正文' })
-      await ensureVault(vaultRoot)
-      const r = await writeCard(vaultRoot, { kind: body.kind || 'knowledge', title: body.title || '无标题', tags: body.tags || [], body: body.body, source: body.source || 'manual' }, { dedup: false })
-      json(res, 200, r)
-      return
-    }
-    case '/import': {
-      let raw = ''
-      for await (const chunk of req) raw += chunk
-      if (raw.length > 20 * 1024 * 1024) return json(res, 413, { ok: false, error: '文件过大' })
-      let payload
-      try { payload = JSON.parse(raw || '{}') } catch { return json(res, 400, { ok: false, error: 'JSON 解析失败' }) }
-      const list = payload.cards || []
-      if (!Array.isArray(list)) return json(res, 400, { ok: false, error: '缺少 cards 数组' })
-      let imported = 0, skipped = 0
-      for (const c of list) {
-        const text = c.text || ''
-        let kind = c.kind || 'knowledge', title = c.title || '导入记忆', tags = [], body = text, source = ''
-        try { const p = parseCard(text); kind = p.meta.kind || kind; title = p.meta.title || title; tags = p.meta.tags || tags; body = p.body; source = p.meta.source } catch {}
-        const r = await writeCard(vaultRoot, { kind, title, tags, body, source })
-        if (r.ok) imported++; else skipped++
-      }
-      json(res, 200, { ok: true, imported, skipped })
-      return
-    }
-    case '/merge': {
-      const paths = (query.get('paths') || '').split(',').map((p) => p.trim()).filter(Boolean)
-      const r = await mergeCards(vaultRoot, paths)
-      if (!r.ok) return json(res, 400, r)
-      json(res, 200, r)
-      return
-    }
-    case '/stats': {
-      await ensureVault(vaultRoot)
-      const days = Math.min(Number(query.get('days')) || 30, 90)
-      json(res, 200, { ok: true, ...(await stats(vaultRoot)), trend: await dailyCounts(vaultRoot, days) })
-      return
-    }
-    case '/optimize': {
-      // 非破坏性：只返回「整理建议」（相似卡对 + 陈旧卡），不自动删改。
-      json(res, 200, { ok: true, ...(await optimizeCandidates(vaultRoot)) })
-      return
-    }
-    case '/feedback': {
-      let raw = ''
-      for await (const chunk of req) raw += chunk
-      let rec
-      try { rec = JSON.parse(raw || '{}') } catch { return json(res, 400, { ok: false, error: 'JSON 解析失败' }) }
-      if (!rec || !rec.path) return json(res, 400, { ok: false, error: '缺少 path' })
-      await addFeedback(vaultRoot, { query: String(rec.query || ''), path: String(rec.path || ''), useful: rec.useful === true })
-      json(res, 200, { ok: true })
-      return
-    }
-    case '/budget': {
-      try {
-        const cfg = settings.get() ?? {}
-        json(res, 200, { ok: true, budgetChars: cfg.sessionBudgetChars ?? 80000, recallLimit: cfg.recallLimit ?? 5, embedding: cfg.recallEmbedding || '' })
-      } catch (e) {
-        // 配置读取异常时降级返回默认值，避免面板整块红屏
-        json(res, 200, { ok: true, budgetChars: 80000, recallLimit: 5, embedding: '' })
-      }
-      return
-    }
-    case '/compress': {
-      // 记忆侧「压缩产物」接口：供 harness 在会话内压缩旧轮次时调用，返回一段可注入的摘要。
-      const cfg = settings.get() ?? {}
-      const body = new URLSearchParams(query)
-      const text = body.get('text') || ''
-      const maxChars = Math.min(Number(body.get('max')) || 2400, 6000)
-      if (!text.trim()) return json(res, 400, { ok: false, error: '缺少 text' })
-      const compressed = await compressExcerpt(text, maxChars)
-      json(res, 200, { ok: true, compressed, budgetChars: cfg.sessionBudgetChars ?? 80000 })
-      return
-    }
-    default:
-      json(res, 404, { ok: false, error: '未知接口' })
-  }
-}
-
-function json(res, status, body) {
-  const payload = JSON.stringify(body)
-  res.writeHead(status, {
-    'Content-Type': 'application/json; charset=utf-8',
-    'Content-Length': Buffer.byteLength(payload),
-    'Cache-Control': 'no-store',
-  })
-  res.end(payload)
-}