helixmind 0.1.0

package/dist/storage/database.js

@@ -0,0 +1,141 @@
+import BetterSqlite3 from 'better-sqlite3';
+import { join } from 'node:path';
+import { mkdirSync } from 'node:fs';
+import { logger } from '../utils/logger.js';
+const SCHEMA = `
+CREATE TABLE IF NOT EXISTS nodes (
+  id TEXT PRIMARY KEY,
+  type TEXT NOT NULL,
+  content TEXT NOT NULL,
+  summary TEXT,
+  level INTEGER NOT NULL DEFAULT 1 CHECK(level IN (1, 2, 3, 4, 5)),
+  relevance_score REAL NOT NULL DEFAULT 1.0,
+  token_count INTEGER NOT NULL DEFAULT 0,
+  metadata TEXT NOT NULL DEFAULT '{}',
+  created_at INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL,
+  accessed_at INTEGER NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS edges (
+  id TEXT PRIMARY KEY,
+  source_id TEXT NOT NULL REFERENCES nodes(id) ON DELETE CASCADE,
+  target_id TEXT NOT NULL REFERENCES nodes(id) ON DELETE CASCADE,
+  relation_type TEXT NOT NULL,
+  weight REAL NOT NULL DEFAULT 1.0,
+  metadata TEXT NOT NULL DEFAULT '{}',
+  created_at INTEGER NOT NULL,
+  UNIQUE(source_id, target_id, relation_type)
+);
+
+CREATE INDEX IF NOT EXISTS idx_nodes_type ON nodes(type);
+CREATE INDEX IF NOT EXISTS idx_nodes_level ON nodes(level);
+CREATE INDEX IF NOT EXISTS idx_nodes_relevance ON nodes(relevance_score);
+CREATE INDEX IF NOT EXISTS idx_nodes_updated ON nodes(updated_at);
+CREATE INDEX IF NOT EXISTS idx_nodes_accessed ON nodes(accessed_at);
+CREATE INDEX IF NOT EXISTS idx_edges_source ON edges(source_id);
+CREATE INDEX IF NOT EXISTS idx_edges_target ON edges(target_id);
+CREATE INDEX IF NOT EXISTS idx_edges_type ON edges(relation_type);
+
+CREATE TABLE IF NOT EXISTS schema_version (version INTEGER NOT NULL);
+`;
+export class Database {
+    raw;
+    hasVecExtension;
+    closed = false;
+    constructor(dataDir) {
+        mkdirSync(dataDir, { recursive: true });
+        const dbPath = join(dataDir, 'spiral.db');
+        this.raw = new BetterSqlite3(dbPath);
+        // Performance pragmas
+        this.raw.pragma('journal_mode = WAL');
+        this.raw.pragma('foreign_keys = ON');
+        this.raw.pragma('synchronous = NORMAL');
+        // Try to load sqlite-vec extension
+        this.hasVecExtension = this.tryLoadVecExtension();
+        // Create schema
+        this.raw.exec(SCHEMA);
+        // Run migrations for existing databases with old CHECK constraints
+        this.migrate();
+        logger.debug(`Database opened at ${dbPath} (vec: ${this.hasVecExtension})`);
+    }
+    tryLoadVecExtension() {
+        try {
+            // Dynamic import to avoid crash if sqlite-vec is not installed
+            // eslint-disable-next-line @typescript-eslint/no-require-imports
+            const sqliteVec = require('sqlite-vec');
+            sqliteVec.load(this.raw);
+            logger.info('sqlite-vec extension loaded');
+            return true;
+        }
+        catch {
+            logger.info('sqlite-vec not available, using JS fallback for vector search');
+            return false;
+        }
+    }
+    migrate() {
+        const versionRow = this.raw.prepare("SELECT version FROM schema_version LIMIT 1").get();
+        const currentVersion = versionRow?.version ?? 0;
+        if (currentVersion < 3) {
+            const nodesSql = this.raw.prepare("SELECT sql FROM sqlite_master WHERE type='table' AND name='nodes'").get()?.sql ?? '';
+            // Needs migration if: has old type CHECK, or has 3-level CHECK constraint
+            const needsMigration = nodesSql.includes("CHECK(type IN") ||
+                (nodesSql.includes("CHECK(level IN") && !nodesSql.includes('4, 5'));
+            if (needsMigration) {
+                this.raw.exec('PRAGMA foreign_keys = OFF');
+                this.raw.exec('BEGIN TRANSACTION');
+                try {
+                    this.raw.exec(`
+            ALTER TABLE nodes RENAME TO nodes_old;
+            CREATE TABLE nodes (
+              id TEXT PRIMARY KEY, type TEXT NOT NULL, content TEXT NOT NULL,
+              summary TEXT, level INTEGER NOT NULL DEFAULT 1 CHECK(level IN (1, 2, 3, 4, 5)),
+              relevance_score REAL NOT NULL DEFAULT 1.0,
+              token_count INTEGER NOT NULL DEFAULT 0, metadata TEXT NOT NULL DEFAULT '{}',
+              created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL, accessed_at INTEGER NOT NULL
+            );
+            INSERT INTO nodes SELECT * FROM nodes_old;
+            DROP TABLE nodes_old;
+
+            ALTER TABLE edges RENAME TO edges_old;
+            CREATE TABLE edges (
+              id TEXT PRIMARY KEY,
+              source_id TEXT NOT NULL REFERENCES nodes(id) ON DELETE CASCADE,
+              target_id TEXT NOT NULL REFERENCES nodes(id) ON DELETE CASCADE,
+              relation_type TEXT NOT NULL, weight REAL NOT NULL DEFAULT 1.0,
+              metadata TEXT NOT NULL DEFAULT '{}', created_at INTEGER NOT NULL,
+              UNIQUE(source_id, target_id, relation_type)
+            );
+            INSERT INTO edges SELECT * FROM edges_old;
+            DROP TABLE edges_old;
+
+            CREATE INDEX IF NOT EXISTS idx_nodes_type ON nodes(type);
+            CREATE INDEX IF NOT EXISTS idx_nodes_level ON nodes(level);
+            CREATE INDEX IF NOT EXISTS idx_nodes_relevance ON nodes(relevance_score);
+            CREATE INDEX IF NOT EXISTS idx_nodes_updated ON nodes(updated_at);
+            CREATE INDEX IF NOT EXISTS idx_nodes_accessed ON nodes(accessed_at);
+            CREATE INDEX IF NOT EXISTS idx_edges_source ON edges(source_id);
+            CREATE INDEX IF NOT EXISTS idx_edges_target ON edges(target_id);
+            CREATE INDEX IF NOT EXISTS idx_edges_type ON edges(relation_type);
+          `);
+                    this.raw.exec('COMMIT');
+                }
+                catch (err) {
+                    this.raw.exec('ROLLBACK');
+                    logger.warn(`Migration failed: ${err}`);
+                }
+                this.raw.exec('PRAGMA foreign_keys = ON');
+            }
+            // Set version
+            this.raw.exec('DELETE FROM schema_version');
+            this.raw.prepare('INSERT INTO schema_version (version) VALUES (?)').run(3);
+        }
+    }
+    close() {
+        if (!this.closed) {
+            this.raw.close();
+            this.closed = true;
+        }
+    }
+}
+//# sourceMappingURL=database.js.map

