pi-memory-stone 0.1.1 → 0.1.3

package/README.md

@@ -48,7 +48,7 @@ pi-memory-stone package source
 │   ├── tools/                    # LLM-callable tools
 │   ├── privacy/                  # Secret redaction, sensitive path filtering
 │   └── config/                   # Project identity, settings
-└── test/                         # 44 tests across 4 suites
+└── test/                         # 51 tests across 6 test files
 ```
 
 ## How It Works
@@ -69,10 +69,12 @@ Every time the agent finishes a response, the extension:
 Before each agent turn, the extension:
 
 - Builds a focused query from the user's prompt
-- Searches records via FTS5
+- Uses `memory.injectionMode` to choose automatic or manual injection
+- In `auto` mode, searches records via FTS5
 - Ranks by hybrid score: FTS match + same-project boost + recency decay + kind weight + confidence
-- Injects top results (max 5, threshold-limited) as system prompt context
-- Tracks injected refs to prevent feedback loops
+- Injects top results (max 5, threshold-limited) plus any refs selected with `/memory-inject`
+- In `manual` mode, skips search and injects only refs selected with `/memory-inject`
+- Tracks auto-injected refs to prevent feedback loops
 - Logs every injection for audit via `/memory-last`
 
 ### 3. Storage Model
@@ -102,9 +104,18 @@ Before each agent turn, the extension:
 | `/memory-status` | `/stone-status` | Show index statistics, record counts by kind, config |
 | `/memory-status --verbose` | | Include per-kind record breakdown |
 | `/memory-search <query>` | `/stone-search` | Search memory for relevant records |
+| `/memory-open <id>` | `/stone-open` | Open a specific memory record by reference ID |
+| `/memory-inject <id> [id ...]` | `/stone-inject` | Manually inject specific refs into future turns this session |
+| `/memory-clear-injected` | `/stone-clear-injected` | Clear manually injected refs for this session |
+| `/memory-mode <auto\|manual>` | `/stone-mode` | Override injection mode for this session |
 | `/memory-last` | `/stone-last` | Show the last memory injection packet |
 | `/memory-forget <id>` | `/stone-forget` | Soft-forget a record (hide from searches) |
 | `/memory-forget <id> --hard` | | Permanently delete (with confirmation) |
+| `/memory-export [path] --format json\|md` | `/stone-export` | Export active records to a portable JSON or Markdown file (`--all` includes inactive records) |
+| `/memory-import <memory-export.json>` | `/stone-import` | Import records from a JSON export, remapping project-scoped records to the current project by default |
+| `/memory-import <memory-export.json> --preserve-project` | | Import records while preserving exported project IDs |
+| `/memory-import <memory-export.json> --global` | | Import all records as global memories |
+| `/memory-backup [path]` | `/stone-backup` | Copy the SQLite memory database to a timestamped backup file |
 | `/memory-on` | | Enable memory injection for this session |
 | `/memory-off` | | Disable memory injection for this session |
 
@@ -154,6 +165,29 @@ Parameters:
   hard?   Request permanent deletion (requires confirmation)
 ```
 
+## Portable Export, Import, and Backup
+
+Use JSON export/import when you want a portable, reviewable memory transfer between machines:
+
+```bash
+/memory-export --format json
+/memory-import memory-export.json
+```
+
+Markdown export is for human review outside SQLite:
+
+```bash
+/memory-export memory-export.md --format md
+```
+
+Use a database backup before pruning or hard deletion:
+
+```bash
+/memory-backup
+```
+
+Import defaults are intentionally practical for machine moves: project-scoped records are remapped to the current project. Use `--preserve-project` to keep exported project IDs, or `--global` to import everything as global memory.
+
 ## Privacy & Safety
 
 ### Secret Redaction
@@ -226,14 +260,16 @@ npm run typecheck
 
 These scripts are also runnable from a pi package clone installed from git; the required script runners are regular dependencies because pi package installs omit `devDependencies`.
 
-44 tests across 4 suites:
+51 tests across 6 test files:
 
 | Suite | Tests | Focus |
 |---|---|---|
 | `indexing.test.ts` | 1 | Incremental session indexing |
