@remnic/core 9.64.1 → 9.64.3

package/src/storage/entity-store.ts

@@ -45,6 +45,9 @@ import {
   serializeEntityFile,
   StorageManager,
 } from "../storage.js";
+// Issue #1533 Phase B: importers take entity-file parsing from this storage/
+// subsystem module, not the storage.ts god file (see check-ratchets.mjs).
+export { parseEntityFile } from "../storage.js";
 import { parseOriginClass } from "../security/origin-authority.js";
 
 export interface EntityStoreDeps {
@@ -64,6 +67,7 @@ export interface EntityStoreDeps {
   getMemoryStatusVersion(): number;
   invalidateKnowledgeIndexCache(): void;
   knowledgeIndexCache: { result: string; builtAt: number } | null;
+  okfConformanceEnabled(): boolean;
   normalizeEntityName(raw: string, type: string): string;
   readAllEntityFiles(): Promise<EntityFile[]>;
   readStorageSecureFile(filePath: string): Promise<string>;
@@ -142,7 +146,7 @@ export class EntityStore {
         located.entity.updated = new Date().toISOString();
         await this.deps.writeStorageSecureFile(
           located.filePath,
-          serializeEntityFile(located.entity, this.deps.entitySchemas),
+          serializeEntityFile(located.entity, this.deps.entitySchemas, this.deps.okfConformanceEnabled()),
         );
         reconcileIfJournalMovedSync(stateDir, idsAtResolve, this.deps.currentHistoricalIds());
         this.deps.invalidateKnowledgeIndexCache();
@@ -352,7 +356,7 @@ export class EntityStore {
     entity.updated = new Date().toISOString();
 
     await this.deps.snapshotBeforeWrite(filePath, "write");
-    await this.deps.writeStorageSecureFile(filePath, serializeEntityFile(entity, this.deps.entitySchemas));
+    await this.deps.writeStorageSecureFile(filePath, serializeEntityFile(entity, this.deps.entitySchemas, this.deps.okfConformanceEnabled()));
     this.deps.invalidateKnowledgeIndexCache();
     this.deps.bumpMemoryStatusVersion(); // invalidate entity cache
     this.deps.bumpEntityMutationVersion();
@@ -401,7 +405,7 @@ export class EntityStore {
       const wrote = await withEntityCanonicalMutationLock(stateDir, async () => {
         const raw = await this.readEntity(entityName);
         if (!raw) return false;
-        const serialized = serializeEntityFile(parseEntityFile(raw, this.deps.entitySchemas), this.deps.entitySchemas);
+        const serialized = serializeEntityFile(parseEntityFile(raw, this.deps.entitySchemas), this.deps.entitySchemas, this.deps.okfConformanceEnabled());
         if (raw.trimEnd() === serialized.trimEnd()) return false;
         const filePath = this.deps.resolveEntityFilePath(entityName);
         if (filePath === null) return false;
@@ -484,7 +488,7 @@ export class EntityStore {
     entity.synthesisVersion = Math.max(0, entity.synthesisVersion ?? 0)
       + (options.incrementVersion === false ? 0 : 1);
     entity.updated = entityUpdatedAt;
-    await this.deps.writeStorageSecureFile(filePath, serializeEntityFile(entity, this.deps.entitySchemas));
+    await this.deps.writeStorageSecureFile(filePath, serializeEntityFile(entity, this.deps.entitySchemas, this.deps.okfConformanceEnabled()));
     await this.deps.removeEntitySynthesisQueueEntries([
       ...new Set([name, this.deps.normalizeEntityName(entity.name, entity.type)]),
     ]);
@@ -898,7 +902,7 @@ export class EntityStore {
         mergedEntity.updated = mergedEntity.updated || new Date().toISOString();
 
         const canonicalPath = path.join(this.deps.entitiesDir, `${canonical}.md`);
-        await this.deps.writeStorageSecureFile(canonicalPath, serializeEntityFile(mergedEntity, this.deps.entitySchemas));
+        await this.deps.writeStorageSecureFile(canonicalPath, serializeEntityFile(mergedEntity, this.deps.entitySchemas, this.deps.okfConformanceEnabled()));
         this.deps.bumpEntityMutationVersion();
 
         // Remove non-canonical files

package/src/storage/profile-header.ts

@@ -245,12 +245,6 @@ function findHtmlTagPrefix(line: string): HtmlTag | null {
   return null;
 }
 
-function isRawHtmlBlockTerminator(line: string): boolean {
-  const normalizedLine = line.toLowerCase();
-  return RAW_HTML_BLOCK_TAGS.some((name) =>
-    hasRawHtmlBlockEndMarker(normalizedLine, `</${name}>`),
-  );
-}
 
 function findHtmlTags(line: string): HtmlTag[] {
   const tags: HtmlTag[] = [];
@@ -429,9 +423,6 @@ function shouldCloseHtmlBlock(line: string, endMarker: string): boolean {
 }
 
 
-function hasRawHtmlBlockEndMarker(line: string, endMarker: string): boolean {
-  return line.includes(endMarker);
-}
 function canStartGenericHtmlBlock(
   lines: ProfileLine[],
   index: number,
@@ -896,3 +887,36 @@ export function renderProfileWithLastUpdated(content: string, updatedAt: string)
   insertHeaderAfter(lines, titleIndex, header);
   return renderProfileLines(lines);
 }
+
+/**
+ * OKF v0.1 profile frontmatter (issue #1946). `profile.md` gains a leading
+ * frontmatter block so the memory directory is a conformant OKF knowledge
+ * bundle; every reader strips it so the bytes injected into prompts are
+ * unchanged. Line-scan based (no regex) per the regex-safety rule.
+ */
+
+/** Prepend the OKF block when enabled and not already present. No-op otherwise. */
+export function withOkfProfileFrontmatter(content: string, timestamp: string, enabled: boolean): string {
+  if (!enabled || stripOkfProfileFrontmatter(content) !== content) return content;
+  return `---\ntype: Profile\ntitle: User Profile\ntimestamp: ${timestamp}\n---\n${content}`;
+}
+
+/**
+ * Strip the OKF profile block from the start of `profile.md` content.
+ * Only a leading block whose keys include `type: Profile` is removed, so
+ * hand-written content without the marker round-trips byte-identically.
+ */
+export function stripOkfProfileFrontmatter(content: string): string {
+  if (!content.startsWith("---\n") && !content.startsWith("---\r\n")) return content;
+  const lines = content.split("\n");
+  for (let index = 1; index < lines.length; index += 1) {
+    const line = lines[index]!;
+    if (line === "---" || line === "---\r") {
+      return lines.slice(1, index).some((l) => l.startsWith("type: Profile"))
+        ? lines.slice(index + 1).join("\n")
+        : content;
+    }
+    if (line === "" || line === "\r" || line === "...") return content;
+  }
+  return content;
+}

package/src/storage/questions-file.ts

@@ -0,0 +1,50 @@
+/**
+ * Question file format (issue #1946 extraction from storage.ts so the
+ * surface file stays under its structural ceiling). Pure text parsing —
+ * no filesystem, no caches; StorageManager delegates through so the
+ * selfDeps consumers (MemoryReadStore) keep their seam unchanged.
+ */
+import path from "node:path";
+
+export interface ParsedQuestionFile {
+  id: string;
+  question: string;
+  context: string;
+  priority: number;
+  resolved: boolean;
+  created: string;
+  filePath: string;
+}
+
+export function parseQuestionFile(raw: string, filePath: string): ParsedQuestionFile | null {
+  if (!raw.startsWith("---\n")) return null;
+  const close = raw.indexOf("\n---\n\n", 4);
+  if (close === -1) return null;
+  const frontmatterStr = raw.slice(4, close);
+  const body = raw.slice(close + 6).trim();
+
+  const id = extractFrontmatterValue(frontmatterStr, "id") ?? path.basename(filePath, ".md");
+  const created = extractFrontmatterValue(frontmatterStr, "created") ?? "";
+  const priority = parseFloat(extractFrontmatterValue(frontmatterStr, "priority") ?? "0.5");
+  const resolved = extractFrontmatterValue(frontmatterStr, "resolved") === "true";
+
+  const contextMarker = "**Context:**";
+  const contextAt = body.indexOf(contextMarker);
+  const question = contextAt === -1 ? body : body.slice(0, contextAt).trim();
+  const context = contextAt === -1 ? "" : body.slice(contextAt + contextMarker.length).trim();
+
+  return { id, question, context, priority, resolved, created, filePath };
+}
+
+function extractFrontmatterValue(frontmatter: string, key: string): string | null {
+  const prefix = `${key}:`;
+  for (const line of frontmatter.split("\n")) {
+    if (!line.startsWith(prefix)) continue;
+    let value = line.slice(prefix.length).trim();
+    if (value.startsWith('"') && value.endsWith('"') && value.length >= 2) {
+      value = value.slice(1, -1);
+    }
+    return value;
+  }
+  return null;
+}

package/src/storage.ts

@@ -30,7 +30,9 @@ import { createTombstoneMigrationSourceContents } from "./storage/tombstone-migr
 import { MemoryReadStore, readWindowedMemories, type WindowedMemoryReadOptions, type WindowedMemoryReadResult } from "./storage/memory-read-store.js";
 import { hasSupersessionAudit } from "./storage/supersession-audit.js";
 import { runCommittedInvalidation } from "./storage/committed-invalidation.js";
-import { renderProfileWithLastUpdated } from "./storage/profile-header.js";
+import { renderProfileWithLastUpdated, stripOkfProfileFrontmatter, withOkfProfileFrontmatter } from "./storage/profile-header.js";
+import { parseQuestionFile as parseQuestionFileText } from "./storage/questions-file.js";
+import { assertNotOkfReservedBasename, OKF_QUESTION_TYPE, okfTypeForEntityKind, okfTypeForMemory } from "./okf/type-mapping.js";
 import { readMaybeEncryptedLines, readMemoryActionEventRowsFromLines } from "./storage/secure-line-reader.js";
 import {
   appendLifecycleEventsSerialized,
@@ -319,6 +321,8 @@ function serializeFrontmatter(fm: MemoryFrontmatter): string {
     `confidenceTier: ${fm.confidenceTier}`,
     `tags: [${fm.tags.map((t) => `"${t}"`).join(", ")}]`,
   ];
+  // OKF v0.1 interop (issue #1946): inert presentation metadata; `category` stays canonical.
+  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.entityRef) lines.push(`entityRef: ${fm.entityRef}`);
   if (fm.sourceConnector) {
@@ -855,6 +859,7 @@ export function parseFrontmatter(raw: string): { frontmatter: MemoryFrontmatter;
     frontmatter: {
       id: fm.id ?? "",
       category: (fm.category ?? "fact") as MemoryCategory,
+      type: parseFrontmatterStringValue(fm.type),
       created: fm.created ?? new Date().toISOString(),
       updated: fm.updated ?? new Date().toISOString(),
       source: fm.source ?? "unknown",
@@ -1099,15 +1104,16 @@ function parseEntityFrontmatter(raw: string): {
 
   const values: Record<string, string> = {};
   const extraLines: string[] = [];
-  const recognizedKeys = new Set([
-    "created",
-    "updated",
-    "synthesis_updated_at",
-    "synthesis_timeline_count",
-    "synthesis_structured_fact_count",
-    "synthesis_structured_fact_digest",
-    "synthesis_version",
-  ]);
+  const recognizedKeys: Record<string, true> = {
+    created: true,
+    updated: true,
+    type: true,
+    synthesis_updated_at: true,
+    synthesis_timeline_count: true,
+    synthesis_structured_fact_count: true,
+    synthesis_structured_fact_digest: true,
+    synthesis_version: true,
+  };
   for (const line of match[1].split(/\r?\n/)) {
     if (/^\s/.test(line)) {
       extraLines.push(line);
@@ -1119,7 +1125,7 @@ function parseEntityFrontmatter(raw: string): {
       continue;
     }
     const key = line.slice(0, colonIdx).trim();
-    if (!recognizedKeys.has(key)) {
+    if (recognizedKeys[key] !== true) {
       extraLines.push(line);
       continue;
     }
@@ -1413,7 +1419,11 @@ export function parseEntityFile(content: string, entitySchemas?: PluginConfig["e
  * Writes the compiled-truth + timeline format while remaining parse-compatible
  * with the legacy in-memory `summary` and `facts` fields.
  */
-export function serializeEntityFile(entity: EntityFile, entitySchemas?: PluginConfig["entitySchemas"]): string {
+export function serializeEntityFile(
+  entity: EntityFile,
+  entitySchemas?: PluginConfig["entitySchemas"],
+  okfType?: boolean,
+): string {
   const synthesis = entity.synthesis || entity.summary || "";
   const created = entity.created?.trim() || entity.updated || new Date().toISOString();
   const updated = entity.updated || created;
@@ -1457,7 +1467,10 @@ export function serializeEntityFile(entity: EntityFile, entitySchemas?: PluginCo
       : [`synthesis_structured_fact_count: ${synthesisStructuredFactCount}`]),
     ...(synthesisStructuredFactDigest ? [`synthesis_structured_fact_digest: "${synthesisStructuredFactDigest}"`] : []),
     `synthesis_version: ${synthesisVersion}`,
-    ...(entity.extraFrontmatterLines ?? []),
+    ...(okfType === false ? [] : [`type: ${okfTypeForEntityKind(entity.type)}`]),
+    ...(okfType === false
+      ? (entity.extraFrontmatterLines ?? [])
+      : (entity.extraFrontmatterLines ?? []).filter((line) => !line.startsWith("type:"))),
     "---",
     "",
     `# ${entity.name}`,
@@ -2261,6 +2274,24 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
     StorageManager.scopedCacheInvalidationByDir.set(memoryDir, enabled !== false);
   }
 
+  /** OKF `type` emission gate registrations per memory dir (issue #1946). */
+  private static readonly okfConformanceByDir = new Map<string, boolean>();
+
+  /** Register the OKF conformance gate for a memory dir. Unregistered dirs default to
+   *  conformance-on; namespace child dirs (<memoryDir>/namespaces/<tok>) inherit the
+   *  nearest registered ancestor. Only an explicit `false` disables. */
+  static setOkfConformanceDefault(memoryDir: string, enabled: boolean | undefined): void {
+    StorageManager.okfConformanceByDir.set(memoryDir, enabled !== false);
+  }
+
+  okfConformanceEnabled(): boolean {
+    for (let dir = this.baseDir; ; dir = path.dirname(dir)) {
+      const registered = StorageManager.okfConformanceByDir.get(dir);
+      if (registered !== undefined) return registered;
+      if (dir === path.dirname(dir)) return true;
+    }
+  }
+
   /**
    * The LIVE class object of this instance (issue #1809 review of the
    * storage decomposition): extracted store modules must read/write the
@@ -2648,6 +2679,7 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
     return this.writeStorageSecureFile(target, content);
   }
   protected writeStorageSecureFile(filePath: string, content: string | Buffer, forceEncrypt = false): Promise<void> {
+    assertNotOkfReservedBasename(filePath);
     const writeKey = this.resolveWriteKey(forceEncrypt);
     return writeMaybeEncryptedFile(filePath, content, writeKey, {}, this.baseDir).then(() => {
       // No manual sniff-cache update needed (issue #1909 round 10): this rewrite
@@ -3577,7 +3609,7 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
     const completionFingerprint = await runLegacyEntityCanonicalIdMigration(
       this as unknown as EntityCanonicalIdMigrationHost,
       (content) => parseEntityFile(content, this.entitySchemas),
-      (entity) => serializeEntityFile(entity, this.entitySchemas),
+      (entity) => serializeEntityFile(entity, this.entitySchemas, this.okfConformanceEnabled()),
       createMemoryEntityRefSerializer(serializeFrontmatter)
     );
     return completionFingerprint;
@@ -3659,6 +3691,13 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
       }) ?? null
     );
   }
+
+  /** Derive the inert OKF `type` at the serialization choke point when conformance is on
+   *  and the parsed frontmatter carried none (issue #1946). Never touches `category`. */
+  private withOkfType(fm: MemoryFrontmatter): MemoryFrontmatter {
+    if (this.okfConformanceEnabled() && fm.type === undefined) fm.type = okfTypeForMemory(fm);
+    return fm;
+  }
   async writeMemory(
     category: MemoryCategory,
     content: string,
@@ -3812,7 +3851,7 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
     };
     await applyTombstoneGate();
 
-    const fileContent = `${serializeFrontmatter(fm)}\n\n${sanitized.text}\n`;
+    const fileContent = `${serializeFrontmatter(this.withOkfType(fm))}\n\n${sanitized.text}\n`;
 
     const filePath = await this.resolveCategoryWritePath(category, id, today);
     const persistFile = async (): Promise<MemoryFile | null> => {
@@ -3837,7 +3876,7 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
               await applyTombstoneGate();
               await this.writeTombstoneBlockedMemory(
                 filePath,
-                `${serializeFrontmatter(fm)}\n\n${sanitized.text}\n`,
+                `${serializeFrontmatter(this.withOkfType(fm))}\n\n${sanitized.text}\n`,
                 fm,
                 sanitized.text,
                 async () => this.invalidateAllMemoriesCache()
@@ -4172,7 +4211,7 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
       return "";
     }
     const filePath = path.join(dir, `${id}.md`);
-    await this.writeStorageSecureFile(filePath, `${serializeFrontmatter(fm)}\n\n${sanitized.text}\n`);
+    await this.writeStorageSecureFile(filePath, `${serializeFrontmatter(this.withOkfType(fm))}\n\n${sanitized.text}\n`);
     const actor =
       typeof options.actor === "string" && options.actor.length > 0 ? options.actor : "storage.writeArtifact";
     await this.appendGeneratedMemoryLifecycleEventFailOpen("storage.writeArtifact", {
@@ -4225,7 +4264,7 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
 
   async readProfile(): Promise<string> {
     try {
-      return await readMaybeEncryptedFile(this.profilePath, this._secureStoreKey, this.baseDir);
+      return stripOkfProfileFrontmatter(await readMaybeEncryptedFile(this.profilePath, this._secureStoreKey, this.baseDir));
     } catch (error) {
       if (error instanceof SecureStoreLockedError) {
         throw error;
@@ -4236,7 +4275,12 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
   }
 
   async writeProfile(content: string): Promise<void> {
-    const stampedContent = renderProfileWithLastUpdated(content, new Date().toISOString());
+    const timestamp = new Date().toISOString();
+    const stampedContent = withOkfProfileFrontmatter(
+      renderProfileWithLastUpdated(content, timestamp),
+      timestamp,
+      this.okfConformanceEnabled(),
+    );
     await this.ensureDirectories();
     await this.snapshotBeforeWrite(this.profilePath, "consolidation");
     await this.writeStorageSecureFile(this.profilePath, stampedContent);
@@ -4912,6 +4956,7 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
     return path.join(root, dir, this.resolveMemoryDateDir(memory), `${memory.frontmatter.id}.md`);
   }
   private async writeMemoryFileAtomic(targetPath: string, memory: MemoryFile): Promise<void> {
+    assertNotOkfReservedBasename(targetPath);
     // Whole-record rewrite (tier moves) — #2213. Repair, not just detect:
     // the source is unlinked after the move, so a mapping parked across this
     // write would strand the moved copy with nothing left to reconcile from.
@@ -4921,7 +4966,7 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
     const persist = (): Promise<void> =>
       writeMaybeEncryptedFile(
         targetPath,
-        `${serializeFrontmatter(frontmatter)}\n\n${memory.content}\n`,
+        `${serializeFrontmatter(this.withOkfType(frontmatter))}\n\n${memory.content}\n`,
         this.resolveWriteKey(),
         {},
         this.baseDir
@@ -5070,7 +5115,7 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
           },
           refIdsAtWrite
         );
-        const fileContent = `${serializeFrontmatter(updatedFm)}\n\n${current.content}\n`;
+        const fileContent = `${serializeFrontmatter(this.withOkfType(updatedFm))}\n\n${current.content}\n`;
         const destPath = path.join(destDir, path.basename(current.path));
         // Snapshot a pre-existing destination (retried archive) so a repair
         // failure restores it instead of deleting the only archived copy (§14).
@@ -5260,7 +5305,7 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
     if (!sanitized.clean) {
       log.warn(`updated memory content sanitized for ${memory.frontmatter.id}; violations=${sanitized.violations.join(", ")}`);
     }
-    const fileContent = `${serializeFrontmatter(updated)}\n\n${sanitized.text}\n`;
+    const fileContent = `${serializeFrontmatter(this.withOkfType(updated))}\n\n${sanitized.text}\n`;
     await this.writeTombstoneBlockedUpdate(memory, fileContent, updated, sanitized.text, async () => {
       this.invalidateAllMemoriesCache();
       if (this.isColdOrArchiveTierPath(memory.path)) this.invalidateColdMemoriesCache();
@@ -5350,7 +5395,7 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
     const refIds = typeof updated.entityRef === "string" ? resolveIds : null;
     const afterStatus = updated.status ?? "active";
 
-    const fileContent = `${serializeFrontmatter(updated)}\n\n${memory.content}\n`;
+    const fileContent = `${serializeFrontmatter(this.withOkfType(updated))}\n\n${memory.content}\n`;
     await this.writeTombstoneBlockedFrontmatter(memory, fileContent, updated, async () => {
       this.invalidateAllMemoriesCache();
       // Rebuild the blocked index from the post-write cold-tier cache.
@@ -6038,11 +6083,12 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
     await mkdir(this.questionsDir, { recursive: true });
 
     const id = this.generateId("q");
-    const frontmatter = {
+    const frontmatter: Record<string, unknown> = {
       id,
       created: new Date().toISOString(),
       priority,
       resolved: false,
+      ...(this.okfConformanceEnabled() ? { type: OKF_QUESTION_TYPE } : {}),
     };
 
     const content = `---\n${Object.entries(frontmatter)
@@ -6076,41 +6122,8 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
     StorageManager.questionsCache.delete(this.questionsDir);
   }
 
-  private parseQuestionFile(
-    raw: string,
-    filePath: string
-  ): {
-    id: string;
-    question: string;
-    context: string;
-    priority: number;
-    resolved: boolean;
-    created: string;
-    filePath: string;
-  } | null {
-    const match = raw.match(/^---\n([\s\S]*?)\n---\n\n([\s\S]*)$/);
-    if (!match) return null;
-
-    const frontmatterStr = match[1];
-    const body = match[2].trim();
-
-    // Parse frontmatter
-    const id = this.extractFrontmatterValue(frontmatterStr, "id") ?? path.basename(filePath, ".md");
-    const created = this.extractFrontmatterValue(frontmatterStr, "created") ?? "";
-    const priority = parseFloat(this.extractFrontmatterValue(frontmatterStr, "priority") ?? "0.5");
-    const resolved = this.extractFrontmatterValue(frontmatterStr, "resolved") === "true";
-
-    // Extract question and context from body
-    const contextMatch = body.match(/\*\*Context:\*\*\s*(.*)/);
-    const question = contextMatch ? body.slice(0, contextMatch.index).trim() : body;
-    const context = contextMatch ? contextMatch[1].trim() : "";
-
-    return { id, question, context, priority, resolved, created, filePath };
-  }
-
-  private extractFrontmatterValue(frontmatter: string, key: string): string | null {
-    const match = frontmatter.match(new RegExp(`^${key}:\\s*"?([^"\\n]*)"?`, "m"));
-    return match ? match[1] : null;
+  private parseQuestionFile(raw: string, filePath: string) {
+    return parseQuestionFileText(raw, filePath);
   }
 
   async resolveQuestion(id: string): Promise<boolean> {
@@ -6534,7 +6547,7 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
             { ...current.frontmatter, accessCount: entry.newCount, lastAccessed: entry.lastAccessed },
             rowIds
           );
-          const fileContent = `${serializeFrontmatter(newFm)}\n\n${current.content}\n`;
+          const fileContent = `${serializeFrontmatter(this.withOkfType(newFm))}\n\n${current.content}\n`;
           await this.writeTombstoneBlockedFrontmatter(current, fileContent, newFm);
           if (typeof current.frontmatter.entityRef === "string") {
             await this.entityRefRepair.repair(
@@ -6855,7 +6868,7 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
     };
 
     const filePath = await this.resolveCategoryWritePath(category, id, today);
-    const fileContent = `${serializeFrontmatter(fm)}\n\n${sanitized.text}\n`;
+    const fileContent = `${serializeFrontmatter(this.withOkfType(fm))}\n\n${sanitized.text}\n`;
 
     const written = await this.writeTombstoneBlockedChunk(
       filePath,
@@ -6999,7 +7012,7 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
           },
           refIdsAtWrite
         );
-        const fileContent = `${serializeFrontmatter(updatedFm)}\n\n${current.content}\n`;
+        const fileContent = `${serializeFrontmatter(this.withOkfType(updatedFm))}\n\n${current.content}\n`;
         await this.writeTombstoneBlockedFrontmatter(current, fileContent, updatedFm);
         if (this.isColdOrArchiveTierPath(current.path)) this.invalidateColdMemoriesCache();
         if (typeof current.frontmatter.entityRef === "string") {
@@ -7147,7 +7160,7 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
             { ...current.frontmatter, status: "archived", archivedAt: now, updated: now },
             rowIds
           );
-          const fileContent = `${serializeFrontmatter(updatedFm)}\n\n${current.content}\n`;
+          const fileContent = `${serializeFrontmatter(this.withOkfType(updatedFm))}\n\n${current.content}\n`;
           await this.writeTombstoneBlockedFrontmatter(current, fileContent, updatedFm);
           if (typeof current.frontmatter.entityRef === "string") {
             await this.entityRefRepair.repair(

package/src/types.ts

@@ -1,6 +1,7 @@
 import type { BoundedJsonlStateConfig } from "./bounded-jsonl-state.js";
 import type { MeetingsConfig } from "./meetings/types.js";
 import type { LocationConfig } from "./location/types.js";
+import type { OkfConfig } from "./okf/config.js";
 import type { ActivityConfig } from "./activity/types.js";
 import type { WearablesConfig } from "./wearables/types.js";
 import type { ExtractionLivenessConfig } from "./extraction-liveness.js";
@@ -1227,17 +1228,13 @@ export interface PluginConfig extends BoundedJsonlStateConfig, SecurityConfig {
   converge: ConvergeConfig;
   /** Claim-level provenance spans (#1575); see `ProvenanceConfig` for defaults. */
   provenance: ProvenanceConfig;
-  /**
-   * Wearable transcript ingestion (Limitless / Bee / Omi connectors).
-   * Disabled by default; see docs/wearables.md.
-   */
   wearables: WearablesConfig;
   activity: ActivityConfig;
   meetings: MeetingsConfig;
   location: LocationConfig;
+  okf: OkfConfig;
   /**
    * At-rest encryption configuration (issue #690 PR 3/4).
-   *
    * When `secureStoreEnabled` is true, `StorageManager` reads and
    * writes memory files through the `secure-fs` encryption layer.
    * The store must be unlocked via `remnic secure-store unlock` before
@@ -2808,6 +2805,8 @@ export interface MemoryFrontmatter extends SourceConnectorProvenance, OriginMeta
   toolScoped?: true;
   id: string;
   category: MemoryCategory;
+  /** OKF v0.1 interop metadata (issue #1946). Inert: presentation only, never overrides `category`. */
+  type?: string;
   created: string;
   updated: string;
   source: string;

package/src/who-knows-cli.ts

@@ -0,0 +1,96 @@
+/**
+ * Input-validation + rendering helpers for the `remnic who-knows` CLI
+ * command (issue #2057). Extracted so validation paths can be unit-tested
+ * without booting an orchestrator (same pattern as `recall-xray-cli.ts`).
+ *
+ * Rules 14 + 51: bare `--limit`, non-integer or out-of-range values, and an
+ * empty topic throw listed-options errors — never silent defaults.
+ */
+
+import {
+  validateWhoKnowsInput,
+  WHO_KNOWS_DEFAULT_LIMIT,
+  WHO_KNOWS_MAX_LIMIT,
+  type WhoKnowsResult,
+} from "./who-knows.js";
+
+export interface ParsedWhoKnowsCliOptions {
+  topic: string;
+  limit: number;
+  namespace?: string;
+  json: boolean;
+}
+
+/** Split raw argv into the positional topic and a flag bag. Value flags error when bare. */
+export function extractWhoKnowsRawArgs(rest: string[]): {
+  topic: string;
+  options: Record<string, unknown>;
+} {
+  const VALUE_FLAGS: Record<string, true> = { "--limit": true, "--namespace": true };
+  const positional: string[] = [];
+  const options: Record<string, unknown> = {};
+  for (let i = 0; i < rest.length; i++) {
+    const token = rest[i];
+    if (token.startsWith("--")) {
+      if (token === "--json") {
+        options.json = true;
+      } else if (VALUE_FLAGS[token]) {
+        const value = rest[i + 1];
+        if (value === undefined || value.startsWith("--")) {
+          throw new Error(`who-knows: ${token} expects a value`);
+        }
+        options[token.slice(2)] = value;
+        i += 1;
+      } else {
+        throw new Error(`who-knows: unknown option ${token} (expected --limit, --namespace, or --json)`);
+      }
+    } else {
+      positional.push(token);
+    }
+  }
+  return { topic: positional.join(" ").trim(), options };
+}
+
+/** Validate the full option bag. Throws listed-options errors for bad input. */
+export function parseWhoKnowsCliOptions(rawTopic: unknown, options: Record<string, unknown>): ParsedWhoKnowsCliOptions {
+  if (typeof rawTopic !== "string" || rawTopic.trim().length === 0) {
+    throw new Error("who-knows: topic is required and must be non-empty");
+  }
+  let limit = WHO_KNOWS_DEFAULT_LIMIT;
+  if (options.limit !== undefined) {
+    const parsed = typeof options.limit === "number" ? options.limit : Number(options.limit);
+    if (!Number.isInteger(parsed) || parsed < 1 || parsed > WHO_KNOWS_MAX_LIMIT) {
+      throw new Error(`who-knows: --limit expects an integer between 1 and ${WHO_KNOWS_MAX_LIMIT}`);
+    }
+    limit = parsed;
+  }
+  const namespace = typeof options.namespace === "string" && options.namespace.trim().length > 0
+    ? options.namespace.trim()
+    : undefined;
+  validateWhoKnowsInput(rawTopic, limit);
+  return { topic: rawTopic.trim(), limit, namespace, json: options.json === true };
+}
+
+export function renderWhoKnowsJson(result: WhoKnowsResult): string {
+  return JSON.stringify(result, null, 2);
+}
+
+export function renderWhoKnowsText(result: WhoKnowsResult): string {
+  if (result.results.length === 0) {
+    return `who knows "${result.topic}": no evidence found`;
+  }
+  const lines = [`who knows "${result.topic}" (top ${result.results.length})`];
+  result.results.forEach((hit, index) => {
+    const name = hit.entityName || hit.entityId;
+    lines.push(`${index + 1}. ${name} [${hit.entityId}] — score ${hit.score.toFixed(4)} — ${hit.rationale}`);
+    for (const ref of hit.evidence) {
+      lines.push(`   - ${ref.id} (${ref.path}) updated ${ref.updated}`);
+    }
+  });
+  return lines.join("\n");
+}
+
+export function renderWhoKnows(result: WhoKnowsResult, json: boolean): string {
+  return json ? renderWhoKnowsJson(result) : renderWhoKnowsText(result);
+}
+