package/dist/storage/database.js.map

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

package/dist/storage/edges.d.ts

@@ -0,0 +1,25 @@
+import type { Database } from './database.js';
+import type { Edge, RelationType } from '../types.js';
+interface CreateEdgeInput {
+    source_id: string;
+    target_id: string;
+    relation_type: RelationType;
+    weight?: number;
+    metadata?: Record<string, unknown>;
+}
+export declare class EdgeStore {
+    private db;
+    constructor(db: Database);
+    create(input: CreateEdgeInput): Edge;
+    getBySource(sourceId: string): Edge[];
+    getByTarget(targetId: string): Edge[];
+    getConnected(nodeId: string): Edge[];
+    /**
+     * Get all node IDs connected to a given node (1-hop neighbors).
+     */
+    getConnectedNodeIds(nodeId: string): string[];
+    count(): number;
+    delete(id: string): void;
+}
+export {};
+//# sourceMappingURL=edges.d.ts.map

package/dist/storage/edges.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"edges.d.ts","sourceRoot":"","sources":["../../src/storage/edges.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,KAAK,EAAE,IAAI,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEtD,UAAU,eAAe;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,YAAY,CAAC;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAwBD,qBAAa,SAAS;IACpB,OAAO,CAAC,EAAE,CAAW;gBAET,EAAE,EAAE,QAAQ;IAIxB,MAAM,CAAC,KAAK,EAAE,eAAe,GAAG,IAAI;IA4BpC,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,EAAE;IAKrC,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,EAAE;IAKrC,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,EAAE;IAKpC;;OAEG;IACH,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE;IAU7C,KAAK,IAAI,MAAM;IAKf,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;CAGzB"}

