@jack200714/mafw 4.5.1

package/gateway/dist/memory/llamacpp-provider.js

@@ -0,0 +1,370 @@
+"use strict";
+// llama.cpp embedding engine via llama-server sidecar (native binary).
+//
+// Why a sidecar instead of node-llama-cpp: the JS binding layer costs ~5.5x
+// on this class of hardware (native decodeBatch 111 tok/s vs official
+// llama-bench 610 tok/s on i9-13900H), and its npm optionalDeps bloat every
+// install by ~650MB. The official llama.cpp win-cpu zip is 18MB, runs the
+// model at native speed, keeps embeddings out of the gateway process (crash
+// isolation + OS-level memory accounting), and switching to GPU later is a
+// binary-variant swap (vulkan zip, 34MB) with zero code changes.
+//
+// Lifecycle: lazy start on first embed → poll /health → OpenAI-compatible
+// POST /v1/embeddings. Fail-open: startup/inference errors propagate so
+// callers (computeDenseScores, EmbeddingIndexer) degrade to BM25-only.
+//
+// Query/document asymmetry reuses the Qwen3 recipe via buildQueryInput —
+// llama.cpp pooling (LAST) comes from the GGUF metadata, not our code.
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LlamaCppServerProvider = void 0;
+const child_process_1 = require("child_process");
+const fs = __importStar(require("fs"));
+const net = __importStar(require("net"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const logger_1 = require("../core/utils/logger");
+const embedding_provider_1 = require("./embedding-provider");
+const DEFAULT_BINARY_VERSION = 'b10752';
+const DEFAULT_MODEL = 'hf:mradermacher/Qwen3-Embedding-0.6B-GGUF:Qwen3-Embedding-0.6B.Q4_K_M.gguf';
+const HEALTH_TIMEOUT_MS = 60_000;
+const REQUEST_TIMEOUT_MS = 120_000;
+function platformKey() {
+    if (process.platform === 'win32')
+        return 'win';
+    if (process.platform === 'darwin')
+        return 'mac';
+    return 'linux';
+}
+/** Assets to download per variant (cuda needs the cudart companion zip). */
+function assetNames(variant, version) {
+    const p = platformKey();
+    const arch = process.arch === 'arm64' ? 'arm64' : 'x64';
+    if (p === 'win') {
+        if (arch !== 'x64' && variant !== 'cpu')
+            return null; // GPU variants: x64 only
+        if (variant === 'cuda') {
+            return {
+                files: [
+                    `llama-${version}-bin-win-cuda-12.4-x64.zip`,
+                    `cudart-llama-bin-win-cuda-12.4-x64.zip`,
+                ],
+                exe: 'llama-server.exe',
+            };
+        }
+        const v = variant === 'vulkan' ? 'vulkan-x64' : arch === 'arm64' ? 'cpu-arm64' : 'cpu-x64';
+        return { files: [`llama-${version}-bin-win-${v}.zip`], exe: 'llama-server.exe' };
+    }
+    if (p === 'mac') {
+        // Metal is built into the macOS binary — no separate variant needed.
+        return { files: [`llama-${version}-bin-macos-arm64.zip`], exe: 'llama-server' };
+    }
+    if (p === 'linux') {
+        if (variant === 'vulkan')
+            return { files: [`llama-${version}-bin-ubuntu-vulkan-x64.zip`], exe: 'llama-server' };
+        return { files: [`llama-${version}-bin-ubuntu-x64.zip`], exe: 'llama-server' };
+    }
+    return null;
+}
+async function pickFreePort() {
+    return new Promise((resolve, reject) => {
+        const srv = net.createServer();
+        srv.once('error', reject);
+        srv.listen(0, '127.0.0.1', () => {
+            const port = srv.address().port;
+            srv.close(() => resolve(port));
+        });
+    });
+}
+class LlamaCppServerProvider {
+    name;
+    dims;
+    cfg;
+    child = null;
+    starting = null;
+    baseUrl = null;
+    queryCache = new Map();
+    consecutiveFailures = 0;
+    exitHookRegistered = false;
+    constructor(opts) {
+        this.cfg = opts.llamacpp ?? {};
+        const modelTag = (this.cfg.modelFile || DEFAULT_MODEL).split(':').pop() || 'qwen3-embedding';
+        this.name = `llamacpp:${modelTag}`;
+        this.dims = opts.dimensions || 1024;
+    }
+    // ── lifecycle ────────────────────────────────────────────────────────────
+    binDir() {
+        return this.cfg.deps?.binDir ?? path.join(os.homedir(), '.mafw', 'bin', 'llama.cpp');
+    }
+    modelDir() {
+        return this.cfg.deps?.modelDir ?? path.join(os.homedir(), '.mafw', 'models', 'gguf');
+    }
+    variant() {
+        if (this.cfg.gpu === 'vulkan')
+            return 'vulkan';
+        if (this.cfg.gpu === 'cuda')
+            return 'cuda';
+        return 'cpu';
+    }
+    async ensureBinary() {
+        const version = this.cfg.binaryVersion || DEFAULT_BINARY_VERSION;
+        const asset = assetNames(this.variant(), version);
+        if (!asset)
+            throw new Error(`llama.cpp binary: unsupported platform ${process.platform}/${process.arch}/${this.variant()}`);
+        const dir = path.join(this.binDir(), version, this.variant());
+        const exe = path.join(dir, asset.exe);
+        if (fs.existsSync(exe))
+            return exe;
+        fs.mkdirSync(dir, { recursive: true });
+        const fetchFn = this.cfg.deps?.fetchFn ?? globalThis.fetch.bind(globalThis);
+        for (const file of asset.files) {
+            const zipPath = path.join(dir, file);
+            const rel = `ggml-org/llama.cpp/releases/download/${version}/${file}`;
+            const mirrors = [
+                `https://github.com/${rel}`,
+                `https://ghfast.top/https://github.com/${rel}`,
+                `https://gh-proxy.com/https://github.com/${rel}`,
+            ];
+            let lastErr = null;
+            for (const url of mirrors) {
+                try {
+                    logger_1.log.info(`[LlamaCpp] downloading binary: ${url}`);
+                    const resp = await fetchFn(url, { redirect: 'follow' });
+                    if (!resp.ok)
+                        throw new Error(`HTTP ${resp.status}`);
+                    fs.writeFileSync(zipPath, Buffer.from(await resp.arrayBuffer()));
+                    // tar.exe (bsdtar) ships with Windows 10+ and handles zip; tar on unix too.
+                    await new Promise((resolve, reject) => {
+                        const tar = (0, child_process_1.spawn)('tar', ['-xf', zipPath, '-C', dir], { windowsHide: true });
+                        tar.on('exit', code => (code === 0 ? resolve() : reject(new Error(`tar exit ${code}`))));
+                        tar.on('error', reject);
+                    });
+                    fs.rmSync(zipPath, { force: true });
+                    lastErr = null;
+                    break;
+                }
+                catch (err) {
+                    lastErr = err;
+                    logger_1.log.warn(`[LlamaCpp] binary download failed via ${url}: ${err?.message || err}`);
+                }
+            }
+            if (lastErr)
+                throw lastErr;
+        }
+        if (!fs.existsSync(exe))
+            throw new Error(`binary missing after extract: ${exe}`);
+        return exe;
+    }
+    async ensureModel() {
+        const spec = this.cfg.modelFile || DEFAULT_MODEL;
+        if (!spec.startsWith('hf:')) {
+            if (!fs.existsSync(spec))
+                throw new Error(`llama.cpp model not found: ${spec}`);
+            return spec;
+        }
+        const [, repo, file] = spec.split(':');
+        const dest = path.join(this.modelDir(), file);
+        if (fs.existsSync(dest) && fs.statSync(dest).size > 100 * 1048576)
+            return dest;
+        fs.mkdirSync(this.modelDir(), { recursive: true });
+        const base = (process.env.HF_ENDPOINT || 'https://hf-mirror.com').replace(/\/$/, '');
+        const url = `${base}/${repo}/resolve/main/${file}`;
+        logger_1.log.info(`[LlamaCpp] downloading model: ${url}`);
+        const fetchFn = this.cfg.deps?.fetchFn ?? globalThis.fetch.bind(globalThis);
+        const resp = await fetchFn(url, { redirect: 'follow' });
+        if (!resp.ok)
+            throw new Error(`model download HTTP ${resp.status}`);
+        fs.writeFileSync(dest + '.tmp', Buffer.from(await resp.arrayBuffer()));
+        fs.renameSync(dest + '.tmp', dest);
+        return dest;
+    }
+    async ensureServer() {
+        if (this.baseUrl && this.child && !this.child.killed)
+            return this.baseUrl;
+        if (this.starting)
+            return this.starting.then(() => this.baseUrl);
+        this.starting = (async () => {
+            const exe = await this.ensureBinary();
+            const model = await this.ensureModel();
+            const port = this.cfg.port && this.cfg.port > 0 ? this.cfg.port : await pickFreePort();
+            const threads = Math.max(1, this.cfg.threads ?? 2);
+            const ctxSize = Math.max(256, this.cfg.contextSize ?? 2048);
+            const spawnFn = this.cfg.deps?.spawnFn ?? child_process_1.spawn;
+            this.child = spawnFn(exe, [
+                '-m', model,
+                '--port', String(port),
+                '--host', '127.0.0.1',
+                '-c', String(ctxSize),
+                // Physical batch must cover one full sequence (embeddings mode splits
+                // nothing across ubatches); keep batch == ctx so the 400 limit above
+                // is the only gate.
+                '-b', String(ctxSize),
+                '-ub', String(ctxSize),
+                '-t', String(threads),
+                // GPU variants (vulkan/cuda): offload all layers — without -ngl the
+                // GPU binary still runs everything on CPU. Measured on RTX 4090
+                // Laptop: vulkan 12ms/embed vs 65ms CPU, ~zero CPU usage.
+                ...(this.variant() === 'cpu' ? [] : ['-ngl', '99']),
+                // Flash attention: mandatory for embedding mode. Without it the
+                // non-causal attention materializes an L×L matrix per head
+                // (4096-ctx RSS ~3GB); with it RSS stays ~880MB at ctx 2048.
+                '-fa', 'on',
+                // One slot: this is a single-client background service. np=auto and
+                // the default warmup each allocate per-slot KV + max-size compute
+                // buffers (observed 2.8GB); np 1 + no-warmup holds load RSS ~925MB.
+                '-np', '1',
+                '--no-warmup',
+                // Embeddings-only server: the prompt cache is write-only for embedding
+                // tasks and grows unbounded to --cache-ram (8GB default) — llama.cpp
+                // issue #26293. -cram 0 disables it; repeats are our LRU's job.
+                '-cram', '0',
+                '--embeddings',
+                '--log-disable',
+            ], { windowsHide: true, stdio: 'ignore' });
+            this.child.on('exit', code => {
+                logger_1.log.warn(`[LlamaCpp] server exited (code ${code}) — next embed restarts it`);
+                this.child = null;
+                this.baseUrl = null;
+                this.starting = null;
+            });
+            if (!this.exitHookRegistered) {
+                this.exitHookRegistered = true;
+                process.once('exit', () => this.killServer());
+            }
+            const url = `http://127.0.0.1:${port}`;
+            const fetchFn = this.cfg.deps?.fetchFn ?? globalThis.fetch.bind(globalThis);
+            const deadline = Date.now() + HEALTH_TIMEOUT_MS;
+            for (;;) {
+                try {
+                    const resp = await fetchFn(`${url}/health`);
+                    if (resp.ok)
+                        break;
+                }
+                catch { /* not up yet */ }
+                if (Date.now() > deadline)
+                    throw new Error('llama-server health check timed out');
+                await new Promise(r => setTimeout(r, 500));
+            }
+            this.baseUrl = url;
+            logger_1.log.info(`[LlamaCpp] server ready on :${port} (threads=${threads}, ctx=${ctxSize}, variant=${this.variant()})`);
+        })().catch(err => {
+            this.starting = null;
+            this.killServer();
+            throw err;
+        });
+        return this.starting.then(() => this.baseUrl);
+    }
+    killServer() {
+        const child = this.child;
+        this.child = null;
+        this.baseUrl = null;
+        if (!child || child.killed || child.pid == null)
+            return;
+        try {
+            if (process.platform === 'win32') {
+                // child.kill is unreliable for spawned trees on Windows (kernel trap).
+                (0, child_process_1.spawn)('taskkill', ['/F', '/T', '/PID', String(child.pid)], { windowsHide: true, stdio: 'ignore' });
+            }
+            else {
+                child.kill('SIGTERM');
+            }
+        }
+        catch { /* best effort */ }
+    }
+    async postEmbeddings(fetchFn, baseUrl, inputs) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+        try {
+            const resp = await fetchFn(`${baseUrl}/v1/embeddings`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ input: inputs }),
+                signal: controller.signal,
+            });
+            if (!resp.ok)
+                throw new Error(`llama-server embeddings HTTP ${resp.status}`);
+            return await resp.json();
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    // ── EmbeddingProvider ────────────────────────────────────────────────────
+    async embed(texts, kind) {
+        if (texts.length === 0)
+            return [];
+        if (kind === 'query' && texts.length === 1) {
+            const cached = this.queryCache.get(texts[0]);
+            if (cached)
+                return cached;
+        }
+        const baseUrl = await this.ensureServer();
+        const inputs = texts.map(t => (kind === 'query' ? (0, embedding_provider_1.buildQueryInput)(t) : t));
+        const fetchFn = this.cfg.deps?.fetchFn ?? globalThis.fetch.bind(globalThis);
+        const data = await this.postEmbeddings(fetchFn, baseUrl, inputs)
+            // llama-server 400s when a single input exceeds -c. Truncate to a safe
+            // budget (~2 chars/token worst case) and retry once rather than dropping
+            // the batch from the dense channel entirely.
+            .catch(async (err) => {
+            if (!/HTTP 400/.test(err?.message || ''))
+                throw err;
+            logger_1.log.warn('[LlamaCpp] input rejected (too long) — retrying with 1500-char truncation');
+            return this.postEmbeddings(fetchFn, baseUrl, inputs.map(t => t.slice(0, 1500)));
+        });
+        const rows = data?.data || [];
+        const byIndex = new Map();
+        for (const r of rows)
+            byIndex.set(r.index, r.embedding);
+        const out = [];
+        for (let i = 0; i < texts.length; i++) {
+            const vec = byIndex.get(i);
+            if (!vec || vec.length === 0)
+                throw new Error(`llama-server embeddings missing index ${i}`);
+            const nrm = Math.sqrt(vec.reduce((s, x) => s + x * x, 0)) || 1;
+            out.push(nrm === 1 ? vec : vec.map(x => x / nrm));
+        }
+        this.consecutiveFailures = 0;
+        if (kind === 'query' && texts.length === 1) {
+            if (this.queryCache.size >= 256) {
+                const first = this.queryCache.keys().next().value;
+                if (first !== undefined)
+                    this.queryCache.delete(first);
+            }
+            this.queryCache.set(texts[0], out);
+        }
+        return out;
+    }
+}
+exports.LlamaCppServerProvider = LlamaCppServerProvider;

