@morningljn/mnemo 0.1.3 → 0.1.4

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

@@ -0,0 +1,65 @@
+## ADDED Requirements
+
+### Requirement: Query results are cached with TTL
+The system SHALL cache query results and return cached data for identical queries within the TTL period.
+
+Cache key:
+- SHALL be derived from query string, category, limit, and minTrust parameters
+- SHALL NOT include trust_score or updated_at values (these change frequently)
+
+Cache behavior:
+- Cache TTL SHALL be 60 seconds by default
+- Cache SHALL be stored in process memory (Map)
+- Cache SHALL be cleared on any write operation (add/update/remove)
+
+#### Scenario: Identical query returns cached result
+- **WHEN** a search query with parameters {query: "用户偏好", category: "identity", limit: 10} is executed
+- **AND** the same query is executed again within 60 seconds
+- **THEN** the second call SHALL return the cached results
+- **AND** no database query SHALL be executed
+
+#### Scenario: Cache cleared on fact addition
+- **WHEN** a new fact is added via fact_store
+- **THEN** all cached query results SHALL be invalidated
+- **AND** the next query SHALL hit the database
+
+#### Scenario: Cache entry expires after TTL
+- **WHEN** a cached query result ages beyond 60 seconds
+- **THEN** the next identical query SHALL execute against the database
+- **AND** generate a new cache entry
+
+### Requirement: Cache supports all search actions
+The system SHALL apply caching to all read-only fact_store actions.
+
+Cached actions:
+- search
+- probe
+- related
+- reason
+- contradict
+- list
+
+Non-cached actions:
+- add
+- update
+- remove
+
+#### Scenario: Probe query is cached
+- **WHEN** a probe action is executed with entity "TypeScript"
+- **AND** the same probe is executed again within TTL
+- **THEN** the second call SHALL return cached results
+
+### Requirement: Cache hit/miss is trackable
+The system SHALL record cache statistics when debug mode is enabled.
+
+Debug metrics:
+- Total queries processed
+- Cache hits and misses
+- Cache hit ratio (hits / total)
+- Average query execution time (cache miss only)
+
+#### Scenario: Debug mode logs cache metrics
+- **WHEN** MNEMO_DEBUG=1 is set
+- **AND** a query is executed
+- **THEN** the system SHALL log whether the query was a cache hit or miss
+- **AND** SHALL include execution time for cache misses

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

@@ -0,0 +1,45 @@
+## 1. Query Cache Layer
+
+- [ ] 1.1 Create `src/cache.ts` with `QueryCache` class
+- [ ] 1.2 Implement cache key generation: hash of query + category + limit + minTrust
+- [ ] 1.3 Implement `get(key)` and `set(key, results)` with TTL (60s)
+- [ ] 1.4 Implement `clear()` for cache invalidation on writes
+- [ ] 1.5 Integrate cache into `FactRetriever.search()` — check cache before DB query
+- [ ] 1.6 Integrate cache into `FactRetriever.probe()`, `related()`, `reason()`, `contradict()`
+- [ ] 1.7 Call `cache.clear()` on add/update/remove operations in server.ts
+
+## 2. Batch Operations
+
+- [ ] 2.1 Update `FactStoreArgs` type in `src/types.ts`: `content` accepts `string | string[]`
+- [ ] 2.2 Update `fact_id` type: accepts `number | number[]` for batch remove
+- [ ] 2.3 Implement batch add handler in `server.ts`: iterate array, call `store.addFact()` per item
+- [ ] 2.4 Implement batch remove handler in `server.ts`: iterate array, call `store.removeFact()` per item
+- [ ] 2.5 Update response format: return array of individual results for batch operations
+- [ ] 2.6 Ensure backward compatibility: single string/number still works
+
+## 3. Performance Metrics
+
+- [ ] 3.1 Create `src/metrics.ts` with `PerfMetrics` class
+- [ ] 3.2 Implement query timing: record start/end timestamps around retriever calls
+- [ ] 3.3 Implement retrieval path tracking: log which fallback stages were executed
+- [ ] 3.4 Implement cache hit/miss tracking
+- [ ] 3.5 Implement aggregate statistics: totalQueries, cacheHits, cacheMisses, avgQueryTime
+- [ ] 3.6 Add `MNEMO_DEBUG` env var check: only record metrics when set to "1"
+- [ ] 3.7 Add debug log output: print metrics after each query when debug enabled
+
+## 4. Startup Optimization
+
+- [ ] 4.1 Remove `auditContradictions()` from startup path in `server.ts`
+- [ ] 4.2 Remove `decayTrustScores()` from startup path in `server.ts`
+- [ ] 4.3 Add lazy initialization: first tool call triggers audit + decay if not yet run
+- [ ] 4.4 Add flag to prevent duplicate lazy initialization
+
+## 5. Testing & Verification
+
+- [ ] 5.1 Verify identical query returns cached result within TTL
+- [ ] 5.2 Verify cache is cleared after fact addition
+- [ ] 5.3 Verify batch add works with string array
+- [ ] 5.4 Verify batch remove works with number array
+- [ ] 5.5 Verify single fact add remains backward compatible
+- [ ] 5.6 Verify debug mode logs query timing and cache stats
+- [ ] 5.7 Verify startup is faster (no immediate audit/decay)

