tinker-agent 2.11.0 → 2.12.0

package/src/memory/memory-coordinator.ts

@@ -1,1274 +0,0 @@
-import path from "node:path";
-import type {
-  CompletedTurnHook,
-  CompletedTurnHookFailure,
-  CompletedTurnHookInput,
-} from "../agent/runtime-session";
-import { throwIfTurnCancelled } from "../agent/turn-cancellation";
-import type { ToolCall } from "../agent/types";
-import type { SessionId } from "../ids/runtime-id";
-import type { ModelContextBudget } from "../model/model-context-profile";
-import type { ModelClient } from "../model/model-client";
-import type { CompletedTurnSnapshot } from "../session/session-store";
-import type {
-  MemoryGetRawResult,
-  MemoryCreateRawResult,
-  MemoryDeleteRawResult,
-  MemorySearchRawResult,
-  MemoryUpdateRawResult,
-  ToolExecutor,
-} from "../tools/types";
-import {
-  boundedMemoryError,
-  MAX_SEARCH_RESULT_SUMMARY_BYTES,
-  MEMORY_CREATE_TOOL_NAME,
-  MEMORY_DELETE_TOOL_NAME,
-  MEMORY_EXTRACTION_QUEUE_CAPACITY,
-  memoryErrorCode,
-  MEMORY_GET_TOOL_NAME,
-  MEMORY_RECALL_CANDIDATE_LIMIT,
-  MEMORY_RRF_K,
-  MEMORY_SEARCH_DIAGNOSTIC_VECTOR_SCORES_LIMIT,
-  MEMORY_SEARCH_LIMIT,
-  MEMORY_SEARCH_TOOL_NAME,
-  MEMORY_UPDATE_TOOL_NAME,
-  MemoryError,
-  boundedMemoryErrorDetail,
-  truncateUtf8,
-  type MemoryEmbeddingConfig,
-  type MemoryExtractionDiagnostic,
-  type MemoryExtractionRejectedCounts,
-  type MemoryFtsMatch,
-  type MemoryGetDiagnostic,
-  type MemoryHybridMatch,
-  type MemoryMutationDiagnostic,
-  type MemoryPaths,
-  type MemoryRecallDegraded,
-  type MemoryRecallPath,
-  type MemorySearchDiagnostic,
-  type MemorySearchMatch,
-  type StoredMemorySummary,
-} from "./contracts";
-import {
-  OpenAICompatibleEmbeddingClient,
-  type MemoryEmbeddingClient,
-} from "./embedding-client";
-import {
-  MemoryExtractionOutputError,
-  MemoryExtractionRequestError,
-  MemoryExtractionSkippedError,
-  MemoryExtractor,
-  type MemoryExtractionResult,
-} from "./memory-extractor";
-import { ExtractedMemoryLog, MemoryLog } from "./memory-log";
-import { createMemoryGetToolExecutor } from "./memory-get-tool";
-import { createMemoryCreateToolExecutor } from "./memory-create-tool";
-import { createMemoryDeleteToolExecutor } from "./memory-delete-tool";
-import { createMemorySearchToolExecutor } from "./memory-search-tool";
-import { createMemoryUpdateToolExecutor } from "./memory-update-tool";
-import { MemoryStore, resolveMemoryPaths } from "./memory-store";
-import { normalizeEmbedding } from "./vector";
-
-type MemoryWorkerTask = {
-  readonly workspaceRoot: string;
-  readonly sessionId: SessionId;
-  readonly turnId: CompletedTurnHookInput["turnId"];
-  readonly extractionEvidenceText: string;
-};
-
-type ActiveMemoryTask = {
-  readonly task: MemoryWorkerTask;
-  readonly controller: AbortController;
-  completion?: Promise<void>;
-};
-
-type MemoryToolSource = {
-  readonly workspaceRoot: string;
-  readonly sessionId: SessionId;
-};
-
-const MEMORY_TOOL_NAMES: readonly string[] = Object.freeze([
-  MEMORY_SEARCH_TOOL_NAME,
-  MEMORY_GET_TOOL_NAME,
-  MEMORY_CREATE_TOOL_NAME,
-  MEMORY_UPDATE_TOOL_NAME,
-  MEMORY_DELETE_TOOL_NAME,
-]);
-
-export type CreateMemoryCoordinatorInput = {
-  readonly paths?: MemoryPaths;
-  readonly embedding: MemoryEmbeddingConfig;
-  readonly extractionContextBudget: ModelContextBudget;
-  readonly createExtractionClient: () => ModelClient;
-  readonly createEmbeddingClient?: () => MemoryEmbeddingClient;
-  readonly clock?: () => string;
-};
-
-export class MemoryCoordinator implements CompletedTurnHook {
-  private accepting = true;
-  private active?: ActiveMemoryTask;
-  private pending: MemoryWorkerTask[] = [];
-
-  private constructor(
-    private readonly store: MemoryStore,
-    private readonly extractor: MemoryExtractor,
-    private readonly embeddingClient: MemoryEmbeddingClient,
-    private readonly log: MemoryLog,
-    private readonly extractedLog: ExtractedMemoryLog,
-    private readonly embeddingDimensions: number,
-    private readonly clock: () => string,
-  ) {}
-
-  static async create(input: CreateMemoryCoordinatorInput): Promise<MemoryCoordinator> {
-    const paths = input.paths ?? resolveMemoryPaths();
-    const log = new MemoryLog(paths.log);
-    const extractedLog = new ExtractedMemoryLog(paths.extractedLog);
-    const store = await MemoryStore.open({
-      paths,
-      embedding: input.embedding,
-      clock: input.clock,
-    });
-    try {
-      const extractionClient = input.createExtractionClient();
-      const embeddingClient =
-        input.createEmbeddingClient?.() ??
-        new OpenAICompatibleEmbeddingClient(input.embedding);
-      return new MemoryCoordinator(
-        store,
-        new MemoryExtractor(extractionClient, input.extractionContextBudget),
-        embeddingClient,
-        log,
-        extractedLog,
-        input.embedding.dimensions,
-        input.clock ?? (() => new Date().toISOString()),
-      );
-    } catch (error) {
-      store.close();
-      throw error;
-    }
-  }
-
-  enqueue(input: CompletedTurnHookInput): void {
-    if (!this.accepting) {
-      throw new MemoryError(
-        "completed_turn_enqueue_failed",
-        "Memory coordinator is shutting down.",
-      );
-    }
-    const extractionEvidenceText = buildExtractionEvidenceText(
-      input.workspaceRoot,
-      input.snapshot,
-    );
-    const task = Object.freeze({
-      workspaceRoot: input.workspaceRoot,
-      sessionId: input.sessionId,
-      turnId: input.turnId,
-      extractionEvidenceText,
-    });
-    if (this.active === undefined) {
-      this.start(task);
-      return;
-    }
-    if (this.pending.length >= MEMORY_EXTRACTION_QUEUE_CAPACITY) {
-      this.pending.shift();
-    }
-    this.pending.push(task);
-  }
-
-  recordFailure(input: CompletedTurnHookFailure): void {
-    void this.log.append(
-      extractionDiagnostic({
-        clock: this.clock,
-        outcome: "failed",
-        reason: input.reason,
-        workspace: input.workspaceRoot,
-        turnId: input.turnId,
-        ms: 0,
-      }),
-    );
-  }
-
-  createSearchToolExecutor(input: {
-    readonly workspaceRoot: string;
-    readonly sessionId: SessionId;
-  }): ToolExecutor {
-    return createMemorySearchToolExecutor({
-      search: (query, keywords, signal) => this.search(query, keywords, signal, input),
-      recordInvalidCall: (invalid) => this.recordInvalidSearch(invalid, input),
-    });
-  }
-
-  createGetToolExecutor(input: {
-    readonly workspaceRoot: string;
-    readonly sessionId: SessionId;
-  }): ToolExecutor {
-    return createMemoryGetToolExecutor({
-      get: (memoryId, signal) => this.get(memoryId, signal, input),
-      recordInvalidCall: () => this.recordInvalidGet(input),
-    });
-  }
-
-  createCreateToolExecutor(input: MemoryToolSource): ToolExecutor {
-    return createMemoryCreateToolExecutor({
-      create: (text, summary, call, signal) =>
-        this.createMemory(text, summary, call, signal, input),
-      recordInvalidCall: (call) => this.recordInvalidMutation("create", call, input),
-    });
-  }
-
-  createUpdateToolExecutor(input: MemoryToolSource): ToolExecutor {
-    return createMemoryUpdateToolExecutor({
-      update: (memoryId, text, summary, call, signal) =>
-        this.updateMemory(memoryId, text, summary, call, signal, input),
-      recordInvalidCall: (call) => this.recordInvalidMutation("update", call, input),
-    });
-  }
-
-  createDeleteToolExecutor(input: MemoryToolSource): ToolExecutor {
-    return createMemoryDeleteToolExecutor({
-      delete: (memoryId, call, signal) =>
-        this.deleteMemory(memoryId, call, signal, input),
-      recordInvalidCall: (call) => this.recordInvalidMutation("delete", call, input),
-    });
-  }
-
-  listStoredMemories(): readonly StoredMemorySummary[] {
-    return this.store.listStoredMemories();
-  }
-
-  dispose(): void {
-    if (!this.accepting) {
-      return;
-    }
-    this.accepting = false;
-    this.pending = [];
-    this.active?.controller.abort(
-      new MemoryError(
-        "memory_coordinator_disposed",
-        "Memory coordinator is shutting down.",
-      ),
-    );
-    this.store.close();
-  }
-
-  private start(task: MemoryWorkerTask): void {
-    const active: ActiveMemoryTask = {
-      task,
-      controller: new AbortController(),
-    };
-    this.active = active;
-    active.completion = Promise.resolve()
-      .then(() => this.processTask(task, active.controller.signal))
-      .catch(() => undefined)
-      .finally(() => {
-        if (this.active !== active) {
-          return;
-        }
-        this.active = undefined;
-        const next = this.accepting ? this.pending.shift() : undefined;
-        if (next !== undefined) {
-          this.start(next);
-        }
-      });
-  }
-
-  private async processTask(
-    task: MemoryWorkerTask,
-    signal: AbortSignal,
-  ): Promise<void> {
-    const startedAt = performance.now();
-    let inputTokens = 0;
-    let returned = 0;
-    let rejected = emptyRejectedCounts();
-
-    let extraction: MemoryExtractionResult;
-    try {
-      extraction = await this.extractor.extract(task.extractionEvidenceText, signal);
-      inputTokens = extraction.inputTokens;
-      returned = extraction.memory === null ? 0 : 1;
-    } catch (error) {
-      if (error instanceof MemoryExtractionSkippedError) {
-        inputTokens = error.inputTokens;
-        await this.log.append(
-          extractionDiagnostic({
-            clock: this.clock,
-            outcome: "skipped",
-            reason: error.code,
-            workspace: task.workspaceRoot,
-            turnId: task.turnId,
-            inputTokens,
-            ms: elapsedMs(startedAt),
-            detail: boundedMemoryErrorDetail(error),
-          }),
-        );
-        return;
-      }
-      if (error instanceof MemoryExtractionOutputError) {
-        inputTokens = error.inputTokens;
-        returned = error.returned;
-        rejected = Object.freeze({ ...rejected, invalid: Math.max(1, returned) });
-      } else if (error instanceof MemoryExtractionRequestError) {
-        inputTokens = error.inputTokens;
-      }
-      await this.log.append(
-        extractionDiagnostic({
-          clock: this.clock,
-          outcome: signal.aborted ? "skipped" : "failed",
-          reason: signal.aborted
-            ? "extraction_cancelled"
-            : memoryErrorCode(error, "extraction_model_failed"),
-          workspace: task.workspaceRoot,
-          turnId: task.turnId,
-          inputTokens,
-          returned,
-          rejected,
-          ms: elapsedMs(startedAt),
-          detail: boundedMemoryErrorDetail(error),
-        }),
-      );
-      return;
-    }
-
-    const candidate = extraction.memory;
-    if (candidate === null) {
-      await this.log.append(
-        extractionDiagnostic({
-          clock: this.clock,
-          outcome: "ok",
-          reason: null,
-          workspace: task.workspaceRoot,
-          turnId: task.turnId,
-          inputTokens,
-          returned,
-          ms: elapsedMs(startedAt),
-        }),
-      );
-      return;
-    }
-
-    if (
-      containsSensitiveMemory(candidate.text) ||
-      containsSensitiveMemory(candidate.summary)
-    ) {
-      rejected = Object.freeze({ ...rejected, secret: 1 });
-      await this.log.append(
-        extractionDiagnostic({
-          clock: this.clock,
-          outcome: "ok",
-          reason: null,
-          workspace: task.workspaceRoot,
-          turnId: task.turnId,
-          inputTokens,
-          returned,
-          rejected,
-          ms: elapsedMs(startedAt),
-        }),
-      );
-      return;
-    }
-
-    let embedding: Float32Array;
-    try {
-      const rawEmbeddings = await this.embeddingClient.embed([candidate.text], signal);
-      if (rawEmbeddings.length !== 1 || rawEmbeddings[0] === undefined) {
-        throw new MemoryError(
-          "memory_embedding_response_invalid",
-          "Embedding response count does not match the memory candidate count.",
-        );
-      }
-      embedding = normalizeEmbedding(rawEmbeddings[0], this.embeddingDimensions);
-    } catch (error) {
-      rejected = Object.freeze({
-        ...rejected,
-        embedding: 1,
-      });
-      await this.log.append(
-        extractionDiagnostic({
-          clock: this.clock,
-          outcome: signal.aborted ? "skipped" : "failed",
-          reason: signal.aborted
-            ? "extraction_cancelled"
-            : memoryErrorCode(error, "memory_embedding_failed"),
-          workspace: task.workspaceRoot,
-          turnId: task.turnId,
-          inputTokens,
-          returned,
-          rejected,
-          ms: elapsedMs(startedAt),
-          detail: boundedMemoryErrorDetail(error),
-        }),
-      );
-      return;
-    }
-
-    try {
-      const result = this.store.insertBatch({
-        workspaceRoot: task.workspaceRoot,
-        sessionId: task.sessionId,
-        turnId: task.turnId,
-        candidates: [
-          {
-            text: candidate.text,
-            summary: candidate.summary,
-            embedding,
-          },
-        ],
-      });
-      rejected = Object.freeze({
-        ...rejected,
-        duplicate: result.duplicate,
-      });
-      if (result.inserted.length > 0) {
-        await this.extractedLog.append({
-          at: result.inserted[0].createdAt,
-          workspace: task.workspaceRoot,
-          turnId: task.turnId,
-          memories: result.inserted,
-        });
-      }
-      await this.log.append(
-        extractionDiagnostic({
-          clock: this.clock,
-          outcome: "ok",
-          reason: null,
-          workspace: task.workspaceRoot,
-          turnId: task.turnId,
-          inputTokens,
-          returned,
-          written: result.written,
-          rejected,
-          ms: elapsedMs(startedAt),
-        }),
-      );
-    } catch (error) {
-      await this.log.append(
-        extractionDiagnostic({
-          clock: this.clock,
-          outcome: signal.aborted ? "skipped" : "failed",
-          reason: signal.aborted
-            ? "extraction_cancelled"
-            : memoryErrorCode(error, "memory_write_failed"),
-          workspace: task.workspaceRoot,
-          turnId: task.turnId,
-          inputTokens,
-          returned,
-          rejected,
-          ms: elapsedMs(startedAt),
-          detail: boundedMemoryErrorDetail(error),
-        }),
-      );
-    }
-  }
-
-  private async createMemory(
-    text: string,
-    summary: string,
-    call: ToolCall,
-    signal: AbortSignal,
-    source: MemoryToolSource,
-  ): Promise<MemoryCreateRawResult> {
-    const startedAt = performance.now();
-    try {
-      throwIfTurnCancelled(signal);
-      if (containsSensitiveMemory(text) || containsSensitiveMemory(summary)) {
-        await this.logMutation({
-          kind: "create",
-          outcome: "failed",
-          reason: "memory_sensitive_rejected",
-          source,
-          call,
-          memoryId: null,
-          startedAt,
-        });
-        return {
-          ok: false,
-          error:
-            "MemoryCreate rejected content that may contain sensitive information.",
-        };
-      }
-
-      let embedding: Float32Array;
-      try {
-        embedding = await this.embedMutationText(text, signal);
-      } catch (error) {
-        if (signal.aborted) {
-          throw error;
-        }
-        await this.logMutation({
-          kind: "create",
-          outcome: "failed",
-          reason: "memory_embedding_failed",
-          source,
-          call,
-          memoryId: null,
-          startedAt,
-        });
-        return {
-          ok: false,
-          error: "MemoryCreate could not generate a memory embedding.",
-        };
-      }
-
-      throwIfTurnCancelled(signal);
-      const result = this.store.insertBatch({
-        workspaceRoot: source.workspaceRoot,
-        sessionId: source.sessionId,
-        turnId: call.turnId,
-        candidates: [{ text, summary, embedding }],
-      });
-      const inserted = result.inserted[0];
-      const existing =
-        inserted === undefined ? this.store.getByTextHash(text) : undefined;
-      const resolved = inserted ?? existing;
-      if (resolved === undefined) {
-        throw new MemoryError(
-          "memory_write_failed",
-          "MemoryCreate did not produce a stored record.",
-        );
-      }
-      const memoryId = resolved.memoryId;
-      const createdAt = resolved.createdAt;
-      const status = inserted === undefined ? "already_exists" : "created";
-      await this.logMutation({
-        kind: "create",
-        outcome: "ok",
-        reason: null,
-        source,
-        call,
-        memoryId,
-        startedAt,
-      });
-      return { ok: true, status, memoryId, createdAt };
-    } catch (error) {
-      if (signal.aborted) {
-        await this.logMutation({
-          kind: "create",
-          outcome: "skipped",
-          reason: "memory_create_cancelled",
-          source,
-          call,
-          memoryId: null,
-          startedAt,
-        });
-        throw error;
-      }
-      await this.logMutation({
-        kind: "create",
-        outcome: "failed",
-        reason: memoryErrorCode(error, "memory_create_failed"),
-        source,
-        call,
-        memoryId: null,
-        startedAt,
-      });
-      return { ok: false, error: boundedMemoryError(error) };
-    }
-  }
-
-  private async updateMemory(
-    memoryId: string,
-    text: string,
-    summary: string,
-    call: ToolCall,
-    signal: AbortSignal,
-    source: MemoryToolSource,
-  ): Promise<MemoryUpdateRawResult> {
-    const startedAt = performance.now();
-    try {
-      throwIfTurnCancelled(signal);
-      if (containsSensitiveMemory(text) || containsSensitiveMemory(summary)) {
-        await this.logMutation({
-          kind: "update",
-          outcome: "failed",
-          reason: "memory_sensitive_rejected",
-          source,
-          call,
-          memoryId,
-          startedAt,
-        });
-        return {
-          ok: false,
-          error:
-            "MemoryUpdate rejected content that may contain sensitive information.",
-        };
-      }
-
-      const target = this.store.getByIdForMutation(memoryId);
-      if (target === undefined) {
-        await this.logMutation({
-          kind: "update",
-          outcome: "failed",
-          reason: "memory_not_found",
-          source,
-          call,
-          memoryId,
-          startedAt,
-        });
-        return {
-          ok: false,
-          code: "memory_not_found",
-          error: `No global memory exists with id ${memoryId}.`,
-        };
-      }
-
-      let embedding = target.embedding;
-      if (text !== target.text) {
-        try {
-          embedding = await this.embedMutationText(text, signal);
-        } catch (error) {
-          if (signal.aborted) {
-            throw error;
-          }
-          await this.logMutation({
-            kind: "update",
-            outcome: "failed",
-            reason: "memory_embedding_failed",
-            source,
-            call,
-            memoryId,
-            startedAt,
-          });
-          return {
-            ok: false,
-            error: "MemoryUpdate could not generate a memory embedding.",
-          };
-        }
-      }
-
-      throwIfTurnCancelled(signal);
-      const result = this.store.updateMemory({
-        memoryId,
-        text,
-        summary,
-        embedding,
-      });
-      if (!result.ok && result.code === "memory_not_found") {
-        await this.logMutation({
-          kind: "update",
-          outcome: "failed",
-          reason: "memory_not_found",
-          source,
-          call,
-          memoryId,
-          startedAt,
-        });
-        return {
-          ok: false,
-          code: "memory_not_found",
-          error: `No global memory exists with id ${memoryId}.`,
-        };
-      }
-      if (!result.ok && result.code === "memory_duplicate") {
-        await this.logMutation({
-          kind: "update",
-          outcome: "failed",
-          reason: "memory_duplicate",
-          source,
-          call,
-          memoryId,
-          startedAt,
-        });
-        return {
-          ok: false,
-          code: "memory_duplicate",
-          conflictMemoryId: result.conflictMemoryId,
-          error: `Another global memory already has the replacement text (memoryId ${result.conflictMemoryId}).`,
-        };
-      }
-
-      await this.logMutation({
-        kind: "update",
-        outcome: "ok",
-        reason: null,
-        source,
-        call,
-        memoryId,
-        startedAt,
-      });
-      return { ok: true, status: "updated", memoryId };
-    } catch (error) {
-      if (signal.aborted) {
-        await this.logMutation({
-          kind: "update",
-          outcome: "skipped",
-          reason: "memory_update_cancelled",
-          source,
-          call,
-          memoryId,
-          startedAt,
-        });
-        throw error;
-      }
-      await this.logMutation({
-        kind: "update",
-        outcome: "failed",
-        reason: memoryErrorCode(error, "memory_update_failed"),
-        source,
-        call,
-        memoryId,
-        startedAt,
-      });
-      return { ok: false, error: boundedMemoryError(error) };
-    }
-  }
-
-  private async deleteMemory(
-    memoryId: string,
-    call: ToolCall,
-    signal: AbortSignal,
-    source: MemoryToolSource,
-  ): Promise<MemoryDeleteRawResult> {
-    const startedAt = performance.now();
-    try {
-      throwIfTurnCancelled(signal);
-      const result = this.store.deleteMemory(memoryId);
-      if (!result.ok) {
-        await this.logMutation({
-          kind: "delete",
-          outcome: "failed",
-          reason: "memory_not_found",
-          source,
-          call,
-          memoryId,
-          startedAt,
-        });
-        return {
-          ok: false,
-          code: "memory_not_found",
-          error: `No global memory exists with id ${memoryId}.`,
-        };
-      }
-      await this.logMutation({
-        kind: "delete",
-        outcome: "ok",
-        reason: null,
-        source,
-        call,
-        memoryId,
-        startedAt,
-      });
-      return { ok: true, status: "deleted", memoryId };
-    } catch (error) {
-      if (signal.aborted) {
-        await this.logMutation({
-          kind: "delete",
-          outcome: "skipped",
-          reason: "memory_delete_cancelled",
-          source,
-          call,
-          memoryId,
-          startedAt,
-        });
-        throw error;
-      }
-      await this.logMutation({
-        kind: "delete",
-        outcome: "failed",
-        reason: memoryErrorCode(error, "memory_delete_failed"),
-        source,
-        call,
-        memoryId,
-        startedAt,
-      });
-      return { ok: false, error: boundedMemoryError(error) };
-    }
-  }
-
-  private async embedMutationText(
-    text: string,
-    signal: AbortSignal,
-  ): Promise<Float32Array> {
-    const raw = await this.embeddingClient.embed([text], signal);
-    if (raw.length !== 1 || raw[0] === undefined) {
-      throw new MemoryError(
-        "memory_embedding_response_invalid",
-        "Embedding response did not contain the memory vector.",
-      );
-    }
-    return normalizeEmbedding(raw[0], this.embeddingDimensions);
-  }
-
-  private recordInvalidMutation(
-    kind: MemoryMutationDiagnostic["kind"],
-    call: ToolCall,
-    source: MemoryToolSource,
-  ): Promise<void> {
-    return this.logMutation({
-      kind,
-      outcome: "failed",
-      reason: `memory_${kind}_args_invalid`,
-      source,
-      call,
-      memoryId: null,
-      startedAt: performance.now(),
-    });
-  }
-
-  private logMutation(input: {
-    readonly kind: MemoryMutationDiagnostic["kind"];
-    readonly outcome: MemoryMutationDiagnostic["outcome"];
-    readonly reason: string | null;
-    readonly source: MemoryToolSource;
-    readonly call: ToolCall;
-    readonly memoryId: string | null;
-    readonly startedAt: number;
-  }): Promise<void> {
-    return this.log.append(
-      mutationDiagnostic({
-        clock: this.clock,
-        kind: input.kind,
-        outcome: input.outcome,
-        reason: input.reason,
-        workspace: input.source.workspaceRoot,
-        sessionId: input.source.sessionId,
-        turnId: input.call.turnId,
-        toolCallId: input.call.toolCallId,
-        memoryId: input.memoryId,
-        ms: elapsedMs(input.startedAt),
-      }),
-    );
-  }
-
-  private async search(
-    query: string | null,
-    keywords: readonly string[],
-    signal: AbortSignal,
-    source: { readonly workspaceRoot: string; readonly sessionId: SessionId },
-  ): Promise<MemorySearchRawResult> {
-    const startedAt = performance.now();
-    const queryBytes = query === null ? 0 : Buffer.byteLength(query, "utf8");
-    let degraded: MemoryRecallDegraded | null = null;
-    let vectorMatches: readonly MemorySearchMatch[] = [];
-    let ftsMatches: readonly MemoryFtsMatch[] = [];
-    try {
-      if (query !== null) {
-        try {
-          const raw = await this.embeddingClient.embed([query], signal);
-          if (raw.length !== 1 || raw[0] === undefined) {
-            throw new MemoryError(
-              "memory_embedding_response_invalid",
-              "Embedding response did not contain the query vector.",
-            );
-          }
-          const queryEmbedding = normalizeEmbedding(raw[0], this.embeddingDimensions);
-          vectorMatches = this.store.search(
-            queryEmbedding,
-            MEMORY_RECALL_CANDIDATE_LIMIT,
-          );
-        } catch (error) {
-          if (signal.aborted || keywords.length === 0) {
-            throw error;
-          }
-          degraded = "vector";
-        }
-      }
-      if (keywords.length > 0) {
-        try {
-          ftsMatches = this.store.searchFts(keywords, MEMORY_RECALL_CANDIDATE_LIMIT);
-        } catch (error) {
-          if (signal.aborted) {
-            throw error;
-          }
-          const vectorUsable = query !== null && degraded === null;
-          if (!vectorUsable) {
-            throw error;
-          }
-          degraded = "fts";
-        }
-      }
-      const fused = fuseMemoryRecall({ vector: vectorMatches, fts: ftsMatches }).slice(
-        0,
-        MEMORY_SEARCH_LIMIT,
-      );
-      await this.log.append(
-        searchDiagnostic({
-          clock: this.clock,
-          outcome: "ok",
-          reason: null,
-          workspace: source.workspaceRoot,
-          sessionId: source.sessionId,
-          queryBytes,
-          keywordCount: keywords.length,
-          returned: fused.length,
-          vectorReturned: vectorMatches.length,
-          ftsReturned: ftsMatches.length,
-          degraded,
-          scores: fused.map((match) => roundScore(match.score)),
-          vectorScores: vectorMatches
-            .slice(0, MEMORY_SEARCH_DIAGNOSTIC_VECTOR_SCORES_LIMIT)
-            .map((match) => roundScore(match.score)),
-          ms: elapsedMs(startedAt),
-        }),
-      );
-      return {
-        ok: true,
-        degraded,
-        matches: Object.freeze(
-          fused.map((match) =>
-            Object.freeze({
-              memoryId: match.memoryId,
-              text: match.text,
-              summary: truncateUtf8(match.summary, MAX_SEARCH_RESULT_SUMMARY_BYTES),
-              score: match.score,
-              via: match.via,
-              sourceWorkspace: match.sourceWorkspace,
-              sourceSessionId: match.sourceSessionId,
-              createdAt: match.createdAt,
-            }),
-          ),
-        ),
-      };
-    } catch (error) {
-      const reason = signal.aborted
-        ? "memory_search_cancelled"
-        : memoryErrorCode(error, "memory_search_failed");
-      await this.log.append(
-        searchDiagnostic({
-          clock: this.clock,
-          outcome: signal.aborted ? "skipped" : "failed",
-          reason,
-          workspace: source.workspaceRoot,
-          sessionId: source.sessionId,
-          queryBytes,
-          keywordCount: keywords.length,
-          ms: elapsedMs(startedAt),
-        }),
-      );
-      if (signal.aborted) {
-        throw error;
-      }
-      return {
-        ok: false,
-        error: boundedMemoryError(error),
-      };
-    }
-  }
-
-  private recordInvalidSearch(
-    invalid: { readonly queryBytes: number; readonly keywordCount: number },
-    source: { readonly workspaceRoot: string; readonly sessionId: SessionId },
-  ): Promise<void> {
-    return this.log.append(
-      searchDiagnostic({
-        clock: this.clock,
-        outcome: "failed",
-        reason: "memory_search_args_invalid",
-        workspace: source.workspaceRoot,
-        sessionId: source.sessionId,
-        queryBytes: invalid.queryBytes,
-        keywordCount: invalid.keywordCount,
-        ms: 0,
-      }),
-    );
-  }
-
-  private async get(
-    memoryId: string,
-    signal: AbortSignal,
-    source: { readonly workspaceRoot: string; readonly sessionId: SessionId },
-  ): Promise<MemoryGetRawResult> {
-    const startedAt = performance.now();
-    try {
-      signal.throwIfAborted();
-      const record = this.store.getById(memoryId);
-      await this.log.append(
-        getDiagnostic({
-          clock: this.clock,
-          outcome: "ok",
-          reason: null,
-          workspace: source.workspaceRoot,
-          sessionId: source.sessionId,
-          found: record !== undefined,
-          ms: elapsedMs(startedAt),
-        }),
-      );
-      return {
-        ok: true,
-        memory:
-          record === undefined
-            ? null
-            : Object.freeze({
-                memoryId: record.memoryId,
-                text: record.text,
-                summary: record.summary,
-                sourceWorkspace: record.sourceWorkspace,
-                sourceSessionId: record.sourceSessionId,
-                sourceTurnId: record.sourceTurnId,
-                createdAt: record.createdAt,
-              }),
-      };
-    } catch (error) {
-      if (signal.aborted) {
-        throw error;
-      }
-      await this.log.append(
-        getDiagnostic({
-          clock: this.clock,
-          outcome: "failed",
-          reason: memoryErrorCode(error, "memory_get_failed"),
-          workspace: source.workspaceRoot,
-          sessionId: source.sessionId,
-          found: false,
-          ms: elapsedMs(startedAt),
-        }),
-      );
-      return {
-        ok: false,
-        error: boundedMemoryError(error),
-      };
-    }
-  }
-
-  private recordInvalidGet(source: {
-    readonly workspaceRoot: string;
-    readonly sessionId: SessionId;
-  }): Promise<void> {
-    return this.log.append(
-      getDiagnostic({
-        clock: this.clock,
-        outcome: "failed",
-        reason: "memory_get_args_invalid",
-        workspace: source.workspaceRoot,
-        sessionId: source.sessionId,
-        found: false,
-        ms: 0,
-      }),
-    );
-  }
-}
-
-export function buildExtractionEvidenceText(
-  workspaceRoot: string,
-  snapshot: CompletedTurnSnapshot,
-): string {
-  if (!path.isAbsolute(workspaceRoot)) {
-    throw new MemoryError(
-      "completed_turn_enqueue_failed",
-      "Completed turn workspace must be absolute.",
-    );
-  }
-  const messages = snapshot.messages
-    .filter(
-      (message) => message.role !== "tool" || !MEMORY_TOOL_NAMES.includes(message.name),
-    )
-    .map((message) => ({ ...message }));
-  return JSON.stringify(
-    {
-      workspaceRoot,
-      messages,
-    },
-    null,
-    2,
-  );
-}
-
-export function containsSensitiveMemory(text: string): boolean {
-  return [
-    /-----BEGIN [A-Z0-9 ]*PRIVATE KEY-----/i,
-    /\b(?:authorization\s*:\s*)?bearer\s+[a-z0-9._~+/=-]{12,}\b/i,
-    /\b(?:sk-[a-z0-9_-]{12,}|gh[opusr]_[a-z0-9_]{20,}|github_pat_[a-z0-9_]{20,}|AKIA[0-9A-Z]{16}|AIza[0-9A-Za-z_-]{30,})\b/,
-    /\b(?:cookie|session(?:_?token|id)?)\s*[:=]\s*["']?[^\s"',;]{8,}/i,
-    /\b(?:password|passwd|pwd|secret|api[_-]?key|access[_-]?token|refresh[_-]?token)\s*[:=]\s*["']?[^\s"',;]{6,}/i,
-  ].some((pattern) => pattern.test(text));
-}
-
-function extractionDiagnostic(input: {
-  readonly clock: () => string;
-  readonly outcome: MemoryExtractionDiagnostic["outcome"];
-  readonly reason: string | null;
-  readonly workspace: string;
-  readonly turnId: string;
-  readonly ms: number;
-  readonly inputTokens?: number;
-  readonly returned?: number;
-  readonly written?: number;
-  readonly rejected?: MemoryExtractionRejectedCounts;
-  readonly detail?: string;
-}): MemoryExtractionDiagnostic {
-  return Object.freeze({
-    at: input.clock(),
-    kind: "extraction",
-    outcome: input.outcome,
-    reason: input.reason,
-    workspace: input.workspace,
-    turnId: input.turnId,
-    inputTokens: input.inputTokens ?? 0,
-    returned: input.returned ?? 0,
-    written: input.written ?? 0,
-    rejected: input.rejected ?? emptyRejectedCounts(),
-    ms: input.ms,
-    ...(input.detail === undefined ? {} : { detail: input.detail }),
-  });
-}
-
-function searchDiagnostic(input: {
-  readonly clock: () => string;
-  readonly outcome: MemorySearchDiagnostic["outcome"];
-  readonly reason: string | null;
-  readonly workspace: string;
-  readonly sessionId: string;
-  readonly queryBytes: number;
-  readonly keywordCount: number;
-  readonly returned?: number;
-  readonly vectorReturned?: number;
-  readonly ftsReturned?: number;
-  readonly degraded?: MemoryRecallDegraded | null;
-  readonly scores?: readonly number[];
-  readonly vectorScores?: readonly number[];
-  readonly ms: number;
-}): MemorySearchDiagnostic {
-  return Object.freeze({
-    at: input.clock(),
-    kind: "search",
-    outcome: input.outcome,
-    reason: input.reason,
-    workspace: input.workspace,
-    sessionId: input.sessionId,
-    queryBytes: input.queryBytes,
-    keywordCount: input.keywordCount,
-    returned: input.returned ?? 0,
-    vectorReturned: input.vectorReturned ?? 0,
-    ftsReturned: input.ftsReturned ?? 0,
-    degraded: input.degraded ?? null,
-    scores: Object.freeze([...(input.scores ?? [])]),
-    vectorScores: Object.freeze([...(input.vectorScores ?? [])]),
-    ms: input.ms,
-  });
-}
-
-function getDiagnostic(input: {
-  readonly clock: () => string;
-  readonly outcome: MemoryGetDiagnostic["outcome"];
-  readonly reason: string | null;
-  readonly workspace: string;
-  readonly sessionId: string;
-  readonly found: boolean;
-  readonly ms: number;
-}): MemoryGetDiagnostic {
-  return Object.freeze({
-    at: input.clock(),
-    kind: "get",
-    outcome: input.outcome,
-    reason: input.reason,
-    workspace: input.workspace,
-    sessionId: input.sessionId,
-    found: input.found,
-    ms: input.ms,
-  });
-}
-
-function mutationDiagnostic(input: {
-  readonly clock: () => string;
-  readonly kind: MemoryMutationDiagnostic["kind"];
-  readonly outcome: MemoryMutationDiagnostic["outcome"];
-  readonly reason: string | null;
-  readonly workspace: string;
-  readonly sessionId: string;
-  readonly turnId: string;
-  readonly toolCallId: string;
-  readonly memoryId: string | null;
-  readonly ms: number;
-}): MemoryMutationDiagnostic {
-  return Object.freeze({
-    at: input.clock(),
-    kind: input.kind,
-    outcome: input.outcome,
-    reason: input.reason,
-    workspace: input.workspace,
-    sessionId: input.sessionId,
-    turnId: input.turnId,
-    toolCallId: input.toolCallId,
-    memoryId: input.memoryId,
-    ms: input.ms,
-  });
-}
-
-function emptyRejectedCounts(): MemoryExtractionRejectedCounts {
-  return Object.freeze({
-    duplicate: 0,
-    secret: 0,
-    invalid: 0,
-    embedding: 0,
-  });
-}
-
-function elapsedMs(startedAt: number): number {
-  return Math.round((performance.now() - startedAt) * 100) / 100;
-}
-
-function roundScore(score: number): number {
-  return Math.round(score * 1_000) / 1_000;
-}
-
-export function fuseMemoryRecall(input: {
-  readonly vector: readonly MemorySearchMatch[];
-  readonly fts: readonly MemoryFtsMatch[];
-}): readonly MemoryHybridMatch[] {
-  type Entry = {
-    readonly memoryId: string;
-    readonly text: string;
-    readonly summary: string;
-    readonly sourceWorkspace: string;
-    readonly sourceSessionId: string;
-    readonly createdAt: string;
-    score: number;
-    readonly via: Set<MemoryRecallPath>;
-  };
-  const entries = new Map<string, Entry>();
-  const accumulate = (
-    match: {
-      readonly memoryId: string;
-      readonly text: string;
-      readonly summary: string;
-      readonly sourceWorkspace: string;
-      readonly sourceSessionId: string;
-      readonly createdAt: string;
-    },
-    rank: number,
-    path: MemoryRecallPath,
-  ): void => {
-    const contribution = 1 / (MEMORY_RRF_K + rank);
-    const existing = entries.get(match.memoryId);
-    if (existing !== undefined) {
-      existing.score += contribution;
-      existing.via.add(path);
-      return;
-    }
-    entries.set(match.memoryId, {
-      memoryId: match.memoryId,
-      text: match.text,
-      summary: match.summary,
-      sourceWorkspace: match.sourceWorkspace,
-      sourceSessionId: match.sourceSessionId,
-      createdAt: match.createdAt,
-      score: contribution,
-      via: new Set([path]),
-    });
-  };
-  input.vector.forEach((match, index) => accumulate(match, index + 1, "vector"));
-  input.fts.forEach((match, index) => accumulate(match, index + 1, "fts"));
-
-  return Object.freeze(
-    [...entries.values()]
-      .sort(
-        (left, right) =>
-          right.score - left.score ||
-          right.createdAt.localeCompare(left.createdAt) ||
-          left.memoryId.localeCompare(right.memoryId),
-      )
-      .map((entry) =>
-        Object.freeze({
-          memoryId: entry.memoryId,
-          text: entry.text,
-          summary: entry.summary,
-          score: entry.score,
-          via: Object.freeze(
-            (["vector", "fts"] as const).filter((path) => entry.via.has(path)),
-          ),
-          sourceWorkspace: entry.sourceWorkspace,
-          sourceSessionId: entry.sourceSessionId,
-          createdAt: entry.createdAt,
-        }),
-      ),
-  );
-}