recallnest 1.4.1 → 2.2.1

package/docs/pipeline-audit-ultramemory.md

@@ -1,177 +0,0 @@
-# Pipeline Audit: RecallNest vs UltraMemory
-
-> Auditor: CC (Claude Code Opus 4.6)
-> Date: 2026-03-28
-> Reference: trihippo/UltraMemory v1.1.0-beta.10 (private)
-> Target: AliceLJY/recallnest (~/recallnest)
-> Method: Three-Lens Pipeline Audit (pipeline-borrower skill)
-
----
-
-## Lens 1: User Lens (Daily Experience)
-
-| Pain Point | Stage | Severity |
-|---|---|---|
-| No real-time capture from live conversations — must run `ingest` manually | CAPTURE | High |
-| Same memory stored twice gets different UUIDs — canonical key helps but ID-level dedup missing | STORE | Medium |
-| Recall results not reordered by task context — same ranking for "fix a bug" vs "write an article" | RETRIEVE | Medium |
-| No one-click memory cleanup — conflict resolution is manual, no automated clustering | DECAY | Medium |
-| "TS" and "TypeScript" treated as different entities in search | RETRIEVE | Low |
-
-## Lens 2: Developer Lens (Pipeline Gaps)
-
-### Stage 1: CAPTURE
-
-**Gap: No heuristic pre-capture for live conversations**
-
-- **Our code:** `capture-engine.ts:87-105` — Only accepts explicit `CaptureMemoryInput` from tool calls
-- **Their solution:** `packages/core/src/auto-capture.ts:1-60` — `shouldCapture(text)` rejects greetings/noise/short text; `extractHeuristic(text)` extracts preference/identity/decision/correction signals with zero LLM calls
-- **Portable?** Yes — pure regex/heuristic, no dependencies
-- **Proposed fix:**
-  - Create `src/capture-heuristic.ts` with `shouldCapture()` + `extractHeuristic()`
-  - Hook into MCP `store_memory` tool as optional pre-filter
-  - Add new MCP tool `auto_capture` for live conversation analysis
-  - Estimated: ~120 LOC
-  - **Priority: High** — biggest user pain point, lowest effort
-
-### Stage 4: STORE
-
-**Gap: Random UUIDs allow duplicate entries with different IDs**
-
-- **Our code:** `store.ts:327` — `randomUUID()` for every new memory
-- **Their solution:** `packages/core/src/utils/deterministic-id.ts:1-20` — UUID v5 from `scope + text` → same content always gets same ID
-- **Portable?** Yes — single function, `uuid` package already available
-- **Proposed fix:**
-  - Add `deterministicId(scope, text)` to `store.ts`
-  - Use for durable memories when canonical key exists; keep random UUID for evidence/ephemeral
-  - Estimated: ~25 LOC
-  - **Priority: High** — prevents data pollution, trivial to implement
-
-### Stage 5: RETRIEVE
-
-**Gap 5a: Single vector search — no multi-granularity retrieval**
-
-- **Our code:** `store.ts:44` — Single `vector` column; `retriever.ts:350` — searches only one vector
-- **Their solution:** `packages/core/src/store.ts:297-309` — 3 vector columns (vector, vector_l0, vector_l1, vector_l2) with auto-migration; `packages/core/src/retriever.ts:143-147` — weighted blend (vector:0.35, bm25:0.30, l0:0.15, l1:0.10, l2:0.10)
-- **Portable?** Medium — requires LanceDB schema migration + embedding pipeline change
-- **Proposed fix:**
-  - Add `vector_l0`, `vector_l1`, `vector_l2` columns to LanceDB schema
-  - Generate L0 (1-sentence abstract), L1 (bullet), L2 (full) at embed time
-  - Blend scores in retriever with configurable weights
-  - Estimated: ~200 LOC (store migration + retriever weights + embedder pipeline)
-  - **Priority: Medium** — high value but high effort, RecallNest's metadata already stores l0/l1/l2 text but not as separate vectors
-  - **Dependency:** Needs embedding cost analysis (3x API calls per memory)
-
-**Gap 5b: No per-category score thresholds**
-
-- **Our code:** `retriever.ts:59,109-121` — Single global `hardMinScore` (0.35)
-- **Their solution:** `packages/core/src/retriever.ts:97-108` — `categoryScoreThresholds` map with per-category overrides
-- **Portable?** Yes — optional config, backward-compatible
-- **Proposed fix:**
-  - Add `categoryMinScores?: Record<string, number>` to `RetrievalConfig`
-  - In scoring pipeline, check category-specific threshold before global
-  - Default: preferences=0.25, entities=0.30, events=0.35, cases=0.40, patterns=0.45, profile=0.25
-  - Estimated: ~30 LOC
-  - **Priority: Medium** — improves recall precision per category
-
-**Gap 5c: No entity resolution in search**
-
-- **Our code:** `query-expander.ts` — hardcoded synonym dict (~20 groups), no entity normalization
-- **Their solution:** `packages/core/src/entity-resolver.ts:1-62` — `EntityResolver` class with builtin + user aliases, resolves TS→typescript, React.js→react, DB aliases
-- **Portable?** Yes — pure mapping logic
-- **Proposed fix:**
-  - Create `src/entity-resolver.ts` with tech entity mappings
-  - Hook into `query-expander.ts` before synonym expansion
-  - Also normalize entities at capture time (before canonical key generation)
-  - Estimated: ~80 LOC
-  - **Priority: Low** — nice-to-have, query-expander partially covers this
-
-### Stage 6: INJECT
-
-**Gap: No contextual reordering of recall results**
-
-- **Our code:** `context-composer.ts:41-100` — scope-based prioritization only; `retriever.ts:346` — returns results in score order
-- **Their solution:** `packages/core/src/context-renderer.ts:1-98` — `renderMemories()` reorders by 60% vector score + 40% term overlap, with task context awareness
-- **Portable?** Yes — pure function, no dependencies
-- **Proposed fix:**
-  - Create `src/context-renderer.ts` with `renderMemories()`
-  - Hook into `context-composer.ts` after retrieval, before budget cutting
-  - Also hook into `search_memory` tool result formatting
-  - Estimated: ~100 LOC
-  - **Priority: Medium** — improves relevance of injected context
-
-### Stage 7: DECAY
-
-**Gap: No automated semantic consolidation**
-
-- **Our code:** `memory-health-rebalance.ts:145-197` — tier rebalancing only; `conflict-engine.ts` — passive conflict detection on write
-- **Their solution:** `packages/core/src/consolidation-engine.ts:1-388` — `ConsolidationEngine.run(scope)` scans all entries, clusters by vector similarity (>0.82), merges near-duplicates (>0.92), detects contradictions, adds relation links
-- **Portable?** Medium — needs store's vectorSearch API; RecallNest already has it
-- **Proposed fix:**
-  - Create `src/consolidation-engine.ts` adapting UltraMemory's approach
-  - Reuse RecallNest's `store.vectorSearch()` and `cosineSimilarity()`
-  - Add MCP tool `consolidate_memories` (scope, threshold params)
-  - Integrate with existing `conflict-engine.ts` for conflict creation
-  - Estimated: ~250 LOC
-  - **Priority: Medium** — automates manual cleanup; high value at scale
-
-## Lens 3: Evidence Table
-
-| Feature | RecallNest | UltraMemory | Status |
-|---|---|---|---|
-| Hybrid retrieval (vector + BM25 + RRF) | `retriever.ts:350` | `retriever.ts:250` | **both have** |
-| Cross-encoder reranking | `retriever.ts:400+` (Jina/Voyage/Pinecone/vLLM) | `retriever.ts:500+` (Jina) | **our advantage** (more providers) |
-| Weibull decay + tier system | `decay-engine.ts:145-159` (β per tier) | `decay-engine.ts:111` (retention presets) | **our advantage** (more sophisticated) |
-| Conflict detection + lifecycle | `conflict-engine.ts` + `conflict-store.ts` + `conflict-lifecycle.ts` | `conflict-detector.ts` (detect only, no lifecycle) | **our advantage** |
-| Canonical key dedup | `memory-boundaries.ts:125-148` | None | **our advantage** |
-| Workflow observation | `workflow-observation-engine.ts` (7 files) | None | **our advantage** |
-| Checkpoint sanitization | `session-engine.ts` (strips repo state) | None | **our advantage** |
-| Retrieval profiles (4 presets) | `retrieval-profiles.ts` (writing/debug/fact-check/default) | None (single config) | **our advantage** |
-| Provenance chain (20 levels) | `memory-boundaries.ts` (provenanceHistory) | None | **our advantage** |
-| MCP tool tier control | `mcp-server.ts` (core/advanced/full) | None (all exposed) | **our advantage** |
-| Multi-vector L0/L1/L2 embedding | Metadata storage only (`mcp-server.ts:1083`) | Full pipeline (`store.ts:297`, `retriever.ts:143`) | **their advantage** |
-| Auto-capture heuristic | None | `auto-capture.ts:1-60` (zero LLM) | **their advantage** |
-| Semantic consolidation | Rebalancing only (`memory-health-rebalance.ts`) | Full engine (`consolidation-engine.ts:1-388`) | **their advantage** |
-| Context renderer | Scope-based only (`context-composer.ts`) | Intent-based (`context-renderer.ts:1-98`) | **their advantage** |
-| Deterministic IDs | Random UUID (`store.ts:327`) | UUID v5 (`deterministic-id.ts`) | **their advantage** |
-| Entity resolver | None | `entity-resolver.ts:1-62` | **their advantage** |
-| Per-category score thresholds | Profile-based only (`retrieval-profiles.ts`) | Category-based (`retriever.ts:97-108`) | **their advantage** |
-
-**Score: RecallNest 10 advantages, UltraMemory 7 advantages.** RecallNest's strengths are in governance/lifecycle; UltraMemory's are in retrieval precision.
-
----
-
-## Phase 4: Implementation Plan
-
-### Phase 1 (No deps, can start immediately)
-
-| # | Gap | File | LOC | Priority |
-|---|---|---|---|---|
-| 1 | Auto-capture heuristic | new `capture-heuristic.ts` | ~120 | **High** |
-| 2 | Deterministic IDs | `store.ts:327` | ~25 | **High** |
-| 3 | Per-category score thresholds | `retriever.ts:59` | ~30 | Medium |
-
-### Phase 2 (Depends on Phase 1)
-
-| # | Gap | File | LOC | Priority |
-|---|---|---|---|---|
-| 4 | Entity resolver | new `entity-resolver.ts` → hooks into capture + query | ~80 | Low |
-| 5 | Context renderer | new `context-renderer.ts` → hooks into composer | ~100 | Medium |
-
-### Phase 3 (Depends on vectorSearch stability)
-
-| # | Gap | File | LOC | Priority |
-|---|---|---|---|---|
-| 6 | Consolidation engine | new `consolidation-engine.ts` + MCP tool | ~250 | Medium |
-| 7 | Multi-vector L0/L1/L2 | `store.ts` + `retriever.ts` + `embedder.ts` | ~200 | Medium |
-
-### Total estimated: ~805 LOC across 7 proposals
-
-**Recommended order:** 1 → 2 → 3 → 5 → 6 → 4 → 7
-
-Rationale: Start with biggest pain point (auto-capture) and easiest win (deterministic IDs). Multi-vector last because it's highest effort and needs embedding cost analysis (3x API calls).
-
----
-
-*Pipeline audit complete. Methodology: Three-Lens (User/Developer/Evidence).*
-*Key lesson applied: Be Team B (pipeline gaps), not Team A (feature envy).*

