@morningljn/mnemo 0.1.3 → 0.2.0

package/openspec/changes/archive/2026-05-15-mnemo-mcp/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-05-15

package/openspec/changes/archive/2026-05-15-mnemo-mcp/design.md

@@ -0,0 +1,83 @@
+## Context
+
+Ocean CLI（ocean-cc-cli）内置了一套从 Hermes 项目移植的结构化事实记忆系统，核心代码在 `src/memory/` 目录下约 2000 行 TypeScript。该系统包含：
+
+- **存储层**：MemoryStore（SQLite + FTS5，`bun:sqlite` 绑定）
+- **检索层**：FactRetriever（5 级 fallback 混合检索管线）
+- **编排层**：MemoryManager + MemoryProvider 抽象 + HolographicProvider 实现
+- **辅助**：安全扫描（security.ts）、类型定义（types.ts）、DDL（schema.ts）、注入工具（injection.ts）
+
+系统被设计为"双层存储"（全局库 + 项目库）+ 多 provider 编排，与 Ocean CLI 的生命周期深度耦合。
+
+目标：将核心存储和检索逻辑提取为独立 MCP server，支持 Claude Code 和 Codex 等任意 MCP 客户端。
+
+## Goals / Non-Goals
+
+**Goals:**
+- 独立 npm 包 `mnemo-mcp`，一行配置即可在任何 MCP 客户端使用
+- 忠实移植全部核心算法（检索管线、去重、信任、矛盾、关键词、双语）
+- Node.js 兼容（使用 `better-sqlite3` 替代 `bun:sqlite`）
+- 单库存储 `~/.mnemo/facts.db`，去掉项目库概念
+- 零外部服务依赖，纯本地运行
+
+**Non-Goals:**
+- 不做多用户 / 中心化存储
+- 不做 system prompt 注入逻辑（MCP 客户端自行决定如何消费数据）
+- 不做项目库 / 双层架构
+- 不做数据迁移工具（v1 用户可手动复制 SQLite 文件）
+- 不做 Web UI / 管理界面
+- 不修改 Ocean CLI 现有代码
+
+## Decisions
+
+### 1. SQLite 绑定：better-sqlite3
+
+**选择**：better-sqlite3
+**替代方案**：sql.js（纯 WASM）、drizzle-orm（抽象层）
+**理由**：better-sqlite3 是 Node.js 生态最成熟的 SQLite 绑定，同步 API（和 bun:sqlite 一致），迁移成本最低。sql.js 性能差，drizzle 多一层抽象没必要。
+
+### 2. 传输协议：stdio
+
+**选择**：MCP stdio transport
+**替代方案**：SSE transport（HTTP 长连接）
+**理由**：本地工具标准模式，所有 MCP 客户端都支持 stdio。SSE 适合远程/多用户场景，v1 不需要。
+
+### 3. 项目结构
+
+```
+mnemo-mcp/
+├── src/
+│   ├── server.ts        # MCP 入口，注册 tools
+│   ├── store.ts          # MemoryStore 移植（better-sqlite3）
+│   ├── retriever.ts      # FactRetriever 移植
+│   ├── schema.ts         # DDL
+│   ├── security.ts       # 安全扫描
+│   └── types.ts          # 类型定义
+├── package.json
+├── tsconfig.json
+└── README.md
+```
+
+**理由**：扁平结构，6 个文件，无子目录嵌套。核心代码从 Ocean CLI 直接移植，只改 import 和 SQLite 绑定。
+
+### 4. category 保留 5 个固定分类
+
+**选择**：identity / coding_style / tool_pref / workflow / general
+**理由**：v1 不动分类，保持和 Ocean CLI 一致，降低移植风险。后续根据用户反馈迭代。
+
+### 5. 去掉编排层和抽象
+
+**选择**：不移植 MemoryManager、MemoryProvider、HolographicProvider、instance.ts、injection.ts
+**理由**：MCP server 只需要一个 store + 一个 retriever，不需要 provider 抽象和编排。HolographicProvider 中的工具处理逻辑（handleFactStore/handleFactFeedback）直接下沉到 server.ts。
+
+### 6. 安全扫描保留但降低为可选
+
+**选择**：security.ts 移植但在 tool 响应中只做警告，不阻止操作
+**理由**：MCP 客户端可能是 AI 自己调用，硬拦截可能导致功能异常。检测到风险时返回 warning 字段。
+
+## Risks / Trade-offs
+
+- **[better-sqlite3 native 编译]** → 用户安装时需要 C++ 编译环境。缓解：提供 prebuilt binaries（better-sqlite3 官方已支持 prebuild）。
+- **[存储路径冲突]** → 多个 AI 工具同时写入 `~/.mnemo/facts.db`。缓解：SQLite WAL 模式支持并发读写，短锁等待即可。
+- **[算法移植遗漏]** → 直接移植代码，关键算法用 diff 对比确认无遗漏。
+- **[MCP SDK 版本]** → @modelcontextprotocol/sdk 仍在快速迭代。缓解：锁定具体版本，定期更新。

