@1mbrain/core 0.1.0

package/src/events.ts

@@ -0,0 +1,142 @@
+/**
+ * Event Bus
+ *
+ * Handles memory events for the dashboard WebSocket stream.
+ * Supports Redis pub/sub for multi-instance deployments and
+ * an in-memory fallback for single-instance / development use.
+ */
+
+import type { MemoryEvent } from './types.js';
+import { createChildLogger } from './logger.js';
+
+const log = createChildLogger('event-bus');
+
+export type MemoryEventHandler = (event: MemoryEvent) => void;
+
+export interface EventBus {
+  publish(event: MemoryEvent): Promise<void>;
+  subscribe(handler: MemoryEventHandler): () => void;
+  close(): Promise<void>;
+}
+
+// ─── In-Memory Event Bus (development / single instance) ─
+
+export class InMemoryEventBus implements EventBus {
+  private handlers = new Set<MemoryEventHandler>();
+
+  async publish(event: MemoryEvent): Promise<void> {
+    log.debug({ type: event.type, memoryId: event.memoryId }, 'Publishing event (in-memory)');
+    for (const handler of this.handlers) {
+      try {
+        handler(event);
+      } catch (err) {
+        log.error({ err }, 'Event handler error');
+      }
+    }
+  }
+
+  subscribe(handler: MemoryEventHandler): () => void {
+    this.handlers.add(handler);
+    log.debug({ subscriberCount: this.handlers.size }, 'Subscriber added');
+
+    return () => {
+      this.handlers.delete(handler);
+      log.debug({ subscriberCount: this.handlers.size }, 'Subscriber removed');
+    };
+  }
+
+  async close(): Promise<void> {
+    this.handlers.clear();
+  }
+}
+
+// ─── Redis Event Bus (production / multi-instance) ──────
+
+export class RedisEventBus implements EventBus {
+  private handlers = new Set<MemoryEventHandler>();
+  private publisher: RedisClient | null = null;
+  private subscriber: RedisClient | null = null;
+  private readonly channel = '1mbrain:events';
+  private readonly redisUrl: string;
+
+  constructor(redisUrl: string) {
+    this.redisUrl = redisUrl;
+  }
+
+  async initialize(): Promise<void> {
+    const { default: Redis } = await import('ioredis');
+
+    this.publisher = new Redis(this.redisUrl) as unknown as RedisClient;
+    this.subscriber = new Redis(this.redisUrl) as unknown as RedisClient;
+
+    await this.subscriber.subscribe(this.channel);
+    this.subscriber.on('message', (_channel: string, message: string) => {
+      try {
+        const event = JSON.parse(message) as MemoryEvent;
+        event.timestamp = new Date(event.timestamp);
+        for (const handler of this.handlers) {
+          try {
+            handler(event);
+          } catch (err) {
+            log.error({ err }, 'Event handler error');
+          }
+        }
+      } catch (err) {
+        log.error({ err, message }, 'Failed to parse event');
+      }
+    });
+
+    log.info({ channel: this.channel }, 'Redis event bus initialized');
+  }
+
+  async publish(event: MemoryEvent): Promise<void> {
+    if (!this.publisher) {
+      throw new Error('Redis event bus not initialized');
+    }
+
+    const serialized = JSON.stringify(event);
+    await this.publisher.publish(this.channel, serialized);
+    log.debug({ type: event.type, memoryId: event.memoryId }, 'Publishing event (Redis)');
+  }
+
+  subscribe(handler: MemoryEventHandler): () => void {
+    this.handlers.add(handler);
+    return () => {
+      this.handlers.delete(handler);
+    };
+  }
+
+  async close(): Promise<void> {
+    if (this.subscriber) {
+      await this.subscriber.unsubscribe(this.channel);
+      await this.subscriber.quit();
+    }
+    if (this.publisher) {
+      await this.publisher.quit();
+    }
+    this.handlers.clear();
+    log.info('Redis event bus closed');
+  }
+}
+
+// Minimal Redis client interface to avoid tight coupling
+interface RedisClient {
+  publish(channel: string, message: string): Promise<number>;
+  subscribe(channel: string): Promise<void>;
+  unsubscribe(channel: string): Promise<void>;
+  on(event: string, handler: (...args: string[]) => void): void;
+  quit(): Promise<void>;
+}
+
+// ─── Factory ────────────────────────────────────────────
+
+export async function createEventBus(redisUrl?: string): Promise<EventBus> {
+  if (redisUrl) {
+    const bus = new RedisEventBus(redisUrl);
+    await bus.initialize();
+    return bus;
+  }
+
+  log.info('Using in-memory event bus (no Redis URL configured)');
+  return new InMemoryEventBus();
+}