package/gateway/dist/memory/okf-index-renderer.js

@@ -0,0 +1,61 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderIndexMd = renderIndexMd;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+function renderIndexMd(baseDir, indexManager) {
+    const index = indexManager.getIndex();
+    const lines = ['# Memory Index', '', '> Auto-generated from `.harmonic_index.json`', ''];
+    const byTier = new Map();
+    for (const entry of index.entries) {
+        const tier = entry.tier || 'unknown';
+        if (!byTier.has(tier))
+            byTier.set(tier, []);
+        byTier.get(tier).push(entry);
+    }
+    for (const [tier, entries] of byTier) {
+        lines.push(`## ${tier}`, '');
+        for (const e of entries) {
+            const pathStr = e.filePath || '';
+            lines.push(`- **${e.primary_abstraction}** (energy: ${e.energy}) —\`${pathStr}\``);
+        }
+        lines.push('');
+    }
+    const memDir = path.join(baseDir, 'memory');
+    if (!fs.existsSync(memDir))
+        fs.mkdirSync(memDir, { recursive: true });
+    fs.writeFileSync(path.join(memDir, 'index.md'), lines.join('\n'), 'utf-8');
+}

package/gateway/dist/memory/okf-migrator.js

@@ -0,0 +1,71 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.migrateFromJson = migrateFromJson;
+const logger_1 = require("../core/utils/logger");
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const harmonic_file_store_1 = require("./harmonic-file-store");
+const okf_index_renderer_1 = require("./okf-index-renderer");
+async function migrateFromJson(mafwDir) {
+    const memPath = path.join(mafwDir, 'memory', 'memories.json');
+    if (!fs.existsSync(memPath))
+        return { migrated: 0, skipped: 0 };
+    const units = JSON.parse(fs.readFileSync(memPath, 'utf-8'));
+    const store = new harmonic_file_store_1.HarmonicUnitFileStore(mafwDir);
+    let migrated = 0;
+    let skipped = 0;
+    for (const unit of units) {
+        if (unit.type === 'episodic') {
+            skipped++;
+            continue;
+        }
+        try {
+            await store.write(unit);
+            migrated++;
+        }
+        catch (err) {
+            logger_1.log.warn(`[migrate] Failed to migrate ${unit.id}: ${err}`);
+            skipped++;
+        }
+    }
+    // Backup old file
+    fs.renameSync(memPath, memPath + '.bak');
+    // Render index.md
+    const { HarmonicIndexManager } = require('../core/memory/harmonic-index');
+    const indexManager = new HarmonicIndexManager(mafwDir);
+    (0, okf_index_renderer_1.renderIndexMd)(mafwDir, indexManager);
+    return { migrated, skipped };
+}