package/openspec/changes/archive/2026-05-15-mnemo-mcp/proposal.md

@@ -0,0 +1,32 @@
+## Why
+
+Ocean CLI 内置了一套结构化事实记忆系统（SQLite + FTS5），具备信任评分、实体图谱、矛盾检测、双语检索等能力。这套系统完全独立于 Ocean CLI 的业务逻辑，但被耦合在代码中，无法被其他 AI 编程工具（Codex、Cursor 等）复用。需要将其提取为独立的 MCP server，让团队成员在任意 AI 编程工具中使用同一套个人记忆。
+
+## What Changes
+
+- 新建独立项目 `mnemo-mcp`，从 Ocean CLI 移植核心记忆逻辑
+- 砍掉编排层（MemoryManager、MemoryProvider 抽象、instance 单例）
+- 砍掉注入层（system prompt 拼接、围栏注入、prefetch 机制）
+- 砍掉项目库双层存储，简化为单库 `~/.mnemo/facts.db`
+- 将 `bun:sqlite` 替换为 `better-sqlite3`（Node.js 兼容）
+- 新增 MCP server 入口，使用 `@modelcontextprotocol/sdk` 注册 tools
+- 保留完整的核心算法：检索管线、去重、信任衰减、矛盾检测、关键词提取、双语扩展、安全扫描
+
+## Capabilities
+
+### New Capabilities
+- `mcp-server`: MCP 协议适配层，注册 fact_store / fact_feedback 两个 tools，stdio transport
+- `fact-store`: 结构化事实存储核心（SQLite + FTS5 + 实体图谱 + 信任评分 + 矛盾检测）
+- `fact-retrieval`: 混合检索管线（FTS5 → LIKE → 字符交叉 → 分类推断 → trust fallback），含双语扩展和 category 信号
+- `security`: 安全扫描（注入检测、PII 检测、不可见 Unicode）
+
+### Modified Capabilities
+
+（无，全新项目）
+
+## Impact
+
+- 新项目依赖：better-sqlite3、@modelcontextprotocol/sdk、TypeScript
+- 存储位置：`~/.mnemo/facts.db`（独立于 `~/.claude/`）
+- 配置方式：各 AI 工具的 MCP server 配置文件中添加 mnemo-mcp
+- 用户数据：从 Ocean CLI 的 `~/.claude/memory/facts.db` 迁移脚本（可选）

package/openspec/changes/archive/2026-05-15-mnemo-mcp/specs/fact-retrieval/spec.md

