@gmickel/gno 1.40.0 → 1.42.0

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,86 @@
+/**
+ * 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 (2025-era Streamable HTTP); absent on stdio and on the 2026-07-28 sessionless leg. */
+  sessionId?: string;
+  /** Opaque per-caller identity the HTTP boundary derived (`ctx.getRequestIdentity`); absent on stdio. */
+  requestIdentity?: 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 (2025-era Streamable HTTP), else the per-caller
+ * identity the HTTP boundary derived (2026-07-28 sessionless leg), 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() ||
+    info.requestIdentity?.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 */

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(