@jungjaehoon/mama-core 1.3.3 → 1.4.1

package/README.md

@@ -74,12 +74,40 @@ const mamaApi = require('@jungjaehoon/mama-core/mama-api');
   - CRUD operations for decisions
   - Vector similarity search
 
-### Core API
+### Memory API
 
-- **mama-api** - High-level API interface
+- **memory/api** - Scoped memory operations
+  - `saveMemory(input)` - Save typed memory with scopes and optional event_date (preference, fact, decision, lesson, constraint)
+  - `recallMemory(query, options)` - Truth-aware recall with scope filtering
+  - `buildProfile(scopes)` - Build memory profile (static/dynamic/evidence)
+  - `ingestMemory(input)` - Ingest raw content as memory
+  - `ingestConversation(input)` - Decompose conversations into typed memory units via optional LLM extraction
+  - `evolveMemory(input)` - Resolve graph edges between memories
+  - `buildMemoryBootstrap(params)` - Build memory agent bootstrap context
+  - `createAuditAck(input)` - Create audit acknowledgment
+  - `recordMemoryAudit(input)` - Record channel audit with state management
+
+- **memory/truth-store** - Truth projection layer
+  - `projectMemoryTruth(row)` - Write truth projection
+  - `queryRelevantTruth(params)` - Query current truth with scope/query filtering
+  - `queryTruthByTopic(topic)` - Get truth rows for a topic
+
+- **memory/evolution-engine** - Graph edge resolution
+  - `resolveMemoryEvolution(input)` - Determine supersedes/builds_on edges
+
+- **memory/extraction-prompt** - LLM extraction for conversation ingestion
+  - `buildExtractionPrompt(messages)` - Build structured prompt for memory extraction
+  - `parseExtractionResponse(response)` - Parse LLM JSON response into typed units
+
+- **memory/channel-summary-state-store** - Channel state management
+  - `recordChannelAudit(input)` - Accumulate audit outcomes into channel state
+
+### Core API (Legacy)
+
+- **mama-api** - High-level API interface (wraps memory API)
   - `save(decision)` - Save decision
   - `recall(topic)` - Retrieve decision history
-  - `suggest(query)` - Semantic search
+  - `suggest(query)` - Semantic search with hybrid FTS5 + vector + recency
   - `updateOutcome(id, outcome)` - Update decision outcome
 
 - **decision-tracker** - Decision graph management
@@ -125,12 +153,15 @@ pnpm test:watch
 
 ## Test Coverage
 
-- 35 unit tests
+- 72 unit tests across 17 test files
 - 100% passing
 - Tests cover:
-  - Config loader
-  - Database initialization
-  - Module exports
+  - Config loader, database initialization, module exports
+  - Memory API (save, recall, profile)
+  - Truth store, evolution engine, scope schema
+  - Channel summary, channel summary state
+  - Event store, finding store, bootstrap builder
+  - Legacy shim compatibility
 
 ## Architecture
 
@@ -139,23 +170,40 @@ MAMA Core uses CommonJS modules and is designed to be shared across multiple pac
 ```
 packages/mama-core/
 ├── src/
-│   ├── index.js              # Main exports
-│   ├── embeddings.js         # Embedding generation
-│   ├── db-manager.js         # Database management
-│   ├── mama-api.js           # High-level API
-│   └── db-adapter/           # Database adapter
-├── db/migrations/            # SQLite migrations
-└── tests/                    # Unit tests
+│   ├── index.ts              # Main exports
+│   ├── embeddings.ts         # Embedding generation
+│   ├── db-manager.ts         # Database management
+│   ├── mama-api.ts           # High-level API (wraps memory API)
+│   ├── db-adapter/           # Database adapter (SQLite)
+│   └── memory/               # Memory infrastructure
+│       ├── types.ts          # MemoryRecord, MemoryScopeRef, RecallBundle, etc.
+│       ├── api.ts            # saveMemory, recallMemory, buildProfile, etc.
+│       ├── truth-store.ts    # Truth projection layer
+│       ├── extraction-prompt.ts  # LLM extraction prompt + parser
+│       ├── evolution-engine.ts  # Graph edge resolution
+│       ├── scope-store.ts    # Scope management
+│       ├── event-store.ts    # Audit event persistence
+│       ├── finding-store.ts  # Audit finding persistence
+│       ├── channel-summary-store.ts       # Channel summaries
+│       ├── channel-summary-state-store.ts # Channel state reducer
+│       ├── bootstrap-builder.ts           # Memory agent bootstrap
+│       └── profile-builder.ts             # Profile classification
+├── db/migrations/            # SQLite migrations (001-023)
+└── tests/                    # 16 test files, 59 tests
 ```
 
 ## Migration Files
 
