audrey 0.8.0 → 0.9.0

package/README.md

@@ -1,6 +1,6 @@
 # Audrey
 
-Biological memory architecture for AI agents. Gives agents cognitive memory that decays, consolidates, self-validates, and learns from experience — not just a database.
+Biological memory architecture for AI agents. Memory that decays, consolidates, feels, and learns — not just a database.
 
 ## Why Audrey Exists
 
@@ -19,7 +19,7 @@ Audrey fixes all of this by modeling memory the way the brain does:
 | Neocortex | Semantic Memory | Consolidated principles and patterns |
 | Sleep Replay | Consolidation Engine | Extracts patterns from episodes, promotes to principles |
 | Prefrontal Cortex | Validation Engine | Truth-checking, contradiction detection |
-| Amygdala | Salience Scorer | Importance weighting for retention priority |
+| Amygdala | Affect System | Emotional encoding, arousal-salience coupling, mood-congruent recall |
 
 ## Install
 
@@ -67,22 +67,26 @@ const brain = new Audrey({
   embedding: { provider: 'mock', dimensions: 8 },  // or 'openai' for production
 });
 
-// 2. Encode observations
+// 2. Encode observations — with optional emotional context
 await brain.encode({
   content: 'Stripe API returns 429 above 100 req/s',
   source: 'direct-observation',
   tags: ['stripe', 'rate-limit'],
+  affect: { valence: -0.4, arousal: 0.7, label: 'frustration' },
 });
 
-// 3. Recall what you know
-const memories = await brain.recall('stripe rate limits', { limit: 5 });
-// Returns: [{ content, type, confidence, score, ... }]
+// 3. Recall what you know — mood-congruent retrieval
+const memories = await brain.recall('stripe rate limits', {
+  limit: 5,
+  mood: { valence: -0.3 },  // frustrated right now? memories encoded in frustration surface first
+});
 
 // 4. Filtered recall — by tag, source, or date range
 const recent = await brain.recall('stripe', {
   tags: ['rate-limit'],
   sources: ['direct-observation'],
   after: '2026-02-01T00:00:00Z',
+  context: { task: 'debugging', domain: 'payments' },  // context-dependent retrieval
 });
 
 // 5. Consolidate episodes into principles (the "sleep" cycle)