package/openspec/changes/retrieval-and-injection-optimization/.openspec.yaml

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

package/openspec/changes/retrieval-and-injection-optimization/design.md

@@ -0,0 +1,117 @@
+## Context
+
+mnemo-mcp 是纯全局记忆 MCP server，服务于 Claude Code / Codex 等客户端。当前架构：
+
+```
+用户消息 → CLAUDE.md 规则触发 fact_store(search) → MCP tool call → FTS5 检索 → 注入 context
+```
+
+当前问题：
+- **每条消息**都触发一次 search MCP 调用，90%+ 的消息与记忆无关（如"git status""运行测试"）
+- 查询直接使用原始用户消息，"帮我重构 auth 模块"中的"帮我""重构"是噪音 token
+- FTS/Jaccard 权重固定 0.5/0.5，短查询和长查询用同一套评分
+- Category 多样性策略硬性限制每个 category 只取 top1，general 类事实被误伤
+
+事实库现状：70+ 条全局事实，5 个 category（identity/coding_style/tool_pref/workflow/general）。
+
+## Goals / Non-Goals
+
+**Goals:**
+- 检索准确率：减少噪音召回，提高 top-K 结果与查询的语义相关性
+- 注入效率：将 MCP 调用频率从"每条消息"降至"会话预热 + 按需补充"
+- 向后兼容：所有变更对现有 tool 调用接口透明
+
+**Non-Goals:**
+- 不引入向量数据库或 embedding 模型（保持零依赖、纯本地运行）
+- 不做项目记忆（scope 明确只做全局记忆）
+- 不改 MCP 协议本身，只利用现有 Resource + Tool 机制
+
+## Decisions
+
+### D1: MCP Resource 暴露全局记忆
+
+**选择**：为每个 category 注册 MCP Resource URI（`mnemo://global/{category}`），返回该 category 下 trust 排名 top-N 的事实摘要。
+
+**替代方案**：
+- A) SessionStart hook 触发 bulk search → 需要客户端支持，且仍有 MCP 调用开销
+- B) 静态文件注入 → 无法动态更新
+
+**理由**：MCP Resource 是协议原生的"客户端主动拉取"机制。Claude Code 在 session 启动时自动拉取所有 MCP Resource 并注入 system context。这实现了**零 MCP tool call 的预热注入**——LLM 直接在 system prompt 中看到记忆，不需要主动调 search。
+
+Resource URI 设计：
+```
+mnemo://global/identity      → identity 类 top-10
+mnemo://global/coding_style  → coding_style 类 top-10
+mnemo://global/tool_pref     → tool_pref 类 top-10
+mnemo://global/workflow      → workflow 类 top-10
+mnemo://global/general       → general 类 top-10
+```
+
+每个 Resource 返回 JSON 格式，客户端（Claude Code）会自动序列化为文本注入。
+
+### D2: 查询提炼层
+
+**选择**：在 `search()` 入口前加 `refineQuery()` 纯函数，做 token 级过滤。
+
+**提炼策略**：
+1. 移除中文虚词（已有 `CN_STOP_WORDS`，复用）
+2. 移除动作词（"帮我""看看""做一下""帮我看看"等）
+3. 提取实体词（引号内容、大写开头词、书名号内容）
+4. 如果提炼后为空（纯操作指令如"运行测试"），返回空查询 → 跳过检索
+
+**不选 LLM-based 查询重写**：引入模型调用成本，违反零依赖原则。
+
+### D3: 动态评分权重
+
+**选择**：根据查询 token 数动态调整 FTS/Jaccard 权重。
+
+```typescript
+// 短查询（≤3 token）→ 更依赖 FTS 精确匹配
+// 长查询（>3 token）→ 更依赖 Jaccard 语义覆盖
+const ftsWeight = tokenCount <= 3 ? 0.7 : 0.3
+const jaccardWeight = tokenCount <= 3 ? 0.3 : 0.7
+```
+
+**不选机器学习权重**：过重，事实库规模不够训练。
+
+### D4: 多样性策略修复
+
+**选择**：去掉硬性 category-per-top1 限制，改为 relevance score 去重——如果两条事实的 Jaccard 相似度 > 0.7（内容高度重叠），只保留评分高的那条。
+
+**理由**：全局记忆 5 个 category，general 占比通常 > 50%。硬性去重导致 general 只取 1 条，丢掉大量有效记忆。
+
+### D5: 相关性门控
+
+**选择**：在 trust 阈值（0.3）之上增加 relevance score 阈值（0.15）。score < 0.15 的结果不返回。
+
+**理由**：trust 是事实质量的静态指标，relevance 是与当前查询的匹配度。两者必须同时满足。
+
+### D6: 注入协议
+
+**选择**：将 CLAUDE.md 规则 1 从"每条消息都搜"改为：
+
+```
+会话启动 → MCP Resource 自动预热（系统层，LLM 不参与）
+用户消息 → LLM 判断是否需要补充查询记忆
+  ├─ 涉及个人偏好/习惯/工具选择 → search
+  ├─ 纯操作/技术问题 → 不查
+  └─ 模糊 → 可查可不查（偏向不查）
+```
+
+**风险**：LLM 可能判断失误，遗漏该查的场景。但 Resource 预热已经覆盖了高频记忆，遗漏的主要是边缘场景。
+
+## Risks / Trade-offs
+
+| Risk | Mitigation |
+|------|-----------|
+| Resource 预热数据量过大占用 context window | 每个 category 限 top-10，总共 ≤50 条，约 2000 token |
+| LLM 判断"不需要查"导致遗漏 | Resource 预热覆盖 80%+ 高频场景；边缘 case 通过 fact_feedback 自然淘汰 |
+| 查询提炼过度过滤导致召回不足 | 保留原始查询作为 fallback（提炼为空时用原始查询） |
+| 动态权重在中等长度查询时表现不稳定 | token 阈值 3 是经验值，可通过 fact_feedback 数据调优 |
+| Content-based 去重（Jaccard > 0.7）可能误判 | 去重只影响 top-K 选择，不影响存储；误判只是多返回一条 |
+
+## Open Questions
+
+- Resource 返回格式：JSON 数组 vs Markdown 文本？Claude Code 如何渲染 MCP Resource 内容？
+- 是否需要 `mnemo://global/all` 聚合 Resource，还是 5 个独立 Resource 分别拉取？
+- CLAUDE.md 规则变更需要用户手动更新，是否提供自动迁移脚本？

