pi-hermes-memory 0.4.1 → 0.4.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-hermes-memory",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "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,4 +1,9 @@
+/**
+ * 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 { DatabaseManager } from '../store/db.js';
@@ -16,9 +21,25 @@ export function registerIndexSessionsCommand(pi: ExtensionAPI): void {
         }
       };
 
-      sendUserMessage('🔍 Indexing session history...');
+      // Show initial progress
+      sendUserMessage('🔍 Scanning session directories...');
 
       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(`📁 Found ${totalFiles} session files across ${projectDirs.length} projects\n⏳ Indexing...`);
+
         const memoryDir = path.join(os.homedir(), '.pi', 'agent', 'memory');
         const dbManager = new DatabaseManager(memoryDir);
 
@@ -28,29 +49,35 @@ 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);
         } finally {

package/src/handlers/learn-memory.ts

@@ -0,0 +1,85 @@
+/**
+ * Learn memory tool command — /learn-memory-tool teaches users about the memory system.
+ */
+
+import type { ExtensionAPI } 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) => {
+      const sendUserMessage = (msg: string) => {
+        if (ctx && typeof ctx === 'object' && 'sendUserMessage' in ctx) {
+          (ctx as { sendUserMessage: (msg: string) => void }).sendUserMessage(msg);
+        }
+      };
+
+      sendUserMessage(LEARN_MEMORY_CONTENT);
+    },
+  });
+}

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