tsunami-memory 1.0.0

package/src/core/project_state.ts

@@ -0,0 +1,88 @@
+/**
+ * TSUNAMI project state stubs
+ *
+ * Provides project-level state queries for the storm center.
+ * Returns null/empty defaults; the storm center handles these gracefully.
+ */
+
+export interface ProjectTaskThread {
+  id: string;
+  title: string;
+  status: string;
+  summary?: string;
+  nextStep?: string;
+  featureId?: string;
+}
+
+export interface ProjectHandoffRecord {
+  id: string;
+  task: string;
+  summary?: string;
+  nextStep?: string;
+  progressStatus?: string;
+  progressFeatureId?: string;
+}
+
+export interface ProjectStateStatus {
+  activeFeature?: {
+    id?: string;
+    title?: string;
+    status?: string;
+    detail?: string;
+  } | null;
+}
+
+export interface ProjectWikiPage {
+  pageId: string;
+  title: string;
+  summary: string;
+  confidence: number;
+  tags: string[];
+  sourceRefs: string[];
+  updatedAt: number;
+}
+
+export interface ProjectWikiEvidence {
+  snippetId: string;
+  pageId: string;
+  title: string;
+  sourcePath: string;
+  sourceRef: string;
+  quote: string;
+  tags: string[];
+}
+
+export interface ProjectWikiQueryResult {
+  evidence: ProjectWikiEvidence[];
+}
+
+export function getProjectStateStatus(_projectDir: string): ProjectStateStatus {
+  return { activeFeature: null };
+}
+
+export function resolveProjectTaskThread(
+  _projectDir: string,
+  _query: string,
+  _limit?: number,
+): { thread: ProjectTaskThread | null; match: string | null } {
+  return { thread: null, match: null };
+}
+
+export function getProjectLatestHandoff(
+  _projectDir: string,
+  _opts?: { sessionId?: string; featureId?: string },
+): ProjectHandoffRecord | null {
+  return null;
+}
+
+export function listProjectWikiPages(_projectDir: string, _limit?: number): ProjectWikiPage[] {
+  return [];
+}
+
+export function queryProjectWiki(
+  _projectDir: string,
+  _query: string,
+  _limit?: number,
+): ProjectWikiQueryResult {
+  return { evidence: [] };
+}

package/src/index.ts

@@ -0,0 +1,54 @@
+/**
+ * TSUNAMI Memory System — Public API
+ *
+ * Bun-native oceanic memory with basin/current flow, storm center,
+ * hot+cold retrieval, knowledge graph sync, and evidence linking.
+ *
+ * Usage:
+ *   import { tsunamiSearch, tsunamiAdd, tsunamiStatus } from 'tsunami-memory';
+ * */
+
+// ── Core Memory Operations ──────────────────────────────────
+export {
+  tsunamiAdd,
+  tsunamiSearch,
+  tsunamiRecall,
+  tsunamiWakeUp,
+  tsunamiDiary,
+  tsunamiStatus,
+  tsunamiTimeline,
+  tsunamiListWings,
+} from './tsunami_client';
+
+// ── Knowledge Graph ────────────────────────────────────────
+export {
+  tsunamiKgQuery,
+  tsunamiKgAdd,
+  tsunamiKgAddTyped,
+  tsunamiKgStats,
+  tsunamiKgTimeline,
+} from './tsunami_client';
+
+// ── Storm Center ────────────────────────────────────────────
+export {
+  buildTsunamiStormCenter,
+  formatTsunamiStormCenterText,
+} from './tsunami_storm_center';
+
+// ── Execution Gate ──────────────────────────────────────────
+export {
+  buildTsunamiExecutionGate,
+  deriveTsunamiLoopStepLimit,
+  applyTsunamiExecutionGateToTool,
+  formatTsunamiExecutionGateSummary,
+} from './tsunami_execution_gate';
+
+// ── Classification & Routing ────────────────────────────────
+export { classifyMemory } from './tsunami_classifier';
+
+// ── Types ───────────────────────────────────────────────────
+export type { TsunamiBasin, TsunamiCurrent } from './tsunami_schema';
+export type { TsunamiStormCenter } from './tsunami_storm_center';
+export type { TsunamiExecutionGate } from './tsunami_execution_gate';
+
+export type { TsunamiAddOptions } from './tsunami_client';

