pi-hermes-memory 0.7.22 → 0.7.23

package/README.md

@@ -339,6 +339,19 @@ Background review triggers based on **activity level**, not just turn count:
 
 Both counters reset after each review.
 
+### Background Review Transport
+
+By default, background review uses an in-process `completeSimple()` side-channel: a small JSON-only prompt, no child `pi` process, and memory writes applied directly by the extension. This keeps the main session's system prompt, tools, and LLM prefix cache intact.
+
+If direct review fails (no model, no auth, provider error, unparseable response), it automatically falls back to the legacy `pi -p --no-session` subprocess path.
+
+Set `reviewTransport` in config only when you need to override this:
+
+| Value | Behavior |
+|---|---|
+| `direct` (default) | Try in-process `completeSimple()` first; fall back to subprocess on failure |
+| `subprocess` | Always use `pi -p` subprocess (pre-PR #92 behavior) |
+
 ### Skill Auto-Extraction
 
 After a complex task (8+ tool calls using 2+ different tools in a single turn), the extension automatically asks the agent:
@@ -430,6 +443,7 @@ Create `~/.pi/agent/hermes-memory-config.json`:
   "nudgeToolCalls": 15,
   "reviewRecentMessages": 0,
   "reviewEnabled": true,
+  "reviewTransport": "direct",
   "memoryOverflowStrategy": "auto-consolidate",
   "autoConsolidate": true,
   "correctionDetection": true,
@@ -455,12 +469,13 @@ Create `~/.pi/agent/hermes-memory-config.json`:
 | `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/` |
-| `llmModelOverride` | unset | Optional model override for child `pi -p` subprocess calls used by background review, correction save, session flush, and consolidation |
-| `llmThinkingOverride` | unset | Optional thinking override for those child subprocess calls; valid values are `off`, `minimal`, `low`, `medium`, `high`, and `xhigh`. If `llmModelOverride` is set and this is omitted, child calls default to `off` |
+| `llmModelOverride` | unset | Optional model override for background review (direct and subprocess), correction save, session flush, and consolidation |
+| `llmThinkingOverride` | unset | Optional thinking override for those LLM calls; valid values are `off`, `minimal`, `low`, `medium`, `high`, and `xhigh`. If `llmModelOverride` is set and this is omitted, review/child calls default to `off` |
 | `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) |
 | `reviewEnabled` | `true` | Enable/disable background learning loop |
+| `reviewTransport` | `direct` | Background review LLM transport: `direct` uses in-process `completeSimple()` with subprocess fallback; `subprocess` forces legacy `pi -p` only |
 | `memoryOverflowStrategy` | `auto-consolidate` | Behavior when MEMORY.md, USER.md, failures.md, or project-scoped memory reaches its character limit: `auto-consolidate` runs the existing consolidation flow; `reject` returns an error; `fifo-evict` rotates older entries in file order until the new entry fits |
 | `autoConsolidate` | `true` | Legacy alias for `memoryOverflowStrategy` when `memoryOverflowStrategy` is not set (`true` = `auto-consolidate`, `false` = `reject`) |
 | `consolidationTimeoutMs` | `60000` | Maximum time in milliseconds for auto-consolidation to complete |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-hermes-memory",
-  "version": "0.7.22",
+  "version": "0.7.23",
   "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",
@@ -45,6 +45,7 @@
     "url": "https://github.com/chandra447/pi-hermes-memory"
   },
   "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
     "@earendil-works/pi-coding-agent": ">=0.74.0"
   },
   "devDependencies": {

package/src/config.ts

@@ -1,6 +1,6 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
-import type { MemoryConfig, MemoryOverflowStrategy, SessionSearchVariant, ThinkingLevel } from "./types.js";
+import type { MemoryConfig, MemoryOverflowStrategy, ReviewTransport, SessionSearchVariant, ThinkingLevel } from "./types.js";
 import {
   DEFAULT_MEMORY_CHAR_LIMIT,
   DEFAULT_USER_CHAR_LIMIT,
@@ -19,8 +19,13 @@ import { AGENT_ROOT, normalizeConfiguredMemoryDir, normalizeProjectsMemoryDir }
 
 const MEMORY_OVERFLOW_STRATEGIES: readonly MemoryOverflowStrategy[] = ["auto-consolidate", "reject", "fifo-evict"];
 const SESSION_SEARCH_VARIANTS: readonly SessionSearchVariant[] = ["legacy", "anchors"];
+const REVIEW_TRANSPORTS: readonly ReviewTransport[] = ["direct", "subprocess"];
 const THINKING_LEVELS: readonly ThinkingLevel[] = ["off", "minimal", "low", "medium", "high", "xhigh"];
 
+function isReviewTransport(value: unknown): value is ReviewTransport {
+  return typeof value === "string" && REVIEW_TRANSPORTS.includes(value as ReviewTransport);
+}
+
 function isMemoryOverflowStrategy(value: unknown): value is MemoryOverflowStrategy {
   return typeof value === "string" && MEMORY_OVERFLOW_STRATEGIES.includes(value as MemoryOverflowStrategy);
 }
@@ -42,6 +47,7 @@ const DEFAULT_CONFIG: MemoryConfig = {
   nudgeInterval: DEFAULT_NUDGE_INTERVAL,
   reviewRecentMessages: DEFAULT_REVIEW_RECENT_MESSAGES,
   reviewEnabled: true,
+  reviewTransport: "direct",
   flushOnCompact: true,
   flushOnShutdown: true,
   flushMinTurns: DEFAULT_FLUSH_MIN_TURNS,
@@ -91,6 +97,7 @@ export function loadConfig(configPath = DEFAULT_CONFIG_PATH): MemoryConfig {
       if (typeof parsed.nudgeInterval === "number") config.nudgeInterval = parsed.nudgeInterval;
       if (isNonNegativeNumber(parsed.reviewRecentMessages)) config.reviewRecentMessages = parsed.reviewRecentMessages;
       if (typeof parsed.reviewEnabled === "boolean") config.reviewEnabled = parsed.reviewEnabled;
+      if (isReviewTransport(parsed.reviewTransport)) config.reviewTransport = parsed.reviewTransport;
       if (typeof parsed.flushOnCompact === "boolean") config.flushOnCompact = parsed.flushOnCompact;
       if (typeof parsed.flushOnShutdown === "boolean") config.flushOnShutdown = parsed.flushOnShutdown;
       if (typeof parsed.flushMinTurns === "number") config.flushMinTurns = parsed.flushMinTurns;

package/src/constants.ts

@@ -145,6 +145,36 @@ For failures, include: what was tried, why it failed, what error occurred, and w
 
 Only act if there's something genuinely worth saving. If nothing stands out, just say 'Nothing to save.' and stop.`;
 
+// ─── Direct (in-process) background review prompts ───
+export const DIRECT_REVIEW_SYSTEM_PROMPT = `You review coding conversations and extract durable memories worth saving across sessions.
+
+Review these aspects:
+- **Memory**: User persona, preferences, expectations about how the agent should behave, work style.
+- **Failures & Corrections**: What failed, user corrections, insights, conventions, tool quirks.
+
+Do NOT create or modify skills. Only save genuinely durable facts — not task progress, session outcomes, or temporary state.
+
+Respond with JSON only (no markdown fences):
+{
+  "operations": [
+    {
+      "action": "add",
+      "target": "memory",
+      "content": "entry text"
+    }
+  ]
+}
+
+Operation fields:
+- action: "add" | "replace" | "remove"
+- target: "memory" | "user" | "project" | "failure"
+- content: required for add/replace
+- old_text: required for replace/remove (substring match)
+- category: for failure target — failure | correction | insight | convention | tool-quirk | preference
+- failure_reason: optional context for failure entries
+
+If nothing is worth saving, return {"operations":[]}.`;
+
 // ─── Flush prompt (ported from flush_memories() in run_agent.py ~L7379) ───
 export const FLUSH_PROMPT = `[System: The session is being compressed. Save anything worth remembering — prioritize user preferences, corrections, and recurring patterns over task-specific details.]`;
 

package/src/handlers/background-review.ts

@@ -3,23 +3,128 @@
  * Ported from hermes-agent/run_agent.py (_spawn_background_review, _memory_nudge_interval).
  * See PLAN.md → "Hermes Source File Reference Map" for source lines.
  *
- * Uses pi.exec("pi", ["-p", ...]) for isolated one-shot review,
- * keeping us within Pi's intended extension API.
+ * Default transport: in-process complete() side-channel (preserves parent LLM cache).
+ * Fallback: pi.exec("pi", ["-p", ...]) subprocess when direct path is unavailable.
  */
 
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { MemoryStore } from "../store/memory-store.js";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { COMBINED_REVIEW_PROMPT } from "../constants.js";
+import { MemoryStore } from "../store/memory-store.js";
+import { DatabaseManager } from "../store/db.js";
 import type { MemoryConfig } from "../types.js";
 import { applyRecentMessageLimit, collectMessageParts } from "./message-parts.js";
 import { execChildPrompt } from "./pi-child-process.js";
+import { runDirectBackgroundReview, type DirectReviewResult } from "./review-memory-ops.js";
+
+export interface BackgroundReviewOptions {
+  dbManager?: DatabaseManager | null;
+  projectName?: string | null;
+  deps?: BackgroundReviewDeps;
+}
+
+export interface BackgroundReviewDeps {
+  runDirectReview?: typeof runDirectBackgroundReview;
+  execChildPrompt?: typeof execChildPrompt;
+}
+
+export interface ReviewPromptInput {
+  parts: string[];
+  currentMemory: string;
+  currentUser: string;
+  currentProject: string | null;
+}
+
+export function buildSubprocessReviewPrompt(input: ReviewPromptInput): string {
+  const reviewPrompt = [
+    COMBINED_REVIEW_PROMPT,
+    "",
+    "--- Current Memory ---",
+    input.currentMemory || "(empty)",
+    "",
+    "--- Current User Profile ---",
+    input.currentUser || "(empty)",
+  ];
+
+  if (input.currentProject !== null) {
+    reviewPrompt.push(
+      "",
+      "--- Current Project Memory ---",
+      input.currentProject || "(empty)",
+    );
+  }
+
+  reviewPrompt.push(
+    "",
+    "--- Conversation to Review ---",
+    input.parts.join("\n\n"),
+  );
+
+  return reviewPrompt.join("\n");
+}
+
+export function buildDirectReviewUserPrompt(input: ReviewPromptInput): string {
+  const sections = [
+    "--- Current Memory ---",
+    input.currentMemory || "(empty)",
+    "",
+    "--- Current User Profile ---",
+    input.currentUser || "(empty)",
+  ];
+
+  if (input.currentProject !== null) {
+    sections.push(
+      "",
+      "--- Current Project Memory ---",
+      input.currentProject || "(empty)",
+    );
+  }
+
+  sections.push(
+    "",
+    "--- Conversation to Review ---",
+    input.parts.join("\n\n"),
+  );
+
+  return sections.join("\n");
+}
+
+function shouldNotifyDirect(result: DirectReviewResult): boolean {
+  return result.ok && result.appliedCount > 0;
+}
+
+function shouldNotifySubprocess(stdout: string | undefined): boolean {
+  const output = stdout?.trim();
+  return !!output && !output.toLowerCase().includes("nothing to save");
+}
+
+function usesDirectTransport(config: MemoryConfig): boolean {
+  return (config.reviewTransport ?? "direct") === "direct";
+}
+
+async function runSubprocessReview(
+  pi: ExtensionAPI,
+  prompt: string,
+  config: MemoryConfig,
+  execChild: typeof execChildPrompt,
+): Promise<{ code: number; stdout?: string }> {
+  return execChild(pi, prompt, config, {
+    signal: undefined,
+    timeoutMs: 120000,
+  });
+}
 
 export function setupBackgroundReview(
   pi: ExtensionAPI,
   store: MemoryStore,
   projectStore: MemoryStore | null,
   config: MemoryConfig,
+  options: BackgroundReviewOptions = {},
 ): void {
+  const dbManager = options.dbManager ?? null;
+  const projectName = options.projectName ?? null;
+  const runDirectReview = options.deps?.runDirectReview ?? runDirectBackgroundReview;
+  const execChild = options.deps?.execChildPrompt ?? execChildPrompt;
+
   let turnsSinceReview = 0;
   let toolCallsSinceReview = 0;
   let userTurnCount = 0;
@@ -37,9 +142,6 @@ export function setupBackgroundReview(
     if (!config.reviewEnabled) return;
     if (reviewInProgress) return;
 
-    // Count tool calls from this turn's message only (not cumulative branch scan —
-    // otherwise the counter resets to 0 at review, then immediately re-counts all
-    // historical tool calls and re-triggers on every subsequent turn).
     try {
       const msg = event.message;
       if (msg?.role === "assistant") {
@@ -56,7 +158,6 @@ export function setupBackgroundReview(
       // If we can't count tool calls, fall back to turn-based only
     }
 
-    // Trigger on EITHER turn count OR tool call count
     const turnThresholdMet = turnsSinceReview >= config.nudgeInterval;
     const toolCallThresholdMet = toolCallsSinceReview >= config.nudgeToolCalls;
 
@@ -67,78 +168,71 @@ export function setupBackgroundReview(
     toolCallsSinceReview = 0;
     reviewInProgress = true;
 
-    // Build conversation snapshot from session entries (crash-safe)
     let allParts: string[] = [];
     try {
       const entries = ctx.sessionManager.getBranch();
       allParts = collectMessageParts(entries);
     } catch {
       reviewInProgress = false;
-      return; // Session expired or empty — nothing to review
+      return;
     }
     if (allParts.length < 4) {
       reviewInProgress = false;
-      return; // Not enough conversation to review
+      return;
     }
+
     const parts = applyRecentMessageLimit(allParts, config.reviewRecentMessages);
+    const promptInput: ReviewPromptInput = {
+      parts,
+      currentMemory: store.getMemoryEntries().join("\n§\n"),
+      currentUser: store.getUserEntries().join("\n§\n"),
+      currentProject: projectStore ? projectStore.getMemoryEntries().join("\n§\n") : null,
+    };
 
-    const currentMemory = store.getMemoryEntries().join("\n§\n");
-    const currentUser = store.getUserEntries().join("\n§\n");
-    const currentProject = projectStore ? projectStore.getMemoryEntries().join("\n§\n") : null;
+    const subprocessPrompt = buildSubprocessReviewPrompt(promptInput);
+    const directPrompt = buildDirectReviewUserPrompt(promptInput);
 
-    const reviewPrompt = [
-      COMBINED_REVIEW_PROMPT,
-      "",
-      "--- Current Memory ---",
-      currentMemory || "(empty)",
-      "",
-      "--- Current User Profile ---",
-      currentUser || "(empty)",
-    ];
-
-    if (currentProject !== null) {
-      reviewPrompt.push(
-        "",
-        "--- Current Project Memory ---",
-        currentProject || "(empty)",
-      );
-    }
+    const finishReview = () => {
+      reviewInProgress = false;
+    };
 
-    reviewPrompt.push(
-      "",
-      "--- Conversation to Review ---",
-      parts.join("\n\n"),
-    );
+    const notifyIfSaved = (saved: boolean) => {
+      if (saved) {
+        ctx.ui.notify("💾 Memory auto-reviewed and updated", "info");
+      }
+    };
+
+    const runReview = async (): Promise<void> => {
+      if (usesDirectTransport(config)) {
+        const directResult = await runDirectReview(
+          ctx as Pick<ExtensionContext, "model" | "modelRegistry">,
+          store,
+          projectStore,
+          { userPrompt: directPrompt, config, timeoutMs: 120000 },
+          dbManager,
+          projectName,
+        );
+
+        if (directResult.ok) {
+          notifyIfSaved(shouldNotifyDirect(directResult));
+          return;
+        }
 
-    // Fire-and-forget: do NOT await. The review runs in a subprocess;
-    // blocking turn_end would freeze the interactive chat.
-    // Notifications are delivered via .then() once the subprocess completes.
-    //
-    // We intentionally omit ctx.signal — the signal is tied to the turn
-    // lifetime and would abort the subprocess before it finishes now that
-    // we're not awaiting. The timeout (120s) provides its own safety net.
-    const reviewPromise = execChildPrompt(pi, reviewPrompt.join("\n"), config, {
-      signal: undefined,
-      timeoutMs: 120000,
-    });
-
-    reviewPromise
-      .then((result) => {
-        reviewInProgress = false;
-        if (result.code === 0 && result.stdout) {
-          const output = result.stdout.trim();
-          if (output && !output.toLowerCase().includes("nothing to save")) {
-            ctx.ui.notify("💾 Memory auto-reviewed and updated", "info");
-          }
+        if (directResult.fallbackReason === "empty") {
+          return;
         }
-        // Auto-review is best-effort. Non-zero exits are silently skipped —
-        // common on Windows where pi CLI may resolve differently. The next
-        // review cycle will retry.
-      })
+      }
+
+      const subprocessResult = await runSubprocessReview(pi, subprocessPrompt, config, execChild);
+      if (subprocessResult.code === 0) {
+        notifyIfSaved(shouldNotifySubprocess(subprocessResult.stdout));
+      }
+    };
+
+    runReview()
       .catch(() => {
-        // Best-effort: subprocess failures (timeout, signal, spawn errors)
-        // are silently ignored. The next review cycle will retry.
-        reviewInProgress = false;
-      });
+        // Best-effort only
+      })
+      .finally(finishReview);
   });
-}
+}

package/src/handlers/review-memory-ops.ts

@@ -0,0 +1,481 @@
+/**
+ * Parse and apply structured memory operations from direct background review.
+ */
+
+import type { Api, Model } from "@earendil-works/pi-ai";
+import { completeSimple, type Message, type SimpleStreamOptions } from "@earendil-works/pi-ai/compat";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { DIRECT_REVIEW_SYSTEM_PROMPT } from "../constants.js";
+import { MemoryStore } from "../store/memory-store.js";
+import { DatabaseManager } from "../store/db.js";
+import {
+  formatFailureMemoryContent,
+  removeExactSyncedMemories,
+  removeSyncedMemories,
+  replaceSyncedMemories,
+  syncMemoryEntry,
+} from "../store/sqlite-memory-store.js";
+import type { MemoryCategory, MemoryConfig, MemoryResult, ThinkingLevel } from "../types.js";
+
+export interface ReviewMemoryOperation {
+  action: "add" | "replace" | "remove";
+  target: "memory" | "user" | "project" | "failure";
+  content?: string;
+  old_text?: string;
+  category?: MemoryCategory;
+  failure_reason?: string;
+}
+
+export interface ApplyReviewOperationsResult {
+  appliedCount: number;
+  skippedCount: number;
+}
+
+export interface DirectReviewResult {
+  ok: boolean;
+  appliedCount: number;
+  fallbackReason?: "no_model" | "no_auth" | "aborted" | "parse_error" | "provider_error" | "empty";
+  error?: string;
+}
+
+export interface RunDirectBackgroundReviewOptions {
+  userPrompt: string;
+  config: Pick<MemoryConfig, "llmModelOverride" | "llmThinkingOverride">;
+  timeoutMs?: number;
+  signal?: AbortSignal;
+}
+
+type ReviewLlmConfig = Pick<MemoryConfig, "llmModelOverride" | "llmThinkingOverride">;
+
+function findExactModelReferenceMatch(modelReference: string, availableModels: Model<Api>[]): Model<Api> | undefined {
+  const trimmedReference = modelReference.trim();
+  if (!trimmedReference) return undefined;
+
+  const normalizedReference = trimmedReference.toLowerCase();
+  const canonicalMatches = availableModels.filter(
+    (model) => `${model.provider}/${model.id}`.toLowerCase() === normalizedReference,
+  );
+  if (canonicalMatches.length === 1) return canonicalMatches[0];
+  if (canonicalMatches.length > 1) return undefined;
+
+  const slashIndex = trimmedReference.indexOf("/");
+  if (slashIndex !== -1) {
+    const provider = trimmedReference.substring(0, slashIndex).trim();
+    const modelId = trimmedReference.substring(slashIndex + 1).trim();
+    if (provider && modelId) {
+      const providerMatches = availableModels.filter(
+        (model) => model.provider.toLowerCase() === provider.toLowerCase()
+          && model.id.toLowerCase() === modelId.toLowerCase(),
+      );
+      if (providerMatches.length === 1) return providerMatches[0];
+    }
+  }
+
+  const idMatches = availableModels.filter((model) => model.id.toLowerCase() === normalizedReference);
+  return idMatches.length === 1 ? idMatches[0] : undefined;
+}
+
+function normalizedModelOverride(config: ReviewLlmConfig): string | undefined {
+  const trimmed = config.llmModelOverride?.trim();
+  return trimmed ? trimmed : undefined;
+}
+
+function effectiveThinkingOverride(config: ReviewLlmConfig): ThinkingLevel | undefined {
+  return config.llmThinkingOverride ?? (normalizedModelOverride(config) ? "off" : undefined);
+}
+
+type ReviewModelRegistry = ExtensionContext["modelRegistry"];
+
+export function buildDirectReviewCompletionOptions(
+  model: Model<Api>,
+  auth: {
+    apiKey: string;
+    headers?: Record<string, string>;
+    env?: Record<string, string>;
+  },
+  thinking: ThinkingLevel | undefined,
+  signal: AbortSignal,
+): SimpleStreamOptions {
+  const options: SimpleStreamOptions = {
+    apiKey: auth.apiKey,
+    headers: auth.headers,
+    env: auth.env,
+    signal,
+  };
+  if (model.reasoning && thinking && thinking !== "off") {
+    options.reasoning = thinking;
+  }
+  return options;
+}
+
+export function resolveReviewModel(
+  ctxModel: Model<Api> | undefined,
+  modelRegistry: ReviewModelRegistry,
+  config: ReviewLlmConfig,
+): Model<Api> | undefined {
+  const override = normalizedModelOverride(config);
+  if (override) {
+    const matched = findExactModelReferenceMatch(override, modelRegistry.getAll());
+    if (matched) return matched;
+  }
+  return ctxModel;
+}
+
+function extractJsonPayload(text: string): unknown {
+  const trimmed = text.trim();
+  if (!trimmed) return null;
+
+  try {
+    return JSON.parse(trimmed);
+  } catch {
+    // continue
+  }
+
+  const fenced = trimmed.match(/```(?:json)?\s*([\s\S]*?)```/i);
+  if (fenced?.[1]) {
+    try {
+      return JSON.parse(fenced[1].trim());
+    } catch {
+      // continue
+    }
+  }
+
+  const start = trimmed.indexOf("{");
+  const end = trimmed.lastIndexOf("}");
+  if (start >= 0 && end > start) {
+    try {
+      return JSON.parse(trimmed.slice(start, end + 1));
+    } catch {
+      return null;
+    }
+  }
+
+  return null;
+}
+
+function isMemoryCategory(value: unknown): value is MemoryCategory {
+  return value === "failure"
+    || value === "correction"
+    || value === "insight"
+    || value === "preference"
+    || value === "convention"
+    || value === "tool-quirk";
+}
+
+function isReviewTarget(value: unknown): value is ReviewMemoryOperation["target"] {
+  return value === "memory" || value === "user" || value === "project" || value === "failure";
+}
+
+function isReviewAction(value: unknown): value is ReviewMemoryOperation["action"] {
+  return value === "add" || value === "replace" || value === "remove";
+}
+
+export function parseReviewOperations(text: string): ReviewMemoryOperation[] | null {
+  if (/nothing to save/i.test(text) && !text.includes("{")) {
+    return [];
+  }
+
+  const payload = extractJsonPayload(text);
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
+    return null;
+  }
+
+  const operations = (payload as { operations?: unknown }).operations;
+  if (!Array.isArray(operations)) return null;
+
+  const parsed: ReviewMemoryOperation[] = [];
+  for (const item of operations) {
+    if (!item || typeof item !== "object") continue;
+    const op = item as Record<string, unknown>;
+    if (!isReviewAction(op.action) || !isReviewTarget(op.target)) continue;
+
+    const operation: ReviewMemoryOperation = {
+      action: op.action,
+      target: op.target,
+    };
+    if (typeof op.content === "string") operation.content = op.content;
+    if (typeof op.old_text === "string") operation.old_text = op.old_text;
+    if (isMemoryCategory(op.category)) operation.category = op.category;
+    if (typeof op.failure_reason === "string") operation.failure_reason = op.failure_reason;
+    parsed.push(operation);
+  }
+
+  return parsed;
+}
+
+function sqliteProjectFor(
+  rawTarget: ReviewMemoryOperation["target"],
+  projectName?: string | null,
+): string | null | undefined {
+  if (rawTarget === "project") return projectName?.trim() || null;
+  if (rawTarget === "memory" || rawTarget === "user" || rawTarget === "failure") return null;
+  return undefined;
+}
+
+function sqliteTargetFor(rawTarget: ReviewMemoryOperation["target"]): "memory" | "user" | "failure" {
+  return rawTarget === "user" ? "user" : rawTarget === "failure" ? "failure" : "memory";
+}
+
+async function syncAdd(
+  rawTarget: ReviewMemoryOperation["target"],
+  content: string,
+  category: MemoryCategory | undefined,
+  failureReason: string | undefined,
+  dbManager: DatabaseManager | null,
+  projectName?: string | null,
+): Promise<void> {
+  if (!dbManager) return;
+
+  const sqliteTarget = sqliteTargetFor(rawTarget);
+  const sqliteProject = sqliteProjectFor(rawTarget, projectName);
+
+  if (rawTarget === "failure") {
+    const failureCategory = category ?? "failure";
+    syncMemoryEntry(dbManager, {
+      content: formatFailureMemoryContent(content, {
+        category: failureCategory,
+        failureReason,
+      }),
+      target: "failure",
+      project: sqliteProject ?? null,
+      category: failureCategory,
+      failureReason,
+    });
+    return;
+  }
+
+  syncMemoryEntry(dbManager, {
+    content,
+    target: sqliteTarget,
+    project: sqliteProject ?? null,
+  });
+}
+
+async function syncReplace(
+  rawTarget: ReviewMemoryOperation["target"],
+  oldText: string,
+  newContent: string,
+  dbManager: DatabaseManager | null,
+  projectName?: string | null,
+): Promise<void> {
+  if (!dbManager) return;
+  replaceSyncedMemories(dbManager, oldText, {
+    content: newContent,
+    target: sqliteTargetFor(rawTarget),
+    project: sqliteProjectFor(rawTarget, projectName),
+  });
+}
+
+async function syncRemove(
+  rawTarget: ReviewMemoryOperation["target"],
+  oldText: string,
+  dbManager: DatabaseManager | null,
+  projectName?: string | null,
+): Promise<void> {
+  if (!dbManager) return;
+  removeSyncedMemories(dbManager, oldText, {
+    target: sqliteTargetFor(rawTarget),
+    project: sqliteProjectFor(rawTarget, projectName),
+  });
+}
+
+async function syncEvictions(
+  rawTarget: ReviewMemoryOperation["target"],
+  evictedEntries: string[] | undefined,
+  dbManager: DatabaseManager | null,
+  projectName?: string | null,
+): Promise<void> {
+  if (!dbManager || !evictedEntries?.length) return;
+  for (const entry of evictedEntries) {
+    try {
+      removeExactSyncedMemories(dbManager, entry, {
+        target: sqliteTargetFor(rawTarget),
+        project: sqliteProjectFor(rawTarget, projectName),
+      });
+    } catch {
+      // best effort
+    }
+  }
+}
+
+export async function applyReviewOperations(
+  store: MemoryStore,
+  projectStore: MemoryStore | null,
+  operations: ReviewMemoryOperation[],
+  dbManager: DatabaseManager | null = null,
+  projectName?: string | null,
+): Promise<ApplyReviewOperationsResult> {
+  let appliedCount = 0;
+  let skippedCount = 0;
+
+  for (const op of operations) {
+    if (op.target === "project" && !projectStore) {
+      skippedCount++;
+      continue;
+    }
+
+    const rawTarget = op.target;
+    const memoryTarget = rawTarget === "project" ? "memory" : rawTarget === "failure" ? "failure" : rawTarget;
+    const activeStore = rawTarget === "project" ? projectStore! : store;
+
+    let result: MemoryResult;
+    switch (op.action) {
+      case "add": {
+        if (!op.content?.trim()) {
+          skippedCount++;
+          continue;
+        }
+        if (rawTarget === "failure") {
+          const category = op.category ?? "failure";
+          result = await activeStore.addFailure(op.content, {
+            category,
+            failureReason: op.failure_reason,
+          });
+          if (result.success) {
+            await syncAdd(rawTarget, op.content, category, op.failure_reason, dbManager, projectName);
+            appliedCount++;
+          } else {
+            skippedCount++;
+          }
+        } else {
+          result = await activeStore.add(memoryTarget, op.content);
+          if (result.success) {
+            await syncEvictions(rawTarget, result.evicted_entries, dbManager, projectName);
+            await syncAdd(rawTarget, op.content, undefined, undefined, dbManager, projectName);
+            appliedCount++;
+          } else {
+            skippedCount++;
+          }
+        }
+        break;
+      }
+      case "replace": {
+        if (!op.old_text || !op.content?.trim()) {
+          skippedCount++;
+          continue;
+        }
+        result = await activeStore.replace(memoryTarget, op.old_text, op.content);
+        if (result.success) {
+          await syncReplace(rawTarget, op.old_text, op.content, dbManager, projectName);
+          appliedCount++;
+        } else {
+          skippedCount++;
+        }
+        break;
+      }
+      case "remove": {
+        if (!op.old_text) {
+          skippedCount++;
+          continue;
+        }
+        result = await activeStore.remove(memoryTarget, op.old_text);
+        if (result.success) {
+          await syncRemove(rawTarget, op.old_text, dbManager, projectName);
+          appliedCount++;
+        } else {
+          skippedCount++;
+        }
+        break;
+      }
+      default:
+        skippedCount++;
+    }
+  }
+
+  return { appliedCount, skippedCount };
+}
+
+function responseText(content: unknown): string {
+  if (!Array.isArray(content)) return "";
+  return content
+    .filter((block): block is { type: "text"; text: string } => (
+      !!block && typeof block === "object" && (block as { type?: string }).type === "text"
+    ))
+    .map((block) => block.text)
+    .join("\n");
+}
+
+export async function runDirectBackgroundReview(
+  ctx: Pick<ExtensionContext, "model" | "modelRegistry">,
+  store: MemoryStore,
+  projectStore: MemoryStore | null,
+  options: RunDirectBackgroundReviewOptions,
+  dbManager: DatabaseManager | null = null,
+  projectName?: string | null,
+): Promise<DirectReviewResult> {
+  const model = resolveReviewModel(ctx.model, ctx.modelRegistry, options.config);
+  if (!model) {
+    return { ok: false, appliedCount: 0, fallbackReason: "no_model" };
+  }
+
+  const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
+  if (!auth.ok || !auth.apiKey) {
+    return {
+      ok: false,
+      appliedCount: 0,
+      fallbackReason: "no_auth",
+      error: auth.ok ? `No API key for ${model.provider}` : auth.error,
+    };
+  }
+
+  const controller = new AbortController();
+  const timeoutMs = options.timeoutMs ?? 120000;
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
+  if (options.signal) {
+    options.signal.addEventListener("abort", () => controller.abort(), { once: true });
+  }
+
+  const thinking = effectiveThinkingOverride(options.config);
+  const userMessage: Message = {
+    role: "user",
+    content: [{ type: "text", text: options.userPrompt }],
+    timestamp: Date.now(),
+  };
+
+  try {
+    const response = await completeSimple(
+      model,
+      { systemPrompt: DIRECT_REVIEW_SYSTEM_PROMPT, messages: [userMessage] },
+      buildDirectReviewCompletionOptions(
+        model,
+        { apiKey: auth.apiKey, headers: auth.headers, env: auth.env },
+        thinking,
+        controller.signal,
+      ),
+    );
+
+    if (response.stopReason === "aborted") {
+      return { ok: false, appliedCount: 0, fallbackReason: "aborted" };
+    }
+
+    const text = responseText(response.content);
+    const operations = parseReviewOperations(text);
+    if (operations === null) {
+      return { ok: false, appliedCount: 0, fallbackReason: "parse_error" };
+    }
+    if (operations.length === 0) {
+      return { ok: true, appliedCount: 0, fallbackReason: "empty" };
+    }
+
+    const { appliedCount } = await applyReviewOperations(
+      store,
+      projectStore,
+      operations,
+      dbManager,
+      projectName,
+    );
+    return { ok: true, appliedCount };
+  } catch (err) {
+    if (controller.signal.aborted) {
+      return { ok: false, appliedCount: 0, fallbackReason: "aborted" };
+    }
+    return {
+      ok: false,
+      appliedCount: 0,
+      fallbackReason: "provider_error",
+      error: err instanceof Error ? err.message : String(err),
+    };
+  } finally {
+    clearTimeout(timeout);
+  }
+}

