@gmickel/gno 1.40.0 → 1.42.0

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/routes/mcp.ts

@@ -30,6 +30,7 @@ export async function createMcpHttpGateway(
   config: ResolvedHttpGatewayConfig
 ): Promise<McpHttpGateway> {
   runtime.mcpContext.enableWrite = config.enableWrite;
+  runtime.mcpContext.toolProfile = config.toolProfile;
   const transport = new HttpMcpTransport(runtime, {
     enableWrite: config.enableWrite,
     idleTimeoutMs: config.limits.sessionIdleTimeoutMs,

package/src/serve/server.ts

@@ -59,6 +59,8 @@ import {
   handleHealth,
   handleImportPreview,
   handleInstallConnector,
+  handleMemoryRecall,
+  handleMemoryRemember,
   handleMoveDoc,
   handleNotePresets,
   handleJob,
@@ -403,6 +405,7 @@ export async function startServer(
     allowedHosts: options.allowedHosts,
     allowedOrigins: options.allowedOrigins,
     enableWrite: options.enableWrite,
+    toolProfile: options.toolProfile,
   });
   if (!isHttpGatewayLoopbackBind(gatewayConfig.host)) {
     await runtime.dispose();
@@ -828,6 +831,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.
    */

package/src/store/types.ts

@@ -643,6 +643,35 @@ export interface FtsSearchOptions {
   categories?: string[];
   /** Filter by author field (case-insensitive contains) */
   author?: string;
+  /**
+   * Managed-memory scope filter: keep only documents carrying at least one of
+   * these normalized scopes. Applied inside the FTS candidate subquery, before
+   * any LIMIT, so an out-of-scope document never occupies the window.
+   */
+  memoryScopesAny?: string[];
+  /**
+   * Exclude documents that an active document supersedes (typed edge
+   * `supersedes` pointing at them). Applied inside the candidate subquery.
+   */
+  excludeSuperseded?: boolean;
+  /** Match documents containing ANY positive term instead of ALL of them. */
+  anyTerm?: boolean;
+}
+
+/** Managed-memory eligibility query (unbounded, executed in one SQL query). */
+export interface MemoryEligibleDocumentsOptions {
+  collection: string;
+  /** Normalized scopes; any-intersection semantics. */
+  scopes: string[];
+  excludeSuperseded?: boolean;
+}
+
+/** Minimal identity of a memory record eligible for managed recall. */
+export interface MemoryEligibleDocument {
+  id: number;
+  docid: string;
+  uri: string;
+  mirrorHash: string;
 }
 
 /** Single FTS search result */
@@ -2022,6 +2051,31 @@ export interface StorePort {
    */
   getTagsForDoc(documentId: number): Promise<StoreResult<TagRow[]>>;
 
+  // ─────────────────────────────────────────────────────────────────────────
+  // Memory scopes (managed memory records)
+  // ─────────────────────────────────────────────────────────────────────────
+
+  /**
+   * Replace the indexed scope set of one document. An empty list clears it,
+   * which removes the document from managed recall.
+   */
+  setDocMemoryScopes(
+    documentId: number,
+    scopes: string[]
+  ): Promise<StoreResult<void>>;
+
+  /** Indexed scopes for one document (sorted). */
+  getDocMemoryScopes(documentId: number): Promise<StoreResult<string[]>>;
+
+  /**
+   * Every active document in the collection carrying at least one requested
+   * scope, optionally excluding superseded records. One unbounded query, so
+   * the result is the exact eligible set rather than a candidate window.
+   */
+  listMemoryEligibleDocuments(
+    options: MemoryEligibleDocumentsOptions
+  ): Promise<StoreResult<MemoryEligibleDocument[]>>;
+
   /**
    * Get tags for multiple documents in a single query.
    * Returns a map of documentId -> TagRow[].

package/browser-extension/artifacts/gno-browser-clipper-v1.40.0.zip.sha256

@@ -1 +0,0 @@
-1d6a17618bddf4425527e94961459fa2a414d06f5123d43ffebadfeca8a3a89b  gno-browser-clipper-v1.40.0.zip