package/src/legacy_compat/tsunami_compat.ts

@@ -0,0 +1,22 @@
+/**
+ * TSUNAMI legacy compatibility stubs
+ *
+ * @deprecated These stubs exist to preserve compile-time compatibility with code
+ * extracted from a larger Python-based monorepo. They provide fallback/opt-in paths
+ * that are disabled by default. Scheduled for removal in v2.0.
+ */
+
+export const TSUNAMI_COMPAT_WRAPPER = '';
+export const TSUNAMI_DEFAULT_LEGACY_ROOM = 'ats/general';
+
+export function normalizeTsunamiCompatRoom(room: string): string {
+  return String(room || TSUNAMI_DEFAULT_LEGACY_ROOM).trim().toLowerCase().replace(/\s+/g, '_');
+}
+
+export function isTsunamiLegacyWrapperExplicitlyEnabled(_req: Record<string, unknown>): boolean {
+  return false;
+}
+
+export function listTsunamiCompatPythonCandidates(): string[] {
+  return ['python3', 'python'];
+}

package/src/legacy_compat/tsunami_legacy_identity.ts

@@ -0,0 +1,13 @@
+/**
+ * TSUNAMI legacy identity stub
+ *
+ * Provides legacy identity text replacements and detection.
+ * All replacements are empty by default; the Bun-native runtime
+ * handles identity normalization directly.
+ */
+
+export const TSUNAMI_LEGACY_IDENTITY_REPLACEMENTS: Array<[RegExp, string]> = [];
+
+export function hasTsunamiLegacyIdentityTerms(_raw: string): boolean {
+  return false;
+}

package/src/legacy_compat/tsunami_legacy_taxonomy.ts

