@gmickel/gno 1.40.0 → 1.41.0

package/src/core/memory.ts

@@ -0,0 +1,87 @@
+/**
+ * Transport-neutral memory service: `remember()` and `recall()`.
+ *
+ * Every surface (CLI, MCP, REST, SDK) is a thin adapter over this module.
+ * The service owns the shared write lease for every write path; adapters
+ * never take `.mcp-write.lock` themselves (single acquisition point, no
+ * nesting — a caller that already holds the lease deadlocks/fails fast).
+ *
+ * This file is the facade: the contracts live in `memory-types`, validation,
+ * the context fence, and receipts in `memory-fence`, the write path in
+ * `memory-remember`, and retrieval in `memory-recall`. Import from here.
+ *
+ * @module src/core/memory
+ */
+
+import type {
+  MemoryCandidate,
+  MemoryMatchDiagnostics,
+  MemoryServiceDeps,
+  RecallInput,
+  RecallResult,
+  RememberInput,
+  RememberResult,
+} from "./memory-types";
+
+import { recallFacts } from "./memory-recall";
+import {
+  type CandidateQuery,
+  findMemoryCandidates,
+  rememberFact,
+} from "./memory-remember";
+
+export {
+  MEMORY_CANDIDATE_POOL,
+  MEMORY_EMPTY_RECALL_HINT,
+  MEMORY_LEXICAL_LIKELY_THRESHOLD,
+  MEMORY_RECALL_MAX_FACTS,
+  MEMORY_RECALL_MAX_TOKENS,
+  MEMORY_SEMANTIC_LIKELY_THRESHOLD,
+  MemoryError,
+} from "./memory-types";
+export type {
+  MemoryCandidate,
+  MemoryCandidateMatch,
+  MemoryDecision,
+  MemoryErrorCode,
+  MemoryFact,
+  MemoryIdentity,
+  MemoryMatchDiagnostics,
+  MemoryMatchMode,
+  MemoryRecallReceipt,
+  MemoryServiceDeps,
+  MemorySyncState,
+  RecalledFact,
+  RecallInput,
+  RecallResult,
+  RememberInput,
+  RememberResult,
+} from "./memory-types";
+
+export class MemoryService {
+  private readonly deps: MemoryServiceDeps;
+
+  constructor(deps: MemoryServiceDeps) {
+    this.deps = deps;
+  }
+
+  /**
+   * Candidate pool: BM25 top-16 (any-term) within the scope intersection,
+   * current facts only. Similarity by cosine when semantic is ready, else by
+   * normalized-token Jaccard. Ordered by similarity desc, ties by recordId.
+   */
+  findCandidates(input: CandidateQuery): Promise<{
+    candidates: MemoryCandidate[];
+    matching: MemoryMatchDiagnostics;
+  }> {
+    return findMemoryCandidates(this.deps, input);
+  }
+
+  remember(input: RememberInput): Promise<RememberResult> {
+    return rememberFact(this.deps, input);
+  }
+
+  recall(input: RecallInput): Promise<RecallResult> {
+    return recallFacts(this.deps, input);
+  }
+}

package/src/ingestion/sync.ts

@@ -60,6 +60,7 @@ import {
   parseLinks,
   parseTargetParts,
 } from "../core/links";
+import { extractMemoryScopes } from "../core/memory-record";
 import { normalizeTag, validateTag } from "../core/tags";
 import { defaultChunker } from "./chunker";
 import {
@@ -1074,6 +1075,22 @@ export class SyncService {
           tagCount: extractedTags.length,
         });
 
+        // 13b. Index managed-memory scopes, memory-managed collections only.
+        // A record that passes the memory validator gets scope rows; a
+        // malformed file clears them and therefore drops out of managed
+        // recall while staying searchable.
+        if (collection.memoryManaged === true) {
+          const memoryScopes = extractMemoryScopes(artifact.markdown);
+          const scopesResult = await store.setDocMemoryScopes(
+            docId,
+            memoryScopes
+          );
+          mustOk(scopesResult, "setDocMemoryScopes", {
+            docId,
+            scopeCount: memoryScopes.length,
+          });
+        }
+
         // 14. Extract and store links (wiki and markdown links)
         const excludedRanges = getExcludedRanges(artifact.markdown);
         const lineOffsets = buildLineOffsets(artifact.markdown);

package/src/mcp/http-egress.ts