package/docs/plans/2026-03-08-query-expansion.md

@@ -1,270 +0,0 @@
-# Query Expansion for Fuzzy Chinese Search
-
-> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
-
-**Goal:** Add a lightweight Chinese synonym/colloquial-to-technical query expansion layer before retrieval, improving fuzzy search hit rate without adding API dependencies.
-
-**Architecture:** New `query-expander.ts` module with a static synonym dictionary. Called in `retriever.ts` before BM25 search — expands the original query into additional BM25 search terms. Vector search stays unchanged (Jina embeddings already handle semantic similarity). The expansion only boosts BM25 recall for terms that the user says differently from how they're stored.
-
-**Tech Stack:** Pure TypeScript, no new dependencies. Static dictionary file.
-
----
-
-### Task 1: Create synonym dictionary + expander module
-
-**Files:**
-- Create: `src/query-expander.ts`
-- Test: `src/__tests__/query-expander.test.ts`
-
-**Step 1: Write the failing test**
-
-```typescript
-// src/__tests__/query-expander.test.ts
-import { describe, it, expect } from "bun:test";
-import { expandQuery } from "../query-expander.js";
-
-describe("expandQuery", () => {
-  it("expands colloquial Chinese to technical terms", () => {
-    const result = expandQuery("bot 突然挂了");
-    expect(result).toContain("崩溃");
-    expect(result).toContain("crash");
-    expect(result).toContain("挂了");
-  });
-
-  it("expands fuzzy feeling queries", () => {
-    const result = expandQuery("AI 到底有没有感受");
-    expect(result).toContain("意识");
-    expect(result).toContain("consciousness");
-    expect(result).toContain("感受");
-  });
-
-  it("preserves original query terms", () => {
-    const result = expandQuery("配图风格");
-    expect(result).toContain("配图");
-    expect(result).toContain("风格");
-  });
-
-  it("returns original for already-precise queries", () => {
-    const result = expandQuery("JINA_API_KEY");
-    expect(result).toBe("JINA_API_KEY");
-  });
-
-  it("handles empty/short queries", () => {
-    expect(expandQuery("")).toBe("");
-    expect(expandQuery("hi")).toBe("hi");
-  });
-});
-```
-
-**Step 2: Run test to verify it fails**
-
-Run: `cd ~/local-memory && bun test src/__tests__/query-expander.test.ts`
-Expected: FAIL — module not found
-
-**Step 3: Write the implementation**
-
-```typescript
-// src/query-expander.ts
-/**
- * Lightweight Chinese query expansion via static synonym dictionary.
- * Expands colloquial/fuzzy terms into technical equivalents for BM25 boost.
- * No API calls — pure local dictionary lookup.
- */
-
-// Each entry: [trigger patterns, expansion terms]
-// Trigger: if any pattern matches (substring), add all expansion terms to query
-const SYNONYM_MAP: Array<[string[], string[]]> = [
-  // --- Status / Failure ---
-  [["挂了", "挂掉", "宕机", "down"], ["崩溃", "crash", "error", "报错", "挂了", "宕机", "失败"]],
-  [["卡住", "卡死", "没反应"], ["hang", "timeout", "超时", "卡住", "无响应", "stuck"]],
-  [["炸了", "爆了"], ["崩溃", "crash", "OOM", "内存溢出", "error"]],
-
-  // --- AI / Consciousness ---
-  [["感受", "感觉", "情感"], ["意识", "consciousness", "experiencing", "感受", "情感", "qualia"]],
-  [["有没有意识", "是否有意识"], ["consciousness", "意识", "sentience", "感知", "自我意识"]],
-  [["自由意志"], ["free will", "自由意志", "决定论", "determinism"]],
-
-  // --- Config / Deploy ---
-  [["配置", "设置", "config"], ["配置", "config", "configuration", "settings", "设置"]],
-  [["部署", "上线"], ["deploy", "部署", "上线", "发布", "release"]],
-  [["容器", "docker"], ["Docker", "容器", "container", "docker-compose"]],
-
-  // --- Code / Debug ---
-  [["报错", "出错", "错误"], ["error", "报错", "exception", "错误", "失败", "bug"]],
-  [["修复", "修了", "修好"], ["fix", "修复", "patch", "修了", "解决"]],
-  [["踩坑", "坑"], ["踩坑", "bug", "问题", "教训", "排查", "troubleshoot"]],
-
-  // --- Writing / Content ---
-  [["配图", "插图"], ["配图", "封面", "style-catalog", "风格", "图片", "image"]],
-  [["排版", "版式"], ["排版", "layout", "主题", "theme", "样式"]],
-  [["风格"], ["风格", "style", "轮换", "catalog"]],
-  [["写作", "写文章"], ["写作", "writing", "文章", "公众号", "content-alchemy"]],
-
-  // --- Infrastructure ---
-  [["bot", "机器人"], ["bot", "机器人", "OpenClaw", "agent", "gateway"]],
-  [["推送", "push"], ["push", "推送", "git push", "commit"]],
-  [["记忆", "memory"], ["记忆", "memory", "记忆系统", "LanceDB", "索引"]],
-  [["搜索", "查找", "找"], ["搜索", "search", "retrieval", "检索", "查找"]],
-];
-
-/**
- * Expand a query by appending synonym terms from the dictionary.
- * Returns the original query with additional terms appended.
- * Idempotent — already-precise queries pass through unchanged.
- */
-export function expandQuery(query: string): string {
-  if (!query || query.trim().length < 2) return query;
-
-  const lower = query.toLowerCase();
-  const additions = new Set<string>();
-
-  for (const [triggers, expansions] of SYNONYM_MAP) {
-    if (triggers.some(t => lower.includes(t.toLowerCase()))) {
-      for (const exp of expansions) {
-        // Don't add terms already in the query
-        if (!lower.includes(exp.toLowerCase())) {
-          additions.add(exp);
-        }
-      }
-    }
-  }
-
-  if (additions.size === 0) return query;
-  return `${query} ${[...additions].join(" ")}`;
-}
-```
-
-**Step 4: Run tests to verify they pass**
-
-Run: `cd ~/local-memory && bun test src/__tests__/query-expander.test.ts`
-Expected: All 5 tests PASS
-
-**Step 5: Commit**
-
-```bash
-cd ~/local-memory
-git add src/query-expander.ts src/__tests__/query-expander.test.ts
-git commit -m "feat: add Chinese synonym query expansion dictionary"
-```
-
----
-
-### Task 2: Wire expander into BM25 search path
-
-**Files:**
-- Modify: `src/retriever.ts` (lines 334-349, hybridRetrieval method)
-
-**Step 1: Write the integration**
-
-In `retriever.ts`, import the expander at the top:
-
-```typescript
-import { expandQuery } from "./query-expander.js";
-```
-
-Then in `hybridRetrieval()` (line 348), change the BM25 call to use expanded query:
-
-```typescript
-// Before:
-this.runBM25Search(query, candidatePoolSize, scopeFilter, category),
-
-// After:
-this.runBM25Search(expandQuery(query), candidatePoolSize, scopeFilter, category),
-```
-
-Note: Vector search (line 347) stays unchanged — Jina embeddings handle semantics.
-Note: The reranker (line 359) uses the original `query`, not expanded — reranking should judge against user intent.
-
-**Step 2: Run existing cases to verify no regression**
-
-Run: `cd ~/local-memory && bun run src/eval.ts`
-Expected: All 6 existing cases still PASS (or same score as before)
-
-**Step 3: Commit**
-
-```bash
-cd ~/local-memory
-git add src/retriever.ts
-git commit -m "feat: wire query expansion into BM25 retrieval path"
-```
-
----
-
-### Task 3: Add fuzzy test cases and run before/after comparison
-
-**Files:**
-- Modify: `eval/cases.json`
-
-**Step 1: Add fuzzy test cases**
-
-Append these cases to `eval/cases.json`:
-
-```json
-{
-  "name": "fuzzy_bot_crash",
-  "query": "上次那个 bot 突然挂了是怎么回事来着",
-  "profile": "debug",
-  "limit": 5,
-  "expectAny": ["崩溃", "crash", "error", "报错", "排查", "修复", "docker"],
-  "expectScopePrefixes": ["cc"],
-  "notes": "Fuzzy colloquial query about bot crash should find debugging conversations."
-},
-{
-  "name": "fuzzy_ai_feelings",
-  "query": "之前聊过一个关于 AI 到底有没有感受的话题",
-  "profile": "writing",
-  "limit": 5,
-  "expectAny": ["意识", "consciousness", "experiencing", "感受", "自由意志", "sentience"],
-  "expectScopePrefixes": ["cc"],
-  "notes": "Vague conversational query about AI consciousness should recall philosophical discussions."
-},
-{
-  "name": "fuzzy_image_style",
-  "query": "那个配图风格轮换的逻辑是怎么搞的",
-  "profile": "default",
-  "limit": 5,
-  "expectAny": ["风格", "style", "轮换", "catalog", "配图"],
-  "expectScopePrefixes": ["cc"],
-  "notes": "Casual question about image style rotation should find implementation discussions."
-}
-```
-
-**Step 2: Run full suite and save report**
-
-Run: `cd ~/local-memory && bun run src/eval.ts --output eval/reports/query-expansion.md`
-Expected: New fuzzy cases should score higher than without expansion
-
-**Step 3: Commit**
-
-```bash
-cd ~/local-memory
-git add eval/cases.json eval/reports/query-expansion.md
-git commit -m "test: add fuzzy Chinese query cases and expansion baseline report"
-```
-
----
-
-### Task 4: Manual smoke test with real queries
-
-**Not code — manual verification via CLI**
-
-Run these and visually check relevance:
-
-```bash
-cd ~/local-memory
-./lm search "上次那个 bot 突然挂了是怎么回事来着" --profile debug
-./lm search "之前聊过一个关于 AI 到底有没有感受的话题" --profile writing
-./lm search "那个配图风格轮换的逻辑是怎么搞的"
-./lm search "怎么给秦超老师的项目提 PR 来着"
-./lm search "公众号发布流程是什么"
-```
-
-Compare against the results we got earlier (before expansion) to confirm improvement.
-
-**Commit (if any dictionary tuning needed):**
-
-```bash
-cd ~/local-memory
-git add src/query-expander.ts
-git commit -m "tune: adjust synonym dictionary based on smoke test"
-```

