tsunami-memory 1.0.1 → 1.0.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tsunami-memory",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "TSUNAMI — Bun-native oceanic memory system with basin/current flow, storm center, hot+cold retrieval, knowledge graph sync, and evidence linking.",
   "main": "src/index.ts",
   "files": [

package/server/api.ts

@@ -89,6 +89,18 @@ const server = Bun.serve({
         return json({ ok: true, timeline: result }, cors);
       }
 
+      // ── POST /search/semantic ────────────────────────
+      if (url.pathname === '/search/semantic' && req.method === 'POST') {
+        const body = await req.json().catch(() => ({}));
+        const { embedding, wing, limit } = body;
+        if (!Array.isArray(embedding) || embedding.length === 0) {
+          return json({ error: 'embedding vector required (number[])' }, cors, 400);
+        }
+        const store = await import('../src/bun_memory_store');
+        const results = store.searchByVector(embedding, limit || 5, wing);
+        return json({ ok: true, results }, cors);
+      }
+
       // ── POST /diary ─────────────────────────────────
       if (url.pathname === '/diary' && req.method === 'POST') {
         const body = await req.json().catch(() => ({}));
@@ -103,7 +115,7 @@ const server = Bun.serve({
         return json({
           service: 'TSUNAMI Memory API',
           version: '1.0.0',
-          endpoints: ['/health', '/add', '/search', '/recall', '/storm', '/status', '/timeline', '/diary'],
+          endpoints: ['/health', '/add', '/search', '/search/semantic', '/recall', '/storm', '/status', '/timeline', '/diary'],
         }, cors);
       }
 

package/server/mcp.ts

@@ -113,6 +113,19 @@ const TOOLS = [
       required: ['entry'],
     },
   },
+  {
+    name: 'tsunami_search_semantic',
+    description: 'Search memories by embedding vector similarity. The caller must provide a pre-computed embedding (e.g. from OpenAI / ollama / local model). Returns top-K results ranked by cosine similarity.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        embedding: { type: 'array', items: { type: 'number' }, description: 'Pre-computed embedding vector (float array)' },
+        wing: { type: 'string', description: 'Filter by wing/basin' },
+        limit: { type: 'number', description: 'Max results (default: 5)', default: 5 },
+      },
+      required: ['embedding'],
+    },
+  },
   {
     name: 'tsunami_wings',
     description: 'List all available memory wings/basins and their memory counts.',
@@ -164,6 +177,15 @@ async function handleTool(name: string, args: Record<string, any>): Promise<any>
     case 'tsunami_diary':
       return { result: await client.tsunamiDiary(args.entry, args.agent || 'external', args.wing || 'diary', 3) };
 
+    case 'tsunami_search_semantic': {
+      if (!Array.isArray(args.embedding) || args.embedding.length === 0) {
+        throw new Error('embedding vector required');
+      }
+      const store = await import('../src/bun_memory_store');
+      const results = store.searchByVector(args.embedding, args.limit || 5, args.wing);
+      return { results };
+    }
+
     case 'tsunami_wings': {
       const wings = await client.tsunamiListWings();
       return { wings };

package/src/bun_memory_store.ts

@@ -5,36 +5,10 @@
  * and content fingerprinting for deduplication. Schema managed by migration runner.
  */
 
-import { Database } from 'bun:sqlite';
-import { existsSync, mkdirSync } from 'fs';
-import { dirname } from 'path';
+import { getDb } from './db';
 import { BUN_MEMORY_DB_PATH } from './tsunami_storage_paths';
-import { runMigrations, getMigrations } from './migration';
 export { BUN_MEMORY_DB_PATH };
 
-// ── Database initialization ──────────────────────────────────
-
-function ensureDbDir(): void {
-  const dir = dirname(BUN_MEMORY_DB_PATH);
-  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
-}
-
-let _db: Database | null = null;
-
-function getDb(): Database {
-  if (_db) return _db;
-  ensureDbDir();
-  _db = new Database(BUN_MEMORY_DB_PATH);
-  _db.run('PRAGMA journal_mode = WAL');
-  const applied = runMigrations(_db, getMigrations());
-  if (applied > 0) {
-    // First-run or upgrade — log for observability
-    const v = (_db.prepare('SELECT MAX(version) as v FROM schema_version').get() as any)?.v ?? 0;
-    console.log(`[TSUNAMI] migrations applied: ${applied}, now at v${v}`);
-  }
-  return _db;
-}
-
 // ── ID Generation ────────────────────────────────────────────
 
 function generateId(): string {
@@ -327,6 +301,102 @@ export function deleteBunMemoryEntry(id: string): boolean {
   return result.changes > 0;
 }
 
+// ── Vector / Semantic Search ─────────────────────────────────
+
+/** Store a memory with an embedding vector for semantic search. */
+export function addWithEmbedding(
+  wing: string,
+  room: string,
+  content: string,
+  importance: number,
+  embedding: number[],
+): string {
+  const id = generateId();
+  const now = Date.now();
+  const blob = Buffer.from(new Float32Array(embedding).buffer);
+
+  getDb().prepare(`
+    INSERT INTO memory_entries (id, wing, room, content, importance, source, embedding, created_at, updated_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(
+    id,
+    wing || 'general',
+    room || 'inbox',
+    content,
+    Math.min(5, Math.max(1, importance ?? 3)),
+    'embedding',
+    blob as any, // Buffer is valid SQLite BLOB but bun:sqlite types don't recognize it
+    now,
+    now,
+  );
+  return id;
+}
+
+function cosineSimilarity(a: number[], b: number[]): number {
+  if (a.length !== b.length || a.length === 0) return 0;
+  let dot = 0, normA = 0, 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 denom = Math.sqrt(normA) * Math.sqrt(normB);
+  return denom === 0 ? 0 : dot / denom;
+}
+
+function blobToArray(blob: unknown): number[] | null {
+  if (!blob) return null;
+  try {
+    // bun:sqlite returns BLOBs as Uint8Array; Node better-sqlite3 returns Buffer
+    if (blob instanceof Uint8Array) {
+      return Array.from(new Float32Array(blob.buffer.slice(blob.byteOffset, blob.byteOffset + blob.byteLength)));
+    }
+    if (Buffer.isBuffer(blob)) {
+      return Array.from(new Float32Array(blob.buffer.slice(blob.byteOffset, blob.byteOffset + blob.byteLength)));
+    }
+    if (blob instanceof ArrayBuffer) {
+      return Array.from(new Float32Array(blob));
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/** Search memories by vector similarity. Returns top-K with similarity scores. */
+export function searchByVector(
+  embedding: number[],
+  topK = 5,
+  wing?: string,
+): Array<{ id: string; wing: string; room: string; content: string; similarity: number }> {
+  const db = getDb();
+  let sql = 'SELECT id, wing, room, content, embedding FROM memory_entries WHERE embedding IS NOT NULL';
+  const params: any[] = [];
+  if (wing) { sql += ' AND wing = ?'; params.push(wing); }
+  sql += ' ORDER BY created_at DESC LIMIT 500';
+
+  const rows = db.prepare(sql).all(...params) as Array<{
+    id: string; wing: string; room: string; content: string; embedding: unknown;
+  }>;
+
+  const scored = rows
+    .map(row => {
+      const vec = blobToArray(row.embedding);
+      if (!vec) return null;
+      return {
+        id: row.id,
+        wing: row.wing,
+        room: row.room,
+        content: row.content,
+        similarity: Number(cosineSimilarity(embedding, vec).toFixed(4)),
+      };
+    })
+    .filter((r): r is NonNullable<typeof r> => r !== null && r.similarity > 0.3)
+    .sort((a, b) => b.similarity - a.similarity);
+
+  return scored.slice(0, Math.max(1, topK));
+}
+
 export function buildBunMemoryPreview(row: BunMemoryRow, maxLen: number): string {
   const text = String(row.content ?? '').replace(/\s+/g, ' ').trim();
   if (!text) return '';

package/src/db.ts

@@ -0,0 +1,41 @@
+/**
+ * TSUNAMI shared database connection.
+ *
+ * Single WAL-mode SQLite connection shared by all modules.
+ * Schema is managed by the migration runner.
+ */
+
+import { Database } from 'bun:sqlite';
+import { existsSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { BUN_MEMORY_DB_PATH } from './tsunami_storage_paths';
+import { runMigrations, getMigrations } from './migration';
+
+let _db: Database | null = null;
+
+/** Get or create the shared database connection. Thread-safe via module-level singleton. */
+export function getDb(): Database {
+  if (_db) return _db;
+
+  const dir = dirname(BUN_MEMORY_DB_PATH);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+
+  _db = new Database(BUN_MEMORY_DB_PATH);
+  _db.run('PRAGMA journal_mode = WAL');
+
+  const applied = runMigrations(_db, getMigrations());
+  if (applied > 0) {
+    const v = (_db.prepare('SELECT MAX(version) as v FROM schema_version').get() as any)?.v ?? 0;
+    console.log(`[TSUNAMI] migrations applied: ${applied}, now at v${v}`);
+  }
+
+  return _db;
+}
+
+/** Close the database connection. Mainly useful in tests. */
+export function closeDb(): void {
+  if (_db) {
+    _db.close();
+    _db = null;
+  }
+}

package/src/migration.ts

@@ -157,7 +157,16 @@ const v1_initial_schema: Migration = {
   },
 };
 
+/** v2 — Add embedding column for vector search. */
+const v2_add_embedding_column: Migration = {
+  version: 2,
+  name: 'add_embedding_column',
+  up(db) {
+    db.run(`ALTER TABLE memory_entries ADD COLUMN embedding BLOB`);
+  },
+};
+
 /** All migrations in version order. Add new entries at the end. */
 export function getMigrations(): Migration[] {
-  return [v1_initial_schema];
+  return [v1_initial_schema, v2_add_embedding_column];
 }

package/src/tsunami_bun_backend.ts

@@ -3,6 +3,7 @@ import { dirname } from 'path';
 
 import {
   BUN_MEMORY_DB_PATH,
+  addWithEmbedding,
   buildBunMemoryPreview,
   checkBunMemoryDuplicate,
   countBunMemoryEntries,
@@ -15,6 +16,7 @@ import {
   listBunMemoryWingCounts,
   recallBunMemoryRows,
   searchBunMemoryRows,
+  searchByVector,
   wakeBunMemoryRows,
 } from './bun_memory_store';
 import {
@@ -701,5 +703,28 @@ export function tryHandleTsunamiBunRequest(req: Record<string, unknown>): any |
     };
   }
 
+  if (cmd === 'add_embedding') {
+    const embedding = Array.isArray(req.embedding) ? (req.embedding as number[]) : [];
+    if (embedding.length === 0) {
+      return { ok: false, error: 'embedding vector required (number[])', __backend: 'bun_native' };
+    }
+    const id = addWithEmbedding(
+      wing || 'general', room || 'inbox',
+      String(req.content ?? '').trim(),
+      Number(req.importance ?? 3),
+      embedding,
+    );
+    return { ok: true, id, __backend: 'bun_native' };
+  }
+
+  if (cmd === 'search_vector') {
+    const vector = Array.isArray(req.embedding) ? (req.embedding as number[]) : [];
+    if (vector.length === 0) {
+      return { ok: false, error: 'embedding vector required for search_vector', __backend: 'bun_native' };
+    }
+    const results = searchByVector(vector, Number(req.limit ?? 5), wing || undefined);
+    return { ok: true, results, __backend: 'bun_native' };
+  }
+
   return null;
 }

package/src/tsunami_graph_runtime.ts

@@ -6,21 +6,7 @@
  * BFS traversal, and cross-wing tunnel discovery.
  */
 
-import { Database } from 'bun:sqlite';
-import { BUN_MEMORY_DB_PATH } from './tsunami_storage_paths';
-import { runMigrations, getMigrations } from './migration';
-
-// ── Database initialization ──────────────────────────────────
-
-let _db: Database | null = null;
-
-function getDb(): Database {
-  if (_db) return _db;
-  _db = new Database(BUN_MEMORY_DB_PATH);
-  _db.run('PRAGMA journal_mode = WAL');
-  runMigrations(_db, getMigrations()); // idempotent — applies only pending
-  return _db;
-}
+import { getDb } from './db';
 
 // ── ID Generation ────────────────────────────────────────────
 

package/src/tsunami_routing.ts

@@ -44,6 +44,8 @@ export const TSUNAMI_BUN_NATIVE_CMDS = [
   'traverse_graph',
   'find_tunnels',
   'graph_stats',
+  'add_embedding',
+  'search_vector',
 ] as const;
 
 export const TSUNAMI_WRAPPER_BRIDGE_CMDS = [] as const;