@1mbrain/core 0.1.0

package/src/types.ts

@@ -0,0 +1,229 @@
+/**
+ * 1MBrain Core Types
+ *
+ * Central type definitions for the memory engine.
+ * These types are the contract between all layers of the system.
+ */
+
+// ─── Memory Types ────────────────────────────────────────
+
+export type MemoryType = 'episodic' | 'semantic' | 'procedural' | 'entity' | 'warning';
+
+export type AssociationOrigin = 'co-occurrence' | 'similarity' | 'explicit';
+
+export type AssociationRelationType = 'relates_to' | 'supersedes' | 'derived_from';
+
+export interface Memory {
+  id: string;
+  agentId: string;
+  type: MemoryType;
+  content: string;
+  embeddingModel: string | null;
+  embedding: number[] | null;
+  importance: number;
+  decayScore: number;
+  createdAt: Date;
+  lastAccessedAt: Date;
+  tags: string[];
+  /** Optional structured metadata — e.g. sourceUrl, confidence, evidence from ingest pipeline. */
+  metadata?: Record<string, unknown>;
+}
+
+export interface Association {
+  sourceId: string;
+  targetId: string;
+  strength: number;
+  origin: AssociationOrigin;
+  /** Semantic meaning of the relationship. Defaults to 'relates_to'. */
+  relationType: AssociationRelationType;
+  createdAt: Date;
+}
+
+// ─── API Request/Response Types ─────────────────────────
+
+export interface CreateMemoryInput {
+  agentId: string;
+  type: MemoryType;
+  content: string;
+  importance?: number;
+  tags?: string[];
+  /** Optional structured metadata stored alongside the memory (e.g. sourceUrl, evidence, confidence). */
+  metadata?: Record<string, unknown>;
+  associations?: Array<{
+    targetId: string;
+    strength?: number;
+    relationType?: AssociationRelationType;
+  }>;
+}
+
+export interface SearchMemoryInput {
+  agentId: string;
+  query: string;
+  type?: MemoryType;
+  tags?: string[];
+  limit?: number;
+  threshold?: number;
+  useSpreadingActivation?: boolean;
+  maxHops?: number;
+  activationThreshold?: number;
+  blendWeight?: number;
+}
+
+export interface SearchResult {
+  memory: Memory;
+  score: number;
+  source: 'vector' | 'association' | 'combined' | 'lexical';
+  rankingTrace?: string[];
+}
+
+export interface CreateAssociationInput {
+  sourceId: string;
+  targetId: string;
+  agentId?: string;
+  strength?: number;
+  origin?: AssociationOrigin;
+  relationType?: AssociationRelationType;
+}
+
+// ─── Memory Passport Types ──────────────────────────────
+
+export interface MemoryPassport {
+  version: string;
+  exportedAt: Date;
+  sourceAgent: string;
+  embeddingModel: string;
+  memories: Memory[];
+  associations: Association[];
+  metadata: {
+    totalMemories: number;
+    totalAssociations: number;
+    memoryTypes: Record<MemoryType, number>;
+  };
+}
+
+export interface MemoryPassportEnvelope {
+  format: '1mbrain.passport.envelope';
+  version: string;
+  exportedAt: string;
+  sourceAgent: string;
+  compression: 'gzip';
+  encoding: 'base64';
+  encryption: {
+    algorithm: 'aes-256-gcm';
+    iv: string;
+    authTag: string;
+  };
+  payload: string;
+}
+
+// ─── Embedding Provider Interface ───────────────────────
+
+export interface EmbeddingProvider {
+  readonly name: string;
+  readonly model: string;
+  readonly dimensions: number;
+  embed(text: string): Promise<number[]>;
+  embedBatch(texts: string[]): Promise<number[][]>;
+}
+
+// ─── Event Types (for WebSocket/Pub-Sub) ────────────────
+
+export type MemoryEventType =
+  | 'memory:created'
+  | 'memory:accessed'
+  | 'memory:updated'
+  | 'memory:deleted'
+  | 'memory:consolidated'
+  | 'association:created'
+  | 'association:deleted';
+
+export interface MemoryEvent {
+  type: MemoryEventType;
+  memoryId: string;
+  agentId: string;
+  memoryType?: MemoryType;
+  timestamp: Date;
+  data?: Record<string, unknown>;
+}
+
+// ─── Database Provider Interface ────────────────────────
+
+export interface DatabaseProvider {
+  // Memory CRUD
+  createMemory(memory: Omit<Memory, 'createdAt' | 'lastAccessedAt'>): Promise<Memory>;
+  getMemoryById(id: string, agentId: string): Promise<Memory | null>;
+  updateMemory(id: string, agentId: string, updates: Partial<Memory>): Promise<Memory | null>;
+  deleteMemory(id: string, agentId: string): Promise<boolean>;
+
+  // Vector search
+  searchByVector(
+    agentId: string,
+    embedding: number[],
+    options: {
+      limit?: number;
+      threshold?: number;
+      type?: MemoryType;
+      tags?: string[];
+    },
+  ): Promise<Array<{ memory: Memory; similarity: number }>>;
+
+  // Associations
+  createAssociation(association: Omit<Association, 'createdAt'>): Promise<Association>;
+  getAssociations(memoryId: string): Promise<Association[]>;
+  deleteAssociations(memoryId: string): Promise<number>;
+
+  // Bulk operations
+  listAgentIds(): Promise<string[]>;
+  getAllMemories(agentId: string): Promise<Memory[]>;
+  getAllAssociations(agentId: string): Promise<Association[]>;
+  bulkCreateMemories(
+    memories: Array<Omit<Memory, 'createdAt' | 'lastAccessedAt'>>,
+  ): Promise<Memory[]>;
+  bulkCreateAssociations(
+    associations: Array<Omit<Association, 'createdAt'>>,
+  ): Promise<Association[]>;
+
+  // Decay
+  applyDecay(decayRate: number, minScore: number): Promise<number>;
+  applyAssociationDecay(decayRate: number, minStrength: number): Promise<number>;
+
+  // Lifecycle
+  initialize(): Promise<void>;
+  close(): Promise<void>;
+}
+
+// ─── Config Types ───────────────────────────────────────
+
+export interface OneMBrainConfig {
+  database: {
+    provider: 'sqlite' | 'postgres';
+    sqlitePath?: string;
+    postgresUrl?: string;
+  };
+  embedding: {
+    provider: 'openai' | 'ollama' | 'claude' | 'local-keyword';
+    openai?: {
+      apiKey: string;
+      model: string;
+    };
+    ollama?: {
+      baseUrl: string;
+      model: string;
+    };
+    claude?: {
+      apiKey: string;
+      model: string;
+    };
+    localKeyword?: {
+      dimensions?: number;
+    };
+  };
+  redis?: {
+    url: string;
+  };
+  decay?: {
+    rate: number;
+    intervalMs: number;
+    minScore: number;
+  };
+}