package/src/index.ts

@@ -0,0 +1,83 @@
+/**
+ * @1mbrain/core
+ *
+ * Public API surface for the core package.
+ */
+
+// Types
+export type {
+  Memory,
+  MemoryType,
+  Association,
+  AssociationOrigin,
+  AssociationRelationType,
+  CreateMemoryInput,
+  SearchMemoryInput,
+  SearchResult,
+  CreateAssociationInput,
+  MemoryPassport,
+  MemoryPassportEnvelope,
+  EmbeddingProvider,
+  DatabaseProvider,
+  MemoryEvent,
+  MemoryEventType,
+  OneMBrainConfig,
+} from './types.js';
+
+// Schemas
+export {
+  CreateMemorySchema,
+  SearchMemorySchema,
+  CreateAssociationSchema,
+  ExportPassportSchema,
+  ImportPassportSchema,
+  MemoryTypeSchema,
+  AssociationOriginSchema,
+  AssociationRelationTypeSchema,
+} from './schemas.js';
+
+export type {
+  CreateMemoryPayload,
+  SearchMemoryQuery,
+  CreateAssociationPayload,
+  ExportPassportPayload,
+  ImportPassportPayload,
+} from './schemas.js';
+
+// Engine
+export { MemoryEngine } from './engine.js';
+export { RankingPolicy, analyzeQueryIntent } from './ranking-policy.js';
+export type { QueryIntent, RankedSearchResult, RankingOutcome } from './ranking-policy.js';
+
+// Memory Passport
+export {
+  createPassportEnvelope,
+  deserializePassport,
+  normalizeEncryptionKey,
+  openPassportEnvelope,
+  serializePassport,
+} from './passport.js';
+
+// Database
+export {
+  createDatabaseProvider,
+  SqliteDatabaseProvider,
+  PostgresDatabaseProvider,
+} from './db/index.js';
+
+// Embedding
+export {
+  createEmbeddingProvider,
+  OpenAIEmbeddingProvider,
+  OllamaEmbeddingProvider,
+} from './embedding/index.js';
+
+// Events
+export { createEventBus, InMemoryEventBus, RedisEventBus } from './events.js';
+export type { EventBus, MemoryEventHandler } from './events.js';
+
+// Config
+export { loadConfig } from './config.js';
+
+// Logger
+export { logger, createChildLogger } from './logger.js';

package/src/logger.ts

@@ -0,0 +1,31 @@
+/**
+ * Pino Logger
+ *
+ * Structured logging used throughout 1MBrain.
+ * Logs in JSON format for production, pretty-printed in development.
+ */
+
+import pino from 'pino';
+
+const isDev = process.env.NODE_ENV !== 'production';
+
+export const logger = pino({
+  level: process.env.LOG_LEVEL || (isDev ? 'debug' : 'info'),
+  transport: isDev
+    ? {
+        target: 'pino-pretty',
+        options: {
+          colorize: true,
+          translateTime: 'HH:MM:ss',
+          ignore: 'pid,hostname',
+        },
+      }
+    : undefined,
+  base: {
+    service: '1mbrain',
+  },
+});
+
+export function createChildLogger(name: string) {
+  return logger.child({ component: name });
+}

package/src/passport.ts