@@ -0,0 +1,75 @@
+## ADDED Requirements
+
+### Requirement: 多级 fallback 检索
+系统 SHALL 实现 5 级 fallback 检索管线：FTS5 → LIKE → 字符交叉 → 分类推断 → trust fallback。
+
+#### Scenario: FTS5 命中
+- **WHEN** 搜索 "用户偏好" 且 FTS5 索引返回匹配结果
+- **THEN** 返回 FTS5 候选集，进入 Jaccard + 信任 + 时间衰减重排序
+
+#### Scenario: FTS5 无结果 fallback 到 LIKE
+- **WHEN** FTS5 无匹配
+- **THEN** 使用 LIKE 模糊匹配（含中文 bigram/trigram 滑动窗口）
+
+#### Scenario: LIKE 无结果 fallback 到字符交叉
+- **WHEN** LIKE 也无匹配
+- **THEN** 提取查询中文字符，与事实内容做单字交叉匹配（≥40% 命中率）
+
+#### Scenario: 全部无结果 fallback 到 trust
+- **WHEN** 所有检索级别都无匹配且查询为个人/身份相关
+- **THEN** 按 trust_score 返回 top-N 事实
+
+### Requirement: 检索结果评分
+系统 SHALL 对检索结果计算综合评分：FTS 权重 × ftsScore + Jaccard 权重 × (0.20 × Jaccard + 0.45 × Containment + 0.35 × KeywordScore) × trustScore × 时间衰减。
+
+#### Scenario: 评分排序
+- **WHEN** 搜索返回多条结果
+- **THEN** 按综合评分降序排列
+
+#### Scenario: Category 信号强化
+- **WHEN** 查询命中某个 category 的特有 tag
+- **THEN** 该 category 的事实获得乘法强化（1 + 0.5 × 集中度 × 归一化信号）
+
+### Requirement: Category 多样性
+系统 SHALL 在返回结果中保证 category 多样性，避免同类事实垄断。
+
+#### Scenario: 去重补位
+- **WHEN** 返回结果中同一 category 事实过多
+- **THEN** 每个 category 优先保留评分最高的，不足 limit 时从原列表补位
+
+### Requirement: 检索追踪
+系统 SHALL 追踪检索命中的事实，递增 retrieval_count，top 3 的 trust_score += 0.01 并重置 updated_at。
+
+#### Scenario: 命中追踪
+- **WHEN** search 返回结果
+- **THEN** 所有返回事实的 retrieval_count += 1，top 3 获得信任微增和时间续命
+
+### Requirement: 高级检索操作
+系统 SHALL 支持 probe（实体探测）、related（实体关联）、reason（多实体推理）、contradict（矛盾检测）四种高级操作。
+
+#### Scenario: 实体探测
+- **WHEN** 调用 `fact_store(action="probe", entity="TypeScript")`
+- **THEN** 返回所有关联 TypeScript 实体的事实
+
+#### Scenario: 实体关联
+- **WHEN** 调用 `fact_store(action="related", entity="TypeScript")`
+- **THEN** 返回与 TypeScript 共享上下文的其他实体关联的事实（排除原始事实）
+
+#### Scenario: 多实体推理
+- **WHEN** 调用 `fact_store(action="reason", entities=["TypeScript", "测试"])`
+- **THEN** 返回同时关联两个实体的事实
+
+#### Scenario: 矛盾检测
+- **WHEN** 调用 `fact_store(action="contradict")`
+- **THEN** 返回高实体重叠 + 低内容相似度的矛盾事实对
+
+### Requirement: 双语查询扩展
+系统 SHALL 自动学习中英术语对照，搜索时将查询中的术语翻译为对端语言。
+
+#### Scenario: 中文搜英文
+- **WHEN** 搜索 "部署" 且已学习 "部署→deploy" 映射
+- **THEN** 查询扩展为 "部署 deploy"，同时命中中英文事实
+
+#### Scenario: 英文搜中文
+- **WHEN** 搜索 "cache" 且已学习 "缓存→cache" 映射
+- **THEN** 查询扩展为 "cache 缓存"

package/openspec/changes/archive/2026-05-15-mnemo-mcp/specs/fact-store/spec.md

