@timmeck/brain-core 1.2.0 → 1.5.0

package/README.md

@@ -5,7 +5,7 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![GitHub stars](https://img.shields.io/github/stars/timmeck/brain-core)](https://github.com/timmeck/brain-core)
 
-**Shared infrastructure for the Brain ecosystem — IPC, MCP, CLI, DB, and utilities.**
+**Shared infrastructure for the Brain ecosystem — IPC, MCP, CLI, DB, math, synapses, and utilities.**
 
 Brain Core extracts the common infrastructure used across all Brain MCP servers ([Brain](https://github.com/timmeck/brain), [Trading Brain](https://github.com/timmeck/trading-brain), [Marketing Brain](https://github.com/timmeck/marketing-brain)) into a single, reusable package.
 
@@ -23,6 +23,15 @@ Brain Core extracts the common infrastructure used across all Brain MCP servers
 | **CLI Colors** | Shared color palette, formatting helpers (header, table, badges) |
 | **Logger** | Winston-based structured logging with file rotation |
 | **Event Bus** | Generic typed event emitter |
+| **Cross-Brain Client** | Discover and query peer brains over IPC named pipes |
+| **Cross-Brain Notifier** | Push event notifications to peer brains (new in v1.5) |
+| **Math — Wilson Score** | Statistical confidence intervals for win rates / rule confidence |
+| **Math — Time Decay** | Exponential half-life decay for synapse and rule freshness |
+| **Config Loader** | `deepMerge()` + `loadConfigFile()` for layered config |
+| **Synapse Algorithms** | Hebbian learning, decay, spreading activation, A* pathfinding |
+| **BaseSynapseManager** | Abstract synapse manager with strengthen/weaken/activate/findPath/decay |
+| **BaseLearningEngine** | Abstract timer-managed learning engine with error handling |
+| **BaseResearchEngine** | Abstract timer-managed research engine with optional initial delay |
 | **Utils** | Path normalization, data dir resolution, SHA-256 hashing |
 
 ## Installation
@@ -120,24 +129,65 @@ class MyRouter implements IpcRouter {
 
 ```
 @timmeck/brain-core
-├── Types ─── IpcMessage
-├── Utils ─── hash, logger, paths, events
-├── DB ────── SQLite connection (WAL mode)
-├── IPC ───── protocol, server, client
-├── MCP ───── stdio server, HTTP/SSE server
-├── CLI ───── colors, formatting helpers
-└── API ───── BaseApiServer (CORS, auth, RPC, SSE)
+├── Types ──────── IpcMessage, SynapseRecord, NodeRef, NetworkStats
+├── Utils ──────── hash, logger, paths, events
+├── DB ─────────── SQLite connection (WAL mode)
+├── IPC ────────── protocol, server, client
+├── MCP ────────── stdio server, HTTP/SSE server
+├── CLI ────────── colors, formatting helpers
+├── API ────────── BaseApiServer (CORS, auth, RPC, SSE)
+├── Math ───────── Wilson Score, Time Decay
+├── Config ─────── deepMerge, loadConfigFile
+├── Synapses ───── Hebbian, Decay, Activation, Pathfinder, BaseSynapseManager
+├── Learning ───── BaseLearningEngine (abstract, timer-managed)
+├── Research ───── BaseResearchEngine (abstract, timer-managed)
+└── Cross-Brain ── CrossBrainClient, CrossBrainNotifier
 ```
 
 ## Brain Ecosystem
 
-| Brain | Purpose | Ports |
-|-------|---------|-------|
-| [Brain](https://github.com/timmeck/brain) | Error memory & code intelligence | 7777/7778 |
-| [Trading Brain](https://github.com/timmeck/trading-brain) | Adaptive trading intelligence | 7779/7780 |
-| [Marketing Brain](https://github.com/timmeck/marketing-brain) | Content strategy & social media | 7781/7782/7783 |
+| Brain | Version | Purpose | Ports |
+|-------|---------|---------|-------|
+| [Brain](https://github.com/timmeck/brain) | v2.1.0 | Error memory & code intelligence | 7777/7778 |
+| [Trading Brain](https://github.com/timmeck/trading-brain) | v1.2.0 | Adaptive trading intelligence | 7779/7780 |
+| [Marketing Brain](https://github.com/timmeck/marketing-brain) | v0.4.0 | Content strategy & social media | 7781/7782/7783 |
+| [Brain Core](https://github.com/timmeck/brain-core) | v1.6.0 | Shared infrastructure (this package) | — |
 
-All three brains are standalone — brain-core is an **optional** shared dependency that eliminates code duplication.
+All three brains are standalone — brain-core is an **optional** shared dependency that eliminates ~600 lines of duplicated code across the ecosystem.
+
+## Cross-Brain Communication
+
+`CrossBrainClient` lets brains discover and query each other over IPC named pipes. Each brain exposes a `status` IPC method returning its name, version, uptime, pid, and method count — enabling automatic peer discovery without central coordination.
+
+```typescript
+import { CrossBrainClient, CrossBrainNotifier } from '@timmeck/brain-core';
+
+// Query peers
+const cross = new CrossBrainClient('brain');
+const peers = await cross.getAvailablePeers();
+// → [{ name: 'trading-brain', version: '1.2.0', uptime: 3600, pid: 12345, methods: 18 }, ...]
+
+// Push event notifications to peers (v1.5+)
+const notifier = new CrossBrainNotifier(cross, 'brain');
+notifier.notify('error:reported', { errorId: 42, fingerprint: 'ENOENT' });
+notifier.notifyPeer('trading-brain', 'insight:created', { insightId: 7 });
+```
+
+### Base Engines
+
+Abstract base classes eliminate timer boilerplate from learning and research engines:
+
+```typescript
+import { BaseLearningEngine, BaseResearchEngine } from '@timmeck/brain-core';
+
+class MyLearningEngine extends BaseLearningEngine {
+  runCycle() { /* your learning logic */ }
+}
+
+class MyResearchEngine extends BaseResearchEngine {
+  runCycle() { /* your research logic */ }
+}
+```
 
 Visit the [Brain Hub](https://timmeck.github.io/brain-hub/) for the full ecosystem overview.
 

package/brain.log

@@ -0,0 +1,6 @@
+2026-02-27T15:33:52.574Z [error] {"error":"Error: boom"} Learning cycle error
+2026-02-27T15:33:52.575Z [error] {"error":"Error: boom"} Research cycle error
+2026-02-27T15:36:06.467Z [error] {"error":"Error: boom"} Learning cycle error
+2026-02-27T15:36:06.471Z [error] {"error":"Error: boom"} Research cycle error
+2026-02-27T15:40:43.982Z [error] {"error":"Error: boom"} Research cycle error
+2026-02-27T15:40:43.982Z [error] {"error":"Error: boom"} Learning cycle error

package/dist/config/__tests__/loader.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/config/__tests__/loader.test.js

@@ -0,0 +1,85 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import fs from 'node:fs';
+import { deepMerge, loadConfigFile } from '../loader.js';
+describe('deepMerge', () => {
+    it('merges flat properties', () => {
+        const target = { a: 1, b: 2 };
+        deepMerge(target, { b: 3, c: 4 });
+        expect(target).toEqual({ a: 1, b: 3, c: 4 });
+    });
+    it('merges nested objects recursively', () => {
+        const target = { api: { port: 7777, enabled: true } };
+        deepMerge(target, { api: { port: 8080 } });
+        expect(target).toEqual({ api: { port: 8080, enabled: true } });
+    });
+    it('overwrites arrays (no merge)', () => {
+        const target = { tags: ['a', 'b'] };
+        deepMerge(target, { tags: ['c'] });
+        expect(target).toEqual({ tags: ['c'] });
+    });
+    it('ignores undefined values', () => {
+        const target = { a: 1 };
+        deepMerge(target, { a: undefined, b: 2 });
+        expect(target).toEqual({ a: 1, b: 2 });
+    });
+    it('handles deeply nested merge', () => {
+        const target = {
+            level1: {
+                level2: {
+                    level3: { keep: true, replace: 'old' },
+                },
+            },
+        };
+        deepMerge(target, {
+            level1: { level2: { level3: { replace: 'new' } } },
+        });
+        expect(target.level1.level2.level3).toEqual({ keep: true, replace: 'new' });
+    });
+});
+describe('loadConfigFile', () => {
+    beforeEach(() => {
+        vi.spyOn(fs, 'existsSync');
+        vi.spyOn(fs, 'readFileSync');
+    });
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+    it('returns defaults when no file exists', () => {
+        vi.mocked(fs.existsSync).mockReturnValue(false);
+        const defaults = { port: 8080, name: 'test' };
+        const result = loadConfigFile(defaults);
+        expect(result).toEqual(defaults);
+    });
+    it('merges config file into defaults', () => {
+        vi.mocked(fs.existsSync).mockReturnValue(true);
+        vi.mocked(fs.readFileSync).mockReturnValue(JSON.stringify({ port: 9090 }));
+        const defaults = { port: 8080, name: 'test' };
+        const result = loadConfigFile(defaults, '/some/config.json');
+        expect(result).toEqual({ port: 9090, name: 'test' });
+    });
+    it('uses defaultConfigPath as fallback', () => {
+        vi.mocked(fs.existsSync).mockReturnValue(true);
+        vi.mocked(fs.readFileSync).mockReturnValue(JSON.stringify({ name: 'custom' }));
+        const defaults = { port: 8080, name: 'test' };
+        const result = loadConfigFile(defaults, undefined, '/default/config.json');
+        expect(result).toEqual({ port: 8080, name: 'custom' });
+        expect(fs.existsSync).toHaveBeenCalledWith('/default/config.json');
+    });
+    it('does not mutate original defaults', () => {
+        vi.mocked(fs.existsSync).mockReturnValue(true);
+        vi.mocked(fs.readFileSync).mockReturnValue(JSON.stringify({ port: 9090 }));
+        const defaults = { port: 8080, name: 'test' };
+        loadConfigFile(defaults, '/some/config.json');
+        expect(defaults.port).toBe(8080);
+    });
+    it('handles nested config merge', () => {
+        vi.mocked(fs.existsSync).mockReturnValue(true);
+        vi.mocked(fs.readFileSync).mockReturnValue(JSON.stringify({
+            api: { port: 9999 },
+        }));
+        const defaults = { api: { port: 8080, enabled: true } };
+        const result = loadConfigFile(defaults, '/some/config.json');
+        expect(result).toEqual({ api: { port: 9999, enabled: true } });
+    });
+});
+//# sourceMappingURL=loader.test.js.map

package/dist/config/__tests__/loader.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.test.js","sourceRoot":"","sources":["../../../src/config/__tests__/loader.test.ts"],"names":[],"mappings":"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"}

package/dist/config/loader.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Deep-merge source into target. Recursively merges nested objects,
+ * overwrites primitives and arrays.
+ */
+export declare function deepMerge(target: Record<string, unknown>, source: Record<string, unknown>): void;
+/**
+ * Load and parse a JSON config file, merging it into defaults.
+ * If the file doesn't exist, returns the defaults unchanged.
+ *
+ * @param defaults The default config object (will be cloned)
+ * @param configPath Explicit config file path, or undefined for auto-detect
+ * @param defaultConfigPath Fallback path when configPath is not provided
+ * @returns Merged config object
+ */
+export declare function loadConfigFile<T>(defaults: T, configPath?: string, defaultConfigPath?: string): T;

package/dist/config/loader.js

@@ -0,0 +1,39 @@
+import fs from 'node:fs';
+import path from 'node:path';
+/**
+ * Deep-merge source into target. Recursively merges nested objects,
+ * overwrites primitives and arrays.
+ */
+export function deepMerge(target, source) {
+    for (const key of Object.keys(source)) {
+        const val = source[key];
+        if (val && typeof val === 'object' && !Array.isArray(val) && target[key] && typeof target[key] === 'object') {
+            deepMerge(target[key], val);
+        }
+        else if (val !== undefined) {
+            target[key] = val;
+        }
+    }
+}
+/**
+ * Load and parse a JSON config file, merging it into defaults.
+ * If the file doesn't exist, returns the defaults unchanged.
+ *
+ * @param defaults The default config object (will be cloned)
+ * @param configPath Explicit config file path, or undefined for auto-detect
+ * @param defaultConfigPath Fallback path when configPath is not provided
+ * @returns Merged config object
+ */
+export function loadConfigFile(defaults, configPath, defaultConfigPath) {
+    const config = structuredClone(defaults);
+    const filePath = configPath
+        ? path.resolve(configPath)
+        : defaultConfigPath;
+    if (filePath && fs.existsSync(filePath)) {
+        const raw = fs.readFileSync(filePath, 'utf-8');
+        const fileConfig = JSON.parse(raw);
+        deepMerge(config, fileConfig);
+    }
+    return config;
+}
+//# sourceMappingURL=loader.js.map

package/dist/config/loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.js","sourceRoot":"","sources":["../../src/config/loader.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B;;;GAGG;AACH,MAAM,UAAU,SAAS,CAAC,MAA+B,EAAE,MAA+B;IACxF,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;QACtC,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;QACxB,IAAI,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,IAAI,OAAO,MAAM,CAAC,GAAG,CAAC,KAAK,QAAQ,EAAE,CAAC;YAC5G,SAAS,CAAC,MAAM,CAAC,GAAG,CAA4B,EAAE,GAA8B,CAAC,CAAC;QACpF,CAAC;aAAM,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;YAC7B,MAAM,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC;QACpB,CAAC;IACH,CAAC;AACH,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,cAAc,CAC5B,QAAW,EACX,UAAmB,EACnB,iBAA0B;IAE1B,MAAM,MAAM,GAAG,eAAe,CAAC,QAAQ,CAAC,CAAC;IAEzC,MAAM,QAAQ,GAAG,UAAU;QACzB,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC;QAC1B,CAAC,CAAC,iBAAiB,CAAC;IAEtB,IAAI,QAAQ,IAAI,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;QACxC,MAAM,GAAG,GAAG,EAAE,CAAC,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QAC/C,MAAM,UAAU,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAe,CAAC;QACjD,SAAS,CAAC,MAA4C,EAAE,UAAgD,CAAC,CAAC;IAC5G,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/cross-brain/__tests__/notifications.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cross-brain/__tests__/notifications.test.js

@@ -0,0 +1,52 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+vi.mock('../../utils/logger.js', () => ({
+    getLogger: () => ({
+        debug: vi.fn(),
+        info: vi.fn(),
+        warn: vi.fn(),
+        error: vi.fn(),
+    }),
+}));
+import { CrossBrainNotifier } from '../notifications.js';
+import { CrossBrainClient } from '../client.js';
+describe('CrossBrainNotifier', () => {
+    let client;
+    let notifier;
+    beforeEach(() => {
+        client = new CrossBrainClient('brain');
+        vi.spyOn(client, 'broadcast').mockResolvedValue([]);
+        vi.spyOn(client, 'query').mockResolvedValue(null);
+        notifier = new CrossBrainNotifier(client, 'brain');
+    });
+    it('broadcasts notifications to all peers', async () => {
+        await notifier.notify('error:reported', { errorId: 1 });
+        expect(client.broadcast).toHaveBeenCalledWith('cross-brain.notify', expect.objectContaining({
+            source: 'brain',
+            event: 'error:reported',
+            data: { errorId: 1 },
+        }));
+    });
+    it('sends targeted notification to specific peer', async () => {
+        await notifier.notifyPeer('trading-brain', 'insight:created', { insightId: 5 });
+        expect(client.query).toHaveBeenCalledWith('trading-brain', 'cross-brain.notify', expect.objectContaining({
+            source: 'brain',
+            event: 'insight:created',
+            data: { insightId: 5 },
+        }));
+    });
+    it('includes timestamp in payload', async () => {
+        await notifier.notify('test', {});
+        const payload = client.broadcast.mock.calls[0][1];
+        expect(payload.timestamp).toBeDefined();
+        expect(new Date(payload.timestamp).getTime()).toBeGreaterThan(0);
+    });
+    it('does not throw when broadcast fails', async () => {
+        vi.spyOn(client, 'broadcast').mockRejectedValue(new Error('offline'));
+        await expect(notifier.notify('test', {})).resolves.toBeUndefined();
+    });
+    it('does not throw when peer query fails', async () => {
+        vi.spyOn(client, 'query').mockRejectedValue(new Error('offline'));
+        await expect(notifier.notifyPeer('trading-brain', 'test', {})).resolves.toBeUndefined();
+    });
+});
+//# sourceMappingURL=notifications.test.js.map

package/dist/cross-brain/__tests__/notifications.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"notifications.test.js","sourceRoot":"","sources":["../../../src/cross-brain/__tests__/notifications.test.ts"],"names":[],"mappings":"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"}

package/dist/cross-brain/notifications.d.ts

@@ -0,0 +1,25 @@
+import { CrossBrainClient } from './client.js';
+export interface CrossBrainEvent {
+    source: string;
+    event: string;
+    data: unknown;
+    timestamp: string;
+}
+/**
+ * Cross-Brain Notifier — sends event notifications to peer brains.
+ * Built on top of CrossBrainClient's query/broadcast infrastructure.
+ */
+export declare class CrossBrainNotifier {
+    private client;
+    private selfName;
+    private logger;
+    constructor(client: CrossBrainClient, selfName: string);
+    /**
+     * Notify all peers about an event.
+     */
+    notify(event: string, data: unknown): Promise<void>;
+    /**
+     * Notify a specific peer about an event.
+     */
+    notifyPeer(peerName: string, event: string, data: unknown): Promise<void>;
+}

package/dist/cross-brain/notifications.js

@@ -0,0 +1,51 @@
+import { getLogger } from '../utils/logger.js';
+/**
+ * Cross-Brain Notifier — sends event notifications to peer brains.
+ * Built on top of CrossBrainClient's query/broadcast infrastructure.
+ */
+export class CrossBrainNotifier {
+    client;
+    selfName;
+    logger = getLogger();
+    constructor(client, selfName) {
+        this.client = client;
+        this.selfName = selfName;
+    }
+    /**
+     * Notify all peers about an event.
+     */
+    async notify(event, data) {
+        const payload = {
+            source: this.selfName,
+            event,
+            data,
+            timestamp: new Date().toISOString(),
+        };
+        try {
+            await this.client.broadcast('cross-brain.notify', payload);
+            this.logger.debug(`Cross-brain notification sent: ${event}`);
+        }
+        catch {
+            this.logger.debug(`Cross-brain notification failed (peers may be offline): ${event}`);
+        }
+    }
+    /**
+     * Notify a specific peer about an event.
+     */
+    async notifyPeer(peerName, event, data) {
+        const payload = {
+            source: this.selfName,
+            event,
+            data,
+            timestamp: new Date().toISOString(),
+        };
+        try {
+            await this.client.query(peerName, 'cross-brain.notify', payload);
+            this.logger.debug(`Cross-brain notification sent to ${peerName}: ${event}`);
+        }
+        catch {
+            this.logger.debug(`Cross-brain notification to ${peerName} failed: ${event}`);
+        }
+    }
+}
+//# sourceMappingURL=notifications.js.map

package/dist/cross-brain/notifications.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"notifications.js","sourceRoot":"","sources":["../../src/cross-brain/notifications.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAS/C;;;GAGG;AACH,MAAM,OAAO,kBAAkB;IAGT;IAAkC;IAF9C,MAAM,GAAG,SAAS,EAAE,CAAC;IAE7B,YAAoB,MAAwB,EAAU,QAAgB;QAAlD,WAAM,GAAN,MAAM,CAAkB;QAAU,aAAQ,GAAR,QAAQ,CAAQ;IAAG,CAAC;IAE1E;;OAEG;IACH,KAAK,CAAC,MAAM,CAAC,KAAa,EAAE,IAAa;QACvC,MAAM,OAAO,GAAoB;YAC/B,MAAM,EAAE,IAAI,CAAC,QAAQ;YACrB,KAAK;YACL,IAAI;YACJ,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;SACpC,CAAC;QAEF,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,oBAAoB,EAAE,OAAO,CAAC,CAAC;YAC3D,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,kCAAkC,KAAK,EAAE,CAAC,CAAC;QAC/D,CAAC;QAAC,MAAM,CAAC;YACP,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,2DAA2D,KAAK,EAAE,CAAC,CAAC;QACxF,CAAC;IACH,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,UAAU,CAAC,QAAgB,EAAE,KAAa,EAAE,IAAa;QAC7D,MAAM,OAAO,GAAoB;YAC/B,MAAM,EAAE,IAAI,CAAC,QAAQ;YACrB,KAAK;YACL,IAAI;YACJ,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;SACpC,CAAC;QAEF,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,QAAQ,EAAE,oBAAoB,EAAE,OAAO,CAAC,CAAC;YACjE,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,oCAAoC,QAAQ,KAAK,KAAK,EAAE,CAAC,CAAC;QAC9E,CAAC;QAAC,MAAM,CAAC;YACP,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,+BAA+B,QAAQ,YAAY,KAAK,EAAE,CAAC,CAAC;QAChF,CAAC;IACH,CAAC;CACF"}

package/dist/index.d.ts

@@ -16,5 +16,21 @@ export type { McpHttpServerOptions } from './mcp/http-server.js';
 export { c, baseIcons, header, keyValue, statusBadge, progressBar, divider, table, stripAnsi } from './cli/colors.js';
 export { BaseApiServer } from './api/server.js';
 export type { ApiServerOptions, RouteDefinition } from './api/server.js';
+export { wilsonScore } from './math/wilson-score.js';
+export { timeDecayFactor } from './math/time-decay.js';
+export { deepMerge, loadConfigFile } from './config/loader.js';
+export type { NodeRef, SynapseRecord, ActivationResult, PathNode, SynapsePath, NetworkStats, HebbianConfig, DecayConfig, SynapseRepoInterface, } from './synapses/types.js';
+export type { SynapseManagerConfig } from './synapses/synapse-manager.js';
+export { strengthen, weaken } from './synapses/hebbian.js';
+export { decayAll } from './synapses/decay.js';
+export { spreadingActivation } from './synapses/activation.js';
+export { findPath } from './synapses/pathfinder.js';
+export { BaseSynapseManager } from './synapses/synapse-manager.js';
+export { BaseLearningEngine } from './learning/base-engine.js';
+export type { LearningEngineConfig } from './learning/base-engine.js';
+export { BaseResearchEngine } from './research/base-engine.js';
+export type { ResearchEngineConfig } from './research/base-engine.js';
 export { CrossBrainClient } from './cross-brain/client.js';
 export type { BrainPeer } from './cross-brain/client.js';
+export { CrossBrainNotifier } from './cross-brain/notifications.js';
+export type { CrossBrainEvent } from './cross-brain/notifications.js';

package/dist/index.js

@@ -16,6 +16,20 @@ export { McpHttpServer } from './mcp/http-server.js';
 export { c, baseIcons, header, keyValue, statusBadge, progressBar, divider, table, stripAnsi } from './cli/colors.js';
 // ── API ────────────────────────────────────────────────────
 export { BaseApiServer } from './api/server.js';
+// ── Math ───────────────────────────────────────────────────
+export { wilsonScore } from './math/wilson-score.js';
+export { timeDecayFactor } from './math/time-decay.js';
+// ── Config ─────────────────────────────────────────────────
+export { deepMerge, loadConfigFile } from './config/loader.js';
+export { strengthen, weaken } from './synapses/hebbian.js';
+export { decayAll } from './synapses/decay.js';
+export { spreadingActivation } from './synapses/activation.js';
+export { findPath } from './synapses/pathfinder.js';
+export { BaseSynapseManager } from './synapses/synapse-manager.js';
+// ── Engines ───────────────────────────────────────────────
+export { BaseLearningEngine } from './learning/base-engine.js';
+export { BaseResearchEngine } from './research/base-engine.js';
 // ── Cross-Brain ────────────────────────────────────────────
 export { CrossBrainClient } from './cross-brain/client.js';
+export { CrossBrainNotifier } from './cross-brain/notifications.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,8DAA8D;AAC9D,OAAO,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AACzC,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEzE,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC1E,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAElD,8DAA8D;AAC9D,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAEtD,8DAA8D;AAC9D,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAClE,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C,8DAA8D;AAC9D,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEjD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAGrD,8DAA8D;AAC9D,OAAO,EAAE,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,WAAW,EAAE,WAAW,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEtH,8DAA8D;AAC9D,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAGhD,8DAA8D;AAC9D,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,8DAA8D;AAC9D,OAAO,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAC;AACzC,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEzE,OAAO,EAAE,aAAa,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC1E,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAElD,8DAA8D;AAC9D,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAEtD,8DAA8D;AAC9D,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAClE,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE5C,8DAA8D;AAC9D,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEjD,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAGrD,8DAA8D;AAC9D,OAAO,EAAE,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,WAAW,EAAE,WAAW,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEtH,8DAA8D;AAC9D,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAGhD,8DAA8D;AAC9D,OAAO,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAEvD,8DAA8D;AAC9D,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAQ/D,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAC/C,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AACpD,OAAO,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AAEnE,6DAA6D;AAC7D,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAE/D,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAG/D,8DAA8D;AAC9D,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAE3D,OAAO,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC"}

package/dist/learning/__tests__/base-engine.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/learning/__tests__/base-engine.test.js

@@ -0,0 +1,49 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { BaseLearningEngine } from '../base-engine.js';
+class TestLearningEngine extends BaseLearningEngine {
+    cycleCount = 0;
+    runCycle() {
+        this.cycleCount++;
+        return { count: this.cycleCount };
+    }
+}
+describe('BaseLearningEngine', () => {
+    beforeEach(() => { vi.useFakeTimers(); });
+    afterEach(() => { vi.useRealTimers(); });
+    it('should run cycles at the configured interval', () => {
+        const engine = new TestLearningEngine({ intervalMs: 1000 });
+        engine.start();
+        expect(engine.cycleCount).toBe(0);
+        vi.advanceTimersByTime(1000);
+        expect(engine.cycleCount).toBe(1);
+        vi.advanceTimersByTime(2000);
+        expect(engine.cycleCount).toBe(3);
+        engine.stop();
+    });
+    it('should stop the timer', () => {
+        const engine = new TestLearningEngine({ intervalMs: 500 });
+        engine.start();
+        vi.advanceTimersByTime(500);
+        expect(engine.cycleCount).toBe(1);
+        engine.stop();
+        vi.advanceTimersByTime(2000);
+        expect(engine.cycleCount).toBe(1);
+    });
+    it('should handle errors in runCycle gracefully', () => {
+        class FailingEngine extends BaseLearningEngine {
+            runCycle() { throw new Error('boom'); }
+        }
+        const engine = new FailingEngine({ intervalMs: 100 });
+        engine.start();
+        // Should not throw
+        expect(() => vi.advanceTimersByTime(100)).not.toThrow();
+        engine.stop();
+    });
+    it('should be safe to call stop multiple times', () => {
+        const engine = new TestLearningEngine({ intervalMs: 1000 });
+        engine.start();
+        engine.stop();
+        engine.stop(); // No error
+    });
+});
+//# sourceMappingURL=base-engine.test.js.map

package/dist/learning/__tests__/base-engine.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-engine.test.js","sourceRoot":"","sources":["../../../src/learning/__tests__/base-engine.test.ts"],"names":[],"mappings":"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"}

package/dist/learning/base-engine.d.ts

@@ -0,0 +1,16 @@
+export interface LearningEngineConfig {
+    intervalMs: number;
+}
+/**
+ * Abstract base class for learning engines.
+ * Handles timer lifecycle — subclasses implement runCycle().
+ */
+export declare abstract class BaseLearningEngine {
+    protected engineConfig: LearningEngineConfig;
+    protected timer: ReturnType<typeof setInterval> | null;
+    protected logger: import("winston").Logger;
+    constructor(engineConfig: LearningEngineConfig);
+    start(): void;
+    stop(): void;
+    abstract runCycle(): unknown;
+}

package/dist/learning/base-engine.js

@@ -0,0 +1,30 @@
+import { getLogger } from '../utils/logger.js';
+/**
+ * Abstract base class for learning engines.
+ * Handles timer lifecycle — subclasses implement runCycle().
+ */
+export class BaseLearningEngine {
+    engineConfig;
+    timer = null;
+    logger = getLogger();
+    constructor(engineConfig) {
+        this.engineConfig = engineConfig;
+    }
+    start() {
+        this.timer = setInterval(() => {
+            try {
+                this.runCycle();
+            }
+            catch (err) {
+                this.logger.error('Learning cycle error', { error: String(err) });
+            }
+        }, this.engineConfig.intervalMs);
+    }
+    stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+    }
+}
+//# sourceMappingURL=base-engine.js.map

package/dist/learning/base-engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-engine.js","sourceRoot":"","sources":["../../src/learning/base-engine.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAM/C;;;GAGG;AACH,MAAM,OAAgB,kBAAkB;IAIhB;IAHZ,KAAK,GAA0C,IAAI,CAAC;IACpD,MAAM,GAAG,SAAS,EAAE,CAAC;IAE/B,YAAsB,YAAkC;QAAlC,iBAAY,GAAZ,YAAY,CAAsB;IAAG,CAAC;IAE5D,KAAK;QACH,IAAI,CAAC,KAAK,GAAG,WAAW,CAAC,GAAG,EAAE;YAC5B,IAAI,CAAC;gBACH,IAAI,CAAC,QAAQ,EAAE,CAAC;YAClB,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,sBAAsB,EAAE,EAAE,KAAK,EAAE,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YACpE,CAAC;QACH,CAAC,EAAE,IAAI,CAAC,YAAY,CAAC,UAAU,CAAC,CAAC;IACnC,CAAC;IAED,IAAI;QACF,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YACf,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YAC1B,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;QACpB,CAAC;IACH,CAAC;CAGF"}

package/dist/math/__tests__/time-decay.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/math/__tests__/time-decay.test.js

@@ -0,0 +1,37 @@
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { timeDecayFactor } from '../time-decay.js';
+describe('timeDecayFactor', () => {
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+    it('returns ~1.0 for just-activated item', () => {
+        const now = new Date().toISOString();
+        const factor = timeDecayFactor(now, 30);
+        expect(factor).toBeGreaterThan(0.99);
+        expect(factor).toBeLessThanOrEqual(1.0);
+    });
+    it('returns ~0.5 at exactly one half-life', () => {
+        const halfLifeDays = 30;
+        const activatedAt = new Date(Date.now() - halfLifeDays * 24 * 60 * 60 * 1000).toISOString();
+        const factor = timeDecayFactor(activatedAt, halfLifeDays);
+        expect(factor).toBeCloseTo(0.5, 1);
+    });
+    it('returns ~0.25 at two half-lives', () => {
+        const halfLifeDays = 14;
+        const activatedAt = new Date(Date.now() - 28 * 24 * 60 * 60 * 1000).toISOString();
+        const factor = timeDecayFactor(activatedAt, halfLifeDays);
+        expect(factor).toBeCloseTo(0.25, 1);
+    });
+    it('returns very small value for very old items', () => {
+        const activatedAt = new Date(Date.now() - 365 * 24 * 60 * 60 * 1000).toISOString();
+        const factor = timeDecayFactor(activatedAt, 30);
+        expect(factor).toBeLessThan(0.01);
+    });
+    it('works with different half-life values', () => {
+        const activatedAt = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000).toISOString();
+        const shortHalfLife = timeDecayFactor(activatedAt, 7);
+        const longHalfLife = timeDecayFactor(activatedAt, 45);
+        expect(shortHalfLife).toBeLessThan(longHalfLife);
+    });
+});
+//# sourceMappingURL=time-decay.test.js.map

package/dist/math/__tests__/time-decay.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"time-decay.test.js","sourceRoot":"","sources":["../../../src/math/__tests__/time-decay.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AAC7D,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAEnD,QAAQ,CAAC,iBAAiB,EAAE,GAAG,EAAE;IAC/B,SAAS,CAAC,GAAG,EAAE;QACb,EAAE,CAAC,eAAe,EAAE,CAAC;IACvB,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,sCAAsC,EAAE,GAAG,EAAE;QAC9C,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QACrC,MAAM,MAAM,GAAG,eAAe,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;QACxC,MAAM,CAAC,MAAM,CAAC,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC;QACrC,MAAM,CAAC,MAAM,CAAC,CAAC,mBAAmB,CAAC,GAAG,CAAC,CAAC;IAC1C,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,uCAAuC,EAAE,GAAG,EAAE;QAC/C,MAAM,YAAY,GAAG,EAAE,CAAC;QACxB,MAAM,WAAW,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,YAAY,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,WAAW,EAAE,CAAC;QAC5F,MAAM,MAAM,GAAG,eAAe,CAAC,WAAW,EAAE,YAAY,CAAC,CAAC;QAC1D,MAAM,CAAC,MAAM,CAAC,CAAC,WAAW,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;IACrC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,iCAAiC,EAAE,GAAG,EAAE;QACzC,MAAM,YAAY,GAAG,EAAE,CAAC;QACxB,MAAM,WAAW,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,WAAW,EAAE,CAAC;QAClF,MAAM,MAAM,GAAG,eAAe,CAAC,WAAW,EAAE,YAAY,CAAC,CAAC;QAC1D,MAAM,CAAC,MAAM,CAAC,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;IACtC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,6CAA6C,EAAE,GAAG,EAAE;QACrD,MAAM,WAAW,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,GAAG,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,WAAW,EAAE,CAAC;QACnF,MAAM,MAAM,GAAG,eAAe,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC;QAChD,MAAM,CAAC,MAAM,CAAC,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC;IACpC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,uCAAuC,EAAE,GAAG,EAAE;QAC/C,MAAM,WAAW,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,WAAW,EAAE,CAAC;QACjF,MAAM,aAAa,GAAG,eAAe,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC;QACtD,MAAM,YAAY,GAAG,eAAe,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC;QACtD,MAAM,CAAC,aAAa,CAAC,CAAC,YAAY,CAAC,YAAY,CAAC,CAAC;IACnD,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/math/__tests__/wilson-score.test.d.ts

@@ -0,0 +1 @@
+export {};