@gmickel/gno 1.40.0 → 1.41.0

package/src/sdk/client.ts

@@ -38,7 +38,11 @@ import type {
   GnoMoveNoteOptions,
   GnoMultiGetOptions,
   GnoQueryOptions,
+  GnoRecallInput,
+  GnoRecallResult,
   GnoRefactorNoteResult,
+  GnoRememberInput,
+  GnoRememberResult,
   GnoRenameNoteApplyOptions,
   GnoRenameNoteOptions,
   GnoSearchOptions,
@@ -113,6 +117,11 @@ import {
   listKnowledgeChanges,
   type KnowledgeDeltaServiceResult,
 } from "../core/knowledge-delta";
+import {
+  MemoryError,
+  type MemoryErrorCode,
+  MemoryService,
+} from "../core/memory";
 import { resolveNoteCreatePlan } from "../core/note-creation";
 import { resolveNotePreset } from "../core/note-presets";
 import {
@@ -144,6 +153,7 @@ import {
 } from "../core/sections";
 import { normalizeStructuredQueryInput } from "../core/structured-query";
 import { parseAndValidateTagFilter } from "../core/tags";
+import { writeLeasePath } from "../core/write-lease";
 import {
   defaultSyncService,
   type SyncResult,
@@ -171,7 +181,7 @@ import {
   multiGetDocuments,
 } from "./documents";
 import { runEmbed } from "./embed";
-import { sdkError } from "./errors";
+import { type GnoSdkErrorCode, sdkError } from "./errors";
 
 interface OpenedClientState {
   config: Config;
@@ -295,6 +305,41 @@ async function resolveClientState(
   };
 }
 
+/** SDK error family per memory code; exhaustive so a new code fails to compile. */
+const MEMORY_ERROR_TO_SDK: Readonly<Record<MemoryErrorCode, GnoSdkErrorCode>> =
+  {
+    MEMORY_TEXT_REQUIRED: "VALIDATION",
+    MEMORY_TEXT_TOO_LARGE: "VALIDATION",
+    MEMORY_QUERY_REQUIRED: "VALIDATION",
+    MEMORY_BUDGET_INVALID: "VALIDATION",
+    MEMORY_COLLECTION_REQUIRED: "VALIDATION",
+    MEMORY_COLLECTION_NOT_FOUND: "NOT_FOUND",
+    MEMORY_COLLECTION_UNMANAGED: "VALIDATION",
+    MEMORY_SCOPES_REQUIRED: "VALIDATION",
+    MEMORY_SCOPES_INVALID: "VALIDATION",
+    MEMORY_IDENTITY_REQUIRED: "VALIDATION",
+    MEMORY_DECISION_INVALID: "VALIDATION",
+    MEMORY_PREDECESSOR_REQUIRED: "VALIDATION",
+    MEMORY_PREDECESSOR_NOT_FOUND: "NOT_FOUND",
+    MEMORY_PREDECESSOR_HASH_MISMATCH: "RUNTIME",
+    MEMORY_SUPERSEDE_CONFLICT: "RUNTIME",
+    MEMORY_SUPERSEDE_PROJECTION_FAILED: "RUNTIME",
+    MEMORY_FENCED_REPLAY: "VALIDATION",
+    MEMORY_FENCED_DERIVED: "VALIDATION",
+    MEMORY_WRITE_LEASE_BUSY: "RUNTIME",
+    MEMORY_SYNC_FAILED: "RUNTIME",
+    MEMORY_QUERY_FAILED: "RUNTIME",
+  };
+
+/** Map a core MemoryError onto the SDK error family; the memory code survives in `details.code`. */
+function toMemorySdkError(cause: unknown): unknown {
+  if (!(cause instanceof MemoryError)) return cause;
+  return sdkError(MEMORY_ERROR_TO_SDK[cause.code], cause.message, {
+    cause,
+    details: { code: cause.code },
+  });
+}
+
 class GnoClientImpl implements GnoClient {
   config: Config;
   readonly dbPath: string;
@@ -1581,6 +1626,54 @@ class GnoClientImpl implements GnoClient {
     };
   }
 
+  /**
+   * The memory service owns the shared write lease; the SDK never takes it.
+   * Embedding is best-effort: without a local model the service reports
+   * lexical-only matching/retrieval instead of failing.
+   */
+  private async withMemoryService<T>(
+    collection: string | undefined,
+    run: (service: MemoryService) => Promise<T>
+  ): Promise<T> {
+    this.assertOpen();
+    const ports = await this.createRuntimePorts({
+      embed: true,
+      collection: this.config.collections.some(
+        (candidate) => candidate.name === collection
+      )
+        ? collection
+        : undefined,
+    });
+    try {
+      return await run(
+        new MemoryService({
+          store: this.store,
+          config: this.config,
+          collections: this.config.collections,
+          lockPath: writeLeasePath(this.dbPath),
+          embedPort: ports.embedPort,
+          vectorIndex: ports.vectorIndex,
+        })
+      );
+    } catch (cause) {
+      throw toMemorySdkError(cause);
+    } finally {
+      await this.disposeRuntimePorts(ports);
+    }
+  }
+
+  async remember(input: GnoRememberInput): Promise<GnoRememberResult> {
+    return this.withMemoryService(input?.collection, (service) =>
+      service.remember(input)
+    );
+  }
+
+  async recall(input: GnoRecallInput): Promise<GnoRecallResult> {
+    return this.withMemoryService(input?.collection, (service) =>
+      service.recall(input)
+    );
+  }
+
   async capture(options: GnoCaptureOptions): Promise<GnoCaptureResult> {
     this.assertOpen();
     const collection = this.getCollections(options.collection)[0];

package/src/sdk/index.ts

@@ -58,6 +58,10 @@ export type {
   GnoMultiGetOptions,
   GnoMultiGetResult,
   GnoQueryOptions,
+  GnoRecallInput,
+  GnoRecallResult,
+  GnoRememberInput,
+  GnoRememberResult,
   GnoRenameNoteApplyOptions,
   GnoRenameNoteOptions,
   GnoProjectHintOptions,
@@ -76,7 +80,16 @@ export type {
   SectionTargetCreateSelector,
   SectionTargetResolveResult,
   SectionTargetV1,
+  MemoryCandidate,
+  MemoryFact,
+  MemoryRecallReceipt,
+  RecalledFact,
 } from "./types";
+export {
+  MemoryError,
+  type MemoryDecision,
+  type MemoryErrorCode,
+} from "../core/memory";
 export {
   ContextCapsuleContractError,
   type ContextCapsuleErrorCode,

package/src/sdk/types.ts

@@ -43,6 +43,16 @@ import type {
   KnowledgeImpactResult,
   ListKnowledgeChangesInput,
 } from "../core/knowledge-delta";
+import type {
+  MemoryCandidate,
+  MemoryFact,
+  MemoryRecallReceipt,
+  RecalledFact,
+  RecallInput,
+  RecallResult,
+  RememberInput,
+  RememberResult,
+} from "../core/memory";
 import type { NoteCollisionPolicy } from "../core/note-creation";
 import type { NotePresetId } from "../core/note-presets";
 import type {
@@ -245,6 +255,13 @@ export interface GnoCaptureOptions extends Omit<CaptureInput, "overwrite"> {}
 
 export type GnoCaptureResult = CaptureReceipt;
 
+/** Shared memory contract (identical on CLI, MCP, REST, and SDK). */
+export type GnoRememberInput = RememberInput;
+export type GnoRememberResult = RememberResult;
+export type GnoRecallInput = RecallInput;
+export type GnoRecallResult = RecallResult;
+export type { MemoryCandidate, MemoryFact, MemoryRecallReceipt, RecalledFact };
+
 export interface GnoCreateFolderOptions {
   collection: string;
   name: string;
@@ -370,6 +387,17 @@ export interface GnoClient {
   embed(options?: GnoEmbedOptions): Promise<GnoEmbedResult>;
   index(options?: GnoIndexOptions): Promise<GnoIndexResult>;
   capture(options: GnoCaptureOptions): Promise<GnoCaptureResult>;
+  /**
+   * Store one fact in a memory-managed collection, or propose candidates when
+   * `decision` is omitted. Requires caller + session identity and explicit
+   * scopes. Errors carry the stable memory code in `details.code`.
+   */
+  remember(input: GnoRememberInput): Promise<GnoRememberResult>;
+  /**
+   * Budgeted, cited recall of current facts in the caller's explicit scopes.
+   * The result carries a content-free fencing receipt.
+   */
+  recall(input: GnoRecallInput): Promise<GnoRecallResult>;
   createNote(options: GnoCreateNoteOptions): Promise<GnoCreateNoteResult>;
   createFolder(options: GnoCreateFolderOptions): Promise<GnoCreateFolderResult>;
   previewRenameNote(

package/src/serve/routes/api.ts

@@ -38,6 +38,7 @@ import type { StartJobError } from "../jobs";
 import type { ResidentStatus } from "../status-model";
 import type { CollectionWatchService } from "../watch-service";
 
+import { getIndexDbPath } from "../../app/constants";
 import { buildVerifiedAsk } from "../../app/verified-ask";
 import { modelsPull } from "../../cli/commands/models/pull";
 import {
@@ -80,6 +81,13 @@ import {
   planCreateFolder,
   planDuplicateRefactor,
 } from "../../core/file-refactors";
+import {
+  MemoryError,
+  type MemoryErrorCode,
+  MemoryService,
+  type RecallInput,
+  type RememberInput,
+} from "../../core/memory";
 import {
   hasContentMutation,
   recordContentMutation,
@@ -117,6 +125,7 @@ import {
   validateTag,
 } from "../../core/tags";
 import { validateRelPath } from "../../core/validation";
+import { writeLeasePath } from "../../core/write-lease";
 import {
   defaultSyncService,
   type SyncResult,
@@ -534,6 +543,12 @@ export interface CreateEditableCopyRequestBody {
   uri?: string;
 }
 
+/** POST /api/memory/remember body: the shared core contract, verbatim. */
+export interface MemoryRememberRequestBody extends RememberInput {}
+
+/** POST /api/memory/recall body: the shared core contract, verbatim. */
+export interface MemoryRecallRequestBody extends RecallInput {}
+
 export interface PublishExportRequestBody {
   encryptionPassphrase?: string;
   slug?: string;
@@ -3673,6 +3688,158 @@ export async function handleCreateCapture(
   }
 }
 
+// ─────────────────────────────────────────────────────────────────────────────
+// Memory (remember / recall)
+// ─────────────────────────────────────────────────────────────────────────────
+
+const HTTP_CREATED = 201;
+const HTTP_NOT_FOUND = 404;
+const HTTP_CONFLICT = 409;
+const HTTP_INTERNAL = 500;
+
+/** HTTP status per stable memory error code; the code itself is the wire code. */
+const MEMORY_ERROR_STATUS: Readonly<Record<MemoryErrorCode, number>> = {
+  MEMORY_TEXT_REQUIRED: 400,
+  MEMORY_TEXT_TOO_LARGE: 400,
+  MEMORY_QUERY_REQUIRED: 400,
+  MEMORY_BUDGET_INVALID: 400,
+  MEMORY_COLLECTION_REQUIRED: 400,
+  MEMORY_COLLECTION_NOT_FOUND: HTTP_NOT_FOUND,
+  MEMORY_COLLECTION_UNMANAGED: 400,
+  MEMORY_SCOPES_REQUIRED: 400,
+  MEMORY_SCOPES_INVALID: 400,
+  MEMORY_IDENTITY_REQUIRED: 400,
+  MEMORY_DECISION_INVALID: 400,
+  MEMORY_PREDECESSOR_REQUIRED: 400,
+  MEMORY_PREDECESSOR_NOT_FOUND: HTTP_NOT_FOUND,
+  MEMORY_PREDECESSOR_HASH_MISMATCH: HTTP_CONFLICT,
+  MEMORY_SUPERSEDE_CONFLICT: HTTP_CONFLICT,
+  MEMORY_FENCED_REPLAY: 400,
+  MEMORY_FENCED_DERIVED: 400,
+  MEMORY_WRITE_LEASE_BUSY: HTTP_CONFLICT,
+  MEMORY_SYNC_FAILED: HTTP_INTERNAL,
+  MEMORY_SUPERSEDE_PROJECTION_FAILED: HTTP_INTERNAL,
+  MEMORY_QUERY_FAILED: HTTP_INTERNAL,
+};
+
+export interface MemoryRouteDeps {
+  /** Shared `.mcp-write.lock` path; defaults to the resident index's lease. */
+  lockPath?: string;
+  lockWaitMs?: number;
+}
+
+function memoryErrorResponse(error: unknown, fallback: string): Response {
+  if (error instanceof MemoryError) {
+    return errorResponse(
+      error.code,
+      error.message,
+      MEMORY_ERROR_STATUS[error.code]
+    );
+  }
+  return errorResponse(
+    "RUNTIME",
+    `${fallback}: ${error instanceof Error ? error.message : String(error)}`,
+    HTTP_INTERNAL
+  );
+}
+
+async function readMemoryBody(
+  req: Request
+): Promise<
+  | { ok: true; body: Record<string, unknown> }
+  | { ok: false; response: Response }
+> {
+  let body: unknown;
+  try {
+    body = await req.json();
+  } catch {
+    return {
+      ok: false,
+      response: errorResponse("VALIDATION", "Invalid JSON body"),
+    };
+  }
+  if (typeof body !== "object" || body === null || Array.isArray(body)) {
+    return {
+      ok: false,
+      response: errorResponse(
+        "VALIDATION",
+        "Request body must be a JSON object"
+      ),
+    };
+  }
+  return { ok: true, body: body as Record<string, unknown> };
+}
+
+/**
+ * The service owns the shared write lease; this adapter never takes it.
+ * Semantic matching/retrieval is enabled only when the resident context has
+ * an embedding port (and a vector index for recall); otherwise the service
+ * reports lexical-only mode in the result.
+ */
+function createMemoryService(
+  ctxHolder: ContextHolder,
+  store: SqliteAdapter,
+  deps: MemoryRouteDeps
+): MemoryService {
+  const ctx = ctxHolder.current;
+  return new MemoryService({
+    store,
+    config: ctx.config,
+    collections: ctx.config.collections,
+    lockPath: deps.lockPath ?? writeLeasePath(getIndexDbPath(ctx.indexName)),
+    lockWaitMs: deps.lockWaitMs,
+    embedPort: ctx.embedPort,
+    vectorIndex: ctx.vectorIndex,
+  });
+}
+
+/**
+ * POST /api/memory/remember
+ * Store a fact (or propose candidates) in a memory-managed collection.
+ * Returns 201 when a record was written, 200 otherwise.
+ */
+export async function handleMemoryRemember(
+  ctxHolder: ContextHolder,
+  store: SqliteAdapter,
+  req: Request,
+  deps: MemoryRouteDeps = {}
+): Promise<Response> {
+  const parsed = await readMemoryBody(req);
+  if (!parsed.ok) return parsed.response;
+  try {
+    const result = await createMemoryService(ctxHolder, store, deps).remember(
+      parsed.body as unknown as MemoryRememberRequestBody
+    );
+    const wrote = result.outcome === "added" || result.outcome === "superseded";
+    if (wrote) ctxHolder.markContentMutation?.();
+    return jsonResponse(result, wrote ? HTTP_CREATED : 200);
+  } catch (error) {
+    return memoryErrorResponse(error, "Failed to remember");
+  }
+}
+
+/**
+ * POST /api/memory/recall
+ * Budgeted, cited recall of current facts in the caller's explicit scopes.
+ */
+export async function handleMemoryRecall(
+  ctxHolder: ContextHolder,
+  store: SqliteAdapter,
+  req: Request,
+  deps: MemoryRouteDeps = {}
+): Promise<Response> {
+  const parsed = await readMemoryBody(req);
+  if (!parsed.ok) return parsed.response;
+  try {
+    const result = await createMemoryService(ctxHolder, store, deps).recall(
+      parsed.body as unknown as MemoryRecallRequestBody
+    );
+    return jsonResponse(result);
+  } catch (error) {
+    return memoryErrorResponse(error, "Failed to recall");
+  }
+}
+
 /**
  * POST /api/docs
  * Create a new document in a collection.

package/src/serve/server.ts

@@ -59,6 +59,8 @@ import {
   handleHealth,
   handleImportPreview,
   handleInstallConnector,
+  handleMemoryRecall,
+  handleMemoryRemember,
   handleMoveDoc,
   handleNotePresets,
   handleJob,
@@ -828,6 +830,30 @@ export async function startServer(
             );
           },
         },
+        "/api/memory/remember": {
+          POST: async (req: Request) => {
+            if (!isRequestAllowed(req, port)) {
+              return withSecurityHeaders(forbiddenResponse(), isDev);
+            }
+            return withSecurityHeaders(
+              await handleMemoryRemember(ctxHolder, store, req),
+              isDev
+            );
+          },
+        },
+        "/api/memory/recall": {
+          POST: async (req: Request) => {
+            if (!isRequestAllowed(req, port)) {
+              return withSecurityHeaders(forbiddenResponse(), isDev);
+            }
+            return withSecurityHeaders(
+              await handleResidentRead(runtime as ResidentRuntime, req, () =>
+                handleMemoryRecall(ctxHolder, store, req)
+              ),
+              isDev
+            );
+          },
+        },
         "/api/docs": {
           GET: async (req: Request) => {
             const url = new URL(req.url);

package/src/store/migrations/027-memory-scopes.ts

@@ -0,0 +1,37 @@
+/**
+ * Migration: indexed memory scopes for managed memory records.
+ *
+ * Scopes are filterable inside retrieval queries (never post-hoc over a
+ * bounded candidate window), so they live in their own indexed table.
+ *
+ * @module src/store/migrations/027-memory-scopes
+ */
+
+import type { Database } from "bun:sqlite";
+
+import type { Migration } from "./runner";
+
+export const migration: Migration = {
+  version: 27,
+  name: "memory_scopes",
+
+  up(db: Database): void {
+    db.exec(`
+      CREATE TABLE IF NOT EXISTS doc_memory_scopes (
+        document_id INTEGER NOT NULL,
+        scope TEXT NOT NULL,
+        PRIMARY KEY (document_id, scope),
+        FOREIGN KEY (document_id) REFERENCES documents(id) ON DELETE CASCADE
+      )
+    `);
+    db.exec(`
+      CREATE INDEX IF NOT EXISTS idx_doc_memory_scopes_scope
+      ON doc_memory_scopes(scope, document_id)
+    `);
+  },
+
+  down(db: Database): void {
+    db.exec("DROP INDEX IF EXISTS idx_doc_memory_scopes_scope");
+    db.exec("DROP TABLE IF EXISTS doc_memory_scopes");
+  },
+};

package/src/store/migrations/index.ts

@@ -40,6 +40,7 @@ import { migration as m023 } from "./023-collection-egress-policy";
 import { migration as m024 } from "./024-egress-derived-lineage";
 import { migration as m025 } from "./025-collection-egress-policy-revision";
 import { migration as m026 } from "./026-file-refactor-recovery-journal";
+import { migration as m027 } from "./027-memory-scopes";
 
 /** All migrations in order */
 export const migrations = [
@@ -69,4 +70,5 @@ export const migrations = [
   m024,
   m025,
   m026,
+  m027,
 ];

package/src/store/sqlite/adapter.ts

@@ -75,6 +75,8 @@ import type {
   IndexStatus,
   IngestErrorInput,
   IngestErrorRow,
+  MemoryEligibleDocument,
+  MemoryEligibleDocumentsOptions,
   MigrationResult,
   RetrievalTraceAppendResult,
   RetrievalTraceBundle,
@@ -324,6 +326,13 @@ type FtsQueryBuildResult =
   | { ok: true; query: string }
   | { ok: false; error: string };
 
+/**
+ * SQL fragment excluding documents superseded by an active document via the
+ * typed `supersedes` edge. `docIdExpr` names the candidate document id column.
+ */
+const SUPERSEDED_EXCLUSION_SQL = (docIdExpr: string): string =>
+  `AND NOT EXISTS (SELECT 1 FROM doc_edges se JOIN documents sd ON sd.id = se.src_doc_id AND sd.active = 1 WHERE se.dst_doc_id = ${docIdExpr} AND se.edge_type = 'supersedes')`;
+
 /**
  * Narrow lexical grammar for BM25/FTS queries.
  *
@@ -333,7 +342,10 @@ type FtsQueryBuildResult =
  * - negation with at least one positive term
  * - hyphenated compounds handled intentionally
  */
-function buildFts5Query(query: string): FtsQueryBuildResult {
+function buildFts5Query(
+  query: string,
+  options: { anyTerm?: boolean } = {}
+): FtsQueryBuildResult {
   const trimmed = query.trim();
   if (!trimmed) {
     return { ok: false, error: "Search query cannot be empty" };
@@ -454,7 +466,9 @@ function buildFts5Query(query: string): FtsQueryBuildResult {
     };
   }
 
-  let ftsQuery = positive.join(" AND ");
+  let ftsQuery = options.anyTerm
+    ? `(${positive.join(" OR ")})`
+    : positive.join(" AND ");
   for (const negation of negative) {
     ftsQuery = `${ftsQuery} NOT ${negation}`;
   }
@@ -2635,7 +2649,7 @@ export class SqliteAdapter implements StorePort, SqliteDbProvider {
     try {
       const db = this.ensureOpen();
       const limit = options.limit ?? 20;
-      const builtQuery = buildFts5Query(query);
+      const builtQuery = buildFts5Query(query, { anyTerm: options.anyTerm });
       if (!builtQuery.ok) {
         return err("INVALID_INPUT", builtQuery.error);
       }
@@ -2683,6 +2697,21 @@ export class SqliteAdapter implements StorePort, SqliteDbProvider {
         params.push(`%${options.author.toLowerCase()}%`);
       }
 
+      // Scope and supersession filters run inside the candidate subquery so
+      // they narrow the corpus before the FTS LIMIT (never a post-filter).
+      const innerConditions: string[] = [];
+      const innerParams: string[] = [];
+      if (options.memoryScopesAny && options.memoryScopesAny.length > 0) {
+        const placeholders = options.memoryScopesAny.map(() => "?").join(",");
+        innerConditions.push(
+          `AND EXISTS (SELECT 1 FROM doc_memory_scopes ms WHERE ms.document_id = documents.id AND ms.scope IN (${placeholders}))`
+        );
+        innerParams.push(...options.memoryScopesAny);
+      }
+      if (options.excludeSuperseded) {
+        innerConditions.push(SUPERSEDED_EXCLUSION_SQL("documents.id"));
+      }
+
       const hasOuterFilters = tagConditions.length > 0;
       const ftsLimit = hasOuterFilters ? limit * 10 : limit;
       params.push(limit);
@@ -2711,6 +2740,7 @@ export class SqliteAdapter implements StorePort, SqliteDbProvider {
                 ? "AND (COALESCE(NULLIF(record_source_path, ''), rel_path) = ? OR substr(COALESCE(NULLIF(record_source_path, ''), rel_path), 1, length(?) + 1) = ? || '/')"
                 : ""
             }
+            ${innerConditions.join("\n            ")}
           )
           ORDER BY score
           LIMIT ?
@@ -2789,6 +2819,7 @@ export class SqliteAdapter implements StorePort, SqliteDbProvider {
               options.relPathPrefix,
             ]
           : []),
+        ...innerParams,
         ftsLimit,
         ...params,
       ];
@@ -3076,6 +3107,99 @@ export class SqliteAdapter implements StorePort, SqliteDbProvider {
     }
   }
 
+  async setDocMemoryScopes(
+    documentId: number,
+    scopes: string[]
+  ): Promise<StoreResult<void>> {
+    try {
+      const db = this.ensureOpen();
+      const transaction = db.transaction(() => {
+        db.run("DELETE FROM doc_memory_scopes WHERE document_id = ?", [
+          documentId,
+        ]);
+        if (scopes.length > 0) {
+          const stmt = db.prepare(
+            "INSERT OR IGNORE INTO doc_memory_scopes (document_id, scope) VALUES (?, ?)"
+          );
+          for (const scope of scopes) {
+            stmt.run(documentId, scope);
+          }
+        }
+      });
+      transaction();
+      return ok(undefined);
+    } catch (cause) {
+      return err(
+        "QUERY_FAILED",
+        cause instanceof Error ? cause.message : "Failed to set memory scopes",
+        cause
+      );
+    }
+  }
+
+  async getDocMemoryScopes(documentId: number): Promise<StoreResult<string[]>> {
+    try {
+      const db = this.ensureOpen();
+      const rows = db
+        .query<{ scope: string }, [number]>(
+          "SELECT scope FROM doc_memory_scopes WHERE document_id = ? ORDER BY scope"
+        )
+        .all(documentId);
+      return ok(rows.map((row) => row.scope));
+    } catch (cause) {
+      return err(
+        "QUERY_FAILED",
+        cause instanceof Error ? cause.message : "Failed to read memory scopes",
+        cause
+      );
+    }
+  }
+
+  async listMemoryEligibleDocuments(
+    options: MemoryEligibleDocumentsOptions
+  ): Promise<StoreResult<MemoryEligibleDocument[]>> {
+    try {
+      const db = this.ensureOpen();
+      if (options.scopes.length === 0) {
+        return ok([]);
+      }
+      const placeholders = options.scopes.map(() => "?").join(",");
+      const rows = db
+        .query<
+          { id: number; docid: string; uri: string; mirror_hash: string },
+          string[]
+        >(
+          `
+          SELECT d.id, d.docid, d.uri, d.mirror_hash
+          FROM documents d
+          WHERE d.active = 1
+            AND d.collection = ?
+            AND d.mirror_hash IS NOT NULL
+            AND EXISTS (SELECT 1 FROM doc_memory_scopes ms WHERE ms.document_id = d.id AND ms.scope IN (${placeholders}))
+            ${options.excludeSuperseded ? SUPERSEDED_EXCLUSION_SQL("d.id") : ""}
+          ORDER BY d.id
+          `
+        )
+        .all(options.collection, ...options.scopes);
+      return ok(
+        rows.map((row) => ({
+          id: row.id,
+          docid: row.docid,
+          uri: row.uri,
+          mirrorHash: row.mirror_hash,
+        }))
+      );
+    } catch (cause) {
+      return err(
+        "QUERY_FAILED",
+        cause instanceof Error
+          ? cause.message
+          : "Failed to list memory-eligible documents",
+        cause
+      );
+    }
+  }
+
   /**
    * Get all tags for a document.
    */