@@ -0,0 +1,197 @@
+/**
+ * TSUNAMI legacy taxonomy mapping
+ *
+ * Maps legacy wing/room identifiers to the current basin/current taxonomy.
+ *
+ * Legacy wings are mapped as follows:
+ *   ats      -> epicenter  (core identity, memory operations)
+ *   brain    -> surface    (model, tools, architecture)
+ *   decision -> faultline  (choices, direction, strategy)
+ *   memory   -> abyss      (deep storage, retrieval, compression)
+ *   task     -> surge      (execution, projects, routines)
+ *   people   -> harbor     (users, partners, team)
+ */
+
+export const TSUNAMI_LEGACY_TAXONOMY_ENTRIES = [
+  // --- epicenter (legacy: ats) ---
+  {
+    legacyWing: 'ats',
+    legacyRoom: 'ats/signature',
+    basin: 'epicenter',
+    current: 'epicenter/signature',
+    description: 'Core identity signature and positioning',
+  },
+  {
+    legacyWing: 'ats',
+    legacyRoom: 'ats/crest',
+    basin: 'epicenter',
+    current: 'epicenter/crest',
+    description: 'Peak identity states and high-confidence role affirmations',
+  },
+  {
+    legacyWing: 'ats',
+    legacyRoom: 'ats/law',
+    basin: 'epicenter',
+    current: 'epicenter/law',
+    description: 'Immutable rules, principles, and hard boundaries',
+  },
+  // --- surface (legacy: brain) ---
+  {
+    legacyWing: 'brain',
+    legacyRoom: 'brain/bridge',
+    basin: 'surface',
+    current: 'surface/bridge',
+    description: 'Model provider bridge and engine configuration',
+  },
+  {
+    legacyWing: 'brain',
+    legacyRoom: 'brain/helm',
+    basin: 'surface',
+    current: 'surface/helm',
+    description: 'Active control plane, execution loop, and orchestration',
+  },
+  {
+    legacyWing: 'brain',
+    legacyRoom: 'brain/rigging',
+    basin: 'surface',
+    current: 'surface/rigging',
+    description: 'Tool rigging, registration, and executor wiring',
+  },
+  {
+    legacyWing: 'brain',
+    legacyRoom: 'brain/hull',
+    basin: 'surface',
+    current: 'surface/hull',
+    description: 'Architecture, modules, and structural integrity',
+  },
+  {
+    legacyWing: 'brain',
+    legacyRoom: 'brain/chart',
+    basin: 'surface',
+    current: 'surface/chart',
+    description: 'Directory layout, paths, and project navigation',
+  },
+  {
+    legacyWing: 'brain',
+    legacyRoom: 'brain/echo',
+    basin: 'surface',
+    current: 'surface/echo',
+    description: 'TTS, voice, audio, and speech synthesis',
+  },
+  // --- faultline (legacy: decision) ---
+  {
+    legacyWing: 'decision',
+    legacyRoom: 'decision/choice',
+    basin: 'faultline',
+    current: 'faultline/choice',
+    description: 'Technical decisions, architecture selection, and approach finalization',
+  },
+  {
+    legacyWing: 'decision',
+    legacyRoom: 'decision/course',
+    basin: 'faultline',
+    current: 'faultline/course',
+    description: 'Strategic direction, priorities, and product decisions',
+  },
+  {
+    legacyWing: 'decision',
+    legacyRoom: 'decision/drift',
+    basin: 'faultline',
+    current: 'faultline/drift',
+    description: 'Conflicts, abandoned approaches, and course corrections',
+  },
+  // --- abyss (legacy: memory) ---
+  {
+    legacyWing: 'memory',
+    legacyRoom: 'memory/archive',
+    basin: 'abyss',
+    current: 'abyss/archive',
+    description: 'Long-term memory storage, compression, and archival',
+  },
+  {
+    legacyWing: 'memory',
+    legacyRoom: 'memory/mesh',
+    basin: 'abyss',
+    current: 'abyss/mesh',
+    description: 'Knowledge graph, relationships, and semantic connections',
+  },
+  {
+    legacyWing: 'memory',
+    legacyRoom: 'memory/wake',
+    basin: 'abyss',
+    current: 'abyss/wake',
+    description: 'Memory retrieval, wake signals, and activation patterns',
+  },
+  {
+    legacyWing: 'memory',
+    legacyRoom: 'memory/anchors',
+    basin: 'abyss',
+    current: 'abyss/anchors',
+    description: 'Recovery anchors, checkpoints, and persistent reference points',
+  },
+  {
+    legacyWing: 'memory',
+    legacyRoom: 'memory/evidence',
+    basin: 'abyss',
+    current: 'abyss/evidence',
+    description: 'Evidence snippets, citations, and supporting context',
+  },
+  // --- surge (legacy: task) ---
+  {
+    legacyWing: 'task',
+    legacyRoom: 'task/expedition',
+    basin: 'surge',
+    current: 'surge/expedition',
+    description: 'Active projects, features, and implementation work',
+  },
+  {
+    legacyWing: 'task',
+    legacyRoom: 'task/tide',
+    basin: 'surge',
+    current: 'surge/tide',
+    description: 'Scheduled routines, daily tasks, and recurring checks',
+  },
+  {
+    legacyWing: 'task',
+    legacyRoom: 'task/queue',
+    basin: 'surge',
+    current: 'surge/queue',
+    description: 'Task backlog, pending items, and work queue',
+  },
+  {
+    legacyWing: 'task',
+    legacyRoom: 'task/blockers',
+    basin: 'surge',
+    current: 'surge/blockers',
+    description: 'Blockers, issues, and impediments to progress',
+  },
+  // --- harbor (legacy: people) ---
+  {
+    legacyWing: 'people',
+    legacyRoom: 'people/crew',
+    basin: 'harbor',
+    current: 'harbor/crew',
+    description: 'Users, team members, and collaboration context',
+  },
+  {
+    legacyWing: 'people',
+    legacyRoom: 'people/research',
+    basin: 'harbor',
+    current: 'harbor/research',
+    description: 'Research findings, explorations, and investigations',
+  },
+  {
+    legacyWing: 'people',
+    legacyRoom: 'people/liu-lie',
+    basin: 'harbor',
+    current: 'harbor/liu-lie',
+    description: 'Partner context and shared understanding',
+  },
+  {
+    legacyWing: 'people',
+    legacyRoom: 'people/dandan',
+    basin: 'harbor',
+    current: 'harbor/dandan',
+    description: 'Companion and adjacent agent context',
+  },
+];

