@monoes/memory 1.0.3 → 1.0.5

package/dist/tier-manager.d.ts

@@ -1,79 +0,0 @@
-/**
- * TierManager — Routes memory operations to the correct tier (Task 09)
- *
- * Coordinates short-term (in-memory), long-term (persistent backend),
- * entity (JSON-lines KV), and contextual (session summaries) tiers.
- *
- * @module v1/memory/tier-manager
- */
-import type { IMemoryBackend, MemoryEntry, MemoryEntryInput, MemoryTier, TierManagerConfig } from './types.js';
-import { ShortTermMemory } from './tiers/short-term.js';
-import { EntityMemory } from './tiers/entity.js';
-import { ContextualMemory } from './tiers/contextual.js';
-import { PartitionedHNSW, type PartitionedHNSWConfig } from './partitioned-hnsw.js';
-import { DiskAnnBackend, type DiskAnnBackendConfig } from './diskann-backend.js';
-export declare class TierManager {
-    readonly shortTerm: ShortTermMemory;
-    readonly entity: EntityMemory;
-    readonly contextual: ContextualMemory;
-    /** Timestamp-partitioned HNSW for temporally-local semantic search.
-     *  Source: ICDE 2025 Timestamp-Partitioned HNSW */
-    readonly partitionedIndex: PartitionedHNSW;
-    /**
-     * Optional DiskANN backend for large-scale ANN search (Tier 4).
-     * Activated by passing `diskAnnConfig` to the constructor.
-     * Wraps the longTermBackend so all CRUD still flows through the delegate;
-     * `search()` uses the disk-resident graph + quantised beam search.
-     * Source: arXiv:2305.04359
-     */
-    readonly diskann?: DiskAnnBackend;
-    private readonly longTermBackend;
-    private readonly config;
-    constructor(longTermBackend: IMemoryBackend, config?: Partial<TierManagerConfig>, partitionedHNSWConfig?: PartitionedHNSWConfig, diskAnnConfig?: DiskAnnBackendConfig);
-    /**
-     * Store a memory entry, routing to the correct tier.
-     *
-     * - `short-term` goes to the in-memory buffer
-     * - `long-term` (or unspecified) goes to the persistent backend
-     *
-     * All entries are also indexed in the timestamp-partitioned HNSW for
-     * temporally-local search (ICDE 2025).
-     *
-     * Returns the generated entry ID.
-     */
-    store(input: MemoryEntryInput & {
-        tier?: MemoryTier;
-    }): Promise<string>;
-    /**
-     * Merged search across partitioned HNSW, short-term buffer, long-term backend,
-     * and (when configured) DiskANN beam search.
-     *
-     * Order of precedence:
-     *  1. Partitioned HNSW (newest buckets first — temporal locality)
-     *  2. Short-term in-memory buffer
-     *  3. Long-term persistent backend (metadata / hybrid query)
-     *  4. DiskANN ANN search — only when diskAnnConfig was supplied; uses a
-     *     character-frequency proxy embedding as the query vector (approximation)
-     *
-     * Results are deduplicated by entry ID.
-     */
-    search(query: string, limit?: number): Promise<MemoryEntry[]>;
-    /**
-     * Derive a fixed-length Float32 proxy embedding from plain text.
-     *
-     * Maps character byte values into a 128-dimensional L2-normalised vector.
-     * This is NOT a semantic embedding — it is solely used to drive DiskANN
-     * beam traversal when no real embedding generator is available at this
-     * call site.  Quality of DiskANN results improves dramatically when entries
-     * are stored with real semantic embeddings.
-     */
-    private static textToVec;
-    /**
-     * Flush the short-term buffer into the long-term backend.
-     * Promoted entries are also added to the partitioned HNSW index so they
-     * remain visible in partition-based searches after promotion.
-     * Returns the number of entries promoted.
-     */
-    flushShortTerm(): Promise<number>;
-}
-//# sourceMappingURL=tier-manager.d.ts.map

