@monoes/memory 1.0.0

package/dist/episodic-store.js

@@ -0,0 +1,160 @@
+/**
+ * EpisodicStore — JSON-lines file-based episodic memory.
+ *
+ * Stores episodes as one JSON object per line in a .jsonl file,
+ * following the same pattern as CostTracker and SwarmCheckpointer.
+ *
+ * @module v1/memory/episodic-store
+ */
+import { randomUUID } from 'node:crypto';
+import { existsSync, readFileSync, appendFileSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+/** Default summarizer: first 500 chars + ellipsis */
+function defaultSummarizer(content) {
+    const trimmed = content.trim();
+    if (trimmed.length <= 500)
+        return Promise.resolve(trimmed);
+    return Promise.resolve(trimmed.slice(0, 500) + '...');
+}
+/**
+ * Accumulates agent runs into episodes and persists them as JSON-lines.
+ */
+export class EpisodicStore {
+    filePath;
+    maxRunsPerEpisode;
+    summarizer;
+    // Current in-progress episode state
+    currentEpisodeId = null;
+    currentSessionId = '';
+    currentRunIds = [];
+    currentAgentSlugs = new Set();
+    currentTaskTypes = new Set();
+    currentContent = [];
+    currentStartedAt = 0;
+    constructor(config) {
+        this.filePath = config.filePath;
+        this.maxRunsPerEpisode = config.maxRunsPerEpisode ?? 20;
+        this.summarizer = config.summarizer ?? defaultSummarizer;
+        // Ensure parent directory exists
+        const dir = dirname(this.filePath);
+        if (!existsSync(dir)) {
+            mkdirSync(dir, { recursive: true });
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // File helpers
+    // ---------------------------------------------------------------------------
+    /** Read all episodes from the JSONL file (oldest-first). */
+    readAll() {
+        if (!existsSync(this.filePath))
+            return [];
+        const raw = readFileSync(this.filePath, 'utf-8').trim();
+        if (!raw)
+            return [];
+        return raw
+            .split('\n')
+            .filter(Boolean)
+            .map((line) => JSON.parse(line));
+    }
+    /** Append a single episode to the file. */
+    append(episode) {
+        appendFileSync(this.filePath, JSON.stringify(episode) + '\n', 'utf-8');
+    }
+    // ---------------------------------------------------------------------------
+    // Public API
+    // ---------------------------------------------------------------------------
+    /**
+     * Add a run to the current episode. Starts a new episode if none is open.
+     * Auto-closes the episode when maxRunsPerEpisode is reached.
+     *
+     * @returns The closed Episode if auto-close triggered, otherwise null.
+     */
+    async addRun(runId, agentSlug, taskType, content, sessionId) {
+        // Start new episode if needed
+        if (this.currentEpisodeId === null) {
+            this.currentEpisodeId = randomUUID();
+            this.currentSessionId = sessionId ?? '';
+            this.currentRunIds = [];
+            this.currentAgentSlugs = new Set();
+            this.currentTaskTypes = new Set();
+            this.currentContent = [];
+            this.currentStartedAt = Date.now();
+        }
+        // Update session if provided
+        if (sessionId) {
+            this.currentSessionId = sessionId;
+        }
+        this.currentRunIds.push(runId);
+        this.currentAgentSlugs.add(agentSlug);
+        this.currentTaskTypes.add(taskType);
+        this.currentContent.push(content);
+        // Auto-close when limit reached
+        if (this.currentRunIds.length >= this.maxRunsPerEpisode) {
+            return this.closeEpisode();
+        }
+        return null;
+    }
+    /**
+     * Close the current episode, persist it, and return it.
+     * Returns null if there is no open episode.
+     */
+    async closeEpisode() {
+        if (this.currentEpisodeId === null || this.currentRunIds.length === 0) {
+            return null;
+        }
+        const combined = this.currentContent.join('\n');
+        const summary = await this.summarizer(combined);
+        const episode = {
+            episodeId: this.currentEpisodeId,
+            sessionId: this.currentSessionId,
+            runIds: [...this.currentRunIds],
+            summary,
+            startedAt: this.currentStartedAt,
+            endedAt: Date.now(),
+            agentSlugs: [...this.currentAgentSlugs],
+            taskTypes: [...this.currentTaskTypes],
+            tokenEstimate: Math.ceil(combined.length / 4),
+        };
+        this.append(episode);
+        // Reset state
+        this.currentEpisodeId = null;
+        this.currentRunIds = [];
+        this.currentAgentSlugs = new Set();
+        this.currentTaskTypes = new Set();
+        this.currentContent = [];
+        this.currentStartedAt = 0;
+        this.currentSessionId = '';
+        return episode;
+    }
+    /**
+     * Simple substring search on episode summaries.
+     */
+    search(query, maxEpisodes = 10) {
+        const all = this.readAll();
+        const lower = query.toLowerCase();
+        return all
+            .filter((ep) => ep.summary.toLowerCase().includes(lower))
+            .slice(-maxEpisodes);
+    }
+    /**
+     * Retrieve an episode by its ID.
+     */
+    getById(episodeId) {
+        const all = this.readAll();
+        return all.find((ep) => ep.episodeId === episodeId);
+    }
+    /**
+     * List all episodes for a given session.
+     */
+    listBySession(sessionId) {
+        const all = this.readAll();
+        return all.filter((ep) => ep.sessionId === sessionId);
+    }
+    /**
+     * Check whether an episode is currently open.
+     */
+    hasOpenEpisode() {
+        return this.currentEpisodeId !== null && this.currentRunIds.length > 0;
+    }
+}
+//# sourceMappingURL=episodic-store.js.map

package/dist/episodic-store.js.map

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

package/dist/hnsw-index.d.ts

@@ -0,0 +1,111 @@
+/**
+ * V1 HNSW Vector Index
+ *
+ * High-performance Hierarchical Navigable Small World (HNSW) index for
+ * 150x-12,500x faster vector similarity search compared to brute force.
+ *
+ * OPTIMIZATIONS:
+ * - BinaryMinHeap/BinaryMaxHeap for O(log n) operations (vs O(n log n) Array.sort)
+ * - Pre-normalized vectors for O(1) cosine similarity (no sqrt needed)
+ * - Bounded max-heap for efficient top-k tracking
+ *
+ * @module v1/memory/hnsw-index
+ */
+import { EventEmitter } from 'node:events';
+import { HNSWConfig, HNSWStats } from './types.js';
+/**
+ * HNSW Index implementation for ultra-fast vector similarity search
+ *
+ * Performance characteristics:
+ * - Search: O(log n) approximate nearest neighbor
+ * - Insert: O(log n) amortized
+ * - Memory: O(n * M * L) where M is max connections, L is layers
+ */
+export declare class HNSWIndex extends EventEmitter {
+    private config;
+    private nodes;
+    private entryPoint;
+    private maxLevel;
+    private levelMult;
+    private stats;
+    private quantizer;
+    constructor(config?: Partial<HNSWConfig>);
+    /**
+     * Add a vector to the index
+     */
+    addPoint(id: string, vector: Float32Array): Promise<void>;
+    /**
+     * Search for k nearest neighbors
+     */
+    search(query: Float32Array, k: number, ef?: number): Promise<Array<{
+        id: string;
+        distance: number;
+    }>>;
+    /**
+     * Search with filters applied post-retrieval
+     */
+    searchWithFilters(query: Float32Array, k: number, filter: (id: string) => boolean, ef?: number): Promise<Array<{
+        id: string;
+        distance: number;
+    }>>;
+    /**
+     * Remove a point from the index
+     */
+    removePoint(id: string): Promise<boolean>;
+    /**
+     * Rebuild the index from scratch
+     */
+    rebuild(entries: Array<{
+        id: string;
+        vector: Float32Array;
+    }>): Promise<void>;
+    /**
+     * Get index statistics
+     */
+    getStats(): HNSWStats;
+    /**
+     * Clear the index
+     */
+    clear(): void;
+    /**
+     * Check if an ID exists in the index
+     */
+    has(id: string): boolean;
+    /**
+     * Get the number of vectors in the index
+     */
+    get size(): number;
+    private mergeConfig;
+    private getRandomLevel;
+    private insertNode;
+    private searchLayer;
+    /**
+     * OPTIMIZED searchLayer using heap-based priority queues
+     * Performance: O(log n) per operation vs O(n log n) for Array.sort()
+     * Expected speedup: 3-5x for large result sets
+     */
+    private searchLayerOptimized;
+    private selectNeighbors;
+    private pruneConnections;
+    private distance;
+    private cosineDistance;
+    /**
+     * OPTIMIZED: Cosine distance using pre-normalized vectors
+     * Only requires dot product (no sqrt operations)
+     * Performance: O(n) with ~2x speedup over standard cosine
+     */
+    private cosineDistanceNormalized;
+    /**
+     * Normalize a vector to unit length for O(1) cosine similarity
+     */
+    private normalizeVector;
+    /**
+     * OPTIMIZED distance calculation that uses pre-normalized vectors when available
+     */
+    private distanceOptimized;
+    private euclideanDistance;
+    private dotProductDistance;
+    private manhattanDistance;
+}
+export default HNSWIndex;
+//# sourceMappingURL=hnsw-index.d.ts.map

package/dist/hnsw-index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hnsw-index.d.ts","sourceRoot":"","sources":["../src/hnsw-index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAEL,UAAU,EACV,SAAS,EAMV,MAAM,YAAY,CAAC;AAwLpB;;;;;;;GAOG;AACH,qBAAa,SAAU,SAAQ,YAAY;IACzC,OAAO,CAAC,MAAM,CAAa;IAC3B,OAAO,CAAC,KAAK,CAAoC;IACjD,OAAO,CAAC,UAAU,CAAuB;IACzC,OAAO,CAAC,QAAQ,CAAa;IAC7B,OAAO,CAAC,SAAS,CAAS;IAG1B,OAAO,CAAC,KAAK,CAYX;IAGF,OAAO,CAAC,SAAS,CAA0B;gBAE/B,MAAM,GAAE,OAAO,CAAC,UAAU,CAAM;IAU5C;;OAEG;IACG,QAAQ,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAwD/D;;OAEG;IACG,MAAM,CACV,KAAK,EAAE,YAAY,EACnB,CAAC,EAAE,MAAM,EACT,EAAE,CAAC,EAAE,MAAM,GACV,OAAO,CAAC,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAqEnD;;OAEG;IACG,iBAAiB,CACrB,KAAK,EAAE,YAAY,EACnB,CAAC,EAAE,MAAM,EACT,MAAM,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,EAC/B,EAAE,CAAC,EAAE,MAAM,GACV,OAAO,CAAC,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAUnD;;OAEG;IACG,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IA6C/C;;OAEG;IACG,OAAO,CACX,OAAO,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,YAAY,CAAA;KAAE,CAAC,GACnD,OAAO,CAAC,IAAI,CAAC;IAmBhB;;OAEG;IACH,QAAQ,IAAI,SAAS;IAqBrB;;OAEG;IACH,KAAK,IAAI,IAAI;IAab;;OAEG;IACH,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAIxB;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;IAID,OAAO,CAAC,WAAW;IAWnB,OAAO,CAAC,cAAc;YAMR,UAAU;YAmEV,WAAW;IA2DzB;;;;OAIG;IACH,OAAO,CAAC,oBAAoB;IAgE5B,OAAO,CAAC,eAAe;IAavB,OAAO,CAAC,gBAAgB;IA6BxB,OAAO,CAAC,QAAQ;IAehB,OAAO,CAAC,cAAc;IAiBtB;;;;OAIG;IACH,OAAO,CAAC,wBAAwB;IAUhC;;OAEG;IACH,OAAO,CAAC,eAAe;IAmBvB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAkBzB,OAAO,CAAC,iBAAiB;IASzB,OAAO,CAAC,kBAAkB;IAS1B,OAAO,CAAC,iBAAiB;CAO1B;AAwGD,eAAe,SAAS,CAAC"}