recallnest 1.4.1 → 2.2.0

package/plan-philosophy-upgrades.md

@@ -0,0 +1,363 @@
+# Implementation Plan: Memory Philosophy-Driven RecallNest Upgrades
+
+> Date: 2026-04-11
+> Status: ✅ ALL 5 PHASES COMPLETE (commits a9e53d3..d150b8d, 1391 tests / 0 fail)
+> Source: Memory philosophy research map + Codex code analysis + Explorer codebase audit
+
+---
+
+## Overview
+
+Five upgrade phases derived from memory philosophy research, each mapped to concrete code changes in the RecallNest codebase. Phase 1 (Emotional Valence in Decay) is implementation-ready today -- the building blocks exist but are not wired into production paths. Phases 2-5 build outward from that foundation. All phases are designed to be independently mergeable and testable.
+
+## Dependency Graph
+
+```
+Phase 1 (Emotion Decay)  <- standalone, no dependencies
+Phase 2 (Ethics Layer)   <- standalone, no dependencies on Phase 1
+Phase 3 (Narrative)      <- standalone, enriches Phase 4 if done first
+Phase 4 (Constructive)   <- benefits from Phase 3 (narrative siblings), Phase 1 (emotion salience)
+Phase 5 (Predictive)     <- benefits from Phase 4 (reconstruction surface)
+```
+
+Phases 1, 2, and 3 can run in parallel. Phase 4 benefits from all three. Phase 5 builds on Phase 4.
+
+## Time Estimates
+
+| Phase | Estimated Effort | Complexity |
+|-------|-----------------|------------|
+| Phase 1 | 3-4 hours | Low -- wiring existing code |
+| Phase 2 | 2-3 days | Medium -- new forget engine + lifecycle unification |
+| Phase 3 | 2-3 days | Medium -- new metadata layer + write/read points |
+| Phase 4 | 3-4 days | High -- LLM pipeline changes + grounding rewrite |
+| Phase 5 | 2-3 days | Medium -- new prediction engine + surface layer |
+| **Total** | **~12-15 days** | |
+
+---
+
+## Phase 1: Emotional Valence in Decay (TODAY)
+
+### Goal
+Wire the existing emotion-adjusted decay functions (`adjustHalfLifeForEmotion`, `computeArousalBoost`) into the production retrieval and evolution scoring paths. Extend `EmotionMetadata` with `salience` and `source` fields. Recalculate emotion on text updates. Backfill emotion on import.
+
+### Current State
+- `emotion-detector.ts` -- keyword heuristic, zero LLM cost, fully tested
+- `decay-engine.ts:99-119` -- `adjustHalfLifeForEmotion()` and `computeArousalBoost()` exist with tests but are NOT called from production code
+- `store.ts:370` -- `detectEmotionIfEnabled()` auto-annotates on `store()`
+- `retriever.ts:261` -- `applyEmotionWeight()` retrieval scoring is live
+- `retriever.ts:1657` -- `applyTimeDecay()` does NOT use emotion-adjusted half-life
+- `memory-evolution.ts:306` -- `computeDecayScore()` has no emotion factor
+- Feature flag: `RECALLNEST_EMOTION_SCORING=true`
+
+### Files Changed
+
+| File | Function(s) | Change |
+|------|------------|--------|
+| `src/memory-schema.ts` | `EmotionMetadata`, `EmotionMetadataSchema` | Add `salience` and `source` fields |
+| `src/retriever.ts` | `applyTimeDecay()` (line 1657) | Wire `adjustHalfLifeForEmotion()` into half-life computation |
+| `src/memory-evolution.ts` | `computeDecayScore()` (line 306), weight constants | Add emotion salience factor, rebalance weights |
+| `src/store.ts` | `update()` (line 863) | Recalculate emotion when text changes |
+| `src/store.ts` | `importEntry()` (line 433) | Backfill emotion if absent |
+| `src/emotion-detector.ts` | `detectEmotion()` | Compute `salience` from |valence| + arousal |
+| Tests | New + updated | Emotion-decay integration, update re-detection, import backfill |
+
+### Steps
+
+#### 1.1 Extend EmotionMetadata schema
+**File:** `src/memory-schema.ts` (lines 40-53)
+
+- [x] Add `salience?: number` field to `EmotionMetadata` interface (0-1 composite of |valence| + arousal)
+- [x] Add `source?: "keyword" | "llm" | "user"` field to `EmotionMetadata` interface
+- [x] Update `EmotionMetadataSchema` Zod object to include `salience: z.number().min(0).max(1).optional()` and `source: z.enum(["keyword", "llm", "user"]).optional()`
+- [x] Verify `parseEmotion()` still works with old data (no salience/source)
+- **Why:** Salience is the single composite signal that decay and evolution scoring will consume. Source enables future LLM-based emotion detection without breaking keyword entries.
+- **Risk:** Low -- additive optional fields, backward compatible
+
+#### 1.2 Compute salience in detectEmotion
+**File:** `src/emotion-detector.ts`, function `detectEmotion()` (line 62)
+
+- [x] After computing `valence` and `arousal`, compute `salience = clamp((Math.abs(valence) + arousal) / 2, 0, 1)`
+- [x] Add `salience` and `source: "keyword"` to the returned `EmotionMetadata` object
+- [x] Update `detectEmotionIfEnabled()` -- no change needed (passes through)
+- **Why:** Decay engine needs a single 0-1 signal, not separate valence/arousal. Formula: average of emotional intensity and arousal, giving equal weight to "how emotional" and "how urgent."
+- **Risk:** Low -- pure addition to return value
+
+#### 1.3 Wire emotion into applyTimeDecay
+**File:** `src/retriever.ts`, method `applyTimeDecay()` (line 1657)
+
+- [x] Import `adjustHalfLifeForEmotion` from `decay-engine.ts` and `parseEmotion` from `memory-schema.ts`
+- [x] At line 1670-1672 (after `this.accessTracker.computeEffectiveHalfLife()`), add emotion adjustment: if `isEmotionScoringEnabled()`, parse emotion from `r.entry.metadata`, call `adjustHalfLifeForEmotion(halfLife, emotion)` to get final half-life
+- [x] Guard behind `isEmotionScoringEnabled()` flag check
+- [x] The arousal boost (`computeArousalBoost()`) applies to score before decay
+
+**Current code pattern:**
+```typescript
+const halfLife = this.accessTracker
+  ? this.accessTracker.computeEffectiveHalfLife(baseHalfLife, r.entry.metadata)
+  : baseHalfLife;
+const tier = resolveTier(r.entry.metadata);
+const factor = weibullDecay(ageDays, halfLife, tier);
+return { ...r, score: clamp01(r.score * factor, r.score * 0.3) };
+```
+
+**Target code:**
+```typescript
+let halfLife = this.accessTracker
+  ? this.accessTracker.computeEffectiveHalfLife(baseHalfLife, r.entry.metadata)
+  : baseHalfLife;
+// HP-emo: Emotion-adjusted half-life — strong emotion slows forgetting
+const emotion = isEmotionScoringEnabled() ? parseEmotion(r.entry.metadata) : null;
+if (emotion) {
+  halfLife = adjustHalfLifeForEmotion(halfLife, emotion);
+}
+const tier = resolveTier(r.entry.metadata);
+const factor = weibullDecay(ageDays, halfLife, tier);
+const arousalFactor = emotion ? computeArousalBoost(emotion) : 1.0;
+return { ...r, score: clamp01(r.score * arousalFactor * factor, r.score * 0.3) };
+```
+
+- **Why:** This is the primary gap -- emotion detection runs on write, emotion weight runs on retrieval scoring, but the decay curve itself ignores emotion. A frustrating debugging session should decay slower than a neutral log entry.
+- **Risk:** Medium -- touches the core scoring pipeline. Parse emotion once per result to avoid double-parse overhead.
+
+#### 1.4 Add emotion factor to computeDecayScore
+**File:** `src/memory-evolution.ts`, function `computeDecayScore()` (line 306), constants at lines 292-295
+
+- [x] Import `parseEmotion`, `isEmotionScoringEnabled` from `memory-schema.ts`
+- [x] Add optional `metadata?: string` parameter to `computeDecayScore()` (backward compatible)
+- [x] When `isEmotionScoringEnabled()` and metadata is provided, extract salience
+- [x] Rebalance weights from `0.2/0.3/0.5` to `0.15/0.25/0.45/0.15`:
+  ```typescript
+  const EMOTION_WEIGHT = isEmotionScoringEnabled() ? 0.15 : 0;
+  const TIME_W = isEmotionScoringEnabled() ? 0.15 : 0.2;
+  const FREQ_W = isEmotionScoringEnabled() ? 0.25 : 0.3;
+  const IMP_W = isEmotionScoringEnabled() ? 0.45 : 0.5;
+  // Final: TIME_W * timeDecay + FREQ_W * frequencyScore + IMP_W * importance + EMOTION_WEIGHT * salience
+  ```
+- [x] Update all callers to pass metadata where available:
+  - `auto-gc.ts:142` -- pass `entry.metadata`
+  - `retriever.ts:1712` (applyEvolutionDecayBlend) -- pass `r.entry.metadata`
+- **Why:** The evolution decay score determines GC archival and evolution blend. Without emotion, high-emotion events get same decay as routine logs.
+- **Risk:** Medium -- changes GC archival threshold behavior. Emotional memories will resist archival slightly more (desirable).
+
+#### 1.5 Re-detect emotion on text update
+**File:** `src/store.ts`, method `update()` (line 863)
+
+- [x] After building the `updated` entry, if `updates.text` is provided (text changed), re-run emotion detection:
+  ```typescript
+  if (updates.text) {
+    const emotionResult = detectEmotionIfEnabled(updated.text);
+    if (emotionResult) {
+      const meta = JSON.parse(updated.metadata || "{}");
+      meta.emotion = emotionResult;
+      updated.metadata = JSON.stringify(meta);
+    }
+  }
+  ```
+- [x] Place this BEFORE the `table!.delete` + `table!.add` at lines 918-920
+- **Why:** When text is updated (e.g., supersede-with-edit), stale emotion metadata creates scoring inaccuracy.
+- **Risk:** Low -- only fires when text is explicitly changed
+
+#### 1.6 Backfill emotion on importEntry
+**File:** `src/store.ts`, method `importEntry()` (line 433)
+
+- [x] After building `full` entry, check if emotion is already present in metadata. If not, detect and inject:
+  ```typescript
+  const metaParsed = JSON.parse(full.metadata || "{}");
+  if (!metaParsed.emotion) {
+    const emotionResult = detectEmotionIfEnabled(full.text);
+    if (emotionResult) {
+      metaParsed.emotion = emotionResult;
+      full.metadata = JSON.stringify(metaParsed);
+    }
+  }
+  ```
+- **Why:** Imported entries may pre-date emotion detection. Backfilling ensures all entries have emotion metadata.
+- **Risk:** Low -- only adds when absent, never overwrites
+
+#### 1.7 Tests
+- [x] **emotion-decay.test.ts**: Add test that `salience` is present in `detectEmotion()` output and matches expected formula
+- [x] **emotion-decay.test.ts**: Add test that `source` field is `"keyword"` in `detectEmotion()` output
+- [x] **New: emotion-evolution-decay.test.ts**: Test `computeDecayScore` with emotion metadata yields higher score than without
+- [x] **New: emotion-evolution-decay.test.ts**: Test backward compat -- no metadata param still works
+- [x] **New: emotion-evolution-decay.test.ts**: Test weight rebalancing (weights sum to 1.0)
+- [x] **Extend retriever tests**: Two entries, same age/importance/frequency, different emotion -- emotional one scores higher after `applyTimeDecay`
+- [x] **Store tests**: Verify `update()` with text change re-detects emotion
+- [x] **Store tests**: Verify `importEntry()` backfills emotion when absent, preserves when present
+- [x] Run `bun test` -- all 1000+ tests must pass
+
+### Verification
+1. `bun test` -- full green, baseline maintained
+2. Manual check: store emotional memory, retrieve at simulated t=30d, confirm higher score vs neutral
+3. Check `computeDecayScore` output for emotional vs neutral with same evo params
+
+### Risks for Phase 1
+- **Double-parse overhead in applyTimeDecay**: Parse emotion once per result, pass to both functions
+- **Weight rebalancing changes GC behavior**: Test with existing GC tests
+- **Feature flag dependency**: All changes gated by `RECALLNEST_EMOTION_SCORING=true`. Flag off = identical to current
+
+---
+
+## Phase 2: Memory Ethics Layer
+
+### Goal
+Add privacy tiers, build a proper forget engine with cascade deletion, unify lifecycle state inconsistency, expose `forget_memory` MCP tool with audit logging.
+
+### Current State
+- `cascade-forget.ts:91` reads legacy `meta.state` -- inconsistent with `evolution.status`
+- `consolidation-engine.ts:71-77` reads BOTH `isActiveMemory()` and `meta.state`
+- `audit-log.ts` exists but lacks "forget" operation type
+- `KGStore.deleteBySource()` exists at `kg-store.ts:314` but never called from forget path
+- No privacy tier field exists
+
+### Files Changed
+
+| File | Function(s) | Change |
+|------|------------|--------|
+| `src/memory-schema.ts` | New types | `PrivacyTier` type + Zod schema |
+| `src/forget-engine.ts` | **New file** | Full cascade forget with KG cleanup, audit, privacy checks |
+| `src/audit-log.ts` | `AuditOperation` type | Add `"forget"` and `"cascade_forget"` operations |
+| `src/cascade-forget.ts` | `cascadeForget()` | Migrate `meta.state` to `evolution.status` |
+| `src/consolidation-engine.ts` | `isActive()` | Remove legacy `meta.state` double-check |
+| `src/capture-engine.ts` | KG extraction gate | Privacy tier check before KG extraction |
+| `src/mcp-server.ts` | New tool | `forget_memory` MCP tool |
+| `src/store.ts` | `store()`, `StoreMemoryInput` | Accept optional `privacyTier` |
+| Tests | New | forget-engine, privacy-tier, lifecycle-state tests |
+
+### Steps
+
+#### 2.1 Add PrivacyTier to schema
+- [x] `PrivacyTier` type: `"ephemeral" | "private" | "durable" | "shared"`
+- [x] `PrivacyTierSchema` Zod enum
+- [x] Optional `privacyTier` in `StoreMemoryInputSchema`
+
+#### 2.2 Unify lifecycle state
+- [x] `cascade-forget.ts:91` -- replace `meta.state` with `isActiveMemory()`
+- [x] `consolidation-engine.ts:70-77` -- simplify to only `isActiveMemory()`
+- [x] Grep for any other `meta.state` reads, migrate them all
+
+#### 2.3 Extend audit operations
+- [x] Add `"forget"` and `"cascade_forget"` to `AuditOperation` union
+
+#### 2.4 Build forget engine (NEW: `src/forget-engine.ts`)
+- [x] `forgetMemory()`: fetch → privacy check → evidence export → KG delete → pin archive → cascade → primary delete → audit
+- [x] `forgetByScope()` for bulk scope-level forget
+- [x] Confirmation gate for `"durable"` entries
+
+#### 2.5 Privacy tier gate in capture
+- [x] Before KG extraction, skip if `privacyTier === "ephemeral" | "private"`
+
+#### 2.6 Register `forget_memory` MCP tool
+- [x] Schema: `{ memoryId: string, confirm: boolean, reason?: string }`
+- [x] Returns deletion summary + evidence paths
+
+#### 2.7 Tests
+- [x] forget-engine: KG cleanup, cascade demotion, audit trail
+- [x] Privacy tier blocks without confirm
+- [x] Evidence export for high-importance memories
+- [x] Consolidation/cascade-forget regression with new `isActiveMemory()`
+- [x] `bun test` full green
+
+### Verification
+1. Store memory → extract KG → forget → verify KG triples gone
+2. Audit log shows complete forget trail
+3. `"ephemeral"` memory produces no KG triples
+
+---
+
+## Phase 3: Autobiographical Narrative Architecture
+
+### Goal
+Add orthogonal narrative metadata layer (life-period / general-event / specific-event) on top of existing 6 categories. Enable temporal grouping and narrative retrieval without disrupting category logic.
+
+### Current State
+- 6 categories hardcoded across `memory-schema.ts`, `memory-boundaries.ts`, `retriever.ts`, `context-composer.ts` -- **do not modify**
+- `event-segmenter.ts:105` has `segmentEvents()`, `temporal-parser.ts:15` has date parsing
+
+### Files Changed
+
+| File | Function(s) | Change |
+|------|------------|--------|
+| `src/narrative-schema.ts` | **New file** | Narrative metadata types + Zod schemas |
+| `src/narrative-tagger.ts` | **New file** | Rule-based narrative period/event assignment |
+| `src/capture-engine.ts` | `buildStructuredMetadata()` | Inject narrative metadata |
+| `src/ingest.ts` | `buildIngestedEntry()` | Inject narrative metadata |
+| `src/retriever.ts` | New method | `expandNarrativeSiblings()` |
+| `src/context-composer.ts` | Result rendering | Group by narrative period |
+| `src/memory-output.ts` | Rendering | Narrative period labels |
+| `src/graph-export.ts` | Graph edges | Narrative relationship edges |
+
+### Steps
+- [x] 3.1 Define `NarrativeMetadata` interface: `lifePeriodId/Label`, `generalEventId/Label`, `specificEventId/Label`, `startAt`, `endAt`, `sequence`
+- [x] 3.2 Build rule-based narrative tagger (scope prefix, temporal clustering, keyword signals)
+- [x] 3.3 Inject narrative at write points (`capture-engine.ts:140`, `ingest.ts:662`)
+- [x] 3.4 `expandNarrativeSiblings()` in retriever: pull entries sharing same `generalEventId`
+- [x] 3.5 Rendering updates: group by `lifePeriodLabel`, narrative edges in graph export
+- [x] 3.6 Tests + `bun test` full green
+
+---
+
+## Phase 4: Constructive Retrieval
+
+### Goal
+Replace "top-k then summarize" with multi-source candidate expansion + grounded reconstruction. Return reconstruction as first-class object.
+
+### Current State
+- `context-reconstructor.ts:91` exists, `retriever.ts:706` `runReconstruction()` exists
+- `mcp-server.ts:888` supports `reconstruct=true`
+- But: only top-k summarize, `metadata._reconstruction` is hacky, `computeCoverage()` is lexical
+
+### Steps
+- [x] 4.1 Define `ReconstructionOutput` with sources, confidence, contradictions
+- [x] 4.2 Add candidate expansion: KG neighbors + evolution chains + cluster members + narrative siblings
+- [x] 4.3 Replace lexical coverage with source-map grounding + contradiction detection
+- [x] 4.4 Return reconstruction as first-class object (remove `metadata._reconstruction` hack)
+- [x] 4.5 Update MCP rendering for new output shape
+- [x] 4.6 Pass checkpoint context (openLoops, nextActions) into reconstruction prompt
+- [x] 4.7 Tests + `bun test` full green
+
+---
+
+## Phase 5: Predictive Prospective Memory
+
+### Goal
+Evolve `prospective-memory.ts` from explicit reminders to include pattern-predicted suggestions. Surface behavioral insights as ephemeral predicted reminders.
+
+### Current State
+- `prospective-memory.ts` -- `setReminder()`, `checkTriggers()`, `fireReminder()` explicit only
+- Behavioral signals: checkpoint openLoops, workflow observations, frequency tracker, access tracker, topic tags
+
+### Steps
+- [x] 5.1 Extend `ProspectiveMetadata` with `source`, `confidence`, `evidence`, `lastSuggestedAt`, `acceptedAt`
+- [x] 5.2 Build `prediction-engine.ts`: collect signals, score predictions, threshold at confidence >= 0.6
+- [x] 5.3 `suggestPredictedReminders()`: deduplicate vs existing, store as ephemeral, auto-expire 7d
+- [x] 5.4 Surface in `search_memory` as separate "Suggested Reminders" section
+- [x] 5.5 Acceptance/promotion flow: repeated/accepted → promote to explicit; ignored → demote
+- [x] 5.6 Tests + `bun test` full green
+
+---
+
+## Global Risks & Mitigations
+
+| Risk | Impact | Mitigation |
+|------|--------|-----------|
+| Feature flag proliferation | Complexity | Phase 1-2 reuse `RECALLNEST_EMOTION_SCORING`. Phase 3-5 add `RECALLNEST_NARRATIVE_MODE` and `RECALLNEST_PREDICTIVE_MEMORY` |
+| Metadata JSON bloat | Storage + parse cost | Each phase adds ~100 bytes/entry. Total metadata stays under 2KB |
+| Scoring formula instability | Retrieval quality regression | Every weight change gated by feature flag and tested against eval cases |
+| LLM cost creep (Phase 4-5) | Token spend | Phase 1-3 zero LLM. Phase 4 reuses existing reconstruction budget. Phase 5 zero LLM (heuristic) |
+
+---
+
+## Success Criteria
+
+- [x] Phase 1: Emotional memories decay 20-30% slower than neutral memories of same age
+- [x] Phase 1: `computeDecayScore` with emotion gives higher scores for high-salience memories
+- [x] Phase 1: All existing tests pass, emotion-decay tests extended
+- [x] Phase 2: `forget_memory` MCP tool deletes entry + KG triples + cascade demotes + audit logs
+- [x] Phase 2: No more `meta.state` reads anywhere in codebase (all `evolution.status`)
+- [x] Phase 3: Ingested sessions have narrative metadata with period/event IDs
+- [x] Phase 3: Search returns narrative siblings alongside direct matches
+- [x] Phase 4: Reconstruction uses expanded candidate set (KG + evolution + cluster)
+- [x] Phase 4: Reconstruction is first-class return object, not metadata hack
+- [x] Phase 5: Predicted reminders surface from behavioral signals
+- [x] Phase 5: Predictions auto-expire and respect acceptance/rejection
+- [x] All phases: `bun test` passes with baseline maintained or increased