package/openspec/changes/retrieval-and-injection-optimization/proposal.md

@@ -0,0 +1,30 @@
+## Why
+
+mnemo-mcp 作为纯全局记忆系统（不含项目记忆），当前检索和注入机制存在两个核心问题：**检索准确率不足**（查询直接用原始用户消息、评分权重静态固定、category 多样性策略误伤高密度类），以及**注入成本过高**（CLAUDE.md 规则要求每条用户消息都触发一次 `fact_store(search)` MCP 调用，即使消息与记忆完全无关）。随着事实库增长到 70+ 条，这两个问题将导致噪音召回增加和 token 浪费加剧。
+
+## What Changes
+
+- 新增 **MCP Resource** 端点，暴露 5 个全局 category 的 top-N 高信任记忆，实现会话启动时零成本预热注入
+- 新增**查询提炼层**（query refinement），从用户消息中提取记忆相关关键词，过滤动作词和无关 token
+- **评分公式动态化**：根据查询长度和类型自适应调整 FTS/Jaccard 权重比例
+- **注入时机重构**：从"每条消息都搜"改为"MCP Resource 预热 + 按需补充"，需配合 CLAUDE.md 规则变更
+- 修复 **category 多样性策略**：对高密度 category（如 general）允许多条入选，改为基于相关性去重而非硬性 category 去重
+- 新增**相关性门控**：检索结果在 trust 阈值之上增加 relevance score 阈值过滤
+
+## Capabilities
+
+### New Capabilities
+- `mcp-resources`: 通过 MCP Resource 协议暴露全局记忆，支持会话预热零调用注入
+- `query-refinement`: 用户消息 → 记忆关键词提炼，过滤动作词/虚词/无关 token
+- `adaptive-scoring`: 查询长度自适应的 FTS/Jaccard 权重分配 + relevance 门控
+- `injection-protocol`: 优化后的注入协议定义（何时查、何时注入、何时跳过），需同步更新 CLAUDE.md 规则
+
+### Modified Capabilities
+<!-- 无既有 spec 需要修改 -->
+
+## Impact
+
+- `src/server.ts`：新增 Resource handler，修改 search 入口加查询提炼
+- `src/retriever.ts`：评分公式动态化、多样性策略修复、relevance 门控
+- `CLAUDE.md`（用户侧配置）：规则 1 从"每条消息都搜"改为"会话预热 + 按需触发"
+- 向后兼容：所有变更对现有 fact_store/fact_feedback tool 调用透明，不影响已有客户端