package/dist/storage/edges.js

@@ -0,0 +1,69 @@
+import { randomUUID } from 'node:crypto';
+function rowToEdge(row) {
+    return {
+        id: row.id,
+        source_id: row.source_id,
+        target_id: row.target_id,
+        relation_type: row.relation_type,
+        weight: row.weight,
+        metadata: JSON.parse(row.metadata),
+        created_at: row.created_at,
+    };
+}
+export class EdgeStore {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    create(input) {
+        const id = randomUUID();
+        const now = Date.now();
+        this.db.raw.prepare(`
+      INSERT INTO edges (id, source_id, target_id, relation_type, weight, metadata, created_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?)
+    `).run(id, input.source_id, input.target_id, input.relation_type, input.weight ?? 1.0, JSON.stringify(input.metadata ?? {}), now);
+        return {
+            id,
+            source_id: input.source_id,
+            target_id: input.target_id,
+            relation_type: input.relation_type,
+            weight: input.weight ?? 1.0,
+            metadata: input.metadata ?? {},
+            created_at: now,
+        };
+    }
+    getBySource(sourceId) {
+        const rows = this.db.raw.prepare('SELECT * FROM edges WHERE source_id = ?').all(sourceId);
+        return rows.map(rowToEdge);
+    }
+    getByTarget(targetId) {
+        const rows = this.db.raw.prepare('SELECT * FROM edges WHERE target_id = ?').all(targetId);
+        return rows.map(rowToEdge);
+    }
+    getConnected(nodeId) {
+        const rows = this.db.raw.prepare('SELECT * FROM edges WHERE source_id = ? OR target_id = ?').all(nodeId, nodeId);
+        return rows.map(rowToEdge);
+    }
+    /**
+     * Get all node IDs connected to a given node (1-hop neighbors).
+     */
+    getConnectedNodeIds(nodeId) {
+        const edges = this.getConnected(nodeId);
+        const ids = new Set();
+        for (const edge of edges) {
+            if (edge.source_id !== nodeId)
+                ids.add(edge.source_id);
+            if (edge.target_id !== nodeId)
+                ids.add(edge.target_id);
+        }
+        return Array.from(ids);
+    }
+    count() {
+        const row = this.db.raw.prepare('SELECT COUNT(*) as cnt FROM edges').get();
+        return row.cnt;
+    }
+    delete(id) {
+        this.db.raw.prepare('DELETE FROM edges WHERE id = ?').run(id);
+    }
+}
+//# sourceMappingURL=edges.js.map

package/dist/storage/edges.js.map

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

package/dist/storage/nodes.d.ts

@@ -0,0 +1,45 @@
+import type { Database } from './database.js';
+import type { ContextNode, ContextType, SpiralLevel, NodeMetadata } from '../types.js';
+interface CreateNodeInput {
+    type: ContextType;
+    content: string;
+    metadata: NodeMetadata;
+    summary?: string;
+    level?: SpiralLevel;
+    relevance_score?: number;
+}
+export declare class NodeStore {
+    private db;
+    constructor(db: Database);
+    create(input: CreateNodeInput): ContextNode;
+    getById(id: string): ContextNode | null;
+    getByLevel(level: SpiralLevel): ContextNode[];
+    getAll(): ContextNode[];
+    getByIds(ids: string[]): ContextNode[];
+    updateLevel(id: string, level: SpiralLevel): void;
+    updateRelevance(id: string, score: number): void;
+    updateSummary(id: string, summary: string): void;
+    count(): number;
+    countByLevel(): Record<SpiralLevel, number>;
+    /** Count web knowledge nodes (L2 nodes with [Web Knowledge: prefix) */
+    countWebKnowledge(): number;
+    getOldestAndNewest(): {
+        oldest: number | null;
+        newest: number | null;
+    };
+    delete(id: string): void;
+    /**
+     * Get nodes that need decay (accessed more than `hours` ago).
+     */
+    getStaleNodes(hoursThreshold: number): ContextNode[];
+    /**
+     * Bulk update relevance scores. Used by decay function.
+     */
+    bulkUpdateRelevance(updates: Array<{
+        id: string;
+        score: number;
+        level: SpiralLevel;
+    }>): void;
+}
+export {};
+//# sourceMappingURL=nodes.d.ts.map

