pi-hermes-memory 0.5.4 → 0.6.1

package/README.md

@@ -38,6 +38,7 @@ pi install npm:pi-hermes-memory
 |---|---|
 | 🔍 **Session Search** | Search across all past conversations via SQLite FTS5 |
 | 🧠 **Persistent Memory** | Facts, preferences, lessons saved to markdown files |
+| ⚠️ **Failure Memory** | Learn from failures — stores what didn't work and why |
 | 📚 **Procedural Skills** | The agent saves *how* it solved problems as reusable docs |
 | ⚡ **Background Learning** | Every 10 turns (or 15 tool calls) the agent reviews and saves |
 | 🔧 **Correction Detection** | When you correct the agent, it saves immediately |
@@ -124,9 +125,51 @@ System Prompt
 │ • tests use node:test with tsx          │
 │ ═══ END MEMORY ═══                     │
 │ </memory-context>                       │
+│                                         │
+│ <memory-context>                        │
+│ RECENT FAILURES & LESSONS (learn from): │
+│ • [correction] Use pnpm, not npm        │
+│ • [failure] Tried localStorage — XSS    │
+│ • [insight] Auth0 handles refresh tokens│
+│ ═══ END MEMORY ═══                     │
+│ </memory-context>                       │
 └─────────────────────────────────────────┘
 ```
 
+## Failure Memory
+
+The agent learns from failures, corrections, and insights — just like humans do.
+
+### Memory Categories
+
+| Category | What it stores | Example |
+|---|---|---|
+| `failure` | What didn't work and why | "Tried localStorage for tokens — XSS vulnerability" |
+| `correction` | User corrections | "Use pnpm, not npm" |
+| `insight` | Learnings from experience | "Auth0 SDK handles refresh tokens automatically" |
+| `preference` | User preferences | "Prefers dark theme" |
+| `convention` | Project conventions | "Monorepo uses turborepo" |
+| `tool-quirk` | Tool-specific knowledge | "CI needs --frozen-lockfile" |
+
+### How It Works
+
+1. **Auto-detection**: Background review extracts failures from conversations
+2. **Correction capture**: When you correct the agent, it saves what went wrong
+3. **System prompt injection**: Recent failures (last 7 days) are injected at session start
+4. **Searchable**: Use `memory_search("auth", category: "failure")` to find past failures
+
+### Example
+
+```
+User: No, use pnpm not npm
+Agent: [saves correction memory]
+
+Next session:
+Agent: "I remember you prefer pnpm over npm. Let me use that."
+```
+
+The agent learns from its mistakes so you don't have to repeat yourself.
+
 Memory blocks are wrapped in `<memory-context>` XML tags with a guard note ("NOT new user input") to prevent the LLM from treating stored facts as instructions.
 
 ## Usage

package/docs/0.4/linkedin_post.md

@@ -0,0 +1,97 @@
+# LinkedIn Post — Pi Hermes Memory v0.4
+
+**Best time to post:** 7:30-8:30 AM (morning engagement peak)
+
+**Attach:** `docs/images/pi_memory.png` as the post image
+
+---
+
+🚀 **I just open-sourced a persistent memory system for AI coding agents.**
+
+Every time you start a new session with an AI coding agent, it forgets everything. That debugging session from last week? Gone. The architecture decision you discussed for 2 hours? Vanished. The user preferences you explained 5 times? You'll explain them a 6th.
+
+I got tired of re-explaining context every session. So I built **Pi Hermes Memory** — an extension that gives your AI agent a brain that actually works.
+
+**What it does:**
+
+🧠 **Persistent memory** — facts, preferences, corrections survive across sessions
+🔍 **Cross-session & cross-project search** — find any conversation across ALL your projects
+📚 **Procedural skills** — the agent saves *how* it solved problems, not just what
+🛡️ **Secret scanning** — API keys and tokens are blocked from being persisted
+⚡ **Background learning** — reviews your conversation every 10 turns and saves what matters
+
+**The key insight:**
+
+Most memory tools only remember facts. Mine remembers:
+- **What you said** (session history — searchable via FTS5)
+- **What you learned** (episodic memory — builds over time)
+- **How you solved problems** (procedural skills — reusable patterns)
+- **What you corrected** (corrections — saves immediately)
+
+And it works **across all your projects**. Ask "what did we discuss about auth?" and it searches every session, every project, instantly.
+
+**The architecture:**
+
+- Core memory (MEMORY.md): Always in context, 5,000 chars
+- Extended memory (SQLite): Unlimited, searchable on demand
+- Session history (FTS5): Full-text search across all past conversations
+- Skills (SKILL.md): Procedural knowledge that builds over time
+
+**The result?**
+
+Instead of starting from zero every session, my agent now says:
+
+*"Last Tuesday we discussed implementing JWT with refresh tokens. You preferred httpOnly cookies over localStorage. We also decided to use the auth0 SDK. Want me to continue from there?"*
+
+**Technical details:**
+- 272 tests
+- SQLite with FTS5 for fast full-text search
+- Hybrid memory: core (always in context) + extended (searchable on demand)
+- Auto-consolidation when memory fills up
+- Correction detection (saves immediately when you correct the agent)
+
+It's open source and works with the Pi coding agent.
+
+**Get started:**
+```
+pi install npm:pi-hermes-memory
+/memory-index-sessions
+```
+
+Your AI agent should remember as much as you do. Now it does.
+
+GitHub: https://github.com/chandra447/pi-hermes-memory
+npm: https://www.npmjs.com/package/pi-hermes-memory
+
+---
+
+#coding-agent #agent-harness #memory #ai
+
+---
+
+## Posting Tips
+
+1. **Attach the logo image** — `docs/images/pi_memory.png`
+2. **Post at 7:30-8:30 AM** — morning coffee + LinkedIn scroll time
+3. **Engage with comments** in the first 2 hours — LinkedIn rewards early engagement
+4. **Reply to everyone** — even simple "thanks!" helps visibility
+5. **Share to relevant groups** if you're in any AI/dev communities
+6. **Tag people** if you know anyone in the Pi community or AI dev space
+
+## Hashtag Strategy
+
+Primary (high volume):
+- #AI
+- #OpenSource
+- #SoftwareEngineering
+- #DevTools
+
+Niche (targeted):
+- #CodingAgent
+- #DeveloperProductivity
+- #MachineLearning
+- #ArtificialIntelligence
+
+Brand (discoverable):
+- #Pi
+- #TypeScript

package/docs/0.6/PLAN.md

@@ -0,0 +1,202 @@
+# 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
+
+```typescript
+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'`:
+
+```sql
+-- 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`)
+
+```typescript
+// 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`)
+
+```typescript
+// Update searchMemories to support category filter
+searchMemories(db, query, { project, target, category, limit })
+```
+
+### Memory Search Tool (`src/tools/memory-search-tool.ts`)
+
+```typescript
+// 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

package/docs/0.6/TASKS.md

@@ -0,0 +1,144 @@
+# v0.5 Tasks: Failure Memory + Categories + Provenance
+
+## Status Legend
+- `[ ]` Not started
+- `[~]` In progress
+- `[x]` Done
+
+---
+
+## Epic 1: Category Types & Schema
+
+### Task 1.1: Add MemoryCategory type
+- [ ] Add `MemoryCategory` type to `src/types.ts`
+- [ ] Categories: `failure`, `correction`, `insight`, `preference`, `convention`, `tool-quirk`
+
+### Task 1.2: Update SQLite schema
+- [ ] Update `src/store/schema.ts` — add `category` column to memories table
+- [ ] Add index on category for faster filtering
+
+---
+
+## Epic 2: Failure Memory Store
+
+### Task 2.1: Update MemoryStore
+- [ ] Add `addFailure()` method to `src/store/memory-store.ts`
+- [ ] Store failures in MEMORY.md with category metadata
+- [ ] Add `getFailureEntries()` to retrieve recent failures (last 7 days)
+- [ ] Update `formatForSystemPrompt()` to include failure section
+
+### Task 2.2: Update SQLite Memory Store
+- [ ] Add category support to `src/store/sqlite-memory-store.ts`
+- [ ] Update `addMemory()` to accept category
+- [ ] Update `searchMemories()` to filter by category
+- [ ] Add `getRecentFailures()` method
+
+### Task 2.3: Tests
+- [ ] Test `addFailure()` in `tests/store/memory-store.test.ts`
+- [ ] Test category filtering in `tests/store/sqlite-memory-store.test.ts`
+- [ ] Test `getRecentFailures()` returns only last 7 days
+
+---
+
+## Epic 3: Failure Detection
+
+### Task 3.1: Update Correction Detector
+- [ ] Update `src/handlers/correction-detector.ts`
+- [ ] Extract failure context when correction detected
+- [ ] Store: what was wrong, what is correct, category
+
+### Task 3.2: Update Background Review Prompt
+- [ ] Update `src/constants.ts` — enhance `CONSOLIDATION_PROMPT`
+- [ ] Add failure extraction instructions
+- [ ] Prompt to categorize findings (failure, correction, insight, etc.)
+
+### Task 3.3: Auto-Detect Failures in Conversation
+- [ ] Add failure pattern detection in `src/handlers/background-review.ts`
+- [ ] Detect: "that didn't work", "use X instead", error messages
+- [ ] Store failures with `tool_state` (error output)
+
+### Task 3.4: Tests
+- [ ] Test failure detection in `tests/handlers/correction-detector.test.ts`
+- [ ] Test failure extraction in `tests/handlers/background-review.test.ts`
+
+---
+
+## Epic 4: Failure Injection
+
+### Task 4.1: Update System Prompt Injection
+- [ ] Update `src/index.ts` — add failure memory block
+- [ ] Separate `<memory-context>` block for failures
+- [ ] Only inject recent (7 days) and relevant (project match)
+- [ ] Max 5 failure entries
+
+### Task 4.2: Failure Injection Format
+- [ ] Format:
+  ```
+  RECENT FAILURES & LESSONS (learn from these):
+  • [failure] Tried: X — Failed: Y → Corrected to: Z
+  • [correction] Use X, not Y (corrected N days ago)
+  • [insight] Learned: X
+  ```
+
+### Task 4.3: Tests
+- [ ] Test failure injection in `tests/handlers/system-prompt.test.ts`
+- [ ] Test: only recent failures injected
+- [ ] Test: max 5 entries enforced
+
+---
+
+## Epic 5: Search with Categories
+
+### Task 5.1: Update Memory Search Tool
+- [ ] Update `src/tools/memory-search-tool.ts`
+- [ ] Add `category` parameter using `StringEnum`
+- [ ] Categories: `failure`, `correction`, `insight`, `preference`, `convention`, `tool-quirk`
+
+### Task 5.2: Update Search Implementation
+- [ ] Update `src/store/sqlite-memory-store.ts` — `searchMemories()`
+- [ ] Filter by category when provided
+- [ ] Include category in search results
+
+### Task 5.3: Tests
+- [ ] Test category search in `tests/store/sqlite-memory-store.test.ts`
+- [ ] Test: `memory_search("auth", category: "failure")` returns failures only
+
+---
+
+## Epic 6: Integration & Polish
+
+### Task 6.1: Wire Everything Together
+- [ ] Update `src/index.ts` — ensure all components work together
+- [ ] Test end-to-end flow: detect → store → inject → search
+
+### Task 6.2: Update README
+- [ ] Add "Learning from Failures" section
+- [ ] Document categories and how they work
+- [ ] Add examples of failure memory
+
+### Task 6.3: Version Bump
+- [ ] Bump to `0.5.5`
+- [ ] Run full test suite
+- [ ] Publish to npm
+
+---
+
+## Summary
+
+| Epic | Files Changed | Tests |
+|---|---|---|
+| 1. Category Types | types.ts, schema.ts | 2 |
+| 2. Failure Store | memory-store.ts, sqlite-memory-store.ts | 6 |
+| 3. Failure Detection | correction-detector.ts, background-review.ts, constants.ts | 4 |
+| 4. Failure Injection | index.ts | 3 |
+| 5. Category Search | memory-search-tool.ts, sqlite-memory-store.ts | 3 |
+| 6. Integration | index.ts, README.md | — |
+| **Total** | **8 files** | **~18 tests** |
+
+## Implementation Order
+
+```
+Epic 1 (Types) → Epic 2 (Store) → Epic 3 (Detection) → Epic 4 (Injection) → Epic 5 (Search) → Epic 6 (Polish)
+```
+
+Each epic builds on the previous one. Epics 3-5 can be done in parallel after Epic 2.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-hermes-memory",
-  "version": "0.5.4",
+  "version": "0.6.1",
   "description": "🧠 Persistent memory + 🔍 session search + 🛡️ secret scanning for Pi. SQLite FTS5 search across every conversation, auto-consolidation, memory aging, procedural skills. 272 tests. Ported from Hermes agent.",
   "type": "module",
   "main": "src/index.ts",

package/src/constants.ts

@@ -45,10 +45,19 @@ THREE TARGETS:
 ACTIONS: add (new entry), replace (update existing -- old_text identifies it), remove (delete -- old_text identifies it).`;
 
 // ─── Background review prompt (ported from _COMBINED_REVIEW_PROMPT in run_agent.py ~L2855) ───