package/openspec/changes/retrieval-and-injection-optimization/specs/adaptive-scoring/spec.md

@@ -0,0 +1,43 @@
+## ADDED Requirements
+
+### Requirement: 查询长度自适应权重
+系统 SHALL 根据查询 token 数动态调整 FTS 和 Jaccard 的权重比例。
+
+- 短查询（token 数 ≤ 3）：FTS 权重 0.7，Jaccard 权重 0.3（偏精确匹配）
+- 长查询（token 数 > 3）：FTS 权重 0.3，Jaccard 权重 0.7（偏语义覆盖）
+
+#### Scenario: 短查询使用高 FTS 权重
+- **WHEN** 查询为 "深色主题"（2 个 token）
+- **THEN** 评分公式中 FTS 权重为 0.7，Jaccard 权重为 0.3
+
+#### Scenario: 长查询使用高 Jaccard 权重
+- **WHEN** 查询为 "为什么 TypeScript 编译报错找不到模块"（7 个 token）
+- **THEN** 评分公式中 FTS 权重为 0.3，Jaccard 权重为 0.7
+
+### Requirement: 相关性评分门控
+系统 SHALL 在 trust 阈值之上增加 relevance score 阈值。综合评分（relevance × trustScore × temporalDecay）低于 0.15 的结果 SHALL 被过滤。
+
+#### Scenario: 低相关性结果被过滤
+- **WHEN** 一条事实 trust_score=0.9 但与查询的 relevance score=0.1
+- **THEN** 综合评分 = 0.1 × 0.9 = 0.09 < 0.15，该结果不返回
+
+#### Scenario: 高相关性结果通过
+- **WHEN** 一条事实 trust_score=0.4 且与查询的 relevance score=0.8
+- **THEN** 综合评分 = 0.8 × 0.4 = 0.32 > 0.15，该结果正常返回
+
+### Requirement: 内容相似度去重
+系统 SHALL 对检索结果中内容高度重叠的事实进行去重——两条事实的 Jaccard 相似度 > 0.7 时，只保留评分高的那条。
+
+替换现有的 category-per-top1 硬性去重策略。
+
+#### Scenario: 相似事实去重
+- **WHEN** 检索结果中有两条事实内容 Jaccard 相似度 > 0.7
+- **THEN** 只保留评分高的那条，另一条被移除
+
+#### Scenario: 不同 category 的不同事实不被误去重
+- **WHEN** 一条 identity 事实和一条 coding_style 事实内容不相似（Jaccard < 0.7）
+- **THEN** 两者都保留在结果中
+
+#### Scenario: general 类允许返回多条
+- **WHEN** general category 有 5 条高相关性事实且内容不重复
+- **THEN** 5 条都保留在结果中（不再受 category-per-top1 限制）

package/openspec/changes/retrieval-and-injection-optimization/specs/injection-protocol/spec.md