package/dist/storage/nodes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nodes.d.ts","sourceRoot":"","sources":["../../src/storage/nodes.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAGvF,UAAU,eAAe;IACvB,IAAI,EAAE,WAAW,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,YAAY,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAgCD,qBAAa,SAAS;IACpB,OAAO,CAAC,EAAE,CAAW;gBAET,EAAE,EAAE,QAAQ;IAIxB,MAAM,CAAC,KAAK,EAAE,eAAe,GAAG,WAAW;IAqC3C,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI;IAWvC,UAAU,CAAC,KAAK,EAAE,WAAW,GAAG,WAAW,EAAE;IAK7C,MAAM,IAAI,WAAW,EAAE;IAKvB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,WAAW,EAAE;IAOtC,WAAW,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,GAAG,IAAI;IAIjD,eAAe,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAIhD,aAAa,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI;IAIhD,KAAK,IAAI,MAAM;IAKf,YAAY,IAAI,MAAM,CAAC,WAAW,EAAE,MAAM,CAAC;IAS3C,uEAAuE;IACvE,iBAAiB,IAAI,MAAM;IAK3B,kBAAkB,IAAI;QAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE;IAKtE,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAIxB;;OAEG;IACH,aAAa,CAAC,cAAc,EAAE,MAAM,GAAG,WAAW,EAAE;IAMpD;;OAEG;IACH,mBAAmB,CAAC,OAAO,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,WAAW,CAAA;KAAE,CAAC,GAAG,IAAI;CAU7F"}

package/dist/storage/nodes.js