-export const COMBINED_REVIEW_PROMPT = `Review the conversation above and consider two things:
+export const COMBINED_REVIEW_PROMPT = `Review the conversation above and consider these aspects:
 
 **Memory**: Has the user revealed things about themselves — their persona, desires, preferences, or personal details? Has the user expressed expectations about how you should behave, their work style, or ways they want you to operate? If so, save using the memory tool.
 
+**Failures & Corrections**: Did anything fail or go wrong? Extract these as failure memories:
+- [failure] What was tried but didn't work? (e.g., "Used localStorage for tokens — XSS vulnerability")
+- [correction] Did the user correct you? (e.g., "Use pnpm, not npm")
+- [insight] What was learned from the experience?
+- [convention] Any project conventions discovered?
+- [tool-quirk] Any tool-specific knowledge gained?
+
+For failures, include: what was tried, why it failed, what error occurred, and what worked instead.
+
 **Skills**: Was a complex, non-trivial approach used to complete a task — one that required trial and error, multiple tool calls, or changing course? If so, save a reusable procedure using the skill tool with action 'create'. Include: when to use it, step-by-step procedure, pitfalls to avoid, and how to verify success. If a related skill already exists, use action 'patch' to update it instead of creating a duplicate.
 
 Only act if there's something genuinely worth saving. If nothing stands out, just say 'Nothing to save.' and stop.`;