-| `privacy.test.ts` | 17 | Secret redaction, sensitive path filtering |
 | `parser.test.ts` | 10 | Turn parsing, file activity detection, error extraction |
+| `portable.test.ts` | 3 | JSON/Markdown export, JSON import, SQLite backup |
+| `privacy.test.ts` | 17 | Secret redaction, sensitive path filtering |
 | `ranking.test.ts` | 16 | Hybrid ranking, cross-project filtering, injection formatting |
+| `session-state.test.ts` | 4 | Injection mode config, session ref selection, manual-only injection |
 
 ## Configuration
 
@@ -246,11 +282,21 @@ Project settings in `.pi/settings.json`:
     "maxInjectedRecords": 5,
     "maxInjectedTokens": 1000,
     "scoreThreshold": 0.3,
-    "crossProjectEnabled": false
+    "crossProjectEnabled": false,
+    "injectionMode": "auto"
   }
 }
 ```
 
+`injectionMode` accepts:
+
+| Value | Behavior |
+|---|---|
+| `auto` | Default. Automatically searches relevant memories and also includes refs selected with `/memory-inject`. |
+| `manual` | Disables automatic search-based injection. Only refs selected with `/memory-inject` are injected. |
+
+For manual-only memory, keep `enabled: true` and set `injectionMode: "manual"`.
+
 ## Deferred (Future Slices)
 
 - LLM extraction (decisions, preferences, tasks)

package/package.json

@@ -1,9 +1,15 @@
 {
   "name": "pi-memory-stone",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "type": "module",
   "description": "Global pi extension: preserves and retrieves useful memory across pi sessions",
   "license": "MIT",
+  "keywords": ["pi-package"],
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
   "pi": {
     "extensions": ["./src/index.ts"]
   },

package/src/commands/index.ts

@@ -1,11 +1,29 @@
 /**
- * Commands: /memory-status, /memory-search, /memory-last
+ * Commands: /memory-status, /memory-search, /memory-open, /memory-inject, /memory-mode, /memory-last,
+ * /memory-export, /memory-import, /memory-backup
  */
 
 import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
-import { getStats, getLastInjection } from "../db/index.js";
+import { getStats, getLastInjection, getRecord } from "../db/index.js";
 import { retrieve } from "../retrieval/index.js";
 import { getProjectId, getConfig } from "../config/index.js";
+import {
+  backupMemoryDatabase,
+  defaultPortablePath,
+  importMemoryJsonFile,
+  resolvePortablePath,
+  writeMemoryExport,
+  type ExportFormat,
+} from "../portable/index.js";
+import {
+  INJECTION_MODE_ENTRY,
+  MANUAL_INJECTION_ENTRY,
+  SESSION_TOGGLE_ENTRY,
+  getMemorySessionState,
+  isInjectionMode,
+  isRecordVisibleInProject,
+  parseRefArgs,
+} from "../session-state/index.js";
 
 export function registerCommands(pi: ExtensionAPI): void {
   // ── /memory-status ──────────────────────────────────────────────
@@ -40,6 +58,70 @@ export function registerCommands(pi: ExtensionAPI): void {
     },
   });
 
+  // ── /memory-open ────────────────────────────────────────────────
+
+  pi.registerCommand("memory-open", {
+    description: "Open a specific memory record by reference ID",
+    handler: async (args, ctx) => {
+      await handleMemoryOpen(args, ctx);
+    },
+  });
+
+  pi.registerCommand("stone-open", {
+    description: "Alias for /memory-open",
+    handler: async (args, ctx) => {
+      await handleMemoryOpen(args, ctx);
+    },
+  });
+
+  // ── /memory-inject / /memory-clear-injected ────────────────────
+
+  pi.registerCommand("memory-inject", {
+    description: "Manually inject specific memory refs into future turns",
+    handler: async (args, ctx) => {
+      await handleMemoryInject(args, ctx, pi);
+    },
+  });
+
+  pi.registerCommand("stone-inject", {
+    description: "Alias for /memory-inject",
+    handler: async (args, ctx) => {
+      await handleMemoryInject(args, ctx, pi);
+    },
+  });
+
+  pi.registerCommand("memory-clear-injected", {
+    description: "Clear manually injected memory refs for this session",
+    handler: async (_args, ctx) => {
+      pi.appendEntry(MANUAL_INJECTION_ENTRY, { action: "clear" });
+      ctx.ui.notify("Cleared manually injected memory refs for this session", "info");
+    },
+  });
+
+  pi.registerCommand("stone-clear-injected", {
+    description: "Alias for /memory-clear-injected",
+    handler: async (_args, ctx) => {
+      pi.appendEntry(MANUAL_INJECTION_ENTRY, { action: "clear" });
+      ctx.ui.notify("Cleared manually injected memory refs for this session", "info");
+    },
+  });
+
+  // ── /memory-mode ────────────────────────────────────────────────
+
+  pi.registerCommand("memory-mode", {
+    description: "Set memory injection mode for this session: auto or manual",
+    handler: async (args, ctx) => {
+      await handleMemoryMode(args, ctx, pi);
+    },
+  });
+
+  pi.registerCommand("stone-mode", {
+    description: "Alias for /memory-mode",
+    handler: async (args, ctx) => {
+      await handleMemoryMode(args, ctx, pi);
+    },
+  });
+
   // ── /memory-last ────────────────────────────────────────────────
 
   pi.registerCommand("memory-last", {
@@ -72,6 +154,50 @@ export function registerCommands(pi: ExtensionAPI): void {
     },
   });
 
+  // ── /memory-export / /memory-import / /memory-backup ───────────
+
+  pi.registerCommand("memory-export", {
+    description: "Export active memory records to JSON or Markdown",
+    handler: async (args, ctx) => {
+      await handleMemoryExport(args, ctx);
+    },
+  });
+
+  pi.registerCommand("stone-export", {
+    description: "Alias for /memory-export",
+    handler: async (args, ctx) => {
+      await handleMemoryExport(args, ctx);
+    },
+  });
+
+  pi.registerCommand("memory-import", {
+    description: "Import memory records from a JSON export",
+    handler: async (args, ctx) => {
+      await handleMemoryImport(args, ctx);
+    },
+  });
+
+  pi.registerCommand("stone-import", {
+    description: "Alias for /memory-import",
+    handler: async (args, ctx) => {
+      await handleMemoryImport(args, ctx);
+    },
+  });
+
+  pi.registerCommand("memory-backup", {
+    description: "Copy the SQLite memory database to a timestamped backup file",
+    handler: async (args, ctx) => {
+      await handleMemoryBackup(args, ctx);
+    },
+  });
+
+  pi.registerCommand("stone-backup", {
+    description: "Alias for /memory-backup",
+    handler: async (args, ctx) => {
+      await handleMemoryBackup(args, ctx);
+    },
+  });
+
   // ── /memory-on / /memory-off ────────────────────────────────────
 
   pi.registerCommand("memory-on", {
@@ -79,7 +205,7 @@ export function registerCommands(pi: ExtensionAPI): void {
     handler: async (_args, ctx) => {
       ctx.ui.notify("Memory injection enabled for this session", "info");
       // Session toggle — stored in extension state
-      pi.appendEntry("memory-stone:session-toggle", { enabled: true });
+      pi.appendEntry(SESSION_TOGGLE_ENTRY, { enabled: true });
     },
   });
 
@@ -87,7 +213,7 @@ export function registerCommands(pi: ExtensionAPI): void {
     description: "Disable memory injection for this session",
     handler: async (_args, ctx) => {
       ctx.ui.notify("Memory injection disabled for this session", "info");
-      pi.appendEntry("memory-stone:session-toggle", { enabled: false });
+      pi.appendEntry(SESSION_TOGGLE_ENTRY, { enabled: false });
     },
   });
 }
@@ -119,7 +245,11 @@ async function handleMemoryStatus(args: string, ctx: ExtensionCommandContext): P
   lines.push(`    enabled: ${config.enabled}`);
   lines.push(`    maxInjectedRecords: ${config.maxInjectedRecords}`);
   lines.push(`    maxInjectedTokens: ${config.maxInjectedTokens}`);
+  const sessionState = getMemorySessionState(ctx.sessionManager.getBranch());
   lines.push(`    crossProjectEnabled: ${config.crossProjectEnabled}`);
+  lines.push(`    injectionMode: ${config.injectionMode}`);
+  lines.push(`    effectiveInjectionMode: ${sessionState.injectionMode ?? config.injectionMode}`);
+  lines.push(`    manuallyInjectedRefs: ${sessionState.manualRefs.length > 0 ? sessionState.manualRefs.join(", ") : "none"}`);
 
   if (ctx.hasUI) {
     ctx.ui.notify(lines.join("\n"), "info");
@@ -169,6 +299,102 @@ async function handleMemorySearch(args: string, ctx: ExtensionCommandContext): P
   }
 }
 
+async function handleMemoryOpen(args: string, ctx: ExtensionCommandContext): Promise<void> {
+  const refId = args?.trim().split(/\s+/).filter(Boolean)[0];
+
+  if (!refId) {
+    ctx.ui.notify("Usage: /memory-open <ref-id>", "warning");
+    return;
+  }
+
+  const record = getRecord(refId);
+  if (!record) {
+    ctx.ui.notify(`Memory record ${refId} not found.`, "warning");
+    return;
+  }
+
+  const currentProjectId = getProjectId(ctx.cwd);
+  if (record.status !== "active" || !isRecordVisibleInProject(record, currentProjectId)) {
+    ctx.ui.notify(`Memory record ${refId} is not available.`, "warning");
+    return;
+  }
+
+  const lines: string[] = [];
+  lines.push(`Memory Record: ${record.id}`);
+  lines.push(`Kind: ${record.kind}`);
+  lines.push(`Scope: ${record.scope}`);
+  lines.push(`Project: ${record.project_id ?? "global"}`);
+  lines.push(`Created: ${new Date(record.created_at).toISOString()}`);
+  lines.push(`Status: ${record.status}`);
+  lines.push("");
+  lines.push(record.text);
+
+  ctx.ui.notify(lines.join("\n"), "info");
+}
+
+async function handleMemoryInject(args: string, ctx: ExtensionCommandContext, pi: ExtensionAPI): Promise<void> {
+  const refIds = parseRefArgs(args);
+
+  if (refIds.length === 0) {
+    ctx.ui.notify("Usage: /memory-inject <ref-id> [ref-id ...]", "warning");
+    return;
+  }
+
+  const currentProjectId = getProjectId(ctx.cwd);
+  const acceptedRefs: string[] = [];
+  const rejectedRefs: string[] = [];
+
+  for (const refId of refIds) {
+    const record = getRecord(refId);
+    if (record && record.status === "active" && isRecordVisibleInProject(record, currentProjectId)) {
+      acceptedRefs.push(refId);
+    } else {
+      rejectedRefs.push(refId);
+    }
+  }
+
+  if (acceptedRefs.length > 0) {
+    pi.appendEntry(MANUAL_INJECTION_ENTRY, { action: "add", refs: acceptedRefs });
+  }
+
+  const lines: string[] = [];
+  if (acceptedRefs.length > 0) {
+    lines.push(`Manually injected memory refs for this session: ${acceptedRefs.join(", ")}`);
+  }
+  if (rejectedRefs.length > 0) {
+    lines.push(`Unavailable refs skipped: ${rejectedRefs.join(", ")}`);
+  }
+
+  ctx.ui.notify(lines.join("\n") || "No memory refs were injected.", acceptedRefs.length > 0 ? "info" : "warning");
+}
+
+async function handleMemoryMode(args: string, ctx: ExtensionCommandContext, pi: ExtensionAPI): Promise<void> {
+  const mode = args?.trim().split(/\s+/).filter(Boolean)[0];
+  const config = getConfig(ctx.cwd);
+  const sessionState = getMemorySessionState(ctx.sessionManager.getBranch());
+
+  if (!mode) {
+    ctx.ui.notify(
+      `Memory injection mode: ${sessionState.injectionMode ?? config.injectionMode}\nUsage: /memory-mode <auto|manual>`,
+      "info",
+    );
+    return;
+  }
+
+  if (!isInjectionMode(mode)) {
+    ctx.ui.notify("Usage: /memory-mode <auto|manual>", "warning");
+    return;
+  }
+
+  pi.appendEntry(INJECTION_MODE_ENTRY, { mode });
+  ctx.ui.notify(
+    mode === "manual"
+      ? "Memory injection mode set to manual for this session. Use /memory-inject <ref-id> to choose memories."
+      : "Memory injection mode set to auto for this session.",
+    "info",
+  );
+}
+
 async function handleMemoryLast(ctx: ExtensionCommandContext): Promise<void> {
   const sessionId = ctx.sessionManager.getSessionId();
   const last = getLastInjection(sessionId);
@@ -195,6 +421,66 @@ async function handleMemoryLast(ctx: ExtensionCommandContext): Promise<void> {
   }
 }
 
+async function handleMemoryExport(args: string, ctx: ExtensionCommandContext): Promise<void> {
+  const parsed = parseCommandArgs(args);
+  const formatValue = parsed.options.get("format") ?? (parsed.flags.has("md") ? "md" : "json");
+  if (formatValue !== "json" && formatValue !== "md") {
+    ctx.ui.notify("Usage: /memory-export [path] [--format json|md] [--all]", "warning");
+    return;
+  }
+
+  const format = formatValue as ExportFormat;
+  const outputPath = resolvePortablePath(
+    ctx.cwd,
+    parsed.positionals[0] ?? defaultPortablePath(ctx.cwd, "memory-export", format),
+  );
+
+  try {
+    const count = writeMemoryExport(outputPath, format, parsed.flags.has("all"));
+    ctx.ui.notify(`Exported ${count} memory records to ${outputPath}`, "info");
+  } catch (err) {
+    ctx.ui.notify(`Memory export failed: ${err instanceof Error ? err.message : String(err)}`, "warning");
+  }
+}
+
+async function handleMemoryImport(args: string, ctx: ExtensionCommandContext): Promise<void> {
+  const parsed = parseCommandArgs(args);
+  const inputPathArg = parsed.positionals[0];
+  if (!inputPathArg) {
+    ctx.ui.notify("Usage: /memory-import <memory-export.json> [--preserve-project|--global]", "warning");
+    return;
+  }
+
+  const inputPath = resolvePortablePath(ctx.cwd, inputPathArg);
+  try {
+    const result = importMemoryJsonFile(inputPath, {
+      projectId: parsed.flags.has("preserve-project") ? undefined : getProjectId(ctx.cwd),
+      scopeOverride: parsed.flags.has("global") ? "global" : undefined,
+    });
+    ctx.ui.notify(
+      `Imported ${result.imported} memory records from ${inputPath}${result.skipped ? ` (${result.skipped} skipped)` : ""}`,
+      "info",
+    );
+  } catch (err) {
+    ctx.ui.notify(`Memory import failed: ${err instanceof Error ? err.message : String(err)}`, "warning");
+  }
+}
+
+async function handleMemoryBackup(args: string, ctx: ExtensionCommandContext): Promise<void> {
+  const parsed = parseCommandArgs(args);
+  const outputPath = resolvePortablePath(
+    ctx.cwd,
+    parsed.positionals[0] ?? defaultPortablePath(ctx.cwd, "memory-backup", "db"),
+  );
+
+  try {
+    backupMemoryDatabase(outputPath);
+    ctx.ui.notify(`Backed up memory database to ${outputPath}`, "info");
+  } catch (err) {
+    ctx.ui.notify(`Memory backup failed: ${err instanceof Error ? err.message : String(err)}`, "warning");
+  }
+}
+
 async function handleMemoryForget(args: string, ctx: ExtensionCommandContext): Promise<void> {
   const { softForgetRecord, hardDeleteRecord, getRecord } = await import("../db/index.js");
 
@@ -232,3 +518,39 @@ async function handleMemoryForget(args: string, ctx: ExtensionCommandContext): P
     }
   }
 }
+
+function parseCommandArgs(args: string): {
+  flags: Set<string>;
+  options: Map<string, string>;
+  positionals: string[];
+} {
+  const flags = new Set<string>();
+  const options = new Map<string, string>();
+  const positionals: string[] = [];
+  const parts = args?.trim().split(/\s+/).filter(Boolean) ?? [];
+
+  for (let i = 0; i < parts.length; i += 1) {
+    const part = parts[i];
+    if (!part.startsWith("--")) {
+      positionals.push(part);
+      continue;
+    }
+
+    const withoutPrefix = part.slice(2);
+    const eqIndex = withoutPrefix.indexOf("=");
+    if (eqIndex >= 0) {
+      options.set(withoutPrefix.slice(0, eqIndex), withoutPrefix.slice(eqIndex + 1));
+      continue;
+    }
+
+    const next = parts[i + 1];
+    if (next && !next.startsWith("--") && ["format"].includes(withoutPrefix)) {
+      options.set(withoutPrefix, next);
+      i += 1;
+    } else {
+      flags.add(withoutPrefix);
+    }
+  }
+
+  return { flags, options, positionals };
+}

package/src/config/index.ts

@@ -8,6 +8,7 @@ import { execSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
+import type { InjectionMode } from "../session-state/index.js";
 
 // ─── Project identity ───────────────────────────────────────────────
 
@@ -51,6 +52,8 @@ export interface MemoryConfig {
   scoreThreshold: number;
   /** Whether cross-project injection is enabled */
   crossProjectEnabled: boolean;
+  /** Search-based automatic injection, or only explicit /memory-inject refs */
+  injectionMode: InjectionMode;
   /** Extra ignore patterns */
   ignorePatterns: string[];
 }
@@ -61,6 +64,7 @@ const DEFAULT_CONFIG: MemoryConfig = {
   maxInjectedTokens: 1000,
   scoreThreshold: 0.3,
   crossProjectEnabled: false,
+  injectionMode: "auto",
   ignorePatterns: [],
 };
 
@@ -80,6 +84,9 @@ export function getConfig(cwd: string = process.cwd()): MemoryConfig {
       const settings = JSON.parse(raw);
       if (settings.memory) {
         const config = { ...DEFAULT_CONFIG, ...settings.memory };
+        if (config.injectionMode !== "auto" && config.injectionMode !== "manual") {
+          config.injectionMode = DEFAULT_CONFIG.injectionMode;
+        }
         _configCache.set(cacheKey, config);
         return config;
       }

package/src/db/index.ts

@@ -242,11 +242,15 @@ export function upsertRecord(record: {
   status?: RecordStatus;
   confidence?: number;
   importance?: number;
+  created_at?: number;
+  updated_at?: number;
   superseded_by?: string | null;
   derived_from_memory_refs?: string | null;
 }): string {
   const db = getDb();
   const now = Date.now();
+  const createdAt = record.created_at ?? now;
+  const updatedAt = record.updated_at ?? now;
   const scope = record.scope ?? "project";
   const projectId = scope === "global" ? null : (record.project_id ?? null);
   const redactedText = redactSecrets(record.text);
@@ -276,7 +280,7 @@ export function upsertRecord(record: {
       redactedTags,
       record.confidence ?? 1.0,
       record.importance ?? 0.5,
-      now,
+      updatedAt,
       record.status ?? existing.status,
       record.superseded_by ?? null,
       record.derived_from_memory_refs ?? null,
@@ -303,8 +307,8 @@ export function upsertRecord(record: {
       record.status ?? "active",
       record.confidence ?? 1.0,
       record.importance ?? 0.5,
-      now,
-      now,
+      createdAt,
+      updatedAt,
       record.superseded_by ?? null,
       record.derived_from_memory_refs ?? null,
     );
@@ -331,6 +335,14 @@ export function getRecord(id: string): RecordRow | undefined {
   );
 }
 
+export function listRecords(options: { includeInactive?: boolean } = {}): RecordRow[] {
+  const db = getDb();
+  const sql = options.includeInactive
+    ? "SELECT * FROM records ORDER BY created_at ASC, id ASC"
+    : "SELECT * FROM records WHERE status = 'active' ORDER BY created_at ASC, id ASC";
+  return db.prepare(sql).all() as unknown as RecordRow[];
+}
+
 export function searchRecordsFts(
   query: string,
   limit = 20,