package/src/index.ts

@@ -188,7 +188,10 @@ export default function (pi: ExtensionAPI) {
   registerSkillTool(pi, skillStore);
 
   // ── 5. Setup background learning loop (with tool-call-aware nudge) ──
-  setupBackgroundReview(pi, store, projectStore, config);
+  setupBackgroundReview(pi, store, projectStore, config, {
+    dbManager,
+    projectName: projectName || null,
+  });
 
   // ── 6. Setup session-end flush ──
   setupSessionFlush(pi, store, projectStore, config);

package/src/types.ts

@@ -10,6 +10,8 @@ export type SessionSearchVariant = "legacy" | "anchors";
 
 export type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh";
 
+export type ReviewTransport = "direct" | "subprocess";
+
 export interface SessionSearchConfig {
   /** Session search implementation variant. Default: legacy */
   variant: SessionSearchVariant;
@@ -34,6 +36,8 @@ export interface MemoryConfig {
   reviewRecentMessages?: number;
   /** Enable background learning loop. Default: true */
   reviewEnabled: boolean;
+  /** How background review invokes the LLM. Default: direct */
+  reviewTransport?: ReviewTransport;
   /** Flush memories before compaction. Default: true */
   flushOnCompact: boolean;
   /** Flush memories on session shutdown. Default: true */