package/gateway/dist/memory/okf-parser.js

@@ -0,0 +1,57 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseOKF = parseOKF;
+exports.readOKFFile = readOKFFile;
+const fs = __importStar(require("fs"));
+const yaml = __importStar(require("js-yaml"));
+const LINK_REGEX = /\[\[([^\]]+)\]\]/g;
+function parseOKF(content) {
+    const match = content.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+    if (!match)
+        throw new Error('Invalid OKF format: missing frontmatter');
+    const frontmatter = yaml.load(match[1]);
+    const body = match[2].trim();
+    const links = [...(frontmatter.links || [])];
+    let linkMatch;
+    while ((linkMatch = LINK_REGEX.exec(body)) !== null) {
+        links.push(linkMatch[1]);
+    }
+    return { unit: frontmatter, body, links: [...new Set(links)] };
+}
+function readOKFFile(filePath) {
+    const content = fs.readFileSync(filePath, 'utf-8');
+    return parseOKF(content);
+}

package/gateway/dist/memory/okf-writer.js

@@ -0,0 +1,107 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildOKF = buildOKF;
+exports.getOKFFilename = getOKFFilename;
+exports.getOKFDirectory = getOKFDirectory;
+exports.writeOKFFile = writeOKFFile;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const yaml = __importStar(require("js-yaml"));
+function buildOKF(unit) {
+    const frontmatter = {
+        type: unit.type === 'semantic' && unit.granularity ? 'knowledge' : unit.type,
+        id: unit.id,
+        primary_abstraction: unit.primary_abstraction,
+        cue_anchors: unit.cue_anchors,
+        energy: unit.energy,
+        created_at: unit.created_at,
+        updated_at: unit.updated_at,
+    };
+    if (unit.granularity)
+        frontmatter.granularity = unit.granularity;
+    if (unit.salience !== undefined)
+        frontmatter.salience = unit.salience;
+    if (unit.abstraction_level !== undefined)
+        frontmatter.abstraction_level = unit.abstraction_level;
+    if (unit.merged_from?.length)
+        frontmatter.merged_from = unit.merged_from;
+    if (unit.superseded_by)
+        frontmatter.superseded_by = unit.superseded_by;
+    if (unit.pinned !== undefined)
+        frontmatter.pinned = unit.pinned;
+    if (unit.sticky_until)
+        frontmatter.sticky_until = unit.sticky_until;
+    if (unit.source_session_id)
+        frontmatter.source_session_id = unit.source_session_id;
+    const yamlStr = yaml.dump(frontmatter, { lineWidth: -1, quotingType: '"' });
+    return `---\n${yamlStr}---\n${unit.memory_value}\n`;
+}
+function getOKFFilename(unit) {
+    const typeLabel = unit.type === 'semantic' && unit.granularity
+        ? 'knowledge'
+        : unit.type === 'procedural' ? 'procedural'
+            : unit.type === 'episodic' ? 'episodic'
+                : unit.type === 'global' ? 'global'
+                    : 'semantic';
+    const slug = unit.primary_abstraction
+        .toLowerCase().replace(/[^a-z0-9\u4e00-\u9fff]+/g, '-').replace(/^-|-$/g, '').slice(0, 40);
+    return `${typeLabel}-${unit.id}-${slug}.md`;
+}
+function getOKFDirectory(unit) {
+    if (unit.type === 'procedural')
+        return 'concepts/procedural';
+    if (unit.type === 'semantic' && unit.granularity)
+        return 'concepts/knowledge';
+    if (unit.type === 'semantic')
+        return 'concepts/semantic';
+    if (unit.type === 'episodic')
+        return 'concepts/episodic';
+    if (unit.type === 'global')
+        return 'concepts/global';
+    throw new Error(`unknown type ${unit.type} should not be written to OKF directly`);
+}
+function writeOKFFile(baseDir, unit) {
+    const dir = getOKFDirectory(unit);
+    const fileName = getOKFFilename(unit);
+    const fullDir = path.join(baseDir, 'memory', dir);
+    if (!fs.existsSync(fullDir)) {
+        fs.mkdirSync(fullDir, { recursive: true });
+    }
+    const fullPath = path.join(fullDir, fileName);
+    const content = buildOKF(unit);
+    fs.writeFileSync(fullPath, content, 'utf-8');
+    return fileName;
+}