@@ -0,0 +1,48 @@
+## ADDED Requirements
+
+### Requirement: 会话预热注入协议
+系统 SHALL 通过 MCP Resource 机制实现会话启动时的自动预热注入，无需 LLM 主动调用 tool。
+
+- 客户端在 session 启动时自动拉取所有 `mnemo://global/*` Resource
+- Resource 内容作为 system context 注入，LLM 可直接访问
+- 预热注入覆盖 identity/coding_style/tool_pref/workflow/general 全部 5 个分类
+
+#### Scenario: 新会话自动获得全局记忆
+- **WHEN** Claude Code 启动新 session
+- **THEN** 系统自动拉取 5 个 category Resource，记忆内容出现在 system context 中
+
+#### Scenario: 预热后 LLM 不需要主动 search 即可回答偏好问题
+- **WHEN** 用户问 "我喜欢什么编辑器" 且预热 Resource 中包含 "用户偏好 VS Code 编辑器"
+- **THEN** LLM 直接从预热 context 回答，无需调用 fact_store(search)
+
+### Requirement: 按需补充查询触发规则
+系统 SHALL 定义何时触发补充 fact_store(search) 调用的规则，替代当前"每条消息都搜"的模式。
+
+触发条件（满足任一即触发）：
+- 用户消息包含明确的记忆查询意图（"我记得说过""我之前说过""按我的习惯"）
+- 用户消息涉及技术选型/工具选择且预热中未覆盖
+- 用户显式要求记住新信息（触发 add 而非 search）
+
+不触发条件：
+- 纯操作指令（"创建文件""运行测试""git commit"）
+- 通用技术问题（"怎么用 Promise""React hooks 语法"）
+- 代码审查/解释请求
+
+#### Scenario: 技术选型触发补充查询
+- **WHEN** 用户说 "用 React 还是 Vue 开发这个项目" 且预热中无相关偏好
+- **THEN** 触发 fact_store(search, query="React Vue 前端框架 偏好")
+
+#### Scenario: 纯操作指令不触发
+- **WHEN** 用户说 "运行测试"
+- **THEN** 不触发 fact_store(search)，节省 MCP 调用
+
+#### Scenario: 明确记忆查询触发
+- **WHEN** 用户说 "我之前说不喜欢什么颜色来着"
+- **THEN** 触发 fact_store(search, query="不喜欢 颜色")
+
+### Requirement: 注入协议配置说明
+系统 SHALL 在 README 或文档中提供更新后的 CLAUDE.md 规则模板，用户可直接复制使用。
+
+#### Scenario: 用户更新 CLAUDE.md 规则
+- **WHEN** 用户按文档更新 CLAUDE.md 中的记忆系统使用规则
+- **THEN** 规则 1 从"每条消息都搜"变为"会话预热 + 按需触发"

package/openspec/changes/retrieval-and-injection-optimization/specs/mcp-resources/spec.md

@@ -0,0 +1,39 @@
+## ADDED Requirements
+
+### Requirement: MCP Resource 暴露全局分类记忆
+系统 SHALL 为每个全局 category 注册 MCP Resource URI，返回该 category 下按 trust 排序的 top-N 事实摘要。
+
+- URI 格式：`mnemo://global/{category}`，其中 category 为 identity / coding_style / tool_pref / workflow / general
+- 每个 Resource 返回该 category 下 trust_score 最高的前 10 条事实
+- 返回格式为 JSON 数组，每条包含 fact_id、content、trust_score
+- Resource 内容在服务启动时计算并缓存，写操作（add/update/remove）时失效重算
+
+#### Scenario: 客户端拉取 identity Resource
+- **WHEN** MCP 客户端请求 `mnemo://global/identity`
+- **THEN** 返回 identity category 下 trust_score DESC 排序的前 10 条事实 JSON 数组
+
+#### Scenario: 写操作后 Resource 刷新
+- **WHEN** 通过 fact_store 执行 add/update/remove 操作
+- **THEN** 所有 Resource 缓存失效，下次拉取时重新从 DB 计算
+
+#### Scenario: 空 category 返回空数组
+- **WHEN** 某个 category 下没有任何事实
+- **THEN** 对应 Resource 返回空 JSON 数组 `[]`
+
+### Requirement: MCP Resource 列表发现
+系统 SHALL 在 MCP `resources/list` 响应中暴露所有 5 个全局 category Resource，包含 name 和 description。
+
+#### Scenario: 客户端发现可用 Resource
+- **WHEN** MCP 客户端调用 `resources/list`
+- **THEN** 响应包含 5 个 Resource 条目，每个的 URI 为 `mnemo://global/{category}`，name 为分类名，description 说明内容
+
+### Requirement: Resource 缓存生命周期
+系统 SHALL 维护 Resource 缓存，避免每次拉取都查询数据库。
+
+- 缓存类型：进程内 Map，key 为 category
+- 缓存失效：任何写操作（add/update/remove）触发全部缓存清空
+- 首次访问时惰性计算
+
+#### Scenario: 连续拉取命中缓存
+- **WHEN** 短时间内连续两次拉取同一 category Resource，中间无写操作
+- **THEN** 第二次直接返回缓存结果，不触发 DB 查询