@@ -0,0 +1,118 @@
+import { createCipheriv, createDecipheriv, createHash, randomBytes } from 'node:crypto';
+import { gzipSync, gunzipSync } from 'node:zlib';
+import type { Association, Memory, MemoryPassport, MemoryPassportEnvelope } from './types.js';
+
+type SerializedMemory = Omit<Memory, 'createdAt' | 'lastAccessedAt'> & {
+  createdAt: string;
+  lastAccessedAt: string;
+};
+
+type SerializedAssociation = Omit<Association, 'createdAt'> & {
+  createdAt: string;
+};
+
+type SerializedPassport = Omit<MemoryPassport, 'exportedAt' | 'memories' | 'associations'> & {
+  exportedAt: string;
+  memories: SerializedMemory[];
+  associations: SerializedAssociation[];
+};
+
+export function serializePassport(passport: MemoryPassport): Buffer {
+  return Buffer.from(JSON.stringify(passport), 'utf8');
+}
+
+export function deserializePassport(input: Buffer | string): MemoryPassport {
+  const raw = typeof input === 'string' ? input : input.toString('utf8');
+  const parsed = JSON.parse(raw) as SerializedPassport;
+
+  return {
+    ...parsed,
+    exportedAt: new Date(parsed.exportedAt),
+    memories: parsed.memories.map((memory) => ({
+      ...memory,
+      createdAt: new Date(memory.createdAt),
+      lastAccessedAt: new Date(memory.lastAccessedAt),
+    })),
+    associations: parsed.associations.map((association) => ({
+      ...association,
+      createdAt: new Date(association.createdAt),
+    })),
+  };
+}
+
+export function createPassportEnvelope(
+  passport: MemoryPassport,
+  encryptionKey: string,
+): MemoryPassportEnvelope {
+  const key = normalizeEncryptionKey(encryptionKey);
+  const iv = randomBytes(12);
+  const cipher = createCipheriv('aes-256-gcm', key, iv);
+  const compressed = gzipSync(serializePassport(passport));
+  const encrypted = Buffer.concat([cipher.update(compressed), cipher.final()]);
+  const authTag = cipher.getAuthTag();
+
+  return {
+    format: '1mbrain.passport.envelope',
+    version: passport.version,
+    exportedAt: new Date(passport.exportedAt).toISOString(),
+    sourceAgent: passport.sourceAgent,
+    compression: 'gzip',
+    encoding: 'base64',
+    encryption: {
+      algorithm: 'aes-256-gcm',
+      iv: iv.toString('base64'),
+      authTag: authTag.toString('base64'),
+    },
+    payload: encrypted.toString('base64'),
+  };
+}
+
+export function openPassportEnvelope(
+  envelope: MemoryPassportEnvelope,
+  encryptionKey: string,
+): MemoryPassport {
+  if (envelope.format !== '1mbrain.passport.envelope') {
+    throw new Error('Unsupported Memory Passport envelope format');
+  }
+
+  if (
+    envelope.compression !== 'gzip' ||
+    envelope.encoding !== 'base64' ||
+    envelope.encryption.algorithm !== 'aes-256-gcm'
+  ) {
+    throw new Error('Unsupported Memory Passport envelope encoding');
+  }
+
+  const key = normalizeEncryptionKey(encryptionKey);
+  const decipher = createDecipheriv(
+    'aes-256-gcm',
+    key,
+    Buffer.from(envelope.encryption.iv, 'base64'),
+  );
+  decipher.setAuthTag(Buffer.from(envelope.encryption.authTag, 'base64'));
+
+  const compressed = Buffer.concat([
+    decipher.update(Buffer.from(envelope.payload, 'base64')),
+    decipher.final(),
+  ]);
+
+  return deserializePassport(gunzipSync(compressed));
+}
+
+export function normalizeEncryptionKey(input: string): Buffer {
+  const trimmed = input.trim();
+
+  if (/^[a-fA-F0-9]{64}$/.test(trimmed)) {
+    return Buffer.from(trimmed, 'hex');
+  }
+
+  const base64 = Buffer.from(trimmed, 'base64');
+  if (
+    base64.length === 32 &&
+    base64.toString('base64').replace(/=+$/, '') === trimmed.replace(/=+$/, '')
+  ) {
+    return base64;
+  }
+
+  return createHash('sha256').update(trimmed).digest();
+}