@jack200714/mafw 4.5.1

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

@@ -0,0 +1,330 @@
+"use strict";
+// Embedding providers for dense retrieval (P1).
+//
+// Two transports share one interface:
+//   - dashscope: native DashScope text-embedding HTTP API (text-embedding-v4 =
+//     hosted Qwen3-Embedding; qwen3.7-text-embedding for 128K context). Auth
+//     reuses the runtime credentials → opencode auth.json chain, same as the
+//     index scan. Cheap (¥0.0005/1K tokens) but adds 100-500ms network latency,
+//     so callers must keep it off the synchronous 100ms recall path.
+//   - local: ONNX Qwen3-Embedding-0.6B via @huggingface/transformers
+//     (lazy model download to HF_HOME). Slower per call on CPU but zero
+//     network dependency — suitable for the sync path with small indexes.
+//
+// Query/document asymmetry follows the Qwen3-Embedding recipe: query inputs
+// get an `Instruct:` task prefix, document inputs are embedded verbatim.
+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.resolveEmbeddingBaseUrl = resolveEmbeddingBaseUrl;
+exports.buildQueryInput = buildQueryInput;
+exports.createEmbeddingProvider = createEmbeddingProvider;
+exports.resolveLocalModelProfile = resolveLocalModelProfile;
+const logger_1 = require("../core/utils/logger");
+const auth_1 = require("../runtime/auth");
+// Mirror + cache home for local ONNX model downloads (same policy as reranker).
+const path = __importStar(require("path"));
+const os = __importStar(require("os"));
+if (typeof process !== 'undefined') {
+    process.env.HF_ENDPOINT = process.env.HF_ENDPOINT || 'https://hf-mirror.com';
+    process.env.HF_HOME = process.env.HF_HOME || path.join(os.homedir(), '.mafw', 'models', 'huggingface');
+}
+const DASHSCOPE_EMBEDDING_URL = 'https://dashscope.aliyuncs.com/compatible-mode/v1/embeddings';
+const DEFAULT_QUERY_TASK = 'Given a user query, retrieve the most relevant memory entries from a long-term agent memory store';
+function resolveEmbeddingBaseUrl(providerID) {
+    if (!providerID)
+        return undefined;
+    const p = providerID.toLowerCase();
+    if (p === 'alibaba-cn' || p === 'dashscope' || p === 'qwen') {
+        return DASHSCOPE_EMBEDDING_URL;
+    }
+    return undefined;
+}
+function buildQueryInput(text, opts = {}) {
+    if (opts.asDocument)
+        return text;
+    return `Instruct: ${DEFAULT_QUERY_TASK}\nQuery: ${text}`;
+}
+function createEmbeddingProvider(cfg) {
+    if (!cfg.provider || cfg.provider === 'off')
+        return null;
+    if (cfg.provider === 'dashscope') {
+        return new DashScopeEmbeddingProvider(cfg);
+    }
+    if (cfg.provider === 'local') {
+        if (cfg.engine === 'llamacpp') {
+            // Runtime import: breaks the module cycle (llamacpp-provider imports
+            // buildQueryInput from this module) and keeps the sidecar code out of
+            // the ONNX path.
+            // eslint-disable-next-line @typescript-eslint/no-var-requires
+            const { LlamaCppServerProvider } = require('./llamacpp-provider');
+            return new LlamaCppServerProvider({
+                model: cfg.model,
+                dimensions: cfg.dimensions,
+                // threads lives at top level in EmbeddingProviderConfig; llamacpp.threads wins.
+                llamacpp: { ...(cfg.llamacpp ?? {}), threads: cfg.llamacpp?.threads ?? cfg.threads },
+            });
+        }
+        return new LocalEmbeddingProvider(cfg);
+    }
+    return null;
+}
+// ── DashScope native text-embedding API ─────────────────────────────────────
+class DashScopeEmbeddingProvider {
+    name;
+    dims;
+    apiKey;
+    authPath;
+    credentials;
+    fetchFn;
+    baseUrl;
+    maxBatch;
+    queryCache = new Map();
+    constructor(cfg) {
+        this.name = `dashscope:${cfg.model || 'text-embedding-v4'}`;
+        this.dims = cfg.dimensions || 1024;
+        this.apiKey = cfg.apiKey;
+        this.authPath = cfg.authPath;
+        this.credentials = cfg.credentials;
+        this.fetchFn = cfg.fetchFn ?? globalThis.fetch.bind(globalThis);
+        this.baseUrl = cfg.baseUrl || DASHSCOPE_EMBEDDING_URL;
+        // v4 batch limit is 10 rows; qwen3.7-text-embedding allows 20.
+        this.maxBatch = (cfg.model || '').includes('qwen3.7') ? 20 : 10;
+    }
+    resolveKey() {
+        if (this.apiKey)
+            return this.apiKey;
+        const providerID = 'alibaba-cn';
+        return (0, auth_1.getProviderApiKey)(providerID, this.authPath, this.credentials) ?? null;
+    }
+    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 apiKey = this.resolveKey();
+        if (!apiKey) {
+            throw new Error('no dashscope API key resolvable for embedding (credentials/auth.json)');
+        }
+        const out = new Array(texts.length);
+        for (let i = 0; i < texts.length; i += this.maxBatch) {
+            const batch = texts.slice(i, i + this.maxBatch);
+            const batchVectors = await this.embedBatch(batch, kind);
+            for (let j = 0; j < batchVectors.length; j++)
+                out[i + j] = batchVectors[j];
+        }
+        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;
+    }
+    async embedBatch(texts, kind) {
+        // OpenAI-compatible embeddings shape (dashscope compatible-mode). The
+        // native text_type=query/document asymmetry is unavailable here — query
+        // asymmetry is instead carried by buildQueryInput's Instruct prefix.
+        void kind;
+        const body = {
+            model: this.modelName(),
+            input: texts,
+            dimensions: this.dims,
+            encoding_format: 'float',
+        };
+        const resp = await this.fetchFn(this.baseUrl, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${apiKeyOf(this.resolveKey())}`,
+            },
+            body: JSON.stringify(body),
+        });
+        if (!resp.ok) {
+            throw new Error(`dashscope embedding failed: HTTP ${resp.status}`);
+        }
+        const data = await resp.json();
+        const rows = data?.data || [];
+        const byIndex = new Map();
+        for (const e of rows)
+            byIndex.set(e.index, e.embedding);
+        const out = [];
+        for (let i = 0; i < texts.length; i++) {
+            const vec = byIndex.get(i);
+            if (!vec)
+                throw new Error('dashscope embedding response missing index ' + i);
+            out.push(vec);
+        }
+        return out;
+    }
+    modelName() {
+        return this.name.slice('dashscope:'.length);
+    }
+}
+function apiKeyOf(key) {
+    return key ?? '';
+}
+const LOCAL_MODEL_PROFILES = [
+    { match: 'granite-embedding', profile: { pooling: 'mean', dims: 384, queryInstruction: false } },
+    { match: 'Qwen3-Embedding-0.6B', profile: { pooling: 'last-token', dims: 1024, queryInstruction: true } },
+];
+const DEFAULT_LOCAL_PROFILE = { pooling: 'last-token', dims: 1024, queryInstruction: true };
+function resolveLocalModelProfile(modelId) {
+    for (const { match, profile } of LOCAL_MODEL_PROFILES) {
+        if (modelId.includes(match))
+            return profile;
+    }
+    return DEFAULT_LOCAL_PROFILE;
+}
+class LocalEmbeddingProvider {
+    name;
+    dims;
+    modelId;
+    profile;
+    threads;
+    queryCache = new Map();
+    localDeps;
+    handle = null;
+    loading = null;
+    constructor(cfg) {
+        this.modelId = cfg.model || 'onnx-community/Qwen3-Embedding-0.6B-ONNX';
+        this.profile = resolveLocalModelProfile(this.modelId);
+        this.name = `local:${this.modelId}`;
+        this.dims = cfg.dimensions || this.profile.dims;
+        this.threads = Math.max(1, cfg.threads ?? 2);
+        this.localDeps = cfg.localDeps;
+    }
+    async ensureHandle() {
+        if (this.handle)
+            return this.handle;
+        if (this.loading)
+            return this.loading;
+        this.loading = (async () => {
+            if (this.localDeps?.modelFactory) {
+                this.handle = await this.localDeps.modelFactory(this.modelId);
+                return this.handle;
+            }
+            const mod = await new Function('spec', 'return import(spec)')('@huggingface/transformers');
+            mod.env.remoteHost = process.env.HF_ENDPOINT || 'https://hf-mirror.com/';
+            // Persist the model cache under the MAFW data root — the transformers.js
+            // default (<package>/.cache) is wiped on every `npm install -g` upgrade.
+            mod.env.cacheDir = path.join(os.homedir(), '.mafw', 'models', 'huggingface');
+            const tokenizer = await mod.AutoTokenizer.from_pretrained(this.modelId);
+            // Cap ORT parallelism: onnxruntime-node defaults intraOpNumThreads=0
+            // (all cores) → every 42ms embed spikes CPU to 100%. Document embeds are
+            // fire-and-forget background work, so a 2-core cap trades latency for a
+            // flat CPU profile; search-path queries hit the LRU cache on repeats.
+            const model = await mod.AutoModel.from_pretrained(this.modelId, {
+                dtype: 'q8',
+                session_options: { intraOpNumThreads: this.threads, interOpNumThreads: 1 },
+            });
+            this.handle = { tokenizer, model };
+            return this.handle;
+        })().catch((err) => {
+            this.loading = null;
+            logger_1.log.warn(`[Embedding] local model load failed: ${err?.message || err}`);
+            throw err;
+        });
+        return this.loading;
+    }
+    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 { tokenizer, model } = await this.ensureHandle();
+        const useInstruct = kind === 'query' && this.profile.queryInstruction;
+        const inputs = texts.map(t => buildQueryInput(t, { asDocument: !useInstruct }));
+        const tokenized = await tokenizer(inputs, { padding: true, truncation: true });
+        const output = await model(tokenized);
+        const lhs = output.last_hidden_state;
+        if (!lhs?.dims || lhs.dims.length !== 3) {
+            throw new Error('unexpected model output shape for embedding (expected last_hidden_state [B,L,H])');
+        }
+        const [B, L, H] = lhs.dims;
+        const mask = tokenized.attention_mask?.data ?? [];
+        const out = [];
+        for (let b = 0; b < B; b++) {
+            const row = new Array(H).fill(0);
+            if (this.profile.pooling === 'mean' && mask.length >= (b + 1) * L) {
+                // Masked mean pooling (granite/E5 family).
+                let count = 0;
+                for (let t = 0; t < L; t++) {
+                    if (Number(mask[b * L + t]) !== 1)
+                        continue;
+                    const offset = (b * L + t) * H;
+                    for (let h = 0; h < H; h++)
+                        row[h] += Number(lhs.data[offset + h]);
+                    count++;
+                }
+                if (count > 0)
+                    for (let h = 0; h < H; h++)
+                        row[h] /= count;
+            }
+            else {
+                // Last non-pad token (Qwen3-Embedding uses last-token pooling).
+                let lastIdx = L - 1;
+                if (mask.length >= (b + 1) * L) {
+                    lastIdx = 0;
+                    for (let t = 0; t < L; t++) {
+                        if (Number(mask[b * L + t]) === 1)
+                            lastIdx = t;
+                    }
+                }
+                const offset = (b * L + lastIdx) * H;
+                for (let h = 0; h < H; h++)
+                    row[h] = Number(lhs.data[offset + h]);
+            }
+            const nrm = Math.sqrt(row.reduce((s, x) => s + x * x, 0)) || 1;
+            out.push(row.map(x => x / nrm));
+        }
+        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;
+    }
+}

package/gateway/dist/memory/embedding-runtime.js

@@ -0,0 +1,174 @@
+"use strict";
+// EmbeddingRuntime: process-wide dense-retrieval wiring (P1).
+//
+// A single runtime instance owns the embedding provider, the vector store
+// (one JSON file per model under <baseDir>/memory/), and the write-path
+// indexer. Search entry points (MCP handler, HTTP route, eval harness) call
+// computeDenseScores() and pass the result into searchScored({ denseScores }).
+//
+// Everything here is fail-open: embedding errors degrade to BM25-only recall,
+// never block the synchronous path.
+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.setEmbeddingRuntime = setEmbeddingRuntime;
+exports.getEmbeddingRuntime = getEmbeddingRuntime;
+exports.initEmbeddingRuntime = initEmbeddingRuntime;
+exports.computeDenseScores = computeDenseScores;
+const path = __importStar(require("path"));
+const config_1 = require("../config");
+const logger_1 = require("../core/utils/logger");
+const embedding_provider_1 = require("./embedding-provider");
+const vector_store_1 = require("./vector-store");
+let runtime = null;
+function setEmbeddingRuntime(rt) {
+    runtime = rt;
+}
+function getEmbeddingRuntime() {
+    return runtime;
+}
+function initEmbeddingRuntime(opts) {
+    const cfg = opts.cfg ?? config_1.config.memory?.embedding;
+    if (!cfg || cfg.provider === 'off')
+        return null;
+    try {
+        const provider = (0, embedding_provider_1.createEmbeddingProvider)({
+            provider: cfg.provider,
+            model: cfg.model,
+            dimensions: cfg.dimensions,
+            baseUrl: cfg.baseUrl || undefined,
+            threads: cfg.threads,
+            engine: cfg.engine,
+            llamacpp: cfg.llamacpp,
+        });
+        if (!provider)
+            return null;
+        // Tag the vector file by provider identity (engine + model), not just the
+        // config model id: ONNX-q8 and GGUF-Q4 embeddings of the same model are
+        // numerically different and must not share a vector store.
+        const modelTag = provider.name.replace(/[^a-zA-Z0-9._-]/g, '_');
+        const vectors = new vector_store_1.MemoryVectorStore(path.join(opts.baseDir, 'memory', `vectors-${modelTag}.json`), cfg.dimensions || provider.dims, cfg.model);
+        const indexer = new vector_store_1.EmbeddingIndexer({ vectors, provider, getTextForId: opts.getTextForId });
+        let flushTimer = null;
+        const rt = {
+            provider,
+            vectors,
+            indexer,
+            scheduleFlush() {
+                if (flushTimer)
+                    return;
+                flushTimer = setTimeout(() => {
+                    flushTimer = null;
+                    indexer.flushQueue().catch(() => { });
+                }, 2000);
+                flushTimer.unref?.();
+            },
+        };
+        runtime = rt;
+        logger_1.log.info(`[Embedding] runtime initialized: ${provider.name} (${vectors.size()} vectors)`);
+        return rt;
+    }
+    catch (err) {
+        logger_1.log.warn(`[Embedding] runtime init failed (BM25-only fallback): ${err?.message || err}`);
+        return null;
+    }
+}
+/**
+ * Query-side dense scores for hybrid retrieval. Returns null on any failure —
+ * callers pass the map into searchScored({ denseScores }) or fall back to
+ * plain BM25.
+ */
+/**
+ * Two dense hits with self-cosine ≥ this are treated as the same fact's
+ * old/new versions (knowledge-update pattern): semantic similarity is blind
+ * to WHICH version is current, so keep the newer and suppress the older —
+ * the BM25 channel still sees it (exact keywords on the updated value).
+ */
+const NEAR_DUP_COSINE = 0.92;
+async function computeDenseScores(query, topK, index) {
+    const rt = runtime;
+    if (!rt)
+        return null;
+    try {
+        const [queryVector] = await rt.provider.embed([query], 'query');
+        if (!queryVector)
+            return null;
+        let hits = rt.vectors.searchByCosine(queryVector, topK);
+        if (index && hits.length > 1) {
+            hits = suppressNearDuplicates(hits, rt.vectors, index.getIndex().entries);
+        }
+        return new Map(hits.map(h => [h.id, h.cosine]));
+    }
+    catch (err) {
+        logger_1.log.warn(`[Embedding] dense scores unavailable (BM25 fallback): ${err?.message || err}`);
+        return null;
+    }
+}
+function suppressNearDuplicates(hits, vectors, entries) {
+    const createdAt = new Map(entries.map(e => [e.id, e.created_at]));
+    const vecOf = (id) => vectors.get(id);
+    const suppressed = new Set();
+    for (let i = 0; i < hits.length; i++) {
+        for (let j = i + 1; j < hits.length; j++) {
+            const a = hits[i];
+            const b = hits[j];
+            if (suppressed.has(a.id) || suppressed.has(b.id))
+                continue;
+            const va = vecOf(a.id);
+            const vb = vecOf(b.id);
+            if (!va || !vb || va.length !== vb.length)
+                continue;
+            let dot = 0;
+            let na = 0;
+            let nb = 0;
+            for (let k = 0; k < va.length; k++) {
+                dot += va[k] * vb[k];
+                na += va[k] * va[k];
+                nb += vb[k] * vb[k];
+            }
+            if (na === 0 || nb === 0)
+                continue;
+            if (dot / Math.sqrt(na * nb) < NEAR_DUP_COSINE)
+                continue;
+            const ta = Date.parse(createdAt.get(a.id) ?? '');
+            const tb = Date.parse(createdAt.get(b.id) ?? '');
+            if (Number.isNaN(ta) || Number.isNaN(tb))
+                continue; // can't order → keep both
+            suppressed.add(ta < tb ? a.id : b.id);
+        }
+    }
+    if (suppressed.size === 0)
+        return hits;
+    return hits.filter(h => !suppressed.has(h.id));
+}

package/gateway/dist/memory/event-log.js

@@ -0,0 +1,84 @@
+"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.EventLog = void 0;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const EVENT_LOG = '.memory-events.log';
+class EventLog {
+    baseDir;
+    constructor(baseDir) {
+        this.baseDir = baseDir;
+    }
+    logFile() {
+        const dir = path.join(this.baseDir, 'memory');
+        if (!fs.existsSync(dir))
+            fs.mkdirSync(dir, { recursive: true });
+        return path.join(dir, EVENT_LOG);
+    }
+    append(entry) {
+        entry.ts = Date.now();
+        fs.appendFileSync(this.logFile(), JSON.stringify(entry) + '\n', 'utf-8');
+    }
+    appendWrite(id, entryData) {
+        this.append({ op: 'write', id, entry: entryData });
+    }
+    appendArchive(id) {
+        this.append({ op: 'archive', id });
+    }
+    appendMiss(query, cause) {
+        this.append({ op: 'miss', query, miss_cause: cause });
+    }
+    appendAccess(id, round, score) {
+        this.append({ op: 'access', id, round, score });
+    }
+    readAll() {
+        const filePath = this.logFile();
+        if (!fs.existsSync(filePath))
+            return [];
+        const lines = fs.readFileSync(filePath, 'utf-8').split('\n').filter(Boolean);
+        const entries = [];
+        for (const line of lines) {
+            try {
+                entries.push(JSON.parse(line));
+            }
+            catch {
+                // skip corrupt lines
+            }
+        }
+        return entries;
+    }
+}
+exports.EventLog = EventLog;