package/openspec/changes/retrieval-and-injection-optimization/specs/query-refinement/spec.md

@@ -0,0 +1,39 @@
+## ADDED Requirements
+
+### Requirement: 查询提炼函数
+系统 SHALL 提供 `refineQuery(rawQuery: string): string | null` 纯函数，从用户原始消息中提取记忆相关关键词。
+
+提炼流程：
+1. 分词（按空格 + 中文字符边界）
+2. 过滤中文虚词（复用 CN_STOP_WORDS）
+3. 过滤动作词（"帮我""看看""做一下""帮我看看""能不能""为什么""怎么""是什么"）
+4. 提取高信号 token（引号内容、大写开头连续词、书名号内容）
+5. 剩余 token 作为提炼结果
+6. 如果提炼后为空（纯操作指令），返回 null
+
+#### Scenario: 包含实体的查询成功提炼
+- **WHEN** 输入 "帮我用 TypeScript 重构 auth 模块"
+- **THEN** 提炼结果包含 "TypeScript" "auth" 等关键词（过滤掉"帮我""重构""模块"）
+
+#### Scenario: 纯操作指令返回 null
+- **WHEN** 输入 "运行测试" 或 "git status"
+- **THEN** 返回 null，表示不需要检索记忆
+
+#### Scenario: 引号内容优先保留
+- **WHEN** 输入 "我喜欢「深色主题」"
+- **THEN** 提炼结果包含 "深色主题"
+
+#### Scenario: 提炼结果集成到 search
+- **WHEN** search() 接收到原始查询
+- **THEN** 先调用 refineQuery()；若返回 null 则直接返回空结果；若返回非空则用提炼结果作为 FTS5 查询词
+
+### Requirement: 提炼为空时的 fallback
+系统 SHALL 在 refineQuery 返回 null 时保留原始查询作为 fallback，由调用方决定是否跳过检索。
+
+#### Scenario: 调用方选择跳过
+- **WHEN** refineQuery 返回 null 且调用方为自动触发（CLAUDE.md 规则 1）
+- **THEN** 跳过检索，返回空结果
+
+#### Scenario: 调用方显式搜索
+- **WHEN** 用户显式调用 `fact_store(action="search", query="运行测试")`
+- **THEN** 即使 refineQuery 返回 null，仍用原始查询执行检索

package/openspec/changes/retrieval-and-injection-optimization/tasks.md

