This repo has moved to brain-ecosystem. This repository is archived — all development continues in the monorepo. Install via
npm install @timmeck/brain-core(unchanged).
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, Trading Brain, Marketing Brain) into a single, reusable package. All packages live in the brain-ecosystem monorepo.
| Module | Description |
|---|---|
| IPC Protocol | Length-prefixed JSON frames over named pipes (Windows) / Unix sockets |
| IPC Server | Named pipe server with auto-recovery of stale pipes |
| IPC Client | Client with request/response, timeouts, and notification support |
| MCP Server | Stdio transport for Claude Code with auto-daemon-start |
| MCP HTTP Server | SSE transport for Cursor, Windsurf, Cline, Continue |
| REST API Server | Base HTTP server with CORS, auth, SSE events, batch RPC |
| DB Connection | SQLite (better-sqlite3) with WAL mode, foreign keys, caching |
| 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 |
| BaseMemoryEngine | Abstract timer-managed memory engine for expiry/consolidation/decay (new in v1.6) |
| Memory Types | Shared types for Memory, Session, Remember/Recall/Session interfaces (new in v1.6) |
| Utils | Path normalization, data dir resolution, SHA-256 hashing |
npm install @timmeck/brain-coreimport {
createLogger,
getDataDir,
getPipeName,
createConnection,
IpcServer,
IpcClient,
startMcpServer,
McpHttpServer,
BaseApiServer,
TypedEventBus,
c, header, keyValue,
} from '@timmeck/brain-core';
// 1. Configure for your brain
const dataDir = getDataDir('MY_BRAIN_DATA_DIR', '.my-brain');
createLogger({ envVar: 'MY_BRAIN_LOG_LEVEL', dataDir, defaultFilename: 'my-brain.log' });
// 2. Database
const db = createConnection(`${dataDir}/my-brain.db`);
// 3. Typed events
interface MyBrainEvents {
'item:created': { itemId: number };
'item:updated': { itemId: number };
}
const bus = new TypedEventBus<MyBrainEvents>();
bus.on('item:created', ({ itemId }) => console.log(`Item ${itemId} created`));
// 4. IPC Server
const router = new MyRouter(services); // implements IpcRouter interface
const ipcServer = new IpcServer(router, getPipeName('my-brain'), 'my-brain');
ipcServer.start();
// 5. REST API (extend BaseApiServer for custom routes)
class MyApiServer extends BaseApiServer {
protected buildRoutes() {
return [
{ method: 'GET', pattern: /^\/api\/v1\/items$/, ipcMethod: 'item.list',
extractParams: () => ({}) },
];
}
}
// 6. MCP Server (stdio)
await startMcpServer({
name: 'my-brain',
version: '1.0.0',
entryPoint: import.meta.filename,
registerTools: (server, ipc) => { /* register MCP tools */ },
});
// 7. CLI output
console.log(header('My Brain Status'));
console.log(keyValue('Items', 42));
console.log(c.success('All systems operational'));Your brain must implement the IpcRouter interface:
import type { IpcRouter } from '@timmeck/brain-core';
class MyRouter implements IpcRouter {
handle(method: string, params: unknown): unknown {
switch (method) {
case 'item.list': return this.itemService.list();
case 'item.get': return this.itemService.get(params);
default: throw new Error(`Unknown method: ${method}`);
}
}
listMethods(): string[] {
return ['item.list', 'item.get'];
}
}@timmeck/brain-core
├── 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)
├── Memory ────── BaseMemoryEngine, MemoryRecord, SessionRecord, shared interfaces
└── Cross-Brain ── CrossBrainClient, CrossBrainNotifier
| Brain | Version | Purpose | Ports |
|---|---|---|---|
| Brain | v2.2.1 | Error memory, code intelligence & persistent context | 7777/7778 |
| Trading Brain | v1.3.2 | Adaptive trading intelligence with memory & sessions | 7779/7780 |
| Marketing Brain | v0.5.2 | Content strategy & engagement with memory & sessions | 7781/7782/7783 |
| Brain Core | v1.6.1 | Shared infrastructure (this package) | — |
All packages live in the brain-ecosystem monorepo with npm workspaces. Brain Core provides shared infrastructure that eliminates ~2,800 lines of duplicated code across the ecosystem.
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.
import { CrossBrainClient, CrossBrainNotifier } from '@timmeck/brain-core';
// Query peers
const cross = new CrossBrainClient('brain');
const peers = await cross.getAvailablePeers();
// → [{ name: 'trading-brain', version: '1.3.2', uptime: 3600, pid: 12345, methods: 22 }, ...]
// 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 });Abstract base classes eliminate timer boilerplate from learning and research engines:
import { BaseLearningEngine, BaseResearchEngine, BaseMemoryEngine } from '@timmeck/brain-core';
class MyLearningEngine extends BaseLearningEngine {
runCycle() { /* your learning logic */ }
}
class MyResearchEngine extends BaseResearchEngine {
runCycle() { /* your research logic */ }
}
class MyMemoryEngine extends BaseMemoryEngine {
runCycle() { /* expiry checks, consolidation, importance decay */ }
}Visit the Brain Hub for the full ecosystem overview.
If Brain Core helps you, consider giving it a star — it helps others discover the project and keeps development going.
