@cleocode/core 2026.4.49 → 2026.4.51

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleocode/core",
-  "version": "2026.4.49",
+  "version": "2026.4.51",
   "description": "CLEO core business logic kernel — tasks, sessions, memory, orchestration, lifecycle, with bundled SQLite store",
   "type": "module",
   "main": "./dist/index.js",
@@ -63,13 +63,13 @@
     "write-file-atomic": "^7.0.1",
     "yaml": "^2.8.3",
     "zod": "^4.3.6",
-    "@cleocode/adapters": "2026.4.49",
-    "@cleocode/agents": "2026.4.49",
-    "@cleocode/caamp": "2026.4.49",
-    "@cleocode/contracts": "2026.4.49",
-    "@cleocode/lafs": "2026.4.49",
-    "@cleocode/nexus": "2026.4.49",
-    "@cleocode/skills": "2026.4.49"
+    "@cleocode/adapters": "2026.4.51",
+    "@cleocode/agents": "2026.4.51",
+    "@cleocode/caamp": "2026.4.51",
+    "@cleocode/contracts": "2026.4.51",
+    "@cleocode/lafs": "2026.4.51",
+    "@cleocode/skills": "2026.4.51",
+    "@cleocode/nexus": "2026.4.51"
   },
   "engines": {
     "node": ">=24.0.0"

package/src/internal.ts

@@ -206,6 +206,13 @@ export type {
   PopulateEmbeddingsResult,
 } from './memory/brain-retrieval.js';
 export { populateEmbeddings, retrieveWithBudget } from './memory/brain-retrieval.js';
+// Memory — STDP plasticity (T626 phase 5)
+export type {
+  PlasticityStatsSummary,
+  RecentPlasticityEvent,
+  StdpPlasticityResult,
+} from './memory/brain-stdp.js';
+export { applyStdpPlasticity, getPlasticityStats } from './memory/brain-stdp.js';
 export { migrateClaudeMem } from './memory/claude-mem-migration.js';
 // Memory — engine-compat
 export {

package/src/memory/__tests__/brain-stdp.test.ts

@@ -0,0 +1,452 @@
+/**
+ * Tests for STDP (Spike-Timing-Dependent Plasticity) in brain-stdp.ts.
+ *
+ * Verifies:
+ *   - LTP (potentiation): A retrieved before B → edge A→B strengthened
+ *   - LTD (depression): existing reverse edge B→A weakened when A fires first
+ *   - Exponential decay: pairs farther apart in time get smaller Δw
+ *   - Window cutoff: pairs beyond sessionWindowMs are ignored
+ *   - Weight clamping: edges never exceed [0, 1]
+ *   - New edge insertion: LTP creates an edge when none exists
+ *   - LTD never creates edges: depression only weakens existing ones
+ *   - Stats query: getPlasticityStats returns correct aggregates
+ *
+ * @task T626
+ * @epic T626
+ */
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+// ============================================================================
+// Hoisted mock factories
+// ============================================================================
+
+const { mockGetBrainDb, mockGetBrainNativeDb } = vi.hoisted(() => ({
+  mockGetBrainDb: vi.fn().mockResolvedValue({}),
+  mockGetBrainNativeDb: vi.fn(),
+}));
+
+vi.mock('../../store/brain-sqlite.js', () => ({
+  getBrainDb: mockGetBrainDb,
+  getBrainNativeDb: mockGetBrainNativeDb,
+}));
+
+// ============================================================================
+// Import module under test (after mocks)
+// ============================================================================
+
+import { applyStdpPlasticity, getPlasticityStats } from '../brain-stdp.js';
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+const PROJECT_ROOT = '/fake/project';
+
+/** Build an ISO-like datetime string `msAgo` milliseconds before now. */
+function msAgo(ms: number): string {
+  return new Date(Date.now() - ms).toISOString().replace('T', ' ').slice(0, 19);
+}
+
+type PrepStmt = {
+  run: ReturnType<typeof vi.fn>;
+  get: ReturnType<typeof vi.fn>;
+  all?: ReturnType<typeof vi.fn>;
+};
+
+/** Create a minimal prepared-statement stub. */
+function makeStmt(runResult?: unknown, getResult?: unknown): PrepStmt {
+  return {
+    run: vi.fn().mockReturnValue(runResult ?? { changes: 0 }),
+    get: vi.fn().mockReturnValue(getResult),
+  };
+}
+
+// ============================================================================
+// Tests: applyStdpPlasticity
+// ============================================================================
+
+describe('applyStdpPlasticity', () => {
+  let mockNativeDb: {
+    prepare: ReturnType<typeof vi.fn>;
+    stmts: Map<string, PrepStmt>;
+  };
+
+  /**
+   * Build a minimal mock nativeDb.
+   * `stmtOverrides` maps substring-of-SQL → statement stub.
+   */
+  function buildNativeDb(
+    logRows: Array<{
+      id: number;
+      entry_ids: string;
+      created_at: string;
+      retrieval_order: number | null;
+      delta_ms: number | null;
+    }>,
+    edgeMap: Map<string, number | undefined> = new Map(),
+  ): ReturnType<typeof buildNativeDb> {
+    const stmts = new Map<string, PrepStmt>();
+
+    const db = {
+      stmts,
+      prepare: vi.fn((sql: string) => {
+        // Guard: plasticity events table existence check
+        if (sql.includes('brain_plasticity_events') && sql.includes('SELECT 1')) {
+          return makeStmt(undefined, {});
+        }
+        // Guard: retrieval log existence check
+        if (sql.includes('brain_retrieval_log') && sql.includes('SELECT 1')) {
+          return makeStmt(undefined, {});
+        }
+        // Retrieval log query
+        if (sql.includes('FROM brain_retrieval_log') && sql.includes('ORDER BY')) {
+          const stmt = {
+            run: vi.fn(),
+            get: vi.fn(),
+            all: vi.fn().mockReturnValue(logRows),
+          };
+          return stmt;
+        }
+        // Get existing edge (SELECT weight FROM brain_page_edges)
+        if (sql.includes('SELECT weight') && sql.includes('edge_type')) {
+          return makeStmt(undefined, undefined); // always no existing edge by default
+        }
+        // Update edge weight
+        if (sql.includes('UPDATE brain_page_edges')) {
+          return makeStmt({ changes: 1 });
+        }
+        // Insert new edge
+        if (sql.includes('INSERT OR IGNORE INTO brain_page_edges')) {
+          return makeStmt({ changes: 1 });
+        }
+        // Log plasticity event
+        if (sql.includes('INSERT INTO brain_plasticity_events')) {
+          return makeStmt({ changes: 1 });
+        }
+        // Default
+        return makeStmt(undefined, undefined);
+      }),
+    };
+
+    // Replace the SELECT weight stub with one that uses the edgeMap
+    const originalPrepare = db.prepare;
+    db.prepare = vi.fn((sql: string) => {
+      if (sql.includes('SELECT weight') && sql.includes('edge_type')) {
+        return {
+          run: vi.fn(),
+          get: vi.fn((fromId: string, toId: string) => {
+            const key = `${fromId}|${toId}`;
+            const w = edgeMap.get(key);
+            return w !== undefined ? { weight: w } : undefined;
+          }),
+        };
+      }
+      return originalPrepare(sql);
+    });
+
+    return db;
+  }
+
+  beforeEach(() => {
+    mockGetBrainDb.mockResolvedValue({});
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('returns zero counts when nativeDb is null', async () => {
+    mockGetBrainNativeDb.mockReturnValue(null);
+    const result = await applyStdpPlasticity(PROJECT_ROOT);
+    expect(result.ltpEvents).toBe(0);
+    expect(result.ltdEvents).toBe(0);
+    expect(result.edgesCreated).toBe(0);
+    expect(result.pairsExamined).toBe(0);
+  });
+
+  it('returns zero counts when retrieval_log table is absent', async () => {
+    const db = {
+      prepare: vi.fn().mockReturnValue({
+        run: vi.fn(),
+        get: vi.fn().mockImplementation(() => {
+          throw new Error('no such table');
+        }),
+        all: vi.fn().mockReturnValue([]),
+      }),
+    };
+    mockGetBrainNativeDb.mockReturnValue(db);
+    const result = await applyStdpPlasticity(PROJECT_ROOT);
+    expect(result.ltpEvents).toBe(0);
+  });
+
+  it('returns zero counts when no retrieval log rows exist', async () => {
+    const db = buildNativeDb([], new Map());
+    mockGetBrainNativeDb.mockReturnValue(db);
+    const result = await applyStdpPlasticity(PROJECT_ROOT);
+    expect(result.pairsExamined).toBe(0);
+    expect(result.ltpEvents).toBe(0);
+  });
+
+  it('applies LTP when A retrieved before B within window', async () => {
+    const window = 5 * 60 * 1000; // 5 min default
+    const now = Date.now();
+
+    // A retrieved 10 s ago, B retrieved 5 s ago → A before B by 5 s
+    const rows = [
+      {
+        id: 1,
+        entry_ids: JSON.stringify(['obs-A']),
+        created_at: new Date(now - 10_000).toISOString().replace('T', ' ').slice(0, 19),
+        retrieval_order: 0,
+        delta_ms: null,
+      },
+      {
+        id: 2,
+        entry_ids: JSON.stringify(['obs-B']),
+        created_at: new Date(now - 5_000).toISOString().replace('T', ' ').slice(0, 19),
+        retrieval_order: 1,
+        delta_ms: 5000,
+      },
+    ];
+
+    const db = buildNativeDb(rows, new Map()); // no existing edges
+    mockGetBrainNativeDb.mockReturnValue(db);
+
+    const result = await applyStdpPlasticity(PROJECT_ROOT, window);
+
+    expect(result.ltpEvents).toBeGreaterThanOrEqual(1);
+    expect(result.edgesCreated).toBeGreaterThanOrEqual(1);
+    expect(result.pairsExamined).toBeGreaterThanOrEqual(1);
+  });
+
+  it('applies LTD on reverse edge when reverse edge already exists', async () => {
+    const window = 5 * 60 * 1000;
+    const now = Date.now();
+
+    const rows = [
+      {
+        id: 1,
+        entry_ids: JSON.stringify(['obs-X']),
+        created_at: new Date(now - 10_000).toISOString().replace('T', ' ').slice(0, 19),
+        retrieval_order: 0,
+        delta_ms: null,
+      },
+      {
+        id: 2,
+        entry_ids: JSON.stringify(['obs-Y']),
+        created_at: new Date(now - 5_000).toISOString().replace('T', ' ').slice(0, 19),
+        retrieval_order: 1,
+        delta_ms: 5000,
+      },
+    ];
+
+    // Pre-seed reverse edge observation:obs-Y → observation:obs-X
+    const edgeMap = new Map<string, number>([['observation:obs-Y|observation:obs-X', 0.6]]);
+
+    const db = buildNativeDb(rows, edgeMap);
+    mockGetBrainNativeDb.mockReturnValue(db);
+
+    const result = await applyStdpPlasticity(PROJECT_ROOT, window);
+
+    expect(result.ltdEvents).toBeGreaterThanOrEqual(1);
+  });
+
+  it('skips pairs beyond sessionWindowMs', async () => {
+    const shortWindow = 1_000; // 1 second window
+    const now = Date.now();
+
+    // A and B retrieved 10 s apart — beyond 1 s window
+    const rows = [
+      {
+        id: 1,
+        entry_ids: JSON.stringify(['obs-P']),
+        created_at: new Date(now - 15_000).toISOString().replace('T', ' ').slice(0, 19),
+        retrieval_order: 0,
+        delta_ms: null,
+      },
+      {
+        id: 2,
+        entry_ids: JSON.stringify(['obs-Q']),
+        created_at: new Date(now - 5_000).toISOString().replace('T', ' ').slice(0, 19),
+        retrieval_order: 1,
+        delta_ms: 10_000,
+      },
+    ];
+
+    const db = buildNativeDb(rows, new Map());
+    mockGetBrainNativeDb.mockReturnValue(db);
+
+    const result = await applyStdpPlasticity(PROJECT_ROOT, shortWindow);
+
+    // Both rows are within cutoff (15 s < 1 h), but spike pair Δt = 10 s > 1 s window
+    expect(result.ltpEvents).toBe(0);
+    expect(result.ltdEvents).toBe(0);
+  });
+
+  it('does not apply LTD when no reverse edge exists', async () => {
+    const window = 5 * 60 * 1000;
+    const now = Date.now();
+
+    const rows = [
+      {
+        id: 1,
+        entry_ids: JSON.stringify(['obs-M']),
+        created_at: new Date(now - 10_000).toISOString().replace('T', ' ').slice(0, 19),
+        retrieval_order: 0,
+        delta_ms: null,
+      },
+      {
+        id: 2,
+        entry_ids: JSON.stringify(['obs-N']),
+        created_at: new Date(now - 5_000).toISOString().replace('T', ' ').slice(0, 19),
+        retrieval_order: 1,
+        delta_ms: 5000,
+      },
+    ];
+
+    // No existing edges at all
+    const db = buildNativeDb(rows, new Map());
+    mockGetBrainNativeDb.mockReturnValue(db);
+
+    const result = await applyStdpPlasticity(PROJECT_ROOT, window);
+
+    // LTP fires (new edge created), but LTD does NOT fire (no reverse edge)
+    expect(result.ltdEvents).toBe(0);
+    expect(result.ltpEvents).toBeGreaterThanOrEqual(1);
+  });
+
+  it('larger Δt produces smaller Δw (exponential decay)', async () => {
+    // We verify the formula directly without a real DB:
+    // Δw = A_PRE * exp(-Δt / TAU_PRE_MS)
+    // For Δt=1000 ms and Δt=10000 ms:
+    const A_PRE = 0.05;
+    const TAU = 20_000;
+    const dw1 = A_PRE * Math.exp(-1_000 / TAU);
+    const dw2 = A_PRE * Math.exp(-10_000 / TAU);
+    expect(dw1).toBeGreaterThan(dw2);
+    expect(dw2).toBeGreaterThan(0);
+  });
+
+  it('skips self-pairs (same entry ID)', async () => {
+    const window = 5 * 60 * 1000;
+    const now = Date.now();
+
+    // Two log rows each returning the same entry ID
+    const rows = [
+      {
+        id: 1,
+        entry_ids: JSON.stringify(['obs-SAME']),
+        created_at: new Date(now - 10_000).toISOString().replace('T', ' ').slice(0, 19),
+        retrieval_order: 0,
+        delta_ms: null,
+      },
+      {
+        id: 2,
+        entry_ids: JSON.stringify(['obs-SAME']),
+        created_at: new Date(now - 5_000).toISOString().replace('T', ' ').slice(0, 19),
+        retrieval_order: 1,
+        delta_ms: 5000,
+      },
+    ];
+
+    const db = buildNativeDb(rows, new Map());
+    mockGetBrainNativeDb.mockReturnValue(db);
+
+    const result = await applyStdpPlasticity(PROJECT_ROOT, window);
+
+    // pairsExamined may increment for the pair, but LTP must be 0 (self-pair skipped)
+    expect(result.ltpEvents).toBe(0);
+  });
+});
+
+// ============================================================================
+// Tests: getPlasticityStats
+// ============================================================================
+
+describe('getPlasticityStats', () => {
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('returns empty stats when nativeDb is null', async () => {
+    mockGetBrainDb.mockResolvedValue({});
+    mockGetBrainNativeDb.mockReturnValue(null);
+    const stats = await getPlasticityStats(PROJECT_ROOT);
+    expect(stats.totalEvents).toBe(0);
+    expect(stats.ltpCount).toBe(0);
+    expect(stats.ltdCount).toBe(0);
+    expect(stats.recentEvents).toHaveLength(0);
+  });
+
+  it('returns empty stats when plasticity_events table is absent', async () => {
+    mockGetBrainDb.mockResolvedValue({});
+    const db = {
+      prepare: vi.fn().mockReturnValue({
+        run: vi.fn(),
+        get: vi.fn().mockImplementation(() => {
+          throw new Error('no such table: brain_plasticity_events');
+        }),
+        all: vi.fn().mockReturnValue([]),
+      }),
+    };
+    mockGetBrainNativeDb.mockReturnValue(db);
+    const stats = await getPlasticityStats(PROJECT_ROOT);
+    expect(stats.totalEvents).toBe(0);
+  });
+
+  it('returns correct aggregates when events exist', async () => {
+    mockGetBrainDb.mockResolvedValue({});
+
+    const aggRow = {
+      total: 5,
+      ltp_count: 3,
+      ltd_count: 2,
+      net_delta_w: 0.12,
+      last_event_at: '2026-04-14 10:00:00',
+    };
+
+    const recentRows = [
+      {
+        id: 5,
+        source_node: 'observation:obs-A',
+        target_node: 'observation:obs-B',
+        delta_w: 0.04,
+        kind: 'ltp',
+        timestamp: '2026-04-14 10:00:00',
+        session_id: null,
+      },
+    ];
+
+    const db = {
+      prepare: vi.fn((sql: string) => {
+        if (sql.includes('SELECT 1') && sql.includes('brain_plasticity_events')) {
+          return { run: vi.fn(), get: vi.fn().mockReturnValue({}) };
+        }
+        if (sql.includes('COUNT(*)')) {
+          return { run: vi.fn(), get: vi.fn().mockReturnValue(aggRow) };
+        }
+        if (sql.includes('ORDER BY timestamp DESC')) {
+          return {
+            run: vi.fn(),
+            get: vi.fn(),
+            all: vi.fn().mockReturnValue(recentRows),
+          };
+        }
+        return { run: vi.fn(), get: vi.fn().mockReturnValue(undefined) };
+      }),
+    };
+    mockGetBrainNativeDb.mockReturnValue(db);
+
+    const stats = await getPlasticityStats(PROJECT_ROOT, 10);
+
+    expect(stats.totalEvents).toBe(5);
+    expect(stats.ltpCount).toBe(3);
+    expect(stats.ltdCount).toBe(2);
+    expect(stats.netDeltaW).toBeCloseTo(0.12);
+    expect(stats.lastEventAt).toBe('2026-04-14 10:00:00');
+    expect(stats.recentEvents).toHaveLength(1);
+    expect(stats.recentEvents[0]!.kind).toBe('ltp');
+    expect(stats.recentEvents[0]!.deltaW).toBeCloseTo(0.04);
+  });
+});