@mono-agent/memory 0.4.1

package/dist/search/vector-index.js

@@ -0,0 +1,214 @@
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { MemorySearchError } from "./embeddings.js";
+const DEFAULT_DOCUMENT_PREFIX = "search_document: ";
+const DEFAULT_QUERY_PREFIX = "search_query: ";
+const DEFAULT_BATCH_SIZE = 32;
+/**
+ * A dependency-free embedded vector store: embeddings persisted as JSON Lines,
+ * searched by brute-force cosine similarity. Fast and simple well under ~50k
+ * chunks, which is ample for a single agent's memory; no external vector DB.
+ */
+export class VectorMemoryIndex {
+    path;
+    embeddings;
+    documentPrefix;
+    queryPrefix;
+    batchSize;
+    records = [];
+    loaded = false;
+    constructor(options) {
+        if (typeof options.path !== "string" || options.path.trim().length === 0) {
+            throw new MemorySearchError("invalid_index_options", "Index path must be a non-empty string.");
+        }
+        this.path = resolve(options.path);
+        this.embeddings = options.embeddings;
+        this.documentPrefix = options.documentPrefix ?? DEFAULT_DOCUMENT_PREFIX;
+        this.queryPrefix = options.queryPrefix ?? DEFAULT_QUERY_PREFIX;
+        this.batchSize = options.batchSize ?? DEFAULT_BATCH_SIZE;
+    }
+    /** Replaces the entire index from the supplied chunks (used by consolidation). */
+    async rebuild(chunks) {
+        const deduped = dedupeById(chunks);
+        const vectors = await this.embedAll(deduped.map((chunk) => `${this.documentPrefix}${chunk.text}`));
+        this.records = deduped.map((chunk, index) => toRecord(chunk, vectors[index] ?? []));
+        this.loaded = true;
+        await this.persist();
+        return { indexed: this.records.length };
+    }
+    /** Semantic search by cosine similarity. Throws if embeddings are unavailable. */
+    async search(query, limit = 8, minScore = 0) {
+        await this.ensureLoaded();
+        if (this.records.length === 0 || query.trim().length === 0) {
+            return [];
+        }
+        const [queryVector] = await this.embeddings.embed([`${this.queryPrefix}${query}`]);
+        if (queryVector === undefined) {
+            return [];
+        }
+        const queryNorm = norm(queryVector);
+        if (queryNorm === 0) {
+            return [];
+        }
+        const scored = this.records.map((record) => ({
+            record,
+            score: cosine(queryVector, queryNorm, record.vector, record.norm),
+        }));
+        scored.sort((a, b) => b.score - a.score);
+        return scored
+            .filter((entry) => entry.score > minScore)
+            .slice(0, Math.max(0, limit))
+            .map((entry) => toHit(entry.record, entry.score));
+    }
+    async size() {
+        await this.ensureLoaded();
+        return this.records.length;
+    }
+    async embedAll(texts) {
+        const out = [];
+        for (let start = 0; start < texts.length; start += this.batchSize) {
+            const batch = texts.slice(start, start + this.batchSize);
+            const vectors = await this.embeddings.embed(batch);
+            out.push(...vectors);
+        }
+        return out;
+    }
+    async ensureLoaded() {
+        if (this.loaded) {
+            return;
+        }
+        let raw;
+        try {
+            raw = await readFile(this.path, "utf8");
+        }
+        catch (error) {
+            if (isNodeError(error, "ENOENT")) {
+                this.loaded = true;
+                return;
+            }
+            throw new MemorySearchError("index_read_failed", "Unable to read vector index.", {
+                path: this.path,
+                cause: error instanceof Error ? error.message : String(error),
+            });
+        }
+        const records = [];
+        for (const line of raw.split("\n")) {
+            const trimmed = line.trim();
+            if (trimmed.length === 0) {
+                continue;
+            }
+            let parsed;
+            try {
+                parsed = JSON.parse(trimmed);
+            }
+            catch (error) {
+                throw new MemorySearchError("index_read_failed", "Vector index contains malformed JSON.", {
+                    path: this.path,
+                    cause: error instanceof Error ? error.message : String(error),
+                });
+            }
+            const record = parseRecord(parsed);
+            if (record !== undefined) {
+                records.push(record);
+            }
+        }
+        this.records = records;
+        this.loaded = true;
+    }
+    async persist() {
+        const body = this.records.length === 0
+            ? ""
+            : `${this.records.map((record) => JSON.stringify({
+                id: record.id,
+                source: record.source,
+                ...(record.day === undefined ? {} : { day: record.day }),
+                text: record.text,
+                vector: record.vector,
+            })).join("\n")}\n`;
+        const tmpPath = `${this.path}.tmp`;
+        try {
+            await mkdir(dirname(this.path), { recursive: true });
+            await writeFile(tmpPath, body, "utf8");
+            await rename(tmpPath, this.path);
+        }
+        catch (error) {
+            throw new MemorySearchError("index_write_failed", "Unable to write vector index.", {
+                path: this.path,
+                cause: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+}
+export function createVectorMemoryIndex(options) {
+    return new VectorMemoryIndex(options);
+}
+function dedupeById(chunks) {
+    const byId = new Map();
+    for (const chunk of chunks) {
+        if (chunk.text.trim().length > 0) {
+            byId.set(chunk.id, chunk);
+        }
+    }
+    return [...byId.values()];
+}
+function toRecord(chunk, vector) {
+    return {
+        id: chunk.id,
+        source: chunk.source,
+        ...(chunk.day === undefined ? {} : { day: chunk.day }),
+        text: chunk.text,
+        vector,
+        norm: norm(vector),
+    };
+}
+function toHit(record, score) {
+    return {
+        id: record.id,
+        source: record.source,
+        text: record.text,
+        score,
+        ...(record.day === undefined ? {} : { day: record.day }),
+    };
+}
+function parseRecord(value) {
+    if (typeof value !== "object" || value === null) {
+        return undefined;
+    }
+    const record = value;
+    if (typeof record.id !== "string" || typeof record.source !== "string" || typeof record.text !== "string") {
+        return undefined;
+    }
+    if (!Array.isArray(record.vector) || record.vector.some((component) => typeof component !== "number")) {
+        return undefined;
+    }
+    const vector = record.vector;
+    return {
+        id: record.id,
+        source: record.source,
+        ...(typeof record.day === "string" ? { day: record.day } : {}),
+        text: record.text,
+        vector,
+        norm: norm(vector),
+    };
+}
+function norm(vector) {
+    let sum = 0;
+    for (const component of vector) {
+        sum += component * component;
+    }
+    return Math.sqrt(sum);
+}
+function cosine(a, aNorm, b, bNorm) {
+    if (aNorm === 0 || bNorm === 0 || a.length !== b.length) {
+        return 0;
+    }
+    let dot = 0;
+    for (let index = 0; index < a.length; index += 1) {
+        dot += (a[index] ?? 0) * (b[index] ?? 0);
+    }
+    return dot / (aNorm * bNorm);
+}
+function isNodeError(error, code) {
+    return typeof error === "object" && error !== null && "code" in error && error.code === code;
+}
+//# sourceMappingURL=vector-index.js.map

package/dist/search/vector-index.js.map

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

package/dist/store/contract.d.ts

@@ -0,0 +1,2 @@
+export type { MemoryBlock, MemoryStore, MemoryWriteResult } from "@mono-agent/agent-contracts";
+//# sourceMappingURL=contract.d.ts.map

package/dist/store/contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../../src/store/contract.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC"}

package/dist/store/contract.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=contract.js.map

package/dist/store/contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../../src/store/contract.ts"],"names":[],"mappings":""}

package/dist/store/db.d.ts

@@ -0,0 +1,84 @@
+import { type Database } from "better-sqlite3";
+import { type EntityRecord, type EntityRelationRecord, type MemoryDbOptions, type MemoryStoreStats, type MemoryStoreStatsOptions, type MemoryRecord, type RecallHit, type RecallOptions, type RecallWeights, type SimilarHit } from "./types.js";
+import type { EmbeddingProvider } from "../search/index.js";
+export declare class MemoryDb {
+    protected readonly db: Database;
+    protected readonly embeddings: EmbeddingProvider | undefined;
+    protected readonly dim: number;
+    protected readonly k: number;
+    protected readonly weights: RecallWeights;
+    protected readonly decayGamma: number;
+    protected readonly clock: () => Date;
+    constructor(options: MemoryDbOptions);
+    vecVersion(): string;
+    /** Configured busy_timeout in ms — how long a blocked writer waits before SQLITE_BUSY. */
+    busyTimeoutMs(): number;
+    /**
+     * Guard that an embedding vector matches the configured `dim` before it reaches sqlite-vec.
+     * Surfaces a clear error (e.g. when the embedding model changed but `dim` was left stale) instead
+     * of the opaque sqlite-vec failure on INSERT/MATCH.
+     */
+    protected assertVectorDim(vector: readonly number[], context: string): void;
+    upsert(record: MemoryRecord): Promise<void>;
+    get(id: string): MemoryRecord | undefined;
+    count(): number;
+    stats(options?: MemoryStoreStatsOptions): MemoryStoreStats;
+    recall(query: string, options?: RecallOptions): Promise<RecallHit[]>;
+    protected vectorCandidates(query: string, limit: number): Promise<string[]>;
+    protected keywordCandidates(query: string, limit: number): string[];
+    supersede(oldId: string, replacement: MemoryRecord): Promise<void>;
+    markSuperseded(oldId: string, replacementId: string, at?: string): void;
+    edges(src: string): {
+        src: string;
+        dst: string;
+        kind: string;
+        weight: number;
+    }[];
+    addEdge(src: string, dst: string, kind: "thread" | "about" | "supports" | "supersedes", weight?: number): void;
+    expand(seedIds: readonly string[], hops?: number): MemoryRecord[];
+    findSimilar(text: string, k?: number): Promise<SimilarHit[]>;
+    /**
+     * Wipe the index and rebuild it from the supplied records (used by rebuild-from-files). No LLM.
+     * Wipes ALL index tables — including entities/entity_relations — so the caller is responsible for
+     * repopulating the entity graph afterwards (memory-bujo's rebuildFromMarkdown re-ingests graph.jsonl).
+     * Not atomic across records: the wipe is transactional, but if a re-upsert throws mid-way the index
+     * is left partially rebuilt. Since the index is rebuildable from canonical files, callers should
+     * treat a thrown rebuild as "index dirty — re-run" rather than relying on all-or-nothing semantics.
+     */
+    rebuild(records: readonly MemoryRecord[]): Promise<{
+        indexed: number;
+    }>;
+    protected bumpAccess(ids: readonly string[], now: Date): void;
+    protected nextSeq(id: string): number;
+    protected toRow(record: MemoryRecord, seq: number): Record<string, unknown>;
+    protected fromRow(row: Record<string, unknown>): MemoryRecord;
+    upsertEntity(entity: EntityRecord): void;
+    getEntity(id: string): EntityRecord | undefined;
+    countEntities(): number;
+    /** All entities ordered by name, for index projections. */
+    listEntities(limit?: number): EntityRecord[];
+    addEntityRelation(src: string, dst: string, relation: string): void;
+    relationsFor(src: string): EntityRelationRecord[];
+    protected entityFromRow(row: Record<string, unknown>): EntityRecord;
+    /** Open memories with a due date at/under `now`, soonest first (the future-log queue). */
+    dueItems(now: Date, limit?: number): MemoryRecord[];
+    /** Live, low-salience, old, infrequently-accessed open memories — migration candidates. */
+    agingOpen(now: Date, opts?: {
+        olderThanDays?: number;
+        maxSalience?: number;
+        limit?: number;
+    }): MemoryRecord[];
+    /** Highest-salience live memories (for promotion / always-in-context / index). */
+    topSalient(limit?: number): MemoryRecord[];
+    /** Decay salience toward `floor` by time since last access (half-life in days). Returns count adjusted.
+     *  Frequently-accessed memories (recent last_accessed_at) decay little; stale ones fade toward floor. */
+    applyDecay(now: Date, opts?: {
+        halfLifeDays?: number;
+        floor?: number;
+    }): {
+        decayed: number;
+    };
+    close(): void;
+}
+export declare function openMemoryDb(options: MemoryDbOptions): MemoryDb;
+//# sourceMappingURL=db.d.ts.map

package/dist/store/db.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"db.d.ts","sourceRoot":"","sources":["../../src/store/db.ts"],"names":[],"mappings":"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"}