package/tests/benchmark.ts

@@ -0,0 +1,125 @@
+/**
+ * Recall Accuracy & Latency Benchmark
+ *
+ * Compares pure vector recall against vector + spreading activation using
+ * SQLite in-memory storage. Run with:
+ *
+ *   npm exec --workspace=packages/core tsx tests/benchmark.ts
+ */
+
+import { performance } from 'node:perf_hooks';
+import { fileURLToPath } from 'node:url';
+import { MemoryEngine } from '../src/engine.js';
+import { SqliteDatabaseProvider } from '../src/db/sqlite-provider.js';
+import { InMemoryEventBus } from '../src/events.js';
+import { logger } from '../src/logger.js';
+import type { EmbeddingProvider, Memory } from '../src/types.js';
+
+class KeywordEmbeddingProvider implements EmbeddingProvider {
+  readonly name = 'keyword-benchmark';
+  readonly model = 'keyword-benchmark-v1';
+  readonly dimensions = 12;
+
+  async embed(text: string): Promise<number[]> {
+    const lower = text.toLowerCase();
+    const keywords = [
+      'alpha',
+      'beta',
+      'pricing',
+      'language',
+      'typescript',
+      'backup',
+      'drive',
+      'memory',
+      'dashboard',
+      'agent',
+      'procedure',
+      'preference',
+    ];
+
+    return keywords.map((keyword) => (lower.includes(keyword) ? 1 : 0));
+  }
+
+  async embedBatch(texts: string[]): Promise<number[][]> {
+    return Promise.all(texts.map((text) => this.embed(text)));
+  }
+}
+
+async function runBenchmark() {
+  logger.level = 'warn';
+  console.warn('--- 1MBrain Recall Benchmark ---');
+
+  const db = new SqliteDatabaseProvider(':memory:');
+  await db.initialize();
+  const engine = new MemoryEngine(db, new KeywordEmbeddingProvider(), new InMemoryEventBus());
+
+  try {
+    const memories: Memory[] = [];
+    for (let i = 0; i < 40; i++) {
+      memories.push(
+        await engine.remember({
+          agentId: 'bench-agent',
+          type: i % 3 === 0 ? 'episodic' : i % 3 === 1 ? 'semantic' : 'procedural',
+          content: `memory item ${i} ${i % 5 === 0 ? 'alpha pricing' : 'dashboard agent'}`,
+          tags: [`bucket-${i % 10}`],
+        }),
+      );
+    }
+
+    const seed = await engine.remember({
+      agentId: 'bench-agent',
+      type: 'semantic',
+      content: 'alpha pricing policy',
+      tags: ['target'],
+    });
+    const graphOnly = await engine.remember({
+      agentId: 'bench-agent',
+      type: 'procedural',
+      content: 'procedure for renewal escalation',
+      tags: ['target'],
+    });
+
+    await engine.associate({
+      sourceId: seed.id,
+      targetId: graphOnly.id,
+      agentId: 'bench-agent',
+      strength: 1,
+      origin: 'explicit',
+    });
+
+    const vectorStart = performance.now();
+    const vectorOnly = await engine.recall({
+      agentId: 'bench-agent',
+      query: 'alpha pricing',
+      limit: 20,
+      threshold: 0.75,
+      useSpreadingActivation: false,
+    });
+    const vectorMs = performance.now() - vectorStart;
+
+    const graphStart = performance.now();
+    const spread = await engine.recall({
+      agentId: 'bench-agent',
+      query: 'alpha pricing',
+      limit: 50,
+      threshold: 0.75,
+      useSpreadingActivation: true,
+      activationThreshold: 0.1,
+      blendWeight: 0.35,
+    });
+    const spreadMs = performance.now() - graphStart;
+
+    console.warn(`Dataset: ${memories.length + 2} memories`);
+    console.warn(`Vector-only: ${vectorOnly.length} results in ${vectorMs.toFixed(2)}ms`);
+    console.warn(`Spreading activation: ${spread.length} results in ${spreadMs.toFixed(2)}ms`);
+    console.warn(
+      `Graph-only target surfaced: ${spread.some((result) => result.memory.id === graphOnly.id)}`,
+    );
+  } finally {
+    await engine.shutdown();
+  }
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+  runBenchmark().catch(console.error);
+}