package/src/memory_audit.ts

@@ -0,0 +1,32 @@
+/**
+ * TSUNAMI memory audit stub
+ *
+ * Provides memory fabric auditing functions expected by the storm center.
+ * Returns empty results; the storm center handles these gracefully.
+ */
+
+export interface MemoryAuditIssue {
+  code: string;
+  severity: 'low' | 'medium' | 'high';
+  detail?: string;
+}
+
+export interface MemoryAuditRepairSuggestion {
+  title: string;
+  priority: 'P0' | 'P1' | 'P2' | 'P3';
+  detail?: string;
+}
+
+export interface MemoryAuditResult {
+  issues: MemoryAuditIssue[];
+  repairSuggestions: MemoryAuditRepairSuggestion[];
+  issueCount: number;
+}
+
+export function auditMemoryFabric(_projectDir: string): MemoryAuditResult {
+  return { issues: [], repairSuggestions: [], issueCount: 0 };
+}
+
+export function buildMemoryAuditContext(): Record<string, unknown> {
+  return {};
+}

package/src/memory_conflict_resolver.ts

@@ -0,0 +1,14 @@
+/**
+ * TSUNAMI memory conflict resolver stub
+ *
+ * Provides memory conflict resolution functions.
+ * Returns empty/unchanged by default.
+ */
+
+export function resolveMemoryConflicts(): null {
+  return null;
+}
+
+export function buildMemoryConflictContext(): Record<string, unknown> {
+  return {};
+}

package/src/memory_fabric.ts

@@ -0,0 +1,31 @@
+export { memoryFabric, memoryManager } from './memory_manager';
+export {
+  auditMemoryFabric,
+  buildMemoryAuditContext,
+} from './memory_audit';
+export {
+  promoteConversationTurn,
+  promoteHandoffToMemory,
+  promoteWorklogSnapshot,
+  queueMemoryPromotion,
+} from './memory_promotion';
+export { memoryRuntime } from './memory_runtime';
+export {
+  buildCrossSessionRecoveryBlock,
+  searchCrossSessionRecovery,
+} from './memory_recovery';
+export {
+  resolveMemoryConflicts,
+  buildMemoryConflictContext,
+} from './memory_conflict_resolver';
+export type {
+  MemoryAddOptions,
+  MemoryCompactOptions,
+  MemoryPrefetchOptions,
+  MemoryProvider,
+  MemoryQueryIntent,
+  MemoryRecallOptions,
+  MemorySearchOptions,
+  MemorySyncOptions,
+  MemoryWakeOptions,
+} from './provider';

package/src/memory_manager.ts

@@ -0,0 +1,10 @@
+/**
+ * TSUNAMI memory manager stub
+ *
+ * Provides the memoryFabric and memoryManager exports expected by memory_fabric.ts.
+ * These are placeholder stubs for future full implementations.
+ */
+
+export const memoryFabric = {};
+
+export const memoryManager = {};

package/src/memory_promotion.ts

