pi-hermes-memory 0.7.8 → 0.7.9

package/README.md

@@ -103,7 +103,7 @@ The extension stores memory at two levels:
 
 | Tier | Location | What goes here | Available when |
 |---|---|---|---|
-| **Global** | `~/.pi/agent/memory/` | Facts that apply everywhere — your name, preferences, OS, tools | Searchable via `memory_search` |
+| **Global** | `~/.pi/agent/pi-hermes-memory/` | Facts that apply everywhere — your name, preferences, OS, tools | Searchable via `memory_search` |
 | **Project** | `~/.pi/agent/projects-memory/<project>/` | Facts scoped to one codebase — architecture decisions, API quirks, team norms | Searchable when cwd matches the project |
 
 By default, full Markdown memories are **not** injected into the system prompt. The system prompt gets a full-detail `<memory-policy>` that tells the agent when to call `memory_search` and how to treat memory results. This keeps first-turn token usage low while preserving access to user, project, failure, correction, insight, preference, convention, and tool-quirk memories.
@@ -185,7 +185,7 @@ The agent also gets a `skill` tool for saving reusable procedures:
 
 Skills are stored in Pi-native locations:
 
-- Global skills: `~/.pi/agent/skills/<slug>/SKILL.md`
+- Global skills: `~/.pi/agent/pi-hermes-memory/skills/<slug>/SKILL.md`
 - Project skills: `~/.pi/agent/projects-memory/<project>/skills/<slug>/SKILL.md`
 
 The extension classifies new skills automatically:
@@ -241,13 +241,13 @@ This lets Pi discover project skills as native skills without copying them into
 |---|---|---|---|
 | **memory** | `MEMORY.md` | Agent's notes — env facts, project conventions, tool quirks, lessons learned | 5,000 chars |
 | **user** | `USER.md` | User profile — name, preferences, communication style, habits | 5,000 chars |
-| **skills** | `~/.pi/agent/skills/<slug>/SKILL.md` or `projects-memory/<project>/skills/<slug>/SKILL.md` | Procedures — *how* to debug, deploy, test, or fix something | Unlimited |
+| **skills** | `~/.pi/agent/pi-hermes-memory/skills/<slug>/SKILL.md` or `projects-memory/<project>/skills/<slug>/SKILL.md` | Procedures — *how* to debug, deploy, test, or fix something | Unlimited |
 | **extended** | `sessions.db` | Searchable memories beyond the core limit | Unlimited |
 | **sessions** | `sessions.db` | Past conversation history (searchable via FTS5) | Unlimited |
 
 ### Session History Search
 
-The extension indexes your Pi session history into a SQLite database with FTS5 full-text search. The agent can search across all past conversations using the `session_search` tool:
+By default, the extension indexes your Pi session history into a SQLite database with FTS5 full-text search. The agent can search across all past conversations using the `session_search` tool:
 
 | Tool | What it does |
 |---|---|---|
@@ -260,6 +260,8 @@ Session history is indexed automatically on session shutdown. To bulk-import exi
 /memory-index-sessions
 ```
 
+For users who prefer source anchors over snippets, `sessionSearch.variant` can be set to `anchors`. In that opt-in mode, the same `session_search` tool reads session JSONL files directly and accepts a Markdown request with fields such as `from`, `to`, `cwd`, and `limit`, plus `all`, `any`, and `exclude` lists. It returns plain text with `count`, an optional `message`, and compact `path:startLine-endLine` style anchors with short reasons instead of summaries or previews.
+
 ### Extended Memory Store
 
 The extension keeps Markdown memory as the human-readable source of truth, and mirrors successful writes into the SQLite-backed search store used by `memory_search`.
@@ -390,8 +392,9 @@ Create `~/.pi/agent/hermes-memory-config.json`:
   "memoryCharLimit": 5000,
   "userCharLimit": 5000,
   "projectCharLimit": 5000,
-  "memoryDir": "~/.pi/agent/memory",
+  "memoryDir": "~/.pi/agent/pi-hermes-memory",
   "projectsMemoryDir": "projects-memory",
+  "sessionSearch": { "variant": "legacy" },
   "nudgeInterval": 10,
   "nudgeToolCalls": 15,
   "reviewRecentMessages": 0,
@@ -418,8 +421,9 @@ Create `~/.pi/agent/hermes-memory-config.json`:
 | `memoryCharLimit` | `5000` | Max characters in MEMORY.md |
 | `userCharLimit` | `5000` | Max characters in USER.md |
 | `projectCharLimit` | `5000` | Max characters in project-scoped MEMORY.md |
-| `memoryDir` | `~/.pi/agent/memory` | Custom directory for memory files |
+| `memoryDir` | `~/.pi/agent/pi-hermes-memory` | Custom directory for extension storage files |
 | `projectsMemoryDir` | `projects-memory` | Subdirectory under `~/.pi/agent/` for project-scoped memory |
+| `sessionSearch` | `{ "variant": "legacy" }` | Session search implementation: `legacy` keeps the existing SQLite/FTS snippet search; `anchors` uses the opt-in Markdown request surface and returns compact JSONL line-range anchors from `~/.pi/agent/sessions/` |
 | `nudgeInterval` | `10` | Turns between auto-reviews |
 | `nudgeToolCalls` | `15` | Tool calls between auto-reviews (OR with turns) |
 | `reviewRecentMessages` | `0` | Recent messages included in background review (`0` = all) |
@@ -444,11 +448,16 @@ Create `~/.pi/agent/hermes-memory-config.json`:
 
 ```
 ~/.pi/agent/