package/docs/plans/2026-03-16-continuity-layer.md

@@ -1,196 +0,0 @@
-# Continuity Layer Plan
-
-> Phase 1 design for turning RecallNest from searchable history into a continuity layer.
-
-## Goal
-
-RecallNest already provides shared memory across Claude Code, Codex, and Gemini CLI. The next step is not "more search." The next step is continuity:
-
-- stable context should survive across windows
-- active work state should not be mixed into long-term memory
-- startup context should be composed deliberately, not copied from raw search results
-
-## The Three Layers
-
-### 1. Durable Memory
-
-Purpose:
-
-- long-lived context worth keeping across sessions and terminals
-
-Categories:
-
-- `profile`
-- `preferences`
-- `entities`
-- `events`
-- `cases`
-- `patterns`
-
-Characteristics:
-
-- stored in the main memory index
-- survives across windows
-- retrieved through the normal retrieval stack
-
-Primary write interface:
-
-- `store_memory`
-
-### 2. Session Checkpoint
-
-Purpose:
-
-- preserve current work state without polluting long-term memory
-
-Typical contents:
-
-- current task summary
-- decisions made in the session
-- open loops
-- next actions
-- active entities
-- relevant files
-
-Characteristics:
-
-- scoped to the current session or work thread
-- short-lived compared with durable memory
-- should be stored separately from the main durable memory table
-
-Primary write interface:
-
-- `checkpoint_session`
-
-### 3. Resume Context
-
-Purpose:
-
-- provide a fresh window with the minimum context needed to work effectively
-
-Sources:
-
-- stable durable memories
-- pinned assets
-- recent cases and patterns
-- latest session checkpoint
-
-Characteristics:
-
-- composed output, not raw search results
-- optimized for prompt injection or startup display
-- should bias toward stable background, not "resume the last conversation verbatim"
-
-Primary read interface:
-
-- `resume_context`
-
-## Interface Boundaries
-
-### `store_memory`
-
-Use when:
-
-- a fact, preference, entity, case, or reusable pattern should survive long term
-
-Do not use when:
-
-- the content is only about the current unfinished work state
-
-Schema:
-
-- code source: [`memory-schema.ts`](/Users/anxianjingya/recallnest/src/memory-schema.ts)
-
-Key fields:
-
-- `text`
-- `category`
-- `importance`
-- `scope`
-- `source`
-- `tags`
-
-### `checkpoint_session`
-
-Use when:
-
-- a session needs a compact representation of current progress
-
-Do not use when:
-
-- the information is already a durable user/project fact
-
-Schema:
-
-- code source: [`session-schema.ts`](/Users/anxianjingya/recallnest/src/session-schema.ts)
-
-Key fields:
-
-- `sessionId`
-- `summary`
-- `decisions`
-- `openLoops`
-- `nextActions`
-- `entities`
-- `files`
-
-### `resume_context`
-
-Use when:
-
-- a new window or task start needs continuity
-
-The response should answer:
-
-- who is this user
-- what stable preferences matter
-- what project entities are relevant
-- what reusable patterns or recent cases matter
-- what is the latest active checkpoint
-
-Schema:
-
-- code source: [`session-schema.ts`](/Users/anxianjingya/recallnest/src/session-schema.ts)
-
-Key fields:
-
-- `summary`
-- `stableContext`
-- `relevantPatterns`
-- `recentCases`
-- `latestCheckpoint`
-
-## Storage Direction
-
-### Durable memory
-
-- stays in the main `memories` index
-- uses existing retrieval, decay, and tiering
-
-### Session checkpoints
-
-- should move to a dedicated store or table
-- should not be mixed with durable memory rows by default
-
-## Why This Split Matters
-
-Without this split, RecallNest tends to accumulate two incompatible things in one place:
-
-- stable memory that should be reused for months
-- transient working notes that are only useful during the current task
-
-That creates noisy recall and weak startup continuity.
-
-## Implementation Order
-
-1. Define schema and contracts
-2. Add structured durable memory writes
-3. Add session checkpoint persistence
-4. Add resume context composition
-5. Add continuity-focused evaluation
-
-## Done in Phase 1
-
-- Added durable memory schemas in [`memory-schema.ts`](/Users/anxianjingya/recallnest/src/memory-schema.ts)
-- Added checkpoint and resume schemas in [`session-schema.ts`](/Users/anxianjingya/recallnest/src/session-schema.ts)
-- Wired existing category validation to the new durable memory schema in [`api-server.ts`](/Users/anxianjingya/recallnest/src/api-server.ts) and [`mcp-server.ts`](/Users/anxianjingya/recallnest/src/mcp-server.ts)