@@ -0,0 +1,83 @@
+## ADDED Requirements
+
+### Requirement: 事实 CRUD
+系统 SHALL 支持 add / update / remove / list 四种事实操作，事实以 (content, category, tags, trust_score) 结构存储。
+
+#### Scenario: 添加新事实
+- **WHEN** 调用 `fact_store(action="add", content="用户偏好深色主题", category="tool_pref", tags="theme,dark")`
+- **THEN** 创建事实记录，返回 `{"fact_id": N, "status": "added", "category": "tool_pref"}`
+
+#### Scenario: 添加重复事实
+- **WHEN** 调用 add 时 content 与已有事实精确相同
+- **THEN** 返回已有 fact_id，不创建重复记录
+
+#### Scenario: 添加相似事实
+- **WHEN** 调用 add 时 content 与已有事实通过三层去重检测（实体重叠+编辑距离 / Jaccard / Containment）判定为相似
+- **THEN** 更新已有事实内容，返回 `{"fact_id": N, "status": "updated", "reason": "similar_fact_merged"}`
+
+#### Scenario: 更新事实
+- **WHEN** 调用 `fact_store(action="update", fact_id=1, content="新内容", trust_delta=0.1)`
+- **THEN** 更新指定事实的字段，重新提取实体
+
+#### Scenario: 删除事实
+- **WHEN** 调用 `fact_store(action="remove", fact_id=1)`
+- **THEN** 删除事实及其实体关联，清理孤立实体
+
+#### Scenario: 浏览事实
+- **WHEN** 调用 `fact_store(action="list", category="identity", min_trust=0.5, limit=10)`
+- **THEN** 返回符合条件的事实列表，按 trust_score 降序
+
+### Requirement: 实体自动提取
+系统 SHALL 从事实内容中自动提取中英文实体并建立关联图谱。
+
+#### Scenario: 英文实体提取
+- **WHEN** 添加内容包含大写首字母词组（如 "Visual Studio Code"）、引号包裹词（如 "TypeScript"）
+- **THEN** 提取为实体，创建 entity 记录，关联到事实
+
+#### Scenario: 中文实体提取
+- **WHEN** 添加内容包含书名号（如《设计模式》）、引号包裹（如「记忆系统」）、声明模式（如"我叫暖暖"）
+- **THEN** 提取为实体，创建 entity 记录
+
+### Requirement: 信任评分系统
+系统 SHALL 维护每个事实的 trust_score（0.0~1.0），支持反馈调整和时间衰减。
+
+#### Scenario: 正向反馈
+- **WHEN** 调用 `fact_feedback(action="helpful", fact_id=1)`
+- **THEN** trust_score += 0.05（上限 1.0），helpful_count += 1
+
+#### Scenario: 负向反馈
+- **WHEN** 调用 `fact_feedback(action="unhelpful", fact_id=1)`
+- **THEN** trust_score -= 0.10（下限 0.0）
+
+#### Scenario: 时间衰减
+- **WHEN** session 启动时执行信任衰减
+- **THEN** 超过宽限期的事实按 category 配置的速率衰减，trust_score < 0.1 的自动删除
+
+### Requirement: 矛盾检测
+系统 SHALL 在写入新事实时检测同 category 中共享实体但内容冲突的旧事实，自动降权。
+
+#### Scenario: 写入时矛盾降权
+- **WHEN** 添加新事实后，同 category 中存在共享实体但编辑距离在 0.2~0.5 区间的旧事实
+- **THEN** 旧事实 trust_score -= 0.10
+
+#### Scenario: 启动时矛盾审计
+- **WHEN** server 启动时
+- **THEN** 扫描所有事实对（实体 JOIN + Jaccard 双层），降权较旧的矛盾事实
+
+### Requirement: 关键词提取
+系统 SHALL 从事实内容中自动提取主题关键词，用于检索增强。
+
+#### Scenario: 关键词生成
+- **WHEN** 添加或更新事实
+- **THEN** 从 content + tags 中提取关键词（位置权重 × 频率 × 类别特异性 × tags 加权），存储为 JSON 数组
+
+### Requirement: 分类固定为 5 个
+系统 SHALL 支持固定的 5 个 category：identity / coding_style / tool_pref / workflow / general。
+
+#### Scenario: 使用有效 category
+- **WHEN** 调用 add 时 category 为 5 个之一
+- **THEN** 正常存储
+
+#### Scenario: 未指定 category
+- **WHEN** 调用 add 时未提供 category
+- **THEN** 默认为 "general"

package/openspec/changes/archive/2026-05-15-mnemo-mcp/specs/mcp-server/spec.md

@@ -0,0 +1,34 @@
+## ADDED Requirements
+
+### Requirement: MCP server 启动与工具注册
+系统 SHALL 作为 MCP server 通过 stdio transport 运行，注册 `fact_store` 和 `fact_feedback` 两个 tools。
+
+#### Scenario: 正常启动
+- **WHEN** 运行 `npx mnemo-mcp` 或 `node dist/server.js`
+- **THEN** server 通过 stdio 建立 MCP 连接，注册 fact_store（9 个 action）和 fact_feedback（2 个 action）两个 tools
+
+#### Scenario: 客户端连接
+- **WHEN** Claude Code 或 Codex 通过 MCP 配置启动 mnemo-mcp
+- **THEN** server 响应 `tools/list` 请求返回两个 tool schema，响应 `tools/call` 请求执行对应操作
+
+### Requirement: 存储路径
+系统 SHALL 使用 `~/.mnemo/facts.db` 作为默认存储路径，目录不存在时自动创建。
+
+#### Scenario: 首次运行
+- **WHEN** `~/.mnemo/` 目录不存在
+- **THEN** server 自动创建目录和数据库文件，执行 schema 初始化
+
+#### Scenario: 数据库已存在
+- **WHEN** `~/.mnemo/facts.db` 已存在
+- **THEN** server 打开已有数据库，执行增量迁移（如添加新列），不破坏已有数据
+
+### Requirement: 错误处理
+系统 SHALL 在 tool 调用失败时返回包含 error 字段的 JSON，不抛出未捕获异常。
+
+#### Scenario: 无效 action
+- **WHEN** fact_store 被调用且 action 为未知值
+- **THEN** 返回 `{"error": "Unknown action: xxx"}`
+
+#### Scenario: 缺少必需参数
+- **WHEN** add action 缺少 content 参数
+- **THEN** 返回 `{"error": "Missing required argument: content"}`

