recallnest 2.2.0 → 2.3.0

package/plan-philosophy-upgrades.md

@@ -1,363 +0,0 @@
-# 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

@@ -1,155 +0,0 @@
-# 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-v1.2-distributable.md

@@ -1,105 +0,0 @@
-# RecallNest v1.2: 首个可传播版本 Plan
-
-> 目标：别人 15 分钟能跑起来，30 分钟能感知价值
-> 负责人：CC (实现) + 用户 (审批)
-> 预计：3-4 天
-
----
-
-## 阻塞项（必须修，按优先级排）
-
-### B1: `recallnest doctor` 命令（新增） ✅ DONE
-**问题**：用户装完后没有一键验证手段，每个环节都可能静默失败
-**方案**：新增 `lm doctor` 子命令，检查清单：
-- [x] Bun 运行时可用？（检测版本）
-- [x] Jina API key 已配置？（读 .env）
-- [x] Jina API key 有效？（发一个测试 embedding 请求）
-- [x] CC transcript 路径可访问？（auto-detect 或 config）
-- [x] LanceDB 数据目录可写？
-- [x] 已有索引？多少条？
-- 输出：绿色 PASS / 红色 FAIL + 修复建议
-
-### B2: README 安装体验重写 ✅ DONE
-**问题**：Bun 未提及、Jina key 获取无引导、步骤跳跃
-**方案**：
-- [x] Prerequisites 段：明确列出 Bun ≥1.0 + Node ≥20（Bun 优先，Node 作为 fallback 说明）
-- [x] 快速开始改为 5 步 copy-paste：clone → install → 配 key → doctor → search
-- [x] 每步附带预期输出（用户知道"成功了"长什么样）
-- [x] 添加 "Troubleshooting" 段：Bun not found / Jina 401 / 路径不存在
-
-### B3: Jina API key 前置验证 ✅ DONE
-**问题**：config 加载成功，但第一次 ingest 才报 embedding 失败，错误信息是 OpenAI SDK 的原始 401
-**方案**：
-- [x] `ingest` 命令启动时，先调 embedder 发一个测试请求（embed "test"）
-- [x] 失败则立即报错：`Jina API key invalid or missing. Get one at https://jina.ai/embeddings/`
-- [x] `doctor` 命令复用同一验证逻辑
-
-### B4: Gemini 支持诚实化 ✅ DONE
-**问题**：README 说支持 Gemini CLI，config 里有 gemini 源，但实际 Gemini 会话是加密 protobuf，解析不了
-**方案**：
-- [x] README 中 Gemini 行标注为 `Coming soon`（不是 ✅）
-- [x] config.json.example 中移除 gemini source（新用户不会误配）
-- [x] ingest 遇到 gemini source 时打印明确 warning：`Gemini CLI sessions are encrypted protobuf; skipping`
-- [x] doctor 显示 Gemini 状态为 warn（已有配置的用户看到明确提示）
-- 不删代码，保留未来扩展能力
-
-### B5: 配置路径健壮化 ✅ DONE
-**问题**：`./data/lancedb` 是相对路径，换目录就炸；auto-detect 失败后建议不够具体
-**方案**：
-- [x] config.json.example 默认路径改为 `~/.recallnest/data/lancedb`（绝对，用户无感）
-- [x] 首次运行自动创建目录（validateStoragePath 已有 mkdirSync recursive）
-- [x] auto-detect 失败时，给出完整示例（含用户名的真实路径）
-- [x] config.json 加入 .gitignore，用户配置不被 git 覆盖
-- [x] findConfigPath 失败时提示 `cp config.json.example config.json`
-
----
-
-## 加分项（做了更好，不阻塞发布）
-
-### P1: Demo 查询内置 ✅ DONE
-- [x] `lm demo` 命令：用 3 个内置 query 跑搜索，展示结果格式
-- [x] 显示索引统计 + 每条结果的分数/来源/预览
-
-### P2: 一键安装脚本
-- [ ] `curl -fsSL https://raw.githubusercontent.com/.../install.sh | bash`
-- [ ] 检测 Bun → clone → npm install → 提示配 key → 跑 doctor
-- [ ] 可以 Q2 再做，现在 README 手动步骤够用
-
-### P3: CI 基础 ✅ DONE
-- [x] GitHub Actions：push/PR 时跑 `doctor --ci` + TypeScript check
-- [x] `lm doctor --ci` 模式跳过 API key 在线验证
-
-### P4: CHANGELOG.md ✅ DONE
-- [x] v1.0.0 到 v1.2.0 的变更记录
-- [x] 后续每个 release 维护
-
----
-
-## 不做的事（明确排除）
-
-- ❌ 不做 Docker 化（用户群是 CLI/MCP 用户，不是 Docker 用户）
-- ❌ 不做 NPM 发布（先 git clone 模式验证需求）
-- ❌ 不做 UI 重写（现有 UI 够用，不是本次重点）
-- ❌ 不做多用户支持（单 operator 场景）
-- ❌ 不重写检索逻辑（已经够好，不是本次范围）
-
----
-
-## 执行顺序
-
-```
-Day 1: B1 (doctor) + B3 (Jina 验证) — 核心安全网 ✅
-Day 2: B5 (路径健壮化) + B4 (Gemini 诚实化) + B2 (README 重写) ✅
-Day 3: P1 (demo 查询) + P3 (CI) + P4 (CHANGELOG) ✅
-Day 4: 自测完整流程
-```
-
----
-
-## 验收标准
-
-1. 全新 macOS 机器（有 Bun），从 clone 到第一条搜索结果 ≤ 15 分钟
-2. `lm doctor` 全绿
-3. Jina key 错误时，3 秒内给出明确修复建议
-4. README 无需翻代码即可完成安装
-5. `lm search "telegram bridge"` 返回有意义结果