hoomanjs 1.28.2 → 1.28.3

package/dist/core/memory/index.d.ts

@@ -1,3 +1,4 @@
 export { create as createShortTermMemory } from "./stm/index.js";
 export { createLongTermMemoryStore, createLongTermMemoryTools, LongTermMemoryStore, } from "./ltm/index.js";
+export { WikiStore, createWikiStore } from "./wiki/index.js";
 export type { ArchiveMemoryInput, LongTermMemoryOptions, LongTermMemoryScope, MemorySource, SearchMemoryInput, SearchMemoryResult, StoreMemoryInput, StoreMemoryResult, UpdateMemoryInput, } from "./ltm/index.js";

package/dist/core/memory/index.js

@@ -1,3 +1,4 @@
 export { create as createShortTermMemory } from "./stm/index.js";
 export { createLongTermMemoryStore, createLongTermMemoryTools, LongTermMemoryStore, } from "./ltm/index.js";
+export { WikiStore, createWikiStore } from "./wiki/index.js";
 //# sourceMappingURL=index.js.map

package/dist/core/memory/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/core/memory/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,IAAI,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AACjE,OAAO,EACL,yBAAyB,EACzB,yBAAyB,EACzB,mBAAmB,GACpB,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/core/memory/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,IAAI,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AACjE,OAAO,EACL,yBAAyB,EACzB,yBAAyB,EACzB,mBAAmB,GACpB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/core/memory/ltm/llama-embed.d.ts

@@ -0,0 +1,28 @@
+export declare function isQwen3EmbeddingModel(modelUri: string): boolean;
+export declare function formatQueryForEmbedding(query: string, modelUri?: string): string;
+export declare function formatDocForEmbedding(text: string, title: string | undefined, modelUri?: string): string;
+export type LtmLlamaEmbedderOptions = {
+    modelUri: string;
+    cacheDir: string;
+};
+/**
+ * Lazy local GGUF embeddings (node-llama-cpp), matching QMD formatting rules.
+ */
+export declare class LtmLlamaEmbedder {
+    private readonly modelUri;
+    private readonly cacheDir;
+    private llama;
+    private model;
+    private context;
+    private loadPromise;
+    constructor(options: LtmLlamaEmbedderOptions);
+    get resolvedModelUri(): string;
+    /** Load GGUF + embedding context (no forward pass). Call at agent startup to avoid blocking tools. */
+    warmup(): Promise<void>;
+    private ensureLoaded;
+    private resolveEmbedTokenLimit;
+    private truncateToContextSize;
+    embedQuery(query: string): Promise<Float32Array>;
+    embedDocument(content: string): Promise<Float32Array>;
+    dispose(): Promise<void>;
+}

package/dist/core/memory/ltm/llama-embed.js