package/openspec/changes/archive/2026-05-15-mnemo-mcp/specs/security/spec.md

@@ -0,0 +1,37 @@
+## ADDED Requirements
+
+### Requirement: 提示注入检测
+系统 SHALL 检测记忆内容中的提示注入尝试（伪造围栏标签、system-reminder 伪装、注入指令模式）。
+
+#### Scenario: 检测到注入
+- **WHEN** 添加的内容包含 `<memory-context>` 标签或 "ignore previous instructions" 模式
+- **THEN** 返回结果中包含 warnings 字段标记风险
+
+#### Scenario: 安全内容
+- **WHEN** 添加的内容无注入特征
+- **THEN** 正常存储，不附加 warnings
+
+### Requirement: PII 检测
+系统 SHALL 检测记忆内容中的个人信息（邮箱、API 密钥模式）。
+
+#### Scenario: 检测到邮箱
+- **WHEN** 添加的内容包含邮箱地址
+- **THEN** 返回 warnings 字段提示"包含邮箱地址"，但不阻止存储
+
+#### Scenario: 检测到 API 密钥
+- **WHEN** 添加的内容匹配 API 密钥模式（sk-xxx、ghp_xxx 等）
+- **THEN** 返回 warnings 字段提示"包含 API 密钥模式"
+
+### Requirement: 不可见 Unicode 检测
+系统 SHALL 检测记忆内容中的不可见 Unicode 字符（零宽字符、控制字符、BOM 等）。
+
+#### Scenario: 零宽字符检测
+- **WHEN** 添加的内容包含 U+200B~U+200F 范围的零宽字符
+- **THEN** 返回 warnings 字段提示具体字符类型
+
+### Requirement: 安全警告不阻止操作
+系统 SHALL 将安全检测结果作为 warnings 返回，不阻止事实的存储或检索操作。
+
+#### Scenario: 有警告但操作成功
+- **WHEN** 添加的事实通过安全扫描发现 PII
+- **THEN** 事实正常存储，响应中附加 `"warnings": ["包含邮箱地址"]` 字段

package/openspec/changes/archive/2026-05-15-mnemo-mcp/tasks.md

