@remnic/core 9.65.1 → 9.65.2

package/src/procedural/procedure-stats.ts

@@ -12,6 +12,8 @@
  */
 import type { MemoryFile, MemoryStatus, PluginConfig } from "../types.js";
 import type { StorageManager } from "../storage.js";
+import { isActiveMemoryStatus } from "../memory-lifecycle-ledger-utils.js";
+import { readProcedureMaintenanceMarker } from "./library-maintenance.js";
 
 export interface ProcedureStatusCounts {
   total: number;
@@ -50,6 +52,10 @@ export interface ProcedureStatsReport {
   counts: ProcedureStatusCounts;
   recent: ProcedureStatsRecent;
   config: ProcedureStatsConfigSnapshot;
+  /** ISO timestamp of the last library-maintenance run marker, or null (issue #2370). */
+  lastMaintenanceAt: string | null;
+  /** Active procedures currently carrying a `needsRepair` flag (issue #2370). */
+  needsRepairFlags: number;
 }
 
 function snapshotConfig(config: PluginConfig): ProcedureStatsConfigSnapshot {
@@ -102,6 +108,7 @@ export async function computeProcedureStats(options: {
   let lastWriteMs: number | null = null;
   let writesLast7Days = 0;
   let minerSourced = 0;
+  let needsRepairFlags = 0;
 
   const known: MemoryStatus[] = [
     "active",
@@ -159,8 +166,15 @@ export async function computeProcedureStats(options: {
     if (m.frontmatter.source === "procedure-miner") {
       minerSourced += 1;
     }
+    if (
+      m.frontmatter.structuredAttributes?.needsRepair !== undefined &&
+      isActiveMemoryStatus(m.frontmatter.status)
+    ) {
+      needsRepairFlags += 1;
+    }
   }
 
+  const maintenanceMarker = await readProcedureMaintenanceMarker(storage.dir);
   return {
     schemaVersion: 1,
     generatedAt: new Date(nowMs).toISOString(),
@@ -171,6 +185,8 @@ export async function computeProcedureStats(options: {
       minerSourced,
     },
     config: snapshotConfig(config),
+    lastMaintenanceAt: maintenanceMarker?.lastRunAt ?? null,
+    needsRepairFlags,
   };
 }
 
@@ -210,5 +226,9 @@ export function formatProcedureStatsText(report: ProcedureStatsReport): string {
   lines.push(`    lastWriteAt:      ${recent.lastWriteAt ?? "(none)"}`);
   lines.push(`    writesLast7Days:  ${recent.writesLast7Days}`);
   lines.push(`    minerSourced:     ${recent.minerSourced}`);
+  lines.push("");
+  lines.push(`  maintenance:`);
+  lines.push(`    lastMaintenanceAt: ${report.lastMaintenanceAt ?? "(never)"}`);
+  lines.push(`    needsRepairFlags:  ${report.needsRepairFlags}`);
   return lines.join("\n") + "\n";
 }

package/src/schemas.ts

@@ -103,6 +103,13 @@ export const ExtractedFactSchema = z.object({
     .describe(
       'Scope classification: "global" for cross-project knowledge (framework bugs, library behavior, API patterns, user preferences, general coding patterns); "project" for project-specific knowledge (file paths, env configs, deployment details, project workarounds) and for tool, command, or CLI-flag instructions tied to one agent, since the same tool name can mean different things across agents. When keeping such an agent-tied instruction, begin the fact with a leading "In <agent>," clause naming that agent. Defaults to "project" when a coding context is active.',
     ),
+  subject: z
+    .enum(["user", "agent"])
+    .optional()
+    .nullable()
+    .describe(
+      'Memory subject: "user" when the fact models the person (preferences, relationships, biography, moments, commitments about their life); "agent" when it is reusable operating knowledge (procedures, principles, tool-usage lessons, debugging strategies, environment facts with no personal content). Emit only for fact/decision-like facts; the category defaults cover preference, relationship, moment, commitment, procedure, principle, and skill.',
+    ),
   quote: z
     .string()
     .optional()

package/src/spaces/index.ts

@@ -8,6 +8,8 @@
  * through push/pull and promotion workflows.
  */
 
+import { evaluateSubjectGuard } from "../memory-subject.js";
+import type { SubjectGuardMode } from "../types.js";
 import { spawnSync } from "node:child_process";
 import crypto from "node:crypto";
 import fs from "node:fs";
@@ -99,6 +101,8 @@ export interface SpacePromoteResult {
   memoriesPromoted: number;
   conflicts: ConflictEntry[];
   durationMs: number;
+  /** Subject-guard warnings (issue #2372): user-subject memories promoted to a shared team space under "warn". */
+  subjectWarnings?: string[];
 }
 
 export interface ConflictEntry {
@@ -748,7 +752,10 @@ export function shareSpace(spaceId: string, members: string[], baseDir?: string)
 export async function promoteSpace(
   sourceSpaceId: string,
   targetSpaceId: string,
-  options?: { memoryIds?: string[]; force?: boolean; forceOverwrite?: boolean; baseDir?: string }
+  options?: {
+    memoryIds?: string[]; force?: boolean; forceOverwrite?: boolean; baseDir?: string;
+    subjectGuard?: SubjectGuardMode; allowUserSubject?: boolean;
+  }
 ): Promise<SpacePromoteResult> {
   const startTime = Date.now();
   const manifest = loadManifest(options?.baseDir);
@@ -766,6 +773,33 @@ export async function promoteSpace(
     }
   }
 
+  // Subject guard (issue #2372): the SAME gate as the scope-profile promotion
+  // path — a user-subject (or unstamped, fail-closed) memory promoted into a
+  // TEAM space warns/rejects with the override named; recorded in the audit trail.
+  const subjectWarnings: string[] = [];
+  const warnedMemoryIds: string[] = [];
+  if (target.kind === "team") {
+    const sourceFiles = fs.existsSync(source.memoryDir) ? walkMd(fs.realpathSync(source.memoryDir)) : [];
+    for (const file of sourceFiles) {
+      const fm = parseSimpleFrontmatter(fs.readFileSync(file, "utf8"));
+      if (!fm?.id) continue;
+      if (options?.memoryIds?.length && !options.memoryIds.includes(fm.id)) continue;
+      const decision = evaluateSubjectGuard({
+        subject: fm.subject === "user" || fm.subject === "agent" ? fm.subject : undefined,
+        sharedTarget: true,
+        mode: options?.subjectGuard ?? "warn",
+        allowUserSubject: options?.allowUserSubject,
+      });
+      if (decision.action === "reject") {
+        throw new Error(`space promote blocked by subject guard: memory ${fm.id} — ${decision.reason}`);
+      }
+      if (decision.action === "warn") {
+        subjectWarnings.push(`memory ${fm.id}: ${decision.reason}`);
+        warnedMemoryIds.push(fm.id);
+      }
+    }
+  }
+
   const result = await copyMemories(source.memoryDir, target.memoryDir, {
     filterIds: options?.memoryIds,
     force: options?.forceOverwrite !== undefined ? options.forceOverwrite : (options?.force ?? false),
@@ -776,7 +810,8 @@ export async function promoteSpace(
       action: "space.promote",
       sourceSpaceId,
       targetSpaceId,
-      details: `Promoted ${result.merged} memories from "${source.name}" to "${target.name}"`,
+      details: `Promoted ${result.merged} memories from "${source.name}" to "${target.name}"${subjectWarnings.length > 0 ? `; subject-guard warned ${subjectWarnings.length} user-subject memories (${warnedMemoryIds.join(", ")})` : ""}${options?.allowUserSubject === true ? "; user-subject override: --allow-user-subject" : ""}`,
+      ...(warnedMemoryIds.length > 0 ? { memoryIds: warnedMemoryIds } : {}),
     },
     options?.baseDir
   );
@@ -787,6 +822,7 @@ export async function promoteSpace(
     memoriesPromoted: result.merged,
     conflicts: result.conflicts,
     durationMs: Date.now() - startTime,
+    ...(subjectWarnings.length > 0 ? { subjectWarnings } : {}),
   };
 }
 

package/src/storage.ts

@@ -166,6 +166,7 @@ import type {
   VerificationState,
   PolicyClass,
   MemoryStatus,
+  MemorySubject,
   MemoryActionEvent,
   MemoryLifecycleEvent,
   MemoryLifecycleEventType,
@@ -326,6 +327,7 @@ function serializeFrontmatter(fm: MemoryFrontmatter): string {
   if (fm.language) lines.push(`language: ${fm.language}`);
   if (fm.type !== undefined) lines.push(`type: ${fm.type}`);
   if (fm.origin) lines.push(`origin: ${/^[A-Za-z0-9:_.*-]+$/.test(fm.origin) ? fm.origin : JSON.stringify(fm.origin)}`);
+  if (fm.subject) lines.push(`subject: ${fm.subject}`);
   if (fm.entityRef) lines.push(`entityRef: ${fm.entityRef}`);
   if (fm.sourceConnector) {
     // YAML-injection guard (review thread QMPsP): emit unquoted for
@@ -871,6 +873,7 @@ export function parseFrontmatter(raw: string): { frontmatter: MemoryFrontmatter;
       tags,
       entityRef: fm.entityRef || undefined,
       origin: fm.origin !== undefined ? parseOriginClass(decodeYamlScalar(fm.origin)) : undefined,
+      subject: fm.subject === "user" || fm.subject === "agent" ? fm.subject : undefined,
       sourceConnector: fm.sourceConnector ? decodeYamlScalar(fm.sourceConnector) || undefined : undefined,
       toolScoped: fm.toolScoped === "true" ? true : undefined,
       supersedes: fm.supersedes || undefined,
@@ -1739,6 +1742,7 @@ export interface WriteMemoryOptions {
   origin?: string;
   sourceConnector?: string;
   toolScoped?: true;
+  subject?: MemorySubject;
 }
 
 /**
@@ -1747,7 +1751,7 @@ export interface WriteMemoryOptions {
  */
 export type SealedWriteExtras = Omit<
   WriteMemoryOptions,
-  "confidence" | "tags" | "entityRef" | "source" | "expiresAt" | "validAt" | "structuredAttributes" | "sourceConnector" | "origin"
+  "confidence" | "tags" | "entityRef" | "source" | "expiresAt" | "validAt" | "structuredAttributes" | "sourceConnector" | "origin" | "subject"
 >;
 
 export class StorageManager extends TombstoneBlockedCaptureIndexHost {
@@ -3791,7 +3795,7 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
       fm.sourceConnector = options.sourceConnector;
     }
     if (options.origin !== undefined) fm.origin = parseOriginClass(options.origin);
-
+    if (options.subject !== undefined) fm.subject = options.subject;
     // Assemble the persisted body (attribute-suffix enrichment + combined
     // sanitize) via the SHARED helper — the sealed-envelope composer uses the
     // same one, so the two write paths cannot diverge (issue #1989 PR2).

package/src/subject-config.ts

@@ -0,0 +1,80 @@
+/**
+ * Config parsing for the memory-subject runtime knobs (issue #2372).
+ *
+ * Extracted from config.ts (its structural-ratchet ceiling forbids growth);
+ * `parseConfig` spreads `parseSubjectRuntimeConfig(cfg)` into the plugin
+ * config literal.
+ *
+ * Validation posture (Review Prevention Checklist §1/§24/§39): invalid
+ * values are REJECTED loudly, never silently reinterpreted — but an omitted
+ * key takes the documented default. The deliberate asymmetry from the issue
+ * stands: classification defaults OFF while the guard defaults "warn", so
+ * enabling classification later immediately yields promotion warnings
+ * without a second flag flip, and with classification off, unstamped
+ * memories still only warn (never silently promote) at shared targets.
+ */
+
+import { coerceBool, coerceNumber } from "./connectors/coerce.js";
+import {
+  isSubjectGuardMode,
+  PROMOTION_CANDIDATES_DEFAULT_MIN_ACCESS,
+} from "./memory-subject.js";
+import type { SubjectGuardMode } from "./types.js";
+
+export interface SubjectRuntimeConfig {
+  subjectClassification: { enabled: boolean };
+  subjectGuard: SubjectGuardMode;
+  promotionCandidates: { minAccessCount: number };
+}
+
+/**
+ * Reject a non-object block loudly (rule 51 / §1): a shorthand like
+ * `subjectClassification: false` must never normalize silently to `{}`.
+ * Returns void so callers read the block through a DIRECT `cfg.<key>`
+ * member access — the config-contract parser walker derives nested key
+ * paths from those accesses, and a helper return value hides them.
+ */
+function assertObjectBlock(value: unknown, key: string, shape: string): void {
+  if (value === undefined) return;
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new Error(
+      `${key} must be an object (got ${JSON.stringify(value)}). Use ${shape} (issue #2372).`,
+    );
+  }
+}
+
+export function parseSubjectRuntimeConfig(cfg: Record<string, unknown>): SubjectRuntimeConfig {
+  assertObjectBlock(cfg.subjectClassification, "subjectClassification", "subjectClassification: { enabled: true }");
+  const classification = (cfg.subjectClassification ?? {}) as Record<string, unknown>;
+  const rawEnabled = classification.enabled;
+  const enabledCoerced = coerceBool(rawEnabled);
+  if (rawEnabled !== undefined && enabledCoerced === undefined) {
+    throw new Error(
+      `subjectClassification.enabled must be a boolean or one of "true"/"false"/"1"/"0"/` +
+        `"yes"/"no"/"on"/"off" (got ${JSON.stringify(rawEnabled)}) — rejected, not defaulted (issue #2372).`,
+    );
+  }
+  const rawGuard = cfg.subjectGuard;
+  if (rawGuard !== undefined && !isSubjectGuardMode(rawGuard)) {
+    throw new Error(
+      `subjectGuard must be one of: off, warn, enforce (got ${JSON.stringify(rawGuard)}) — ` +
+        `rejected, not defaulted (issue #2372; checklist §1/§39).`,
+    );
+  }
+  assertObjectBlock(cfg.promotionCandidates, "promotionCandidates", "promotionCandidates: { minAccessCount: 3 }");
+  const candidates = (cfg.promotionCandidates ?? {}) as Record<string, unknown>;
+  const minAccessRaw = coerceNumber(candidates.minAccessCount);
+  if (candidates.minAccessCount !== undefined && (minAccessRaw === undefined || !Number.isFinite(minAccessRaw) || minAccessRaw < 0)) {
+    throw new Error(
+      `promotionCandidates.minAccessCount must be a non-negative number (got ${JSON.stringify(candidates.minAccessCount)}) — rejected, not defaulted (issue #2372).`,
+    );
+  }
+  return {
+    subjectClassification: { enabled: rawEnabled === undefined ? false : enabledCoerced === true },
+    subjectGuard: isSubjectGuardMode(rawGuard) ? rawGuard : "warn",
+    promotionCandidates: {
+      minAccessCount:
+        minAccessRaw !== undefined ? Math.floor(minAccessRaw) : PROMOTION_CANDIDATES_DEFAULT_MIN_ACCESS,
+    },
+  };
+}

package/src/types.ts

@@ -11,8 +11,11 @@ import type { ContradictionLocalizationConfig, ContradictionScanConfig } from ".
 import type { GraphPathScoringConfig } from "./graph-path-scoring-config.js";
 export type { ContradictionLocalizationConfig, ContradictionScanConfig } from "./contradiction-config.js";
 export type { GraphPathScoringConfig } from "./graph-path-scoring-config.js";
+import type { ProceduralMaintenanceConfig } from "./procedural/maintenance-config.js";
 
 import type { AmbientCaptureProvenance, BufferTurnOwner, SecurityConfig, OriginMetadata } from "./security/types.js";
+export type MemorySubject = "user" | "agent";
+export type SubjectGuardMode = "off" | "warn" | "enforce";
 export type ReasoningEffort = "none" | "low" | "medium" | "high";
 export type TriggerMode = "smart" | "every_n" | "time_based";
 export type ConvergeConflictPolicy = "newest-wins" | "manual";
@@ -383,7 +386,6 @@ export interface DreamsPhasesConfig {
   deepSleep: DreamsDeepSleepConfig;
 }
 
-/** Procedural memory (issue #519): mining + recall gates. All sub-features default off. */
 export interface ProceduralConfig {
   enabled: boolean;
   /** Minimum cluster size before emitting a candidate; `0` disables mining (`minOccurrences_zero`). */
@@ -396,8 +398,8 @@ export interface ProceduralConfig {
   lookbackDays: number;
   /** When true, installer may register the nightly procedural mining cron (default off). */
   proceduralMiningCronAutoRegister: boolean;
-  /** Max procedure memories to inject on task-initiation recall (1–10). */
   recallMaxProcedures: number;
+  maintenance: ProceduralMaintenanceConfig;
 }
 
 /**
@@ -1041,14 +1043,11 @@ export interface PluginConfig extends BoundedJsonlStateConfig, SecurityConfig {
   recallMaxConcurrentPerPrincipal: number;
   /** Coalesce identical concurrent recalls per principal; each caller gets its own clone. Default true. */
   recallSingleFlightEnabled: boolean;
-  // Memory Worth recall filter (issue #560 PR 4)
   /**
-   * When true, recall multiplies candidate scores by the Memory Worth
-   * factor computed from `mw_success` / `mw_fail` counters on each
-   * memory's frontmatter (see `computeMemoryWorth`). Memories with a
-   * history of failed sessions sink; neutral / uninstrumented memories
-   * are untouched (multiplier 1.0). Default false — flip to true in PR 5
-   * once the benchmark shows precision tie-or-win.
+   * When true, recall multiplies candidate scores by the Memory Worth factor
+   * from `mw_success` / `mw_fail` (see `computeMemoryWorth`): failed memories
+   * sink; neutral ones untouched (multiplier 1.0). Default false until the
+   * benchmark shows precision tie-or-win.
    */
   recallMemoryWorthFilterEnabled: boolean;
   /**
@@ -1265,6 +1264,10 @@ export interface PluginConfig extends BoundedJsonlStateConfig, SecurityConfig {
   codexCompat: CodexCompatConfig;
   /** When true (default), LLM classifies facts as `"project"` or `"global"` scope for promotion across projects. */
   extractionScopeClassificationEnabled: boolean;
+  subjectClassification: { enabled: boolean };
+  subjectGuard: SubjectGuardMode;
+  /** Min accessCount reuse signal for promotion candidates (issue #2372). Default 3. */
+  promotionCandidates: { minAccessCount: number };
   // Extraction judge (issue #376)
   /** Enable the LLM-as-judge fact-worthiness gate on extracted facts. Default false (opt-in). */
   extractionJudgeEnabled: boolean;
@@ -2804,6 +2807,8 @@ export interface MemoryFrontmatter extends SourceConnectorProvenance, OriginMeta
   /** True when write-time classification ties this memory to its source connector's tools or commands. */
   toolScoped?: true;
   id: string;
+  /** Whom this memory models (issue #2372). The promotion guard treats absent as "user" (fail closed). */
+  subject?: MemorySubject;
   category: MemoryCategory;
   /** OKF v0.1 interop metadata (issue #1946). Inert: presentation only, never overrides `category`. */
   type?: string;
@@ -2824,12 +2829,8 @@ export interface MemoryFrontmatter extends SourceConnectorProvenance, OriginMeta
   /** Memory status: active (default), pending_review, rejected, quarantined, superseded, archived, or forgotten */
   status?: MemoryStatus;
   /**
-   * Tombstone block marker (issue #1579). When a new fact matches an active
-   * tombstone at the storage chokepoint, it is persisted with
-   * `status: "pending_review"` and this field set to the tombstone id — making
-   * the block VISIBLE (rule 34: never a silent drop) rather than silently
-   * discarding the extraction. Approving the memory through the review queue
-   * emits a revocation that re-allows the content.
+   * Tombstone block marker (issue #1579): persisted `pending_review` with this
+   * set to the tombstone id — a VISIBLE block (rule 34); approval revokes it.
    */
   blockedBy?: string;
   /** Which tombstone tier matched (`exact`/`normalized`/`keyed`/`semantic`). */
@@ -3234,29 +3235,25 @@ export interface ExtractedFact {
    */
   provenance?: "verified" | "unverified" | "none";
   /**
-   * Transient LLM-provided supporting quote (issue #1575 PR 2). Consumed by
-   * the post-parse validator to build `sources`, then stripped before the
-   * fact reaches persistence. NEVER included in content-hash dedup (rule 23 /
-   * checklist §13). Absent on facts that have already passed the validator.
+   * Transient LLM quote (issue #1575 PR 2): consumed by the post-parse
+   * validator to build `sources`, stripped before persistence, never in
+   * content-hash dedup (rule 23 / checklist §13).
    */
   quote?: string;
   /**
-   * Transient requireSpans signal (issue #1575 PR 2). Set by the provenance
-   * validator (`ProvenanceBuildResult.requireSpansPending`) when
-   * `provenance.requireSpans` is enabled and the quote could not be located
-   * in any source turn. Read by the persist path to route the fact to
-   * `pending_review` instead of `active`. Stripped before persistence —
-   * it never reaches frontmatter (chatgpt-codex-connector thread 4xB).
+   * Transient requireSpans signal (#1575 PR 2): quote unlocatable while
+   * `provenance.requireSpans` is on. Persist path routes the fact to
+   * `pending_review`. Stripped before persistence — never reaches frontmatter.
    */
   requireSpansPending?: boolean;
   promptedByQuestion?: string;
   /**
-   * Whether this fact is project-scoped or globally applicable.
-   * When `extractionScopeClassificationEnabled` is true, the extraction LLM
-   * classifies each fact. Default is `"project"` when a coding context is
-   * active, `"global"` when no coding context is present.
+   * Project- vs global-scoped; emitted when `extractionScopeClassificationEnabled`.
+   * Defaults to "project" with a coding context active, else "global".
    */
   scope?: MemoryScope;
+  /** Extractor-assigned subject, present only when subjectClassification.enabled (issue #2372). */
+  subject?: MemorySubject;
   /** Structured key-value attributes extracted from the content (e.g., product attributes, dates, quantities). */
   structuredAttributes?: Record<string, string>;
   /** When category is `procedure`, ordered steps with intents (persisted under procedures/). */

package/src/write-envelope.test.ts

@@ -9,6 +9,7 @@ import {
   WRITE_FINGERPRINT_FIELDS,
   buildWriteIdempotencyPayload,
   composeMemoryEnvelope,
+  sealedWriteToLegacyArgs,
   isSealedMemoryEnvelope,
   type FingerprintScope,
   type MemoryWriteInput,
@@ -198,6 +199,7 @@ test("registry and exempt list disjointly cover every MemoryWriteInput field", (
     sourceConnector: "bee",
     sourceReason: "r",
     origin: "user",
+    subject: "user",
   };
   for (const key of Object.keys(populated)) {
     assert.ok(classified.has(key), `field ${key} is not classified`);
@@ -682,3 +684,15 @@ test("structural fallback rejects prototype-inherited accessors (round 13)", ()
     "prototype-inherited getter lookalike must be rejected",
   );
 });
+
+test("sealedWriteToLegacyArgs always copies sourceConnector from the envelope", () => {
+  const envelope = composeMemoryEnvelope(
+    minimalInput({ sourceConnector: "chatgpt" }),
+    CTX,
+  );
+  const mapped = sealedWriteToLegacyArgs(envelope, { sourceConnector: "smuggled" });
+  assert.equal(mapped.options.sourceConnector, "chatgpt");
+  const empty = composeMemoryEnvelope(minimalInput(), CTX);
+  const cleared = sealedWriteToLegacyArgs(empty, { sourceConnector: "smuggled" });
+  assert.equal(cleared.options.sourceConnector, undefined);
+});

package/src/write-envelope.ts

@@ -24,7 +24,8 @@
  * the write call sites onto this module (see #1989 for the slicing).
  */
 
-import type { MemoryCategory } from "./types.js";
+import { isMemorySubject } from "./memory-subject.js";
+import type { MemoryCategory, MemorySubject } from "./types.js";
 import { normalizeTags } from "./recall-tag-filter.js";
 import { parseFlexibleIsoTimestamp } from "./utils/iso-timestamp.js";
 import { assemblePersistedBody } from "./structured-attributes.js";
@@ -61,6 +62,8 @@ export interface MemoryWriteInput {
   sourceConnector?: string;
   /** Origin class stamped at creation time (issue #1955). */
   origin?: string;
+  /** Whom the memory models (issue #2372): "user" or "agent". */
+  subject?: MemorySubject;
   /** Human-readable provenance note. */
   sourceReason?: string;
 }
@@ -184,6 +187,7 @@ export interface SealedMemoryEnvelope {
   readonly validAt: string | undefined;
   readonly sourceConnector: string | undefined;
   readonly origin: string | undefined;
+  readonly subject: MemorySubject | undefined;
   readonly sourceReason: string | undefined;
   readonly source: string;
   /** ISO timestamp the envelope was composed (from ctx.now). */
@@ -430,6 +434,18 @@ export function composeMemoryEnvelope(
     }
   }
 
+  let subject: MemorySubject | undefined;
+  if (input.subject !== undefined) {
+    if (!isMemorySubject(input.subject)) {
+      hygiene.flag(
+        "subject",
+        `must be "user" or "agent" (got ${JSON.stringify(input.subject)}) — dropped`,
+      );
+    } else {
+      subject = input.subject;
+    }
+  }
+
   // validAt stays FATAL in salvage too: legacy writeMemory throws on an
   // invalid validAt (normalizeMemoryWriteTimestamp), so salvage-dropping it
   // would CHANGE behavior rather than preserve it.
@@ -465,11 +481,12 @@ export function composeMemoryEnvelope(
     structuredAttributes: attributes?.canonical,
     rawStructuredAttributes: attributes?.raw,
     entityRef: normalizeOptionalString("entityRef", input.entityRef, hygiene),
+    origin: normalizeOptionalString("origin", input.origin, hygiene),
+    subject,
     confidence,
     ttl: normalizeOptionalString("ttl", input.ttl, hygiene),
     validAt,
     sourceConnector: normalizeOptionalString("sourceConnector", input.sourceConnector, hygiene),
-    origin: normalizeOptionalString("origin", input.origin, hygiene),
     sourceReason: normalizeOptionalString("sourceReason", input.sourceReason, hygiene),
     source: ctx.source.trim(),
     composedAt: now.toISOString(),
@@ -656,8 +673,9 @@ export function sealedWriteToLegacyArgs(
       // extras — a conditional spread let extras.sourceConnector smuggle
       // unvalidated connector provenance past the sealed envelope when the
       // envelope had none.
-      sourceConnector: envelope.sourceConnector,
       origin: envelope.origin,
+      sourceConnector: envelope.sourceConnector,
+      subject: envelope.subject,
     },
   };
 }
@@ -695,6 +713,9 @@ export const FINGERPRINT_EXEMPT_FIELDS = [
   // Free-text provenance note; carries no identity.
   // Origin is provenance metadata, not write identity (#1955).
   "origin",
+  // Subject is derived classification metadata (#2372): two writes identical
+  // except subject are the same memory for dedup purposes.
+  "subject",
   "sourceReason",
 ] as const satisfies readonly (keyof MemoryWriteInput)[];