pi-hermes-memory 0.4.1 → 0.4.3

package/docs/0.4/RELEASE-POST.md

@@ -0,0 +1,341 @@
+# Your AI Agent Just Got a Brain Upgrade: Pi Hermes Memory v0.4
+
+**TL;DR**: Your coding agent can now remember every conversation you've ever had with it. Search through weeks of context in milliseconds. Never lose an insight again.
+
+---
+
+## The Problem
+
+Every time you start a new session with an AI coding agent, it forgets everything. That debugging session from last Tuesday? Gone. The architecture decision you discussed for 2 hours? Vanished. The user preferences you explained 5 times? You'll explain them a 6th.
+
+You're not just losing context — you're losing **hours of accumulated knowledge**.
+
+## The Solution: Persistent Memory + Session Search
+
+Pi Hermes Memory v0.4 introduces **SQLite-powered session history** with full-text search. Your agent now has:
+
+- 🧠 **Persistent memory** that survives across sessions (MEMORY.md + USER.md)
+- 🔍 **Full-text search** across every conversation you've ever had
+- 📦 **Unlimited extended memory** via SQLite — no more "memory is full" errors
+- 🔎 **Two search tools** — `session_search` for conversations, `memory_search` for facts
+- 📊 **5,000 character limits** (up from 2,200) — more room for context
+
+## What Changed: Before vs After
+
+### Before v0.4
+```
+You: "What did we discuss about the auth flow last week?"
+Agent: "I don't have access to previous sessions."
+You: *sighs, re-explains everything*
+```
+
+### After v0.4
+```
+You: "What did we discuss about the auth flow last week?"
+Agent: *searches session history*
+       "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?"
+You: *continues where you left off*
+```
+
+## New Capabilities Deep Dive
+
+### 1. Session History Search
+
+Every conversation is automatically indexed into SQLite with FTS5 (full-text search 5). When you ask about something from the past, your agent searches across all sessions instantly.
+
+**How it works:**
+- Sessions are indexed on shutdown (automatic)
+- Full-text search via FTS5 — fast, keyword-based
+- Filter by project, role (user/assistant), or date
+
+**Try it:**
+```
+"What was that error we fixed with the database connection?"
+"Find the PR where we added the secret scanning feature"
+"What testing approach did we use for the memory store?"
+```
+
+### 2. Extended Memory Store
+
+The old memory had a 2,200 character limit. Now it's 5,000 — but more importantly, there's an **unlimited extended store** in SQLite. When core memory fills up, entries are preserved in the extended store and remain searchable.
+
+**What this means:**
+- Core memory (MEMORY.md): 5,000 chars — always in context
+- Extended memory (SQLite): Unlimited — searchable on demand
+- No more losing memories to consolidation
+
+### 3. Two-Tier Search Architecture
+
+| Tool | What It Searches | When to Use |
+|---|---|---|
+| `session_search` | Past conversations | "What did we discuss about X?" |
+| `memory_search` | Extended memory store | "What do I know about X?" |
+
+The agent decides which tool to use based on your question. But you can also invoke them directly.
+
+### 4. Hybrid Memory Design
+
+```
+Always in Context (5,000 chars each)
+┌─────────────────────────────────────┐
+│ MEMORY.md — Facts, conventions      │
+│ USER.md   — Who you are             │
+│ Project memory — When cwd matches   │
+└─────────────────────────────────────┘
+
+Searchable on Demand (Unlimited)
+┌─────────────────────────────────────┐
+│ session_search("auth flow")         │
+│ memory_search("testing patterns")   │
+└─────────────────────────────────────┘
+```
+
+Your agent always knows who you are and what you prefer (core memory). When it needs deeper context, it searches.
+
+## How to Test Your Memory
+
+### Step 1: Index Your Past Sessions
+
+```bash
+/memory-index-sessions
+```
+
+This imports all your existing Pi sessions into the search database. You'll see:
+
+```
+🔍 Scanning session directories...
+📁 Found 36 session files across 5 projects
+⏳ Indexing...
+
+✅ Session indexing complete!
+
+📊 Results:
+├─ Sessions processed: 36
+├─ Sessions indexed: 36
+├─ Messages indexed: 1,247
+
+📁 Projects indexed:
+├─ pi-hermes-memory: 12 sessions, 856 messages
+├─ my-other-project: 8 sessions, 234 messages
+└─ ...
+```
+
+### Step 2: Explore Your Memory
+
+```bash
+/memory-insights
+```
+
+Shows everything stored in your memory — facts, user profile, and project-specific memories.
+
+### Step 3: Search Your History
+
+Ask your agent to search:
+
+```
+"Search my sessions for discussions about TypeScript configuration"
+"What do I know about the user's testing preferences?"
+"Find conversations about database migrations"
+```
+
+### Step 4: Query the Database Directly
+
+For the curious, your data lives in `~/.pi/agent/memory/sessions.db`:
+
+```bash
+# Sessions overview
+sqlite3 -header -column ~/.pi/agent/memory/sessions.db \
+  "SELECT project, COUNT(*) as sessions, SUM(message_count) as messages 
+   FROM sessions GROUP BY project;"
+
+# Full-text search
+sqlite3 -header -column ~/.pi/agent/memory/sessions.db \
+  "SELECT s.project, substr(m.content, 1, 100) as snippet
+   FROM messages m JOIN sessions s ON s.id = m.session_id
+   WHERE m.rowid IN (SELECT rowid FROM message_fts WHERE message_fts MATCH 'SQLite')
+   LIMIT 5;"
+
+# Messages by role
+sqlite3 ~/.pi/agent/memory/sessions.db \
+  "SELECT role, COUNT(*) FROM messages GROUP BY role;"
+```
+
+## Real-World Impact
+
+### For Individual Developers
+- **Context continuity**: Pick up where you left off, even days later
+- **No more re-explaining**: Your preferences and setup are remembered
+- **Institutional memory**: Your debugging insights persist
+
+### For Teams
+- **Shared knowledge**: Project conventions are stored and searchable
+- **Onboarding**: New team members can search past discussions
+- **Decision history**: Architecture decisions are preserved
+
+### For Power Users
+- **Pattern recognition**: Search for similar problems across projects
+- **Learning retention**: Your coding learnings accumulate over time
+- **Workflow optimization**: Discover what approaches worked before
+
+## The Architecture (For the Technical)
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                    Pi Extension                          │
+├─────────────────────────────────────────────────────────┤
+│  Tools:                                                 │
+│  ├── memory (add/replace/remove)                        │
+│  ├── skill (create/view/patch/edit/delete)              │
+│  ├── session_search (FTS5 across messages)              │
+│  └── memory_search (FTS5 across extended memories)      │
+├─────────────────────────────────────────────────────────┤
+│  Storage:                                               │
+│  ├── MEMORY.md / USER.md (core, always injected)        │
+│  ├── skills/*.md (procedural, on-demand)                │
+│  └── sessions.db (SQLite + FTS5, searchable)            │
+├─────────────────────────────────────────────────────────┤
+│  Events:                                                │
+│  ├── session_start → Load core memory                   │
+│  ├── context → Inject memory into system prompt         │
+│  ├── session_shutdown → Auto-index session              │
+│  └── turn_count ≥ 10 → Background review                │
+└─────────────────────────────────────────────────────────┘
+```
+
+**Key technical decisions:**
+- **better-sqlite3**: Native C++ addon, synchronous API, built-in FTS5
+- **WAL mode**: Write-ahead logging for concurrent reads
+- **Lazy initialization**: DB only opened when first needed
+- **Single file**: `sessions.db` — easy to backup, easy to delete
+
+## What's Next (v0.5+)
+
+- **Semantic search**: Embedding-based search using local models (potion-base-4M)
+- **Cross-project insights**: Find patterns across all your projects
+- **Memory visualization**: Timeline view of your knowledge accumulation
+- **Collaborative memory**: Share project memories with team members
+
+## Get Started
+
+```bash
+# Install or update
+pi install chandra447/pi-hermes-memory
+
+# Index your past sessions
+/memory-index-sessions
+
+# Learn how to use it
+/learn-memory-tool
+
+# Check what's stored
+/memory-insights
+```
+
+## Links
+
+- **npm**: [pi-hermes-memory](https://www.npmjs.com/package/pi-hermes-memory)
+- **GitHub**: [chandra447/pi-hermes-memory](https://github.com/chandra447/pi-hermes-memory)
+- **Pi**: [pi.dev](https://pi.dev)
+
+---
+
+*Your AI agent should remember as much as you do. Now it does.*
+
+---
+
+## Social Media Posts
+
+### X/Twitter (Thread)
+
+**Post 1:**
+🚀 Just shipped v0.4 of Pi Hermes Memory — your AI coding agent can now search through every conversation you've ever had with it.
+
+No more re-explaining context. No more lost debugging sessions.
+
+Thread 🧵👇
+
+**Post 2:**
+The problem: Every AI session starts from zero. That 2-hour debugging session from Tuesday? Gone. The architecture decision you discussed? Vanished.
+
+You're not just losing context — you're losing hours of accumulated knowledge.
+
+**Post 3:**
+The solution: SQLite-powered session history with full-text search.
+
+Your agent now has:
+• Persistent memory (survives across sessions)
+• Full-text search across all conversations
+• Unlimited extended memory
+• 5,000 char limits (up from 2,200)
+
+**Post 4:**
+How it works:
+
+1. Sessions auto-indexed on shutdown
+2. FTS5 search finds relevant context in milliseconds
+3. Agent decides when to search based on your question
+4. Core memory always in context, extended memory searchable on demand
+
+**Post 5:**
+Try it yourself:
+
+```
+/memory-index-sessions  # Import past sessions
+/memory-insights        # See what's stored
+"Search my sessions for discussions about auth"  # Test it
+```
+
+**Post 6:**
+Technical details:
+• better-sqlite3 (native C++ addon)
+• WAL mode for concurrent reads
+• Single sessions.db file (easy backup)
+• Lazy initialization (no startup cost)
+
+**Post 7:**
+Your AI agent should remember as much as you do. Now it does.
+
+npm: npmjs.com/package/pi-hermes-memory
+GitHub: github.com/chandra447/pi-hermes-memory
+
+#AI #DevTools #CodingAgent #Pi #OpenSource
+
+---
+
+### LinkedIn Post
+
+**Your AI Agent Just Got a Brain Upgrade**
+
+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? Vanished.
+
+Pi Hermes Memory v0.4 changes this.
+
+Your agent now has:
+✅ Persistent memory that survives across sessions
+✅ Full-text search across every conversation
+✅ Unlimited extended memory via SQLite
+✅ Automatic session indexing
+
+The result? Context continuity. No more re-explaining your preferences. No more lost debugging insights. Your accumulated knowledge persists.
+
+I built this because I was tired of re-explaining context every session. Now my agent remembers what we discussed last week, last month, last year.
+
+Key technical decisions:
+• SQLite with FTS5 for fast full-text search
+• Hybrid memory: core (always in context) + extended (searchable on demand)
+• 5,000 character limits (up from 2,200)
+• Auto-indexing on session shutdown
+
+Try it:
+```
+pi install chandra447/pi-hermes-memory
+/memory-index-sessions
+```
+
+Your AI agent should remember as much as you do. Now it does.
+
+Open source: github.com/chandra447/pi-hermes-memory
+
+#AI #DevTools #SoftwareEngineering #OpenSource #CodingAgent #DeveloperProductivity #MachineLearning #ArtificialIntelligence

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-hermes-memory",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "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",

package/src/handlers/index-sessions.ts

@@ -1,6 +1,11 @@
+/**
+ * Index sessions command — /memory-index-sessions imports past sessions into SQLite.
+ */
+
 import path from 'node:path';