@@ -51,6 +51,8 @@ export const MCP_HTTP_EGRESS_TOOLS = {
   gno_multi_get: "source",
   gno_query: "snippet",
   gno_query_diagnose: "metadata",
+  gno_recall: "source",
+  gno_remember: "source",
   gno_remove_collection: "metadata",
   gno_rename_note: "metadata",
   gno_search: "snippet",

package/src/mcp/tools/index.ts

@@ -64,6 +64,16 @@ import {
 } from "./links";
 import { handleListJobs } from "./list-jobs";
 import { handleListTags } from "./list-tags";
+import {
+  handleRecall,
+  RECALL_MCP_ANNOTATIONS,
+  recallInputSchema,
+} from "./memory-recall";
+import {
+  handleRemember,
+  REMEMBER_MCP_ANNOTATIONS,
+  rememberInputSchema,
+} from "./memory-remember";
 import { handleMultiGet } from "./multi-get";
 import { handlePeek, PEEK_MCP_ANNOTATIONS } from "./peek";
 import { handleQuery, handleQueryDiagnose } from "./query";
@@ -140,11 +150,16 @@ export const MCP_TOOL_DESCRIPTIONS = {
   contextVerify:
     "Verify a saved Context Capsule without rebuilding or mutating it. Reports unchanged, stale, missing, reranked, and fingerprint drift states against the active index.",
   ask: "Generate one answer from a deterministic Context Capsule, verify every substantive claim against exact retained spans, and abstain unless support coverage is complete. Read-only; returns the Capsule, freshness receipt, claim verdicts, gaps, and evidence IDs.",
+  recall:
+    "Recall current facts from a memory-managed collection for explicit scopes. Call before answering about the user's preferences, decisions, people, or prior work, and before gno_remember to find the predecessor of a changed fact. Returns at most 8 facts within 512 tokens by default, each with text, scopes, provenance, gno:// cite, and content hash, plus a content-free receipt; superseded facts are excluded. Pass the receipt to gno_remember when a stored fact derives from this recall. An empty result names the command that stores the first fact.",
+  remember:
+    "Store one fact in a memory-managed collection under explicit scopes. Call when the user states a durable preference, decision, or fact worth recalling later; use gno_capture for documents and file edits for existing notes. Without decision it returns likely matches and writes nothing; decision=add writes a new fact; decision=supersede replaces predecessorUri after a hash check, one successor per fact. Exact duplicates return the existing record. Text that replays a recall receipt span or declares a gno:// origin is rejected. The fact is lexically searchable when the call returns.",
 } as const;
 
 /** Tool names whose execution mutates disk, config, or index state. */
 export const MCP_WRITE_TOOL_NAMES = new Set([
   "gno_capture",
+  "gno_remember",
   "gno_add_collection",
   "gno_sync",
   "gno_embed",
@@ -1037,6 +1052,20 @@ export function registerTools(server: McpServer, ctx: ToolContext): void {
     (args) => handleAsk(args, ctx)
   );
 
+  server.registerTool(
+    "gno_recall",
+    {
+      description: MCP_TOOL_DESCRIPTIONS.recall,
+      inputSchema: recallInputSchema,
+      annotations: RECALL_MCP_ANNOTATIONS,
+    },
+    (args, extra) =>
+      handleRecall(args, ctx, {
+        clientName: server.server.getClientVersion()?.name,
+        sessionId: extra.sessionId,
+      })
+  );
+
   server.tool(
     "gno_search",
     MCP_TOOL_DESCRIPTIONS.search,
@@ -1315,6 +1344,20 @@ export function registerTools(server: McpServer, ctx: ToolContext): void {
       (args) => handleTracePurge(args, ctx)
     );
 
+    server.registerTool(
+      "gno_remember",
+      {
+        description: MCP_TOOL_DESCRIPTIONS.remember,
+        inputSchema: rememberInputSchema,
+        annotations: REMEMBER_MCP_ANNOTATIONS,
+      },
+      (args, extra) =>
+        handleRemember(args, ctx, {
+          clientName: server.server.getClientVersion()?.name,
+          sessionId: extra.sessionId,
+        })
+    );
+
     server.tool(
       "gno_capture",
       "Create a new document in a collection. Writes to disk. Does NOT auto-embed; run gno_index after to make it searchable via vector search.",

package/src/mcp/tools/memory-recall.ts

@@ -0,0 +1,122 @@
+/**
+ * MCP gno_recall tool - budgeted, cited, current-state memory recall.
+ *
+ * Thin adapter over the core `MemoryService`. Identity is mapped from the
+ * server session (MCP client name + transport session), never from tool
+ * arguments; see `memory-shared` for the mapping and service construction.
+ *
+ * @module src/mcp/tools/memory-recall
+ */
+
+import { z } from "zod";
+
+import type { ToolContext } from "../server";
+
+import {
+  MEMORY_RECALL_MAX_FACTS,
+  MEMORY_RECALL_MAX_TOKENS,
+  type RecallResult,
+} from "../../core/memory";
+import { runTool, type ToolResult } from "./index";
+import {
+  createMcpMemoryService,
+  type McpMemorySessionInfo,
+  memoryScopesInputSchema,
+  resolveMcpMemoryIdentity,
+  rethrowMemoryError,
+} from "./memory-shared";
+
+export const RECALL_MCP_ANNOTATIONS = {
+  readOnlyHint: true,
+  destructiveHint: false,
+  idempotentHint: true,
+  openWorldHint: false,
+} as const;
+
+export const recallInputSchema = z.object({
+  query: z
+    .string()
+    .trim()
+    .min(1, "Query cannot be empty")
+    .describe("What you need to know, phrased as the fact would be stated"),
+  collection: z
+    .string()
+    .trim()
+    .min(1, "Collection cannot be empty")
+    .describe("Memory-managed collection to recall from"),
+  scopes: memoryScopesInputSchema,
+  maxFacts: z
+    .number()
+    .int()
+    .min(1)
+    .max(64)
+    .optional()
+    .describe(`Fact budget (default ${MEMORY_RECALL_MAX_FACTS})`),
+  maxTokens: z
+    .number()
+    .int()
+    .min(1)
+    .max(8192)
+    .optional()
+    .describe(`Payload token budget (default ${MEMORY_RECALL_MAX_TOKENS})`),
+});
+
+export type RecallToolInput = z.infer<typeof recallInputSchema>;
+
+export function formatRecallResult(result: RecallResult): string {
+  const lines: string[] = [];
+  lines.push(
+    `Facts: ${result.facts.length} (budget ${result.budget.maxFacts} facts / ${result.budget.maxTokens} tokens, used ${result.budget.usedTokens}, omitted ${result.budget.omitted})`
+  );
+  lines.push(
+    `Retrieval: ${result.retrieval.mode}${
+      result.retrieval.semanticUnavailable
+        ? ` (${result.retrieval.semanticUnavailable})`
+        : ""
+    }`
+  );
+  for (const fact of result.facts) {
+    lines.push("");
+    lines.push(`- ${fact.text}`);
+    lines.push(`  cite: ${fact.uri}`);
+    lines.push(
+      `  scopes: ${fact.scopes.join(", ")} | hash: ${fact.contentHash} | created: ${fact.createdAt}`
+    );
+  }
+  if (result.hint) {
+    lines.push("");
+    lines.push(result.hint);
+  }
+  lines.push("");
+  lines.push(
+    `Receipt: ${result.receipt.digest} (caller ${result.receipt.caller}, session ${result.receipt.session}, ${result.receipt.memoryIds.length} ids)`
+  );
+  return lines.join("\n");
+}
+
+export function handleRecall(
+  args: RecallToolInput,
+  ctx: ToolContext,
+  info: McpMemorySessionInfo = {}
+): Promise<ToolResult> {
+  return runTool(
+    ctx,
+    "gno_recall",
+    async () => {
+      const service = createMcpMemoryService(ctx);
+      try {
+        return await service.recall({
+          ...resolveMcpMemoryIdentity(ctx, info),
+          query: args.query,
+          collection: args.collection,
+          scopes: args.scopes,
+          maxFacts: args.maxFacts,
+          maxTokens: args.maxTokens,
+        });
+      } catch (error) {
+        return rethrowMemoryError(error);
+      }
+    },
+    formatRecallResult
+  );
+}

package/src/mcp/tools/memory-remember.ts

@@ -0,0 +1,177 @@
+/**
+ * MCP gno_remember tool - store one fact with supersession semantics.
+ *
+ * Thin adapter over the core `MemoryService`, registered only with
+ * `--enable-write`. The service acquires the shared write lease itself; this
+ * module performs no lock acquisition.
+ *
+ * @module src/mcp/tools/memory-remember
+ */
+
+import { z } from "zod";
+
+import type { ToolContext } from "../server";
+
+import { type RememberResult } from "../../core/memory";
+import { MEMORY_MAX_FACT_BYTES } from "../../core/memory-record";
+import { runTool, type ToolResult } from "./index";
+import {
+  createMcpMemoryService,
+  type McpMemorySessionInfo,
+  memoryScopesInputSchema,
+  resolveMcpMemoryIdentity,
+  rethrowMemoryError,
+} from "./memory-shared";
+
+export const REMEMBER_MCP_ANNOTATIONS = {
+  readOnlyHint: false,
+  destructiveHint: false,
+  idempotentHint: false,
+  openWorldHint: false,
+} as const;
+
+export const memoryReceiptInputSchema = z
+  .object({
+    caller: z.string(),
+    session: z.string(),
+    issuedAt: z.string(),
+    memoryIds: z.array(z.string()),
+    spanHashes: z.array(z.string()),
+    digest: z.string(),
+  })
+  .describe(
+    "The receipt from the gno_recall response the fact was derived from, if any; replayed recalled spans are rejected"
+  );
+
+export const rememberInputSchema = z.object({
+  text: z
+    .string()
+    .trim()
+    .min(1, "Fact text cannot be empty")
+    .max(MEMORY_MAX_FACT_BYTES)
+    .describe(
+      "One fact, stated in full (single statement, not a document; use gno_capture for documents)"
+    ),
+  collection: z
+    .string()
+    .trim()
+    .min(1, "Collection cannot be empty")
+    .describe("Memory-managed collection to write into"),
+  scopes: memoryScopesInputSchema,
+  decision: z
+    .enum(["add", "supersede"])
+    .optional()
+    .describe(
+      "Omit to receive candidates without writing; add creates a new fact; supersede replaces predecessorUri"
+    ),
+  predecessorUri: z
+    .string()
+    .trim()
+    .min(1)
+    .optional()
+    .describe("gno:// URI of the fact being superseded (supersede only)"),
+  predecessorHash: z
+    .string()
+    .trim()
+    .min(1)
+    .optional()
+    .describe(
+      "contentHash of the predecessor as returned by gno_recall (supersede only)"
+    ),
+  receipt: memoryReceiptInputSchema.optional(),
+  derivedFrom: z
+    .array(z.string().trim().min(1))
+    .max(32)
+    .optional()
+    .describe(
+      "Declared origins of the fact; any gno:// origin is rejected as GNO-derived"
+    ),
+  source: z
+    .string()
+    .trim()
+    .min(1)
+    .optional()
+    .describe("Free-text evidence for the fact (where it came from)"),
+});
+
+export type RememberToolInput = z.infer<typeof rememberInputSchema>;
+
+export function formatRememberResult(result: RememberResult): string {
+  const lines: string[] = [];
+  const matching = `matching: ${result.matching.mode} (threshold ${result.matching.threshold}${
+    result.matching.semanticUnavailable
+      ? `, ${result.matching.semanticUnavailable}`
+      : ""
+  })`;
+  switch (result.outcome) {
+    case "existing":
+      lines.push(`Outcome: existing (exact duplicate, nothing written)`);
+      lines.push(`URI: ${result.record.uri}`);
+      lines.push(`Hash: ${result.record.contentHash}`);
+      break;
+    case "candidates":
+      lines.push(
+        `Outcome: candidates (${result.candidates.length}, nothing written). Decide: decision=add for a new fact, or decision=supersede with predecessorUri + predecessorHash.`
+      );
+      for (const candidate of result.candidates) {
+        lines.push(
+          `- [${candidate.match} ${candidate.similarity.toFixed(2)}] ${candidate.text}`
+        );
+        lines.push(`  uri: ${candidate.uri} | hash: ${candidate.contentHash}`);
+      }
+      break;
+    default:
+      lines.push(`Outcome: ${result.outcome}`);
+      lines.push(`URI: ${result.record.uri}`);
+      lines.push(`Hash: ${result.record.contentHash}`);
+      lines.push(`Path: ${result.absPath}`);
+      lines.push(`Sync: ${result.sync.status}`);
+      if (result.record.supersedes.length > 0) {
+        lines.push(`Supersedes: ${result.record.supersedes.join(", ")}`);
+      }
+      break;
+  }
+  lines.push(matching);
+  return lines.join("\n");
+}
+
+export function handleRemember(
+  args: RememberToolInput,
+  ctx: ToolContext,
+  info: McpMemorySessionInfo = {}
+): Promise<ToolResult> {
+  return runTool(
+    ctx,
+    "gno_remember",
+    async () => {
+      if (!ctx.enableWrite) {
+        throw new Error(
+          "WRITE_DISABLED: gno_remember requires --enable-write or GNO_MCP_ENABLE_WRITE=1"
+        );
+      }
+      const service = createMcpMemoryService(ctx);
+      let result: RememberResult;
+      try {
+        result = await service.remember({
+          ...resolveMcpMemoryIdentity(ctx, info),
+          text: args.text,
+          collection: args.collection,
+          scopes: args.scopes,
+          decision: args.decision,
+          predecessorUri: args.predecessorUri,
+          predecessorHash: args.predecessorHash,
+          receipt: args.receipt,
+          derivedFrom: args.derivedFrom,
+          source: args.source,
+        });
+      } catch (error) {
+        return rethrowMemoryError(error);
+      }
+      if (result.outcome === "added" || result.outcome === "superseded") {
+        ctx.markContentMutation?.();
+      }
+      return result;
+    },
+    formatRememberResult
+  );
+}

package/src/mcp/tools/memory-shared.ts

@@ -0,0 +1,80 @@
+/**
+ * Helpers shared by the MCP gno_recall / gno_remember tools: identity
+ * mapping from the server session, service construction, error rethrow in
+ * the shape runTool parses, and the common scopes input schema.
+ *
+ * The service owns the shared write lease; this module never touches
+ * `ctx.writeLockPath` beyond naming the lease file for the service.
+ *
+ * @module src/mcp/tools/memory-shared
+ */
+
+import { z } from "zod";
+
+import type { ToolContext } from "../server";
+
+import {
+  MemoryError,
+  type MemoryIdentity,
+  MemoryService,
+} from "../../core/memory";
+import { MEMORY_MAX_SCOPES } from "../../core/memory-record";
+
+/** Caller name when the MCP client sent no implementation name. */
+const DEFAULT_MCP_CALLER = "mcp";
+
+/** Server-side identity inputs resolved at dispatch time by the registry. */
+export interface McpMemorySessionInfo {
+  /** `clientInfo.name` from the MCP initialize handshake. */
+  clientName?: string;
+  /** Transport session id (Streamable HTTP); absent on stdio. */
+  sessionId?: string;
+}
+
+export const memoryScopesInputSchema = z
+  .array(z.string().trim().min(1))
+  .min(1, "At least one explicit scope is required")
+  .max(MEMORY_MAX_SCOPES)
+  .describe(
+    `Explicit scopes (1-${MEMORY_MAX_SCOPES}, e.g. "project:gno"). Visibility is any-intersection; there is no implicit global scope`
+  );
+
+/**
+ * Map the MCP server session to the core identity contract.
+ *
+ * caller = MCP client implementation name; session = transport session id
+ * when the transport has one (Streamable HTTP), else the per-process server
+ * instance id (stdio: one process is one session).
+ */
+export function resolveMcpMemoryIdentity(
+  ctx: ToolContext,
+  info: McpMemorySessionInfo
+): MemoryIdentity {
+  const caller = info.clientName?.trim() || DEFAULT_MCP_CALLER;
+  const session = info.sessionId?.trim() || ctx.serverInstanceId;
+  return { caller, session };
+}
+
+/**
+ * Construct the core service for one MCP call.
+ *
+ * The lease path names the same `.mcp-write.lock` file the rest of the MCP
+ * write surface uses, so a memory write and a capture serialise on one lease.
+ * Acquisition happens inside the service only.
+ */
+export function createMcpMemoryService(ctx: ToolContext): MemoryService {
+  return new MemoryService({
+    store: ctx.store,
+    config: ctx.config,
+    collections: ctx.collections,
+    lockPath: ctx.writeLockPath,
+  });
+}
+
+/** Re-throw a core memory error in the `CODE: message` shape runTool parses. */
+export function rethrowMemoryError(error: unknown): never {
+  if (error instanceof MemoryError) {
+    throw new Error(`${error.code}: ${error.message}`);
+  }
+  throw error;
+}

package/src/pipeline/search.ts

@@ -211,6 +211,8 @@ export async function searchBm25(
     until: temporalRange.until,
     categories: options.categories,
     author: options.author,
+    memoryScopesAny: options.memoryFilter?.scopes,
+    excludeSuperseded: options.memoryFilter?.excludeSuperseded,
   });
 
   if (!ftsResult.ok) {

package/src/pipeline/types.ts

@@ -212,6 +212,14 @@ export interface SearchOptions {
   intent?: string;
   /** Explicit exclusion terms for hard candidate pruning */
   exclude?: string[];
+  /**
+   * Internal managed-memory filter: scope any-intersection plus superseded
+   * exclusion, executed inside the retrieval query (never post-hoc).
+   */
+  memoryFilter?: {
+    scopes: string[];
+    excludeSuperseded: boolean;
+  };
 }
 
 /** Structured query mode identifier */