-Database migrations are included in `db/migrations/`:
+Database migrations are included in `db/migrations/` (001-023):
 
-- 001-initial-decision-graph.sql
-- 002-add-error-patterns.sql
-- 003-add-validation-fields.sql
-- (and more...)
+- 001-013: Core schema (decisions, embeddings, graph edges)
+- 014: Add is_static column
+- 015: FTS5 full-text search index
+- 016: Memory kind/status/summary columns
+- 017-018: Memory scopes and scope bindings
+- 019-020: Memory events and audit findings
+- 021: Memory truth projection
+- 022-023: Channel summaries and state
 
 ## License
 

package/db/migrations/001-initial-decision-graph.sql

@@ -100,7 +100,12 @@ CREATE TABLE IF NOT EXISTS sessions (
   -- Timestamps
   started_at INTEGER DEFAULT (unixepoch() * 1000),
   last_active_at INTEGER DEFAULT (unixepoch() * 1000),
+  last_active TEXT,
+  created_at TEXT DEFAULT (datetime('now')),
   ended_at INTEGER,
+  status TEXT DEFAULT 'active',
+  pid INTEGER,
+  client_id TEXT,
 
   CHECK (action_count >= 0),
   CHECK (decision_count >= 0)
@@ -119,7 +124,7 @@ CREATE INDEX IF NOT EXISTS idx_sessions_last_active ON sessions(last_active_at);
 -- because sqlite-vss requires extension loading first
 --
 -- CREATE VIRTUAL TABLE vss_memories USING vss0(
---   embedding(384)                    -- multilingual-e5-small embeddings
+--   embedding(1024)                   -- multilingual-e5-large embeddings
 -- );
 
 -- ══════════════════════════════════════════════════════════════

package/db/migrations/002-add-error-patterns.sql

@@ -33,7 +33,7 @@ CREATE TABLE IF NOT EXISTS error_patterns (
   first_seen INTEGER NOT NULL,     -- First occurrence timestamp
 
   -- Vector Embedding (for semantic matching)
-  embedding BLOB,                  -- 384-dim embedding (multilingual-e5-small)
+  embedding BLOB,                  -- 1024-dim embedding (multilingual-e5-large)
 
   -- Metadata
   created_at INTEGER DEFAULT (unixepoch() * 1000),

package/db/migrations/014-add-is-static-column.sql

@@ -0,0 +1,5 @@
+-- Add is_static column for user profile (long-term preferences vs current work)
+ALTER TABLE decisions ADD COLUMN is_static INTEGER DEFAULT 0;
+
+INSERT OR IGNORE INTO schema_version (version, description)
+VALUES (14, 'Add is_static column for user profile preferences');

package/db/migrations/015-add-fts5-search.sql

@@ -0,0 +1,34 @@
+-- FTS5 virtual table for keyword search
+CREATE VIRTUAL TABLE IF NOT EXISTS decisions_fts USING fts5(
+  topic, decision, reasoning,
+  content='decisions',
+  content_rowid='rowid'
+);
+
+-- Sync triggers for external content table
+CREATE TRIGGER IF NOT EXISTS decisions_ai AFTER INSERT ON decisions BEGIN
+  INSERT INTO decisions_fts(rowid, topic, decision, reasoning)
+  VALUES (new.rowid, new.topic, new.decision, new.reasoning);
+END;
+
+CREATE TRIGGER IF NOT EXISTS decisions_ad BEFORE DELETE ON decisions BEGIN
+  INSERT INTO decisions_fts(decisions_fts, rowid, topic, decision, reasoning)
+  VALUES('delete', old.rowid, old.topic, old.decision, old.reasoning);
+END;
+
+CREATE TRIGGER IF NOT EXISTS decisions_au BEFORE UPDATE ON decisions BEGIN
+  INSERT INTO decisions_fts(decisions_fts, rowid, topic, decision, reasoning)
+  VALUES('delete', old.rowid, old.topic, old.decision, old.reasoning);
+END;
+
+CREATE TRIGGER IF NOT EXISTS decisions_au2 AFTER UPDATE ON decisions BEGIN
+  INSERT INTO decisions_fts(rowid, topic, decision, reasoning)
+  VALUES (new.rowid, new.topic, new.decision, new.reasoning);
+END;
+
+-- Backfill existing decisions into FTS index
+INSERT INTO decisions_fts(rowid, topic, decision, reasoning)
+  SELECT rowid, topic, decision, reasoning FROM decisions;
+
+INSERT OR IGNORE INTO schema_version (version, description)
+VALUES (15, 'Add FTS5 keyword search with sync triggers');

package/db/migrations/016-add-memory-v2-columns.sql

@@ -0,0 +1,14 @@
+ALTER TABLE decisions ADD COLUMN kind TEXT DEFAULT 'decision'
+  CHECK (kind IN ('decision', 'preference', 'constraint', 'lesson', 'fact'));
+
+ALTER TABLE decisions ADD COLUMN status TEXT DEFAULT 'active'
+  CHECK (status IN ('active', 'superseded', 'contradicted', 'stale'));
+
+ALTER TABLE decisions ADD COLUMN summary TEXT;
+
+UPDATE decisions
+SET summary = decision
+WHERE summary IS NULL;
+
+INSERT OR IGNORE INTO schema_version (version, description)
+VALUES (16, 'Add memory v2 kind/status/summary columns');

package/db/migrations/017-create-memory-scopes.sql

@@ -0,0 +1,10 @@
+CREATE TABLE IF NOT EXISTS memory_scopes (
+  id TEXT PRIMARY KEY,
+  kind TEXT NOT NULL CHECK (kind IN ('global', 'user', 'channel', 'project')),
+  external_id TEXT NOT NULL,
+  created_at INTEGER DEFAULT (unixepoch() * 1000),
+  UNIQUE(kind, external_id)
+);
+
+INSERT OR IGNORE INTO schema_version (version, description)
+VALUES (17, 'Create memory scopes table');

package/db/migrations/018-create-memory-scope-bindings.sql

@@ -0,0 +1,15 @@
+CREATE TABLE IF NOT EXISTS memory_scope_bindings (
+  memory_id TEXT NOT NULL,
+  scope_id TEXT NOT NULL,
+  is_primary INTEGER DEFAULT 0 CHECK (is_primary IN (0, 1)),
+  created_at INTEGER DEFAULT (unixepoch() * 1000),
+  PRIMARY KEY (memory_id, scope_id),
+  FOREIGN KEY (memory_id) REFERENCES decisions(id) ON DELETE CASCADE,
+  FOREIGN KEY (scope_id) REFERENCES memory_scopes(id) ON DELETE CASCADE
+);
+
+CREATE INDEX IF NOT EXISTS idx_memory_scope_bindings_scope_id
+  ON memory_scope_bindings(scope_id);
+
+INSERT OR IGNORE INTO schema_version (version, description)
+VALUES (18, 'Create memory scope bindings table');

package/db/migrations/019-create-memory-events.sql

@@ -0,0 +1,18 @@
+CREATE TABLE IF NOT EXISTS memory_events (
+  event_id TEXT PRIMARY KEY,
+  event_type TEXT NOT NULL,
+  actor TEXT NOT NULL,
+  source_turn_id TEXT,
+  memory_id TEXT,
+  topic TEXT,
+  scope_refs TEXT NOT NULL,
+  evidence_refs TEXT,
+  reason TEXT,
+  created_at INTEGER NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_memory_events_topic_created_at
+  ON memory_events(topic, created_at DESC);
+
+INSERT OR IGNORE INTO schema_version (version, description)
+VALUES (19, 'Create memory events table');

package/db/migrations/020-create-audit-findings.sql

@@ -0,0 +1,18 @@
+CREATE TABLE IF NOT EXISTS audit_findings (
+  finding_id TEXT PRIMARY KEY,
+  kind TEXT NOT NULL,
+  severity TEXT NOT NULL,
+  summary TEXT NOT NULL,
+  evidence_refs TEXT NOT NULL,
+  affected_memory_ids TEXT NOT NULL,
+  recommended_action TEXT NOT NULL,
+  status TEXT NOT NULL DEFAULT 'open',
+  created_at INTEGER NOT NULL,
+  resolved_at INTEGER
+);
+
+CREATE INDEX IF NOT EXISTS idx_audit_findings_status_created_at
+  ON audit_findings(status, created_at DESC);
+
+INSERT OR IGNORE INTO schema_version (version, description)
+VALUES (20, 'Create audit findings table');

package/db/migrations/021-create-memory-truth.sql

@@ -0,0 +1,20 @@
+CREATE TABLE IF NOT EXISTS memory_truth (
+  memory_id TEXT PRIMARY KEY,
+  topic TEXT NOT NULL,
+  truth_status TEXT NOT NULL,
+  effective_summary TEXT NOT NULL,
+  effective_details TEXT NOT NULL,
+  trust_score REAL NOT NULL,
+  scope_refs TEXT NOT NULL,
+  supporting_event_ids TEXT NOT NULL,
+  superseded_by TEXT,
+  contradicted_by TEXT,
+  created_at INTEGER NOT NULL DEFAULT (unixepoch() * 1000),
+  updated_at INTEGER NOT NULL DEFAULT (unixepoch() * 1000)
+);
+
+CREATE INDEX IF NOT EXISTS idx_memory_truth_topic_updated_at
+  ON memory_truth(topic, updated_at DESC);
+
+INSERT OR IGNORE INTO schema_version (version, description)
+VALUES (21, 'Create memory truth projection table');

package/db/migrations/022-create-channel-summaries.sql

@@ -0,0 +1,9 @@
+CREATE TABLE IF NOT EXISTS channel_summaries (
+  channel_key TEXT PRIMARY KEY,
+  summary_markdown TEXT NOT NULL,
+  delta_hash TEXT,
+  updated_at INTEGER NOT NULL
+);
+
+INSERT OR IGNORE INTO schema_version (version, description)
+VALUES (22, 'Create channel summaries table');

package/db/migrations/023-create-channel-summary-state.sql

@@ -0,0 +1,9 @@
+CREATE TABLE IF NOT EXISTS channel_summary_state (
+  channel_key TEXT PRIMARY KEY,
+  state_json TEXT NOT NULL,
+  state_hash TEXT NOT NULL,
+  updated_at INTEGER NOT NULL
+);
+
+INSERT OR IGNORE INTO schema_version (version, description)
+VALUES (23, 'Create channel summary state table');

package/db/migrations/024-add-event-date.sql

@@ -0,0 +1,9 @@
+-- Migration 024: Add event_date column to decisions table
+-- event_date stores the ISO 8601 date when the event actually occurred
+-- (distinct from created_at which is ingestion time)
+ALTER TABLE decisions ADD COLUMN event_date TEXT;
+
+CREATE INDEX IF NOT EXISTS idx_decisions_event_date ON decisions(event_date);
+
+INSERT OR IGNORE INTO schema_version (version, description)
+VALUES (24, 'Add event_date column for temporal tracking');

package/db/migrations/025-extend-kind-check.sql

@@ -0,0 +1,59 @@
+-- v0.17: Extend kind CHECK constraint to include 'task' and 'schedule'.
+-- Only runs if the old CHECK exists (idempotent).
+-- Uses a temp table approach since SQLite cannot ALTER CHECK constraints.
+
+-- Drop the old column constraint by recreating the table
+-- This is safe because we explicitly list all columns
+
+CREATE TABLE IF NOT EXISTS decisions_v17 (
+  id TEXT PRIMARY KEY,
+  topic TEXT NOT NULL,
+  decision TEXT NOT NULL,
+  reasoning TEXT,
+  outcome TEXT,
+  failure_reason TEXT,
+  limitation TEXT,
+  user_involvement TEXT,
+  session_id TEXT,
+  supersedes TEXT,
+  superseded_by TEXT,
+  refined_from TEXT,
+  confidence REAL DEFAULT 0.5 CHECK (confidence >= 0.0 AND confidence <= 1.0),
+  created_at INTEGER NOT NULL DEFAULT (strftime('%s','now') * 1000),
+  updated_at INTEGER NOT NULL DEFAULT (strftime('%s','now') * 1000),
+  needs_validation INTEGER DEFAULT 0 CHECK (needs_validation IN (0, 1)),
+  validation_attempts INTEGER DEFAULT 0,
+  last_validated_at INTEGER,
+  usage_count INTEGER DEFAULT 0,
+  trust_context TEXT,
+  usage_success INTEGER DEFAULT 0,
+  usage_failure INTEGER DEFAULT 0,
+  time_saved INTEGER DEFAULT 0,
+  evidence TEXT,
+  alternatives TEXT,
+  risks TEXT,
+  event_date TEXT,
+  kind TEXT DEFAULT 'decision'
+    CHECK (kind IN ('decision', 'preference', 'constraint', 'lesson', 'fact', 'task', 'schedule')),
+  status TEXT DEFAULT 'active'
+    CHECK (status IN ('active', 'superseded', 'contradicted', 'stale')),
+  summary TEXT,
+  is_static INTEGER DEFAULT 0
+);
+
+INSERT OR IGNORE INTO decisions_v17 (
+  id, topic, decision, reasoning, outcome, failure_reason, limitation,
+  user_involvement, session_id, supersedes, superseded_by, refined_from,
+  confidence, created_at, updated_at, needs_validation, validation_attempts,
+  last_validated_at, usage_count, trust_context, usage_success, usage_failure,
+  time_saved, evidence, alternatives, risks, event_date, kind, status, summary, is_static
+) SELECT
+  id, topic, decision, reasoning, outcome, failure_reason, limitation,
+  user_involvement, session_id, supersedes, superseded_by, refined_from,
+  confidence, created_at, updated_at, needs_validation, validation_attempts,
+  last_validated_at, usage_count, trust_context, usage_success, usage_failure,
+  time_saved, evidence, alternatives, risks, event_date, kind, status, summary, is_static
+FROM decisions;
+
+DROP TABLE decisions;
+ALTER TABLE decisions_v17 RENAME TO decisions;

package/dist/config-loader.d.ts

@@ -6,7 +6,7 @@
  *
  * Loads user configuration from ~/.mama/config.json with sensible defaults.
  * Supports:
- * - Model selection (default: multilingual-e5-small)
+ * - Model selection (default: multilingual-e5-large)
  * - Embedding dimensions
  * - Cache directory configuration
  *

package/dist/config-loader.js

@@ -7,7 +7,7 @@
  *
  * Loads user configuration from ~/.mama/config.json with sensible defaults.
  * Supports:
- * - Model selection (default: multilingual-e5-small)
+ * - Model selection (default: multilingual-e5-large)
  * - Embedding dimensions
  * - Cache directory configuration
  *
@@ -31,8 +31,8 @@ const os_1 = __importDefault(require("os"));
 const debug_logger_js_1 = require("./debug-logger.js");
 // Default configuration
 exports.DEFAULT_CONFIG = {
-    modelName: 'Xenova/multilingual-e5-small',
-    embeddingDim: 384,
+    modelName: 'Xenova/multilingual-e5-large',
+    embeddingDim: 1024,
     quantized: true,
     cacheDir: path_1.default.join(os_1.default.homedir(), '.cache', 'huggingface', 'transformers'),
 };

package/dist/db-adapter/base-adapter.d.ts

@@ -43,11 +43,11 @@ export declare abstract class DatabaseAdapter {
     abstract transaction<T>(fn: () => T): T;
     /**
      * Vector similarity search
-     * @param embedding - Query embedding (384-dim)
+     * @param embedding - Query embedding (1024-dim)
      * @param limit - Max results
      * @returns Search results with distance
      */
-    abstract vectorSearch(embedding: Float32Array | number[], limit: number): VectorSearchResult[] | null;
+    abstract vectorSearch(embedding: Float32Array | number[], limit: number, topicPrefix?: string): VectorSearchResult[] | null;
     /**
      * Insert vector embedding
      * @param rowid - Decision rowid

package/dist/db-adapter/index.js

@@ -24,14 +24,8 @@ Object.defineProperty(exports, "DatabaseAdapter", { enumerable: true, get: funct
  * @returns Configured SQLite adapter instance
  */
 function createAdapter(config = {}) {
-    const configuredDriver = process.env.MAMA_SQLITE_DRIVER;
-    if (configuredDriver &&
-        configuredDriver !== 'node-sqlite' &&
-        configuredDriver !== 'node:sqlite' &&
-        configuredDriver !== 'auto') {
-        throw new Error(`Unsupported SQLite driver "${configuredDriver}". MAMA now requires node:sqlite.`);
-    }
-    (0, debug_logger_js_1.info)('[db-adapter] Using node:sqlite adapter');
+    // SQLiteAdapter (extends NodeSQLiteAdapter) auto-detects: better-sqlite3 (preferred, FTS5) → node:sqlite (fallback)
+    (0, debug_logger_js_1.info)('[db-adapter] Creating SQLite adapter (auto-detect driver)');
     const dbPath = config.dbPath || process.env.MAMA_DB_PATH;
     return new sqlite_adapter_js_1.SQLiteAdapter({ dbPath });
 }

package/dist/db-adapter/node-sqlite-adapter.d.ts

@@ -24,6 +24,7 @@ interface NodeSQLiteStatementLike {
 declare class NodeSQLiteConnection {
     private db;
     private connected;
+    private isBetterSQLite3;
     constructor(db: NodeSQLiteDatabaseLike);
     prepare(sql: string): NodeSQLiteStatementLike;
     exec(sql: string): void;
@@ -37,16 +38,20 @@ export declare class NodeSQLiteAdapter extends DatabaseAdapter {
     private config;
     private db;
     private _vectorSearchEnabled;
+    private vectorCache;
+    private topicCache;
     constructor(config?: SQLiteAdapterConfig);
     get vectorSearchEnabled(): boolean;
     getDbPath(): string;
     connect(): NodeSQLiteConnection;
+    reloadVectorCache(): void;
+    private loadVectorCache;
     disconnect(): void;
     isConnected(): boolean;
     prepare(sql: string): Statement;
     exec(sql: string): void;
     transaction<T>(fn: () => T): T;
-    vectorSearch(embedding: Float32Array | number[], limit?: number): VectorSearchResult[] | null;
+    vectorSearch(embedding: Float32Array | number[], limit?: number, topicPrefix?: string): VectorSearchResult[] | null;
     insertEmbedding(rowid: number, embedding: Float32Array | number[]): RunResult | null;
     getLastInsertRowid(): number;
     runMigrations(migrationsDir: string): void;