audrey 0.3.0 → 0.3.1

package/README.md

@@ -24,49 +24,119 @@ Audrey fixes all of this by modeling memory the way the brain does:
 
 ## Install
 
+### MCP Server for Claude Code (one command)
+
+```bash
+npx audrey install
+```
+
+That's it. Audrey auto-detects API keys from your environment:
+
+- `OPENAI_API_KEY` set? Uses real OpenAI embeddings (1536d) for semantic search.
+- `ANTHROPIC_API_KEY` set? Enables LLM-powered consolidation and contradiction detection.
+- Neither? Runs with mock embeddings — fully functional, upgrade anytime.
+
+To upgrade later, set the keys and re-run `npx audrey install`.
+
+```bash
+# Check status
+npx audrey status
+
+# Uninstall
+npx audrey uninstall
+```
+
+Every Claude Code session now has 5 memory tools: `memory_encode`, `memory_recall`, `memory_consolidate`, `memory_introspect`, `memory_resolve_truth`.
+
+### SDK in Your Code
+
 ```bash
 npm install audrey
 ```
 
-Zero external infrastructure. One SQLite file. That's it.
+Zero external infrastructure. One SQLite file.
 
-## Quick Start
+## Usage
 
 ```js
 import { Audrey } from 'audrey';
 
+// 1. Create a brain
 const brain = new Audrey({
   dataDir: './agent-memory',
   agent: 'my-agent',
-  embedding: { provider: 'openai', model: 'text-embedding-3-small' },
+  embedding: { provider: 'mock', dimensions: 8 },  // or 'openai' for production
 });
 
-// Agent observes something
+// 2. Encode observations
 await brain.encode({
   content: 'Stripe API returns 429 above 100 req/s',
   source: 'direct-observation',
-  salience: 0.9,
-  causal: { trigger: 'batch-payment-job', consequence: 'queue-stalled' },
   tags: ['stripe', 'rate-limit'],
 });
 
-// Later — agent encounters Stripe again
-const memories = await brain.recall('stripe rate limits', {
-  minConfidence: 0.5,
-  types: ['semantic', 'procedural'],
-  limit: 5,
-});
+// 3. Recall what you know
+const memories = await brain.recall('stripe rate limits', { limit: 5 });
+// Returns: [{ content, type, confidence, score, ... }]
 
-// Run consolidation (the "sleep" cycle)
+// 4. Consolidate episodes into principles (the "sleep" cycle)
 await brain.consolidate();
 
-// Check brain health
+// 5. Check brain health
 const stats = brain.introspect();
 // { episodic: 47, semantic: 12, procedural: 3, dormant: 8, ... }
 
+// 6. Clean up
 brain.close();
 ```
 
+### Configuration
+
+```js
+const brain = new Audrey({
+  dataDir: './audrey-data',     // SQLite database directory
+  agent: 'my-agent',           // Agent identifier
+
+  // Embedding provider (required)
+  embedding: {
+    provider: 'mock',          // 'mock' for testing, 'openai' for production
+    dimensions: 8,             // 8 for mock, 1536 for openai text-embedding-3-small
+    apiKey: '...',             // Required for openai
+  },
+
+  // LLM provider (optional — enables smart consolidation + contradiction detection)
+  llm: {
+    provider: 'anthropic',     // 'mock', 'anthropic', or 'openai'
+    apiKey: '...',             // Required for anthropic/openai
+    model: 'claude-sonnet-4-6', // Optional model override
+  },
+
+  // Consolidation settings
+  consolidation: {
+    minEpisodes: 3,            // Minimum cluster size for principle extraction
+  },
+
+  // Decay settings
+  decay: {
+    dormantThreshold: 0.1,     // Below this confidence = dormant
+  },
+});
+```
+
+**Without an LLM provider**, consolidation uses a default text-based extractor and contradiction detection is similarity-only. **With an LLM provider**, Audrey extracts real generalized principles, detects semantic contradictions, and resolves context-dependent truths.
+
+### Environment Variables (MCP Server)
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `AUDREY_DATA_DIR` | `~/.audrey/data` | SQLite database directory |
+| `AUDREY_AGENT` | `claude-code` | Agent identifier |
+| `AUDREY_EMBEDDING_PROVIDER` | `mock` | `mock` or `openai` |
+| `AUDREY_EMBEDDING_DIMENSIONS` | `8` | Vector dimensions (1536 for openai) |
+| `OPENAI_API_KEY` | — | Required when embedding/LLM provider is openai |
+| `AUDREY_LLM_PROVIDER` | — | `mock`, `anthropic`, or `openai` |
+| `ANTHROPIC_API_KEY` | — | Required when LLM provider is anthropic |
+
 ## Core Concepts
 
 ### Four Memory Types