package/dist/tier-manager.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"tier-manager.d.ts","sourceRoot":"","sources":["../src/tier-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EACV,cAAc,EACd,WAAW,EACX,gBAAgB,EAChB,UAAU,EACV,iBAAiB,EAClB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,eAAe,EAAE,KAAK,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AACpF,OAAO,EAAE,cAAc,EAAE,KAAK,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAEjF,qBAAa,WAAW;IACtB,QAAQ,CAAC,SAAS,EAAE,eAAe,CAAC;IACpC,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,UAAU,EAAE,gBAAgB,CAAC;IAEtC;uDACmD;IACnD,QAAQ,CAAC,gBAAgB,EAAE,eAAe,CAAC;IAE3C;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,cAAc,CAAC;IAElC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAiB;IACjD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAoB;gBAGzC,eAAe,EAAE,cAAc,EAC/B,MAAM,GAAE,OAAO,CAAC,iBAAiB,CAAM,EACvC,qBAAqB,GAAE,qBAA0B,EACjD,aAAa,CAAC,EAAE,oBAAoB;IA4BtC;;;;;;;;;;OAUG;IACG,KAAK,CAAC,KAAK,EAAE,gBAAgB,GAAG;QAAE,IAAI,CAAC,EAAE,UAAU,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,CAAC;IAgB7E;;;;;;;;;;;;OAYG;IACG,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,SAAK,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAmD/D;;;;;;;;OAQG;IACH,OAAO,CAAC,MAAM,CAAC,SAAS;IAYxB;;;;;OAKG;IACG,cAAc,IAAI,OAAO,CAAC,MAAM,CAAC;CAUxC"}

package/dist/tier-manager.js

