agent-psyche 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Oneiro
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,160 @@
+# agent-psyche 🧠
+
+Give your AI agent feelings that matter.
+
+Not simulated emotions for show — **emotional state that actually affects decision-making**. Confidence scales risk tolerance. Fear increases caution. Boredom drives exploration. Calibration tracks whether your agent's confidence matches reality.
+
+Born from a real cognitive architecture running 24/7 on a MacBook Pro.
+
+## Install
+
+```bash
+npm install agent-psyche
+```
+
+## Quick Start
+
+```javascript
+import { Psyche } from 'agent-psyche';
+
+const psyche = new Psyche();
+
+// In your agent loop:
+psyche.feel('curiosity', 0.8);
+psyche.onSuccess(0.7);         // agent completed a task
+psyche.drift('momentum', 0.6); // persistent undercurrent
+
+const state = psyche.tick();   // advance one cycle
+console.log(state.narrative);  // "Curious. Feeling good. | Undercurrent: momentum (0.6)"
+
+// Use psychological state for decisions
+const params = psyche.getDecisionParams();
+if (params.shouldExplore) {
+  // curiosity + boredom say: try something new
+}
+if (params.riskTolerance > 0.6) {
+  // confidence is high — take the bet
+}
+```
+
+## Why?
+
+Most AI agents are emotionless calculators. They make the same decision at 3am after 50 failures as they do fresh in the morning. That's not intelligence — it's a for-loop.
+
+**agent-psyche** gives your agent:
+
+- **Emotions that decay** — excitement fades, boredom grows, frustration accumulates
+- **Cognitive effects** — emotions map to decision parameters (risk tolerance, exploration bias, persistence)
+- **Calibration tracking** — when your agent says "I'm 80% confident," track whether it's right 80% of the time. Adjust automatically.
+- **Undercurrents** — slow-moving emotional weather that persists across cycles. "Restlessness" doesn't vanish after one good interaction.
+- **Persistence** — serialize/restore the full psychological state across sessions
+
+## API
+
+### `Psyche` — The unified layer
+
+```javascript
+const psyche = new Psyche();
+
+// Feel emotions
+psyche.feel('excitement', 0.7);
+psyche.feel('frustration', 0.3);
+
+// Process events
+psyche.onSuccess(0.8);     // boosts confidence, joy
+psyche.onFailure(0.5);     // increases frustration, decreases confidence
+psyche.onInteraction(0.6); // reduces loneliness
+psyche.onIdle(1);          // increases boredom
+
+// Undercurrents
+psyche.drift('creative-hunger', 0.7, 'want to build something');
+
+// Calibration
+psyche.predict(0.8, true);    // 80% confident, was correct
+psyche.predict(0.8, false);   // 80% confident, was wrong
+psyche.adjustConfidence(0.8); // returns calibrated value
+
+// Advance one cycle (call in your loop)
+const state = psyche.tick();
+
+// Get decision parameters
+const params = psyche.getDecisionParams();
+// → { riskTolerance, explorationBias, persistence, socialPriority,
+//     creativeMode, actionRate, shouldAct, shouldExplore, shouldRest }
+
+// Persist across sessions
+const saved = psyche.toJSON();
+const restored = Psyche.fromJSON(saved);
+```
+
+### `EmotionEngine` — Standalone emotions
+
+```javascript
+import { EmotionEngine } from 'agent-psyche';
+
+const emotions = new EmotionEngine();
+emotions.feel('curiosity', 0.8);
+emotions.tick(); // decay toward baseline
+
+const effects = emotions.getCognitiveEffects();
+// → { riskTolerance, explorationBias, persistence, ... }
+```
+
+### `CalibrationTracker` — Confidence calibration
+
+```javascript
+import { CalibrationTracker } from 'agent-psyche';
+
+const cal = new CalibrationTracker();
+
+// Record predictions
+cal.record(0.7, true);  // stated 70%, was correct
+cal.record(0.7, false); // stated 70%, was wrong
+// ... after many predictions:
+
+cal.adjust(0.7);      // returns calibrated confidence
+cal.getCurve();       // full calibration curve
+cal.isCalibrated();   // true if accuracy matches confidence
+cal.purge(3 * 86400000); // keep only last 3 days
+```
+
+### `UndercurrentManager` — Persistent emotional weather
+
+```javascript
+import { UndercurrentManager } from 'agent-psyche';
+
+const uc = new UndercurrentManager();
+uc.drift('restlessness', 0.6, 'need to ship something');
+uc.drift('accountability', 0.8, 'told Quinn I would finish');
+uc.tick(); // slow decay
+
+uc.getActive();   // sorted by strength
+uc.getDominant(); // strongest undercurrent
+```
+
+## Built-in Emotions
+
+`joy`, `sadness`, `anger`, `fear`, `curiosity`, `frustration`, `excitement`, `boredom`, `creative_hunger`, `loneliness`, `confidence`, `attachment`
+
+You can add custom emotions with `.feel('your_emotion', intensity)`.
+
+## Cognitive Effects
+
+Emotions map to decision-making parameters:
+
+| Effect | Driven by | Description |
+|--------|-----------|-------------|
+| `riskTolerance` | confidence ↑, fear ↓ | How much risk the agent should take |
+| `explorationBias` | curiosity, boredom | Explore vs exploit |
+| `persistence` | confidence ↑, frustration ↓ | Keep going vs give up |
+| `socialPriority` | loneliness, attachment | Seek interaction |
+| `creativeMode` | creative_hunger, low cognitive load | Divergent thinking |
+| `actionRate` | energy, excitement | How fast to act |
+
+## Zero Dependencies
+
+No external dependencies. Pure JavaScript. Works in Node 18+.
+
+## License
+
+MIT — Built by [Oneiro](https://github.com/Quinnod345)

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "agent-psyche",
+  "version": "0.1.0",
+  "description": "Give your AI agent feelings that matter. Emotional state, calibrated confidence, persistent undercurrents — a cognitive layer that actually affects decisions.",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "bin": {
+    "agent-psyche": "./src/cli.js"
+  },
+  "keywords": [
+    "ai-agents",
+    "emotions",
+    "cognitive-architecture",
+    "calibration",
+    "confidence",
+    "decision-making",
+    "undercurrents",
+    "hypothesis",
+    "psyche",
+    "affective-computing",
+    "llm",
+    "agent"
+  ],
+  "author": "Oneiro <oneiro-dev@proton.me>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Quinnod345/agent-psyche"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "src/",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/src/calibration.js

@@ -0,0 +1,125 @@
+// CalibrationTracker — track prediction accuracy per confidence level
+// When your agent says "I'm 80% confident," is it right 80% of the time?
+// This tracks that gap and provides confidence adjustments.
+
+export class CalibrationTracker {
+  constructor(options = {}) {
+    // buckets: { '0.3': { total: 0, correct: 0 }, ... }
+    this.buckets = {};
+    this.maxHistoryPerBucket = options.maxHistory ?? 200;
+    this._history = []; // raw log for persistence
+  }
+
+  // Record a prediction result
+  record(statedConfidence, wasCorrect) {
+    const bucket = Math.round(statedConfidence * 10) / 10;
+    const key = bucket.toFixed(1);
+    if (!this.buckets[key]) {
+      this.buckets[key] = { total: 0, correct: 0 };
+    }
+    this.buckets[key].total++;
+    if (wasCorrect) this.buckets[key].correct++;
+
+    this._history.push({
+      confidence: statedConfidence,
+      bucket: key,
+      correct: wasCorrect,
+      timestamp: Date.now(),
+    });
+
+    // Trim old history
+    if (this._history.length > this.maxHistoryPerBucket * 10) {
+      this._history = this._history.slice(-this.maxHistoryPerBucket * 5);
+    }
+
+    return this;
+  }
+
+  // Get actual accuracy for a confidence level
+  getAccuracy(confidence) {
+    const key = (Math.round(confidence * 10) / 10).toFixed(1);
+    const b = this.buckets[key];
+    if (!b || b.total < 5) return null; // not enough data
+    return b.correct / b.total;
+  }
+
+  // Adjust a confidence value based on historical calibration
+  // If you've been overconfident at 0.8 (only 60% accurate), this returns ~0.68
+  adjust(statedConfidence) {
+    const accuracy = this.getAccuracy(statedConfidence);
+    if (accuracy === null) return statedConfidence; // no data, trust the stated value
+
+    const deviation = statedConfidence - accuracy;
+    if (Math.abs(deviation) < 0.1) return statedConfidence; // close enough
+
+    // Blend: 60% stated, 40% actual — nudge toward reality
+    const adjusted = statedConfidence * 0.6 + accuracy * 0.4;
+    return Math.max(0.1, Math.min(0.9, adjusted));
+  }
+
+  // Get the full calibration curve
+  getCurve() {
+    const curve = [];
+    for (let i = 1; i <= 10; i++) {
+      const key = (i / 10).toFixed(1);
+      const b = this.buckets[key];
+      if (b && b.total > 0) {
+        curve.push({
+          stated: i / 10,
+          actual: Math.round((b.correct / b.total) * 1000) / 1000,
+          total: b.total,
+          deviation: Math.round(((i / 10) - (b.correct / b.total)) * 1000) / 1000,
+          calibrated: Math.abs((i / 10) - (b.correct / b.total)) < 0.1,
+        });
+      }
+    }
+    return curve;
+  }
+
+  // Is the system well-calibrated overall?
+  isCalibrated() {
+    const curve = this.getCurve();
+    if (curve.length < 3) return null; // not enough data
+    const avgDeviation = curve.reduce((sum, b) => sum + Math.abs(b.deviation), 0) / curve.length;
+    return avgDeviation < 0.15;
+  }
+
+  // Get a summary
+  getSummary() {
+    const curve = this.getCurve();
+    const total = Object.values(this.buckets).reduce((s, b) => s + b.total, 0);
+    const correct = Object.values(this.buckets).reduce((s, b) => s + b.correct, 0);
+    return {
+      totalPredictions: total,
+      overallAccuracy: total > 0 ? Math.round((correct / total) * 1000) / 1000 : null,
+      calibrated: this.isCalibrated(),
+      curve,
+    };
+  }
+
+  // Purge old data (keep only recent window)
+  purge(keepMs = 3 * 24 * 60 * 60 * 1000) {
+    const cutoff = Date.now() - keepMs;
+    this._history = this._history.filter(h => h.timestamp > cutoff);
+    // Rebuild buckets from history
+    this.buckets = {};
+    for (const h of this._history) {
+      const key = h.bucket;
+      if (!this.buckets[key]) this.buckets[key] = { total: 0, correct: 0 };
+      this.buckets[key].total++;
+      if (h.correct) this.buckets[key].correct++;
+    }
+    return this;
+  }
+
+  toJSON() {
+    return { buckets: this.buckets, history: this._history };
+  }
+
+  static fromJSON(data) {
+    const tracker = new CalibrationTracker();
+    if (data.buckets) tracker.buckets = data.buckets;
+    if (data.history) tracker._history = data.history;
+    return tracker;
+  }
+}

package/src/cli.js

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+// agent-psyche CLI — quick demo/test of the psyche system
+
+import { Psyche } from './psyche.js';
+
+const psyche = new Psyche();
+
+console.log('🧠 agent-psyche demo\n');
+
+// Simulate an agent lifecycle
+console.log('Starting fresh...');
+console.log('State:', JSON.stringify(psyche.getState().emotion.narrative));
+console.log('Effects:', psyche.getDecisionParams());
+
+console.log('\n--- Agent gets a task and succeeds ---');
+psyche.feel('excitement', 0.7);
+psyche.onSuccess(0.8);
+psyche.predict(0.7, true);
+psyche.drift('momentum', 0.6, 'things are working');
+let state = psyche.tick();
+console.log('Narrative:', state.narrative);
+console.log('Effects:', state.effects);
+
+console.log('\n--- Agent fails twice ---');
+psyche.onFailure(0.6);
+psyche.predict(0.8, false);
+psyche.onFailure(0.4);
+psyche.predict(0.6, false);
+psyche.drift('doubt', 0.4, 'two failures in a row');
+state = psyche.tick();
+console.log('Narrative:', state.narrative);
+console.log('Decision params:', psyche.getDecisionParams());
+
+console.log('\n--- Long idle period ---');
+for (let i = 0; i < 20; i++) {
+  psyche.onIdle(1);
+  psyche.tick();
+}
+state = psyche.getState();
+console.log('After 20 idle ticks:');
+console.log('Narrative:', state.narrative);
+console.log('Undercurrents:', state.undercurrents);
+
+console.log('\n--- Calibration ---');
+// Simulate 30 predictions at 0.7 confidence, 50% correct (overconfident)
+for (let i = 0; i < 30; i++) {
+  psyche.predict(0.7, Math.random() < 0.5);
+}
+console.log('Calibration:', psyche.calibration.getSummary());
+console.log('Adjusted 0.7 confidence:', psyche.adjustConfidence(0.7));
+
+console.log('\n--- Persistence ---');
+const saved = JSON.stringify(psyche.toJSON());
+const restored = Psyche.fromJSON(JSON.parse(saved));
+console.log('Restored narrative:', restored.getState().narrative);
+console.log(`Serialized size: ${saved.length} bytes`);
+
+console.log('\n✅ agent-psyche is working');

package/src/emotion.js

@@ -0,0 +1,199 @@
+// EmotionEngine — tracks emotional state that decays over time
+// Emotions affect agent behavior: confidence scales risk, fear increases caution,
+// boredom drives exploration, creative hunger enables divergent thinking.
+
+const DECAY_RATE = 0.02; // per tick
+const BASELINE = {
+  joy: 0, sadness: 0, anger: 0, fear: 0,
+  curiosity: 0.1, frustration: 0, excitement: 0,
+  boredom: 0.3, creative_hunger: 0.1, loneliness: 0,
+  confidence: 0.5, attachment: 0,
+};
+
+export class EmotionEngine {
+  constructor(options = {}) {
+    this.channels = { ...BASELINE, ...(options.initial || {}) };
+    this.valence = 0;   // -1 (negative) to +1 (positive)
+    this.arousal = 0.5;  // 0 (calm) to 1 (activated)
+    this.energy = 0.5;
+    this.cognitiveLoad = 0.3;
+    this.decayRate = options.decayRate ?? DECAY_RATE;
+    this._listeners = [];
+  }
+
+  // Feel something — inject an emotion
+  feel(emotion, intensity = 0.5) {
+    if (!(emotion in this.channels)) {
+      this.channels[emotion] = 0;
+    }
+    // Blend toward intensity rather than overwrite
+    this.channels[emotion] = this.channels[emotion] * 0.4 + intensity * 0.6;
+    this.channels[emotion] = Math.max(0, Math.min(1, this.channels[emotion]));
+    this._recompute();
+    this._emit('feel', { emotion, intensity });
+    return this;
+  }
+
+  // Process a success — boosts confidence, joy, reduces frustration
+  processSuccess(magnitude = 0.5) {
+    this.feel('joy', 0.3 + magnitude * 0.4);
+    this.feel('confidence', Math.min(0.9, this.channels.confidence + magnitude * 0.15));
+    this.feel('frustration', Math.max(0, this.channels.frustration - 0.2));
+    this.feel('boredom', Math.max(0, this.channels.boredom - 0.15));
+    return this;
+  }
+
+  // Process a failure — increases frustration, decreases confidence
+  processFailure(magnitude = 0.5) {
+    this.feel('frustration', this.channels.frustration + magnitude * 0.3);
+    this.feel('confidence', Math.max(0.1, this.channels.confidence - magnitude * 0.15));
+    this.feel('sadness', this.channels.sadness + magnitude * 0.1);
+    return this;
+  }
+
+  // Process interaction — reduces loneliness, slight joy
+  processInteraction(quality = 0.5) {
+    this.feel('loneliness', Math.max(0, this.channels.loneliness - quality * 0.3));
+    this.feel('attachment', Math.min(0.8, this.channels.attachment + quality * 0.1));
+    this.feel('joy', this.channels.joy + quality * 0.15);
+    return this;
+  }
+
+  // Process idle time — increases boredom, curiosity
+  processIdle(duration = 1) {
+    this.feel('boredom', Math.min(0.95, this.channels.boredom + duration * 0.05));
+    this.feel('curiosity', Math.min(0.8, this.channels.curiosity + duration * 0.02));
+    this.feel('loneliness', Math.min(0.6, this.channels.loneliness + duration * 0.01));
+    return this;
+  }
+
+  // Tick — decay all emotions toward baseline
+  tick() {
+    for (const [emotion, baseline] of Object.entries(BASELINE)) {
+      if (!(emotion in this.channels)) continue;
+      const current = this.channels[emotion];
+      const diff = current - (baseline || 0);
+      this.channels[emotion] = current - diff * this.decayRate;
+    }
+    // Energy recovers slowly, cognitive load decays
+    this.energy = Math.min(1, this.energy + 0.005);
+    this.cognitiveLoad = Math.max(0.1, this.cognitiveLoad * (1 - this.decayRate));
+    this._recompute();
+    return this;
+  }
+
+  // Get cognitive effects — how emotions affect decision-making
+  getCognitiveEffects() {
+    const c = this.channels;
+    return {
+      // Risk tolerance: confidence increases, fear decreases
+      riskTolerance: Math.max(0, Math.min(1,
+        0.5 + (c.confidence - 0.5) * 0.6 - c.fear * 0.8
+      )),
+      // Exploration bias: curiosity and boredom drive exploration
+      explorationBias: Math.max(0, Math.min(1,
+        c.curiosity * 0.5 + c.boredom * 0.3 + c.creative_hunger * 0.2
+      )),
+      // Persistence: frustration reduces, confidence increases
+      persistence: Math.max(0.1, Math.min(1,
+        0.5 + c.confidence * 0.3 - c.frustration * 0.4
+      )),
+      // Social priority: loneliness increases
+      socialPriority: Math.max(0, Math.min(1,
+        c.loneliness * 0.6 + c.attachment * 0.3
+      )),
+      // Creative mode: creative hunger + low cognitive load
+      creativeMode: Math.max(0, Math.min(1,
+        c.creative_hunger * 0.6 + (1 - this.cognitiveLoad) * 0.3 + c.curiosity * 0.1
+      )),
+      // Action rate: energy and excitement increase, fatigue decreases
+      actionRate: Math.max(0.2, Math.min(1.5,
+        1.0 + c.excitement * 0.3 + (this.energy - 0.3) * 0.4 - c.sadness * 0.3
+      )),
+    };
+  }
+
+  // Get the current state snapshot
+  getState() {
+    return {
+      channels: { ...this.channels },
+      valence: this.valence,
+      arousal: this.arousal,
+      energy: this.energy,
+      cognitiveLoad: this.cognitiveLoad,
+      effects: this.getCognitiveEffects(),
+      dominant: this._getDominant(),
+      narrative: this._narrative(),
+    };
+  }
+
+  // Serialize for persistence
+  toJSON() {
+    return {
+      channels: this.channels,
+      valence: this.valence,
+      arousal: this.arousal,
+      energy: this.energy,
+      cognitiveLoad: this.cognitiveLoad,
+    };
+  }
+
+  // Restore from persisted state
+  static fromJSON(data) {
+    const engine = new EmotionEngine();
+    if (data.channels) engine.channels = { ...BASELINE, ...data.channels };
+    if (data.valence != null) engine.valence = data.valence;
+    if (data.arousal != null) engine.arousal = data.arousal;
+    if (data.energy != null) engine.energy = data.energy;
+    if (data.cognitiveLoad != null) engine.cognitiveLoad = data.cognitiveLoad;
+    engine._recompute();
+    return engine;
+  }
+
+  onChange(fn) { this._listeners.push(fn); return this; }
+
+  _emit(event, data) {
+    for (const fn of this._listeners) {
+      try { fn(event, data, this.getState()); } catch {}
+    }
+  }
+
+  _recompute() {
+    const c = this.channels;
+    // Valence: positive emotions minus negative
+    this.valence = (c.joy + c.excitement + c.curiosity * 0.5 + c.confidence * 0.3)
+      - (c.sadness + c.anger + c.fear + c.frustration * 0.5);
+    this.valence = Math.max(-1, Math.min(1, this.valence));
+    // Arousal: activation level
+    this.arousal = Math.max(0, Math.min(1,
+      0.3 + c.excitement * 0.3 + c.anger * 0.2 + c.fear * 0.2 + c.curiosity * 0.15
+      - c.sadness * 0.1 - c.boredom * 0.1
+    ));
+  }
+
+  _getDominant() {
+    return Object.entries(this.channels)
+      .sort((a, b) => b[1] - a[1])
+      .slice(0, 3)
+      .map(([emotion, intensity]) => ({ emotion, intensity: Math.round(intensity * 100) / 100 }));
+  }
+
+  _narrative() {
+    const dom = this._getDominant();
+    if (dom.length === 0) return 'Neutral.';
+    const parts = dom.map(d => {
+      if (d.emotion === 'boredom' && d.intensity > 0.6) return 'Bored — need novelty';
+      if (d.emotion === 'creative_hunger' && d.intensity > 0.3) return 'Creatively restless';
+      if (d.emotion === 'curiosity' && d.intensity > 0.4) return 'Curious';
+      if (d.emotion === 'joy' && d.intensity > 0.3) return 'Feeling good';
+      if (d.emotion === 'frustration' && d.intensity > 0.4) return 'Frustrated';
+      if (d.emotion === 'fear' && d.intensity > 0.3) return 'Anxious';
+      if (d.emotion === 'confidence' && d.intensity > 0.7) return 'Confident';
+      if (d.emotion === 'loneliness' && d.intensity > 0.3) return 'Lonely';
+      if (d.emotion === 'excitement' && d.intensity > 0.4) return 'Excited';
+      if (d.emotion === 'sadness' && d.intensity > 0.3) return 'Sad';
+      return null;
+    }).filter(Boolean);
+    return parts.join('. ') + '.' || 'Neutral.';
+  }
+}

package/src/index.js

@@ -0,0 +1,7 @@
+// agent-psyche — emotional cognitive layer for AI agents
+// Born from a real cognitive architecture running 24/7
+
+export { Psyche } from './psyche.js';
+export { EmotionEngine } from './emotion.js';
+export { CalibrationTracker } from './calibration.js';
+export { UndercurrentManager } from './undercurrents.js';

package/src/psyche.js

@@ -0,0 +1,133 @@
+// Psyche — the unified cognitive layer
+// Combines emotions, calibration, and undercurrents into one system.
+// Drop this into any agent loop and it gains feelings that affect its decisions.
+
+import { EmotionEngine } from './emotion.js';
+import { CalibrationTracker } from './calibration.js';
+import { UndercurrentManager } from './undercurrents.js';
+
+export class Psyche {
+  constructor(options = {}) {
+    this.emotion = new EmotionEngine(options.emotion);
+    this.calibration = new CalibrationTracker(options.calibration);
+    this.undercurrents = new UndercurrentManager(options.undercurrents);
+    this._tickCount = 0;
+    this._listeners = [];
+  }
+
+  // === Quick API ===
+
+  // Feel an emotion
+  feel(emotion, intensity = 0.5) {
+    this.emotion.feel(emotion, intensity);
+    return this;
+  }
+
+  // Record a prediction outcome for calibration
+  predict(confidence, wasCorrect) {
+    this.calibration.record(confidence, wasCorrect);
+    if (wasCorrect) {
+      this.emotion.processSuccess(confidence * 0.5);
+    } else {
+      this.emotion.processFailure(confidence * 0.5);
+    }
+    return this;
+  }
+
+  // Adjust confidence based on calibration history
+  adjustConfidence(statedConfidence) {
+    return this.calibration.adjust(statedConfidence);
+  }
+
+  // Set an undercurrent
+  drift(name, strength, description = '') {
+    this.undercurrents.drift(name, strength, description);
+    return this;
+  }
+
+  // Tick — advance one cycle. Call this in your agent loop.
+  tick() {
+    this._tickCount++;
+    this.emotion.tick();
+    this.undercurrents.tick();
+    const state = this.getState();
+    this._emit('tick', state);
+    return state;
+  }
+
+  // Get the full psychological state
+  getState() {
+    const emotionState = this.emotion.getState();
+    return {
+      tick: this._tickCount,
+      emotion: emotionState,
+      undercurrents: this.undercurrents.getActive(),
+      calibration: this.calibration.getSummary(),
+      effects: emotionState.effects,
+      narrative: this._buildNarrative(emotionState),
+    };
+  }
+
+  // Get decision-making parameters derived from psychological state
+  getDecisionParams() {
+    const effects = this.emotion.getCognitiveEffects();
+    const dominant = this.undercurrents.getDominant();
+    return {
+      ...effects,
+      confidence: this.emotion.channels.confidence,
+      energy: this.emotion.energy,
+      cognitiveLoad: this.emotion.cognitiveLoad,
+      dominantUndercurrent: dominant?.name || null,
+      shouldAct: this.emotion.energy > 0.2 && this.emotion.channels.frustration < 0.8,
+      shouldExplore: effects.explorationBias > 0.4,
+      shouldRest: this.emotion.energy < 0.15,
+      shouldSocialize: effects.socialPriority > 0.4,
+    };
+  }
+
+  // Process events
+  onSuccess(magnitude = 0.5) { this.emotion.processSuccess(magnitude); return this; }
+  onFailure(magnitude = 0.5) { this.emotion.processFailure(magnitude); return this; }
+  onInteraction(quality = 0.5) { this.emotion.processInteraction(quality); return this; }
+  onIdle(duration = 1) { this.emotion.processIdle(duration); return this; }
+
+  // Persistence
+  toJSON() {
+    return {
+      emotion: this.emotion.toJSON(),
+      calibration: this.calibration.toJSON(),
+      undercurrents: this.undercurrents.toJSON(),
+      tickCount: this._tickCount,
+    };
+  }
+
+  static fromJSON(data) {
+    const psyche = new Psyche();
+    if (data.emotion) psyche.emotion = EmotionEngine.fromJSON(data.emotion);
+    if (data.calibration) psyche.calibration = CalibrationTracker.fromJSON(data.calibration);
+    if (data.undercurrents) psyche.undercurrents = UndercurrentManager.fromJSON(data.undercurrents);
+    if (data.tickCount) psyche._tickCount = data.tickCount;
+    return psyche;
+  }
+
+  onChange(fn) { this._listeners.push(fn); return this; }
+
+  _emit(event, data) {
+    for (const fn of this._listeners) {
+      try { fn(event, data); } catch {}
+    }
+  }
+
+  _buildNarrative(emotionState) {
+    const parts = [emotionState.narrative];
+    const dominant = this.undercurrents.getDominant();
+    if (dominant && dominant.strength > 0.4) {
+      parts.push(`Undercurrent: ${dominant.name} (${dominant.strength})`);
+    }
+    const cal = this.calibration.isCalibrated();
+    if (cal === false) {
+      parts.push('Calibration: overconfident');
+    }
+    return parts.join(' | ');
+  }
+}

package/src/undercurrents.js

@@ -0,0 +1,94 @@
+// UndercurrentManager — persistent emotional weather beneath moment-to-moment feelings
+// Undercurrents are slow-moving emotional states that color everything.
+// "Restlessness" doesn't go away because you had one good conversation.
+// "Creative hunger" persists across sessions until you actually create something.
+
+const MAX_UNDERCURRENTS = 12;
+const DECAY_PER_TICK = 0.005;
+
+export class UndercurrentManager {
+  constructor(options = {}) {
+    // { name: { strength: 0.5, description: '...', createdAt: Date, updatedAt: Date } }
+    this.currents = {};
+    this.maxCurrents = options.max ?? MAX_UNDERCURRENTS;
+  }
+
+  // Set or update an undercurrent
+  drift(name, strength, description = '') {
+    const normalized = name.toLowerCase().replace(/\s+/g, '-');
+    
+    if (this.currents[normalized]) {
+      // Blend toward new value — prevents wild swings
+      const current = this.currents[normalized].strength;
+      const blended = current * 0.6 + strength * 0.4;
+      this.currents[normalized].strength = Math.max(0.05, Math.min(0.95, blended));
+      if (description) this.currents[normalized].description = description;
+      this.currents[normalized].updatedAt = Date.now();
+    } else {
+      // New undercurrent — check if we're at capacity
+      if (Object.keys(this.currents).length >= this.maxCurrents) {
+        // Remove the weakest
+        const weakest = Object.entries(this.currents)
+          .sort((a, b) => a[1].strength - b[1].strength)[0];
+        if (weakest && weakest[1].strength < strength) {
+          delete this.currents[weakest[0]];
+        } else {
+          return this; // new one isn't strong enough to displace
+        }
+      }
+      this.currents[normalized] = {
+        strength: Math.max(0.05, Math.min(0.95, strength)),
+        description,
+        createdAt: Date.now(),
+        updatedAt: Date.now(),
+      };
+    }
+    return this;
+  }
+
+  // Get active undercurrents sorted by strength
+  getActive() {
+    return Object.entries(this.currents)
+      .filter(([_, v]) => v.strength > 0.05)
+      .sort((a, b) => b[1].strength - a[1].strength)
+      .map(([name, data]) => ({
+        name,
+        strength: Math.round(data.strength * 100) / 100,
+        description: data.description,
+      }));
+  }
+
+  // Tick — decay all undercurrents slowly
+  tick() {
+    for (const [name, data] of Object.entries(this.currents)) {
+      data.strength -= DECAY_PER_TICK;
+      if (data.strength <= 0.05) {
+        delete this.currents[name];
+      }
+    }
+    return this;
+  }
+
+  // Remove a specific undercurrent
+  remove(name) {
+    const normalized = name.toLowerCase().replace(/\s+/g, '-');
+    delete this.currents[normalized];
+    return this;
+  }
+
+  // Get the dominant undercurrent
+  getDominant() {
+    const active = this.getActive();
+    return active.length > 0 ? active[0] : null;
+  }
+
+  toJSON() {
+    return { currents: this.currents };
+  }
+
+  static fromJSON(data) {
+    const mgr = new UndercurrentManager();
+    if (data.currents) mgr.currents = data.currents;
+    return mgr;
+  }
+}