@@ -0,0 +1,204 @@
+import { getLlama, resolveModelFile, LlamaLogLevel, } from "node-llama-cpp";
+import { closeSync, existsSync, mkdirSync, openSync, readSync, statSync, unlinkSync, } from "node:fs";
+const GGUF_MAGIC = Buffer.from("GGUF");
+function validateGgufFile(filePath, modelUri) {
+    if (!existsSync(filePath)) {
+        return;
+    }
+    const fd = openSync(filePath, "r");
+    const sniff = Buffer.alloc(512);
+    try {
+        readSync(fd, sniff, 0, 512, 0);
+    }
+    finally {
+        closeSync(fd);
+    }
+    const header = sniff.subarray(0, 4);
+    if (header.equals(GGUF_MAGIC)) {
+        return;
+    }
+    const text = sniff.toString("utf-8").toLowerCase();
+    const isHtml = text.includes("<!doctype") || text.includes("<html");
+    const got = header.toString("utf-8");
+    const sizeKB = (statSync(filePath).size / 1024).toFixed(0);
+    unlinkSync(filePath);
+    if (isHtml) {
+        throw new Error(`Downloaded LTM embed model is an HTML page, not GGUF (${sizeKB} KB).\n` +
+            `Model: ${modelUri}\nPath: ${filePath}`);
+    }
+    throw new Error(`LTM embed model is not valid GGUF (expected "GGUF", got "${got}", ${sizeKB} KB).\n` +
+        `Model: ${modelUri}`);
+}
+export function isQwen3EmbeddingModel(modelUri) {
+    return /qwen.*embed/i.test(modelUri) || /embed.*qwen/i.test(modelUri);
+}
+export function formatQueryForEmbedding(query, modelUri) {
+    const uri = modelUri ?? "";
+    if (isQwen3EmbeddingModel(uri)) {
+        return `Instruct: Retrieve relevant documents for the given query\nQuery: ${query}`;
+    }
+    return `task: search result | query: ${query}`;
+}
+export function formatDocForEmbedding(text, title, modelUri) {
+    const uri = modelUri ?? "";
+    if (isQwen3EmbeddingModel(uri)) {
+        return title ? `${title}\n${text}` : text;
+    }
+    return `title: ${title || "none"} | text: ${text}`;
+}
+function resolveLlamaGpuMode() {
+    if (process.env.CI) {
+        return false;
+    }
+    const raw = process.env.HOOMAN_LTM_LLAMA_GPU?.trim() ||
+        process.env.QMD_LLAMA_GPU?.trim() ||
+        "";
+    const normalized = raw.toLowerCase();
+    if (!normalized) {
+        return "auto";
+    }
+    if (["false", "off", "none", "disable", "disabled", "0"].includes(normalized)) {
+        return false;
+    }
+    if (normalized === "metal" ||
+        normalized === "vulkan" ||
+        normalized === "cuda") {
+        return normalized;
+    }
+    return "auto";
+}
+function resolveEmbedContextSize() {
+    const v = Number.parseInt(process.env.HOOMAN_LTM_EMBED_CONTEXT_SIZE ?? "", 10);
+    if (Number.isFinite(v) && v > 0) {
+        return v;
+    }
+    return 2048;
+}
+const EMBED_CONTEXT_SIZE = resolveEmbedContextSize();
+/**
+ * Lazy local GGUF embeddings (node-llama-cpp), matching QMD formatting rules.
+ */
+export class LtmLlamaEmbedder {
+    modelUri;
+    cacheDir;
+    llama = null;
+    model = null;
+    context = null;
+    loadPromise = null;
+    constructor(options) {
+        this.modelUri = options.modelUri;
+        this.cacheDir = options.cacheDir;
+    }
+    get resolvedModelUri() {
+        return this.modelUri;
+    }
+    /** Load GGUF + embedding context (no forward pass). Call at agent startup to avoid blocking tools. */
+    async warmup() {
+        await this.ensureLoaded();
+    }
+    async ensureLoaded() {
+        if (this.context) {
+            return;
+        }
+        if (this.loadPromise) {
+            await this.loadPromise;
+            return;
+        }
+        this.loadPromise = (async () => {
+            if (!existsSync(this.cacheDir)) {
+                mkdirSync(this.cacheDir, { recursive: true });
+            }
+            const modelPath = await resolveModelFile(this.modelUri, this.cacheDir);
+            validateGgufFile(modelPath, this.modelUri);
+            const gpuMode = resolveLlamaGpuMode();
+            const loadLlama = async (gpu) => getLlama({
+                build: "never",
+                logLevel: LlamaLogLevel.error,
+                gpu,
+            });
+            let llama;
+            if (gpuMode === false) {
+                llama = await loadLlama(false);
+            }
+            else {
+                try {
+                    llama = await loadLlama(gpuMode);
+                }
+                catch {
+                    llama = await loadLlama(false);
+                }
+            }
+            this.llama = llama;
+            const model = await llama.loadModel({ modelPath });
+            this.model = model;
+            const trained = model.trainContextSize;
+            const contextSize = typeof trained === "number" && Number.isFinite(trained) && trained > 0
+                ? Math.max(1, Math.min(EMBED_CONTEXT_SIZE, trained))
+                : EMBED_CONTEXT_SIZE;
+            this.context = await model.createEmbeddingContext({ contextSize });
+        })();
+        try {
+            await this.loadPromise;
+        }
+        finally {
+            this.loadPromise = null;
+        }
+    }
+    resolveEmbedTokenLimit() {
+        const trained = this.model?.trainContextSize;
+        if (typeof trained === "number" &&
+            Number.isFinite(trained) &&
+            trained > 0) {
+            return Math.max(1, Math.min(EMBED_CONTEXT_SIZE, trained));
+        }
+        return EMBED_CONTEXT_SIZE;
+    }
+    truncateToContextSize(text) {
+        if (!this.model) {
+            return text;
+        }
+        const maxTokens = this.resolveEmbedTokenLimit();
+        if (maxTokens <= 0) {
+            return text;
+        }
+        const tokens = this.model.tokenize(text);
+        if (tokens.length <= maxTokens) {
+            return text;
+        }
+        const safeLimit = Math.max(1, maxTokens - 4);
+        const truncatedTokens = tokens.slice(0, safeLimit);
+        return this.model.detokenize(truncatedTokens);
+    }
+    async embedQuery(query) {
+        await this.ensureLoaded();
+        if (!this.context || !this.model) {
+            throw new Error("LTM embed context not initialized");
+        }
+        const formatted = formatQueryForEmbedding(query, this.modelUri);
+        const safe = this.truncateToContextSize(formatted);
+        const result = await this.context.getEmbeddingFor(safe);
+        return new Float32Array(result.vector);
+    }
+    async embedDocument(content) {
+        await this.ensureLoaded();
+        if (!this.context || !this.model) {
+            throw new Error("LTM embed context not initialized");
+        }
+        const formatted = formatDocForEmbedding(content, undefined, this.modelUri);
+        const safe = this.truncateToContextSize(formatted);
+        const result = await this.context.getEmbeddingFor(safe);
+        return new Float32Array(result.vector);
+    }
+    async dispose() {
+        if (this.context) {
+            await this.context.dispose();
+            this.context = null;
+        }
+        if (this.model) {
+            await this.model.dispose();
+            this.model = null;
+        }
+        this.llama = null;
+    }
+}
+//# sourceMappingURL=llama-embed.js.map