@@ -176,25 +246,7 @@ Audrey's defenses:
 
 ### `new Audrey(config)`
 
-```js
-const brain = new Audrey({
-  dataDir: './audrey-data',       // Where the SQLite DB lives
-  agent: 'my-agent',             // Agent identifier
-  embedding: {
-    provider: 'openai',          // 'openai' | 'mock'
-    model: 'text-embedding-3-small',
-    apiKey: process.env.OPENAI_API_KEY,
-  },
-  consolidation: {
-    interval: '1h',              // Auto-consolidation interval
-    minEpisodes: 3,              // Minimum cluster size
-    confidenceTarget: 2.0,       // Adaptive threshold multiplier
-  },
-  decay: {
-    dormantThreshold: 0.1,       // Below this → dormant
-  },
-});
-```
+See [Configuration](#configuration) above for all options.
 
 ### `brain.encode(params)` → `Promise<string>`
 
@@ -252,6 +304,29 @@ Each result:
 
 Retrieval automatically reinforces matched memories (boosts confidence, resets decay clock).
 
+### `brain.encodeBatch(paramsList)` → `Promise<string[]>`
+
+Encode multiple episodes in one call. Same params as `encode()`, but as an array.
+
+```js
+const ids = await brain.encodeBatch([
+  { content: 'Stripe returned 429', source: 'direct-observation' },
+  { content: 'Redis timed out', source: 'tool-result' },
+  { content: 'User reports slow checkout', source: 'told-by-user' },
+]);
+```
+
+### `brain.recallStream(query, options)` → `AsyncGenerator<Memory>`
+
+Streaming version of `recall()`. Yields results one at a time. Supports early `break`.
+
+```js
+for await (const memory of brain.recallStream('stripe issues', { limit: 10 })) {
+  console.log(memory.content, memory.score);
+  if (memory.score > 0.9) break;
+}
+```
+
 ### `brain.consolidate(options)` → `Promise<ConsolidationResult>`
 
 Run the consolidation engine manually.
@@ -286,6 +361,15 @@ brain.rollback('01ABC...');
 // { rolledBackMemories: 3, restoredEpisodes: 9 }
 ```
 
+### `brain.resolveTruth(contradictionId)` → `Promise<Resolution>`
+
+Resolve an open contradiction using LLM reasoning. Requires an LLM provider configured.
+
+```js
+const resolution = await brain.resolveTruth('contradiction-id');
+// { resolution: 'context_dependent', conditions: { a: 'live keys', b: 'test keys' }, explanation: '...' }
+```
+
 ### `brain.introspect()` → `Stats`
 
 Get memory system health stats.
@@ -310,6 +394,7 @@ Full audit trail of all consolidation runs.
 ```js
 brain.on('encode', ({ id, content, source }) => { ... });
 brain.on('reinforcement', ({ episodeId, targetId, similarity }) => { ... });
+brain.on('contradiction', ({ episodeId, contradictionId, semanticId, resolution }) => { ... });
 brain.on('consolidation', ({ runId, principlesExtracted }) => { ... });
 brain.on('decay', ({ totalEvaluated, transitionedToDormant }) => { ... });
 brain.on('rollback', ({ runId, rolledBackMemories }) => { ... });
@@ -330,37 +415,48 @@ audrey-data/
 ```
 src/
   audrey.js          Main class. EventEmitter. Public API surface.
+  causal.js          Causal graph management. LLM-powered mechanism articulation.
   confidence.js      Compositional confidence formula. Pure math.
-  consolidate.js     "Sleep" cycle. Cluster → extract → promote.
-  db.js              SQLite schema. 6 tables. CHECK constraints. Indexes.
+  consolidate.js     "Sleep" cycle. KNN clustering → LLM extraction → promote.
+  db.js              SQLite + sqlite-vec. Schema, vec0 tables, migrations.
   decay.js           Ebbinghaus forgetting curves.
-  embedding.js       Pluggable providers (Mock, OpenAI).
-  encode.js          Immutable episodic memory creation.
+  embedding.js       Pluggable providers (Mock, OpenAI). Batch embedding.
+  encode.js          Immutable episodic memory creation + vec0 writes.
   introspect.js      Health dashboard queries.
-  recall.js          Confidence-weighted vector retrieval.
+  llm.js             Pluggable LLM providers (Mock, Anthropic, OpenAI).
+  prompts.js         Structured prompt templates for LLM operations.
+  recall.js          KNN retrieval + confidence scoring + async streaming.
   rollback.js        Undo consolidation runs.
-  utils.js           Shared: cosine similarity, date math, safe JSON parse.
-  validate.js        Reinforcement + contradiction lifecycle.
+  utils.js           Date math, safe JSON parse.
+  validate.js        KNN validation + LLM contradiction detection.
   index.js           Barrel export.
-```
 
-### Database Schema (6 tables)
+mcp-server/
+  index.js           MCP tool server (5 tools, stdio transport) + CLI subcommands.
+  config.js          Shared config (env var parsing, install arg builder).
+```
 
-| Table | Purpose | Key Columns |
-|---|---|---|
-| `episodes` | Immutable raw events | content, embedding, source, salience, causal_trigger/consequence, supersedes |
-| `semantics` | Consolidated principles | content, embedding, state, evidence_episode_ids, source_type_diversity |
-| `procedures` | Learned workflows | content, embedding, trigger_conditions, success/failure_count |
-| `causal_links` | Why things happened | cause_id, effect_id, link_type (causal/correlational/temporal), mechanism |
-| `contradictions` | Dispute tracking | claim_a/b_id, state (open/resolved/context_dependent/reopened), resolution |
-| `consolidation_runs` | Audit trail | input_episode_ids, output_memory_ids, status, checkpoint_cursor |
+### Database Schema
 
-All mutations use SQLite transactions for atomicity. CHECK constraints enforce valid states and source types.
+| Table | Purpose |
+|---|---|
+| `episodes` | Immutable raw events (content, source, salience, causal context) |
+| `semantics` | Consolidated principles (content, state, evidence chain) |
+| `procedures` | Learned workflows (trigger conditions, success/failure counts) |
+| `causal_links` | Causal relationships (cause, effect, mechanism, link type) |
+| `contradictions` | Dispute tracking (claims, state, resolution) |
+| `consolidation_runs` | Audit trail (inputs, outputs, status) |
+| `vec_episodes` | sqlite-vec KNN index for episode embeddings |
+| `vec_semantics` | sqlite-vec KNN index for semantic embeddings |
+| `vec_procedures` | sqlite-vec KNN index for procedural embeddings |
+| `audrey_config` | Dimension configuration and metadata |
+
+All mutations use SQLite transactions. CHECK constraints enforce valid states and source types. Vector search uses sqlite-vec with cosine distance.
 
 ## Running Tests
 
 ```bash
-npm test          # 104 tests, ~760ms
+npm test          # 194 tests across 17 files
 npm run test:watch
 ```
 
@@ -431,8 +527,9 @@ Demonstrates the full pipeline: encode 3 rate-limit observations → consolidate
 - [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] Registration script for Claude Code (`mcp-server/register.sh`)
-- [x] 184 tests across 17 test files
+- [x] One-command install: `npx audrey install` (auto-detects API keys)
+- [x] CLI subcommands: `install`, `uninstall`, `status`
+- [x] 194 tests across 17 test files
 
 ### v0.3.5 — Embedding Migration (deferred from v0.3.0)
 

package/mcp-server/config.js

@@ -0,0 +1,60 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+export const VERSION = '0.3.1';
+export const SERVER_NAME = 'audrey-memory';
+export const DEFAULT_DATA_DIR = join(homedir(), '.audrey', 'data');
+
+export function buildAudreyConfig() {
+  const dataDir = process.env.AUDREY_DATA_DIR || DEFAULT_DATA_DIR;
+  const agent = process.env.AUDREY_AGENT || 'claude-code';
+  const embProvider = process.env.AUDREY_EMBEDDING_PROVIDER || 'mock';
+  const embDimensions = parseInt(process.env.AUDREY_EMBEDDING_DIMENSIONS || '8', 10);
+  const llmProvider = process.env.AUDREY_LLM_PROVIDER;
+
+  const config = {
+    dataDir,
+    agent,
+    embedding: { provider: embProvider, dimensions: embDimensions },
+  };
+
+  if (embProvider === 'openai') {
+    config.embedding.apiKey = process.env.OPENAI_API_KEY;
+  }
+
+  if (llmProvider === 'anthropic') {
+    config.llm = { provider: 'anthropic', apiKey: process.env.ANTHROPIC_API_KEY };
+  } else if (llmProvider === 'openai') {
+    config.llm = { provider: 'openai', apiKey: process.env.OPENAI_API_KEY };
+  } else if (llmProvider === 'mock') {
+    config.llm = { provider: 'mock' };
+  }
+
+  return config;
+}
+
+export function buildInstallArgs(env = process.env) {
+  const envPairs = [`AUDREY_DATA_DIR=${DEFAULT_DATA_DIR}`];
+
+  if (env.OPENAI_API_KEY) {
+    envPairs.push('AUDREY_EMBEDDING_PROVIDER=openai');
+    envPairs.push('AUDREY_EMBEDDING_DIMENSIONS=1536');
+    envPairs.push(`OPENAI_API_KEY=${env.OPENAI_API_KEY}`);
+  } else {
+    envPairs.push('AUDREY_EMBEDDING_PROVIDER=mock');
+    envPairs.push('AUDREY_EMBEDDING_DIMENSIONS=8');
+  }
+
+  if (env.ANTHROPIC_API_KEY) {
+    envPairs.push('AUDREY_LLM_PROVIDER=anthropic');
+    envPairs.push(`ANTHROPIC_API_KEY=${env.ANTHROPIC_API_KEY}`);
+  }
+
+  const args = ['mcp', 'add', '-s', 'user', SERVER_NAME];
+  for (const pair of envPairs) {
+    args.push('-e', pair);
+  }
+  args.push('--', 'npx', 'audrey');
+
+  return args;
+}

package/mcp-server/index.js

@@ -4,33 +4,121 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { z } from 'zod';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
+import { existsSync, readFileSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
 import { Audrey } from '../src/index.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'];
 const VALID_TYPES = ['episodic', 'semantic', 'procedural'];
 
-function buildAudreyConfig() {
-  const dataDir = process.env.AUDREY_DATA_DIR || join(homedir(), '.audrey', 'data');
-  const agent = process.env.AUDREY_AGENT || 'claude-code';
-  const embProvider = process.env.AUDREY_EMBEDDING_PROVIDER || 'mock';
-  const embDimensions = parseInt(process.env.AUDREY_EMBEDDING_DIMENSIONS || '8', 10);
-  const llmProvider = process.env.AUDREY_LLM_PROVIDER;
-
-  const config = {
-    dataDir,
-    agent,
-    embedding: { provider: embProvider, dimensions: embDimensions },
-  };
-
-  if (llmProvider === 'anthropic') {
-    config.llm = { provider: 'anthropic', apiKey: process.env.ANTHROPIC_API_KEY };
-  } else if (llmProvider === 'openai') {
-    config.llm = { provider: 'openai', apiKey: process.env.OPENAI_API_KEY };
-  } else if (llmProvider === 'mock') {
-    config.llm = { provider: 'mock' };
+const subcommand = process.argv[2];
+
+if (subcommand === 'install') {
+  install();
+} else if (subcommand === 'uninstall') {
+  uninstall();
+} else if (subcommand === 'status') {
+  status();
+} else {
+  main().catch(err => {
+    console.error('[audrey-mcp] fatal:', err);
+    process.exit(1);
+  });
+}
+
+function install() {
+  try {
+    execFileSync('claude', ['--version'], { stdio: 'ignore' });
+  } catch {
+    console.error('Error: claude CLI not found. Install Claude Code first: https://docs.anthropic.com/en/docs/claude-code');
+    process.exit(1);
+  }
+
+  if (process.env.OPENAI_API_KEY) {
+    console.log('Detected OPENAI_API_KEY — using OpenAI embeddings (1536d)');
+  } else {
+    console.log('No OPENAI_API_KEY found — using mock embeddings (upgrade anytime by re-running with the key set)');
+  }
+
+  if (process.env.ANTHROPIC_API_KEY) {
+    console.log('Detected ANTHROPIC_API_KEY — enabling LLM-powered consolidation + contradiction detection');
+  }
+
+  const args = buildInstallArgs(process.env);
+
+  try {
+    execFileSync('claude', args, { stdio: 'inherit' });
+  } catch {
+    console.error('Failed to register MCP server. Is Claude Code installed and on your PATH?');
+    process.exit(1);
+  }
+
+  console.log(`
+Audrey registered as "${SERVER_NAME}" with Claude Code.
+
+5 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
+
+Data stored in: ${DEFAULT_DATA_DIR}
+Verify: claude mcp list
+`);
+}
+
+function uninstall() {
+  try {
+    execFileSync('claude', ['--version'], { stdio: 'ignore' });
+  } catch {
+    console.error('Error: claude CLI not found.');
+    process.exit(1);
+  }
+
+  try {
+    execFileSync('claude', ['mcp', 'remove', SERVER_NAME], { stdio: 'inherit' });
+    console.log(`Removed "${SERVER_NAME}" from Claude Code.`);
+  } catch {
+    console.error(`Failed to remove "${SERVER_NAME}". It may not be registered.`);
+    process.exit(1);
+  }
+}
+
+function status() {
+  let registered = false;
+  const claudeJsonPath = join(homedir(), '.claude.json');
+  try {
+    const claudeConfig = JSON.parse(readFileSync(claudeJsonPath, 'utf-8'));
+    registered = SERVER_NAME in (claudeConfig.mcpServers || {});
+  } catch {
+    // claude.json doesn't exist or isn't readable
   }
 
-  return config;
+  console.log(`Registration: ${registered ? 'active' : 'not registered'}`);
+
+  if (existsSync(DEFAULT_DATA_DIR)) {
+    try {
+      const audrey = new Audrey({
+        dataDir: DEFAULT_DATA_DIR,
+        agent: 'status-check',
+        embedding: { provider: 'mock', dimensions: 8 },
+      });
+      const stats = audrey.introspect();
+      audrey.close();
+      console.log(`Data directory: ${DEFAULT_DATA_DIR}`);
+      console.log(`Memories: ${stats.episodic} episodic, ${stats.semantic} semantic, ${stats.procedural} procedural`);
+      console.log(`Dormant: ${stats.dormant}`);
+      console.log(`Causal links: ${stats.causalLinks}`);
+      console.log(`Contradictions: ${stats.contradictions.open} open, ${stats.contradictions.resolved} resolved`);
+      console.log(`Consolidation runs: ${stats.totalConsolidationRuns}`);
+    } catch (err) {
+      console.log(`Data directory: ${DEFAULT_DATA_DIR} (exists but could not read: ${err.message})`);
+    }
+  } else {
+    console.log(`Data directory: ${DEFAULT_DATA_DIR} (not yet created — will be created on first use)`);
+  }
 }
 
 function toolResult(data) {
@@ -44,11 +132,15 @@ function toolError(err) {
 async function main() {
   const config = buildAudreyConfig();
   const audrey = new Audrey(config);
-  console.error(`[audrey-mcp] started — agent=${config.agent} dataDir=${config.dataDir}`);
+
+  const embLabel = config.embedding.provider === 'mock'
+    ? 'mock embeddings — set OPENAI_API_KEY for real semantic search'
+    : `${config.embedding.provider} embeddings (${config.embedding.dimensions}d)`;
+  console.error(`[audrey-mcp] v${VERSION} started — agent=${config.agent} dataDir=${config.dataDir} (${embLabel})`);
 
   const server = new McpServer({
-    name: 'audrey-memory',
-    version: '0.3.0',
+    name: SERVER_NAME,
+    version: VERSION,
   });
 
   server.tool(
@@ -148,8 +240,3 @@ async function main() {
     process.exit(0);
   });
 }
-
-main().catch(err => {
-  console.error('[audrey-mcp] fatal:', err);
-  process.exit(1);
-});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "audrey",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "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",
@@ -9,7 +9,8 @@
     "./mcp": "./mcp-server/index.js"
   },
   "bin": {
-    "audrey-mcp": "./mcp-server/index.js"
+    "audrey": "mcp-server/index.js",
+    "audrey-mcp": "mcp-server/index.js"
   },
   "files": [
     "src/",
@@ -50,7 +51,7 @@
   ],
   "repository": {
     "type": "git",
-    "url": "https://github.com/Evilander/Audrey.git"
+    "url": "git+https://github.com/Evilander/Audrey.git"
   },
   "homepage": "https://github.com/Evilander/Audrey",
   "bugs": {