-├── skills/                ← Global Pi-native skills
-│   ├── debug-typescript-errors/
-│   │   └── SKILL.md
-│   └── testing-checklist/
-│       └── SKILL.md
+├── pi-hermes-memory/      ← Global extension storage root
+│   ├── MEMORY.md          ← Agent's personal notes (env facts, patterns, lessons)
+│   ├── USER.md            ← User profile (name, preferences, habits)
+│   ├── sessions.db        ← SQLite database (session history + extended memory)
+│   ├── skills/            ← Global extension-managed skills
+│   │   ├── debug-typescript-errors/
+│   │   │   └── SKILL.md
+│   │   └── testing-checklist/
+│   │       └── SKILL.md
+│   └── .skills-migrated-to-extension-storage
 ├── projects-memory/       ← ALL project-scoped memories (one subfolder per project)
 │   ├── my-project/
 │   │   ├── MEMORY.md
@@ -457,11 +466,6 @@ Create `~/.pi/agent/hermes-memory-config.json`:
 │   │           └── SKILL.md
 │   └── another-project/
 │       └── MEMORY.md
-├── memory/                ← Global memory
-│   ├── MEMORY.md          ← Agent's personal notes (env facts, patterns, lessons)
-│   ├── USER.md            ← User profile (name, preferences, habits)
-│   ├── sessions.db        ← SQLite database (session history + extended memory)
-│   └── .skills-migrated-to-pi-native
 ├── hermes-memory-config.json
 └── ...
 ```
@@ -482,7 +486,7 @@ The `sessions.db` SQLite database stores session history and extended memory ent
 - **System prompts are invisible**: Pi's TUI does not display the system prompt. Use `/memory-preview-context` to inspect whether policy-only or legacy memory injection is active.
 - **Project skill visibility depends on Pi discovery cycles**: project skills are exposed through `resources_discover` using the active project's `skills/` path. If a moved or newly created project skill doesn't show up immediately in a running session, trigger a reload/new session so Pi refreshes discovered resources.
 - **Project move requires active project context**: in `/memory-skills`, the `p` hotkey is disabled when Pi is not currently in a detected project directory.
-- **Skills are agent-generated**: Skills are created by the agent based on its experience. They may not always be perfectly structured. You can move, delete, or still edit them directly in `~/.pi/agent/skills/` or the active project's `skills/` folder.
+- **Skills are agent-generated**: Skills are created by the agent based on its experience. They may not always be perfectly structured. You can move, delete, or still edit them directly in `~/.pi/agent/pi-hermes-memory/skills/` or the active project's `skills/` folder.
 
 ## Architecture
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-hermes-memory",
-  "version": "0.7.8",
+  "version": "0.7.9",
   "description": "🧠 Persistent memory + 🔍 session search + 🛡️ secret scanning for Pi. Token-aware policy-only memory by default, SQLite FTS5 search, auto-consolidation, procedural skills. 368 tests. Ported from Hermes agent.",
   "type": "module",
   "main": "src/index.ts",

package/src/config.ts

@@ -1,7 +1,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import * as os from "node:os";
-import type { MemoryConfig, MemoryOverflowStrategy } from "./types.js";
+import type { MemoryConfig, MemoryOverflowStrategy, SessionSearchVariant } from "./types.js";
 import {
   DEFAULT_MEMORY_CHAR_LIMIT,
   DEFAULT_USER_CHAR_LIMIT,
@@ -18,11 +18,16 @@ import {
 } from "./constants.js";
 
 const MEMORY_OVERFLOW_STRATEGIES: readonly MemoryOverflowStrategy[] = ["auto-consolidate", "reject", "fifo-evict"];
+const SESSION_SEARCH_VARIANTS: readonly SessionSearchVariant[] = ["legacy", "anchors"];
 
 function isMemoryOverflowStrategy(value: unknown): value is MemoryOverflowStrategy {
   return typeof value === "string" && MEMORY_OVERFLOW_STRATEGIES.includes(value as MemoryOverflowStrategy);
 }
 
+function isSessionSearchVariant(value: unknown): value is SessionSearchVariant {
+  return typeof value === "string" && SESSION_SEARCH_VARIANTS.includes(value as SessionSearchVariant);
+}
+
 const DEFAULT_CONFIG: MemoryConfig = {
   memoryMode: "policy-only",
   memoryPolicyStyle: "full",
@@ -45,6 +50,7 @@ const DEFAULT_CONFIG: MemoryConfig = {
   consolidationTimeoutMs: DEFAULT_CONSOLIDATION_TIMEOUT_MS,
   nudgeToolCalls: DEFAULT_NUDGE_TOOL_CALLS,
   projectsMemoryDir: DEFAULT_PROJECTS_MEMORY_DIR,
+  sessionSearch: { variant: "legacy" },
 };
 
 export const DEFAULT_CONFIG_PATH = path.join(
@@ -107,6 +113,13 @@ export function loadConfig(configPath = DEFAULT_CONFIG_PATH): MemoryConfig {
       if (typeof parsed.projectCharLimit === "number") config.projectCharLimit = parsed.projectCharLimit;
       if (typeof parsed.memoryDir === "string") config.memoryDir = parsed.memoryDir;
       if (typeof parsed.projectsMemoryDir === "string") config.projectsMemoryDir = parsed.projectsMemoryDir;
+      if (
+        typeof parsed.sessionSearch === "object" &&
+        parsed.sessionSearch !== null &&
+        isSessionSearchVariant(parsed.sessionSearch.variant)
+      ) {
+        config.sessionSearch = { variant: parsed.sessionSearch.variant };
+      }
       if (hasMemoryOverflowStrategy) {
         config.autoConsolidate = config.memoryOverflowStrategy === "auto-consolidate";
       } else if (hasLegacyAutoConsolidate) {

package/src/extension-root-migration.ts

@@ -0,0 +1,101 @@
+import fs from "node:fs/promises";
+import { existsSync } from "node:fs";
+import path from "node:path";
+
+export interface ExtensionRootMigrationResult {
+  moved: number;
+  merged: number;
+  skipped: number;
+  warnings: string[];
+}
+
+async function pathExists(filePath: string): Promise<boolean> {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function moveFileSafe(source: string, target: string): Promise<void> {
+  await fs.mkdir(path.dirname(target), { recursive: true });
+
+  try {
+    await fs.rename(source, target);
+    return;
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException)?.code;
+    if (code !== "EXDEV") throw error;
+  }
+
+  await fs.copyFile(source, target);
+  await fs.unlink(source);
+}
+
+async function moveDirContents(sourceDir: string, targetDir: string, result: ExtensionRootMigrationResult): Promise<void> {
+  await fs.mkdir(targetDir, { recursive: true });
+
+  const entries = await fs.readdir(sourceDir, { withFileTypes: true });
+  for (const entry of entries) {
+    const sourcePath = path.join(sourceDir, entry.name);
+    const targetPath = path.join(targetDir, entry.name);
+
+    if (!await pathExists(targetPath)) {
+      try {
+        await moveFileSafe(sourcePath, targetPath);
+        result.moved++;
+      } catch (error) {
+        result.warnings.push(`${sourcePath}: ${error instanceof Error ? error.message : String(error)}`);
+      }
+      continue;
+    }
+
+    if (entry.isDirectory()) {
+      await moveDirContents(sourcePath, targetPath, result);
+      result.merged++;
+      try {
+        const remaining = await fs.readdir(sourcePath);
+        if (remaining.length === 0) await fs.rmdir(sourcePath);
+      } catch {
+        // best effort
+      }
+      continue;
+    }
+
+    result.skipped++;
+  }
+}
+
+/**
+ * Move legacy extension assets from ~/.pi/agent/memory into
+ * ~/.pi/agent/pi-hermes-memory. Existing destination files win.
+ */
+export async function migrateExtensionRoot(
+  legacyRoot: string,
+  targetRoot: string,
+): Promise<ExtensionRootMigrationResult> {
+  const result: ExtensionRootMigrationResult = {
+    moved: 0,
+    merged: 0,
+    skipped: 0,
+    warnings: [],
+  };
+
+  if (path.resolve(legacyRoot) === path.resolve(targetRoot)) return result;
+  if (!existsSync(legacyRoot)) return result;
+
+  await fs.mkdir(targetRoot, { recursive: true });
+  await moveDirContents(legacyRoot, targetRoot, result);
+
+  try {
+    const remaining = await fs.readdir(legacyRoot);
+    if (remaining.length === 0) {
+      await fs.rmdir(legacyRoot);
+    }
+  } catch {
+    // best effort
+  }
+
+  return result;
+}

package/src/handlers/index-sessions.ts

@@ -34,7 +34,7 @@ export function registerIndexSessionsCommand(pi: ExtensionAPI): void {
 
         ctx.ui.notify(`📁 Found ${totalFiles} session files across ${projectDirs.length} projects\n⏳ Indexing...`, 'info');
 
-        const memoryDir = path.join(os.homedir(), '.pi', 'agent', 'memory');
+        const memoryDir = path.join(os.homedir(), '.pi', 'agent', 'pi-hermes-memory');
         const dbManager = new DatabaseManager(memoryDir);
 
         try {