@@ -0,0 +1,124 @@
+import { randomUUID } from 'node:crypto';
+import { estimateTokens } from '../utils/tokens.js';
+function rowToNode(row) {
+    return {
+        id: row.id,
+        type: row.type,
+        content: row.content,
+        summary: row.summary,
+        level: row.level,
+        relevance_score: row.relevance_score,
+        token_count: row.token_count,
+        metadata: JSON.parse(row.metadata),
+        created_at: row.created_at,
+        updated_at: row.updated_at,
+        accessed_at: row.accessed_at,
+    };
+}
+export class NodeStore {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    create(input) {
+        const id = randomUUID();
+        const now = Date.now();
+        const tokenCount = estimateTokens(input.content);
+        this.db.raw.prepare(`
+      INSERT INTO nodes (id, type, content, summary, level, relevance_score, token_count, metadata, created_at, updated_at, accessed_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(id, input.type, input.content, input.summary ?? null, input.level ?? 1, input.relevance_score ?? 1.0, tokenCount, JSON.stringify(input.metadata), now, now, now);
+        return {
+            id,
+            type: input.type,
+            content: input.content,
+            summary: input.summary ?? null,
+            level: (input.level ?? 1),
+            relevance_score: input.relevance_score ?? 1.0,
+            token_count: tokenCount,
+            metadata: input.metadata,
+            created_at: now,
+            updated_at: now,
+            accessed_at: now,
+        };
+    }
+    getById(id) {
+        const row = this.db.raw.prepare('SELECT * FROM nodes WHERE id = ?').get(id);
+        if (!row)
+            return null;
+        // Update accessed_at
+        const now = Date.now();
+        this.db.raw.prepare('UPDATE nodes SET accessed_at = ? WHERE id = ?').run(now, id);
+        return rowToNode({ ...row, accessed_at: now });
+    }
+    getByLevel(level) {
+        const rows = this.db.raw.prepare('SELECT * FROM nodes WHERE level = ? ORDER BY relevance_score DESC').all(level);
+        return rows.map(rowToNode);
+    }
+    getAll() {
+        const rows = this.db.raw.prepare('SELECT * FROM nodes ORDER BY relevance_score DESC').all();
+        return rows.map(rowToNode);
+    }
+    getByIds(ids) {
+        if (ids.length === 0)
+            return [];
+        const placeholders = ids.map(() => '?').join(',');
+        const rows = this.db.raw.prepare(`SELECT * FROM nodes WHERE id IN (${placeholders})`).all(...ids);
+        return rows.map(rowToNode);
+    }
+    updateLevel(id, level) {
+        this.db.raw.prepare('UPDATE nodes SET level = ?, updated_at = ? WHERE id = ?').run(level, Date.now(), id);
+    }
+    updateRelevance(id, score) {
+        this.db.raw.prepare('UPDATE nodes SET relevance_score = ?, updated_at = ? WHERE id = ?').run(score, Date.now(), id);
+    }
+    updateSummary(id, summary) {
+        this.db.raw.prepare('UPDATE nodes SET summary = ?, updated_at = ? WHERE id = ?').run(summary, Date.now(), id);
+    }
+    count() {
+        const row = this.db.raw.prepare('SELECT COUNT(*) as cnt FROM nodes').get();
+        return row.cnt;
+    }
+    countByLevel() {
+        const rows = this.db.raw.prepare('SELECT level, COUNT(*) as cnt FROM nodes GROUP BY level').all();
+        const result = { 1: 0, 2: 0, 3: 0, 4: 0, 5: 0 };
+        for (const row of rows) {
+            result[row.level] = row.cnt;
+        }
+        return result;
+    }
+    /** Count web knowledge nodes (L2 nodes with [Web Knowledge: prefix) */
+    countWebKnowledge() {
+        const row = this.db.raw.prepare("SELECT COUNT(*) as cnt FROM nodes WHERE content LIKE '[Web Knowledge:%'").get();
+        return row.cnt;
+    }
+    getOldestAndNewest() {
+        const row = this.db.raw.prepare('SELECT MIN(created_at) as oldest, MAX(created_at) as newest FROM nodes').get();
+        return { oldest: row.oldest, newest: row.newest };
+    }
+    delete(id) {
+        this.db.raw.prepare('DELETE FROM nodes WHERE id = ?').run(id);
+    }
+    /**
+     * Get nodes that need decay (accessed more than `hours` ago).
+     */
+    getStaleNodes(hoursThreshold) {
+        const cutoff = Date.now() - hoursThreshold * 60 * 60 * 1000;
+        const rows = this.db.raw.prepare('SELECT * FROM nodes WHERE accessed_at < ? AND level < 5 ORDER BY accessed_at ASC').all(cutoff);
+        return rows.map(rowToNode);
+    }
+    /**
+     * Bulk update relevance scores. Used by decay function.
+     */
+    bulkUpdateRelevance(updates) {
+        const stmt = this.db.raw.prepare('UPDATE nodes SET relevance_score = ?, level = ?, updated_at = ? WHERE id = ?');
+        const now = Date.now();
+        const transaction = this.db.raw.transaction((items) => {
+            for (const item of items) {
+                stmt.run(item.score, item.level, now, item.id);
+            }
+        });
+        transaction(updates);
+    }
+}
+//# sourceMappingURL=nodes.js.map

package/dist/storage/nodes.js.map

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

package/dist/storage/vectors.d.ts

@@ -0,0 +1,25 @@
+import type { Database } from './database.js';
+import type { VectorSearchResult } from '../types.js';
+/**
+ * Handles vector storage and similarity search.
+ * Uses sqlite-vec extension when available, falls back to JS-based cosine similarity.
+ */
+export declare class VectorStore {
+    private db;
+    private dimensions;
+    private useVec;
+    constructor(db: Database, dimensions: number);
+    private initialize;
+    private createFallbackTable;
+    store(nodeId: string, embedding: Float32Array): void;
+    search(queryEmbedding: Float32Array, limit: number): VectorSearchResult[];
+    private searchVec;
+    private searchFallback;
+    delete(nodeId: string): void;
+    /**
+     * Computes cosine similarity between two vectors.
+     * Returns value in range [-1, 1] where 1 = identical.
+     */
+    static cosineSimilarity(a: Float32Array, b: Float32Array): number;
+}
+//# sourceMappingURL=vectors.d.ts.map

package/dist/storage/vectors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vectors.d.ts","sourceRoot":"","sources":["../../src/storage/vectors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAGtD;;;GAGG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,EAAE,CAAW;IACrB,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,MAAM,CAAU;gBAEZ,EAAE,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM;IAQ5C,OAAO,CAAC,UAAU;IAoBlB,OAAO,CAAC,mBAAmB;IAS3B,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,YAAY,GAAG,IAAI;IAUpD,MAAM,CAAC,cAAc,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,GAAG,kBAAkB,EAAE;IASzE,OAAO,CAAC,SAAS;IAYjB,OAAO,CAAC,cAAc;IAmBtB,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAQ5B;;;OAGG;IACH,MAAM,CAAC,gBAAgB,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,YAAY,GAAG,MAAM;CAalE"}

package/dist/storage/vectors.js

@@ -0,0 +1,110 @@
+import { logger } from '../utils/logger.js';
+/**
+ * Handles vector storage and similarity search.
+ * Uses sqlite-vec extension when available, falls back to JS-based cosine similarity.
+ */
+export class VectorStore {
+    db;
+    dimensions;
+    useVec;
+    constructor(db, dimensions) {
+        this.db = db;
+        this.dimensions = dimensions;
+        this.useVec = db.hasVecExtension;
+        this.initialize();
+    }
+    initialize() {
+        if (this.useVec) {
+            try {
+                this.db.raw.exec(`
+          CREATE VIRTUAL TABLE IF NOT EXISTS vec_nodes USING vec0(
+            node_id TEXT PRIMARY KEY,
+            embedding float[${this.dimensions}] distance_metric=cosine
+          );
+        `);
+                logger.debug('vec_nodes virtual table created');
+            }
+            catch (err) {
+                logger.warn(`Failed to create vec0 table, using fallback: ${err}`);
+                this.useVec = false;
+                this.createFallbackTable();
+            }
+        }
+        else {
+            this.createFallbackTable();
+        }
+    }
+    createFallbackTable() {
+        this.db.raw.exec(`
+      CREATE TABLE IF NOT EXISTS embeddings (
+        node_id TEXT PRIMARY KEY,
+        embedding BLOB NOT NULL
+      );
+    `);
+    }
+    store(nodeId, embedding) {
+        const buffer = Buffer.from(embedding.buffer, embedding.byteOffset, embedding.byteLength);
+        if (this.useVec) {
+            this.db.raw.prepare('INSERT OR REPLACE INTO vec_nodes (node_id, embedding) VALUES (?, ?)').run(nodeId, buffer);
+        }
+        else {
+            this.db.raw.prepare('INSERT OR REPLACE INTO embeddings (node_id, embedding) VALUES (?, ?)').run(nodeId, buffer);
+        }
+    }
+    search(queryEmbedding, limit) {
+        const buffer = Buffer.from(queryEmbedding.buffer, queryEmbedding.byteOffset, queryEmbedding.byteLength);
+        if (this.useVec) {
+            return this.searchVec(buffer, limit);
+        }
+        return this.searchFallback(queryEmbedding, limit);
+    }
+    searchVec(queryBuffer, limit) {
+        const rows = this.db.raw.prepare(`
+      SELECT node_id, distance
+      FROM vec_nodes
+      WHERE embedding MATCH ?
+        AND k = ?
+      ORDER BY distance
+    `).all(queryBuffer, limit);
+        return rows.map(r => ({ node_id: r.node_id, distance: r.distance }));
+    }
+    searchFallback(queryEmbedding, limit) {
+        const rows = this.db.raw.prepare('SELECT node_id, embedding FROM embeddings').all();
+        const results = rows.map(row => {
+            const stored = new Float32Array(row.embedding.buffer, row.embedding.byteOffset, row.embedding.byteLength / 4);
+            const similarity = VectorStore.cosineSimilarity(queryEmbedding, stored);
+            // Convert similarity (1=identical) to distance (0=identical) for consistent API
+            return { node_id: row.node_id, distance: 1 - similarity };
+        });
+        return results
+            .sort((a, b) => a.distance - b.distance)
+            .slice(0, limit);
+    }
+    delete(nodeId) {
+        if (this.useVec) {
+            this.db.raw.prepare('DELETE FROM vec_nodes WHERE node_id = ?').run(nodeId);
+        }
+        else {
+            this.db.raw.prepare('DELETE FROM embeddings WHERE node_id = ?').run(nodeId);
+        }
+    }
+    /**
+     * Computes cosine similarity between two vectors.
+     * Returns value in range [-1, 1] where 1 = identical.
+     */
+    static cosineSimilarity(a, b) {
+        let dot = 0;
+        let normA = 0;
+        let normB = 0;
+        for (let i = 0; i < a.length; i++) {
+            dot += a[i] * b[i];
+            normA += a[i] * a[i];
+            normB += b[i] * b[i];
+        }
+        const denominator = Math.sqrt(normA) * Math.sqrt(normB);
+        if (denominator === 0)
+            return 0;
+        return dot / denominator;
+    }
+}
+//# sourceMappingURL=vectors.js.map

package/dist/storage/vectors.js.map

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

package/dist/tools/spiral-compact.d.ts

@@ -0,0 +1,14 @@
+import { z } from 'zod';
+import type { SpiralEngine } from '../spiral/engine.js';
+export declare const spiralCompactSchema: {
+    aggressive: z.ZodOptional<z.ZodBoolean>;
+};
+export declare function handleSpiralCompact(engine: SpiralEngine, args: {
+    aggressive?: boolean;
+}): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;
+//# sourceMappingURL=spiral-compact.d.ts.map

package/dist/tools/spiral-compact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spiral-compact.d.ts","sourceRoot":"","sources":["../../src/tools/spiral-compact.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAExD,eAAO,MAAM,mBAAmB;;CAE/B,CAAC;AAEF,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,YAAY,EACpB,IAAI,EAAE;IAAE,UAAU,CAAC,EAAE,OAAO,CAAA;CAAE;;;;;GAU/B"}

package/dist/tools/spiral-compact.js

@@ -0,0 +1,14 @@
+import { z } from 'zod';
+export const spiralCompactSchema = {
+    aggressive: z.boolean().optional().describe('If true, more aggressive compaction thresholds'),
+};
+export async function handleSpiralCompact(engine, args) {
+    const result = engine.compact(args.aggressive ?? false);
+    return {
+        content: [{
+                type: 'text',
+                text: JSON.stringify(result, null, 2),
+            }],
+    };
+}
+//# sourceMappingURL=spiral-compact.js.map

package/dist/tools/spiral-compact.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spiral-compact.js","sourceRoot":"","sources":["../../src/tools/spiral-compact.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC,UAAU,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,gDAAgD,CAAC;CAC9F,CAAC;AAEF,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,MAAoB,EACpB,IAA8B;IAE9B,MAAM,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,UAAU,IAAI,KAAK,CAAC,CAAC;IAExD,OAAO;QACL,OAAO,EAAE,CAAC;gBACR,IAAI,EAAE,MAAe;gBACrB,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;aACtC,CAAC;KACH,CAAC;AACJ,CAAC"}

package/dist/tools/spiral-query.d.ts

@@ -0,0 +1,18 @@
+import { z } from 'zod';
+import type { SpiralEngine } from '../spiral/engine.js';
+export declare const spiralQuerySchema: {
+    query: z.ZodString;
+    max_tokens: z.ZodOptional<z.ZodNumber>;
+    levels: z.ZodOptional<z.ZodArray<z.ZodNumber, "many">>;
+};
+export declare function handleSpiralQuery(engine: SpiralEngine, args: {
+    query: string;
+    max_tokens?: number;
+    levels?: number[];
+}): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+}>;
+//# sourceMappingURL=spiral-query.d.ts.map

package/dist/tools/spiral-query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spiral-query.d.ts","sourceRoot":"","sources":["../../src/tools/spiral-query.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAExD,eAAO,MAAM,iBAAiB;;;;CAI7B,CAAC;AAEF,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,YAAY,EACpB,IAAI,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE;;;;;GAUhE"}