pi-memory-stone 0.1.2 → 0.1.4

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,17 +1,19 @@
 {
   "name": "pi-memory-stone",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "type": "module",
   "description": "Global pi extension: preserves and retrieves useful memory across pi sessions",
   "license": "MIT",
   "keywords": ["pi-package"],
   "files": [
     "src",
+    "skills/**/*",
     "README.md",
     "LICENSE"
   ],
   "pi": {
-    "extensions": ["./src/index.ts"]
+    "extensions": ["./src/index.ts"],
+    "skills": ["./skills"]
   },
   "scripts": {
     "test": "NODE_OPTIONS='--experimental-sqlite' tsx --test test/*.test.ts",

package/skills/pi-memory-stone/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: pi-memory-stone
+description: Persistent cross-session memory for pi via SQLite+FTS5. Remembers past decisions, preferences, turns, and error resolutions across sessions. Use when recalling context from prior sessions, using memory_search/memory_open/memory_remember/memory_forget tools, troubleshooting memory injection, or when user asks about pi-memory-stone, memory stone, session memory, or remembering context.
+---
+
+# Pi Memory Stone
+
+pi-memory-stone indexes session turns into a searchable SQLite+FTS5 database (`~/.pi/agent/memory/memory.db`) and auto-injects relevant past memories into the system prompt before each agent turn.
+
+**Quick check:** `/memory-status` and `/memory-search <query>`.
+
+## Tools
+
+### `memory_search(query, kind?, scope?, limit?)` — find past context
+
+Use **before** answering questions that may have been addressed in past sessions. FTS5-based: include concrete keywords, not abstract concepts. Use `kind` filter for precision: `"decision"`, `"error_resolution"`, `"preference"`, `"task"`, `"turn_summary"`, `"session_summary"`. Use `scope: "global"` for cross-project recall.
+
+**Examples:** `memory_search("database schema user authentication")`, `memory_search("Next.js build error", kind: "error_resolution")`, `memory_search("deployment workflow", scope: "global")`.
+
+### `memory_open(ref)` — full record by ID
+
+Use when an injection packet or search result references a record ID (e.g., `ref=abc123`). Returns full text and metadata. Only shows records visible in current project.
+
+### `memory_remember(kind, text, scope?, tags?, importance?)` — explicit storage
+
+Use **only when the user explicitly asks** to remember something. Defaults to `scope: "project"`. Use `scope: "global"` only when the user says "for all projects". Auto-downgrades to project scope if text appears to contain secrets, hostnames, or internal details.
+
+### `memory_forget(ref, hard?)` — remove stale/wrong memories
+
+Soft-forget hides from future searches. Hard delete (`hard: true`) requires user confirmation via the `/memory-forget --hard` command.
+
+## Ranking (craft better queries)
+
+Hybrid score: FTS match × kind boost × recency decay × confidence × importance, then sorted descending.
+
+| Factor | Boost | Implication |
+|---|---|---|
+| Same-project | ×1.5 | Current project memories rank highest |
+| Kind: decision | ×1.5 | Decisions and errors surface prominently |
+| Kind: error_resolution | ×1.4 | |
+| Kind: preference | ×1.3 | |
+| Recency | Half-life 7 days | Older memories fade; add time hints to queries |
+| Confidence × Importance | 0.5–1.5× | Explicitly remembered items outrank auto-indexed turns |
+
+Queries include the user's first ~200 chars + basenames of recently touched files. Include filenames when searching for file-specific context.
+
+## Injection modes
+
+| Mode | Behavior |
+|---|---|
+| `auto` (default) | FTS5 search every turn + manual refs. Score threshold: 0.3. Auto-injected refs not re-injected (anti-feedback-loop). |
+| `manual` | Only `/memory-inject` refs. Inject every turn until `/memory-clear-injected`. |
+
+Session override (`/memory-mode`) takes precedence over config. Check: `/memory-status`.
+
+## Session state (per-session, persists across turns)
+
+- **enabled** — toggle via `/memory-on` / `/memory-off`
+- **injectionMode** — `auto` or `manual`, via `/memory-mode`, falls back to config
+- **manualRefs** — via `/memory-inject <ref>`, cleared by `/memory-clear-injected`
+
+## Commands quick reference
+
+| Command | Purpose |
+|---|---|
+| `/memory-status [-v]` | Stats, config, effective mode |
+| `/memory-search <q>` | Search (top 20) |
+| `/memory-open <ref>` | Full record |
+| `/memory-inject <ref>...` | Add manual refs for session |
+| `/memory-clear-injected` | Clear manual refs |
+| `/memory-mode <auto\|manual>` | Override injection mode |
+| `/memory-last` | Last injection packet |
+| `/memory-forget <ref> [--hard]` | Soft/hard delete |
+| `/memory-export [path] [--format json\|md] [--all]` | Portable export |
+| `/memory-import <file> [--preserve-project\|--global]` | Import (default: remap to current project) |
+| `/memory-backup [path]` | Backup SQLite DB |
+| `/memory-on` / `/memory-off` | Enable/disable injection |
+
+## Troubleshooting
+
+| Problem | Likely cause | Fix |
+|---|---|---|
+| No memories injected | Score < 0.3 threshold, manual mode, or `/memory-off` | Lower threshold, `/memory-mode auto`, or `/memory-on` |
+| Cross-project memories missing | `crossProjectEnabled: false` in config | Enable in `.pi/settings.json` or `/memory-inject` manually |
+| Search returns nothing | Keywords don't match FTS5, or record soft_forgotten | Use concrete terms; try `/memory-export --all` to find |
+| Global `memory_remember` refused | Text matched as sensitive | The tool auto-downgrades safely; this is expected |
+
+## Config
+
+`.pi/settings.json` in project root (all fields optional, shown with defaults):
+
+```json
+{ "memory": { "enabled": true, "maxInjectedRecords": 5, "maxInjectedTokens": 1000, "scoreThreshold": 0.3, "crossProjectEnabled": false, "injectionMode": "auto" } }
+```
+
+## Privacy guarantees
+
+- All text redacted before storage: API keys, tokens, passwords, connection strings
+- Sensitive paths never indexed: `.env`, keys, certs, `node_modules`, `.git`, `.ssh`, `.aws`
+- Global scope refused for text containing secret/hostname/internal patterns
+- `memory_open` only shows records visible in current project

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");
 
@@ -214,6 +500,12 @@ async function handleMemoryForget(args: string, ctx: ExtensionCommandContext): P
       continue;
     }
 
+    const currentProjectId = getProjectId(ctx.cwd);
+    if (record.status !== "active" || !isRecordVisibleInProject(record, currentProjectId)) {
+      ctx.ui.notify(`Memory record ${refId} is not available.`, "warning");
+      continue;
+    }
+
     if (hardFlag) {
       const confirmed = ctx.hasUI
         ? await ctx.ui.confirm(
@@ -232,3 +524,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;
       }