package/plan-product-upgrades.md

@@ -0,0 +1,155 @@
+# RecallNest 产品化升级实施计划
+
+## 目标
+
+把 RecallNest 从"引擎很强但用户无感"变成"用户能看到记忆在成长"。
+
+## 四个升级（按优先级）
+
+---
+
+### Upgrade 1: SKILL.md — 记忆伙伴使用协议
+
+**做什么**：在 repo 根目录创建 `SKILL.md`，教 LLM 怎么当好记忆伙伴（不只是 API 文档）。
+
+**内容结构**：
+- Session Protocol（resume → work → checkpoint）
+- Onboarding Flow（首次检测：memory_stats 为 0 时引导）
+- Memory Feedback（store 后回显，search 后展示匹配）
+- Tool Decision Tree（什么时候 store vs checkpoint vs pin）
+- Weekly Health Check（data_checkup + dream + lint）
+
+**改动**：
+- 新建 `SKILL.md`（~250 行 markdown）
+- 零代码改动
+
+**风险**：低。纯文档。
+
+---
+
+### Upgrade 2: Memory Lint — 记忆体检
+
+**做什么**：新增 MCP tool + CLI 命令，对记忆做质量自检。
+
+**检查项**：
+| 检查 | 复用什么 | 怎么做 |
+|------|---------|--------|
+| 矛盾检测 | `detectHeuristicContradiction`（consolidation-engine.ts） | 同 scope 同 category 内两两比较 |
+| 重复检测 | `cosineSimilarity`（multi-vector.ts） | 向量相似度 > 0.92 的配对 |
+| 陈旧检测 | `parseEvolution` 的 accessCount/lastAccessedAt | 90 天未被召回 + accessCount ≤ 1 |
+| 孤儿检测 | consolidatedInto 指向的 ID | 不存在的引用 |
+| 健康分 | 综合以上 | 100 - (矛盾×10 + 重复×5 + 陈旧×2 + 孤儿×3) |
+
+**改动**：
+- 新建 `src/memory-lint.ts`（~180 行）
+- 新建 `src/__tests__/memory-lint.test.ts`（~150 行）
+- 改 `src/mcp-server.ts`：注册 `memory_lint` tool（~25 行）
+- 改 `src/cli.ts`：增加 `lint` 命令（~30 行）
+- 改 `src/api-server.ts`：增加 `GET /v1/lint`（~20 行）
+- 改 `src/consolidation-engine.ts`：export `detectHeuristicContradiction`（1 行）
+- 改 `package.json`：增加 `lint:memory` 脚本
+
+**性能守卫**：矛盾/重复检测是 O(n²)，每个 scope/category 组限 200 条，按 importance 降序取。
+
+**预计**：~405 LOC
+
+**风险**：中。矛盾检测基于启发式，会有误报，报告中标注"启发式建议"。
+
+---
+
+### Upgrade 3: Dashboard 仪表盘首页
+
+**做什么**：现有 UI（port 4317）只有搜索，加一个 Dashboard 首页 tab。
+
+**展示内容**：
+- 总记忆数 + 分类分布（bar chart，纯 CSS 实现，不引入图表库）
+- 本周/本月新增趋势
+- 健康分（来自 Lint）
+- 最近召回 Top N
+- 沉睡记忆列表（90天未召回）
+
+**改动**：
+- 改 `src/ui-server.ts`：新增 4 个 API endpoint（~80 行）
+  - `GET /api/dashboard-stats`
+  - `GET /api/recent-recalls`
+  - `GET /api/lint-summary`
+  - `GET /api/stale-memories`
+- 改 `assets/ui/index.html`：增加 Dashboard tab（~60 行）
+- 改 `assets/ui/app.js`：Dashboard 渲染逻辑（~120 行）
+- 改 `assets/ui/styles.css`：Dashboard 样式（~80 行）
+
+**依赖**：Upgrade 2（Lint 的健康分）。可以先不接 Lint，用 placeholder。
+
+**预计**：~340 LOC
+
+**风险**：中。Growth trend 需要扫全量 entries 按时间分桶，大库可能慢。缓存 60s 缓解。
+
+---
+
+### Upgrade 4: HTML 知识图谱
+
+**做什么**：把记忆导出为一个交互式 HTML 文件，浏览器打开即可看到力导向图。
+
+**节点/边设计**：
+- 节点 = 每条记忆，颜色按 category（profile=金, preferences=蓝, entities=绿, events=灰, cases=红, patterns=紫）
+- 边 = scope 关系 + consolidation 链 + supersede 链 + cluster 关系
+- 支持缩放、拖拽、点击查看详情
+
+**改动**：
+- 新建 `src/graph-export.ts`（~250 行）
+  - `buildMemoryGraph()`：从 store 构建节点/边
+  - `renderGraphHTML()`：生成自包含 HTML（D3.js via CDN，或 `--offline` 内嵌）
+  - `exportMemoryGraph()`：写文件到 `data/exports/`
+- 新建 `src/__tests__/graph-export.test.ts`（~100 行）
+- 改 `src/mcp-server.ts`：注册 `export_graph` tool（~25 行）
+- 改 `src/cli.ts`：增加 `graph` 命令（~25 行）
+- 改 `src/ui-server.ts`：增加 `/api/graph` endpoint（~20 行）
+
+**默认上限**：200 节点（按 importance 降序），避免图谱变成乱麻。
+
+**预计**：~420 LOC
+
+**风险**：中高。>100 节点时力导向布局可能卡顿。限制节点数+scope 过滤。
+
+---
+
+## 实施顺序
+
+```
+Phase 1（可独立合并）
+  ├── 1.1 SKILL.md（无代码依赖）
+  └── 1.2 memory-lint.ts + tests
+
+Phase 2（依赖 1.2）
+  ├── 2.1 Lint MCP tool + CLI
+  └── 2.2 Lint API endpoint
+
+Phase 3（依赖 Phase 2）
+  └── 3.1 Dashboard 首页
+
+Phase 4（独立，可与 1-3 并行）
+  └── 4.1 HTML 知识图谱
+```
+
+**可并行**：SKILL.md 和 Graph Export 不依赖其他升级。
+
+## 总改动量
+
+| 升级 | 新文件 | 改动文件 | 新增 LOC |
+|------|--------|---------|---------|
+| SKILL.md | 1 | 0 | ~250 (markdown) |
+| Memory Lint | 2 | 4 | ~405 |
+| Dashboard | 0 | 4 | ~340 |
+| Knowledge Graph | 2 | 3 | ~420 |
+| **总计** | **5** | **~8** | **~1,415** |
+
+## 成功标准
+
+- [ ] SKILL.md 覆盖 5 个核心场景
+- [ ] `memory_lint` MCP tool 返回矛盾/重复/陈旧/孤儿数量 + 0-100 健康分
+- [ ] `bun run src/cli.ts lint` CLI 输出相同报告
+- [ ] Dashboard tab 展示总记忆数、分类分布、健康分、沉睡记忆
+- [ ] `bun run src/cli.ts graph` 生成有效 HTML，浏览器打开有交互图谱
+- [ ] 现有 1168 个测试全部通过
+- [ ] 新增测试 > 20 个
+- [ ] 不引入新 npm 依赖

