my-pi/pi-hermes-memory/docs/0.6/PLAN.md

v0.5 Plan: Failure Memory + Categories + Provenance

Overview

Track failures, corrections, and insights as first-class memories with full provenance and category labels. Learn from failures like humans do.

Motivation

From X/Twitter feedback:

"Memory gets much more useful when it stores failures, not just conversations. I'd want every recalled session to carry provenance: source, timestamp, tool state, and whether the old answer survived contact with reality."

Key Features

1. Memory Categories

Add category labels to differentiate memory types:

Category	What It Is	Example
failure	What didn't work	"Tried localStorage for tokens — XSS risk"
correction	User corrected the agent	"Use pnpm, not npm"
insight	Learning from experience	"Auth0 SDK handles refresh tokens automatically"
preference	User preference	"Prefers dark theme"
convention	Project convention	"Monorepo uses turborepo"
tool-quirk	Tool-specific knowledge	"CI needs --frozen-lockfile"

2. Failure Memory Structure

interface FailureMemory {
  category: 'failure' | 'correction' | 'insight' | 'preference' | 'convention' | 'tool-quirk';
  content: string;           // What was tried / what happened
  failure_reason?: string;   // Why it failed (for failures)
  tool_state?: string;       // Relevant tool state (error message, output)
  corrected_to?: string;     // What worked instead (if known)
  project: string;           // Which project
  session_id?: string;       // Which session
  timestamp: string;         // When it happened
}

3. Auto-Detect Failures

Detect failures from:

• Explicit corrections: "that didn't work", "use X instead", "no, do it this way"
• Error messages: stderr output, test failures, build errors
• Agent retries: When the agent tries multiple approaches
• User feedback: "this is wrong", "that's not right"

4. Failure Injection into System Prompt

Inject relevant recent failures into the system prompt at session start:

<memory-context>
RECENT FAILURES & LESSONS (learn from these):
• [failure] Tried: localStorage for JWT tokens — Failed: XSS vulnerability
  → Corrected to: httpOnly cookies with SameSite=Strict
• [correction] Use pnpm, not npm (corrected 2 days ago)
• [insight] Auth0 SDK handles refresh tokens automatically — no manual implementation needed
═══ END MEMORY ═══
</memory-context>

Injection rules:

• Only inject failures from last 7 days
• Only inject failures relevant to current project (or global)
• Max 5 failure entries to avoid prompt bloat
• Separate <memory-context> block from regular memory

5. Search with Categories

Update memory_search tool to support category filtering:

memory_search("auth", category: "failure")   → Past auth failures
memory_search("deploy", category: "convention") → Deploy conventions
memory_search("typescript", category: "tool-quirk") → TS tool quirks

6. Store Failures in SQLite

Failures stored in memories table with target: 'failure':

-- New target type
target TEXT CHECK (target IN ('memory', 'user', 'failure'))

-- Content stored as JSON with category
{
  "category": "failure",
  "content": "Tried localStorage for JWT tokens",
  "failure_reason": "XSS vulnerability - tokens accessible via JS",
  "tool_state": "Error: Token exposed in browser console",
  "corrected_to": "httpOnly cookies with SameSite=Strict",
  "project": "my-app",
  "timestamp": "2026-05-03T10:30:00Z"
}

7. Update Background Review Prompt

Enhance the background review prompt to extract failures:

Review this conversation and extract:

1. FAILURES: What was tried but didn't work?
   - What was attempted
   - Why it failed
   - What error occurred
   - What worked instead (if found)

2. CORRECTIONS: Did the user correct the agent?
   - What was wrong
   - What is correct

3. INSIGHTS: What was learned?
   - New knowledge about tools, APIs, patterns
   - Project-specific learnings

4. CONVENTIONS: Any project conventions discovered?
   - Coding style, naming, patterns
   - Tool preferences

Architecture Changes

Memory Store (src/store/memory-store.ts)

// Add to MemoryStore class
addFailure(content: string, options: {
  category: MemoryCategory;
  failureReason?: string;
  toolState?: string;
  correctedTo?: string;
}): void;

getFailureEntries(): string[];  // Returns recent failures for injection

SQLite Memory Store (src/store/sqlite-memory-store.ts)

// Update searchMemories to support category filter
searchMemories(db, query, { project, target, category, limit })

Memory Search Tool (src/tools/memory-search-tool.ts)

// Add category parameter
category: Type.Optional(StringEnum([
  'failure', 'correction', 'insight', 'preference', 'convention', 'tool-quirk'
] as const, { description: 'Filter by memory category.' }))

Background Review (src/handlers/background-review.ts)

• Extract failures during review
• Store with category labels
• Include failure context in review prompt

Correction Detector (src/handlers/correction-detector.ts)

• Extract failure context when correction detected
• Store what was wrong + what is correct

System Prompt Injection (src/index.ts)

• Add separate <memory-context> block for failures
• Inject only recent (7 days) and relevant (project match)
• Max 5 entries

Files to Change

File	Change
src/types.ts	Add MemoryCategory type
src/constants.ts	Update review prompt for failure extraction
src/store/memory-store.ts	Add addFailure(), getFailureEntries()
src/store/sqlite-memory-store.ts	Add category support to search
src/tools/memory-search-tool.ts	Add category parameter
src/handlers/background-review.ts	Extract failures during review
src/handlers/correction-detector.ts	Store failure context on corrections
src/index.ts	Inject failure memories into system prompt
tests/store/memory-store.test.ts	Test failure storage
tests/store/sqlite-memory-store.test.ts	Test category search
tests/tools/memory-search-tool.test.ts	Test category parameter

Complexity Assessment

• Effort: Medium (2-3 hours)
• Risk: Low (additive, no breaking changes)
• Tests: ~15 new tests

Migration

• Existing memories get category: null (no migration needed)
• New memories get category assigned
• Search works with or without category filter