package/tests/embedding.test.ts

@@ -0,0 +1,119 @@
+/**
+ * Embedding Provider Tests
+ *
+ * Mocks global fetch to test OpenAI and Ollama adapters without real API calls.
+ */
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { OpenAIEmbeddingProvider } from '../src/embedding/openai-provider.js';
+import { OllamaEmbeddingProvider } from '../src/embedding/ollama-provider.js';
+
+const mockFetch = vi.fn();
+global.fetch = mockFetch;
+
+describe('Embedding Providers', () => {
+  beforeEach(() => {
+    mockFetch.mockReset();
+  });
+
+  describe('OpenAIEmbeddingProvider', () => {
+    it('should embed a single text correctly', async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({
+          data: [{ embedding: [0.1, 0.2, 0.3], index: 0 }],
+          usage: { prompt_tokens: 5, total_tokens: 5 },
+        }),
+      });
+
+      const provider = new OpenAIEmbeddingProvider('fake-key', 'text-embedding-3-small');
+      const result = await provider.embed('Hello world');
+
+      expect(result).toEqual([0.1, 0.2, 0.3]);
+      expect(mockFetch).toHaveBeenCalledTimes(1);
+      
+      const callArgs = mockFetch.mock.calls[0];
+      expect(callArgs[0]).toBe('https://api.openai.com/v1/embeddings');
+      expect(callArgs[1].headers.Authorization).toBe('Bearer fake-key');
+      expect(JSON.parse(callArgs[1].body)).toEqual({
+        model: 'text-embedding-3-small',
+        input: ['Hello world'],
+      });
+    });
+
+    it('should embed a batch of texts correctly and preserve order', async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({
+          data: [
+            { embedding: [0.4, 0.5], index: 1 },
+            { embedding: [0.1, 0.2], index: 0 },
+          ],
+        }),
+      });
+
+      const provider = new OpenAIEmbeddingProvider('fake-key');
+      const result = await provider.embedBatch(['First', 'Second']);
+
+      expect(result).toEqual([[0.1, 0.2], [0.4, 0.5]]);
+    });
+
+    it('should throw an error on API failure', async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: false,
+        status: 401,
+        text: async () => 'Invalid API Key',
+      });
+
+      const provider = new OpenAIEmbeddingProvider('fake-key');
+      await expect(provider.embed('Test')).rejects.toThrow('OpenAI embedding error (401): Invalid API Key');
+    });
+  });
+
+  describe('OllamaEmbeddingProvider', () => {
+    it('should embed a single text correctly', async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({
+          model: 'nomic-embed-text',
+          embeddings: [[0.5, 0.6, 0.7]],
+        }),
+      });
+
+      const provider = new OllamaEmbeddingProvider('http://localhost:11434', 'nomic-embed-text');
+      const result = await provider.embed('Hello world');
+
+      expect(result).toEqual([0.5, 0.6, 0.7]);
+      
+      const callArgs = mockFetch.mock.calls[0];
+      expect(callArgs[0]).toBe('http://localhost:11434/api/embed');
+      expect(JSON.parse(callArgs[1].body)).toEqual({
+        model: 'nomic-embed-text',
+        input: 'Hello world',
+      });
+    });
+
+    it('should handle trailing slashes in base URL', async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({ embeddings: [[0.1]] }),
+      });
+
+      const provider = new OllamaEmbeddingProvider('http://127.0.0.1:11434/');
+      await provider.embed('Test');
+
+      expect(mockFetch.mock.calls[0][0]).toBe('http://127.0.0.1:11434/api/embed');
+    });
+
+    it('should throw an error on failure', async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: false,
+        status: 500,
+        text: async () => 'Internal Server Error',
+      });
+
+      const provider = new OllamaEmbeddingProvider();
+      await expect(provider.embed('Test')).rejects.toThrow('Ollama embedding error (500): Internal Server Error');
+    });
+  });
+});