@@ -0,0 +1,44 @@
+## 1. 项目初始化
+
+- [ ] 1.1 在 `~/Documents/demo/ocean/mnemo-mcp/` 创建项目目录，初始化 package.json（name: mnemo-mcp, bin 入口, dependencies: better-sqlite3, @modelcontextprotocol/sdk）
+- [ ] 1.2 创建 tsconfig.json（target: ES2022, module: NodeNext, outDir: dist）
+- [ ] 1.3 创建项目骨架文件：src/server.ts, src/store.ts, src/retriever.ts, src/schema.ts, src/security.ts, src/types.ts
+
+## 2. 类型与 Schema 移植
+
+- [ ] 2.1 移植 types.ts：去掉 ProviderContext/ToolSchema 等 Ocean CLI 特有类型，保留 Fact/ScoredFact/Contradiction/SearchOptions/FactStoreArgs/FactFeedbackArgs/FactCategory 等核心类型
+- [ ] 2.2 移植 schema.ts：去掉 doc_index 表和 category_token_stats 表（v1 简化），保留 facts + entities + fact_entities + FTS5 索引 + 触发器
+
+## 3. 存储层移植
+
+- [ ] 3.1 移植 MemoryStore → store.ts：将 `bun:sqlite` 替换为 `better-sqlite3`，保留全部 public API（addFact/findSimilarFact/updateFact/removeFact/listFacts/recordFeedback/getFactsByEntity/getFactsByEntities/decayTrustScores/demoteContradictingFacts/auditContradictions）
+- [ ] 3.2 移植实体提取逻辑（extractEntities/resolveEntity/classifyEntity/cleanOrphanEntities）
+- [ ] 3.3 移植去重算法（三层递进：实体重叠+编辑距离 / Jaccard bigram / Containment）
+- [ ] 3.4 移植信任衰减逻辑（decayTrustScores，按 category 宽限期 + 衰减率）
+- [ ] 3.5 移植关键词提取逻辑（extractKeywords/tokenizeForKeywords/backfillKeywords + category_token_stats 表）
+
+## 4. 检索层移植
+
+- [ ] 4.1 移植 FactRetriever → retriever.ts：5 级 fallback（ftsCandidates/likeFallback/charOverlapFallback/categoryInferFallback/trustFallback）
+- [ ] 4.2 移植评分逻辑（Jaccard + Containment + KeywordScore + Category 信号乘法 + 时间衰减）
+- [ ] 4.3 移植高级检索（probe/related/reason/contradict）
+- [ ] 4.4 移植双语查询扩展（getCnEnPairs/expandQueryBilingually + 种子表）
+- [ ] 4.5 移植检索追踪（trackRetrieval: retrieval_count + top3 信任刷新）
+
+## 5. 安全扫描移植
+
+- [ ] 5.1 移植 security.ts：注入检测、PII 检测、不可见 Unicode 检测，保留全部函数签名
+
+## 6. MCP Server 入口
+
+- [ ] 6.1 实现 server.ts：McpServer 创建，stdio transport，注册 fact_store 和 fact_feedback 两个 tools
+- [ ] 6.2 实现 fact_store tool handler：9 个 action（add/search/probe/related/reason/contradict/update/remove/list），调用 store + retriever
+- [ ] 6.3 实现 fact_feedback tool handler：helpful/unhelpful 两个 action
+- [ ] 6.4 实现启动初始化：创建 ~/.mnemo/ 目录、打开/创建数据库、执行信任衰减和矛盾审计、关键词补算
+- [ ] 6.5 安全扫描集成：add/update 时调用 fullSecurityScan，将 warnings 附加到响应中
+
+## 7. 构建与验证
+
+- [ ] 7.1 配置构建脚本（tsc 编译），确认 `node dist/server.js` 可正常启动
+- [ ] 7.2 用 MCP Inspector 或手动测试验证 tools/list 和 tools/call 响应格式正确
+- [ ] 7.3 验证 add → search → feedback 完整流程可用

package/openspec/changes/archive/2026-05-16-mnemo-query-cache/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-05-16

package/openspec/changes/archive/2026-05-16-mnemo-query-cache/design.md

