pi-hermes-memory 0.1.0 → 0.2.1

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.1",
+  "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": [
@@ -17,17 +17,20 @@
   },
   "scripts": {
     "check": "tsc --noEmit",
-    "test": "npx tsx --test 'tests/**/*.test.ts' --test-concurrency=1"
+    "test": "tests/run-all.sh"
   },
   "keywords": [
     "pi-package",
     "pi-extension",
     "memory",
+    "skills",
     "learning-loop",
     "agent",
     "hermes",
     "persistent-memory",
-    "content-scanner"
+    "content-scanner",
+    "correction-detection",
+    "auto-consolidation"
   ],
   "license": "MIT",
   "repository": {
@@ -35,11 +38,12 @@
     "url": "https://github.com/chandra447/pi-hermes-memory"
   },
   "peerDependencies": {
-    "@mariozechner/pi-coding-agent": "*"
+    "@mariozechner/pi-coding-agent": ">=0.70.0"
   },
   "devDependencies": {
     "@mariozechner/pi-ai": "^0.70.0",
     "@mariozechner/pi-coding-agent": "^0.70.0",
+    "tsx": "^4.21.0",
     "typebox": "^1.1.33",
     "typescript": "^6.0.3"
   }

package/src/config.ts

@@ -5,18 +5,24 @@ import type { MemoryConfig } from "./types.js";
 import {
   DEFAULT_MEMORY_CHAR_LIMIT,
   DEFAULT_USER_CHAR_LIMIT,
+  DEFAULT_PROJECT_CHAR_LIMIT,
   DEFAULT_NUDGE_INTERVAL,
   DEFAULT_FLUSH_MIN_TURNS,
+  DEFAULT_NUDGE_TOOL_CALLS,
 } from "./constants.js";
 
 const DEFAULT_CONFIG: MemoryConfig = {
   memoryCharLimit: DEFAULT_MEMORY_CHAR_LIMIT,
   userCharLimit: DEFAULT_USER_CHAR_LIMIT,
+  projectCharLimit: DEFAULT_PROJECT_CHAR_LIMIT,
   nudgeInterval: DEFAULT_NUDGE_INTERVAL,
   reviewEnabled: true,
   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 +46,11 @@ 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;
+      if (typeof parsed.projectCharLimit === "number") config.projectCharLimit = parsed.projectCharLimit;
+      if (typeof parsed.memoryDir === "string") config.memoryDir = parsed.memoryDir;
       return config;
     }
   } catch {