@@ -0,0 +1,22 @@
+/**
+ * TSUNAMI memory promotion stubs
+ *
+ * Provides memory promotion functions for promoting conversation turns,
+ * handoffs, and worklog snapshots into durable memory.
+ */
+
+export function promoteConversationTurn(): null {
+  return null;
+}
+
+export function promoteHandoffToMemory(): null {
+  return null;
+}
+
+export function promoteWorklogSnapshot(): null {
+  return null;
+}
+
+export function queueMemoryPromotion(): null {
+  return null;
+}

package/src/memory_recovery.ts

@@ -0,0 +1,14 @@
+/**
+ * TSUNAMI memory recovery stubs
+ *
+ * Provides cross-session recovery block builders and search functions.
+ * Returns null/empty by default.
+ */
+
+export function buildCrossSessionRecoveryBlock(): null {
+  return null;
+}
+
+export function searchCrossSessionRecovery(): null {
+  return null;
+}

package/src/memory_runtime.ts

@@ -0,0 +1,7 @@
+/**
+ * TSUNAMI memory runtime stub
+ *
+ * Provides the memoryRuntime export expected by memory_fabric.ts.
+ */
+
+export const memoryRuntime = {};

package/src/migration.ts

@@ -0,0 +1,163 @@
+/**
+ * TSUNAMI Schema Migration System
+ *
+ * Versioned, idempotent migrations for the SQLite database.
+ * Each migration has a version number and an `up` function.
+ * The `schema_version` table tracks which migrations have been applied.
+ *
+ * Usage:
+ *   import { runMigrations } from './migration';
+ *   const db = new Database(path);
+ *   const applied = runMigrations(db, getMigrations());
+ */
+
+import type { Database } from 'bun:sqlite';
+
+export interface Migration {
+  version: number;
+  name: string;
+  up: (db: Database) => void;
+}
+
+const SCHEMA_TABLE = 'schema_version';
+
+/** Ensure the schema_version tracking table exists. */
+function ensureVersionTable(db: Database): void {
+  db.run(`
+    CREATE TABLE IF NOT EXISTS ${SCHEMA_TABLE} (
+      version   INTEGER PRIMARY KEY,
+      name      TEXT    NOT NULL,
+      appliedAt INTEGER NOT NULL DEFAULT (unixepoch() * 1000)
+    )
+  `);
+}
+
+/** Get the highest applied migration version. */
+function currentVersion(db: Database): number {
+  ensureVersionTable(db);
+  const row = db.prepare(
+    `SELECT MAX(version) as v FROM ${SCHEMA_TABLE}`
+  ).get() as { v: number | null } | undefined;
+  return row?.v ?? 0;
+}
+
+/** Apply a single migration if not already applied. */
+function applyMigration(db: Database, m: Migration): boolean {
+  const existing = db.prepare(
+    `SELECT 1 FROM ${SCHEMA_TABLE} WHERE version = ?`
+  ).get(m.version);
+  if (existing) return false;
+
+  m.up(db);
+  db.prepare(
+    `INSERT INTO ${SCHEMA_TABLE} (version, name) VALUES (?, ?)`
+  ).run(m.version, m.name);
+  return true;
+}
+
+/** Run all pending migrations in order. Returns count of newly applied. */
+export function runMigrations(db: Database, migrations: Migration[]): number {
+  ensureVersionTable(db);
+  const current = currentVersion(db);
+  const pending = migrations
+    .filter(m => m.version > current)
+    .sort((a, b) => a.version - b.version);
+
+  let applied = 0;
+  for (const m of pending) {
+    if (applyMigration(db, m)) applied++;
+  }
+  return applied;
+}
+
+// ═══════════════════════════════════════════════════════════
+// Migration definitions
+// ═══════════════════════════════════════════════════════════
+
+/** v1 — Initial schema: memory entries + FTS5 + knowledge graph. */
+const v1_initial_schema: Migration = {
+  version: 1,
+  name: 'initial_schema',
+  up(db) {
+    // Memory entries
+    db.run(`
+      CREATE TABLE IF NOT EXISTS memory_entries (
+        id          TEXT PRIMARY KEY,
+        wing        TEXT NOT NULL DEFAULT 'general',
+        room        TEXT NOT NULL DEFAULT 'inbox',
+        content     TEXT NOT NULL,
+        importance  INTEGER NOT NULL DEFAULT 3,
+        source      TEXT DEFAULT 'direct',
+        session_id  TEXT,
+        project_dir TEXT,
+        fingerprint TEXT,
+        created_at  INTEGER NOT NULL DEFAULT (unixepoch() * 1000),
+        updated_at  INTEGER NOT NULL DEFAULT (unixepoch() * 1000)
+      )
+    `);
+
+    // FTS5 virtual table
+    db.run(`
+      CREATE VIRTUAL TABLE IF NOT EXISTS memory_fts USING fts5(
+        content, wing, room,
+        content='memory_entries',
+        content_rowid='rowid'
+      )
+    `);
+
+    // FTS sync triggers
+    db.run(`
+      CREATE TRIGGER IF NOT EXISTS memory_ai AFTER INSERT ON memory_entries BEGIN
+        INSERT INTO memory_fts(rowid, content, wing, room)
+        VALUES (new.rowid, new.content, new.wing, new.room);
+      END
+    `);
+    db.run(`
+      CREATE TRIGGER IF NOT EXISTS memory_ad AFTER DELETE ON memory_entries BEGIN
+        INSERT INTO memory_fts(memory_fts, rowid, content, wing, room)
+        VALUES ('delete', old.rowid, old.content, old.wing, old.room);
+      END
+    `);
+    db.run(`
+      CREATE TRIGGER IF NOT EXISTS memory_au AFTER UPDATE ON memory_entries BEGIN
+        INSERT INTO memory_fts(memory_fts, rowid, content, wing, room)
+        VALUES ('delete', old.rowid, old.content, old.wing, old.room);
+        INSERT INTO memory_fts(rowid, content, wing, room)
+        VALUES (new.rowid, new.content, new.wing, new.room);
+      END
+    `);
+
+    // Indexes
+    db.run(`CREATE INDEX IF NOT EXISTS idx_mem_wing    ON memory_entries(wing)`);
+    db.run(`CREATE INDEX IF NOT EXISTS idx_mem_room    ON memory_entries(room)`);
+    db.run(`CREATE INDEX IF NOT EXISTS idx_mem_created ON memory_entries(created_at)`);
+
+    // Knowledge graph
+    db.run(`
+      CREATE TABLE IF NOT EXISTS graph_triples (
+        id                 TEXT PRIMARY KEY,
+        subject            TEXT NOT NULL,
+        predicate          TEXT NOT NULL,
+        object             TEXT NOT NULL,
+        subject_type       TEXT,
+        object_type        TEXT,
+        subject_properties TEXT DEFAULT '{}',
+        object_properties  TEXT DEFAULT '{}',
+        confidence         REAL NOT NULL DEFAULT 1.0,
+        valid_from         TEXT,
+        valid_to           TEXT,
+        source_file        TEXT,
+        created_at         INTEGER NOT NULL DEFAULT (unixepoch() * 1000)
+      )
+    `);
+
+    db.run(`CREATE INDEX IF NOT EXISTS idx_graph_subject   ON graph_triples(subject)`);
+    db.run(`CREATE INDEX IF NOT EXISTS idx_graph_object    ON graph_triples(object)`);
+    db.run(`CREATE INDEX IF NOT EXISTS idx_graph_predicate ON graph_triples(predicate)`);
+  },
+};
+
+/** All migrations in version order. Add new entries at the end. */
+export function getMigrations(): Migration[] {
+  return [v1_initial_schema];
+}