audrey 0.3.2 → 0.5.0

package/README.md

@@ -46,7 +46,7 @@ npx audrey status
 npx audrey uninstall
 ```
 
-Every Claude Code session now has 5 memory tools: `memory_encode`, `memory_recall`, `memory_consolidate`, `memory_introspect`, `memory_resolve_truth`.
+Every Claude Code session now has 7 memory tools: `memory_encode`, `memory_recall`, `memory_consolidate`, `memory_introspect`, `memory_resolve_truth`, `memory_export`, `memory_import`.
 
 ### SDK in Your Code
 
@@ -456,7 +456,7 @@ All mutations use SQLite transactions. CHECK constraints enforce valid states an
 ## Running Tests
 
 ```bash
-npm test          # 194 tests across 17 files
+npm test          # 208 tests across 17 files
 npm run test:watch
 ```
 
@@ -522,7 +522,7 @@ Demonstrates the full pipeline: encode 3 rate-limit observations → consolidate
 - [x] Automatic migration from v0.2.0 embedding BLOBs to vec0 tables
 - [x] 168 tests across 16 test files
 
-### v0.3.1 — MCP Server + JSDoc Types (current)
+### v0.3.1 — MCP Server + JSDoc Types
 
 - [x] MCP tool server via `@modelcontextprotocol/sdk` with stdio transport
 - [x] 5 tools: `memory_encode`, `memory_recall`, `memory_consolidate`, `memory_introspect`, `memory_resolve_truth`
@@ -533,6 +533,19 @@ Demonstrates the full pipeline: encode 3 rate-limit observations → consolidate
 - [x] Published to npm with proper package metadata
 - [x] 194 tests across 17 test files
 
+### v0.5.0 — Feature Depth (current)
+
+- [x] Configurable confidence weights per Audrey instance
+- [x] Configurable decay rates (half-lives) per Audrey instance
+- [x] Confidence config wired through constructor to recall and decay
+- [x] Memory export (JSON snapshot of all tables, no raw embeddings)
+- [x] Memory import with automatic re-embedding via current provider
+- [x] `memory_export` and `memory_import` MCP tools (7 tools total)
+- [x] Auto-consolidation scheduling (`startAutoConsolidate` / `stopAutoConsolidate`)
+- [x] Consolidation metrics tracking (per-run params and results)
+- [x] Adaptive consolidation parameter suggestions based on historical yield
+- [x] 220+ tests across 20 test files
+
 ### v0.4.0 — Type Safety & Developer Experience
 
 - [ ] Full TypeScript conversion with strict mode
@@ -545,16 +558,6 @@ Demonstrates the full pipeline: encode 3 rate-limit observations → consolidate
 - [ ] Embedding migration pipeline (re-embed when models change)
 - [ ] Re-consolidation queue (re-run consolidation with new embedding model)
 
-### v0.5.0 — Advanced Memory Features
-
-- [ ] Adaptive consolidation threshold (learn optimal N per domain, not fixed N=3)
-- [ ] Source-aware confidence for semantic memories (track strongest source composition)
-- [ ] Configurable decay rates per Audrey instance
-- [ ] Configurable confidence weights per Audrey instance
-- [ ] PII detection and redaction (opt-in)
-- [ ] Memory export/import (JSON snapshot)
-- [ ] Auto-consolidation scheduling (setInterval with configurable interval)
-
 ### v0.6.0 — Scale
 
 - [ ] pgvector adapter for PostgreSQL backend

package/mcp-server/config.js

@@ -1,7 +1,7 @@
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 
-export const VERSION = '0.3.2';
+export const VERSION = '0.5.0';
 export const SERVER_NAME = 'audrey-memory';
 export const DEFAULT_DATA_DIR = join(homedir(), '.audrey', 'data');
 

package/mcp-server/index.js

@@ -7,6 +7,7 @@ import { join } from 'node:path';
 import { existsSync, readFileSync } from 'node:fs';
 import { execFileSync } from 'node:child_process';
 import { Audrey } from '../src/index.js';
+import { readStoredDimensions } from '../src/db.js';
 import { VERSION, SERVER_NAME, DEFAULT_DATA_DIR, buildAudreyConfig, buildInstallArgs } from './config.js';
 
 const VALID_SOURCES = ['direct-observation', 'told-by-user', 'tool-result', 'inference', 'model-generated'];
@@ -64,12 +65,14 @@ function install() {
   console.log(`
 Audrey registered as "${SERVER_NAME}" with Claude Code.
 
-5 tools available in every session:
+7 tools available in every session:
   memory_encode        — Store observations, facts, preferences
   memory_recall        — Search memories by semantic similarity
   memory_consolidate   — Extract principles from accumulated episodes
   memory_introspect    — Check memory system health
   memory_resolve_truth — Resolve contradictions between claims
+  memory_export        — Export all memories as JSON snapshot
+  memory_import        — Import a snapshot into a fresh database
 
 Data stored in: ${DEFAULT_DATA_DIR}
 Verify: claude mcp list
