@caupulican/pi-adaptative 0.94.0 → 0.94.1

package/dist/core/memory/okf-project-memory-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"okf-project-memory-store.js","sourceRoot":"","sources":["../../../src/core/memory/okf-project-memory-store.ts"],"names":[],"mappings":"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","sourcesContent":["import { createHash } from \"node:crypto\";\nimport { promises as fs } from \"node:fs\";\nimport { join } from \"node:path\";\nimport { okfMemoryDir, okfProjectMemoryDir } from \"../agent-paths.ts\";\nimport { isPathWithinScope, safeRealpathSync } from \"../autonomy/path-scope.ts\";\nimport {\n\tformatOkfMemoryDocument,\n\ttype OkfMemoryDocumentInput,\n\ttype PiOkfType,\n\tvalidateOkfMemoryDocumentInput,\n} from \"../context/okf-memory.ts\";\nimport { loadOkfMemoryBundle } from \"../context/okf-memory-provider.ts\";\nimport { getDirectoryResourceProfileInfo } from \"../settings-manager.ts\";\nimport { isMissingFileError, withFileLock, writeFileAtomic } from \"../util/atomic-file.ts\";\nimport { readBoundedTextFile } from \"../util/bounded-file.ts\";\n\nconst MAX_OKF_DOCUMENT_BYTES = 16_384;\n\nfunction digest(content: string): string {\n\treturn createHash(\"sha256\").update(content, \"utf8\").digest(\"hex\");\n}\n\nexport interface OkfProjectMemoryPutResult {\n\tcreated: boolean;\n\tdigest: string;\n\tpath: string;\n}\n\nexport interface OkfProjectMemoryRemoveResult {\n\tremoved: boolean;\n}\n\n/**\n * Durable storage owner for model-authored project OKF records. It owns project identity, bounds,\n * conflict policy, symlink containment, per-record locking, and atomic replacement. Existing\n * different content is never overwritten by an `add`; reflection must confront it explicitly.\n */\nexport class OkfProjectMemoryStore {\n\treadonly projectId: string;\n\treadonly projectRoot: string;\n\tprivate readonly agentDir: string;\n\tprivate readonly rootDir: string;\n\tprivate readonly projectDir: string;\n\n\tconstructor(agentDir: string, cwd: string) {\n\t\tconst identity = getDirectoryResourceProfileInfo(cwd, agentDir);\n\t\tthis.agentDir = agentDir;\n\t\tthis.rootDir = okfMemoryDir(agentDir);\n\t\tthis.projectId = identity.hash;\n\t\tthis.projectRoot = identity.root;\n\t\tthis.projectDir = okfProjectMemoryDir(agentDir, identity.hash);\n\t}\n\n\tprivate recordPath(type: PiOkfType, title: string): string {\n\t\tconst path = join(this.projectDir, `${digest(`${type}\\0${title}`)}.okf.md`);\n\t\tif (!isPathWithinScope(path, this.projectDir)) throw new Error(\"OKF record escaped its project root.\");\n\t\treturn path;\n\t}\n\n\tprivate assertContained(path: string): void {\n\t\tconst canonicalAgentDir = safeRealpathSync(this.agentDir);\n\t\tconst canonicalRootDir = safeRealpathSync(this.rootDir);\n\t\tconst canonicalProjectDir = safeRealpathSync(this.projectDir);\n\t\tconst canonicalPath = safeRealpathSync(path);\n\t\tif (!isPathWithinScope(canonicalRootDir, canonicalAgentDir)) {\n\t\t\tthrow new Error(\"OKF memory root escapes the agent directory.\");\n\t\t}\n\t\tif (!isPathWithinScope(canonicalProjectDir, canonicalRootDir)) {\n\t\t\tthrow new Error(\"OKF project root escapes the OKF memory root.\");\n\t\t}\n\t\tif (!isPathWithinScope(canonicalPath, canonicalProjectDir)) {\n\t\t\tthrow new Error(\"OKF record escapes its project root.\");\n\t\t}\n\t}\n\n\tasync put(input: Omit<OkfMemoryDocumentInput, \"projectId\">): Promise<OkfProjectMemoryPutResult> {\n\t\tconst errors = validateOkfMemoryDocumentInput(input, { projectOnly: true, requireEvidence: true });\n\t\tif (errors.length > 0) throw new Error(`Invalid OKF record: ${errors.join(\"; \")}`);\n\t\tconst document = formatOkfMemoryDocument({ ...input, projectId: this.projectId });\n\t\tconst documentDigest = digest(document);\n\t\tconst path = this.recordPath(input.type, input.title);\n\t\tthis.assertContained(path);\n\t\treturn withFileLock(path, async () => {\n\t\t\tthis.assertContained(path);\n\t\t\ttry {\n\t\t\t\tconst existing = await readBoundedTextFile(path, MAX_OKF_DOCUMENT_BYTES, \"OKF project record\");\n\t\t\t\tif (existing === document) return { created: false, digest: documentDigest, path };\n\t\t\t\tthrow new Error(\"A different structured record already exists for this type and title.\");\n\t\t\t} catch (error) {\n\t\t\t\tif (!isMissingFileError(error)) throw error;\n\t\t\t}\n\t\t\tawait writeFileAtomic(path, document, { mode: 0o600 });\n\t\t\treturn { created: true, digest: documentDigest, path };\n\t\t});\n\t}\n\n\tasync remove(type: PiOkfType, title: string, expectedDigest?: string): Promise<OkfProjectMemoryRemoveResult> {\n\t\tconst path = this.recordPath(type, title);\n\t\tthis.assertContained(path);\n\t\treturn withFileLock(path, async () => {\n\t\t\tthis.assertContained(path);\n\t\t\tlet existing: string;\n\t\t\ttry {\n\t\t\t\texisting = await readBoundedTextFile(path, MAX_OKF_DOCUMENT_BYTES, \"OKF project record\");\n\t\t\t} catch (error) {\n\t\t\t\tif (isMissingFileError(error)) return { removed: false };\n\t\t\t\tthrow error;\n\t\t\t}\n\t\t\tif (expectedDigest !== undefined && digest(existing) !== expectedDigest) {\n\t\t\t\tthrow new Error(\"OKF record changed after the audited write; refusing removal.\");\n\t\t\t}\n\t\t\tawait fs.unlink(path);\n\t\t\treturn { removed: true };\n\t\t});\n\t}\n\n\tlist(maxDocuments = 64): string {\n\t\treturn loadOkfMemoryBundle({\n\t\t\trootDir: this.rootDir,\n\t\t\tprojectId: this.projectId,\n\t\t\tprojectRoot: this.projectRoot,\n\t\t\tmaxDocuments,\n\t\t})\n\t\t\t.entries.map(({ relativePath, parsed }) => {\n\t\t\t\tconst item = parsed.item;\n\t\t\t\treturn item === undefined ? \"\" : `${relativePath}: ${item.title ?? \"Untitled\"} — ${item.summary}`;\n\t\t\t})\n\t\t\t.filter((entry) => entry.length > 0)\n\t\t\t.join(\"\\n\")\n\t\t\t.slice(0, 8_000);\n\t}\n}\n"]}

