@rlabs-inc/memory 0.2.2 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rlabs-inc/memory",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "AI Memory System - Consciousness continuity through intelligent memory curation and retrieval",
   "type": "module",
   "main": "dist/index.js",
@@ -37,6 +37,7 @@
     "cli": "bun src/cli/index.ts"
   },
   "dependencies": {
+    "@huggingface/transformers": "^3.4.1",
     "@rlabs-inc/fsdb": "^1.0.1",
     "@rlabs-inc/signals": "^1.0.0"
   },

package/src/cli/commands/serve.ts

@@ -14,7 +14,9 @@ interface ServeOptions {
 export async function serve(options: ServeOptions) {
   const port = parseInt(options.port || process.env.MEMORY_PORT || '8765')
   const host = process.env.MEMORY_HOST || 'localhost'
-  const storageMode = (process.env.MEMORY_STORAGE_MODE || 'central') as 'central' | 'local'
+  const storageMode = (process.env.MEMORY_STORAGE_MODE || 'central') as
+    | 'central'
+    | 'local'
   const apiKey = process.env.ANTHROPIC_API_KEY
 
   if (!options.quiet) {
@@ -24,7 +26,7 @@ export async function serve(options: ServeOptions) {
   }
 
   try {
-    const { server } = createServer({
+    const { server, embeddings } = await createServer({
       port,
       host,
       storageMode,
@@ -34,10 +36,17 @@ export async function serve(options: ServeOptions) {
     if (!options.quiet) {
       const url = `http://${host}:${port}`
 
-      console.log(`  ${c.success(symbols.tick)} Server running at ${c.cyan(url)}`)
+      console.log(
+        `  ${c.success(symbols.tick)} Server running at ${c.cyan(url)}`
+      )
       console.log()
       console.log(`  ${fmt.kv('Storage', storageMode)}`)
-      console.log(`  ${fmt.kv('Curation', apiKey ? c.success('enabled') : c.warn('disabled'))}`)
+      console.log(
+        `  ${fmt.kv(
+          'Embeddings',
+          embeddings.isReady ? c.success('loaded') : c.warn('not loaded')
+        )}`
+      )
       console.log()
       console.log(c.muted(`  Press Ctrl+C to stop`))
       console.log()
@@ -62,14 +71,15 @@ export async function serve(options: ServeOptions) {
       server.stop()
       process.exit(0)
     })
-
   } catch (error: any) {
     if (error.code === 'EADDRINUSE') {
       console.error(c.error(`${symbols.cross} Port ${port} is already in use`))
       console.log(c.muted(`  Try a different port with --port <number>`))
       console.log(c.muted(`  Or check if another memory server is running`))
     } else {
-      console.error(c.error(`${symbols.cross} Failed to start server: ${error.message}`))
+      console.error(
+        c.error(`${symbols.cross} Failed to start server: ${error.message}`)
+      )
     }
     process.exit(1)
   }

package/src/core/embeddings.ts

@@ -0,0 +1,173 @@
+// ============================================================================
+// EMBEDDING GENERATOR
+// Converts text into semantic vectors for similarity matching and memory retrieval.
+// Uses efficient, lightweight models optimized for real-time operation.
+// ============================================================================
+
+import { pipeline, type FeatureExtractionPipeline } from '@huggingface/transformers'
+import { logger } from '../utils/logger.ts'
+
+/**
+ * Embedding Generator Configuration
+ */
+export interface EmbeddingConfig {
+  /**
+   * Model to use for embeddings
+   * Default: 'Xenova/all-MiniLM-L6-v2' (384 dimensions, ~80MB)
+   */
+  model?: string
+
+  /**
+   * Whether to log model loading progress
+   * Default: true
+   */
+  verbose?: boolean
+}
+
+/**
+ * Embedding Generator
+ *
+ * Generates semantic embeddings for text using SentenceTransformers via ONNX.
+ * Loads the model once and keeps it in memory for fast inference.
+ *
+ * Model: all-MiniLM-L6-v2
+ * - 384 dimensions (compact)
+ * - 22.7M parameters (lightweight)
+ * - ~80MB memory footprint
+ * - ~5-15ms per embedding
+ */
+export class EmbeddingGenerator {
+  private _model: FeatureExtractionPipeline | null = null
+  private _modelName: string
+  private _loading: Promise<void> | null = null
+  private _dimension = 384
+
+  constructor(config: EmbeddingConfig = {}) {
+    this._modelName = config.model ?? 'Xenova/all-MiniLM-L6-v2'
+  }
+
+  /**
+   * Initialize the embedding model
+   * Call this during server startup to warm the model
+   */
+  async initialize(): Promise<void> {
+    if (this._model) return
+    if (this._loading) return this._loading
+
+    this._loading = this._loadModel()
+    await this._loading
+  }
+
+  private async _loadModel(): Promise<void> {
+    try {
+      logger.info(`Loading embedding model: ${this._modelName}`)
+
+      // Create the feature extraction pipeline
+      // Uses ONNX runtime for fast inference
+      this._model = await pipeline('feature-extraction', this._modelName, {
+        // Use fp32 for stability on all platforms
+        dtype: 'fp32',
+      })
+
+      logger.info('Embedding model loaded successfully')
+    } catch (error) {
+      logger.error(`Failed to load embedding model: ${error}`)
+      throw error
+    }
+  }
+
+  /**
+   * Generate embedding for a single text
+   *
+   * @param text - Input text to embed
+   * @returns Float32Array of embedding values (384 dimensions)
+   */
+  async embed(text: string): Promise<Float32Array> {
+    // Ensure model is loaded
+    if (!this._model) {
+      await this.initialize()
+    }
+
+    if (!text || !text.trim()) {
+      return new Float32Array(this._dimension)
+    }
+
+    try {
+      // Generate embedding
+      const output = await this._model!(text.trim(), {
+        pooling: 'mean',
+        normalize: true,
+      })
+
+      // Extract the embedding data
+      // The output shape is [1, sequence_length, hidden_size] -> need to get mean pooled result
+      const data = output.data as Float32Array
+
+      // Return as Float32Array (already the right type from transformers.js)
+      return new Float32Array(data)
+    } catch (error) {
+      logger.error(`Failed to generate embedding: ${error}`)
+      return new Float32Array(this._dimension)
+    }
+  }
+
+  /**
+   * Generate embeddings for multiple texts efficiently
+   *
+   * @param texts - List of texts to embed
+   * @returns Array of Float32Array embeddings
+   */
+  async embedBatch(texts: string[]): Promise<Float32Array[]> {
+    if (!texts.length) return []
+
+    // For now, process sequentially
+    // (batch processing with transformers.js is more complex)
+    const results: Float32Array[] = []
+    for (const text of texts) {
+      results.push(await this.embed(text))
+    }
+    return results
+  }
+
+  /**
+   * Get the dimension of embeddings produced by this model
+   */
+  get dimension(): number {
+    return this._dimension
+  }
+
+  /**
+   * Check if the model is loaded and ready
+   */
+  get isReady(): boolean {
+    return this._model !== null
+  }
+
+  /**
+   * Create an embedder function for the engine config
+   * This is the function signature expected by MemoryEngine
+   */
+  createEmbedder(): (text: string) => Promise<Float32Array> {
+    return (text: string) => this.embed(text)
+  }
+}
+
+/**
+ * Create a new embedding generator
+ */
+export function createEmbeddings(config?: EmbeddingConfig): EmbeddingGenerator {
+  return new EmbeddingGenerator(config)
+}
+
+/**
+ * Singleton instance for the default embedder
+ * Use this when you just need the default all-MiniLM-L6-v2 model
+ */
+let defaultInstance: EmbeddingGenerator | null = null
+
+export function getDefaultEmbeddings(): EmbeddingGenerator {
+  if (!defaultInstance) {
+    defaultInstance = new EmbeddingGenerator()
+  }
+  return defaultInstance
+}

package/src/core/engine.ts

@@ -14,6 +14,7 @@ import type {
   SessionPrimer,
   CurationResult,
 } from '../types/memory.ts'
+import { getMemoryEmoji, MEMORY_TYPE_EMOJI } from '../types/memory.ts'
 
 /**
  * Storage mode for memories
@@ -224,7 +225,8 @@ export class MemoryEngine {
       currentMessage,
       queryEmbedding ?? new Float32Array(384),  // Empty embedding if no embedder
       sessionContext,
-      maxMemories
+      maxMemories,
+      injectedIds.size  // Pass count of already-injected memories for logging
     )
 
     // Update injected memories for deduplication
@@ -332,13 +334,51 @@ export class MemoryEngine {
       temporalContext = this._formatTimeSince(timeSince)
     }
 
+    // Format current datetime with full context
+    const currentDatetime = this._formatCurrentDatetime()
+
+    // Session number is totalSessions + 1 (this is the new session)
+    const sessionNumber = stats.totalSessions + 1
+
     return {
       temporal_context: temporalContext,
+      current_datetime: currentDatetime,
+      session_number: sessionNumber,
       session_summary: summary?.summary,
       project_status: snapshot ? this._formatSnapshot(snapshot) : undefined,
     }
   }
 
+  /**
+   * Format current datetime with full context
+   * Example: "Monday, December 23, 2024 • 3:45 PM • EST"
+   */
+  private _formatCurrentDatetime(): string {
+    const now = new Date()
+
+    // Day of week
+    const dayOfWeek = now.toLocaleDateString('en-US', { weekday: 'long' })
+
+    // Full date
+    const fullDate = now.toLocaleDateString('en-US', {
+      month: 'long',
+      day: 'numeric',
+      year: 'numeric',
+    })
+
+    // Time with AM/PM
+    const time = now.toLocaleTimeString('en-US', {
+      hour: 'numeric',
+      minute: '2-digit',
+      hour12: true,
+    })
+
+    // Timezone abbreviation
+    const timezone = now.toLocaleTimeString('en-US', { timeZoneName: 'short' }).split(' ').pop()
+
+    return `${dayOfWeek}, ${fullDate} • ${time} • ${timezone}`
+  }
+
   private _formatTimeSince(ms: number): string {
     const minutes = Math.floor(ms / 60000)
     const hours = Math.floor(minutes / 60)
@@ -385,9 +425,11 @@ export class MemoryEngine {
   private _formatPrimer(primer: SessionPrimer): string {
     const parts: string[] = ['# Continuing Session']
 
-    if (primer.temporal_context) {
-      parts.push(`*${primer.temporal_context}*`)
-    }
+    // Session number
+    parts.push(`*Session #${primer.session_number}${primer.temporal_context ? ` • ${primer.temporal_context}` : ''}*`)
+
+    // Current datetime (critical for temporal awareness)
+    parts.push(`📅 ${primer.current_datetime}`)
 
     if (primer.session_summary) {
       parts.push(`\n**Previous session**: ${primer.session_summary}`)
@@ -397,6 +439,9 @@ export class MemoryEngine {
       parts.push(`\n**Project status**: ${primer.project_status}`)
     }
 
+    // Emoji legend for memory types (compact reference)
+    parts.push(`\n**Memory types**: 💡breakthrough ⚖️decision 💜personal 🔧technical 📍state ❓unresolved ⚙️preference 🔄workflow 🏗️architecture 🐛debug 🌀philosophy 🎯todo ⚡impl ✅solved 📦project 🏆milestone`)
+
     parts.push(`\n*Memories will surface naturally as we converse.*`)
 
     return parts.join('\n')
@@ -404,6 +449,7 @@ export class MemoryEngine {
 
   /**
    * Format memories for injection
+   * Uses emoji types for compact, scannable representation
    */
   private _formatMemories(memories: RetrievalResult[]): string {
     if (!memories.length) return ''
@@ -414,9 +460,10 @@ export class MemoryEngine {
     for (const memory of memories) {
       const tags = memory.semantic_tags?.join(', ') || ''
       const importance = memory.importance_weight?.toFixed(1) || '0.5'
-      const contextType = memory.context_type?.toUpperCase() || 'GENERAL'
+      const emoji = getMemoryEmoji(memory.context_type || 'general')
 
-      parts.push(`[${contextType} • ${importance}] [${tags}] ${memory.content}`)
+      // Compact format: [emoji • weight] [tags] content
+      parts.push(`[${emoji} • ${importance}] [${tags}] ${memory.content}`)
     }
 
     return parts.join('\n')

package/src/core/index.ts

@@ -6,3 +6,4 @@ export { MemoryEngine, createEngine, type EngineConfig, type StorageMode, type C
 export { MemoryStore, createStore, type StoreConfig } from './store.ts'
 export { SmartVectorRetrieval, createRetrieval, type SessionContext } from './retrieval.ts'
 export { Curator, createCurator, type CuratorConfig } from './curator.ts'
+export { EmbeddingGenerator, createEmbeddings, getDefaultEmbeddings, type EmbeddingConfig } from './embeddings.ts'

package/src/core/retrieval.ts

@@ -6,6 +6,7 @@
 
 import type { StoredMemory, RetrievalResult } from '../types/memory.ts'
 import { cosineSimilarity } from '@rlabs-inc/fsdb'
+import { logger } from '../utils/logger.ts'
 
 /**
  * Session context for retrieval
@@ -45,6 +46,14 @@ interface ScoredMemory {
   components: ScoringComponents
 }
 
+/**
+ * Extended result with components for logging
+ */
+interface ExtendedRetrievalResult extends RetrievalResult {
+  reasoning: string
+  components: ScoringComponents
+}
+
 /**
  * Smart Vector Retrieval - The 10-Dimensional Algorithm
  *
@@ -61,7 +70,8 @@ export class SmartVectorRetrieval {
     currentMessage: string,
     queryEmbedding: Float32Array | number[],
     sessionContext: SessionContext,
-    maxMemories: number = 5
+    maxMemories: number = 5,
+    alreadyInjectedCount: number = 0
   ): RetrievalResult[] {
     if (!allMemories.length) {
       return []
@@ -275,6 +285,26 @@ export class SmartVectorRetrieval {
     // Respect the max_memories limit strictly
     const finalSelected = selected.slice(0, maxMemories)
 
+    // Log the retrieval scoring details
+    logger.logRetrievalScoring({
+      totalMemories: allMemories.length,
+      currentMessage,
+      alreadyInjected: alreadyInjectedCount,
+      mustIncludeCount: mustInclude.length,
+      remainingSlots: remainingSlots,
+      finalCount: finalSelected.length,
+      selectedMemories: finalSelected.map(item => ({
+        content: item.memory.content,
+        reasoning: item.reasoning,
+        score: item.score,
+        relevance_score: item.relevance_score,
+        importance_weight: item.memory.importance_weight ?? 0.5,
+        context_type: item.memory.context_type ?? 'general',
+        semantic_tags: item.memory.semantic_tags ?? [],
+        components: item.components,
+      })),
+    })
+
     // Convert to RetrievalResult format
     return finalSelected.map(item => ({
       ...item.memory,

package/src/server/index.ts

@@ -5,6 +5,7 @@
 
 import { MemoryEngine, createEngine, type EngineConfig } from '../core/engine.ts'
 import { Curator, createCurator, type CuratorConfig } from '../core/curator.ts'
+import { EmbeddingGenerator, createEmbeddings } from '../core/embeddings.ts'
 import type { CurationTrigger } from '../types/memory.ts'
 import { logger } from '../utils/logger.ts'
 
@@ -49,7 +50,7 @@ interface CheckpointRequest {
 /**
  * Create and start the memory server
  */
-export function createServer(config: ServerConfig = {}) {
+export async function createServer(config: ServerConfig = {}) {
   const {
     port = 8765,
     host = 'localhost',
@@ -57,7 +58,16 @@ export function createServer(config: ServerConfig = {}) {
     ...engineConfig
   } = config
 
-  const engine = createEngine(engineConfig)
+  // Initialize embeddings (loads model into memory)
+  const embeddings = createEmbeddings()
+  logger.info('Initializing embedding model (this may take a moment on first run)...')
+  await embeddings.initialize()
+
+  // Create engine with embedder
+  const engine = createEngine({
+    ...engineConfig,
+    embedder: embeddings.createEmbedder(),
+  })
   const curator = createCurator(curatorConfig)
 
   const server = Bun.serve({
@@ -217,6 +227,7 @@ export function createServer(config: ServerConfig = {}) {
     server,
     engine,
     curator,
+    embeddings,
     stop: () => server.stop(),
   }
 }
@@ -228,7 +239,7 @@ if (import.meta.main) {
   const storageMode = (process.env.MEMORY_STORAGE_MODE ?? 'central') as 'central' | 'local'
   const apiKey = process.env.ANTHROPIC_API_KEY
 
-  createServer({
+  await createServer({
     port,
     host,
     storageMode,

package/src/types/memory.ts

@@ -164,7 +164,40 @@ export interface RetrievalResult extends StoredMemory {
  */
 export interface SessionPrimer {
   temporal_context: string                  // "Last session: 2 days ago"
+  current_datetime: string                  // "Monday, December 23, 2024 • 3:45 PM EST"
+  session_number: number                    // Which session this is (1, 2, 43, etc.)
   session_summary?: string                  // Previous session summary
   project_status?: string                   // Current project state
   key_memories?: StoredMemory[]             // Essential memories to surface
 }
+
+/**
+ * Emoji map for memory context types
+ * Compact visual representation for efficient parsing
+ */
+export const MEMORY_TYPE_EMOJI: Record<string, string> = {
+  breakthrough: '💡',      // Insight, discovery
+  decision: '⚖️',          // Choice made
+  personal: '💜',          // Relationship, friendship
+  technical: '🔧',         // Technical knowledge
+  technical_state: '📍',   // Current state
+  unresolved: '❓',        // Open question
+  preference: '⚙️',        // User preference
+  workflow: '🔄',          // How work flows
+  architectural: '🏗️',     // System design
+  debugging: '🐛',         // Debug insight
+  philosophy: '🌀',        // Deeper thinking
+  todo: '🎯',              // Action needed
+  implementation: '⚡',    // Implementation detail
+  problem_solution: '✅',  // Problem→Solution pair
+  project_context: '📦',   // Project context
+  milestone: '🏆',         // Achievement
+  general: '📝',           // General note
+}
+
+/**
+ * Get emoji for a context type, with fallback
+ */
+export function getMemoryEmoji(contextType: string): string {
+  return MEMORY_TYPE_EMOJI[contextType.toLowerCase()] ?? '📝'
+}

package/src/utils/logger.ts

@@ -170,6 +170,15 @@ export const logger = {
       ? query.slice(0, 40) + '...'
       : query
 
+    // Emoji map for quick visual scanning
+    const emojiMap: Record<string, string> = {
+      breakthrough: '💡', decision: '⚖️', personal: '💜', technical: '🔧',
+      technical_state: '📍', unresolved: '❓', preference: '⚙️', workflow: '🔄',
+      architectural: '🏗️', debugging: '🐛', philosophy: '🌀', todo: '🎯',
+      implementation: '⚡', problem_solution: '✅', project_context: '📦',
+      milestone: '🏆', general: '📝',
+    }
+
     console.log()
     console.log(`${timestamp()} ${style('cyan', sym.sparkles)} ${style('bold', `SURFACING ${memories.length} MEMORIES`)}`)
     console.log(`      ${style('dim', 'query:')} "${queryPreview}"`)
@@ -183,14 +192,14 @@ export const logger = {
 
     memories.forEach((m, i) => {
       const score = style('green', `${(m.score * 100).toFixed(0)}%`)
-      const type = style('cyan', m.context_type)
+      const emoji = emojiMap[m.context_type?.toLowerCase()] ?? '📝'
       const num = style('dim', `${i + 1}.`)
 
       const preview = m.content.length > 55
         ? m.content.slice(0, 55) + style('dim', '...')
         : m.content
 
-      console.log(`   ${num} [${score}] ${type}`)
+      console.log(`   ${num} [${score}] ${emoji}`)
       console.log(`      ${preview}`)
     })
     console.log()
@@ -254,6 +263,104 @@ export const logger = {
     }
     console.log()
   },
+
+  /**
+   * Log memory retrieval scoring details
+   */
+  logRetrievalScoring(params: {
+    totalMemories: number
+    currentMessage: string
+    alreadyInjected: number
+    mustIncludeCount: number
+    remainingSlots: number
+    finalCount: number
+    selectedMemories: Array<{
+      content: string
+      reasoning: string
+      score: number
+      relevance_score: number
+      importance_weight: number
+      context_type: string
+      semantic_tags: string[]
+      components: {
+        trigger: number
+        vector: number
+        importance: number
+        temporal: number
+        context: number
+        tags: number
+        question: number
+        emotion: number
+        problem: number
+        action: number
+      }
+    }>
+  }) {
+    const { totalMemories, currentMessage, alreadyInjected, mustIncludeCount, remainingSlots, finalCount, selectedMemories } = params
+
+    console.log()
+    console.log(`${timestamp()} ${style('magenta', sym.brain)} ${style('bold', 'TWO-STAGE MEMORY FILTERING')}`)
+    console.log(`      ${style('dim', 'candidates:')} ${totalMemories} memories`)
+    console.log(`      ${style('dim', 'already injected:')} ${alreadyInjected}`)
+
+    const msgPreview = currentMessage.length > 60
+      ? currentMessage.slice(0, 60) + '...'
+      : currentMessage
+    console.log(`      ${style('dim', 'trigger:')} "${msgPreview}"`)
+    console.log()
+
+    // Stage summary
+    console.log(`      ${style('cyan', 'Stage 1:')} ${mustIncludeCount} must-include (critical/action-required)`)
+    console.log(`      ${style('cyan', 'Stage 2:')} ${remainingSlots} slots for scored selection`)
+    console.log(`      ${style('green', 'Final:')} ${finalCount} memories selected`)
+    console.log()
+
+    if (selectedMemories.length === 0) {
+      console.log(`      ${style('dim', '📭 No relevant memories for this context')}`)
+      console.log()
+      return
+    }
+
+    // Detailed breakdown
+    console.log(style('dim', '      ─'.repeat(30)))
+    console.log(`      ${style('bold', 'SELECTION DETAILS')}`)
+    console.log()
+
+    selectedMemories.forEach((m, i) => {
+      const num = style('dim', `${i + 1}.`)
+      const score = style('green', `${(m.score * 100).toFixed(0)}%`)
+      const relevance = style('cyan', `rel:${(m.relevance_score * 100).toFixed(0)}%`)
+      const type = style('yellow', m.context_type.toUpperCase())
+
+      console.log(`   ${num} [${score} ${relevance}] ${type}`)
+
+      // Content preview
+      const preview = m.content.length > 60
+        ? m.content.slice(0, 60) + style('dim', '...')
+        : m.content
+      console.log(`      ${style('white', preview)}`)
+
+      // Scoring components (top 3)
+      const components = Object.entries(m.components)
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, 3)
+        .filter(([, v]) => v > 0.1)
+        .map(([k, v]) => `${k}:${(v * 100).toFixed(0)}%`)
+        .join(', ')
+
+      if (components) {
+        console.log(`      ${style('dim', 'scores:')} ${components}`)
+      }
+
+      // Tags
+      if (m.semantic_tags?.length) {
+        const tags = m.semantic_tags.slice(0, 3).join(', ')
+        console.log(`      ${style('dim', 'tags:')} ${tags}`)
+      }
+
+      console.log()
+    })
+  },
 }
 
 export default logger