package/dist/core/memory/ltm/llama-embed.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"llama-embed.js","sourceRoot":"","sources":["../../../../src/core/memory/ltm/llama-embed.ts"],"names":[],"mappings":"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"}

package/dist/core/memory/ltm/sqlite.d.ts

@@ -0,0 +1,12 @@
+import Database from "better-sqlite3";
+export type LtmDatabase = Database.Database;
+declare const META_DIMS = "embedding_dims";
+declare const META_MODEL = "embedding_model_id";
+export declare function loadSqliteVecExtension(db: LtmDatabase): void;
+export declare function verifySqliteVecLoaded(db: LtmDatabase): void;
+export declare function openLtmDatabase(path: string): LtmDatabase;
+export declare function getStoreMeta(db: LtmDatabase, key: string): string | null;
+export declare function setStoreMeta(db: LtmDatabase, key: string, value: string): void;
+export declare function ensureVecTable(db: LtmDatabase, dimensions: number): void;
+export declare function persistEmbeddingSchemaMeta(db: LtmDatabase, modelId: string, dimensions: number): void;
+export { META_DIMS, META_MODEL };

package/dist/core/memory/ltm/sqlite.js

@@ -0,0 +1,101 @@
+import Database from "better-sqlite3";
+import * as sqliteVec from "sqlite-vec";
+const META_DIMS = "embedding_dims";
+const META_MODEL = "embedding_model_id";
+export function loadSqliteVecExtension(db) {
+    sqliteVec.load(db);
+}
+export function verifySqliteVecLoaded(db) {
+    try {
+        const row = db.prepare(`SELECT vec_version() AS version`).get();
+        if (!row?.version || typeof row.version !== "string") {
+            throw new Error("vec_version() returned no version");
+        }
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new Error(`sqlite-vec extension is unavailable (probe failed: ${msg}). ` +
+            "Ensure sqlite-vec native bindings are installed for your platform.");
+    }
+}
+function migrateSchema(db) {
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS ltm_memories (
+      id TEXT PRIMARY KEY NOT NULL,
+      user_id TEXT NOT NULL,
+      type TEXT NOT NULL,
+      status TEXT NOT NULL,
+      content TEXT NOT NULL,
+      importance REAL NOT NULL,
+      strength REAL NOT NULL,
+      access_count INTEGER NOT NULL,
+      confidence REAL,
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER,
+      last_accessed_at INTEGER,
+      version INTEGER NOT NULL,
+      source TEXT NOT NULL,
+      tags_json TEXT,
+      entities_json TEXT,
+      related_to_json TEXT,
+      superseded_by TEXT
+    );
+    CREATE INDEX IF NOT EXISTS idx_ltm_user_status ON ltm_memories(user_id, status);
+    CREATE INDEX IF NOT EXISTS idx_ltm_user_type ON ltm_memories(user_id, type);
+
+    CREATE TABLE IF NOT EXISTS ltm_store_meta (
+      key TEXT PRIMARY KEY,
+      value TEXT NOT NULL
+    );
+  `);
+}
+export function openLtmDatabase(path) {
+    const db = new Database(path);
+    db.pragma("journal_mode = WAL");
+    db.pragma("foreign_keys = ON");
+    loadSqliteVecExtension(db);
+    verifySqliteVecLoaded(db);
+    migrateSchema(db);
+    return db;
+}
+export function getStoreMeta(db, key) {
+    const row = db
+        .prepare(`SELECT value FROM ltm_store_meta WHERE key = ?`)
+        .get(key);
+    return row?.value ?? null;
+}
+export function setStoreMeta(db, key, value) {
+    db.prepare(`INSERT INTO ltm_store_meta (key, value) VALUES (?, ?)
+     ON CONFLICT(key) DO UPDATE SET value = excluded.value`).run(key, value);
+}
+export function ensureVecTable(db, dimensions) {
+    const tableInfo = db
+        .prepare(`SELECT sql FROM sqlite_master WHERE type='table' AND name='vectors_vec'`)
+        .get();
+    if (tableInfo) {
+        const match = tableInfo.sql.match(/float\[(\d+)\]/);
+        const hasMemoryId = tableInfo.sql.includes("memory_id");
+        const hasCosine = tableInfo.sql.includes("distance_metric=cosine");
+        const existingDims = match?.[1] ? Number.parseInt(match[1], 10) : null;
+        if (existingDims === dimensions && hasMemoryId && hasCosine) {
+            return;
+        }
+        if (existingDims !== null && existingDims !== dimensions) {
+            throw new Error(`LTM embedding dimension mismatch: existing vectors are ${existingDims}d but the current model produces ${dimensions}d. ` +
+                "Change back to the previous embed model or delete ~/.hooman/ltm.sqlite to rebuild (data loss).");
+        }
+        db.exec("DROP TABLE IF EXISTS vectors_vec");
+    }
+    db.exec(`CREATE VIRTUAL TABLE vectors_vec USING vec0(memory_id TEXT PRIMARY KEY, embedding float[${dimensions}] distance_metric=cosine)`);
+}
+export function persistEmbeddingSchemaMeta(db, modelId, dimensions) {
+    const existingModel = getStoreMeta(db, META_MODEL);
+    if (existingModel != null && existingModel !== modelId) {
+        throw new Error(`LTM database was built with embed model "${existingModel}" but config requests "${modelId}". ` +
+            "Change DEFAULT_LTM_EMBED_MODEL in Hooman or delete ltm.sqlite to rebuild (data loss).");
+    }
+    setStoreMeta(db, META_MODEL, modelId);
+    setStoreMeta(db, META_DIMS, String(dimensions));
+}
+export { META_DIMS, META_MODEL };
+//# sourceMappingURL=sqlite.js.map

package/dist/core/memory/ltm/sqlite.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sqlite.js","sourceRoot":"","sources":["../../../../src/core/memory/ltm/sqlite.ts"],"names":[],"mappings":"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"}

package/dist/core/memory/ltm/store.d.ts

@@ -1,12 +1,19 @@
 import type { ArchiveMemoryInput, LongTermMemoryOptions, LongTermMemoryScope, Memory, SearchMemoryInput, SearchMemoryResult, StoreMemoryInput, StoreMemoryResult, UpdateMemoryInput } from "./types.js";
-import type { Config } from "../../config.js";
+import { type Config } from "../../config.js";
 export declare class LongTermMemoryStore {
-    private readonly config;
     private readonly options;
-    private readonly client;
-    private collectionPromise;
-    constructor(config: Config, options?: LongTermMemoryOptions);
-    private collection;
+    private readonly db;
+    private readonly embedder;
+    constructor(_config: Config, options?: LongTermMemoryOptions);
+    /**
+     * Preload the local embed model so the first memory_search / memory_store call
+     * does not block the LLM turn (otherwise the UI can sit at "thinking" with 0 tokens).
+     */
+    warmup(): Promise<void>;
+    private hasVectorTable;
+    private ensureEmbeddingMeta;
+    private insertMemoryRow;
+    private updateMemoryRow;
     count(scope?: LongTermMemoryScope): Promise<number>;
     get(id: string): Promise<Memory | null>;
     search(input: SearchMemoryInput): Promise<SearchMemoryResult[]>;