+import fs from 'node:fs';
 import os from 'node:os';
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI, ExtensionCommandContext } from "@mariozechner/pi-coding-agent";
 import { DatabaseManager } from '../store/db.js';
 import { indexAllSessions, getSessionStats } from '../store/session-indexer.js';
 
@@ -9,16 +14,26 @@ const SESSIONS_DIR = path.join(os.homedir(), '.pi', 'agent', 'sessions');
 export function registerIndexSessionsCommand(pi: ExtensionAPI): void {
   pi.registerCommand("memory-index-sessions", {
     description: "Import past Pi sessions into the search database",
-    handler: async (_args, ctx) => {
-      const sendUserMessage = (msg: string) => {
-        if (ctx && typeof ctx === 'object' && 'sendUserMessage' in ctx) {
-          (ctx as { sendUserMessage: (msg: string) => void }).sendUserMessage(msg);
+    handler: async (_args, ctx: ExtensionCommandContext) => {
+      // Show initial progress
+      ctx.ui.notify('🔍 Scanning session directories...', 'info');
+
+      try {
+        // Count sessions first for progress display
+        let totalFiles = 0;
+        let projectDirs: string[] = [];
+        if (fs.existsSync(SESSIONS_DIR)) {
+          projectDirs = fs.readdirSync(SESSIONS_DIR)
+            .filter(d => fs.statSync(path.join(SESSIONS_DIR, d)).isDirectory());
+          for (const dir of projectDirs) {
+            const files = fs.readdirSync(path.join(SESSIONS_DIR, dir))
+              .filter(f => f.endsWith('.jsonl'));
+            totalFiles += files.length;
+          }
         }
-      };
 
-      sendUserMessage('🔍 Indexing session history...');
+        ctx.ui.notify(`📁 Found ${totalFiles} session files across ${projectDirs.length} projects\n⏳ Indexing...`, 'info');
 
-      try {
         const memoryDir = path.join(os.homedir(), '.pi', 'agent', 'memory');
         const dbManager = new DatabaseManager(memoryDir);
 
@@ -28,36 +43,42 @@ export function registerIndexSessionsCommand(pi: ExtensionAPI): void {
 
           let output = `\n✅ Session indexing complete!\n\n`;
           output += `📊 Results:\n`;
-          output += `• Sessions processed: ${result.sessionsProcessed}\n`;
-          output += `• Sessions indexed: ${result.sessionsIndexed}\n`;
-          output += `• Sessions skipped (already indexed): ${result.sessionsSkipped}\n`;
-          output += `• Messages indexed: ${result.messagesIndexed}\n`;
+          output += `├─ Sessions processed: ${result.sessionsProcessed}\n`;
+          output += `├─ Sessions indexed: ${result.sessionsIndexed}\n`;
+          output += `├─ Sessions skipped (already indexed): ${result.sessionsSkipped}\n`;
+          output += `└─ Messages indexed: ${result.messagesIndexed}\n`;
 
           if (stats.projects.length > 0) {
-            output += `\n📁 Projects:\n`;
+            output += `\n📁 Projects indexed:\n`;
             for (const p of stats.projects) {
-              output += `• ${p.project}: ${p.sessions} sessions, ${p.messages} messages\n`;
+              output += `├─ ${p.project}: ${p.sessions} sessions, ${p.messages} messages\n`;
             }
           }
 
+          // Show totals
+          output += `\n📈 Database totals:\n`;
+          output += `├─ ${stats.totalSessions} sessions\n`;
+          output += `├─ ${stats.totalMessages} messages\n`;
+          output += `└─ ${stats.projects.length} projects\n`;
+
           if (result.errors.length > 0) {
             output += `\n⚠️ Errors (${result.errors.length}):\n`;
-            for (const err of result.errors.slice(0, 5)) {
-              output += `• ${err}\n`;
+            for (const err of result.errors.slice(0, 3)) {
+              output += `├─ ${err}\n`;
             }
-            if (result.errors.length > 5) {
-              output += `• ... and ${result.errors.length - 5} more\n`;
+            if (result.errors.length > 3) {
+              output += `└─ ... and ${result.errors.length - 3} more\n`;
             }
           }
 
-          output += `\n💡 Use the \`session_search\` tool to search across indexed sessions.`;
+          output += `\n💡 Use the session_search tool to search across indexed sessions.`;
 
-          sendUserMessage(output);
+          ctx.ui.notify(output, 'info');
         } finally {
           dbManager.close();
         }
       } catch (err) {
-        sendUserMessage(`❌ Session indexing failed: ${err instanceof Error ? err.message : String(err)}`);
+        ctx.ui.notify(`❌ Session indexing failed: ${err instanceof Error ? err.message : String(err)}`, 'error');
       }
     },
   });

package/src/handlers/learn-memory.ts

@@ -0,0 +1,79 @@
+/**
+ * Learn memory tool command — /learn-memory-tool teaches users about the memory system.
+ */
+
+import type { ExtensionAPI, ExtensionCommandContext } from "@mariozechner/pi-coding-agent";
+
+const LEARN_MEMORY_CONTENT = `# Pi Hermes Memory — Quick Guide
+
+## What Gets Saved
+
+| Type | File | What Goes Here | Limit |
+|---|---|---|---|
+| **Memory** | MEMORY.md | Facts — env details, project conventions, tool quirks | 5,000 chars |
+| **User Profile** | USER.md | Who you are — name, preferences, communication style | 5,000 chars |
+| **Skills** | skills/*.md | Procedures — how to debug, deploy, test | Unlimited |
+| **Extended Memory** | sessions.db | Searchable memories beyond the core limit | Unlimited |
+
+## Tools Available
+
+| Tool | What It Does |
+|---|---|
+| memory (add/replace/remove) | Save, update, or delete memories |
+| skill (create/view/patch/edit/delete) | Save reusable procedures |
+| session_search | Search past conversations across all sessions |
+| memory_search | Search extended memory store (unlimited) |
+
+## Commands
+
+| Command | What It Does |
+|---|---|
+| /memory-insights | Shows everything stored in memory |
+| /memory-skills | Lists all saved skills |
+| /memory-consolidate | Manually trigger memory cleanup |
+| /memory-interview | Answer questions to pre-fill your profile |
+| /memory-switch-project | List all project memories |
+| /memory-index-sessions | Import past sessions for search |
+
+## Best Practices
+
+**DO save:**
+- User preferences ("prefers pnpm", "uses vim", "likes concise answers")
+- Environment facts ("macOS M1", "Node 20", "project uses Prisma")
+- Corrections ("don't use npm — use pnpm", "always run tests first")
+- Project conventions ("monorepo with turborepo", "conventional commits")
+
+**DON'T save:**
+- Task progress ("finished implementing auth") — temporary
+- Session outcomes ("PR #42 was merged") — belongs in git history
+- Temporary state ("currently debugging X") — will be irrelevant soon
+
+## How Memory Flows
+
+1. Session starts → Core memory injected into system prompt
+2. During conversation → Agent saves via memory tool
+3. Every 10 turns → Background review saves noteworthy items
+4. On correction → Immediate save
+5. When full → Auto-consolidation merges entries
+6. Session ends → Final flush
+
+## Two-Tier Architecture
+
+- Global (always injected): ~/.pi/agent/memory/ — your name, preferences, tools
+- Project (when cwd matches): ~/.pi/agent/<project>/ — project-specific facts
+
+## Troubleshooting
+
+- "Memory is full" → /memory-consolidate to merge entries
+- "Can't find something" → memory_search to search extended store
+- "Agent forgot something" → Check /memory-insights, tell agent "remember that X"
+- "Want to edit manually" → Files are plain markdown at ~/.pi/agent/memory/`;
+
+export function registerLearnMemoryCommand(pi: ExtensionAPI): void {
+  pi.registerCommand("learn-memory-tool", {
+    description: "Learn how to use the pi-hermes-memory extension effectively",
+    handler: async (_args, ctx: ExtensionCommandContext) => {
+      ctx.ui.notify(LEARN_MEMORY_CONTENT, 'info');
+    },
+  });
+}

package/src/index.ts

@@ -44,6 +44,7 @@ import { registerSkillsCommand } from "./handlers/skills-command.js";
 import { registerInterviewCommand } from "./handlers/interview.js";
 import { registerSwitchProjectCommand } from "./handlers/switch-project.js";
 import { registerIndexSessionsCommand } from "./handlers/index-sessions.js";
+import { registerLearnMemoryCommand } from "./handlers/learn-memory.js";
 import { loadConfig } from "./config.js";
 import { detectProject } from "./project.js";
 
@@ -118,6 +119,7 @@ export default function (pi: ExtensionAPI) {
   registerSkillsCommand(pi, skillStore);
   registerInterviewCommand(pi, store);
   registerSwitchProjectCommand(pi);
+  registerLearnMemoryCommand(pi);
 
   // ── 11. SQLite session search + extended memory ──
   registerSessionSearchTool(pi, dbManager);

package/src/skills/learn-memory-tool/SKILL.md

@@ -1,125 +0,0 @@
----
-name: learn-memory-tool
-description: Learn how to use the pi-hermes-memory extension effectively — when to save memories, how to search, and best practices for persistent memory.
-version: 1
-created: 2026-05-03
-updated: 2026-05-03
----
-
-## When to Use
-
-When a user asks about the memory system, how to use it, or when they seem confused about what gets remembered. Also useful for onboarding new users to the extension.
-
-## Overview
-
-Pi Hermes Memory gives your AI agent persistent memory across sessions. Here's what it does:
-
-### What Gets Saved
-
-| Type | File | What Goes Here | Limit |
-|---|---|---|---|
-| **Memory** | `MEMORY.md` | Facts — env details, project conventions, tool quirks | 5,000 chars |
-| **User Profile** | `USER.md` | Who you are — name, preferences, communication style | 5,000 chars |
-| **Skills** | `skills/*.md` | Procedures — *how* to debug, deploy, test | Unlimited |
-| **Extended Memory** | `sessions.db` | Searchable memories beyond the core limit | Unlimited |
-
-### The `memory` Tool
-
-The agent has a `memory` tool with these actions:
-
-| Action | Target | What It Does |
-|---|---|---|
-| `add` | `memory` or `user` | Append a new entry |
-| `replace` | `memory` or `user` | Update an existing entry (matched by substring) |
-| `remove` | `memory` or `user` | Delete an entry (matched by substring) |
-
-### The `skill` Tool
-
-For saving reusable procedures:
-
-| Action | What It Does |
-|---|---|
-| `create` | Save a new skill |
-| `view` | Read a skill or list all skills |
-| `patch` | Update one section of a skill |
-| `edit` | Replace description and/or body |
-| `delete` | Remove a skill |
-
-### Search Tools
-
-| Tool | What It Does |
-|---|---|
-| `session_search` | Search past conversations across all sessions |
-| `memory_search` | Search extended memory store (unlimited capacity) |
-
-### Commands
-
-| Command | What It Does |
-|---|---|
-| `/memory-insights` | Shows everything stored in memory and user profile |
-| `/memory-skills` | Lists all agent-created skills |
-| `/memory-consolidate` | Manually trigger memory consolidation |
-| `/memory-interview` | Answer questions to pre-fill your user profile |
-| `/memory-switch-project` | List all project memories |
-| `/memory-index-sessions` | Import past sessions for search |
-
-## Best Practices
-
-### What TO Save
-
-- **User preferences**: "prefers pnpm over npm", "uses vim", "likes concise answers"
-- **Environment facts**: "macOS M1", "Node 20", "project uses Prisma"
-- **Corrections**: "don't use npm — use pnpm", "always run tests first"
-- **Project conventions**: "monorepo with turborepo", "conventional commits"
-- **Tool quirks**: "CI needs `--frozen-lockfile`", "deploy script is in scripts/deploy.sh"
-
-### What NOT to Save
-
-- **Task progress**: "finished implementing auth" — this is temporary
-- **Session outcomes**: "PR #42 was merged" — this belongs in git history
-- **Temporary state**: "currently debugging the test failure" — will be irrelevant soon
-- **Large code blocks**: Use skills instead for procedures
-
-### How Memory Flows
-
-1. **Session starts**: Core memory (MEMORY.md + USER.md) is injected into the system prompt
-2. **During conversation**: Agent saves memories via the `memory` tool
-3. **Every 10 turns or 15 tool calls**: Background review saves anything noteworthy
-4. **When you correct the agent**: Immediate save — no waiting
-5. **When memory is full**: Auto-consolidation merges and prunes entries
-6. **Session ends**: One last flush before shutdown
-
-### Two-Tier Architecture
-
-- **Global memory** (`~/.pi/agent/memory/`): Always injected — your name, preferences, tools
-- **Project memory** (`~/.pi/agent/<project>/`): Injected when cwd matches — project-specific facts
-
-### Memory Aging
-
-Entries carry timestamps. When consolidating, the agent knows which entries are stale (created long ago, never referenced) and which are fresh.
-
-### Context Fencing
-
-Memory is wrapped in `<memory-context>` XML tags so the LLM never treats stored facts as user instructions. This prevents injection attacks through stored memory.
-
-## Troubleshooting
-
-### "Memory is full"
-Run `/memory-consolidate` to manually merge entries. Or let auto-consolidation handle it.
-
-### "I can't find what I'm looking for"
-Use `memory_search` to search the extended store, or `session_search` to search past conversations.
-
-### "The agent forgot something"
-Check `/memory-insights` to see what's stored. If it's not there, the agent may not have saved it yet. You can tell the agent: "remember that X".
-
-### "I want to edit memory manually"
-Memory files are plain markdown at `~/.pi/agent/memory/MEMORY.md` and `USER.md`. Edit them directly if you want.
-
-## Verification
-
-After reading this skill, the user should understand:
-1. What the memory tool does and when to use it
-2. The difference between memory, user profile, skills, and extended memory
-3. How to search across sessions and extended memory
-4. Best practices for what to save and what not to save