audrey 0.3.1 → 0.3.3

package/README.md

@@ -403,7 +403,7 @@ brain.on('error', (err) => { ... });
 
 ### `brain.close()`
 
-Close the database connection and stop auto-consolidation.
+Close the database connection.
 
 ## Architecture
 
@@ -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,28 +522,37 @@ 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 (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`
 - [x] Configuration via environment variables (data dir, embedding provider, LLM provider)
 - [x] One-command install: `npx audrey install` (auto-detects API keys)
 - [x] CLI subcommands: `install`, `uninstall`, `status`
+- [x] JSDoc type annotations on all public exports (16 source files)
+- [x] Published to npm with proper package metadata
 - [x] 194 tests across 17 test files
 
-### v0.3.5 — Embedding Migration (deferred from v0.3.0)
+### v0.3.3 — Hardening (current)
 
-- [ ] Embedding migration pipeline (re-embed when models change)
-- [ ] Re-consolidation queue (re-run consolidation with new embedding model)
+- [x] Fix status command dimension mismatch (read stored dimensions from existing database)
+- [x] Safe JSON parsing in LLM providers (descriptive errors on malformed responses)
+- [x] Fetch timeouts on all API calls (configurable, default 30s)
+- [x] Config validation in Audrey constructor (dormantThreshold, minEpisodes)
+- [x] encodeBatch error isolation tests
+- [x] 208 tests across 17 test files
 
 ### v0.4.0 — Type Safety & Developer Experience
 
 - [ ] Full TypeScript conversion with strict mode
-- [ ] JSDoc types on all exports (interim before TS conversion)
 - [ ] Published type declarations (.d.ts)
 - [ ] Schema versioning and migration system
 - [ ] Structured logging (optional, pluggable)
-- [ ] npm publish with proper package metadata
+
+### v0.4.5 — Embedding Migration (deferred from v0.3.0)
+
+- [ ] Embedding migration pipeline (re-embed when models change)
+- [ ] Re-consolidation queue (re-run consolidation with new embedding model)
 
 ### v0.5.0 — Advanced Memory Features
 

package/mcp-server/config.js

@@ -1,7 +1,7 @@
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 
-export const VERSION = '0.3.1';
+export const VERSION = '0.3.3';
 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'];
@@ -45,6 +46,13 @@ function install() {
     console.log('Detected ANTHROPIC_API_KEY — enabling LLM-powered consolidation + contradiction detection');
   }
 
+  // Remove existing entry first so re-installs work cleanly
+  try {
+    execFileSync('claude', ['mcp', 'remove', SERVER_NAME], { stdio: 'ignore' });
+  } catch {
+    // Not registered yet — that's fine
+  }
+
   const args = buildInstallArgs(process.env);
 
   try {
@@ -100,10 +108,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();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "audrey",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "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/audrey.js

@@ -81,15 +81,24 @@ export class Audrey extends EventEmitter {
     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.consolidationConfig = {
-      minEpisodes: consolidation.minEpisodes || 3,
-    };
-    this.decayConfig = { dormantThreshold: decay.dormantThreshold || 0.1 };
+    this.consolidationConfig = { minEpisodes };
+    this.decayConfig = { dormantThreshold };
   }
 
   _emitValidation(id, params) {

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 (
@@ -232,10 +232,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/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/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)}`);
+    }
   }
 }