@gmickel/gno 1.40.0 → 1.41.0

package/src/cli/program.ts

@@ -354,6 +354,7 @@ export function createProgram(): Command {
   wireSearchCommands(program);
   wireOnboardingCommands(program);
   wireCaptureCommand(program);
+  wireMemoryCommands(program);
   wireManagementCommands(program);
   wireTraceCommands(program);
   wirePublishCommand(program);
@@ -1888,6 +1889,132 @@ function wireCaptureCommand(program: Command): void {
     );
 }
 
+// ─────────────────────────────────────────────────────────────────────────────
+// Memory Commands (remember, recall)
+// ─────────────────────────────────────────────────────────────────────────────
+
+function wireMemoryCommands(program: Command): void {
+  program
+    .command("remember <text>")
+    .description("Store a fact in a memory-managed collection")
+    .option("-c, --collection <name>", "memory-managed target collection")
+    .option(
+      "--scope <scope>",
+      "explicit scope (repeatable, required; no implicit global scope)",
+      collectRepeatableValue,
+      []
+    )
+    .option("--decision <decision>", "add or supersede (omit for candidates)")
+    .option("--add", "shorthand for --decision add")
+    .option(
+      "--supersede <uri>",
+      "shorthand for --decision supersede --predecessor <uri>"
+    )
+    .option("--predecessor <uri>", "predecessor gno:// URI for supersede")
+    .option(
+      "--predecessor-hash <hash>",
+      "predecessor contentHash from recall (required for supersede)"
+    )
+    .option(
+      "--receipt <path>",
+      "recall receipt JSON to fence against (recall --json output)"
+    )
+    .option(
+      "--derived-from <uri>",
+      "declared origin of the fact (repeatable; gno:// origins are fenced)",
+      collectRepeatableValue,
+      []
+    )
+    .option("--source <text>", "free-form source evidence")
+    .option(
+      "--caller <id>",
+      "caller identity (default: $GNO_MEMORY_CALLER or cli:<user>)"
+    )
+    .option(
+      "--session <id>",
+      "session identity (default: $GNO_MEMORY_SESSION or ppid:<pid>)"
+    )
+    .option("--json", "JSON output")
+    .action(async (text: string, cmdOpts: Record<string, unknown>) => {
+      const format = getFormat(cmdOpts);
+      const globals = getGlobals();
+      const { formatRememberResult, remember } =
+        await import("./commands/memory");
+      const result = await remember({
+        configPath: globals.config,
+        indexName: globals.index,
+        text,
+        collection: cmdOpts.collection as string | undefined,
+        scopes: cmdOpts.scope as string[],
+        decision: cmdOpts.decision as string | undefined,
+        add: Boolean(cmdOpts.add),
+        supersede: cmdOpts.supersede as string | undefined,
+        predecessor: cmdOpts.predecessor as string | undefined,
+        predecessorHash: cmdOpts.predecessorHash as string | undefined,
+        receipt: cmdOpts.receipt as string | undefined,
+        derivedFrom: cmdOpts.derivedFrom as string[],
+        source: cmdOpts.source as string | undefined,
+        caller: cmdOpts.caller as string | undefined,
+        session: cmdOpts.session as string | undefined,
+      });
+      await writeOutput(
+        formatRememberResult(result, {
+          json: format === "json",
+          quiet: globals.quiet,
+        }),
+        format
+      );
+    });
+
+  program
+    .command("recall <query>")
+    .description("Recall current facts from a memory-managed collection")
+    .option("-c, --collection <name>", "memory-managed collection")
+    .option(
+      "--scope <scope>",
+      "explicit scope (repeatable, required; no implicit global scope)",
+      collectRepeatableValue,
+      []
+    )
+    .option("--max-facts <n>", "budget override: max facts (default 8)")
+    .option(
+      "--max-tokens <n>",
+      "budget override: max payload tokens (default 512)"
+    )
+    .option(
+      "--caller <id>",
+      "caller identity (default: $GNO_MEMORY_CALLER or cli:<user>)"
+    )
+    .option(
+      "--session <id>",
+      "session identity (default: $GNO_MEMORY_SESSION or ppid:<pid>)"
+    )
+    .option("--json", "JSON output")
+    .action(async (query: string, cmdOpts: Record<string, unknown>) => {
+      const format = getFormat(cmdOpts);
+      const globals = getGlobals();
+      const { formatRecallResult, recall } = await import("./commands/memory");
+      const result = await recall({
+        configPath: globals.config,
+        indexName: globals.index,
+        query,
+        collection: cmdOpts.collection as string | undefined,
+        scopes: cmdOpts.scope as string[],
+        maxFacts: cmdOpts.maxFacts as number | undefined,
+        maxTokens: cmdOpts.maxTokens as number | undefined,
+        caller: cmdOpts.caller as string | undefined,
+        session: cmdOpts.session as string | undefined,
+      });
+      await writeOutput(
+        formatRecallResult(result, {
+          json: format === "json",
+          quiet: globals.quiet,
+        }),
+        format
+      );
+    });
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Retrieval Commands (get, multi-get, ls)
 // ─────────────────────────────────────────────────────────────────────────────

package/src/config/types.ts

@@ -163,6 +163,13 @@ export const CollectionSchema = z.object({
    */
   sourceAvailability: SourceAvailabilitySchema.optional(),
 
+  /**
+   * Declares the collection as a GNO-managed memory substrate: `remember`
+   * writes fact files here and refuses every collection without the flag.
+   * Omitted means false; ordinary retrieval is unaffected either way.
+   */
+  memoryManaged: z.boolean().optional(),
+
   /** Optional per-collection model overrides */
   models: z
     .object({

package/src/core/audit-provenance.ts

@@ -5,6 +5,7 @@ import type { CaptureSource } from "./capture";
 
 import { compareAuditFindingDrafts } from "./audit";
 import { validateDeclaredCaptureProvenance } from "./capture";
+import { diagnoseMemoryContent } from "./memory-diagnostics";
 import {
   hasDeclaredRecordProvenance,
   validateDeclaredRecordProvenance,
@@ -20,6 +21,11 @@ export interface AuditProvenanceDocument {
   captureSourceSupported?: boolean;
   captureSource?: Partial<CaptureSource>;
   captureSourceDeclared: boolean;
+  /**
+   * Present only for documents in a memory-managed collection: the file
+   * content the memory-record validator runs against (null when unreadable).
+   */
+  memory?: { content: string | null };
   record: {
     recordKey?: string | null;
     recordSourceLocator?: string | null;
@@ -52,6 +58,90 @@ const issueFinding = (input: {
   ],
 });
 
+const memoryFinding = (
+  document: AuditProvenanceDocument,
+  code: string,
+  message: string
+): AuditFindingDraft => ({
+  subject: document.uri,
+  location: code,
+  severity: "warning",
+  message: `memory record excluded from recall: ${message}`,
+  evidence: [
+    {
+      kind: "memory-record-contract",
+      summary: code,
+      uri: document.uri,
+      path: document.relPath,
+    },
+  ],
+  guidance: [
+    "Repair the memory frontmatter (memory.recordId/scopes/caller/session/createdAt/contentHash) or re-create the fact with gno remember",
+  ],
+});
+
+/**
+ * Managed memory files are audited against the memory-record contract; each
+ * malformed file yields one finding per diagnostic code. Ordinary retrieval
+ * still sees such files; managed recall does not.
+ */
+export const evaluateMemoryRecordAudit = (
+  documents: readonly AuditProvenanceDocument[],
+  options: { truncated?: boolean } = {}
+): AuditRuleContribution => {
+  const findings: AuditFindingDraft[] = [];
+  let managedDocuments = 0;
+  let unreadable = 0;
+  for (const document of documents) {
+    if (document.memory === undefined) continue;
+    managedDocuments += 1;
+    if (document.memory.content === null) {
+      unreadable += 1;
+      continue;
+    }
+    const diagnostics = diagnoseMemoryContent(document.memory.content) ?? [];
+    for (const diagnostic of diagnostics) {
+      findings.push(
+        memoryFinding(document, diagnostic.code, diagnostic.message)
+      );
+    }
+  }
+  findings.sort(compareAuditFindingDrafts);
+  const truncated = options.truncated === true;
+  return {
+    ruleId: "provenance.memory-record",
+    category: "provenance",
+    status: truncated
+      ? "inconclusive"
+      : unreadable > 0
+        ? "unavailable"
+        : findings.length > 0
+          ? "fail"
+          : managedDocuments === 0
+            ? "skip"
+            : "pass",
+    message: truncated
+      ? "Audit selection was truncated; memory record contract not fully evaluated"
+      : unreadable > 0
+        ? `${unreadable} memory-managed source(s) could not be read`
+        : findings.length > 0
+          ? `${findings.length} memory record contract violation(s) across ${managedDocuments} managed document(s)`
+          : managedDocuments === 0
+            ? "No memory-managed collections in scope"
+            : `${managedDocuments} managed memory record(s) satisfy the contract`,
+    findings: findings.slice(0, PROVENANCE_AUDIT_MAX_FINDINGS_PER_RULE),
+    findingCount: findings.length,
+    examinedCount: managedDocuments,
+    skipReason: truncated
+      ? "snapshot_truncated"
+      : unreadable > 0
+        ? "source_unavailable"
+        : managedDocuments === 0
+          ? "no_memory_managed_collections"
+          : null,
+  };
+};
+
 /** Missing provenance is completeness evidence, never a truth judgment. */
 export const evaluateProvenanceAudit = (
   documents: readonly AuditProvenanceDocument[],
@@ -150,5 +240,6 @@ export const evaluateProvenanceAudit = (
       recordFindings,
       declaredRecordDocuments
     ),
+    evaluateMemoryRecordAudit(documents, options),
   ];
 };

package/src/core/audit-workspace.ts

@@ -189,6 +189,7 @@ export const groupAuditPhysicalSources = (
 const observeDocument = async (
   document: DocumentRow,
   roots: ReadonlyMap<string, string>,
+  managedCollections: ReadonlySet<string>,
   readFrontmatter: boolean,
   inspectFreshness: boolean,
   signal?: AbortSignal
@@ -196,6 +197,8 @@ const observeDocument = async (
   const markdownSource = MARKDOWN_SOURCE_EXTENSIONS.has(
     document.sourceExt.toLowerCase()
   );
+  const memoryManaged = managedCollections.has(document.collection);
+  const memoryUnreadable = memoryManaged ? { content: null } : undefined;
   const root = roots.get(document.collection);
   if (!root) {
     return {
@@ -206,6 +209,7 @@ const observeDocument = async (
         sourceState: "unreadable",
         captureSourceSupported: markdownSource,
         captureSourceDeclared: false,
+        memory: memoryUnreadable,
         record: document,
       },
       freshness: {
@@ -238,6 +242,7 @@ const observeDocument = async (
           sourceState: "missing",
           captureSourceSupported: markdownSource,
           captureSourceDeclared: false,
+          memory: memoryUnreadable,
           record: document,
         },
         freshness: {
@@ -286,6 +291,11 @@ const observeDocument = async (
         captureSource: incompleteFrontmatter
           ? undefined
           : extractCaptureSourceFromFrontmatter(frontmatter),
+        // Memory facts are small single files, so the bounded frontmatter
+        // read covers the whole record the validator needs.
+        memory: memoryManaged
+          ? { content: incompleteFrontmatter ? null : frontmatter }
+          : undefined,
         record: document,
       },
       freshness: {
@@ -316,6 +326,7 @@ const observeDocument = async (
         sourceState: "unreadable",
         captureSourceSupported: markdownSource,
         captureSourceDeclared: false,
+        memory: memoryUnreadable,
         record: document,
       },
       freshness: {
@@ -382,11 +393,17 @@ const loadWorkspaceSnapshot = async (
   const needsSourceObservation =
     options.categories.includes("provenance") ||
     options.categories.includes("freshness");
+  const managedCollections = new Set(
+    options.collections
+      .filter((collection) => collection.memoryManaged === true)
+      .map((collection) => collection.name)
+  );
   const observed = needsSourceObservation
     ? await mapConcurrent(selected.documents, (document) =>
         observeDocument(
           document,
           roots,
+          managedCollections,
           options.categories.includes("provenance"),
           options.categories.includes("freshness"),
           options.signal

package/src/core/memory-diagnostics.ts

@@ -0,0 +1,144 @@
+/**
+ * Malformed-memory diagnostics projected through status and audit.
+ *
+ * A memory-managed collection may contain hand-edited files that no longer
+ * satisfy the record contract. Ingestion drops their scope rows (so managed
+ * recall never returns them) while ordinary retrieval still sees the file.
+ * This module names those files and their diagnostic codes.
+ *
+ * @module src/core/memory-diagnostics
+ */
+
+import type { Collection } from "../config/types";
+import type { StorePort } from "../store/types";
+import type { MemoryDiagnostic } from "./memory-record";
+
+import { validateMemoryRecord } from "./memory-record";
+
+/** Bounded list of malformed files per collection in status output. */
+export const MEMORY_STATUS_MAX_MALFORMED = 20;
+
+export interface MalformedMemoryRecord {
+  uri: string;
+  relPath: string;
+  codes: string[];
+  diagnostics: MemoryDiagnostic[];
+}
+
+export interface MemoryCollectionStatus {
+  collection: string;
+  /** Active documents indexed in the collection. */
+  documents: number;
+  /** Documents that satisfy the record contract (recallable). */
+  records: number;
+  malformed: number;
+  malformedRecords: MalformedMemoryRecord[];
+  /** True when more malformed files exist than were listed. */
+  truncated: boolean;
+}
+
+export interface MemoryStatus {
+  managedCollections: number;
+  records: number;
+  malformed: number;
+  collections: MemoryCollectionStatus[];
+}
+
+export const memoryManagedCollections = (
+  collections: readonly Collection[]
+): Collection[] =>
+  collections.filter((collection) => collection.memoryManaged === true);
+
+/** Validate one indexed file as a memory record (null when unreadable). */
+export const diagnoseMemoryContent = (
+  content: string
+): MemoryDiagnostic[] | null => {
+  const validation = validateMemoryRecord(content);
+  return validation.ok ? [] : validation.diagnostics;
+};
+
+/**
+ * Scan every active document of each memory-managed collection through the
+ * validator. Read-only; bounded by the collection's own document count.
+ */
+export async function buildMemoryStatus(
+  store: Pick<StorePort, "listDocuments" | "getContent">,
+  collections: readonly Collection[],
+  options: { maxListed?: number } = {}
+): Promise<MemoryStatus> {
+  const maxListed = options.maxListed ?? MEMORY_STATUS_MAX_MALFORMED;
+  const statuses: MemoryCollectionStatus[] = [];
+  for (const collection of memoryManagedCollections(collections)) {
+    const listed = await store.listDocuments(collection.name);
+    const documents = listed.ok
+      ? listed.value.filter((document) => document.active)
+      : [];
+    let records = 0;
+    const malformedRecords: MalformedMemoryRecord[] = [];
+    let malformed = 0;
+    for (const document of documents) {
+      if (!document.mirrorHash) continue;
+      const content = await store.getContent(document.mirrorHash);
+      if (!content.ok || content.value === null) continue;
+      const diagnostics = diagnoseMemoryContent(content.value);
+      if (diagnostics === null) continue;
+      if (diagnostics.length === 0) {
+        records += 1;
+        continue;
+      }
+      malformed += 1;
+      if (malformedRecords.length < maxListed) {
+        malformedRecords.push({
+          uri: document.uri,
+          relPath: document.relPath,
+          codes: [...new Set(diagnostics.map((item) => item.code))],
+          diagnostics,
+        });
+      }
+    }
+    malformedRecords.sort((left, right) =>
+      left.uri < right.uri ? -1 : left.uri > right.uri ? 1 : 0
+    );
+    statuses.push({
+      collection: collection.name,
+      documents: documents.length,
+      records,
+      malformed,
+      malformedRecords,
+      truncated: malformed > malformedRecords.length,
+    });
+  }
+  return {
+    managedCollections: statuses.length,
+    records: statuses.reduce((sum, item) => sum + item.records, 0),
+    malformed: statuses.reduce((sum, item) => sum + item.malformed, 0),
+    collections: statuses,
+  };
+}
+
+/** Terminal lines for the `gno status` memory section. */
+export function formatMemoryStatusLines(status: MemoryStatus): string[] {
+  if (status.managedCollections === 0) {
+    return ["Memory: no memory-managed collections"];
+  }
+  const lines = [
+    `Memory: ${status.records} records, ${status.malformed} malformed across ${status.managedCollections} managed collection${status.managedCollections === 1 ? "" : "s"}`,
+  ];
+  for (const collection of status.collections) {
+    lines.push(
+      `  ${collection.collection}: ${collection.records} records` +
+        (collection.malformed > 0
+          ? `, ${collection.malformed} malformed (excluded from recall)`
+          : "")
+    );
+    for (const record of collection.malformedRecords) {
+      lines.push(`    ${record.relPath}: ${record.codes.join(", ")}`);
+    }
+    if (collection.truncated) {
+      lines.push(
+        `    ... ${collection.malformed - collection.malformedRecords.length} more (run: gno audit --category provenance)`
+      );
+    }
+  }
+  return lines;
+}