my-pi/pi-hermes-memory/docs/0.7/TASKS.md

v0.7 Tasks: Token-Aware Graph-Based Memory Retrieval

Status Legend

• [ ] Not started
• [~] In progress
• [x] Done

Epic 1: Stop Prompt Bloat

Done when full Markdown memory is no longer injected by default.

• src/types.ts — add memoryMode: "policy-only" | "legacy-inject"
• src/config.ts — parse memoryMode with policy-only default
• src/constants.ts — add expanded MEMORY_POLICY_PROMPT with accepted targets/categories
• src/index.ts — replace full memory block injection with memory policy by default
• Legacy compatibility — support memoryMode: "legacy-inject" for old behavior
• /memory-preview-context — show policy-only prompt in default mode and full blocks in legacy mode
• Tests — system prompt contains policy only in retrieval mode
• Tests — legacy mode still injects current blocks

Epic 2: Memory Router

Future phase. Do not start until policy-only mode is shipped and measured.

• src/handlers/memory-router.ts — inspect user message, recent context, project, repo/tool/error signals
• Router rules — retrieve for prior-context phrases, repo tasks, failures, preferences, conventions
• Router rules — skip generic explanation and one-off examples
• Query builder — produce compact search query from message + signals
• Debug record — persist last router decision in memory for /memory-debug-last
• Tests — retrieve/skip decisions for representative coding and generic prompts

Epic 3: Memory Ranking + Packing

Future phase. Depends on a working runtime injection hook and router.

• src/store/memory-ranker.ts — score candidates by FTS relevance, project match, category, recency, confidence
• src/store/memory-eligibility.ts — exclude wrong-scope, stale, superseded, low-confidence, and irrelevant memories
• src/store/memory-pack.ts — build <retrieved-memory security="untrusted-context"> block
• Read-time scanner — run scanContent() or equivalent before injection
• Token estimate helper — approximate budget with chars/4 and hard cap
• Tests — ranking favors project corrections/failures/conventions
• Tests — packer respects maxRetrievedTokens

Epic 4: Runtime Injection

Future phase. Do not start until the policy-only default proves insufficient.

• Identify Pi hook/API for per-turn context injection or closest supported equivalent
• src/index.ts — wire router/search/ranker/packer into the selected hook
• No-memory path — inject nothing when router skips retrieval
• Retrieved-memory path — inject small block when router finds eligible memories
• Tests — no retrieved block for generic prompt
• Tests — retrieved block appears for project/debugging prompt

Epic 5: SQLite Graph Tables

Done when graph relationships exist in SQLite and can boost retrieval.

• src/store/schema.ts — add memory_nodes, memory_edges, memory_node_links
• src/store/memory-graph-store.ts — CRUD for nodes, edges, memory links
• src/store/memory-graph-extractor.ts — extract project/file/tool/error/decision/failure entities from memory text
• Sync path — link new/updated memories to graph nodes
• Graph lookup — retrieve 1-2 hop related memory IDs for current turn signals
• Ranking integration — add graph_distance_score
• Tests — graph tables migrate cleanly
• Tests — graph-linked memory outranks unrelated FTS match

Epic 6: Conflict + Staleness

Done when stale or conflicting memory is not blindly injected.

• Schema migration — add confidence, status, supersedes_id, valid_from, valid_to, last_accessed_at, access_count
• src/store/memory-conflict-detector.ts — mark superseded/conflicting memories where deterministic
• Update write path — support status/confidence updates
• Update search path — exclude superseded and expired rows by default
• Tests — superseded memory is not injected
• Tests — current project evidence wins over memory conflict

Epic 7: Debug Commands

Done when users can see what memory did and why.

• /memory-status — mode, config, DB counts, prompt injection mode
• /memory-debug-last — router decision, query, candidates, injected count, skipped reasons, token estimate
• /memory-graph-status — graph backend, nodes, edges, links, traversal depth
• /memory-doctor — stale schema, FTS consistency, orphan graph links, oversized prompt warnings
• Tests — commands render useful output with empty and populated DBs

Epic 8: Documentation + Release

• README — document policy-only mode and legacy mode
• README — add memory policy and retrieved-memory examples
• ROADMAP — mark frozen full injection as legacy, not the future default
• Migration notes — explain how Markdown remains readable/syncable
• npm run check
• npm test
• Version bump
• Tag release

Implementation Order

1. Epic 1 — remove token tax first.
2. Epic 2 — route retrieval cheaply.
3. Epic 3 — rank/filter/pack safely.
4. Epic 4 — wire runtime injection.
5. Epic 7 — expose behavior for debugging.
6. Epic 5 — add graph booster after baseline retrieval works.
7. Epic 6 — harden conflict/staleness.
8. Epic 8 — docs and release.