pi-hermes-memory 0.1.0 → 0.2.0

package/docs/ROADMAP.md

@@ -14,122 +14,204 @@
 - 119 automated tests, 0 type errors
 - Atomic writes (temp + rename)
 
-## Architecture Evolution
+---
 
-```mermaid
-graph TB
-    subgraph "v0.1.0 — Current"
-        T1["memory tool<br/>(add / replace / remove)"]
-        SC["Content Scanner<br/>(injection · exfiltration · unicode)"]
-        MD["Markdown Backend<br/>MEMORY.md · USER.md"]
-        FS["Frozen Snapshot<br/>(system prompt injection)"]
-        BL["Background Review<br/>(pi.exec child process)"]
-        SF["Session Flush<br/>(compact · shutdown)"]
-        IC["/memory-insights<br/>(command)"]
-        CF["Config File<br/>(hermes-memory-config.json)"]
-    end
+## Hermes Agent Competitive Analysis
 
-    T1 --> SC --> MD
-    BL --> MD
-    SF --> MD
-    MD --> FS
-
-    style T1 fill:#e94560,stroke:#fff,color:#fff
-    style SC fill:#ff6600,stroke:#fff,color:#fff
-    style MD fill:#0f3460,stroke:#fff,color:#fff
-    style FS fill:#16213e,stroke:#fff,color:#fff
-    style BL fill:#16213e,stroke:#fff,color:#fff
-    style SF fill:#16213e,stroke:#fff,color:#fff
-    style IC fill:#16213e,stroke:#fff,color:#fff
-    style CF fill:#16213e,stroke:#fff,color:#fff
-```
+> Research conducted 2026-04-26. Sources: [hermes-agent.ai](https://hermes-agent.ai/blog/hermes-agent-memory-system), [GitHub README](https://github.com/NousResearch/Hermes-Agent), [official docs](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory), [skills docs](https://hermes-agent.nousresearch.com/docs/user-guide/features/skills).
+
+### Hermes 3-Layer Memory Architecture
+
+Hermes has three memory subsystems operating at different timescales:
+
+| Layer | What | Capacity | Token Cost |
+|---|---|---|---|
+| **L1: Persistent Memory** (MEMORY.md + USER.md) | Curated facts, frozen snapshot injection | ~1,300 tokens total | Fixed per session |
+| **L2: Episodic Memory** (Skills System) | Procedural memory — SKILL.md files created from experience, progressive disclosure | Unlimited | ~3K tokens for index, full content on demand |
+| **L3: Session Search** (SQLite FTS5) | Full-text search over ALL conversations | Unlimited | On-demand only |
+
+Plus **L4: External Providers** — Honcho, Mem0, Hindsight, etc. for deeper user modeling.
+
+### Gap Analysis: Hermes vs. Our v0.1
+
+| Capability | Hermes | Our v0.1 | Priority |
+|---|---|---|---|
+| L1: Persistent Memory (MEMORY.md + USER.md) | ✅ | ✅ **Covered** | — |
+| Frozen snapshot + prefix cache preservation | ✅ | ✅ **Covered** | — |
+| Content scanning (injection, exfil, unicode) | ✅ | ✅ **Covered** | — |
+| Background learning loop (periodic nudge) | ✅ | ✅ **Covered** | — |
+| Session flush (compact + shutdown) | ✅ | ✅ **Covered** | — |
+| **L2: Skills / Procedural Memory** | ✅ Auto-created after complex tasks, progressive disclosure, SKILL.md format | ❌ **MISSING** — our COMBINED_REVIEW_PROMPT already asks about skills but there's no skill tool | 🔴 **Critical** |
+| **L3: Session Search** | ✅ SQLite FTS5 over all conversations, on-demand retrieval + summarization | ❌ **MISSING** — no cross-session recall at all | 🔴 **Critical** |
+| **Auto-consolidation when memory full** | ✅ Agent merges/removes entries automatically | ❌ Returns error "Replace or remove existing entries" | 🟡 **High** |
+| **Correction-triggered memory save** | ✅ Detects user corrections for immediate save | ❌ Only saves on nudge interval (every 10 turns) | 🟡 **High** |
+| **Tool-call-aware nudge** | ✅ Self-evaluation every 15 tool calls | ❌ Only turn-count based | 🟡 **Medium** |
+| **Progressive disclosure** | ✅ 3-level loading (index → full → references) | ❌ Not applicable (no skills yet) | 🟡 **Depends on Skills** |
+| **Memory aging / staleness tracking** | ✅ Consolidation removes superseded entries | ❌ Entries live forever until manually removed | 🟠 **Medium** |
+| **Context fencing** (memory-context XML tags) | ✅ Prevents prompt injection through stored memories | ❌ Raw injection | 🟠 **Medium** |
+| **External providers** (Honcho, Mem0, etc.) | ✅ 8+ external provider plugins | ⏳ Planned for v0.4 | 🟢 **Deferred** |
+| **Skills Hub / Community skills** | ✅ agentskills.io, search, install, audit | ❌ Not applicable (Pi has its own skill system) | ⚪ **N/A** |
+| **Cross-platform messaging** | ✅ Telegram, Discord, Slack, WhatsApp, Signal | ❌ Not applicable (Pi extension, not standalone agent) | ⚪ **N/A** |
+
+### Key Painpoints Hermes Solves That We Must Address
+
+1. **"Goldfish memory"** — Every session starts from zero, user re-explains preferences, stack, conventions. Our L1 solves this. ✅
+
+2. **No procedural knowledge** — The agent forgets *how* it solved problems. After 60+ sessions, Hermes shows "anticipatory behavior" because it has skill documents from past experience. Our review prompt asks about skills but has nowhere to save them. 🔴
+
+3. **No cross-session recall** — "Did we discuss X last week?" is unanswerable. Hermes searches all past conversations via FTS5. We have zero session search. 🔴
+
+4. **Memory full = dead end** — When our memory hits capacity, we return an error and force the user/agent to manually fix it. Hermes auto-consolidates. 🟡
+
+5. **Missed corrections** — User says "no, don't do that" and the agent only saves it 8 turns later at the next nudge. Hermes detects corrections immediately. 🟡
+
+---
+
+## Revised Roadmap
+
+The roadmap is restructured based on the Hermes gap analysis. The biggest missing pieces are **Skills/Procedural Memory** and **Smart Curation** (auto-consolidation, correction detection). Session Search and External Providers stay in later phases.
 
 ```mermaid
-graph TB
-    subgraph "v0.2.0 — Structured Storage & Search"
-        T2["memory tool<br/>(add / replace / remove / search)"]
-        SC2["Content Scanner<br/>(v0.1.0 scanner unchanged)"]
-        SA["Search Abstraction<br/>(MemoryBackend interface)"]
-        SQL["SQLite Backend<br/>(FTS5 · key-value · confidence)"]
-        PI2["Context-Aware Injection<br/>(relevance-filtered)"]
-        PS["Project-Scoped Memory<br/>(keyed by cwd)"]
+graph LR
+    subgraph "v0.1 ✅"
+        A[L1: Persistent Memory]
+        B[Content Scanner]
+        C[Background Review]
+        D[Session Flush]
     end
 
-    T2 --> SC2 --> SA
-    SA --> SQL
-    SQL --> PI2
-    SQL --> PS
-
-    style T2 fill:#e94560,stroke:#fff,color:#fff
-    style SC2 fill:#ff6600,stroke:#fff,color:#fff
-    style SA fill:#1282a2,stroke:#fff,color:#fff
-    style SQL fill:#0f3460,stroke:#fff,color:#fff
-    style PI2 fill:#16213e,stroke:#fff,color:#fff
-    style PS fill:#16213e,stroke:#fff,color:#fff
-```
+    subgraph "v0.2 — Next"
+        E[Skill Tool]
+        F[Auto-Consolidation]
+        G[Correction Detection]
+        H[Tool-Call-Aware Nudge]
+    end
 
-```mermaid
-graph TB
-    subgraph "v0.3.0 — Pluggable Backend & External Memory"
-        T3["memory tool<br/>(add / replace / remove / search)"]
-        SC3["Content Scanner<br/>(unchanged — guards all backends)"]
-        SA3["Search Abstraction<br/>(MemoryBackend interface)"]
-        LOC["Local SQLite<br/>(default · offline)"]
-        M0["Mem0 Backend<br/>(vector search · cloud)"]
-        HON["Honcho Backend<br/>(dialectic reasoning · Hermes-native)"]
-        SEL["Selective Injection<br/>(search-relevant · project-scoped)"]
+    subgraph "v0.3"
+        I[Session Search]
+        J[Context Fencing]
+        K[Memory Aging]
     end
 
-    T3 --> SC3 --> SA3
-    SA3 --> LOC
-    SA3 --> M0
-    SA3 --> HON
-    LOC --> SEL
-    M0 --> SEL
-    HON --> SEL
-
-    style T3 fill:#e94560,stroke:#fff,color:#fff
-    style SC3 fill:#ff6600,stroke:#fff,color:#fff
-    style SA3 fill:#1282a2,stroke:#fff,color:#fff
-    style LOC fill:#0f3460,stroke:#fff,color:#fff
-    style M0 fill:#6b21a8,stroke:#fff,color:#fff
-    style HON fill:#6b21a8,stroke:#fff,color:#fff
-    style SEL fill:#16213e,stroke:#fff,color:#fff
-```
+    subgraph "v0.4"
+        L[MemoryBackend Interface]
+        M[SQLite Backend]
+        N[Project-Scoped Memory]
+    end
 
-```mermaid
-graph TB
-    subgraph "v1.0.0 — Production Memory Substrate"
-        T4["memory tool<br/>(add / replace / remove / search / consolidate)"]
-        SC4["Content Scanner<br/>(extensible rule system)"]
-        SA4["Pluggable Backend<br/>(local · Mem0 · Honcho · custom)"]
-        CON["Smart Consolidation<br/>(structured extraction · dedup)"]
-        MUL["Multi-Agent Memory<br/>(shared context · scoping)"]
-        OBS["Observability<br/>(memory stats · usage · audit log)"]
+    subgraph "v0.5"
+        O[ExternalSync Interface]
+        P[Mem0 / Honcho]
     end
 
-    T4 --> SC4 --> SA4
-    SA4 --> CON
-    SA4 --> MUL
-    CON --> OBS
-
-    style T4 fill:#e94560,stroke:#fff,color:#fff
-    style SC4 fill:#ff6600,stroke:#fff,color:#fff
-    style SA4 fill:#1282a2,stroke:#fff,color:#fff
-    style CON fill:#16213e,stroke:#fff,color:#fff
-    style MUL fill:#16213e,stroke:#fff,color:#fff
-    style OBS fill:#16213e,stroke:#fff,color:#fff
+    A --> E
+    C --> F
+    C --> G
+    C --> H
+    E --> I
+    F --> K
+    A --> J
+    K --> L
+    I --> N
+    L --> O
+    O --> P
 ```
 
 ---
 
-## v0.2.0 — Structured Storage & Search
+## v0.2.0 — Skills + Smart Curation
+
+**Goal**: Close the two biggest gaps from the Hermes analysis — procedural memory (skills) and intelligent memory management (auto-consolidation, correction detection, tool-call-aware nudges).
+
+**Why this before SQLite/Session Search**: Our `COMBINED_REVIEW_PROMPT` already asks the agent to save skills — but there's no skill tool. The review prompt is literally asking the agent to do something it can't do. Fixing this is the single highest-leverage change. Auto-consolidation and correction detection are small, high-impact additions to the existing curation system.
+
+### Epic 1: Skill Tool + Procedural Memory
+
+Hermes creates skills after complex tasks (5+ tool calls). Skills are SKILL.md files in `~/.hermes/skills/` with progressive disclosure. We adapt this for Pi's existing skill infrastructure at `~/.pi/agent/skills/`.
+
+**Key insight**: Pi already has a skill system. Our skill tool should write SKILL.md files that are compatible with Pi's skill discovery. This means our skills are immediately usable as Pi slash commands — no separate ecosystem needed.
+
+- [ ] `skill` tool — register via `pi.registerTool()` with actions: `create`, `patch`, `edit`, `delete`
+- [ ] Skill storage in `~/.pi/agent/memory/skills/` (not `~/.pi/agent/skills/` — avoid conflicting with user's own skills)
+- [ ] SKILL.md format — compatible with Pi's SKILL.md spec (frontmatter + markdown body)
+- [ ] Progressive disclosure — skill index (name + description only) injected into system prompt, full content loaded on demand via `skill_view` action
+- [ ] Auto-trigger after complex tasks — track tool calls per turn, trigger skill extraction at 5+ tool calls
+- [ ] Background skill review — extend `COMBINED_REVIEW_PROMPT` to actually call the `skill` tool (currently it asks about skills but can't save them)
+- [ ] Security — skill writes go through the same content scanner as memory writes
+- [ ] `/memory-skills` command — list all agent-created skills with usage stats
+
+**Reference**: Hermes `skill_manage` tool and `~/.hermes/skills/` directory structure. See [Hermes Skills docs](https://hermes-agent.nousresearch.com/docs/user-guide/features/skills).
+
+### Epic 2: Auto-Consolidation
+
+When Hermes memory hits capacity, it automatically merges related entries and removes superseded ones. Our extension currently returns an error. This fixes the "memory full" dead end.
+
+- [ ] When `add()` would exceed char limit, trigger auto-consolidation instead of returning error
+- [ ] Consolidation via `pi.exec()` — spawn a one-shot process with a consolidation prompt
+- [ ] Consolidation prompt — "Memory is at capacity. Merge related entries, remove outdated ones, keep the most important facts. Use the memory tool to make changes."
+- [ ] After consolidation, retry the original `add()`
+- [ ] Config: `autoConsolidate: boolean` (default: true)
+- [ ] `/memory-consolidate` command — manual consolidation trigger
+
+**Reference**: Hermes memory compression behavior described in [hermes-agent.ai memory blog](https://hermes-agent.ai/blog/hermes-agent-memory-system).
+
+### Epic 3: Correction Detection + Immediate Save
+
+Hermes detects user corrections and saves them immediately. Our extension only saves on the nudge interval (every 10 turns). User corrections are the most valuable memories — every missed correction is a repeated mistake.
+
+- [ ] Correction detector — scan user messages for patterns: "no,", "wrong,", "actually,", "don't do that", "stop", "not like that", "I said..."
+- [ ] On detection, trigger an immediate memory save prompt via `pi.exec()`
+- [ ] Config: `correctionDetection: boolean` (default: true)
+- [ ] Rate limit — max 1 correction save per 3 turns (avoid over-triggering on multi-turn corrections)
 
-**Goal**: Replace flat markdown with SQLite. Add search. Keep the same tool interface.
+**Reference**: Hermes correction patterns inferred from the `MEMORY_TOOL_DESCRIPTION` priority list: "User preferences and corrections > environment facts > procedural knowledge."
 
-### `MemoryBackend` Interface
+### Epic 4: Tool-Call-Aware Nudge
 
-The core abstraction that makes everything after this possible:
+Hermes runs a self-evaluation checkpoint every 15 tool calls. Our nudge is purely turn-count based. Complex tasks with many tool calls generate more valuable memories than simple conversations.
+
+- [ ] Track tool call count per turn (via `tool_end` event or similar)
+- [ ] Trigger background review when EITHER `nudgeInterval` turns OR `nudgeToolCalls` (default: 15) tool calls are reached
+- [ ] Weight the review prompt based on complexity — more tool calls = deeper review
+- [ ] Config: `nudgeToolCalls: number` (default: 15)
+
+**Reference**: Hermes self-evaluation checkpoint described in [hermes-agent.ai skills blog](https://hermes-agent.ai/blog/hermes-agent-memory-system): "Every 15 tool calls, Hermes runs a self-evaluation checkpoint."
+
+---
+
+## v0.3.0 — Session Search + Context Hardening
+
+**Goal**: Add cross-session recall (Hermes L3) and security hardening via context fencing.
+
+### Epic 5: Session Search
+
+Hermes stores all conversations in SQLite with FTS5 full-text search. When it needs past context, it searches + summarizes. This transforms the extension from "2 files of notes" to "infinite searchable memory."
+
+- [ ] Investigate Pi's `SessionManager` API for reading past session history
+- [ ] Session indexer — index past and current session conversations for full-text search
+- [ ] Storage: either a separate SQLite file (`~/.pi/agent/memory/sessions.db`) or leverage Pi's built-in session storage
+- [ ] `session_search` tool — agent can query past conversations on demand
+- [ ] Summarization via `pi.exec()` — summarize relevant session fragments to keep token cost manageable
+- [ ] Config: `sessionSearchEnabled: boolean` (default: true)
+- [ ] Config: `sessionRetentionDays: number` (default: 90)
+
+**Reference**: Hermes `~/.hermes/state.db` with FTS5 indexing. See [Hermes Session Search docs](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory#session-search).
+
+### Epic 6: Context Fencing + Memory Aging
+
+- [ ] `<memory-context>` XML tags wrapping the system prompt injection — prevents the model from treating recalled memory as user discourse
+- [ ] Memory aging — track last-referenced timestamp per entry, surface stale entries during consolidation
+- [ ] Entry metadata — add optional `last_referenced` and `created_at` fields (stored in comments, transparent to § delimiter)
+
+**Reference**: Hermes `MemoryManager.build_memory_context_block()` fencing with `<memory-context>` tags and "NOT new user input" system note.
+
+---
+
+## v0.4.0 — Structured Storage + Project Scoping
+
+**Goal**: Replace flat markdown with SQLite backend. Add search. Add project-scoped memory. Keep the same tool interface.
+
+### Core Abstraction
 
 ```typescript
 interface MemoryBackend {
@@ -150,6 +232,18 @@ interface MemoryBackend {
 
 Current `MemoryStore` becomes `MarkdownBackend` — the default, zero-dependency implementation. New `SQLiteBackend` adds structure without breaking anything.
 
+### Onboarding: `/memory-interview`
+
+New users install the extension and memory starts empty — the LLM has to learn preferences over many sessions through trial and error. The interview command solves this:
+
+```
+/memory-interview
+```
+
+The LLM asks 5-7 structured questions. Each answer is saved to `USER.md` via the existing content scanner. Users get immediate value on the very first session.
+
+Inspired by [Honcho's `/honcho:interview`](https://docs.honcho.dev/v3/guides/integrations/claude-code#the-interview) pattern.
+
 ### Deliverables
 
 - [ ] `MemoryBackend` interface in `src/types.ts`
@@ -159,7 +253,10 @@ Current `MemoryStore` becomes `MarkdownBackend` — the default, zero-dependency
 - [ ] Project-scoped memory — entries tagged with `cwd`, injected when matching
 - [ ] Context-aware injection — `formatForSystemPrompt(cwd, prompt)` filters by relevance
 - [ ] Config: `"backend": "markdown" | "sqlite"` (defaults to `markdown` for zero-dep install)
-- [ ] Migration tool: `markdown → sqlite` one-time import
+- [ ] Migration tool: markdown → sqlite one-time import
+- [ ] `/memory-interview` command — guided first-run interview that saves preferences to USER.md
+- [ ] Interview prompt in `src/constants.ts` — structured questions with save instructions
+- [ ] Content scanner validates interview answers (same as all writes)
 
 ### What Does NOT Change
 
@@ -170,38 +267,45 @@ Current `MemoryStore` becomes `MarkdownBackend` — the default, zero-dependency
 
 ---
 
-## v0.3.0 — Pluggable External Memory
+## v0.5.0 — External Sync
 
-**Goal**: Let users swap the backend to Mem0 or Honcho without changing anything else. The content scanner guards all data before it leaves the machine.
+**Goal**: Run a local backend (SQLite) as the source of truth, with optional external sync (Mem0 or Honcho) that mirrors writes and supplements search. Based on the [Hermes MemoryManager pattern](https://github.com/NousResearch/hermes-agent/blob/main/agent/memory_manager.py).
 
-### Why This Matters
-
-External memory services provide better semantic search, cross-session continuity, and multi-agent awareness. But they introduce trust boundaries — your agent's memories leave your machine. The content scanner becomes the security gate between Pi and any external service.
-
-### Deliverables
-
-- [ ] `Mem0Backend` — wraps Mem0's Node.js SDK (`add`, `search`, `update`, `delete`)
-- [ ] `HonchoBackend` — wraps Honcho's API (`honcho_context`, `honcho_search_conclusions`, `honcho_reasoning`)
-- [ ] Backend auto-detection — check for `MEM0_API_KEY` or `HONCHO_API_KEY` env vars, offer to configure
-- [ ] Config: `"backend": "sqlite" | "mem0" | "honcho"` with `"mem0": { "apiKey": "...", "orgId": "..." }` options
-- [ ] Selective injection by default when using external backends (leverage their search APIs)
-- [ ] Offline fallback — if external backend is unreachable, fall back to local SQLite cache
-- [ ] Data export — `memory export` command to dump all entries as JSON
-
-### Security Model
+### Architecture: Orchestrator + Sync Mirror
 
 ```
-LLM tool call
+memory tool call (add/replace/remove/search)
     ↓
-Content Scanner (local, always runs first)
+Content Scanner (always runs first, local)
     ↓ blocked? → return error to LLM
     ↓ passed
-MemoryBackend.add()
+MemoryOrchestrator.write()
+    ↓
+    ├── BuiltinBackend.add()          ← always runs (source of truth)
+    │
+    └── ExternalSync.onWrite()        ← if configured (Mem0 or Honcho)
+          ├── Mirror the write to external API
+          └── If external fails → log warning, don't block
+
+MemoryOrchestrator.search()
     ↓
-Mem0 / Honcho / SQLite / Markdown
+    ├── BuiltinBackend.search()       ← always runs
+    └── ExternalSync.search()         ← supplementary results (if configured)
+    ↓
+    Merge + deduplicate → return to LLM
 ```
 
-The scanner runs **before** any backend. No adversarial content reaches external services.
+### Deliverables
+
+- [ ] `MemoryOrchestrator` — wraps `MemoryBackend` + optional `ExternalSync`
+- [ ] `ExternalSync` interface in `src/types.ts`
+- [ ] `Mem0Sync` — implements `ExternalSync` using Mem0 Node.js SDK
+- [ ] `HonchoSync` — implements `ExternalSync` using Honcho API
+- [ ] `onWrite()` mirroring — builtin writes propagate to external sync
+- [ ] One-external-only enforcement — same as Hermes, prevents conflicts
+- [ ] Offline fallback — if external sync `isAvailable()` returns false, skip silently
+- [ ] Config: `"externalSync": "mem0" | "honcho" | "none"` with credentials
+- [ ] Data export — `memory export` command to dump all entries as JSON
 
 ---
 
@@ -216,7 +320,7 @@ The scanner runs **before** any backend. No adversarial content reaches external
 - [ ] Multi-agent memory — shared context between agents, scoping rules (per-user, per-project, global)
 - [ ] Extensible scanner rules — users can add custom patterns to the content scanner
 - [ ] `/memory-insights` upgrade — show backend type, entry count, storage stats, last sync time
-- [ ] Audit log — track all memory operations with timestamps (already in SQLite schema for `SQLiteBackend`)
+- [ ] Audit log — track all memory operations with timestamps
 - [ ] Import/export — migrate between backends without data loss
 - [ ] Benchmarks — context injection latency, search relevance, token budget utilization
 
@@ -232,6 +336,7 @@ These hold across all versions:
 4. **Crash safety** — Atomic writes for markdown, WAL mode for SQLite, graceful degradation for external backends.
 5. **Zero-config start** — Install and it works with sensible defaults. Configuration is for power users.
 6. **Backwards compatible** — Every new version is a drop-in upgrade. No breaking changes to the tool interface or config format without a major version bump.
+7. **Hermes-compatible data format** — `§` delimiter, MEMORY.md/USER.md structure, so users migrating from Hermes keep their data.
 
 ---
 
@@ -243,30 +348,35 @@ gantt
     dateFormat YYYY-MM-DD
     axisFormat %b %Y
 
-    section v0.1.0
-    Core memory + scanner + tool + review + flush    :done, v01, 2025-04-20, 5d
+    section v0.1.0 ✅
+    Core memory + scanner + tool + review + flush    :done, v01, 2026-04-20, 5d
 
-    section v0.2.0
-    MemoryBackend interface                          :v02a, after v01, 7d
-    SQLite backend + FTS5 search                     :v02b, after v02a, 7d
-    memory search tool + project scoping             :v02c, after v02b, 5d
-    Context-aware injection                          :v02d, after v02c, 5d
+    section v0.2.0 — Next
+    Skill tool + procedural memory                   :v02a, after v01, 5d
+    Auto-consolidation                               :v02b, after v02a, 3d
+    Correction detection + immediate save            :v02c, after v02b, 3d
+    Tool-call-aware nudge                            :v02d, after v02c, 2d
 
     section v0.3.0
-    Mem0 backend                                     :v03a, after v02d, 7d
-    Honcho backend                                   :v03b, after v03a, 7d
-    Offline fallback + data export                   :v03c, after v03b, 5d
+    Session search + indexer                         :v03a, after v02d, 7d
+    Context fencing + memory aging                   :v03b, after v03a, 3d
+
+    section v0.4.0
+    MemoryBackend interface + SQLite                 :v04a, after v03b, 7d
+    Project-scoped memory + interview                :v04b, after v04a, 5d
+
+    section v0.5.0
+    ExternalSync + Mem0 / Honcho                     :v05a, after v04b, 10d
 
     section v1.0.0
-    Smart consolidation + confidence                 :v1a, after v03c, 10d
+    Smart consolidation + confidence                 :v1a, after v05a, 10d
     Multi-agent memory + audit log                   :v1b, after v1a, 10d
-    Extensible scanner + benchmarks                  :v1c, after v1b, 7d
 ```
 
 ---
 
 ## How to Contribute
 
-See [TASKS.md](0.1/TASKS.md) for current work. Pick an unchecked item, mark it `[~]`, implement, mark it `[x]` with the commit hash.
+See [TASKS.md](0.1/TASKS.md) for current v0.1 work. Pick an unchecked item, mark it `[~]`, implement, mark it `[x]` with the commit hash.
 
-For roadmap items, open an issue with the version tag (e.g. `v0.2.0`) and describe what you want to work on.
+For v0.2+ items, see [v0.2/TASKS.md](0.2/TASKS.md) once created. Open an issue with the version tag and describe what you want to work on.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-hermes-memory",
-  "version": "0.1.0",
-  "description": "Persistent memory and self-directed learning loop for Pi — ported from the Hermes agent harness. Security-first content scanning, real-time saves, and frozen snapshot injection.",
+  "version": "0.2.0",
+  "description": "Your Pi agent remembers everything across sessions — your preferences, your stack, your corrections, and even how it solved problems. Zero-config install, works immediately. Persistent memory + procedural skills + auto-correction detection + security-first content scanning.",
   "type": "module",
   "main": "src/index.ts",
   "files": [
@@ -23,11 +23,14 @@
     "pi-package",
     "pi-extension",
     "memory",
+    "skills",
     "learning-loop",
     "agent",
     "hermes",
     "persistent-memory",
-    "content-scanner"
+    "content-scanner",
+    "correction-detection",
+    "auto-consolidation"
   ],
   "license": "MIT",
   "repository": {

package/src/config.ts

@@ -7,6 +7,7 @@ import {
   DEFAULT_USER_CHAR_LIMIT,
   DEFAULT_NUDGE_INTERVAL,
   DEFAULT_FLUSH_MIN_TURNS,
+  DEFAULT_NUDGE_TOOL_CALLS,
 } from "./constants.js";
 
 const DEFAULT_CONFIG: MemoryConfig = {
@@ -17,6 +18,9 @@ const DEFAULT_CONFIG: MemoryConfig = {
   flushOnCompact: true,
   flushOnShutdown: true,
   flushMinTurns: DEFAULT_FLUSH_MIN_TURNS,
+  autoConsolidate: true,
+  correctionDetection: true,
+  nudgeToolCalls: DEFAULT_NUDGE_TOOL_CALLS,
 };
 
 export const DEFAULT_CONFIG_PATH = path.join(
@@ -40,6 +44,9 @@ export function loadConfig(): MemoryConfig {
       if (typeof parsed.flushOnCompact === "boolean") config.flushOnCompact = parsed.flushOnCompact;
       if (typeof parsed.flushOnShutdown === "boolean") config.flushOnShutdown = parsed.flushOnShutdown;
       if (typeof parsed.flushMinTurns === "number") config.flushMinTurns = parsed.flushMinTurns;
+      if (typeof parsed.autoConsolidate === "boolean") config.autoConsolidate = parsed.autoConsolidate;
+      if (typeof parsed.correctionDetection === "boolean") config.correctionDetection = parsed.correctionDetection;
+      if (typeof parsed.nudgeToolCalls === "number") config.nudgeToolCalls = parsed.nudgeToolCalls;
       return config;
     }
   } catch {

package/src/constants.ts

@@ -14,6 +14,8 @@ export const DEFAULT_USER_CHAR_LIMIT = 1375;
 // ─── Learning loop defaults ───
 export const DEFAULT_NUDGE_INTERVAL = 10;
 export const DEFAULT_FLUSH_MIN_TURNS = 6;
+export const DEFAULT_NUDGE_TOOL_CALLS = 15;
+export const DEFAULT_SKILL_TRIGGER_TOOL_CALLS = 8;
 
 // ─── File names ───
 export const MEMORY_FILE = "MEMORY.md";
@@ -44,9 +46,79 @@ export const COMBINED_REVIEW_PROMPT = `Review the conversation above and conside
 
 **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.
 
-**Skills**: Was a non-trivial approach used to complete a task that required trial and error, or changing course due to experiential findings along the way, or did the user expect or desire a different method or outcome?
+**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.`;
 
 // ─── Flush prompt (ported from flush_memories() in run_agent.py ~L7379) ───
 export const FLUSH_PROMPT = `[System: The session is being compressed. Save anything worth remembering — prioritize user preferences, corrections, and recurring patterns over task-specific details.]`;
+
+// ─── Auto-consolidation prompt ───
+export const CONSOLIDATION_PROMPT = `The memory is at capacity. Review the current entries and consolidate them:
+- Merge related entries into a single, concise entry
+- Remove outdated or superseded entries
+- Keep the most important and frequently-referenced facts
+- Preserve user preferences and corrections (highest priority)
+
+Use the memory tool to make changes. Be aggressive about merging — less is more.`;
+
+// ─── Correction detection patterns (two-pass filter) ───
+
+/** Strong patterns — always trigger (high confidence these are corrections) */
+export const CORRECTION_STRONG_PATTERNS: RegExp[] = [
+  /don'?t do that/i,
+  /not like that/i,
+  /^I said\b/i,
+  /^I told you\b/i,
+  /we already discussed/i,
+  /^please don'?t/i,
+  /^that'?s not what I/i,
+];
+
+/** Weak patterns — only trigger if followed by a directive (verb or "the/that/this") */
+export const CORRECTION_WEAK_PATTERNS: RegExp[] = [
+  /^no[,\.\s!]/i,
+  /^wrong[,\.\s!]/i,
+  /^actually[,\.\s]/i,
+  /^stop[,\.\s!]/i,
+];
+
+/** Negative patterns — suppress trigger even if a positive pattern matches */
+export const CORRECTION_NEGATIVE_PATTERNS: RegExp[] = [
+  /^no worries/i,
+  /^no problem/i,
+  /^no thanks/i,
+  /^no need/i,
+  /^actually.{0,10}(looks? great|perfect|good|correct|right)/i,
+  /^stop.{0,5}(there|here|for now)/i,
+];
+
+// ─── Correction save prompt ───
+export const CORRECTION_SAVE_PROMPT = `The user just corrected you. Review what went wrong and save the correction to persistent memory.
+
+Priority:
+1. User preference ("don't do X", "always use Y instead")
+2. Wrong assumption you made
+3. Environment fact you got wrong
+
+Use the memory tool to save. If this contradicts an existing entry, use 'replace' to update it.`;
+
+// ─── Skill tool description ───
+export const SKILL_TOOL_DESCRIPTION = `Save reusable procedures and patterns as skills that survive across sessions. Skills are procedural memory — they capture HOW to do something, not just what happened.
+
+WHEN TO CREATE A SKILL:
+- After completing a complex task that required trial and error or multiple tool calls
+- When you discover a non-obvious approach that could be reused
+- When the user teaches you a specific workflow or procedure
+
+WHEN TO UPDATE A SKILL (use 'patch'):
+- You discover a better approach for an existing skill
+- A pitfall or edge case not covered by the skill
+- A step in the procedure changed
+
+SKILL FORMAT:
+- name: short, descriptive (e.g., "debug-typescript-errors")
+- description: one-line summary of when to use it
+- body: structured with sections — ## When to Use, ## Procedure, ## Pitfalls, ## Verification
+
+ACTIONS: create (new skill), view (read full content), patch (update a section), edit (replace description + body), delete (remove skill).`;