pi-memory-stone 0.1.2 → 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,6 +1,6 @@
 {
   "name": "pi-memory-stone",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "type": "module",
   "description": "Global pi extension: preserves and retrieves useful memory across pi sessions",
   "license": "MIT",

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,

package/src/index.ts

@@ -8,7 +8,7 @@
  *  - SQLite schema + migrations
  *  - Deterministic turn_summary and file_activity capture on agent_end
  *  - FTS5 search
- *  - /memory-status, /memory-search, /memory-last commands
+ *  - /memory-status, /memory-search, /memory-open, /memory-inject, /memory-last commands
  *  - memory_search, memory_open, memory_remember, memory_forget tools
  *  - Conservative same-project before_agent_start injection
  */
@@ -19,7 +19,8 @@ import { registerTools } from "./tools/index.js";
 import { indexSessionOnAgentEnd } from "./indexing/index.js";
 import { retrieve, buildInjectionPacket, formatInjectionForLlm } from "./retrieval/index.js";
 import { getProjectId, getConfig, clearProjectCache } from "./config/index.js";
-import { closeDb } from "./db/index.js";
+import { closeDb, getRecord, insertInjection } from "./db/index.js";
+import { getMemorySessionState, manualRecordsToRankedResults } from "./session-state/index.js";
 import { createHash } from "node:crypto";
 
 // ─── Session-scoped state ───────────────────────────────────────────
@@ -72,62 +73,54 @@ export default function (pi: ExtensionAPI) {
       const config = getConfig(ctx.cwd);
       if (!config.enabled) return;
 
-      // Check for session toggle entries before honoring the cached toggle so
-      // /memory-on can re-enable injection after /memory-off in the same session.
-      for (const entry of ctx.sessionManager.getBranch()) {
-        if (
-          entry.type === "custom" &&
-          entry.customType === "memory-stone:session-toggle"
-        ) {
-          const data = entry.data as { enabled?: boolean } | undefined;
-          if (typeof data?.enabled === "boolean") {
-            sessionEnabled = data.enabled;
-          }
-        }
-      }
+      const sessionState = getMemorySessionState(ctx.sessionManager.getBranch());
+      sessionEnabled = sessionState.enabled;
 
       if (!sessionEnabled) return;
 
       const prompt = event.prompt || "";
-      if (!prompt.trim()) return;
-
-      // Hash prompt to detect repeated injections
       const promptHash = createHash("sha256").update(prompt).digest("hex").slice(0, 12);
-
       const projectId = getProjectId(ctx.cwd);
+      const injectionMode = sessionState.injectionMode ?? config.injectionMode;
+
+      const manualRecords = sessionState.manualRefs
+        .map((ref) => getRecord(ref))
+        .filter((record): record is NonNullable<typeof record> => Boolean(record));
+      const manualResults = manualRecordsToRankedResults(manualRecords, projectId);
+      const manualRefSet = new Set(manualResults.map((r) => r.record.id));
+
+      let autoResults: ReturnType<typeof retrieve> = [];
+      if (injectionMode === "auto" && prompt.trim()) {
+        const results = retrieve(prompt, projectId, [], {
+          limit: config.maxInjectedRecords,
+          crossProjectEnabled: config.crossProjectEnabled,
+        });
+
+        autoResults = results
+          .filter((r) => !manualRefSet.has(r.record.id))
+          .filter((r) => !injectedRefsThisSession.has(r.record.id))
+          .filter((r) => r.score >= config.scoreThreshold);
+      }
 
-      // Build search query
-      const results = retrieve(prompt, projectId, [], {
-        limit: config.maxInjectedRecords,
-        crossProjectEnabled: config.crossProjectEnabled,
-      });
-
-      // Filter: skip already-injected refs
-      const newResults = results.filter((r) => !injectedRefsThisSession.has(r.record.id));
-
-      // Score threshold
-      const thresholdResults = newResults.filter((r) => r.score >= config.scoreThreshold);
-
-      if (thresholdResults.length === 0) return;
+      const selectedResults = [...manualResults, ...autoResults];
+      if (selectedResults.length === 0) return;
 
-      // Build and format injection packet
-      const packet = buildInjectionPacket(thresholdResults);
+      const packet = buildInjectionPacket(selectedResults);
       const formatted = formatInjectionForLlm(packet, config.maxInjectedTokens);
 
-      // Track injected refs (prevent feedback loop)
-      for (const r of thresholdResults) {
+      // Track only search-selected refs. Manually chosen refs are intentionally
+      // injected on every turn until /memory-clear-injected is used.
+      for (const r of autoResults) {
         injectedRefsThisSession.add(r.record.id);
       }
 
-      // Log injection to DB
-      const { insertInjection } = await import("./db/index.js");
       insertInjection({
         session_id: ctx.sessionManager.getSessionId(),
         turn_entry_id: ctx.sessionManager.getLeafId() ?? undefined,
         prompt_hash: promptHash,
-        injected_refs: thresholdResults.map((r) => r.record.id).join(","),
+        injected_refs: selectedResults.map((r) => r.record.id).join(","),
         packet: formatted,
-        reasons: thresholdResults.map((r) => r.reasons.join(";")).join(" | "),
+        reasons: selectedResults.map((r) => r.reasons.join(";")).join(" | "),
       });
 
       // Inject as a non-context audit custom entry (separate from LLM context)
@@ -156,17 +149,7 @@ export default function (pi: ExtensionAPI) {
       sessionEnabled = true;
 
       // Restore session toggle from branch
-      for (const entry of ctx.sessionManager.getBranch()) {
-        if (
-          entry.type === "custom" &&
-          entry.customType === "memory-stone:session-toggle"
-        ) {
-          const data = entry.data as { enabled?: boolean } | undefined;
-          if (typeof data?.enabled === "boolean") {
-            sessionEnabled = data.enabled;
-          }
-        }
-      }
+      sessionEnabled = getMemorySessionState(ctx.sessionManager.getBranch()).enabled;
 
       // Clear project ID cache on session change
       clearProjectCache();

package/src/portable/index.ts

@@ -0,0 +1,204 @@
+/**
+ * Portable export/import/backup helpers for memory records.
+ */
+
+import { copyFileSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, resolve } from "node:path";
+import { getDb, getDbPath, listRecords, upsertRecord, type RecordRow } from "../db/index.js";
+import { SCHEMA_VERSION, RECORD_KINDS, RECORD_SCOPES, RECORD_STATUSES, type RecordKind, type RecordScope, type RecordStatus } from "../db/schema.js";
+
+export type ExportFormat = "json" | "md";
+
+export interface PortableMemoryRecord {
+  id: string;
+  kind: RecordKind;
+  scope: RecordScope;
+  project_id: string | null;
+  text: string;
+  tags: string | null;
+  status: RecordStatus;
+  confidence: number;
+  importance: number;
+  created_at: number;
+  updated_at: number;
+  superseded_by: string | null;
+  derived_from_memory_refs: string | null;
+}
+
+export interface PortableMemoryExport {
+  format: "pi-memory-stone-export";
+  version: 1;
+  exported_at: string;
+  schema_version: number;
+  records: PortableMemoryRecord[];
+}
+
+export interface ImportOptions {
+  /** Remap project-scoped records to this project id. Use undefined to preserve exported project ids. */
+  projectId?: string | null;
+  /** Force every imported record into a scope. */
+  scopeOverride?: RecordScope;
+}
+
+export interface ImportResult {
+  imported: number;
+  skipped: number;
+  ids: string[];
+}
+
+export function buildMemoryExport(includeInactive = false): PortableMemoryExport {
+  return {
+    format: "pi-memory-stone-export",
+    version: 1,
+    exported_at: new Date().toISOString(),
+    schema_version: SCHEMA_VERSION,
+    records: listRecords({ includeInactive }).map(toPortableRecord),
+  };
+}
+
+export function exportMemory(format: ExportFormat, includeInactive = false): string {
+  const payload = buildMemoryExport(includeInactive);
+  if (format === "json") {
+    return JSON.stringify(payload, null, 2) + "\n";
+  }
+
+  return exportMarkdown(payload);
+}
+
+export function writeMemoryExport(path: string, format: ExportFormat, includeInactive = false): number {
+  const payload = buildMemoryExport(includeInactive);
+  const content = format === "json" ? JSON.stringify(payload, null, 2) + "\n" : exportMarkdown(payload);
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, content, "utf8");
+  return payload.records.length;
+}
+
+export function importMemoryJsonFile(path: string, options: ImportOptions = {}): ImportResult {
+  const raw = readFileSync(path, "utf8");
+  return importMemoryJson(raw, options);
+}
+
+export function importMemoryJson(raw: string, options: ImportOptions = {}): ImportResult {
+  const parsed = JSON.parse(raw) as Partial<PortableMemoryExport>;
+  if (parsed.format !== "pi-memory-stone-export" || parsed.version !== 1 || !Array.isArray(parsed.records)) {
+    throw new Error("Unsupported memory export file. Expected pi-memory-stone-export version 1 JSON.");
+  }
+
+  const result: ImportResult = { imported: 0, skipped: 0, ids: [] };
+  for (const candidate of parsed.records) {
+    const record = normalizePortableRecord(candidate);
+    if (!record) {
+      result.skipped += 1;
+      continue;
+    }
+
+    const scope = options.scopeOverride ?? record.scope;
+    const projectId = scope === "global" ? null : (options.projectId !== undefined ? options.projectId : record.project_id);
+    const id = upsertRecord({
+      kind: record.kind,
+      scope,
+      project_id: projectId,
+      text: record.text,
+      tags: record.tags,
+      status: record.status,
+      confidence: record.confidence,
+      importance: record.importance,
+      created_at: record.created_at,
+      updated_at: record.updated_at,
+      superseded_by: record.superseded_by,
+      derived_from_memory_refs: record.derived_from_memory_refs,
+    });
+
+    result.imported += 1;
+    result.ids.push(id);
+  }
+
+  return result;
+}
+
+export function backupMemoryDatabase(path: string): void {
+  mkdirSync(dirname(path), { recursive: true });
+  getDb().exec("PRAGMA wal_checkpoint(TRUNCATE)");
+  copyFileSync(getDbPath(), path);
+}
+
+export function defaultPortablePath(cwd: string, prefix: string, extension: string): string {
+  const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+  return resolve(cwd, `${prefix}-${stamp}.${extension}`);
+}
+
+export function resolvePortablePath(cwd: string, path: string): string {
+  return isAbsolute(path) ? path : resolve(cwd, path);
+}
+
+function toPortableRecord(row: RecordRow): PortableMemoryRecord {
+  return {
+    id: row.id,
+    kind: row.kind,
+    scope: row.scope,
+    project_id: row.project_id,
+    text: row.text,
+    tags: row.tags,
+    status: row.status,
+    confidence: row.confidence,
+    importance: row.importance,
+    created_at: row.created_at,
+    updated_at: row.updated_at,
+    superseded_by: row.superseded_by,
+    derived_from_memory_refs: row.derived_from_memory_refs,
+  };
+}
+
+function exportMarkdown(payload: PortableMemoryExport): string {
+  const lines: string[] = [];
+  lines.push("# Memory Stone Export");
+  lines.push("");
+  lines.push(`Exported: ${payload.exported_at}`);
+  lines.push(`Records: ${payload.records.length}`);
+  lines.push("");
+
+  for (const record of payload.records) {
+    lines.push(`## [${record.kind}] ${record.id}`);
+    lines.push("");
+    lines.push(`- Scope: ${record.scope}`);
+    lines.push(`- Project: ${record.project_id ?? "global"}`);
+    lines.push(`- Status: ${record.status}`);
+    lines.push(`- Importance: ${record.importance}`);
+    lines.push(`- Created: ${new Date(record.created_at).toISOString()}`);
+    if (record.tags) lines.push(`- Tags: ${record.tags}`);
+    lines.push("");
+    lines.push(record.text);
+    lines.push("");
+  }
+
+  return lines.join("\n");
+}
+
+function normalizePortableRecord(candidate: unknown): PortableMemoryRecord | null {
+  if (!candidate || typeof candidate !== "object") return null;
+  const r = candidate as Record<string, unknown>;
+  if (typeof r.text !== "string" || r.text.trim() === "") return null;
+  if (!isStringMember(r.kind, RECORD_KINDS)) return null;
+  if (!isStringMember(r.scope, RECORD_SCOPES)) return null;
+  if (!isStringMember(r.status, RECORD_STATUSES)) return null;
+
+  return {
+    id: typeof r.id === "string" ? r.id : "",
+    kind: r.kind,
+    scope: r.scope,
+    project_id: typeof r.project_id === "string" ? r.project_id : null,
+    text: r.text,
+    tags: typeof r.tags === "string" ? r.tags : null,
+    status: r.status,
+    confidence: typeof r.confidence === "number" ? r.confidence : 1,
+    importance: typeof r.importance === "number" ? r.importance : 0.5,
+    created_at: typeof r.created_at === "number" ? r.created_at : Date.now(),
+    updated_at: typeof r.updated_at === "number" ? r.updated_at : Date.now(),
+    superseded_by: typeof r.superseded_by === "string" ? r.superseded_by : null,
+    derived_from_memory_refs: typeof r.derived_from_memory_refs === "string" ? r.derived_from_memory_refs : null,
+  };
+}
+
+function isStringMember<T extends readonly string[]>(value: unknown, allowed: T): value is T[number] {
+  return typeof value === "string" && (allowed as readonly string[]).includes(value);
+}

package/src/session-state/index.ts

@@ -0,0 +1,88 @@
+import type { RecordRow } from "../db/index.js";
+import type { RankedResult } from "../retrieval/index.js";
+
+export type InjectionMode = "auto" | "manual";
+
+export const SESSION_TOGGLE_ENTRY = "memory-stone:session-toggle";
+export const INJECTION_MODE_ENTRY = "memory-stone:injection-mode";
+export const MANUAL_INJECTION_ENTRY = "memory-stone:manual-injection";
+
+export interface MemorySessionState {
+  enabled: boolean;
+  injectionMode?: InjectionMode;
+  manualRefs: string[];
+}
+
+export function isInjectionMode(value: unknown): value is InjectionMode {
+  return value === "auto" || value === "manual";
+}
+
+export function getMemorySessionState(branch: unknown[]): MemorySessionState {
+  let enabled = true;
+  let injectionMode: InjectionMode | undefined;
+  let manualRefs: string[] = [];
+
+  for (const entry of branch) {
+    if (!isCustomEntry(entry)) continue;
+
+    if (entry.customType === SESSION_TOGGLE_ENTRY) {
+      const data = entry.data as { enabled?: unknown } | undefined;
+      if (typeof data?.enabled === "boolean") {
+        enabled = data.enabled;
+      }
+      continue;
+    }
+
+    if (entry.customType === INJECTION_MODE_ENTRY) {
+      const data = entry.data as { mode?: unknown } | undefined;
+      if (isInjectionMode(data?.mode)) {
+        injectionMode = data.mode;
+      }
+      continue;
+    }
+
+    if (entry.customType === MANUAL_INJECTION_ENTRY) {
+      const data = entry.data as { action?: unknown; refs?: unknown } | undefined;
+      if (data?.action === "clear") {
+        manualRefs = [];
+      } else if (data?.action === "add" && Array.isArray(data.refs)) {
+        for (const ref of data.refs) {
+          if (typeof ref === "string" && ref.trim() && !manualRefs.includes(ref)) {
+            manualRefs.push(ref);
+          }
+        }
+      }
+    }
+  }
+
+  return { enabled, injectionMode, manualRefs };
+}
+
+export function parseRefArgs(args: string): string[] {
+  return (args ?? "")
+    .trim()
+    .split(/\s+/)
+    .map((part) => part.trim())
+    .filter((part) => part.length > 0 && !part.startsWith("--"));
+}
+
+export function isRecordVisibleInProject(record: RecordRow, currentProjectId: string | null): boolean {
+  return record.scope === "global" || record.project_id === null || record.project_id === currentProjectId;
+}
+
+export function manualRecordsToRankedResults(
+  records: RecordRow[],
+  currentProjectId: string | null,
+): RankedResult[] {
+  return records
+    .filter((record) => record.status === "active" && isRecordVisibleInProject(record, currentProjectId))
+    .map((record) => ({
+      record,
+      score: Number.POSITIVE_INFINITY,
+      reasons: ["manual-ref"],
+    }));
+}
+
+function isCustomEntry(entry: unknown): entry is { type?: string; customType?: string; data?: unknown } {
+  return typeof entry === "object" && entry !== null && (entry as { type?: unknown }).type === "custom";
+}