@@ -107,10 +110,11 @@ function status() {
 
   if (existsSync(DEFAULT_DATA_DIR)) {
     try {
+      const dimensions = readStoredDimensions(DEFAULT_DATA_DIR) || 8;
       const audrey = new Audrey({
         dataDir: DEFAULT_DATA_DIR,
         agent: 'status-check',
-        embedding: { provider: 'mock', dimensions: 8 },
+        embedding: { provider: 'mock', dimensions },
       });
       const stats = audrey.introspect();
       audrey.close();
@@ -237,6 +241,44 @@ async function main() {
     },
   );
 
+  server.tool(
+    'memory_export',
+    {},
+    async () => {
+      try {
+        const snapshot = audrey.export();
+        return toolResult(snapshot);
+      } catch (err) {
+        return toolError(err);
+      }
+    },
+  );
+
+  server.tool(
+    'memory_import',
+    {
+      snapshot: z.object({
+        version: z.string(),
+        episodes: z.array(z.any()),
+        semantics: z.array(z.any()).optional(),
+        procedures: z.array(z.any()).optional(),
+        causalLinks: z.array(z.any()).optional(),
+        contradictions: z.array(z.any()).optional(),
+        consolidationRuns: z.array(z.any()).optional(),
+        config: z.record(z.string()).optional(),
+      }).passthrough().describe('A snapshot from memory_export'),
+    },
+    async ({ snapshot }) => {
+      try {
+        await audrey.import(snapshot);
+        const stats = audrey.introspect();
+        return toolResult({ imported: true, stats });
+      } catch (err) {
+        return toolError(err);
+      }
+    },
+  );
+
   const transport = new StdioServerTransport();
   await server.connect(transport);
   console.error('[audrey-mcp] connected via stdio');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "audrey",
-  "version": "0.3.2",
+  "version": "0.5.0",
   "description": "Biological memory architecture for AI agents — encode, consolidate, and recall memories with confidence decay, contradiction detection, and causal graphs",
   "type": "module",
   "main": "src/index.js",

package/src/adaptive.js

@@ -0,0 +1,53 @@
+export function suggestConsolidationParams(db) {
+  const runs = db.prepare(`
+    SELECT min_cluster_size, similarity_threshold, clusters_found, principles_extracted, episodes_evaluated
+    FROM consolidation_metrics
+    ORDER BY created_at DESC
+    LIMIT 20
+  `).all();
+
+  if (runs.length === 0) {
+    return {
+      minClusterSize: 3,
+      similarityThreshold: 0.85,
+      confidence: 'no_data',
+    };
+  }
+
+  const paramScores = new Map();
+  for (const run of runs) {
+    if (run.episodes_evaluated === 0) continue;
+    const key = `${run.min_cluster_size}:${run.similarity_threshold}`;
+    if (!paramScores.has(key)) {
+      paramScores.set(key, {
+        minClusterSize: run.min_cluster_size,
+        similarityThreshold: run.similarity_threshold,
+        yields: [],
+      });
+    }
+    paramScores.get(key).yields.push(run.principles_extracted / run.episodes_evaluated);
+  }
+
+  let bestKey = null;
+  let bestAvgYield = -1;
+  for (const [key, data] of paramScores) {
+    const avg = data.yields.reduce((a, b) => a + b, 0) / data.yields.length;
+    if (avg > bestAvgYield) {
+      bestAvgYield = avg;
+      bestKey = key;
+    }
+  }
+
+  if (!bestKey) {
+    return { minClusterSize: 3, similarityThreshold: 0.85, confidence: 'no_data' };
+  }
+
+  const best = paramScores.get(bestKey);
+  const confidence = runs.length >= 5 ? 'high' : runs.length >= 2 ? 'medium' : 'low';
+
+  return {
+    minClusterSize: best.minClusterSize,
+    similarityThreshold: best.similarityThreshold,
+    confidence,
+  };
+}

package/src/audrey.js

@@ -10,6 +10,9 @@ import { applyDecay } from './decay.js';
 import { rollbackConsolidation, getConsolidationHistory } from './rollback.js';
 import { introspect as introspectFn } from './introspect.js';
 import { buildContextResolutionPrompt } from './prompts.js';
+import { exportMemories } from './export.js';
+import { importMemories } from './import.js';
+import { suggestConsolidationParams as suggestParamsFn } from './adaptive.js';
 
 /**
  * @typedef {'direct-observation' | 'told-by-user' | 'tool-result' | 'inference' | 'model-generated'} SourceType
@@ -77,19 +80,37 @@ export class Audrey extends EventEmitter {
     agent = 'default',
     embedding = { provider: 'mock', dimensions: 64 },
     llm,
+    confidence = {},
     consolidation = {},
     decay = {},
   } = {}) {
     super();
+
+    const dormantThreshold = decay.dormantThreshold ?? 0.1;
+    if (dormantThreshold < 0 || dormantThreshold > 1) {
+      throw new Error(`dormantThreshold must be between 0 and 1, got: ${dormantThreshold}`);
+    }
+
+    const minEpisodes = consolidation.minEpisodes ?? 3;
+    if (!Number.isInteger(minEpisodes) || minEpisodes < 1) {
+      throw new Error(`minEpisodes must be a positive integer, got: ${minEpisodes}`);
+    }
+
     this.agent = agent;
     this.dataDir = dataDir;
     this.embeddingProvider = createEmbeddingProvider(embedding);
     this.db = createDatabase(dataDir, { dimensions: this.embeddingProvider.dimensions });
     this.llmProvider = llm ? createLLMProvider(llm) : null;
+    this.confidenceConfig = {
+      weights: confidence.weights,
+      halfLives: confidence.halfLives,
+      sourceReliability: confidence.sourceReliability,
+    };
     this.consolidationConfig = {
       minEpisodes: consolidation.minEpisodes || 3,
     };
     this.decayConfig = { dormantThreshold: decay.dormantThreshold || 0.1 };
+    this._autoConsolidateTimer = null;
   }
 
   _emitValidation(id, params) {
@@ -152,7 +173,10 @@ export class Audrey extends EventEmitter {
    * @returns {Promise<RecallResult[]>}
    */
   recall(query, options = {}) {
-    return recallFn(this.db, this.embeddingProvider, query, options);
+    return recallFn(this.db, this.embeddingProvider, query, {
+      ...options,
+      confidenceConfig: options.confidenceConfig ?? this.confidenceConfig,
+    });
   }
 
   /**
@@ -161,7 +185,10 @@ export class Audrey extends EventEmitter {
    * @returns {AsyncGenerator<RecallResult>}
    */
   async *recallStream(query, options = {}) {
-    yield* recallStreamFn(this.db, this.embeddingProvider, query, options);
+    yield* recallStreamFn(this.db, this.embeddingProvider, query, {
+      ...options,
+      confidenceConfig: options.confidenceConfig ?? this.confidenceConfig,
+    });
   }
 
   /**
@@ -188,6 +215,7 @@ export class Audrey extends EventEmitter {
   decay(options = {}) {
     const result = applyDecay(this.db, {
       dormantThreshold: options.dormantThreshold || this.decayConfig.dormantThreshold,
+      halfLives: options.halfLives ?? this.confidenceConfig.halfLives,
     });
     this.emit('decay', result);
     return result;
@@ -269,8 +297,40 @@ export class Audrey extends EventEmitter {
     return introspectFn(this.db);
   }
 
+  export() {
+    return exportMemories(this.db);
+  }
+
+  async import(snapshot) {
+    return importMemories(this.db, this.embeddingProvider, snapshot);
+  }
+
+  startAutoConsolidate(intervalMs, options = {}) {
+    if (intervalMs < 1000) {
+      throw new Error('Auto-consolidation interval must be at least 1000ms');
+    }
+    if (this._autoConsolidateTimer) {
+      throw new Error('Auto-consolidation is already running');
+    }
+    this._autoConsolidateTimer = setInterval(() => {
+      this.consolidate(options).catch(err => this.emit('error', err));
+    }, intervalMs);
+  }
+
+  stopAutoConsolidate() {
+    if (this._autoConsolidateTimer) {
+      clearInterval(this._autoConsolidateTimer);
+      this._autoConsolidateTimer = null;
+    }
+  }
+
+  suggestConsolidationParams() {
+    return suggestParamsFn(this.db);
+  }
+
   /** @returns {void} */
   close() {
+    this.stopAutoConsolidate();
     closeDatabase(this.db);
   }
 }

package/src/consolidate.js

@@ -213,6 +213,15 @@ export async function runConsolidation(db, embeddingProvider, options = {}) {
 
     promoteAll();
 
+    db.prepare(`
+      INSERT INTO consolidation_metrics (id, run_id, min_cluster_size, similarity_threshold,
+        episodes_evaluated, clusters_found, principles_extracted, created_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(
+      generateId(), runId, minClusterSize, similarityThreshold,
+      episodesEvaluated, clusters.length, principlesExtracted, new Date().toISOString(),
+    );
+
     return {
       runId,
       episodesEvaluated,

package/src/db.js

@@ -1,7 +1,7 @@
 import Database from 'better-sqlite3';
 import * as sqliteVec from 'sqlite-vec';
 import { join } from 'node:path';
-import { mkdirSync } from 'node:fs';
+import { mkdirSync, existsSync } from 'node:fs';
 
 const SCHEMA = `
   CREATE TABLE IF NOT EXISTS episodes (
@@ -104,6 +104,18 @@ const SCHEMA = `
     value TEXT NOT NULL
   );
 
+  CREATE TABLE IF NOT EXISTS consolidation_metrics (
+    id TEXT PRIMARY KEY,
+    run_id TEXT NOT NULL,
+    min_cluster_size INTEGER NOT NULL,
+    similarity_threshold REAL NOT NULL,
+    episodes_evaluated INTEGER NOT NULL,
+    clusters_found INTEGER NOT NULL,
+    principles_extracted INTEGER NOT NULL,
+    created_at TEXT NOT NULL,
+    FOREIGN KEY (run_id) REFERENCES consolidation_runs(id)
+  );
+
   CREATE INDEX IF NOT EXISTS idx_episodes_created ON episodes(created_at);
   CREATE INDEX IF NOT EXISTS idx_episodes_consolidated ON episodes(consolidated);
   CREATE INDEX IF NOT EXISTS idx_episodes_source ON episodes(source);
@@ -232,10 +244,21 @@ export function createDatabase(dataDir, options = {}) {
   return db;
 }
 
-/**
- * @param {import('better-sqlite3').Database} db
- * @returns {void}
- */
+export function readStoredDimensions(dataDir) {
+  const dbPath = join(dataDir, 'audrey.db');
+  if (!existsSync(dbPath)) return null;
+  const db = new Database(dbPath, { readonly: true });
+  try {
+    const row = db.prepare("SELECT value FROM audrey_config WHERE key = 'dimensions'").get();
+    return row ? parseInt(row.value, 10) : null;
+  } catch (err) {
+    if (err.message?.includes('no such table')) return null;
+    throw err;
+  } finally {
+    db.close();
+  }
+}
+
 export function closeDatabase(db) {
   if (db && db.open) {
     db.close();

package/src/decay.js

@@ -6,7 +6,7 @@ import { daysBetween } from './utils.js';
  * @param {{ dormantThreshold?: number }} [options]
  * @returns {{ totalEvaluated: number, transitionedToDormant: number, timestamp: string }}
  */
-export function applyDecay(db, { dormantThreshold = 0.1 } = {}) {
+export function applyDecay(db, { dormantThreshold = 0.1, halfLives } = {}) {
   const now = new Date();
   let totalEvaluated = 0;
   let transitionedToDormant = 0;
@@ -31,7 +31,7 @@ export function applyDecay(db, { dormantThreshold = 0.1 } = {}) {
       supportingCount: sem.supporting_count || 0,
       contradictingCount: sem.contradicting_count || 0,
       ageDays,
-      halfLifeDays: DEFAULT_HALF_LIVES.semantic,
+      halfLifeDays: halfLives?.semantic ?? DEFAULT_HALF_LIVES.semantic,
       retrievalCount: sem.retrieval_count || 0,
       daysSinceRetrieval,
     });
@@ -62,7 +62,7 @@ export function applyDecay(db, { dormantThreshold = 0.1 } = {}) {
       supportingCount: proc.success_count || 0,
       contradictingCount: proc.failure_count || 0,
       ageDays,
-      halfLifeDays: DEFAULT_HALF_LIVES.procedural,
+      halfLifeDays: halfLives?.procedural ?? DEFAULT_HALF_LIVES.procedural,
       retrievalCount: proc.retrieval_count || 0,
       daysSinceRetrieval,
     });

package/src/embedding.js

@@ -76,10 +76,11 @@ export class MockEmbeddingProvider {
 /** @implements {EmbeddingProvider} */
 export class OpenAIEmbeddingProvider {
   /** @param {Partial<OpenAIEmbeddingConfig>} [config={}] */
-  constructor({ apiKey, model = 'text-embedding-3-small', dimensions = 1536 } = {}) {
+  constructor({ apiKey, model = 'text-embedding-3-small', dimensions = 1536, timeout = 30000 } = {}) {
     this.apiKey = apiKey || process.env.OPENAI_API_KEY;
     this.model = model;
     this.dimensions = dimensions;
+    this.timeout = timeout;
     this.modelName = model;
     this.modelVersion = 'latest';
   }
@@ -89,17 +90,24 @@ export class OpenAIEmbeddingProvider {
    * @returns {Promise<number[]>}
    */
   async embed(text) {
-    const response = await fetch('https://api.openai.com/v1/embeddings', {
-      method: 'POST',
-      headers: {
-        'Authorization': `Bearer ${this.apiKey}`,
-        'Content-Type': 'application/json',
-      },
-      body: JSON.stringify({ input: text, model: this.model, dimensions: this.dimensions }),
-    });
-    if (!response.ok) throw new Error(`OpenAI embedding failed: ${response.status}`);
-    const data = await response.json();
-    return data.data[0].embedding;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeout);
+    try {
+      const response = await fetch('https://api.openai.com/v1/embeddings', {
+        method: 'POST',
+        headers: {
+          'Authorization': `Bearer ${this.apiKey}`,
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({ input: text, model: this.model, dimensions: this.dimensions }),
+        signal: controller.signal,
+      });
+      if (!response.ok) throw new Error(`OpenAI embedding failed: ${response.status}`);
+      const data = await response.json();
+      return data.data[0].embedding;
+    } finally {
+      clearTimeout(timer);
+    }
   }
 
   /**
@@ -107,17 +115,24 @@ export class OpenAIEmbeddingProvider {
    * @returns {Promise<number[][]>}
    */
   async embedBatch(texts) {
-    const response = await fetch('https://api.openai.com/v1/embeddings', {
-      method: 'POST',
-      headers: {
-        'Authorization': `Bearer ${this.apiKey}`,
-        'Content-Type': 'application/json',
-      },
-      body: JSON.stringify({ input: texts, model: this.model, dimensions: this.dimensions }),
-    });
-    if (!response.ok) throw new Error(`OpenAI embedding failed: ${response.status}`);
-    const data = await response.json();
-    return data.data.map(d => d.embedding);
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeout);
+    try {
+      const response = await fetch('https://api.openai.com/v1/embeddings', {
+        method: 'POST',
+        headers: {
+          'Authorization': `Bearer ${this.apiKey}`,
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({ input: texts, model: this.model, dimensions: this.dimensions }),
+        signal: controller.signal,
+      });
+      if (!response.ok) throw new Error(`OpenAI embedding failed: ${response.status}`);
+      const data = await response.json();
+      return data.data.map(d => d.embedding);
+    } finally {
+      clearTimeout(timer);
+    }
   }
 
   /**

package/src/export.js

@@ -0,0 +1,59 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { join, dirname } from 'node:path';
+import { safeJsonParse } from './utils.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(__dirname, '../package.json'), 'utf-8'));
+
+export function exportMemories(db) {
+  const episodes = db.prepare(
+    'SELECT id, content, source, source_reliability, salience, tags, causal_trigger, causal_consequence, created_at, supersedes, superseded_by, consolidated FROM episodes'
+  ).all().map(ep => ({
+    ...ep,
+    tags: safeJsonParse(ep.tags, null),
+  }));
+
+  const semantics = db.prepare(
+    'SELECT id, content, state, conditions, evidence_episode_ids, evidence_count, supporting_count, contradicting_count, source_type_diversity, consolidation_checkpoint, created_at, last_reinforced_at, retrieval_count, challenge_count FROM semantics'
+  ).all().map(sem => ({
+    ...sem,
+    evidence_episode_ids: safeJsonParse(sem.evidence_episode_ids, []),
+  }));
+
+  const procedures = db.prepare(
+    'SELECT id, content, state, trigger_conditions, evidence_episode_ids, success_count, failure_count, created_at, last_reinforced_at, retrieval_count FROM procedures'
+  ).all().map(proc => ({
+    ...proc,
+    evidence_episode_ids: safeJsonParse(proc.evidence_episode_ids, []),
+  }));
+
+  const causalLinks = db.prepare('SELECT * FROM causal_links').all();
+
+  const contradictions = db.prepare(
+    'SELECT id, claim_a_id, claim_a_type, claim_b_id, claim_b_type, state, resolution, resolved_at, reopened_at, reopen_evidence_id, created_at FROM contradictions'
+  ).all();
+
+  const consolidationRuns = db.prepare(
+    'SELECT id, input_episode_ids, output_memory_ids, started_at, completed_at, status FROM consolidation_runs'
+  ).all().map(run => ({
+    ...run,
+    input_episode_ids: safeJsonParse(run.input_episode_ids, []),
+    output_memory_ids: safeJsonParse(run.output_memory_ids, []),
+  }));
+
+  const configRows = db.prepare('SELECT key, value FROM audrey_config').all();
+  const config = Object.fromEntries(configRows.map(r => [r.key, r.value]));
+
+  return {
+    version: pkg.version,
+    exportedAt: new Date().toISOString(),
+    episodes,
+    semantics,
+    procedures,
+    causalLinks,
+    contradictions,
+    consolidationRuns,
+    config,
+  };
+}

package/src/import.js

@@ -0,0 +1,116 @@
+export async function importMemories(db, embeddingProvider, snapshot) {
+  const existingEpisodes = db.prepare('SELECT COUNT(*) as c FROM episodes').get().c;
+  if (existingEpisodes > 0) {
+    throw new Error('Cannot import into a database that is not empty');
+  }
+
+  const insertEpisode = db.prepare(`
+    INSERT INTO episodes (id, content, source, source_reliability, salience, tags,
+      causal_trigger, causal_consequence, created_at, supersedes, superseded_by, consolidated)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `);
+
+  const insertVecEpisode = db.prepare(
+    'INSERT INTO vec_episodes(id, embedding, source, consolidated) VALUES (?, ?, ?, ?)'
+  );
+
+  const insertSemantic = db.prepare(`
+    INSERT INTO semantics (id, content, state, conditions, evidence_episode_ids,
+      evidence_count, supporting_count, contradicting_count, source_type_diversity,
+      consolidation_checkpoint, created_at, last_reinforced_at, retrieval_count, challenge_count)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `);
+
+  const insertVecSemantic = db.prepare(
+    'INSERT INTO vec_semantics(id, embedding, state) VALUES (?, ?, ?)'
+  );
+
+  const insertProcedure = db.prepare(`
+    INSERT INTO procedures (id, content, state, trigger_conditions, evidence_episode_ids,
+      success_count, failure_count, created_at, last_reinforced_at, retrieval_count)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `);
+
+  const insertVecProcedure = db.prepare(
+    'INSERT INTO vec_procedures(id, embedding, state) VALUES (?, ?, ?)'
+  );
+
+  const insertCausalLink = db.prepare(`
+    INSERT INTO causal_links (id, cause_id, effect_id, link_type, mechanism, confidence, evidence_count, created_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+  `);
+
+  const insertContradiction = db.prepare(`
+    INSERT INTO contradictions (id, claim_a_id, claim_a_type, claim_b_id, claim_b_type,
+      state, resolution, resolved_at, reopened_at, reopen_evidence_id, created_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `);
+
+  const insertConsolidationRun = db.prepare(`
+    INSERT INTO consolidation_runs (id, input_episode_ids, output_memory_ids, started_at, completed_at, status)
+    VALUES (?, ?, ?, ?, ?, ?)
+  `);
+
+  for (const ep of snapshot.episodes) {
+    const tags = ep.tags ? JSON.stringify(ep.tags) : null;
+    insertEpisode.run(
+      ep.id, ep.content, ep.source, ep.source_reliability, ep.salience ?? 0.5,
+      tags, ep.causal_trigger ?? null, ep.causal_consequence ?? null,
+      ep.created_at, ep.supersedes ?? null, ep.superseded_by ?? null, ep.consolidated ?? 0,
+    );
+
+    const vector = await embeddingProvider.embed(ep.content);
+    const buffer = embeddingProvider.vectorToBuffer(vector);
+    insertVecEpisode.run(ep.id, buffer, ep.source, BigInt(ep.consolidated ?? 0));
+  }
+
+  for (const sem of (snapshot.semantics || [])) {
+    insertSemantic.run(
+      sem.id, sem.content, sem.state, sem.conditions ?? null,
+      JSON.stringify(sem.evidence_episode_ids || []),
+      sem.evidence_count ?? 0, sem.supporting_count ?? 0, sem.contradicting_count ?? 0,
+      sem.source_type_diversity ?? 0, sem.consolidation_checkpoint ?? null,
+      sem.created_at, sem.last_reinforced_at ?? null, sem.retrieval_count ?? 0, sem.challenge_count ?? 0,
+    );
+
+    const vector = await embeddingProvider.embed(sem.content);
+    const buffer = embeddingProvider.vectorToBuffer(vector);
+    insertVecSemantic.run(sem.id, buffer, sem.state);
+  }
+
+  for (const proc of (snapshot.procedures || [])) {
+    insertProcedure.run(
+      proc.id, proc.content, proc.state, proc.trigger_conditions ?? null,
+      JSON.stringify(proc.evidence_episode_ids || []),
+      proc.success_count ?? 0, proc.failure_count ?? 0,
+      proc.created_at, proc.last_reinforced_at ?? null, proc.retrieval_count ?? 0,
+    );
+
+    const vector = await embeddingProvider.embed(proc.content);
+    const buffer = embeddingProvider.vectorToBuffer(vector);
+    insertVecProcedure.run(proc.id, buffer, proc.state);
+  }
+
+  for (const link of (snapshot.causalLinks || [])) {
+    insertCausalLink.run(
+      link.id, link.cause_id, link.effect_id, link.link_type ?? 'causal',
+      link.mechanism ?? null, link.confidence ?? null, link.evidence_count ?? 1, link.created_at,
+    );
+  }
+
+  for (const con of (snapshot.contradictions || [])) {
+    insertContradiction.run(
+      con.id, con.claim_a_id, con.claim_a_type, con.claim_b_id, con.claim_b_type,
+      con.state, con.resolution ?? null, con.resolved_at ?? null,
+      con.reopened_at ?? null, con.reopen_evidence_id ?? null, con.created_at,
+    );
+  }
+
+  for (const run of (snapshot.consolidationRuns || [])) {
+    insertConsolidationRun.run(
+      run.id, JSON.stringify(run.input_episode_ids || []),
+      JSON.stringify(run.output_memory_ids || []),
+      run.started_at ?? null, run.completed_at ?? null, run.status,
+    );
+  }
+}

package/src/index.js

@@ -10,3 +10,6 @@ export {
   buildCausalArticulationPrompt,
   buildContextResolutionPrompt,
 } from './prompts.js';
+export { exportMemories } from './export.js';
+export { importMemories } from './import.js';
+export { suggestConsolidationParams } from './adaptive.js';

package/src/llm.js

@@ -92,10 +92,11 @@ export class MockLLMProvider {
 /** @implements {LLMProvider} */
 export class AnthropicLLMProvider {
   /** @param {Partial<AnthropicLLMConfig>} [config={}] */
-  constructor({ apiKey, model = 'claude-sonnet-4-6', maxTokens = 1024 } = {}) {
+  constructor({ apiKey, model = 'claude-sonnet-4-6', maxTokens = 1024, timeout = 30000 } = {}) {
     this.apiKey = apiKey || process.env.ANTHROPIC_API_KEY;
     this.model = model;
     this.maxTokens = maxTokens;
+    this.timeout = timeout;
     this.modelName = model;
     this.modelVersion = 'latest';
   }
@@ -116,23 +117,30 @@ export class AnthropicLLMProvider {
     };
     if (systemMsg) body.system = systemMsg;
 
-    const response = await fetch('https://api.anthropic.com/v1/messages', {
-      method: 'POST',
-      headers: {
-        'x-api-key': this.apiKey,
-        'anthropic-version': '2023-06-01',
-        'content-type': 'application/json',
-      },
-      body: JSON.stringify(body),
-    });
-
-    if (!response.ok) {
-      throw new Error(`Anthropic API error: ${response.status}`);
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeout);
+    try {
+      const response = await fetch('https://api.anthropic.com/v1/messages', {
+        method: 'POST',
+        headers: {
+          'x-api-key': this.apiKey,
+          'anthropic-version': '2023-06-01',
+          'content-type': 'application/json',
+        },
+        body: JSON.stringify(body),
+        signal: controller.signal,
+      });
+
+      if (!response.ok) {
+        throw new Error(`Anthropic API error: ${response.status}`);
+      }
+
+      const data = await response.json();
+      const text = data.content?.[0]?.text || '';
+      return { content: text };
+    } finally {
+      clearTimeout(timer);
     }
-
-    const data = await response.json();
-    const text = data.content?.[0]?.text || '';
-    return { content: text };
   }
 
   /**
@@ -142,17 +150,22 @@ export class AnthropicLLMProvider {
    */
   async json(messages, options = {}) {
     const result = await this.complete(messages, options);
-    return JSON.parse(result.content);
+    try {
+      return JSON.parse(result.content);
+    } catch {
+      throw new Error(`Failed to parse LLM response as JSON: ${result.content.slice(0, 200)}`);
+    }
   }
 }
 
 /** @implements {LLMProvider} */
 export class OpenAILLMProvider {
   /** @param {Partial<OpenAILLMConfig>} [config={}] */
-  constructor({ apiKey, model = 'gpt-4o', maxTokens = 1024 } = {}) {
+  constructor({ apiKey, model = 'gpt-4o', maxTokens = 1024, timeout = 30000 } = {}) {
     this.apiKey = apiKey || process.env.OPENAI_API_KEY;
     this.model = model;
     this.maxTokens = maxTokens;
+    this.timeout = timeout;
     this.modelName = model;
     this.modelVersion = 'latest';
   }
@@ -169,22 +182,29 @@ export class OpenAILLMProvider {
       messages,
     };
 
-    const response = await fetch('https://api.openai.com/v1/chat/completions', {
-      method: 'POST',
-      headers: {
-        'Authorization': `Bearer ${this.apiKey}`,
-        'Content-Type': 'application/json',
-      },
-      body: JSON.stringify(body),
-    });
-
-    if (!response.ok) {
-      throw new Error(`OpenAI API error: ${response.status}`);
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeout);
+    try {
+      const response = await fetch('https://api.openai.com/v1/chat/completions', {
+        method: 'POST',
+        headers: {
+          'Authorization': `Bearer ${this.apiKey}`,
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify(body),
+        signal: controller.signal,
+      });
+
+      if (!response.ok) {
+        throw new Error(`OpenAI API error: ${response.status}`);
+      }
+
+      const data = await response.json();
+      const text = data.choices?.[0]?.message?.content || '';
+      return { content: text };
+    } finally {
+      clearTimeout(timer);
     }
-
-    const data = await response.json();
-    const text = data.choices?.[0]?.message?.content || '';
-    return { content: text };
   }
 
   /**
@@ -194,7 +214,11 @@ export class OpenAILLMProvider {
    */
   async json(messages, options = {}) {
     const result = await this.complete(messages, options);
-    return JSON.parse(result.content);
+    try {
+      return JSON.parse(result.content);
+    } catch {
+      throw new Error(`Failed to parse LLM response as JSON: ${result.content.slice(0, 200)}`);
+    }
   }
 }
 

package/src/recall.js

@@ -1,48 +1,57 @@
 import { computeConfidence, DEFAULT_HALF_LIVES } from './confidence.js';
 import { daysBetween, safeJsonParse } from './utils.js';
 
-function computeEpisodicConfidence(ep, now) {
+function computeEpisodicConfidence(ep, now, confidenceConfig = {}) {
   const ageDays = daysBetween(ep.created_at, now);
+  const halfLives = confidenceConfig.halfLives || DEFAULT_HALF_LIVES;
   return computeConfidence({
     sourceType: ep.source,
     supportingCount: 1,
     contradictingCount: 0,
     ageDays,
-    halfLifeDays: DEFAULT_HALF_LIVES.episodic,
+    halfLifeDays: halfLives.episodic ?? DEFAULT_HALF_LIVES.episodic,
     retrievalCount: 0,
     daysSinceRetrieval: ageDays,
+    weights: confidenceConfig.weights,
+    customSourceReliability: confidenceConfig.sourceReliability,
   });
 }
 
-function computeSemanticConfidence(sem, now) {
+function computeSemanticConfidence(sem, now, confidenceConfig = {}) {
   const ageDays = daysBetween(sem.created_at, now);
   const daysSinceRetrieval = sem.last_reinforced_at
     ? daysBetween(sem.last_reinforced_at, now)
     : ageDays;
+  const halfLives = confidenceConfig.halfLives || DEFAULT_HALF_LIVES;
   return computeConfidence({
     sourceType: 'tool-result',
     supportingCount: sem.supporting_count || 0,
     contradictingCount: sem.contradicting_count || 0,
     ageDays,
-    halfLifeDays: DEFAULT_HALF_LIVES.semantic,
+    halfLifeDays: halfLives.semantic ?? DEFAULT_HALF_LIVES.semantic,
     retrievalCount: sem.retrieval_count || 0,
     daysSinceRetrieval,
+    weights: confidenceConfig.weights,
+    customSourceReliability: confidenceConfig.sourceReliability,
   });
 }
 
-function computeProceduralConfidence(proc, now) {
+function computeProceduralConfidence(proc, now, confidenceConfig = {}) {
   const ageDays = daysBetween(proc.created_at, now);
   const daysSinceRetrieval = proc.last_reinforced_at
     ? daysBetween(proc.last_reinforced_at, now)
     : ageDays;
+  const halfLives = confidenceConfig.halfLives || DEFAULT_HALF_LIVES;
   return computeConfidence({
     sourceType: 'tool-result',
     supportingCount: proc.success_count || 0,
     contradictingCount: proc.failure_count || 0,
     ageDays,
-    halfLifeDays: DEFAULT_HALF_LIVES.procedural,
+    halfLifeDays: halfLives.procedural ?? DEFAULT_HALF_LIVES.procedural,
     retrievalCount: proc.retrieval_count || 0,
     daysSinceRetrieval,
+    weights: confidenceConfig.weights,
+    customSourceReliability: confidenceConfig.sourceReliability,
   });
 }
 
@@ -112,7 +121,7 @@ function buildProceduralEntry(proc, confidence, score, includeProvenance) {
   return entry;
 }
 
-function knnEpisodic(db, queryBuffer, candidateK, now, minConfidence, includeProvenance) {
+function knnEpisodic(db, queryBuffer, candidateK, now, minConfidence, includeProvenance, confidenceConfig) {
   const rows = db.prepare(`
     SELECT e.*, (1.0 - v.distance) AS similarity
     FROM vec_episodes v
@@ -124,7 +133,7 @@ function knnEpisodic(db, queryBuffer, candidateK, now, minConfidence, includePro
 
   const results = [];
   for (const row of rows) {
-    const confidence = computeEpisodicConfidence(row, now);
+    const confidence = computeEpisodicConfidence(row, now, confidenceConfig);
     if (confidence < minConfidence) continue;
     const score = row.similarity * confidence;
     results.push(buildEpisodicEntry(row, confidence, score, includeProvenance));
@@ -132,7 +141,7 @@ function knnEpisodic(db, queryBuffer, candidateK, now, minConfidence, includePro
   return results;
 }
 
-function knnSemantic(db, queryBuffer, candidateK, now, minConfidence, includeProvenance, includeDormant) {
+function knnSemantic(db, queryBuffer, candidateK, now, minConfidence, includeProvenance, includeDormant, confidenceConfig) {
   let stateFilter;
   if (includeDormant) {
     stateFilter = "AND (v.state = 'active' OR v.state = 'context_dependent' OR v.state = 'dormant')";
@@ -152,7 +161,7 @@ function knnSemantic(db, queryBuffer, candidateK, now, minConfidence, includePro
   const results = [];
   const matchedIds = [];
   for (const row of rows) {
-    const confidence = computeSemanticConfidence(row, now);
+    const confidence = computeSemanticConfidence(row, now, confidenceConfig);
     if (confidence < minConfidence) continue;
     const score = row.similarity * confidence;
     matchedIds.push(row.id);
@@ -161,7 +170,7 @@ function knnSemantic(db, queryBuffer, candidateK, now, minConfidence, includePro
   return { results, matchedIds };
 }
 
-function knnProcedural(db, queryBuffer, candidateK, now, minConfidence, includeProvenance, includeDormant) {
+function knnProcedural(db, queryBuffer, candidateK, now, minConfidence, includeProvenance, includeDormant, confidenceConfig) {
   let stateFilter;
   if (includeDormant) {
     stateFilter = "AND (v.state = 'active' OR v.state = 'context_dependent' OR v.state = 'dormant')";
@@ -181,7 +190,7 @@ function knnProcedural(db, queryBuffer, candidateK, now, minConfidence, includeP
   const results = [];
   const matchedIds = [];
   for (const row of rows) {
-    const confidence = computeProceduralConfidence(row, now);
+    const confidence = computeProceduralConfidence(row, now, confidenceConfig);
     if (confidence < minConfidence) continue;
     const score = row.similarity * confidence;
     matchedIds.push(row.id);
@@ -204,6 +213,7 @@ export async function* recallStream(db, embeddingProvider, query, options = {})
     limit = 10,
     includeProvenance = false,
     includeDormant = false,
+    confidenceConfig,
   } = options;
 
   const queryVector = await embeddingProvider.embed(query);
@@ -215,13 +225,13 @@ export async function* recallStream(db, embeddingProvider, query, options = {})
   const allResults = [];
 
   if (searchTypes.includes('episodic')) {
-    const episodic = knnEpisodic(db, queryBuffer, candidateK, now, minConfidence, includeProvenance);
+    const episodic = knnEpisodic(db, queryBuffer, candidateK, now, minConfidence, includeProvenance, confidenceConfig);
     allResults.push(...episodic);
   }
 
   if (searchTypes.includes('semantic')) {
     const { results: semResults, matchedIds: semIds } =
-      knnSemantic(db, queryBuffer, candidateK, now, minConfidence, includeProvenance, includeDormant);
+      knnSemantic(db, queryBuffer, candidateK, now, minConfidence, includeProvenance, includeDormant, confidenceConfig);
     allResults.push(...semResults);
 
     if (semIds.length > 0) {
@@ -237,7 +247,7 @@ export async function* recallStream(db, embeddingProvider, query, options = {})
 
   if (searchTypes.includes('procedural')) {
     const { results: procResults, matchedIds: procIds } =
-      knnProcedural(db, queryBuffer, candidateK, now, minConfidence, includeProvenance, includeDormant);
+      knnProcedural(db, queryBuffer, candidateK, now, minConfidence, includeProvenance, includeDormant, confidenceConfig);
     allResults.push(...procResults);
 
     if (procIds.length > 0) {