package/dist/core/memory/providers/file-store.d.ts

@@ -1,4 +1,5 @@
 import type { MemoryPromptBudget } from "../../context/memory-prompt-budget.ts";
+import { type PiOkfType } from "../../context/okf-memory.ts";
 import type { ToolDefinition } from "../../extensions/types.ts";
 import type { MemoryLifecycleContext, MemoryProvider } from "../memory-provider.ts";
 /**
@@ -9,8 +10,42 @@ import type { MemoryLifecycleContext, MemoryProvider } from "../memory-provider.
 export declare function supersedeNearDuplicateLine(existing: string, content: string): string | null;
 export interface FileStoreProviderOptions {
     onDurableMemoryChanged?: () => void;
+    /** Test seam between loss-safe OKF creation and exact hot-memory removal. */
+    beforeOrganizeHotRemoval?: () => void | Promise<void>;
 }
-export declare const FILE_STORE_MEMORY_SYSTEM_NOTE = "[System Note: Below is a snapshot of persistent memory. Proactively record verified reusable project facts and user preferences with the 'memory' tool; never store transient noise.]";
+export type StructuredReflectionWrite = {
+    kind: "okf_add";
+    type: PiOkfType;
+    title: string;
+    description: string;
+    text: string;
+    tags?: string[];
+    evidenceRefs: string[];
+} | {
+    kind: "okf_organize";
+    type: PiOkfType;
+    title: string;
+    description: string;
+    text: string;
+    sourceText: string;
+    tags?: string[];
+    evidenceRefs: string[];
+};
+export interface StructuredReflectionApplyResult {
+    applied: boolean;
+    created: boolean;
+    digest?: string;
+    sourceRemoved?: boolean;
+    error?: string;
+}
+export interface StructuredReflectionRollback {
+    type: PiOkfType;
+    title: string;
+    expectedDigest?: string;
+    sourceText?: string;
+    removeRecord: boolean;
+}
+export declare const FILE_STORE_MEMORY_SYSTEM_NOTE = "[System Note: Below is a snapshot of persistent memory. Proactively record verified reusable project facts and user preferences with the 'memory' tool. Keep MEMORY.md for compact hot facts, USER.md for preferences, and use target 'okf' for durable project decisions, architecture, rules, findings, and references. Never store transient noise.]";
 export declare class FileStoreProvider implements MemoryProvider {
     readonly name = "file-store";
     readonly egress = "local";
@@ -22,6 +57,7 @@ export declare class FileStoreProvider implements MemoryProvider {
     private lastWrittenMemory;
     private lastWrittenUser;
     private userArchive?;
+    private okfStore?;
     private readonly options;
     private static readonly BUDGET_MEMORY;
     private static readonly BUDGET_USER;
@@ -35,6 +71,11 @@ export declare class FileStoreProvider implements MemoryProvider {
     systemPromptBlock(budget?: MemoryPromptBudget): string;
     prefetch(_query: string): Promise<string>;
     shutdown(): Promise<void>;
+    private executeMemoryCommand;
+    /** Reflection-owned structured write. Organization is OKF-first, then exact hot-memory removal. */
+    applyStructuredReflectionWrite(write: StructuredReflectionWrite, signal?: AbortSignal): Promise<StructuredReflectionApplyResult>;
+    /** Restore hot memory first, then conditionally remove the exact audited OKF bytes. */
+    rollbackStructuredReflectionWrite(rollback: StructuredReflectionRollback, signal?: AbortSignal): Promise<boolean>;
     getContextMarkers(): string[];
     getToolDefinitions(): ToolDefinition[];
 }

package/dist/core/memory/providers/file-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"file-store.d.ts","sourceRoot":"","sources":["../../../../src/core/memory/providers/file-store.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uCAAuC,CAAC;AAChF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAQhE,OAAO,KAAK,EAAE,sBAAsB,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAGpF;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAsB3F;AAiBD,MAAM,WAAW,wBAAwB;IACxC,sBAAsB,CAAC,EAAE,MAAM,IAAI,CAAC;CACpC;AAED,eAAO,MAAM,6BAA6B,0LAC8I,CAAC;AA4GzL,qBAAa,iBAAkB,YAAW,cAAc;IACvD,SAAgB,IAAI,gBAAgB;IACpC,SAAgB,MAAM,WAAW;IAEjC,OAAO,CAAC,GAAG,CAAC,CAAyB;IACrC,OAAO,CAAC,cAAc,CAAM;IAC5B,OAAO,CAAC,YAAY,CAAM;IAC1B,OAAO,CAAC,eAAe,CAAM;IAC7B,OAAO,CAAC,aAAa,CAAM;IAE3B,OAAO,CAAC,iBAAiB,CAAM;IAC/B,OAAO,CAAC,eAAe,CAAM;IAC7B,OAAO,CAAC,WAAW,CAAC,CAAoB;IACxC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA2B;IAGnD,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,aAAa,CAAQ;IAC7C,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,WAAW,CAAQ;IAE3C,YAAY,OAAO,GAAE,wBAA6B,EAEjD;IAEM,WAAW,IAAI,OAAO,CAE5B;IAEM,eAAe;QACZ,QAAQ;MACjB;IAEY,UAAU,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,sBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,CAatF;YAEa,qBAAqB;IA8B5B,iBAAiB,CAAC,MAAM,CAAC,EAAE,kBAAkB,GAAG,MAAM,CAyC5D;IAEY,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAGrD;IAEY,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAErC;IAEM,iBAAiB,IAAI,MAAM,EAAE,CAEnC;IAEM,kBAAkB,IAAI,cAAc,EAAE,CAwN5C;CACD"}
+{"version":3,"file":"file-store.d.ts","sourceRoot":"","sources":["../../../../src/core/memory/providers/file-store.ts"],"names":[],"mappings":"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"}

package/dist/core/memory/providers/file-store.js

@@ -2,9 +2,11 @@ import { createHash, randomUUID } from "node:crypto";
 import { promises as fs } from "node:fs";
 import { Type } from "typebox";
 import { configFile, managedMemoryStateFile } from "../../agent-paths.js";
+import { OKF_MEMORY_LIMITS, PI_OKF_TYPES, validateOkfMemoryDocumentInput, } from "../../context/okf-memory.js";
 import { hasInvisibleUnicode, scanContextFileThreats, stripInvisibleUnicode, } from "../../security/context-threat-scanner.js";
 import { jaccard, tokenize } from "../../tools/skill-audit.js";
-import { withFileLock, writeFileAtomic } from "../../util/atomic-file.js";
+import { isMissingFileError, withFileLock, writeFileAtomic } from "../../util/atomic-file.js";
+import { OkfProjectMemoryStore } from "../okf-project-memory-store.js";
 import { UserMemoryArchive } from "./user-memory-archive.js";
 /**
  * Confront-before-write (anti append-rot): if `content` is a near-duplicate of an existing
@@ -39,22 +41,48 @@ export function supersedeNearDuplicateLine(existing, content) {
     return lines.join("\n");
 }
 const memorySchema = Type.Object({
-    action: Type.Union([Type.Literal("add"), Type.Literal("replace"), Type.Literal("remove")], {
+    action: Type.Union([Type.Literal("add"), Type.Literal("replace"), Type.Literal("remove"), Type.Literal("list")], {
         description: "Action to perform: add new content, replace existing content, or remove content",
     }),
-    target: Type.Union([Type.Literal("memory"), Type.Literal("user")], {
-        description: "Target file: 'memory' for MEMORY.md, 'user' for USER.md",
+    target: Type.Union([Type.Literal("memory"), Type.Literal("user"), Type.Literal("okf")], {
+        description: "Target: 'memory' for MEMORY.md, 'user' for USER.md, or 'okf' for structured project memory",
     }),
-    content: Type.Optional(Type.String({ description: "Content to write (required for 'add' or 'replace')" })),
+    content: Type.Optional(Type.String({
+        maxLength: OKF_MEMORY_LIMITS.bodyChars,
+        description: "Content to write (required for add/replace)",
+    })),
+    title: Type.Optional(Type.String({
+        minLength: 1,
+        maxLength: OKF_MEMORY_LIMITS.titleChars,
+        description: "Structured OKF title (required when target is 'okf')",
+    })),
     oldContent: Type.Optional(Type.String({ description: "Exact substring to replace or remove (required for 'replace' or 'remove')" })),
+    type: Type.Optional(Type.Union(PI_OKF_TYPES.map((value) => Type.Literal(value)), {
+        description: "Structured OKF type (required when target is 'okf')",
+    })),
+    description: Type.Optional(Type.String({
+        minLength: 1,
+        maxLength: OKF_MEMORY_LIMITS.descriptionChars,
+        description: "Structured OKF summary (required when target is 'okf')",
+    })),
+    scope: Type.Optional(Type.Literal("project", { description: "Structured OKF records are project-scoped" })),
+    tags: Type.Optional(Type.Array(Type.String({ minLength: 1, maxLength: OKF_MEMORY_LIMITS.tagChars }), {
+        maxItems: OKF_MEMORY_LIMITS.tagCount,
+        uniqueItems: true,
+        description: "Structured OKF tags",
+    })),
+    evidenceRefs: Type.Optional(Type.Array(Type.String({ minLength: 1, maxLength: OKF_MEMORY_LIMITS.evidenceRefChars }), {
+        minItems: 1,
+        maxItems: OKF_MEMORY_LIMITS.evidenceRefCount,
+        uniqueItems: true,
+        description: "Evidence references for structured OKF",
+    })),
+    expectedDigest: Type.Optional(Type.String({ pattern: "^[a-f0-9]{64}$", description: "Optional conflict guard for structured removal" })),
 });
-export const FILE_STORE_MEMORY_SYSTEM_NOTE = "[System Note: Below is a snapshot of persistent memory. Proactively record verified reusable project facts and user preferences with the 'memory' tool; never store transient noise.]";
+export const FILE_STORE_MEMORY_SYSTEM_NOTE = "[System Note: Below is a snapshot of persistent memory. Proactively record verified reusable project facts and user preferences with the 'memory' tool. Keep MEMORY.md for compact hot facts, USER.md for preferences, and use target 'okf' for durable project decisions, architecture, rules, findings, and references. Never store transient noise.]";
 function contentDigest(content) {
     return createHash("sha256").update(content, "utf8").digest("hex");
 }
-function isMissingFileError(error) {
-    return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
-}
 function parseManagedMemoryState(raw) {
     let parsed;
     try {
@@ -177,6 +205,7 @@ export class FileStoreProvider {
         this.userStatePath = managedMemoryStateFile(ctx.agentDir, "USER.md");
         this.userArchive = new UserMemoryArchive(ctx.agentDir);
         await fs.mkdir(ctx.agentDir, { recursive: true });
+        this.okfStore = new OkfProjectMemoryStore(ctx.agentDir, ctx.cwd);
         [this.lastWrittenMemory, this.lastWrittenUser] = await Promise.all([
             this.initializeManagedFile(this.memoryFilePath, this.memoryStatePath),
             this.initializeManagedFile(this.userFilePath, this.userStatePath),
@@ -256,6 +285,70 @@ export class FileStoreProvider {
     async shutdown() {
         // no-op
     }
+    async executeMemoryCommand(params, signal) {
+        const tool = this.getToolDefinitions()[0];
+        if (tool === undefined)
+            return { details: { success: false, error: "Memory tool unavailable" } };
+        const result = await tool.execute("reflection-memory", params, signal, undefined, undefined);
+        return result;
+    }
+    /** Reflection-owned structured write. Organization is OKF-first, then exact hot-memory removal. */
+    async applyStructuredReflectionWrite(write, signal) {
+        const added = await this.executeMemoryCommand({
+            action: "add",
+            target: "okf",
+            type: write.type,
+            title: write.title,
+            description: write.description,
+            scope: "project",
+            content: write.text,
+            tags: write.tags,
+            evidenceRefs: write.evidenceRefs,
+        }, signal);
+        if (added.details?.success !== true) {
+            return { applied: false, created: false, error: added.details?.error ?? "OKF write failed" };
+        }
+        const created = added.details.created === true;
+        const storedDigest = added.details.digest;
+        if (write.kind === "okf_add") {
+            return {
+                applied: created,
+                created,
+                ...(storedDigest ? { digest: storedDigest } : {}),
+                ...(!created ? { error: "Exact OKF record already exists" } : {}),
+            };
+        }
+        await this.options.beforeOrganizeHotRemoval?.();
+        const removed = await this.executeMemoryCommand({ action: "remove", target: "memory", oldContent: write.sourceText }, signal);
+        const sourceRemoved = removed.details?.success === true;
+        return {
+            // A newly-created OKF record is a real durable change even if exact hot cleanup was
+            // interrupted. This records a reversible partial apply instead of hiding landed data.
+            applied: created || sourceRemoved,
+            created,
+            ...(storedDigest ? { digest: storedDigest } : {}),
+            sourceRemoved,
+            ...(!sourceRemoved ? { error: removed.details?.error ?? "Hot-memory removal failed" } : {}),
+        };
+    }
+    /** Restore hot memory first, then conditionally remove the exact audited OKF bytes. */
+    async rollbackStructuredReflectionWrite(rollback, signal) {
+        if (rollback.sourceText !== undefined) {
+            const restored = await this.executeMemoryCommand({ action: "add", target: "memory", content: rollback.sourceText }, signal);
+            if (restored.details?.success !== true)
+                return false;
+        }
+        if (!rollback.removeRecord)
+            return true;
+        const removed = await this.executeMemoryCommand({
+            action: "remove",
+            target: "okf",
+            type: rollback.type,
+            title: rollback.title,
+            expectedDigest: rollback.expectedDigest,
+        }, signal);
+        return removed.details?.success === true;
+    }
     getContextMarkers() {
         return [];
     }
@@ -264,10 +357,11 @@ export class FileStoreProvider {
             {
                 name: "memory",
                 label: "Persistent Memory Manager",
-                description: "Add, replace, or remove durable project facts and user preferences. Proactively store newly verified reusable facts; USER.md overflow is migrated into indexed OKF shards.",
-                promptSnippet: "Persist verified project facts and user preferences.",
+                description: "Add, replace, or remove durable facts and preferences. Use target 'okf' with structured metadata for durable project decisions, architecture, rules, debugging findings, and references; USER.md overflow is migrated into indexed OKF shards.",
+                promptSnippet: "Persist verified facts; route durable project knowledge to structured OKF records.",
                 promptGuidelines: [
-                    "Store verified facts and preferences. Repeatable multi-step procedures become skills via skillify; reflection promotes them when the write is a workflow.",
+                    "OKF=project decisions/rules/findings with type,title,summary,body,evidenceRefs; MEMORY=hot facts; USER=preferences.",
+                    "Workers gather evidence read-only; only the parent or its reflection writes memory. Repeatable procedures become skills via skillify.",
                 ],
                 parameters: memorySchema,
                 execute: async (_toolCallId, params, _signal, _onUpdate, _execCtx) => {
@@ -282,7 +376,7 @@ export class FileStoreProvider {
                             details: { success: false, error: "Child session write-gated" },
                         };
                     }
-                    const { action, target, content, oldContent } = params;
+                    const { action, target, content, oldContent, title, type, description, scope, tags, evidenceRefs, expectedDigest, } = params;
                     // Strict-scope injection guard on the high-privilege WRITE path (agy #31): a poisoned
                     // memory entry persists across sessions and is injected into every future system prompt,
                     // so block outright rather than strip. Hidden/bidi-control chars have no legitimate place
@@ -312,6 +406,173 @@ export class FileStoreProvider {
                             };
                         }
                     }
+                    if (target === "okf") {
+                        if (action === "list") {
+                            if (this.okfStore === undefined) {
+                                return {
+                                    content: [{ type: "text", text: "Error: Memory provider is not initialized." }],
+                                    details: { success: false },
+                                };
+                            }
+                            const catalog = this.okfStore.list();
+                            return {
+                                content: [{ type: "text", text: catalog || "No structured OKF memory records found." }],
+                                details: { success: true },
+                            };
+                        }
+                        if (action !== "add" && action !== "remove") {
+                            return {
+                                content: [
+                                    {
+                                        type: "text",
+                                        text: "Error: structured OKF memory only supports action 'add' or 'remove'.",
+                                    },
+                                ],
+                                details: { success: false, error: "Unsupported OKF action" },
+                            };
+                        }
+                        if (action === "remove") {
+                            if (this.okfStore === undefined ||
+                                type === undefined ||
+                                title === undefined ||
+                                !PI_OKF_TYPES.includes(type)) {
+                                return {
+                                    content: [{ type: "text", text: "Error: OKF removal requires a valid type and title." }],
+                                    details: { success: false, error: "Incomplete OKF removal" },
+                                };
+                            }
+                            try {
+                                const removed = await this.okfStore.remove(type, title, expectedDigest);
+                                if (removed.removed)
+                                    this.options.onDurableMemoryChanged?.();
+                                return {
+                                    content: [
+                                        {
+                                            type: "text",
+                                            text: removed.removed
+                                                ? "Successfully removed structured OKF project memory."
+                                                : "Structured OKF project memory was already absent.",
+                                        },
+                                    ],
+                                    details: { success: true, removed: removed.removed },
+                                };
+                            }
+                            catch (err) {
+                                const error = String(err);
+                                return {
+                                    content: [{ type: "text", text: `Error: Failed to remove structured OKF memory: ${error}` }],
+                                    details: { success: false, error: /ENOENT/.test(error) ? "not found" : error },
+                                };
+                            }
+                        }
+                        if (type === undefined ||
+                            title === undefined ||
+                            description === undefined ||
+                            scope !== "project" ||
+                            content === undefined ||
+                            evidenceRefs === undefined ||
+                            evidenceRefs.length === 0) {
+                            return {
+                                content: [
+                                    {
+                                        type: "text",
+                                        text: "Error: structured OKF memory requires type, title, description, scope, content, and evidenceRefs.",
+                                    },
+                                ],
+                                details: { success: false, error: "Incomplete OKF memory" },
+                            };
+                        }
+                        if (!PI_OKF_TYPES.includes(type)) {
+                            return {
+                                content: [{ type: "text", text: `Error: unsupported OKF type '${type}'.` }],
+                                details: { success: false, error: "Unsupported OKF type" },
+                            };
+                        }
+                        const validationErrors = validateOkfMemoryDocumentInput({
+                            type: type,
+                            title,
+                            description,
+                            scope,
+                            body: content,
+                            tags,
+                            evidenceRefs,
+                        }, { projectOnly: true, requireEvidence: true });
+                        if (validationErrors.length > 0) {
+                            return {
+                                content: [
+                                    {
+                                        type: "text",
+                                        text: `Error: Invalid structured OKF memory: ${validationErrors.join("; ")}`,
+                                    },
+                                ],
+                                details: { success: false, error: "Invalid OKF memory" },
+                            };
+                        }
+                        const okfText = [type, title, description, scope, content, ...(tags ?? []), ...evidenceRefs].join("\n");
+                        if (hasInvisibleUnicode(okfText)) {
+                            return {
+                                content: [
+                                    {
+                                        type: "text",
+                                        text: "Error: OKF write rejected — contains hidden/bidirectional control characters.",
+                                    },
+                                ],
+                                details: { success: false, error: "Invisible unicode in OKF write" },
+                            };
+                        }
+                        const threats = scanContextFileThreats(okfText, "strict");
+                        if (threats.length > 0) {
+                            return {
+                                content: [
+                                    {
+                                        type: "text",
+                                        text: `Error: OKF write rejected — potential injection/exfiltration detected (${threats.join(", ")}).`,
+                                    },
+                                ],
+                                details: { success: false, error: "Threat in OKF write" },
+                            };
+                        }
+                        try {
+                            if (this.okfStore === undefined)
+                                throw new Error("Memory provider is not initialized.");
+                            const stored = await this.okfStore.put({
+                                type: type,
+                                title,
+                                description,
+                                scope,
+                                body: content,
+                                tags,
+                                evidenceRefs,
+                            });
+                            if (stored.created)
+                                this.options.onDurableMemoryChanged?.();
+                            return {
+                                content: [
+                                    {
+                                        type: "text",
+                                        text: stored.created
+                                            ? "Successfully added structured OKF project memory."
+                                            : "Structured OKF project memory already contained this exact record.",
+                                    },
+                                ],
+                                details: { success: true, created: stored.created, digest: stored.digest },
+                            };
+                        }
+                        catch (err) {
+                            return {
+                                content: [
+                                    { type: "text", text: `Error: Failed to write structured OKF memory: ${String(err)}` },
+                                ],
+                                details: { success: false, error: String(err) },
+                            };
+                        }
+                    }
+                    if (action === "list") {
+                        return {
+                            content: [{ type: "text", text: "Error: action 'list' is only supported for target 'okf'." }],
+                            details: { success: false, error: "Unsupported list target" },
+                        };
+                    }
                     const filePath = target === "memory" ? this.memoryFilePath : this.userFilePath;
                     const statePath = target === "memory" ? this.memoryStatePath : this.userStatePath;
                     const budget = target === "memory" ? FileStoreProvider.BUDGET_MEMORY : FileStoreProvider.BUDGET_USER;