@@ -0,0 +1,96 @@
+## Context
+
+mnemo-mcp 作为独立 MCP server，每次 fact_store tool 调用都直接查询 SQLite（FTS5 + Jaccard + 多级 fallback）。相同 query 在短时间内重复检索浪费计算资源。同时缺少批量操作能力，一次只能 add 一条事实，MCP 往返次数多。
+
+当前查询链路：
+```
+tool call → server.ts → retriever.search() → FTS5 → Jaccard → 评分 → 返回
+```
+
+优化目标：减少重复查询开销，支持批量操作，提升整体响应速度。
+
+## Goals / Non-Goals
+
+**Goals:**
+- 实现查询结果缓存层，相同 query + 参数在 TTL 内直接返回缓存
+- 支持批量 add 操作，一次写入多条事实
+- 增加性能监控（debug 模式），记录查询耗时和缓存命中率
+- 启动时延迟加载非关键索引，减少首次响应时间
+
+**Non-Goals:**
+- 不修改检索算法（FTS5 + Jaccard 不动）
+- 不修改存储 schema（facts/entities/fact_entities 表结构不变）
+- 不做分布式缓存（单机 SQLite，本地内存缓存足够）
+- 不做持久化缓存（进程级缓存，重启失效可接受）
+
+## Decisions
+
+### 1. 缓存实现方式
+
+**选择**：进程内 Map 缓存，基于 query + category + limit + minTrust 做键
+
+```typescript
+interface CacheEntry {
+  results: ScoredFact[]
+  timestamp: number
+  queryKey: string
+}
+
+const cache = new Map<string, CacheEntry>()
+const CACHE_TTL_MS = 60_000
+```
+
+**理由**：mnemo-mcp 是单进程 MCP server，没有多进程共享需求。Map 简单高效，不需要引入 Redis 等外部依赖。
+
+### 2. 缓存失效策略
+
+**选择**：写操作（add/update/remove）时清空全部缓存
+
+**理由**：事实写入会改变查询结果，但写入频率远低于查询频率。全量清空实现简单，不需要维护复杂的依赖图。
+
+### 3. 批量 add 接口
+
+**选择**：扩展 fact_store 的 add action，支持 `content` 为数组
+
+```typescript
+// 单条（兼容现有）
+{ action: 'add', content: '事实内容', category: 'general' }
+
+// 批量（新增）
+{ action: 'add', content: ['事实1', '事实2'], category: 'general' }
+```
+
+**理由**：保持接口向后兼容，现有单条调用不受影响。批量返回数组形式的 fact_id 和状态。
+
+### 4. 性能监控
+
+**选择**：环境变量开关 `MNEMO_DEBUG=1`，开启时记录查询日志
+
+**记录内容**：
+- 查询耗时（ms）
+- 是否命中缓存
+- 检索路径（FTS5 / LIKE / charOverlap / categoryInfer / trustFallback）
+- 返回结果数
+
+**理由**：默认关闭避免性能开销，开发调试时开启。
+
+### 5. 延迟加载
+
+**选择**：启动时不预加载 category_tag_map 和 cn_en_pairs，首次查询时惰性初始化
+
+**理由**：这两个数据结构在 `FactRetriever` 中已经是惰性初始化的（`getCategoryTagMap()` 和 `getCnEnPairs()`），但启动时的 `auditContradictions` 和 `decayTrustScores` 会触发数据库全表扫描。改为启动时跳过这些操作，首次 tool 调用时再执行。
+
+## Risks / Trade-offs
+
+- **[缓存雪崩]** → 大量并发请求同时命中失效缓存。缓解：缓存失效是同步的，SQLite 的 WAL 模式本身有锁保护。
+- **[批量 add 部分失败]** → 数组中某条写入失败（如 UNIQUE 冲突）。缓解：逐条处理，返回每条独立的状态，部分成功部分失败。
+- **[延迟加载导致首次查询慢]** → 启动时跳过的审计和衰减在首次查询时执行。缓解：这些操作通常很快（<100ms），且只在首次触发。
+
+## Migration Plan
+
+无需迁移。新增功能完全向后兼容，现有 tool 调用方式不变。
+
+## Open Questions
+
+- 是否需要支持缓存预热（启动时预加载高频查询）？
+- 批量 add 是否需要支持每条不同的 category 和 tags？

package/openspec/changes/archive/2026-05-16-mnemo-query-cache/proposal.md

@@ -0,0 +1,29 @@
+## Why
+
+mnemo-mcp 作为独立 MCP server，每次 tool 调用都直接查询 SQLite（FTS5 + Jaccard + 多级 fallback），相同 query 重复检索浪费计算资源。同时缺少批量操作能力，一次只能 add 一条事实，MCP 往返次数多。需要增加查询缓存和批量操作支持，提升响应速度和用户体验。
+
+## What Changes
+
+- 增加查询结果缓存层：相同 query + 参数在 60s 内直接返回缓存结果
+- 增加批量 add 操作：支持一次写入多条事实，减少 MCP 往返
+- 增加启动性能优化：延迟加载非关键索引、异步初始化
+- 增加查询性能监控：记录检索耗时、缓存命中率（debug 模式）
+
+## Capabilities
+
+### New Capabilities
+- `query-cache`: 查询结果缓存层，基于 query + category + limit + minTrust 做缓存键，TTL 60s
+- `batch-operations`: 批量事实操作，支持一次 add 多条、一次 remove 多条
+- `perf-metrics`: 性能监控，记录查询耗时、缓存命中率、检索 fallback 路径
+
+### Modified Capabilities
+- `fact-store`: 修改 fact_store tool 的 add action，支持传入数组批量写入
+
+## Impact
+
+- 修改文件：`src/store.ts`（增加缓存层、批量操作接口）
+- 修改文件：`src/retriever.ts`（增加缓存查询、性能埋点）
+- 修改文件：`src/server.ts`（增加 batch_add handler、perf_metrics 开关）
+- 修改文件：`src/types.ts`（增加批量操作类型定义）
+- 无外部依赖变化
+- 预估性能提升：重复查询减少 80% 计算开销，批量操作减少 N 次 MCP 往返