@@ -0,0 +1,33 @@
+## 1. MCP Resource 注册与缓存
+
+- [ ] 1.1 在 `src/server.ts` 中注册 5 个 MCP Resource URI（`mnemo://global/{identity,coding_style,tool_pref,workflow,general}`），每个 Resource 返回对应 category 的 top-10 事实 JSON 数组
+- [ ] 1.2 实现 Resource 缓存层：进程内 Map，写操作时清空，首次访问惰性计算
+- [ ] 1.3 在 `resources/list` 响应中暴露所有 5 个 Resource 条目（含 name + description）
+- [ ] 1.4 验证：启动 server 后用 MCP Inspector 拉取 Resource 确认返回格式正确
+
+## 2. 查询提炼层
+
+- [ ] 2.1 在 `src/retriever.ts` 中实现 `refineQuery(rawQuery: string): string | null` 纯函数，过滤虚词 + 动作词 + 提取高信号 token
+- [ ] 2.2 修改 `search()` 入口：先调 refineQuery()，返回 null 时直接返回空结果；返回非空时用提炼结果作为查询词
+- [ ] 2.3 保留原始查询 fallback：当用户显式调用 search action（非自动触发）时，即使 refineQuery 返回 null 也用原始查询
+- [ ] 2.4 验证：测试 "帮我用 TypeScript 重构 auth 模块" → 提炼出 "TypeScript auth"；"运行测试" → 返回 null
+
+## 3. 动态评分权重
+
+- [ ] 3.1 修改 `search()` 中的评分公式：根据 query token 数动态设置 ftsWeight/jaccardWeight（≤3 token → 0.7/0.3，>3 → 0.3/0.7）
+- [ ] 3.2 新增 relevance score 阈值门控：综合评分 < 0.15 的结果不返回
+- [ ] 3.3 替换 category-per-top1 硬性去重为 Jaccard 相似度去重（> 0.7 的只保留高分）
+- [ ] 3.4 验证：general 类多条不同事实可以同时出现在结果中
+
+## 4. 注入协议文档
+
+- [ ] 4.1 编写更新后的 CLAUDE.md 记忆系统使用规则模板（会话预热 + 按需触发 + 写入/反馈规则）
+- [ ] 4.2 更新 README.md 添加注入协议说明和 CLAUDE.md 规则配置示例
+- [ ] 4.3 验证：按新规则配置 CLAUDE.md 后启动 session，确认 Resource 自动拉取且无需每条消息都调 search
+
+## 5. 集成测试
+
+- [ ] 5.1 编写 `tests/resource.test.ts`：验证 Resource 返回格式、缓存命中、写操作后缓存失效
+- [ ] 5.2 编写 `tests/refine.test.ts`：验证查询提炼的虚词过滤、动作词剥离、null 返回场景
+- [ ] 5.3 更新 `tests/retriever.test.ts`：验证动态权重、relevance 门控、Jaccard 去重
+- [ ] 5.4 运行全量测试 `npm run test` 确认无回归

package/openspec/config.yaml

@@ -0,0 +1,20 @@
+schema: spec-driven
+
+# Project context (optional)
+# This is shown to AI when creating artifacts.
+# Add your tech stack, conventions, style guides, domain knowledge, etc.
+# Example:
+#   context: |
+#     Tech stack: TypeScript, React, Node.js
+#     We use conventional commits
+#     Domain: e-commerce platform
+
+# Per-artifact rules (optional)
+# Add custom rules for specific artifacts.
+# Example:
+#   rules:
+#     proposal:
+#       - Keep proposals under 500 words
+#       - Always include a "Non-goals" section
+#     tasks:
+#       - Break tasks into chunks of max 2 hours

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@morningljn/mnemo",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Structured fact memory MCP server — SQLite + FTS5, trust scoring, entity graph, bilingual retrieval for Claude Code & Codex",
   "type": "module",
   "main": "dist/server.js",

package/src/init.ts

@@ -23,19 +23,27 @@ const MEMORY_RULES = `
 
 你有 mnemo 记忆工具（fact_store / fact_feedback），必须按以下规则使用：
 
-## 规则 1：搜索记忆（每次回复前）
-收到用户消息后，你必须先调用 \`fact_store(action="search", query="<用户消息的关键词>")\` 检索相关记忆。
-query 必须从用户消息中提取关键词，不要用固定模板。例如：
-- 用户说"我叫什么" → query="姓名 名字 叫什么"
-- 用户说"我喜欢什么语言" → query="编程语言 偏好 喜欢"
-搜索后根据结果自然回复，不要说"根据记忆"。
-
-## 规则 2：写入记忆
+## 规则 1：会话预热（自动）
+会话启动时，mnemo-mcp 的 MCP Resource 会自动注入全局记忆到 system context。
+你不需要主动调用 fact_store(search) 来获取高频记忆。
+
+## 规则 2：按需补充查询
+仅在以下情况调用 \`fact_store(action="search")\`：
+- 用户消息涉及个人偏好/习惯/工具选择且预热中未覆盖
+- 用户明确查询记忆（"我之前说过什么""按我的习惯"）
+- 技术选型时需要确认用户偏好
+
+不触发查询的情况：
+- 纯操作指令（"运行测试""git commit"）
+- 通用技术问题（"Promise 怎么用"）
+- 代码审查/解释请求
+
+## 规则 3：写入记忆
 用户说"记住"、"记下来"时，调用 \`fact_store(action="add", content="...", category="...")\`。
 - 先 search 检查是否已有相似事实，有则 update
 - category：identity / coding_style / tool_pref / workflow / general
 
-## 规则 3：反馈强化
+## 规则 4：反馈强化
 成功使用某条记忆时，调用 \`fact_feedback(action="helpful", fact_id=...)\`。
 `