package/plan.md

@@ -0,0 +1,140 @@
+# RecallNest 架构迭代 Plan
+
+**目标**：提升 RecallNest 架构能力（不刷分，关注真实场景）
+**推送**：全部推河马仓(origin)，实用的推公开仓(public)
+
+---
+
+## 已完成
+
+### Step 1: 隐式偏好检测 (preference-slots.ts)
+- `ImplicitUsagePreferenceSlot` + 8 种中英文模式 | `6db35d08`
+
+### Step 2: Source Diversity (retriever.ts)
+- `sourceDiversity` config, round-robin 跨 scope | `6db35d08`
+
+### Step 3: Adaptive Candidate Pool (retriever.ts)
+- `adaptivePoolMultiplier` config, 聚合 query 自动扩池 | `6db35d08`
+
+### Step 4: 隐式偏好双写 (capture-engine.ts)
+- 非 preference 记忆自动派生 preference 副本 | `778cd906`
+
+### Step 5: Multi-hop 两轮检索 (retriever.ts)
+- 实体驱动的两轮检索 + 并行 follow-up | `86a4f0a3`
+
+---
+
+## 待做：架构改进（借鉴 memL + 自身短板）
+
+### Step 7: Recall Governor — auto-recall 治理层 [高优先级]
+
+**问题**：当前 auto-recall 路径只有 `shouldSkipRetrieval()` (gating) 和 `noise-filter` (事后过滤)。缺少中间治理层：
+- 无字符预算控制，注入过多记忆浪费 token
+- 无会话去重，同一轮对话里同一条记忆可能被多次注入
+- 无状态过滤二次确认（retriever 有 evolution filter 但 auto-recall 路径没有兜底）
+
+**方案**：新增 `recall-governor.ts`，在 auto-recall.ts 的 retrieve 后、返回前插入 6 层治理：
+1. Gating — 已有 `shouldSkipRetrieval()`，保持
+2. Query 截断 — 超长 query 截断到 1000 chars（省 embedding 成本）
+3. 检索 — 已有 HybridRetriever，保持
+4. 状态过滤 — 排除 archived/superseded, tier=peripheral
+5. 预算控制 — 总字符预算 + 条目数上限（可配置）
+6. 会话去重 — 维护本轮已注入 ID set，不重复注入
+
+**文件**：`src/recall-governor.ts`(新增), `src/auto-recall.ts`(接入)
+**工作量**：约 120 行 + 测试
+
+---
+
+### Step 8: Admission Control — 写入准入控制 [高优先级]
+
+**问题**：当前记忆写入只有 noise-filter（检索时才过滤）和 write-verifier（写后验证），没有写前门控。低质量记忆进库再过滤不如一开始就拦。
+
+**方案**：新增 `admission-control.ts`，在 capture-engine.ts 的 persistMemory 入口加准入检查：
+- 最短文本长度（< 10 chars 拒绝）
+- noise-filter 前置（写入前就过滤）
+- importance 下限（< 0.2 拒绝或标记 pending_review）
+- 重复检测（向量相似度 > 0.95 近似重复直接跳过）
+- 每 scope 写入频率限制（防 flood）
+
+**文件**：`src/admission-control.ts`(新增), `src/capture-engine.ts`(接入)
+**工作量**：约 80 行 + 测试
+
+---
+
+### Step 9: LLM 降级策略 — dream-pipeline + capture 容错 [中优先级]
+
+**问题**：dream-pipeline 和 LLM importance assessment 依赖外部 LLM。LLM 挂了：
+- dream-pipeline 直接失败
+- importance 静默跳过（fallback 默认 0.7，还行）
+- capture-heuristic 是纯 regex 备选但不在同一链路
+
+**方案**：借鉴 memL 三层降级：
+- Level 1: 正常 LLM 调用
+- Level 2: 降级 prompt（更短，更高成功率）
+- Level 3: 确定性 fallback（零 LLM）
+  - dream consolidation: 跳过本轮下次再试
+  - importance: heuristic 规则（文本长度 + category 权重）
+  - capture: capture-heuristic.ts 的 regex 提取
+
+**文件**：`src/llm-client.ts`(加 degradation wrapper)
+**工作量**：约 60 行 + 测试
+
+---
+
+### Step 10: Metadata 显式字段 — 去 JSON bag [中优先级，大工作量]
+
+**问题**：85 处 `JSON.parse(metadata)`。metadata 是 JSON string，塞了 evolution/boundary/anchor/preferenceSlot/pii/tags 等所有东西。每次读都要 parse，LanceDB filter 不能直接用内部字段。
+
+**方案**：高频字段提升为 MemoryEntry 顶级字段：
+```
+新增：anchor, evolution_status, confidence, access_count,
+     last_accessed_at, supersedes, superseded_by, tier
+保留 metadata：低频扩展字段仍用 JSON string
+```
+
+**风险**：LanceDB schema 变更需重建表，需 migration 脚本。
+**工作量**：约 300 行 + migration + 大量测试更新
+**建议**：单独一个完整 session，不混其他改动
+
+---
+
+### Step 11: 两段式捕获 — message buffer + batch persist [低优先级]
+
+**问题**：capture-engine 单条同步写入。高频对话产生碎片记忆。
+
+**方案**：借鉴 memL 两段式：
+- Stage 1: message_received -> 缓存到内存 buffer
+- Stage 2: agent_end（或 buffer 满/超时）-> 批量合并后写入
+
+**价值**：减少碎片，LLM 看到更完整上下文提高提取质量
+**工作量**：约 150 行 + event bus 集成
+**依赖**：host adapter 需提供 message_received / agent_end 事件
+
+---
+
+## 停车场（不做）
+
+| 方案 | 原因 |
+|------|------|
+| Extraction prompt 加偏好示例 | 针对题型优化 = 刷分 |
+| Reader 升级 | 不是 RecallNest 自身能力 |
+| L1 Context Engine | memL 的差异化，RecallNest 定位是 L2 记忆引擎 |
+| Embedding 模型更换 | 当前够用 |
+
+---
+
+## 优先级排序
+
+```
+高优先级（下一个窗口做）
+  Step 7: Recall Governor          ~120 行  <- 生产环境最需要
+  Step 8: Admission Control         ~80 行  <- 防垃圾记忆入库
+
+中优先级（之后做）
+  Step 9: LLM 降级策略              ~60 行  <- 生产容错
+  Step 10: Metadata 显式字段       ~300 行  <- 大重构，单独 session
+
+低优先级（有空再做）
+  Step 11: 两段式捕获              ~150 行  <- 需 host adapter 配合
+```