@@ -127,6 +131,31 @@ const brain = new Audrey({
     minEpisodes: 3,            // Minimum cluster size for principle extraction
   },
 
+  // Context-dependent retrieval (v0.8.0)
+  context: {
+    enabled: true,             // Enable encoding-specificity principle
+    weight: 0.3,               // Max 30% confidence boost on full context match
+  },
+
+  // Emotional memory (v0.9.0)
+  affect: {
+    enabled: true,             // Enable affect system
+    weight: 0.2,               // Max 20% mood-congruence boost
+    arousalWeight: 0.3,        // Yerkes-Dodson arousal-salience coupling
+    resonance: {               // Detect emotional echoes across experiences
+      enabled: true,
+      k: 5,                    // How many past episodes to check
+      threshold: 0.5,          // Semantic similarity threshold
+      affectThreshold: 0.6,    // Emotional similarity threshold
+    },
+  },
+
+  // Interference-based forgetting (v0.7.0)
+  interference: {
+    enabled: true,             // New episodes suppress similar existing memories
+    weight: 0.15,              // Suppression strength
+  },
+
   // Decay settings
   decay: {
     dormantThreshold: 0.1,     // Below this confidence = dormant
@@ -284,6 +313,12 @@ const id = await brain.encode({
   },
   tags: ['stripe', 'production'],    // Optional. Array of strings.
   supersedes: 'previous-id',         // Optional. ID of episode this corrects.
+  context: { task: 'debugging' },    // Optional. Situational context for retrieval.
+  affect: {                          // Optional. Emotional context.
+    valence: -0.5,                   //   -1 (negative) to 1 (positive)
+    arousal: 0.7,                    //   0 (calm) to 1 (activated)
+    label: 'frustration',            //   Human-readable emotion label
+  },
 });
 ```
 
@@ -316,6 +351,8 @@ const memories = await brain.recall('stripe rate limits', {
   sources: ['direct-observation'], // Only episodic memories from these sources
   after: '2026-02-01T00:00:00Z', // Only memories created after this date
   before: '2026-03-01T00:00:00Z', // Only memories created before this date
+  context: { task: 'debugging' }, // Boost memories encoded in matching context
+  mood: { valence: -0.3, arousal: 0.5 }, // Mood-congruent retrieval
 });
 ```
 
@@ -332,6 +369,8 @@ Each result:
   score: 0.74,          // similarity * confidence
   source: 'consolidation',
   state: 'active',
+  contextMatch: 0.8,   // When retrieval context provided
+  moodCongruence: 0.7, // When mood provided
   provenance: {         // When includeProvenance: true
     evidenceEpisodeIds: ['01XYZ...', '01DEF...'],
     evidenceCount: 3,
@@ -467,6 +506,8 @@ brain.on('decay', ({ totalEvaluated, transitionedToDormant }) => { ... });
 brain.on('rollback', ({ runId, rolledBackMemories }) => { ... });
 brain.on('forget', ({ id, type, purged }) => { ... });
 brain.on('purge', ({ episodes, semantics, procedures }) => { ... });
+brain.on('interference', ({ newEpisodeId, suppressedId, similarity }) => { ... });
+brain.on('resonance', ({ episodeId, resonances }) => { ... });
 brain.on('migration', ({ episodes, semantics, procedures }) => { ... });
 brain.on('error', (err) => { ... });
 ```
@@ -492,6 +533,9 @@ src/
   decay.js           Ebbinghaus forgetting curves.
   embedding.js       Pluggable providers (Mock, OpenAI). Batch embedding.
   encode.js          Immutable episodic memory creation + vec0 writes.
+  affect.js          Emotional memory: arousal-salience coupling, mood-congruent recall, resonance.
+  context.js         Context-dependent retrieval modifier (encoding specificity).
+  interference.js    Competitive memory suppression (engram competition).
   forget.js          Soft-delete, hard-delete, query-based forget, bulk purge.
   introspect.js      Health dashboard queries.
   llm.js             Pluggable LLM providers (Mock, Anthropic, OpenAI).
@@ -531,7 +575,7 @@ All mutations use SQLite transactions. CHECK constraints enforce valid states an
 ## Running Tests
 
 ```bash
-npm test          # 278 tests across 23 files
+npm test          # 379 tests across 28 files
 npm run test:watch
 ```
 
@@ -547,7 +591,29 @@ Demonstrates the full pipeline: encode 3 rate-limit observations, consolidate in
 
 ## Changelog
 
-### v0.6.0 — Filtered Recall + Forget (current)
+### v0.9.0 — Emotional Memory (current)
+
+- Valence-arousal affect model (Russell's circumplex) on every episode
+- Arousal-salience coupling via Yerkes-Dodson inverted-U curve
+- Mood-congruent recall — matching emotional state boosts retrieval confidence
+- Emotional resonance detection — new experiences that echo past emotional patterns emit events
+- MCP server: `memory_encode` accepts `affect`, `memory_recall` accepts `mood`
+- 379 tests across 28 test files
+
+### v0.8.0 — Context-Dependent Retrieval
+
+- Encoding specificity principle: context stored with memory, matching context boosts recall
+- MCP server: `memory_encode` and `memory_recall` accept `context`
+- 340 tests across 27 test files
+
+### v0.7.0 — Interference + Salience
+
+- Interference-based forgetting: new memories competitively suppress similar existing ones
+- Salience-weighted confidence: high-salience memories resist decay
+- Spaced-repetition reconsolidation: retrieval intervals affect reinforcement strength
+- 310 tests across 25 test files
+
+### v0.6.0 — Filtered Recall + Forget
 
 - Filtered recall: tag, source, and date-range filters on `recall()` and `recallStream()`
 - `forget()` — soft-delete any memory by ID
@@ -608,6 +674,8 @@ Demonstrates the full pipeline: encode 3 rate-limit observations, consolidate in
 
 **Why soft-delete by default?** Hard-deletes are irreversible. Soft-delete preserves data integrity and audit trails while excluding the memory from recall. Use `purge: true` or `brain.purge()` when you need permanent removal (GDPR, storage cleanup).
 
+**Why emotional memory?** Every memory system stores facts. Biological memory stores facts with emotional context — and that context changes how memories are retrieved. Emotional arousal modulates encoding strength (amygdala-hippocampal interaction). Current mood biases which memories surface (Bower, 1981). This isn't a novelty feature — it's the foundation for AI that remembers like it cares.
+
 ## License
 
 MIT

package/mcp-server/config.js

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

package/mcp-server/index.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
@@ -164,10 +164,15 @@ async function main() {
       tags: z.array(z.string()).optional().describe('Optional tags for categorization'),
       salience: z.number().min(0).max(1).optional().describe('Importance weight 0-1'),
       context: z.record(z.string()).optional().describe('Situational context as key-value pairs (e.g., {task: "debugging", domain: "payments"})'),
+      affect: z.object({
+        valence: z.number().min(-1).max(1).describe('Emotional valence: -1 (very negative) to 1 (very positive)'),
+        arousal: z.number().min(0).max(1).optional().describe('Emotional arousal: 0 (calm) to 1 (highly activated)'),
+        label: z.string().optional().describe('Human-readable emotion label (e.g., "curiosity", "frustration", "relief")'),
+      }).optional().describe('Emotional affect — how this memory feels'),
     },
-    async ({ content, source, tags, salience, context }) => {
+    async ({ content, source, tags, salience, context, affect }) => {
       try {
-        const id = await audrey.encode({ content, source, tags, salience, context });
+        const id = await audrey.encode({ content, source, tags, salience, context, affect });
         return toolResult({ id, content, source });
       } catch (err) {
         return toolError(err);
@@ -187,8 +192,12 @@ async function main() {
       after: z.string().optional().describe('Only return memories created after this ISO date'),
       before: z.string().optional().describe('Only return memories created before this ISO date'),
       context: z.record(z.string()).optional().describe('Retrieval context — memories encoded in matching context get boosted'),
+      mood: z.object({
+        valence: z.number().min(-1).max(1).describe('Current emotional valence: -1 (negative) to 1 (positive)'),
+        arousal: z.number().min(0).max(1).optional().describe('Current arousal: 0 (calm) to 1 (activated)'),
+      }).optional().describe('Current mood — boosts recall of memories encoded in similar emotional state'),
     },
-    async ({ query, limit, types, min_confidence, tags, sources, after, before, context }) => {
+    async ({ query, limit, types, min_confidence, tags, sources, after, before, context, mood }) => {
       try {
         const results = await audrey.recall(query, {
           limit: limit ?? 10,
@@ -199,6 +208,7 @@ async function main() {
           after,
           before,
           context,
+          mood,
         });
         return toolResult(results);
       } catch (err) {

package/package.json

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

@@ -0,0 +1,64 @@
+export function arousalSalienceBoost(arousal) {
+  if (arousal === undefined || arousal === null) return 0;
+  // Inverted-U (Yerkes-Dodson): peaks at 0.7, Gaussian sigma=0.3
+  return Math.exp(-Math.pow(arousal - 0.7, 2) / (2 * 0.3 * 0.3));
+}
+
+export function affectSimilarity(a, b) {
+  if (!a || !b) return 0;
+  if (a.valence === undefined || b.valence === undefined) return 0;
+  const valenceDist = Math.abs(a.valence - b.valence);
+  const valenceSim = 1.0 - (valenceDist / 2.0);
+  if (a.arousal === undefined || b.arousal === undefined) return valenceSim;
+  const arousalSim = 1.0 - Math.abs(a.arousal - b.arousal);
+  // Valence is primary (70%), arousal secondary (30%) per Bower 1981
+  return 0.7 * valenceSim + 0.3 * arousalSim;
+}
+
+export function moodCongruenceModifier(encodingAffect, retrievalMood, weight = 0.2) {
+  if (!encodingAffect || !retrievalMood) return 1.0;
+  const similarity = affectSimilarity(encodingAffect, retrievalMood);
+  if (similarity === 0) return 1.0;
+  return 1.0 + (weight * similarity);
+}
+
+export async function detectResonance(db, embeddingProvider, episodeId, { content, affect }, config = {}) {
+  const { enabled = true, k = 5, threshold = 0.5, affectThreshold = 0.6 } = config;
+  if (!enabled || !affect || affect.valence === undefined) return [];
+
+  const vector = await embeddingProvider.embed(content);
+  const buffer = embeddingProvider.vectorToBuffer(vector);
+
+  const matches = db.prepare(`
+    SELECT e.*, (1.0 - v.distance) AS similarity
+    FROM vec_episodes v
+    JOIN episodes e ON e.id = v.id
+    WHERE v.embedding MATCH ?
+      AND k = ?
+      AND e.id != ?
+      AND e.superseded_by IS NULL
+  `).all(buffer, k, episodeId);
+
+  const resonances = [];
+  for (const match of matches) {
+    if (match.similarity < threshold) continue;
+    let priorAffect;
+    try { priorAffect = JSON.parse(match.affect || '{}'); } catch { continue; }
+    if (priorAffect.valence === undefined) continue;
+
+    const emotionalSimilarity = affectSimilarity(affect, priorAffect);
+    if (emotionalSimilarity < affectThreshold) continue;
+
+    resonances.push({
+      priorEpisodeId: match.id,
+      priorContent: match.content,
+      priorAffect,
+      semanticSimilarity: match.similarity,
+      emotionalSimilarity,
+      timeDelta: Date.now() - new Date(match.created_at).getTime(),
+      priorCreatedAt: match.created_at,
+    });
+  }
+
+  return resonances;
+}

package/src/audrey.js

@@ -16,6 +16,7 @@ import { importMemories } from './import.js';
 import { suggestConsolidationParams as suggestParamsFn } from './adaptive.js';
 import { reembedAll } from './migrate.js';
 import { applyInterference } from './interference.js';
+import { detectResonance } from './affect.js';
 
 /**
  * @typedef {'direct-observation' | 'told-by-user' | 'tool-result' | 'inference' | 'model-generated'} SourceType
@@ -92,6 +93,7 @@ export class Audrey extends EventEmitter {
     decay = {},
     interference = {},
     context = {},
+    affect = {},
   } = {}) {
     super();
 
@@ -118,6 +120,7 @@ export class Audrey extends EventEmitter {
       sourceReliability: confidence.sourceReliability,
       interferenceWeight: interference.weight ?? 0.1,
       contextWeight: context.weight ?? 0.3,
+      affectWeight: affect.weight ?? 0.2,
     };
     this.consolidationConfig = {
       minEpisodes: consolidation.minEpisodes || 3,
@@ -134,6 +137,17 @@ export class Audrey extends EventEmitter {
       enabled: context.enabled ?? true,
       weight: context.weight ?? 0.3,
     };
+    this.affectConfig = {
+      enabled: affect.enabled ?? true,
+      weight: affect.weight ?? 0.2,
+      arousalWeight: affect.arousalWeight ?? 0.3,
+      resonance: {
+        enabled: affect.resonance?.enabled ?? true,
+        k: affect.resonance?.k ?? 5,
+        threshold: affect.resonance?.threshold ?? 0.5,
+        affectThreshold: affect.resonance?.affectThreshold ?? 0.6,
+      },
+    };
   }
 
   async _ensureMigrated() {
@@ -173,7 +187,8 @@ export class Audrey extends EventEmitter {
    */
   async encode(params) {
     await this._ensureMigrated();
-    const id = await encodeEpisode(this.db, this.embeddingProvider, params);
+    const encodeParams = { ...params, arousalWeight: this.affectConfig.arousalWeight };
+    const id = await encodeEpisode(this.db, this.embeddingProvider, encodeParams);
     this.emit('encode', { id, ...params });
     if (this.interferenceConfig.enabled) {
       applyInterference(this.db, this.embeddingProvider, id, params, this.interferenceConfig)
@@ -184,6 +199,15 @@ export class Audrey extends EventEmitter {
         })
         .catch(err => this.emit('error', err));
     }
+    if (this.affectConfig.enabled && this.affectConfig.resonance.enabled && params.affect?.valence !== undefined) {
+      detectResonance(this.db, this.embeddingProvider, id, params, this.affectConfig.resonance)
+        .then(echoes => {
+          if (echoes.length > 0) {
+            this.emit('resonance', { episodeId: id, affect: params.affect, echoes });
+          }
+        })
+        .catch(err => this.emit('error', err));
+    }
     this._emitValidation(id, params);
     return id;
   }
@@ -235,10 +259,14 @@ export class Audrey extends EventEmitter {
   }
 
   _recallConfig(options) {
-    const base = options.confidenceConfig ?? this.confidenceConfig;
-    return this.contextConfig.enabled && options.context
-      ? { ...base, retrievalContext: options.context }
-      : base;
+    let config = options.confidenceConfig ?? this.confidenceConfig;
+    if (this.contextConfig.enabled && options.context) {
+      config = { ...config, retrievalContext: options.context };
+    }
+    if (this.affectConfig.enabled && options.mood) {
+      config = { ...config, retrievalMood: options.mood };
+    }
+    return config;
   }
 
   /**

package/src/db.js

@@ -12,6 +12,7 @@ const SCHEMA = `
     source_reliability REAL NOT NULL,
     salience REAL DEFAULT 0.5,
     context TEXT DEFAULT '{}',
+    affect TEXT DEFAULT '{}',
     tags TEXT,
     causal_trigger TEXT,
     causal_consequence TEXT,

package/src/encode.js

@@ -1,5 +1,6 @@
 import { generateId } from './ulid.js';
 import { sourceReliability } from './confidence.js';
+import { arousalSalienceBoost } from './affect.js';
 
 /**
  * @param {import('better-sqlite3').Database} db
@@ -15,6 +16,8 @@ export async function encodeEpisode(db, embeddingProvider, {
   tags,
   supersedes,
   context = {},
+  affect = {},
+  arousalWeight = 0.3,
 }) {
   if (!content || typeof content !== 'string') throw new Error('content must be a non-empty string');
   if (salience < 0 || salience > 1) throw new Error('salience must be between 0 and 1');
@@ -26,16 +29,20 @@ export async function encodeEpisode(db, embeddingProvider, {
   const id = generateId();
   const now = new Date().toISOString();
 
+  const boost = arousalSalienceBoost(affect.arousal);
+  const effectiveSalience = Math.min(1.0, salience + (boost * arousalWeight));
+
   const insertAndLink = db.transaction(() => {
     db.prepare(`
       INSERT INTO episodes (
-        id, content, embedding, source, source_reliability, salience, context,
+        id, content, embedding, source, source_reliability, salience, context, affect,
         tags, causal_trigger, causal_consequence, created_at,
         embedding_model, embedding_version, supersedes
-      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
     `).run(
-      id, content, embeddingBuffer, source, reliability, salience,
+      id, content, embeddingBuffer, source, reliability, effectiveSalience,
       JSON.stringify(context),
+      JSON.stringify(affect),
       tags ? JSON.stringify(tags) : null,
       causal?.trigger || null, causal?.consequence || null,
       now, embeddingProvider.modelName, embeddingProvider.modelVersion,

package/src/index.js

@@ -17,3 +17,4 @@ export { reembedAll } from './migrate.js';
 export { forgetMemory, forgetByQuery, purgeMemories } from './forget.js';
 export { applyInterference, interferenceModifier } from './interference.js';
 export { contextMatchRatio, contextModifier } from './context.js';
+export { arousalSalienceBoost, affectSimilarity, moodCongruenceModifier, detectResonance } from './affect.js';

package/src/recall.js

@@ -1,6 +1,7 @@
 import { computeConfidence, DEFAULT_HALF_LIVES, salienceModifier } from './confidence.js';
 import { interferenceModifier } from './interference.js';
 import { contextMatchRatio, contextModifier } from './context.js';
+import { moodCongruenceModifier, affectSimilarity } from './affect.js';
 import { daysBetween, safeJsonParse } from './utils.js';
 
 function computeEpisodicConfidence(ep, now, confidenceConfig = {}) {
@@ -65,7 +66,7 @@ function computeProceduralConfidence(proc, now, confidenceConfig = {}) {
   return Math.max(0, Math.min(1, confidence));
 }
 
-function buildEpisodicEntry(ep, confidence, score, includeProvenance, contextMatch) {
+function buildEpisodicEntry(ep, confidence, score, includeProvenance, contextMatch, moodCongruence) {
   const entry = {
     id: ep.id,
     content: ep.content,
@@ -78,6 +79,9 @@ function buildEpisodicEntry(ep, confidence, score, includeProvenance, contextMat
   if (contextMatch !== undefined) {
     entry.contextMatch = contextMatch;
   }
+  if (moodCongruence !== undefined) {
+    entry.moodCongruence = moodCongruence;
+  }
   if (includeProvenance) {
     entry.provenance = {
       source: ep.source,
@@ -174,9 +178,17 @@ function knnEpisodic(db, queryBuffer, candidateK, now, minConfidence, includePro
       confidence = Math.max(0, Math.min(1, confidence));
     }
 
+    let moodMatch;
+    if (confidenceConfig?.retrievalMood) {
+      const encodingAffect = safeJsonParse(row.affect, {});
+      moodMatch = affectSimilarity(encodingAffect, confidenceConfig.retrievalMood);
+      confidence *= moodCongruenceModifier(encodingAffect, confidenceConfig.retrievalMood, confidenceConfig.affectWeight);
+      confidence = Math.max(0, Math.min(1, confidence));
+    }
+
     if (confidence < minConfidence) continue;
     const score = row.similarity * confidence;
-    results.push(buildEpisodicEntry(row, confidence, score, includeProvenance, ctxMatch));
+    results.push(buildEpisodicEntry(row, confidence, score, includeProvenance, ctxMatch, moodMatch));
   }
   return results;
 }