@@ -1,173 +0,0 @@
-/**
- * TierManager — Routes memory operations to the correct tier (Task 09)
- *
- * Coordinates short-term (in-memory), long-term (persistent backend),
- * entity (JSON-lines KV), and contextual (session summaries) tiers.
- *
- * @module v1/memory/tier-manager
- */
-import { createDefaultEntry } from './types.js';
-import { ShortTermMemory } from './tiers/short-term.js';
-import { EntityMemory } from './tiers/entity.js';
-import { ContextualMemory } from './tiers/contextual.js';
-import { PartitionedHNSW } from './partitioned-hnsw.js';
-import { DiskAnnBackend } from './diskann-backend.js';
-export class TierManager {
-    shortTerm;
-    entity;
-    contextual;
-    /** Timestamp-partitioned HNSW for temporally-local semantic search.
-     *  Source: ICDE 2025 Timestamp-Partitioned HNSW */
-    partitionedIndex;
-    /**
-     * Optional DiskANN backend for large-scale ANN search (Tier 4).
-     * Activated by passing `diskAnnConfig` to the constructor.
-     * Wraps the longTermBackend so all CRUD still flows through the delegate;
-     * `search()` uses the disk-resident graph + quantised beam search.
-     * Source: arXiv:2305.04359
-     */
-    diskann;
-    longTermBackend;
-    config;
-    constructor(longTermBackend, config = {}, partitionedHNSWConfig = {}, diskAnnConfig) {
-        this.config = {
-            shortTermCapacity: config.shortTermCapacity ?? 500,
-            entityStorePath: config.entityStorePath ?? './data/memory/entities.jsonl',
-            contextualNamespace: config.contextualNamespace ?? 'contextual-summaries',
-            autoFlushOnSessionEnd: config.autoFlushOnSessionEnd ?? true,
-        };
-        // If diskAnnConfig is supplied, wrap longTermBackend in a DiskAnnBackend.
-        // All CRUD still delegates to the original backend; search() uses DiskANN.
-        if (diskAnnConfig) {
-            const diskannBackend = new DiskAnnBackend(longTermBackend, diskAnnConfig);
-            this.diskann = diskannBackend;
-            this.longTermBackend = diskannBackend;
-        }
-        else {
-            this.longTermBackend = longTermBackend;
-        }
-        this.shortTerm = new ShortTermMemory(this.config.shortTermCapacity);
-        this.entity = new EntityMemory(this.config.entityStorePath);
-        this.contextual = new ContextualMemory(this.longTermBackend, this.config.contextualNamespace);
-        this.partitionedIndex = new PartitionedHNSW(partitionedHNSWConfig);
-    }
-    /**
-     * Store a memory entry, routing to the correct tier.
-     *
-     * - `short-term` goes to the in-memory buffer
-     * - `long-term` (or unspecified) goes to the persistent backend
-     *
-     * All entries are also indexed in the timestamp-partitioned HNSW for
-     * temporally-local search (ICDE 2025).
-     *
-     * Returns the generated entry ID.
-     */
-    async store(input) {
-        const entry = createDefaultEntry(input);
-        const tier = input.tier ?? 'long-term';
-        if (tier === 'short-term') {
-            this.shortTerm.store(entry);
-        }
-        else {
-            await this.longTermBackend.store(entry);
-        }
-        // Index in partitioned HNSW for temporal-locality search
-        this.partitionedIndex.add(entry);
-        return entry.id;
-    }
-    /**
-     * Merged search across partitioned HNSW, short-term buffer, long-term backend,
-     * and (when configured) DiskANN beam search.
-     *
-     * Order of precedence:
-     *  1. Partitioned HNSW (newest buckets first — temporal locality)
-     *  2. Short-term in-memory buffer
-     *  3. Long-term persistent backend (metadata / hybrid query)
-     *  4. DiskANN ANN search — only when diskAnnConfig was supplied; uses a
-     *     character-frequency proxy embedding as the query vector (approximation)
-     *
-     * Results are deduplicated by entry ID.
-     */
-    async search(query, limit = 10) {
-        // 1. Partitioned HNSW — nearest neighbours in recent time buckets first
-        const partitionedResults = this.partitionedIndex.search(null, // no raw embedding at this call-site; uses text fallback
-        query, limit);
-        // 2. Short-term results (synchronous)
-        const shortResults = this.shortTerm.search(query, limit);
-        // 3. Long-term results via the backend query interface
-        const longResults = await this.longTermBackend.query({
-            type: 'hybrid',
-            content: query,
-            limit,
-        });
-        // 4. DiskANN ANN search (activated when diskann is configured)
-        //    Uses a character-frequency proxy embedding to drive beam search.
-        //    Re-ranking in DiskAnnBackend.search() uses the actual stored embeddings.
-        let annEntries = [];
-        if (this.diskann) {
-            try {
-                const proxyVec = TierManager.textToVec(query);
-                const annResults = await this.diskann.search(proxyVec, { k: limit });
-                annEntries = annResults.map(r => r.entry);
-            }
-            catch {
-                // Non-fatal; DiskANN is best-effort
-            }
-        }
-        // Deduplicate by id: partitioned > short-term > long-term > diskann
-        // Iterate each source directly to avoid allocating a combined array and to
-        // enable early-exit between sources once the limit is reached.
-        const seen = new Set();
-        const merged = [];
-        outer: for (const batch of [partitionedResults, shortResults, longResults, annEntries]) {
-            for (const entry of batch) {
-                if (!seen.has(entry.id)) {
-                    seen.add(entry.id);
-                    merged.push(entry);
-                }
-                if (merged.length >= limit)
-                    break outer;
-            }
-        }
-        return merged;
-    }
-    /**
-     * Derive a fixed-length Float32 proxy embedding from plain text.
-     *
-     * Maps character byte values into a 128-dimensional L2-normalised vector.
-     * This is NOT a semantic embedding — it is solely used to drive DiskANN
-     * beam traversal when no real embedding generator is available at this
-     * call site.  Quality of DiskANN results improves dramatically when entries
-     * are stored with real semantic embeddings.
-     */
-    static textToVec(text, dims = 128) {
-        const vec = new Float32Array(dims);
-        for (let i = 0; i < text.length; i++) {
-            vec[i % dims] += text.charCodeAt(i) / 255;
-        }
-        let norm = 0;
-        for (const v of vec)
-            norm += v * v;
-        norm = Math.sqrt(norm) || 1;
-        for (let i = 0; i < dims; i++)
-            vec[i] /= norm;
-        return vec;
-    }
-    /**
-     * Flush the short-term buffer into the long-term backend.
-     * Promoted entries are also added to the partitioned HNSW index so they
-     * remain visible in partition-based searches after promotion.
-     * Returns the number of entries promoted.
-     */
-    async flushShortTerm() {
-        // Snapshot the entries before flush so we can index them afterwards.
-        // ShortTermMemory.flush() clears the buffer, so we must read first.
-        const toPromote = this.shortTerm.snapshot();
-        const count = await this.shortTerm.flush(this.longTermBackend);
-        for (const entry of toPromote) {
-            this.partitionedIndex.add(entry);
-        }
-        return count;
-    }
-}
-//# sourceMappingURL=tier-manager.js.map

package/dist/tier-manager.js.map

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