package/src/handlers/auto-consolidate.ts

@@ -15,7 +15,7 @@ import type { ConsolidationResult } from "../types.js";
 export async function triggerConsolidation(
   pi: ExtensionAPI,
   store: MemoryStore,
-  target: "memory" | "user",
+  target: "memory" | "user" | "failure",
   signal?: AbortSignal,
 ): Promise<ConsolidationResult> {
   const entries =

package/src/handlers/background-review.ts

@@ -111,7 +111,7 @@ export function setupBackgroundReview(
 
       const result = await pi.exec("pi", ["-p", "--no-session", reviewPrompt.join("\n")], {
         signal: ctx.signal,
-        timeout: 60000,
+        timeout: 120000,
       });
 
       if (result.code === 0 && result.stdout) {

package/src/handlers/correction-detector.ts

@@ -20,6 +20,19 @@ import {
 import type { MemoryConfig } from "../types.js";
 import { getMessageText } from "../types.js";
 
+/**
+ * Extract the directive part from a correction message.
+ * E.g., "no, use pnpm instead" -> "use pnpm instead"
+ */
+function extractCorrectionDirective(text: string): string {
+  // Remove common correction starters
+  const cleaned = text
+    .replace(/^(no|wrong|actually|stop|don'?t|that'?s not|I said|I told you)[,\.\s!]+/i, '')
+    .replace(/^(please\s+)?/i, '')
+    .trim();
+  return cleaned || text;
+}
+
 /**
  * Check if a user message is a correction using the two-pass filter.
  * Returns true if the message should trigger an immediate save.
@@ -147,6 +160,22 @@ export function setupCorrectionDetector(
           ctx.ui.notify("🔧 Correction detected — memory updated", "info");
         }
       }
+
+      // Also save as a failure memory for learning
+      try {
+        const lastUserMsg = recentParts.find(p => p.startsWith("[USER]"));
+        const correctionText = lastUserMsg ? lastUserMsg.replace(/^\[USER\]:\s*/, "") : "";
+        if (correctionText) {
+          const directive = extractCorrectionDirective(correctionText);
+          await store.addFailure(directive, {
+            category: "correction",
+            failureReason: "User corrected the agent",
+            project: projectStore ? "project" : undefined,
+          });
+        }
+      } catch {
+        // Best-effort — don't block the session
+      }
     } catch {
       // Best-effort — don't block the session
     } finally {

package/src/store/memory-store.ts

@@ -22,13 +22,14 @@ import {
   MEMORY_FILE,
   USER_FILE,
 } from "../constants.js";
-import type { MemoryConfig, MemoryResult, MemorySnapshot, ConsolidationResult } from "../types.js";
+import type { MemoryConfig, MemoryResult, MemorySnapshot, ConsolidationResult, MemoryCategory } from "../types.js";
 
 export class MemoryStore {
   private memoryEntries: string[] = [];
   private userEntries: string[] = [];
+  private failureEntries: string[] = [];
   private snapshot: MemorySnapshot = { memory: "", user: "" };
-  private consolidator: ((target: "memory" | "user", signal?: AbortSignal) => Promise<ConsolidationResult>) | null = null;
+  private consolidator: ((target: "memory" | "user" | "failure", signal?: AbortSignal) => Promise<ConsolidationResult>) | null = null;
 
   constructor(private config: MemoryConfig) {}
 
@@ -36,7 +37,7 @@ export class MemoryStore {
    * Inject a consolidation function (avoids circular imports).
    * Called from index.ts after both store and pi are available.
    */
-  setConsolidator(fn: (target: "memory" | "user", signal?: AbortSignal) => Promise<ConsolidationResult>): void {
+  setConsolidator(fn: (target: "memory" | "user" | "failure", signal?: AbortSignal) => Promise<ConsolidationResult>): void {
     this.consolidator = fn;
   }
 
@@ -46,24 +47,30 @@ export class MemoryStore {
     return this.config.memoryDir ?? path.join(os.homedir(), ".pi", "agent", "memory");
   }
 
-  private pathFor(target: "memory" | "user"): string {
-    return path.join(this.memoryDir, target === "user" ? USER_FILE : MEMORY_FILE);
+  private pathFor(target: "memory" | "user" | "failure"): string {
+    if (target === "user") return path.join(this.memoryDir, USER_FILE);
+    if (target === "failure") return path.join(this.memoryDir, "failures.md");
+    return path.join(this.memoryDir, MEMORY_FILE);
   }
 
-  private entriesFor(target: "memory" | "user"): string[] {
-    return target === "user" ? this.userEntries : this.memoryEntries;
+  private entriesFor(target: "memory" | "user" | "failure"): string[] {
+    if (target === "user") return this.userEntries;
+    if (target === "failure") return this.failureEntries;
+    return this.memoryEntries;
   }
 
-  private setEntries(target: "memory" | "user", entries: string[]): void {
+  private setEntries(target: "memory" | "user" | "failure", entries: string[]): void {
     if (target === "user") this.userEntries = entries;
+    else if (target === "failure") this.failureEntries = entries;
     else this.memoryEntries = entries;
   }
 
-  private charLimit(target: "memory" | "user"): number {
+  private charLimit(target: "memory" | "user" | "failure"): number {
+    if (target === "failure") return this.config.memoryCharLimit * 2; // Failures get more space
     return target === "user" ? this.config.userCharLimit : this.config.memoryCharLimit;
   }
 
-  private charCount(target: "memory" | "user"): number {
+  private charCount(target: "memory" | "user" | "failure"): number {
     const entries = this.entriesFor(target);
     return entries.length ? entries.join(ENTRY_DELIMITER).length : 0;
   }
@@ -74,10 +81,12 @@ export class MemoryStore {
     await fs.mkdir(this.memoryDir, { recursive: true });
     this.memoryEntries = await this.readFile(this.pathFor("memory"));
     this.userEntries = await this.readFile(this.pathFor("user"));
+    this.failureEntries = await this.readFile(this.pathFor("failure"));
 
     // Deduplicate preserving order
     this.memoryEntries = [...new Set(this.memoryEntries)];
     this.userEntries = [...new Set(this.userEntries)];
+    this.failureEntries = [...new Set(this.failureEntries)];
 
     // Capture frozen snapshot for system prompt injection
     // Strip metadata comments — the LLM doesn't need to see timestamps
@@ -91,11 +100,59 @@ export class MemoryStore {
 
   // ─── CRUD ───
 
-  async add(target: "memory" | "user", content: string, signal?: AbortSignal): Promise<MemoryResult> {
+  async add(target: "memory" | "user" | "failure", content: string, signal?: AbortSignal): Promise<MemoryResult> {
     return this._add(target, content, signal);
   }
 
-  private async _add(target: "memory" | "user", content: string, signal?: AbortSignal, _retriesLeft = 1): Promise<MemoryResult> {
+  async addFailure(content: string, options: {
+    category: MemoryCategory;
+    failureReason?: string;
+    toolState?: string;
+    correctedTo?: string;
+    project?: string;
+  }): Promise<MemoryResult> {
+    content = content.trim();
+    if (!content) return { success: false, error: "Content cannot be empty." };
+
+    const scanError = scanContent(content);
+    if (scanError) return { success: false, error: scanError };
+
+    const categoryTag = "[" + options.category + "]";
+    const parts = [categoryTag + " " + content];
+    if (options.failureReason) parts.push("Failed: " + options.failureReason);
+    if (options.toolState) parts.push("Tool state: " + options.toolState);
+    if (options.correctedTo) parts.push("Corrected to: " + options.correctedTo);
+    if (options.project) parts.push("Project: " + options.project);
+
+    const failureText = parts.join(" — ");
+    const today = new Date().toISOString().split("T")[0];
+    const encoded = this.encodeEntry(failureText, today, today);
+
+    this.failureEntries.push(encoded);
+    await this.saveToDisk("failure");
+
+    return {
+      success: true,
+      target: "failure",
+      message: "Failure memory saved: " + options.category,
+      entry_count: this.failureEntries.length,
+    };
+  }
+
+  getFailureEntries(maxAgeDays = 7): string[] {
+    const cutoff = new Date();
+    cutoff.setDate(cutoff.getDate() - maxAgeDays);
+    const cutoffStr = cutoff.toISOString().split("T")[0];
+
+    return this.failureEntries
+      .filter((entry) => {
+        const decoded = this.decodeEntry(entry);
+        return decoded.created >= cutoffStr;
+      })
+      .map((entry) => this.stripMetadata(entry));
+  }
+
+  private async _add(target: "memory" | "user" | "failure", content: string, signal?: AbortSignal, _retriesLeft = 1): Promise<MemoryResult> {
     content = content.trim();
     if (!content) return { success: false, error: "Content cannot be empty." };
 
@@ -145,7 +202,7 @@ export class MemoryStore {
     return this.successResponse(target, "Entry added.");
   }
 
-  async replace(target: "memory" | "user", oldText: string, newContent: string): Promise<MemoryResult> {
+  async replace(target: "memory" | "user" | "failure", oldText: string, newContent: string): Promise<MemoryResult> {
     oldText = oldText.trim();
     newContent = newContent.trim();
     if (!oldText) return { success: false, error: "old_text cannot be empty." };
@@ -191,7 +248,7 @@ export class MemoryStore {
     return this.successResponse(target, "Entry replaced.");
   }
 
-  async remove(target: "memory" | "user", oldText: string): Promise<MemoryResult> {
+  async remove(target: "memory" | "user" | "failure", oldText: string): Promise<MemoryResult> {
     oldText = oldText.trim();
     if (!oldText) return { success: false, error: "old_text cannot be empty." };
 
@@ -221,6 +278,16 @@ export class MemoryStore {
     const parts: string[] = [];
     if (this.snapshot.memory) parts.push(this.fenceBlock(this.snapshot.memory));
     if (this.snapshot.user) parts.push(this.fenceBlock(this.snapshot.user));
+
+    // Add recent failure memories
+    const recentFailures = this.getFailureEntries(7);
+    if (recentFailures.length > 0) {
+      const maxFailures = 5;
+      const failures = recentFailures.slice(0, maxFailures);
+      const failureBlock = this.renderFailureBlock(failures);
+      parts.push(this.fenceBlock(failureBlock));
+    }
+
     return parts.join("\n\n");
   }
 
@@ -270,7 +337,7 @@ export class MemoryStore {
     return this.decodeEntry(text).text;
   }
 
-  private successResponse(target: "memory" | "user", message?: string): MemoryResult {
+  private successResponse(target: "memory" | "user" | "failure", message?: string): MemoryResult {
     const entries = this.entriesFor(target);
     const current = this.charCount(target);
     const limit = this.charLimit(target);
@@ -333,6 +400,13 @@ export class MemoryStore {
     return `${separator}\n${header}\n${separator}\n${content}`;
   }
 
+  private renderFailureBlock(entries: string[]): string {
+    if (!entries.length) return "";
+    const header = "RECENT FAILURES & LESSONS (learn from these):";
+    const bulletList = entries.map((e) => "• " + e).join("\n");
+    return `${header}\n${bulletList}`;
+  }
+
   private async readFile(filePath: string): Promise<string[]> {
     try {
       const raw = await fs.readFile(filePath, "utf-8");
@@ -344,7 +418,7 @@ export class MemoryStore {
   }
 
   /** Atomic write: temp file + fs.rename() — same crash-safety as Hermes. */
-  private async saveToDisk(target: "memory" | "user"): Promise<void> {
+  private async saveToDisk(target: "memory" | "user" | "failure"): Promise<void> {
     const filePath = this.pathFor(target);
     const entries = this.entriesFor(target);
     const content = entries.length ? entries.join(ENTRY_DELIMITER) : "";

package/src/store/schema.ts

@@ -56,8 +56,12 @@ export const SCHEMA_SQL = `
   CREATE TABLE IF NOT EXISTS memories (
     id INTEGER PRIMARY KEY AUTOINCREMENT,
     project TEXT,
-    target TEXT NOT NULL CHECK (target IN ('memory', 'user')),
+    target TEXT NOT NULL CHECK (target IN ('memory', 'user', 'failure')),
+    category TEXT CHECK (category IN ('failure', 'correction', 'insight', 'preference', 'convention', 'tool-quirk')),
     content TEXT NOT NULL,
+    failure_reason TEXT,
+    tool_state TEXT,
+    corrected_to TEXT,
     created DATE NOT NULL,
     last_referenced DATE NOT NULL
   );
@@ -89,6 +93,7 @@ export const SCHEMA_SQL = `
   CREATE INDEX IF NOT EXISTS idx_messages_timestamp ON messages(timestamp);
   CREATE INDEX IF NOT EXISTS idx_memories_project ON memories(project);
   CREATE INDEX IF NOT EXISTS idx_memories_target ON memories(target);
+  CREATE INDEX IF NOT EXISTS idx_memories_category ON memories(category);
   CREATE INDEX IF NOT EXISTS idx_sessions_project ON sessions(project);
   CREATE INDEX IF NOT EXISTS idx_sessions_started_at ON sessions(started_at);
 `;

package/src/store/sqlite-memory-store.ts

@@ -1,4 +1,5 @@
 import { DatabaseManager } from './db.js';
+import type { MemoryCategory } from '../types.js';
 
 /**
  * A memory entry stored in SQLite.
@@ -6,8 +7,12 @@ import { DatabaseManager } from './db.js';
 export interface SqliteMemoryEntry {
   id: number;
   project: string | null;
-  target: 'memory' | 'user';
+  target: 'memory' | 'user' | 'failure';
+  category: MemoryCategory | null;
   content: string;
+  failureReason: string | null;
+  toolState: string | null;
+  correctedTo: string | null;
   created: string;
   lastReferenced: string;
 }
@@ -18,22 +23,30 @@ export interface SqliteMemoryEntry {
 export function addMemory(
   dbManager: DatabaseManager,
   content: string,
-  target: 'memory' | 'user' = 'memory',
-  project: string | null = null
+  target: 'memory' | 'user' | 'failure' = 'memory',
+  project: string | null = null,
+  category: MemoryCategory | null = null,
+  failureReason: string | null = null,
+  toolState: string | null = null,
+  correctedTo: string | null = null
 ): SqliteMemoryEntry {
   const db = dbManager.getDb();
   const today = new Date().toISOString().split('T')[0];
 
   const result = db.prepare(`
-    INSERT INTO memories (project, target, content, created, last_referenced)
-    VALUES (?, ?, ?, ?, ?)
-  `).run(project, target, content, today, today);
+    INSERT INTO memories (project, target, category, content, failure_reason, tool_state, corrected_to, created, last_referenced)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(project, target, category, content, failureReason, toolState, correctedTo, today, today);
 
   return {
     id: Number(result.lastInsertRowid),
     project,
     target,
+    category,
     content,
+    failureReason,
+    toolState,
+    correctedTo,
     created: today,
     lastReferenced: today,
   };
@@ -58,10 +71,10 @@ function escapeFts5Query(query: string): string {
 export function searchMemories(
   dbManager: DatabaseManager,
   query: string,
-  options: { project?: string; target?: string; limit?: number } = {}
+  options: { project?: string; target?: string; category?: MemoryCategory; limit?: number } = {}
 ): SqliteMemoryEntry[] {
   const db = dbManager.getDb();
-  const { project, target, limit = 10 } = options;
+  const { project, target, category, limit = 10 } = options;
 
   const conditions: string[] = [];
   const params: unknown[] = [];
@@ -84,10 +97,15 @@ export function searchMemories(
     params.push(target);
   }
 
+  if (category) {
+    conditions.push('m.category = ?');
+    params.push(category);
+  }
+
   const whereClause = conditions.length > 0 ? `WHERE ${conditions.join(' AND ')}` : '';
 
   const sql = `
-    SELECT id, project, target, content, created, last_referenced
+    SELECT id, project, target, category, content, failure_reason, tool_state, corrected_to, created, last_referenced
     FROM memories m
     ${whereClause}
     ORDER BY m.last_referenced DESC
@@ -99,7 +117,11 @@ export function searchMemories(
     id: number;
     project: string | null;
     target: string;
+    category: string | null;
     content: string;
+    failure_reason: string | null;
+    tool_state: string | null;
+    corrected_to: string | null;
     created: string;
     last_referenced: string;
   }>;
@@ -107,8 +129,12 @@ export function searchMemories(
   return rows.map(row => ({
     id: row.id,
     project: row.project,
-    target: row.target as 'memory' | 'user',
+    target: row.target as 'memory' | 'user' | 'failure',
+    category: row.category as MemoryCategory | null,
     content: row.content,
+    failureReason: row.failure_reason,
+    toolState: row.tool_state,
+    correctedTo: row.corrected_to,
     created: row.created,
     lastReferenced: row.last_referenced,
   }));
@@ -119,10 +145,10 @@ export function searchMemories(
  */
 export function getMemories(
   dbManager: DatabaseManager,
-  options: { project?: string | null; target?: string } = {}
+  options: { project?: string | null; target?: string; category?: MemoryCategory } = {}
 ): SqliteMemoryEntry[] {
   const db = dbManager.getDb();
-  const { project, target } = options;
+  const { project, target, category } = options;
 
   const conditions: string[] = [];
   const params: unknown[] = [];
@@ -141,10 +167,15 @@ export function getMemories(
     params.push(target);
   }
 
+  if (category) {
+    conditions.push('category = ?');
+    params.push(category);
+  }
+
   const whereClause = conditions.length > 0 ? `WHERE ${conditions.join(' AND ')}` : '';
 
   const rows = db.prepare(`
-    SELECT id, project, target, content, created, last_referenced
+    SELECT id, project, target, category, content, failure_reason, tool_state, corrected_to, created, last_referenced
     FROM memories
     ${whereClause}
     ORDER BY last_referenced DESC
@@ -152,7 +183,11 @@ export function getMemories(
     id: number;
     project: string | null;
     target: string;
+    category: string | null;
     content: string;
+    failure_reason: string | null;
+    tool_state: string | null;
+    corrected_to: string | null;
     created: string;
     last_referenced: string;
   }>;
@@ -160,8 +195,12 @@ export function getMemories(
   return rows.map(row => ({
     id: row.id,
     project: row.project,
-    target: row.target as 'memory' | 'user',
+    target: row.target as 'memory' | 'user' | 'failure',
+    category: row.category as MemoryCategory | null,
     content: row.content,
+    failureReason: row.failure_reason,
+    toolState: row.tool_state,
+    correctedTo: row.corrected_to,
     created: row.created,
     lastReferenced: row.last_referenced,
   }));
@@ -176,6 +215,64 @@ export function removeMemory(dbManager: DatabaseManager, id: number): boolean {
   return result.changes > 0;
 }
 
+/**
+ * Get recent failure memories (last N days).
+ */
+export function getRecentFailures(
+  dbManager: DatabaseManager,
+  maxAgeDays = 7,
+  project?: string | null
+): SqliteMemoryEntry[] {
+  const db = dbManager.getDb();
+  const cutoff = new Date();
+  cutoff.setDate(cutoff.getDate() - maxAgeDays);
+  const cutoffStr = cutoff.toISOString().split('T')[0];
+
+  const conditions: string[] = ['target = ?', 'created >= ?'];
+  const params: unknown[] = ['failure', cutoffStr];
+
+  if (project !== undefined) {
+    if (project === null) {
+      conditions.push('project IS NULL');
+    } else {
+      conditions.push('(project = ? OR project IS NULL)');
+      params.push(project);
+    }
+  }
+
+  const rows = db.prepare(`
+    SELECT id, project, target, category, content, failure_reason, tool_state, corrected_to, created, last_referenced
+    FROM memories
+    WHERE ${conditions.join(' AND ')}
+    ORDER BY created DESC
+    LIMIT 5
+  `).all(...params) as Array<{
+    id: number;
+    project: string | null;
+    target: string;
+    category: string | null;
+    content: string;
+    failure_reason: string | null;
+    tool_state: string | null;
+    corrected_to: string | null;
+    created: string;
+    last_referenced: string;
+  }>;
+
+  return rows.map(row => ({
+    id: row.id,
+    project: row.project,
+    target: row.target as 'memory' | 'user' | 'failure',
+    category: row.category as MemoryCategory | null,
+    content: row.content,
+    failureReason: row.failure_reason,
+    toolState: row.tool_state,
+    correctedTo: row.corrected_to,
+    created: row.created,
+    lastReferenced: row.last_referenced,
+  }));
+}
+
 /**
  * Update a memory's last_referenced date.
  */

package/src/tools/memory-search-tool.ts

@@ -3,6 +3,7 @@ import { Type } from "typebox";
 import { StringEnum } from "@mariozechner/pi-ai";
 import { DatabaseManager } from '../store/db.js';
 import { searchMemories, getMemoryStats } from '../store/sqlite-memory-store.js';
+import type { MemoryCategory } from '../types.js';
 
 interface SearchResult {
   success: boolean;
@@ -21,23 +22,27 @@ Use cases:
 - Find memories about a specific topic: "What do I know about auth setup?"
 - Search project-specific memories: "What conventions does project X follow?"
 - Find user preferences: "What are the user's testing preferences?"
+- Search for past failures: "memory_search('auth', category='failure')"
 
 Returns matching memory entries with project context and dates.`,
     promptSnippet: 'Search extended memory store (unlimited capacity)',
     promptGuidelines: [
       'Use memory_search when you need context beyond what is in the system prompt.',
       'Use memory_search to find project-specific memories or user preferences.',
+      'Use memory_search with category filter to find specific types of memories (failure, correction, insight, etc.).',
     ],
     parameters: Type.Object({
       query: Type.String({ description: 'Search query. Use natural language or specific terms.' }),
       project: Type.Optional(Type.String({ description: 'Filter by project name. Pass null for global memories only.' })),
-      target: Type.Optional(StringEnum(['memory', 'user'] as const, { description: 'Filter by target type (memory or user).' })),
+      target: Type.Optional(StringEnum(['memory', 'user', 'failure'] as const, { description: 'Filter by target type (memory, user, or failure).' })),
+      category: Type.Optional(StringEnum(['failure', 'correction', 'insight', 'preference', 'convention', 'tool-quirk'] as const, { description: 'Filter by memory category.' })),
       limit: Type.Optional(Type.Number({ description: 'Maximum results to return (default: 10, max: 20).' })),
     }),
-    execute: async (_id: string, args: { query: string; project?: string; target?: string; limit?: number }) => {
+    execute: async (_id: string, args: { query: string; project?: string; target?: string; category?: string; limit?: number }) => {
       const query = args.query;
       const project = args.project;
       const target = args.target;
+      const category = args.category as MemoryCategory | undefined;
       const limit = Math.min(args.limit || 10, 20);
 
       if (!query || query.trim().length === 0) {
@@ -51,7 +56,7 @@ Returns matching memory entries with project context and dates.`,
         return { content: [{ type: 'text' as const, text: result.message! }], details: result };
       }
 
-      const results = searchMemories(dbManager, query, { project, target, limit });
+      const results = searchMemories(dbManager, query, { project, target, category, limit });
 
       if (results.length === 0) {
         const result: SearchResult = { success: true, count: 0, message: `No memories found matching "${query}". Try a different search term or broader query.` };
@@ -62,8 +67,9 @@ Returns matching memory entries with project context and dates.`,
 
       for (const entry of results) {
         const projectLabel = entry.project ? `[${entry.project}]` : '[global]';
-        const targetLabel = entry.target === 'user' ? '👤' : '🧠';
-        output += `${targetLabel} ${projectLabel} ${entry.content}\n`;
+        const targetLabel = entry.target === 'user' ? '👤' : entry.target === 'failure' ? '⚠️' : '🧠';
+        const categoryLabel = entry.category ? ` [${entry.category}]` : '';
+        output += `${targetLabel} ${projectLabel}${categoryLabel} ${entry.content}\n`;
         output += `   Created: ${entry.created} | Last used: ${entry.lastReferenced}\n\n`;
       }
 

package/src/tools/memory-tool.ts

@@ -9,6 +9,7 @@ import { Type } from "typebox";
 import { StringEnum } from "@mariozechner/pi-ai";
 import { MemoryStore } from "../store/memory-store.js";
 import { MEMORY_TOOL_DESCRIPTION } from "../constants.js";
+import type { MemoryCategory } from "../types.js";
 
 export function registerMemoryTool(pi: ExtensionAPI, store: MemoryStore, projectStore: MemoryStore | null): void {
   pi.registerTool({
@@ -21,10 +22,11 @@ export function registerMemoryTool(pi: ExtensionAPI, store: MemoryStore, project
       "Use the memory tool proactively when the user corrects you, shares a preference, or reveals personal details worth remembering.",
       "Use the memory tool when you discover environment facts, project conventions, or reusable patterns useful in future sessions.",
       "Do NOT use memory for temporary task state, TODO items, or session progress — only for durable, cross-session facts.",
+      "Use target='failure' with category to save what didn't work (failures, corrections, insights).",
     ],
     parameters: Type.Object({
       action: StringEnum(["add", "replace", "remove"] as const),
-      target: StringEnum(["memory", "user", "project"] as const),
+      target: StringEnum(["memory", "user", "project", "failure"] as const),
       content: Type.Optional(
         Type.String({ description: "Entry content for add/replace" })
       ),
@@ -34,12 +36,20 @@ export function registerMemoryTool(pi: ExtensionAPI, store: MemoryStore, project
             "Substring identifying entry for replace/remove",
         })
       ),
+      category: Type.Optional(
+        StringEnum(["failure", "correction", "insight", "preference", "convention", "tool-quirk"] as const, {
+          description: "Category for failure memories",
+        })
+      ),
+      failure_reason: Type.Optional(
+        Type.String({ description: "Why it failed (for failure category)" })
+      ),
     }),
     async execute(toolCallId, params, signal, onUpdate, ctx) {
-      const { action, target: rawTarget, content, old_text } = params;
+      const { action, target: rawTarget, content, old_text, category, failure_reason } = params;
 
       // Route 'project' to projectStore (internal target 'memory')
-      const target = rawTarget as "memory" | "user";
+      const target = rawTarget as "memory" | "user" | "failure";
       const activeStore = rawTarget === "project" ? projectStore : store;
 
       if (rawTarget === "project" && !projectStore) {
@@ -69,7 +79,16 @@ export function registerMemoryTool(pi: ExtensionAPI, store: MemoryStore, project
               details: {},
             };
           }
-          result = await store_.add(target, content);
+          // Handle failure target with category
+          if (rawTarget === "failure") {
+            const memoryCategory = (category || "failure") as MemoryCategory;
+            result = await store_.addFailure(content, {
+              category: memoryCategory,
+              failureReason: failure_reason,
+            });
+          } else {
+            result = await store_.add(target, content);
+          }
           break;
 
         case "replace":

package/src/types.ts

@@ -35,11 +35,19 @@ export interface MemoryConfig {
   sessionRetentionDays?: number;
 }
 
+export type MemoryCategory =
+  | "failure"
+  | "correction"
+  | "insight"
+  | "preference"
+  | "convention"
+  | "tool-quirk";
+
 export interface MemoryResult {
   success: boolean;
   error?: string;
   message?: string;
-  target?: "memory" | "user";
+  target?: "memory" | "user" | "failure";
   entries?: string[];
   usage?: string;
   entry_count?: number;