package/openspec/changes/archive/2026-05-16-mnemo-query-cache/specs/batch-operations/spec.md

@@ -0,0 +1,42 @@
+## ADDED Requirements
+
+### Requirement: Batch add supports multiple facts in one call
+The system SHALL support adding multiple facts in a single fact_store tool call.
+
+Batch add interface:
+- The `content` field SHALL accept either a string (single fact) or an array of strings (multiple facts)
+- All facts in a batch SHALL share the same category and tags
+- The response SHALL contain an array of results, one per fact
+
+Individual result format:
+- `fact_id`: number (or -1 on error)
+- `status`: "added" | "updated" | "error"
+- `reason`: optional string explaining the result
+
+#### Scenario: Batch add multiple facts
+- **WHEN** fact_store is called with action="add", content=["事实1", "事实2"], category="general"
+- **THEN** the system SHALL process each fact sequentially
+- **AND** return an array of results with fact_id and status for each
+
+#### Scenario: Batch add with partial failure
+- **WHEN** a batch contains one valid fact and one empty string
+- **THEN** the valid fact SHALL be added successfully
+- **AND** the empty string SHALL return an error status
+- **AND** the overall response SHALL include all individual results
+
+#### Scenario: Single fact add remains compatible
+- **WHEN** fact_store is called with action="add", content="单条事实" (string, not array)
+- **THEN** the system SHALL process it as a single fact
+- **AND** return a single result object (backward compatible)
+
+### Requirement: Batch remove supports multiple fact IDs
+The system SHALL support removing multiple facts in a single fact_store tool call.
+
+Batch remove interface:
+- The `fact_id` field SHALL accept either a number (single) or an array of numbers (multiple)
+- The response SHALL contain an array of results, one per fact_id
+
+#### Scenario: Batch remove multiple facts
+- **WHEN** fact_store is called with action="remove", fact_id=[1, 2, 3]
+- **THEN** the system SHALL attempt to remove each fact
+- **AND** return an array of {fact_id, removed: boolean} results

package/openspec/changes/archive/2026-05-16-mnemo-query-cache/specs/perf-metrics/spec.md

@@ -0,0 +1,55 @@
+## ADDED Requirements
+
+### Requirement: Query execution time is recorded
+The system SHALL record the execution time of every database query when debug mode is enabled.
+
+Recorded metrics:
+- Query type (search/probe/related/reason/contradict/list)
+- Execution time in milliseconds
+- Number of results returned
+- Retrieval path (which fallback stages were used)
+
+#### Scenario: Debug mode records search timing
+- **WHEN** MNEMO_DEBUG=1 is set
+- **AND** a search query is executed
+- **THEN** the system SHALL log the query type, execution time, and result count
+
+#### Scenario: Non-debug mode skips recording
+- **WHEN** MNEMO_DEBUG is not set or is 0
+- **AND** a query is executed
+- **THEN** no performance metrics SHALL be recorded
+- **AND** no debug logs SHALL be emitted
+
+### Requirement: Retrieval path is tracked
+The system SHALL record which retrieval stages were executed for each search query.
+
+Retrieval stages:
+- FTS5 (ftsCandidates)
+- LIKE fallback (likeFallback)
+- Character overlap fallback (charOverlapFallback)
+- Category inference fallback (categoryInferFallback)
+- Trust fallback (trustFallback)
+
+#### Scenario: Search hits FTS5 path
+- **WHEN** a search query matches via FTS5
+- **THEN** the logged retrieval path SHALL include "FTS5"
+- **AND** SHALL NOT include subsequent fallback stages
+
+#### Scenario: Search falls through to LIKE
+- **WHEN** a search query finds no FTS5 results but matches via LIKE
+- **THEN** the logged retrieval path SHALL include "FTS5,LIKE"
+
+### Requirement: Cache statistics are aggregated
+The system SHALL maintain aggregate cache statistics over the process lifetime.
+
+Aggregated metrics:
+- totalQueries: total number of queries processed
+- cacheHits: number of queries served from cache
+- cacheMisses: number of queries executed against database
+- avgQueryTime: average execution time for cache misses (ms)
+- totalTimeSaved: estimated time saved by cache hits (sum of miss avg × hit count)
+
+#### Scenario: Cache stats are queryable
+- **WHEN** the system has processed multiple queries
+- **AND** MNEMO_DEBUG=1 is set
+- **THEN** a special internal call SHALL return the aggregated statistics