@timmeck/brain-core 1.5.1 → 1.6.1

package/README.md

@@ -3,11 +3,11 @@
 [![npm version](https://img.shields.io/npm/v/@timmeck/brain-core)](https://www.npmjs.com/package/@timmeck/brain-core)
 [![npm downloads](https://img.shields.io/npm/dm/@timmeck/brain-core)](https://www.npmjs.com/package/@timmeck/brain-core)
 [![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)
+[![GitHub stars](https://img.shields.io/github/stars/timmeck/brain-ecosystem?style=social)](https://github.com/timmeck/brain-ecosystem)
 
 **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.
+Brain Core extracts the common infrastructure used across all Brain MCP servers ([Brain](https://github.com/timmeck/brain-ecosystem/tree/main/packages/brain), [Trading Brain](https://github.com/timmeck/brain-ecosystem/tree/main/packages/trading-brain), [Marketing Brain](https://github.com/timmeck/brain-ecosystem/tree/main/packages/marketing-brain)) into a single, reusable package. All packages live in the [brain-ecosystem](https://github.com/timmeck/brain-ecosystem) monorepo.
 
 ## What's Included
 
@@ -32,6 +32,8 @@ Brain Core extracts the common infrastructure used across all Brain MCP servers
 | **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 |
 
 ## Installation
@@ -141,6 +143,7 @@ class MyRouter implements IpcRouter {
 ├── 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
 ```
 
@@ -148,12 +151,12 @@ class MyRouter implements IpcRouter {
 
 | 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.5.0 | Shared infrastructure (this package) | — |
+| [Brain](https://github.com/timmeck/brain-ecosystem/tree/main/packages/brain) | v2.2.1 | Error memory, code intelligence & persistent context | 7777/7778 |
+| [Trading Brain](https://github.com/timmeck/brain-ecosystem/tree/main/packages/trading-brain) | v1.3.2 | Adaptive trading intelligence with memory & sessions | 7779/7780 |
+| [Marketing Brain](https://github.com/timmeck/brain-ecosystem/tree/main/packages/marketing-brain) | v0.5.2 | Content strategy & engagement with memory & sessions | 7781/7782/7783 |
+| [Brain Core](https://github.com/timmeck/brain-ecosystem/tree/main/packages/brain-core) | v1.6.1 | Shared infrastructure (this package) | — |
 
-All three brains are standalone — brain-core is an **optional** shared dependency that eliminates ~600 lines of duplicated code across the ecosystem.
+All packages live in the [brain-ecosystem](https://github.com/timmeck/brain-ecosystem) monorepo with npm workspaces. Brain Core provides shared infrastructure that eliminates ~2,800 lines of duplicated code across the ecosystem.
 
 ## Cross-Brain Communication
 
@@ -165,7 +168,7 @@ 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 }, ...]
+// → [{ 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');
@@ -178,7 +181,7 @@ notifier.notifyPeer('trading-brain', 'insight:created', { insightId: 7 });
 Abstract base classes eliminate timer boilerplate from learning and research engines:
 
 ```typescript
-import { BaseLearningEngine, BaseResearchEngine } from '@timmeck/brain-core';
+import { BaseLearningEngine, BaseResearchEngine, BaseMemoryEngine } from '@timmeck/brain-core';
 
 class MyLearningEngine extends BaseLearningEngine {
   runCycle() { /* your learning logic */ }
@@ -187,10 +190,21 @@ class MyLearningEngine extends BaseLearningEngine {
 class MyResearchEngine extends BaseResearchEngine {
   runCycle() { /* your research logic */ }
 }
+
+class MyMemoryEngine extends BaseMemoryEngine {
+  runCycle() { /* expiry checks, consolidation, importance decay */ }
+}
 ```
 
 Visit the [Brain Hub](https://timmeck.github.io/brain-hub/) for the full ecosystem overview.
 
+## Support
+
+If Brain Core helps you, consider giving it a star — it helps others discover the project and keeps development going.
+
+[![Star this repo](https://img.shields.io/github/stars/timmeck/brain-ecosystem?style=social)](https://github.com/timmeck/brain-ecosystem)
+[![Sponsor](https://img.shields.io/badge/Sponsor-Support%20Development-ea4aaa)](https://github.com/sponsors/timmeck)
+
 ## License
 
 [MIT](LICENSE)

package/dist/index.d.ts

@@ -30,6 +30,8 @@ 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 type { MemoryRecord, SessionRecord, MemoryCategory, MemorySource, SessionOutcome, RememberInput, RecallInput, StartSessionInput, EndSessionInput, MemoryRepoInterface, SessionRepoInterface, MemoryEngineConfig, } from './memory/types.js';
+export { BaseMemoryEngine } from './memory/base-memory-engine.js';
 export { CrossBrainClient } from './cross-brain/client.js';
 export type { BrainPeer } from './cross-brain/client.js';
 export { CrossBrainNotifier } from './cross-brain/notifications.js';

package/dist/index.js

@@ -29,6 +29,7 @@ export { BaseSynapseManager } from './synapses/synapse-manager.js';
 // ── Engines ───────────────────────────────────────────────
 export { BaseLearningEngine } from './learning/base-engine.js';
 export { BaseResearchEngine } from './research/base-engine.js';
+export { BaseMemoryEngine } from './memory/base-memory-engine.js';
 // ── Cross-Brain ────────────────────────────────────────────
 export { CrossBrainClient } from './cross-brain/client.js';
 export { CrossBrainNotifier } from './cross-brain/notifications.js';

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,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"}
+{"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;AAU/D,OAAO,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAElE,8DAA8D;AAC9D,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAE3D,OAAO,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC"}

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

@@ -0,0 +1,19 @@
+import type { MemoryEngineConfig } from './types.js';
+/**
+ * Abstract base class for memory engines.
+ * Handles timer lifecycle for periodic memory maintenance:
+ * - Expiry checks (deactivate expired memories)
+ * - Consolidation (merge similar memories)
+ * - Importance decay (reduce importance of never-recalled memories)
+ *
+ * Subclasses implement runCycle().
+ */
+export declare abstract class BaseMemoryEngine {
+    protected config: MemoryEngineConfig;
+    protected timer: ReturnType<typeof setInterval> | null;
+    protected logger: import("winston").Logger;
+    constructor(config: MemoryEngineConfig);
+    start(): void;
+    stop(): void;
+    abstract runCycle(): unknown;
+}

package/dist/memory/base-memory-engine.js

@@ -0,0 +1,35 @@
+import { getLogger } from '../utils/logger.js';
+/**
+ * Abstract base class for memory engines.
+ * Handles timer lifecycle for periodic memory maintenance:
+ * - Expiry checks (deactivate expired memories)
+ * - Consolidation (merge similar memories)
+ * - Importance decay (reduce importance of never-recalled memories)
+ *
+ * Subclasses implement runCycle().
+ */
+export class BaseMemoryEngine {
+    config;
+    timer = null;
+    logger = getLogger();
+    constructor(config) {
+        this.config = config;
+    }
+    start() {
+        this.timer = setInterval(() => {
+            try {
+                this.runCycle();
+            }
+            catch (err) {
+                this.logger.error('Memory engine cycle error', { error: String(err) });
+            }
+        }, this.config.intervalMs);
+    }
+    stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+    }
+}
+//# sourceMappingURL=base-memory-engine.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"base-memory-engine.js","sourceRoot":"","sources":["../../src/memory/base-memory-engine.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAG/C;;;;;;;;GAQG;AACH,MAAM,OAAgB,gBAAgB;IAId;IAHZ,KAAK,GAA0C,IAAI,CAAC;IACpD,MAAM,GAAG,SAAS,EAAE,CAAC;IAE/B,YAAsB,MAA0B;QAA1B,WAAM,GAAN,MAAM,CAAoB;IAAG,CAAC;IAEpD,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,2BAA2B,EAAE,EAAE,KAAK,EAAE,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YACzE,CAAC;QACH,CAAC,EAAE,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;IAC7B,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/memory/types.d.ts

@@ -0,0 +1,88 @@
+export type MemoryCategory = 'preference' | 'decision' | 'context' | 'fact' | 'goal' | 'lesson';
+export type MemorySource = 'explicit' | 'inferred' | 'hook';
+export type SessionOutcome = 'completed' | 'paused' | 'abandoned';
+export interface MemoryRecord {
+    id: number;
+    project_id: number | null;
+    session_id: number | null;
+    category: MemoryCategory;
+    key: string | null;
+    content: string;
+    importance: number;
+    source: MemorySource;
+    tags: string | null;
+    expires_at: string | null;
+    superseded_by: number | null;
+    active: number;
+    created_at: string;
+    updated_at: string;
+    embedding: Buffer | null;
+}
+export interface SessionRecord {
+    id: number;
+    session_id: string;
+    project_id: number | null;
+    started_at: string;
+    ended_at: string | null;
+    summary: string | null;
+    goals: string | null;
+    outcome: SessionOutcome | null;
+    metadata: string | null;
+    embedding: Buffer | null;
+}
+export interface RememberInput {
+    content: string;
+    category: MemoryCategory;
+    key?: string;
+    importance?: number;
+    source?: MemorySource;
+    tags?: string[];
+    projectId?: number;
+    sessionId?: number;
+    expiresAt?: string;
+}
+export interface RecallInput {
+    query: string;
+    category?: MemoryCategory;
+    projectId?: number;
+    limit?: number;
+    activeOnly?: boolean;
+}
+export interface StartSessionInput {
+    sessionId?: string;
+    projectId?: number;
+    goals?: string[];
+    metadata?: Record<string, unknown>;
+}
+export interface EndSessionInput {
+    sessionId: number;
+    summary: string;
+    outcome?: SessionOutcome;
+}
+export interface MemoryRepoInterface {
+    create(data: Omit<MemoryRecord, 'id' | 'created_at' | 'updated_at'>): number;
+    getById(id: number): MemoryRecord | undefined;
+    findByKey(projectId: number | null, key: string): MemoryRecord | undefined;
+    findByCategory(category: MemoryCategory, projectId?: number, limit?: number): MemoryRecord[];
+    findActive(projectId?: number, limit?: number): MemoryRecord[];
+    search(query: string, limit?: number): MemoryRecord[];
+    supersede(oldId: number, newId: number): void;
+    deactivate(id: number): void;
+    expireOld(): number;
+    update(id: number, data: Partial<MemoryRecord>): void;
+}
+export interface SessionRepoInterface {
+    create(data: Omit<SessionRecord, 'id'>): number;
+    getById(id: number): SessionRecord | undefined;
+    findBySessionId(sessionId: string): SessionRecord | undefined;
+    findByProject(projectId: number, limit?: number): SessionRecord[];
+    findRecent(limit?: number): SessionRecord[];
+    update(id: number, data: Partial<SessionRecord>): void;
+    search(query: string, limit?: number): SessionRecord[];
+}
+export interface MemoryEngineConfig {
+    intervalMs: number;
+    expiryCheckEnabled: boolean;
+    consolidationEnabled: boolean;
+    importanceDecayDays: number;
+}

package/dist/memory/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/memory/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/memory/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timmeck/brain-core",
-  "version": "1.5.1",
+  "version": "1.6.1",
   "description": "Shared core infrastructure for the Brain ecosystem — IPC, MCP, CLI, DB connection, and utilities",
   "type": "module",
   "main": "dist/index.js",
@@ -29,12 +29,14 @@
     "./synapses/activation": "./dist/synapses/activation.js",
     "./synapses/pathfinder": "./dist/synapses/pathfinder.js",
     "./synapses/synapse-manager": "./dist/synapses/synapse-manager.js",
-    "./cross-brain": "./dist/cross-brain/client.js"
+    "./cross-brain": "./dist/cross-brain/client.js",
+    "./memory/types": "./dist/memory/types.js",
+    "./memory/base-memory-engine": "./dist/memory/base-memory-engine.js"
   },
   "scripts": {
     "build": "tsc",
     "dev": "tsx src/index.ts",
-    "test": "vitest",
+    "test": "vitest run",
     "lint": "eslint src/",
     "lint:fix": "eslint src/ --fix",
     "test:coverage": "vitest --coverage"
@@ -60,7 +62,8 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/timmeck/brain-core"
+    "url": "https://github.com/timmeck/brain-ecosystem",
+    "directory": "packages/brain-core"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",

package/brain.log

@@ -1,6 +0,0 @@
-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