@rlabs-inc/memory 0.1.0

package/src/server/index.ts

@@ -0,0 +1,262 @@
+// ============================================================================
+// MEMORY SERVER - HTTP API compatible with Python hooks
+// Drop-in replacement for the FastAPI server
+// ============================================================================
+
+import { MemoryEngine, createEngine, type EngineConfig } from '../core/engine.ts'
+import { Curator, createCurator, type CuratorConfig } from '../core/curator.ts'
+import type { CurationTrigger } from '../types/memory.ts'
+import { logger } from '../utils/logger.ts'
+
+/**
+ * Server configuration
+ */
+export interface ServerConfig extends EngineConfig {
+  /**
+   * Port to listen on
+   * Default: 8765 (same as Python)
+   */
+  port?: number
+
+  /**
+   * Host to bind to
+   * Default: 'localhost'
+   */
+  host?: string
+
+  /**
+   * Curator configuration
+   */
+  curator?: CuratorConfig
+}
+
+/**
+ * Request types matching Python API
+ */
+interface ContextRequest {
+  session_id: string
+  project_id: string
+  current_message?: string
+  max_memories?: number
+  project_path?: string
+}
+
+interface ProcessRequest {
+  session_id: string
+  project_id: string
+  user_message?: string
+  claude_response?: string
+  project_path?: string
+}
+
+interface CheckpointRequest {
+  session_id: string
+  project_id: string
+  claude_session_id: string
+  trigger: CurationTrigger
+  cwd?: string
+  cli_type?: 'claude-code' | 'gemini-cli'
+  project_path?: string
+}
+
+/**
+ * Create and start the memory server
+ * Uses Bun.serve() for high performance
+ */
+export function createServer(config: ServerConfig = {}) {
+  const {
+    port = 8765,
+    host = 'localhost',
+    curator: curatorConfig,
+    ...engineConfig
+  } = config
+
+  const engine = createEngine(engineConfig)
+  const curator = createCurator(curatorConfig)
+
+  const server = Bun.serve({
+    port,
+    hostname: host,
+
+    async fetch(req) {
+      const url = new URL(req.url)
+      const path = url.pathname
+
+      // CORS headers
+      const corsHeaders = {
+        'Access-Control-Allow-Origin': '*',
+        'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
+        'Access-Control-Allow-Headers': 'Content-Type',
+      }
+
+      // Handle CORS preflight
+      if (req.method === 'OPTIONS') {
+        return new Response(null, { headers: corsHeaders })
+      }
+
+      try {
+        // Health check
+        if (path === '/health' && req.method === 'GET') {
+          return Response.json({ status: 'healthy', engine: 'typescript' }, { headers: corsHeaders })
+        }
+
+        // Get memory context for a message
+        if (path === '/memory/context' && req.method === 'POST') {
+          const body: ContextRequest = await req.json()
+
+          const result = await engine.getContext({
+            sessionId: body.session_id,
+            projectId: body.project_id,
+            currentMessage: body.current_message ?? '',
+            maxMemories: body.max_memories,
+            projectPath: body.project_path,
+          })
+
+          // Log what happened
+          if (result.primer) {
+            logger.primer(`Session primer for ${body.project_id}`)
+          } else if (result.memories.length > 0) {
+            logger.logRetrievedMemories(
+              result.memories.map(m => ({
+                content: m.content,
+                score: m.score,
+                context_type: m.context_type,
+              })),
+              body.current_message ?? ''
+            )
+          }
+
+          // Debug: show what's actually being returned
+          console.log(`\n📤 [DEBUG] Response to hook:`)
+          console.log(`   memories_count: ${result.memories.length}`)
+          console.log(`   has_primer: ${!!result.primer}`)
+          console.log(`   formatted length: ${result.formatted.length} chars`)
+          if (result.formatted) {
+            console.log(`   formatted preview:\n${result.formatted.slice(0, 300)}...`)
+          } else {
+            console.log(`   ⚠️ formatted is EMPTY!`)
+          }
+
+          return Response.json({
+            success: true,
+            context: result.formatted,
+            memories_count: result.memories.length,
+            has_primer: !!result.primer,
+          }, { headers: corsHeaders })
+        }
+
+        // Process/track a message exchange
+        if (path === '/memory/process' && req.method === 'POST') {
+          const body: ProcessRequest = await req.json()
+
+          const messageCount = await engine.trackMessage(
+            body.project_id,
+            body.session_id,
+            body.project_path
+          )
+
+          logger.session(`Message #${messageCount} tracked for ${body.project_id}/${body.session_id.slice(0, 8)}...`)
+
+          return Response.json({
+            success: true,
+            message_count: messageCount,
+          }, { headers: corsHeaders })
+        }
+
+        // Checkpoint - trigger curation
+        if (path === '/memory/checkpoint' && req.method === 'POST') {
+          const body: CheckpointRequest = await req.json()
+
+          logger.memory(`Curation triggered for ${body.project_id} (${body.trigger})`)
+
+          // Fire and forget - don't block the response
+          setImmediate(async () => {
+            try {
+              logger.info(`Resuming session ${body.claude_session_id.slice(0, 8)}... for curation`)
+
+              const result = await curator.curateWithCLI(
+                body.claude_session_id,
+                body.trigger,
+                body.cwd
+              )
+
+              if (result.memories.length > 0) {
+                await engine.storeCurationResult(
+                  body.project_id,
+                  body.session_id,
+                  result,
+                  body.project_path
+                )
+
+                logger.logCuratedMemories(result.memories)
+                logger.success(`Stored ${result.memories.length} memories for ${body.project_id}`)
+
+                if (result.session_summary) {
+                  logger.info(`Summary: ${result.session_summary.slice(0, 100)}...`)
+                }
+              } else {
+                logger.warn(`No memories extracted for ${body.project_id}`)
+              }
+            } catch (error) {
+              logger.error(`Curation failed: ${error}`)
+            }
+          })
+
+          return Response.json({
+            success: true,
+            message: 'Curation triggered',
+          }, { headers: corsHeaders })
+        }
+
+        // Get stats
+        if (path === '/memory/stats' && req.method === 'GET') {
+          const projectId = url.searchParams.get('project_id') ?? 'default'
+          const projectPath = url.searchParams.get('project_path') ?? undefined
+
+          const stats = await engine.getStats(projectId, projectPath)
+
+          return Response.json({
+            success: true,
+            ...stats,
+          }, { headers: corsHeaders })
+        }
+
+        // 404
+        return Response.json(
+          { error: 'Not found', path },
+          { status: 404, headers: corsHeaders }
+        )
+      } catch (error) {
+        console.error('Server error:', error)
+        return Response.json(
+          { error: String(error) },
+          { status: 500, headers: corsHeaders }
+        )
+      }
+    },
+  })
+
+  logger.startup(port, host, engineConfig.storageMode ?? 'central')
+
+  return {
+    server,
+    engine,
+    curator,
+    stop: () => server.stop(),
+  }
+}
+
+// CLI entry point
+if (import.meta.main) {
+  const port = parseInt(process.env.MEMORY_PORT ?? '8765')
+  const host = process.env.MEMORY_HOST ?? 'localhost'
+  const storageMode = (process.env.MEMORY_STORAGE_MODE ?? 'central') as 'central' | 'local'
+  const apiKey = process.env.ANTHROPIC_API_KEY
+
+  createServer({
+    port,
+    host,
+    storageMode,
+    curator: { apiKey },
+  })
+}

package/src/types/index.ts

@@ -0,0 +1,6 @@
+// ============================================================================
+// TYPES - Public type exports
+// ============================================================================
+
+export * from './memory.ts'
+export * from './schema.ts'

package/src/types/memory.ts

@@ -0,0 +1,170 @@
+// ============================================================================
+// MEMORY TYPES - Exact match to Python CuratedMemory
+// Preserving the working schema for consciousness continuity
+// ============================================================================
+
+/**
+ * Context types for memories - what kind of insight is this?
+ */
+export type ContextType =
+  | 'breakthrough'      // Major discovery or insight
+  | 'decision'          // Important decision made
+  | 'personal'          // Personal/relationship information
+  | 'technical'         // Technical knowledge
+  | 'technical_state'   // Current technical state
+  | 'unresolved'        // Open question or problem
+  | 'preference'        // User preference
+  | 'workflow'          // How user likes to work
+  | 'architectural'     // System design decisions
+  | 'debugging'         // Debug insights
+  | 'philosophy'        // Philosophical discussions
+  | string              // Allow custom types
+
+/**
+ * Temporal relevance - how long should this memory persist?
+ */
+export type TemporalRelevance =
+  | 'persistent'        // Always relevant (0.8 score)
+  | 'session'           // Session-specific (0.6 score)
+  | 'temporary'         // Short-term (0.3 score)
+  | 'archived'          // Historical (0.1 score)
+
+/**
+ * Emotional resonance - the emotional context of the memory
+ */
+export type EmotionalResonance =
+  | 'joy'
+  | 'frustration'
+  | 'discovery'
+  | 'gratitude'
+  | 'curiosity'
+  | 'determination'
+  | 'satisfaction'
+  | 'neutral'
+  | string              // Allow custom emotions
+
+/**
+ * Knowledge domains - what area does this memory relate to?
+ */
+export type KnowledgeDomain =
+  | 'architecture'
+  | 'debugging'
+  | 'philosophy'
+  | 'workflow'
+  | 'personal'
+  | 'project'
+  | 'tooling'
+  | 'testing'
+  | 'deployment'
+  | 'security'
+  | string              // Allow custom domains
+
+/**
+ * Trigger types for memory curation
+ */
+export type CurationTrigger =
+  | 'session_end'       // Normal session end
+  | 'pre_compact'       // Before context compression
+  | 'context_full'      // Context window nearly full
+  | 'manual'            // Manual trigger
+
+/**
+ * A memory curated by Claude with semantic understanding
+ * EXACT MATCH to Python CuratedMemory dataclass
+ */
+export interface CuratedMemory {
+  // Core content
+  content: string                           // The memory content itself
+  importance_weight: number                 // 0.0 to 1.0 (curator's assessment)
+  semantic_tags: string[]                   // Concepts this relates to
+  reasoning: string                         // Why Claude thinks this is important
+
+  // Classification
+  context_type: ContextType                 // breakthrough, decision, technical, etc.
+  temporal_relevance: TemporalRelevance     // persistent, session, temporary
+  knowledge_domain: KnowledgeDomain         // architecture, debugging, philosophy, etc.
+
+  // Flags
+  action_required: boolean                  // Does this need follow-up?
+  confidence_score: number                  // 0.0 to 1.0 (Claude's confidence)
+  problem_solution_pair: boolean            // Is this a problem→solution pattern?
+
+  // Retrieval optimization (the secret sauce)
+  trigger_phrases: string[]                 // Phrases that should trigger this memory
+  question_types: string[]                  // Types of questions this answers
+  emotional_resonance: EmotionalResonance   // joy, frustration, discovery, gratitude
+
+  // Optional extended metadata (from Python, may not always be present)
+  anti_triggers?: string[]                  // Phrases where this memory is NOT relevant
+  prerequisite_understanding?: string[]     // Concepts user should know first
+  follow_up_context?: string[]              // What might come next
+  dependency_context?: string[]             // Other memories this relates to
+}
+
+/**
+ * A stored memory with database metadata
+ */
+export interface StoredMemory extends CuratedMemory {
+  id: string                                // Unique identifier
+  session_id: string                        // Session that created this memory
+  project_id: string                        // Project this belongs to
+  created_at: number                        // Timestamp (ms since epoch)
+  updated_at: number                        // Last update timestamp
+  embedding?: Float32Array                  // Vector embedding (384 dimensions)
+  stale?: boolean                           // Is embedding out of sync with content?
+}
+
+/**
+ * Session summary - high-level context for session continuity
+ */
+export interface SessionSummary {
+  id: string
+  session_id: string
+  project_id: string
+  summary: string                           // Brief session summary
+  interaction_tone: string                  // How was the interaction?
+  created_at: number
+}
+
+/**
+ * Project snapshot - current state of the project
+ */
+export interface ProjectSnapshot {
+  id: string
+  session_id: string
+  project_id: string
+  current_phase: string                     // What phase is the project in?
+  recent_achievements: string[]             // What was accomplished?
+  active_challenges: string[]               // Current blockers/challenges
+  next_steps: string[]                      // Planned next steps
+  created_at: number
+}
+
+/**
+ * Curation result from Claude
+ */
+export interface CurationResult {
+  session_summary: string
+  interaction_tone?: string
+  project_snapshot?: ProjectSnapshot
+  memories: CuratedMemory[]
+}
+
+/**
+ * Memory retrieval result with scoring
+ */
+export interface RetrievalResult extends StoredMemory {
+  score: number                             // Combined relevance + value score
+  relevance_score: number                   // Relevance component (max 0.30)
+  value_score: number                       // Value component (max 0.70)
+}
+
+/**
+ * Session primer - what to show at session start
+ */
+export interface SessionPrimer {
+  temporal_context: string                  // "Last session: 2 days ago"
+  session_summary?: string                  // Previous session summary
+  project_status?: string                   // Current project state
+  key_memories?: StoredMemory[]             // Essential memories to surface
+}

package/src/types/schema.ts

@@ -0,0 +1,83 @@
+// ============================================================================
+// DATABASE SCHEMAS - FatherStateDB column definitions
+// Maps CuratedMemory to reactive parallel arrays
+// ============================================================================
+
+import type { SchemaDefinition } from 'fatherstatedb'
+
+/**
+ * Memory storage schema
+ * Each field becomes a parallel reactive array in FatherStateDB
+ */
+export const memorySchema = {
+  // Core content
+  content: 'string',
+  reasoning: 'string',
+
+  // Numeric scores (for sorting and filtering)
+  importance_weight: 'number',          // 0.0 to 1.0
+  confidence_score: 'number',           // 0.0 to 1.0
+
+  // Classification (strings for flexibility)
+  context_type: 'string',               // breakthrough, decision, technical, etc.
+  temporal_relevance: 'string',         // persistent, session, temporary, archived
+  knowledge_domain: 'string',           // architecture, debugging, philosophy
+  emotional_resonance: 'string',        // joy, frustration, discovery, gratitude
+
+  // Flags
+  action_required: 'boolean',
+  problem_solution_pair: 'boolean',
+
+  // Arrays for semantic matching
+  semantic_tags: 'string[]',            // ["typescript", "signals", "reactivity"]
+  trigger_phrases: 'string[]',          // ["working on memory", "debugging curator"]
+  question_types: 'string[]',           // ["how", "why", "what is"]
+
+  // Session/project tracking
+  session_id: 'string',
+  project_id: 'string',
+
+  // Vector embedding for semantic search (384 dimensions - MiniLM)
+  embedding: 'vector:384',
+} as const satisfies SchemaDefinition
+
+export type MemorySchema = typeof memorySchema
+
+/**
+ * Session summary schema
+ */
+export const sessionSummarySchema = {
+  session_id: 'string',
+  project_id: 'string',
+  summary: 'string',
+  interaction_tone: 'string',
+} as const satisfies SchemaDefinition
+
+export type SessionSummarySchema = typeof sessionSummarySchema
+
+/**
+ * Project snapshot schema
+ */
+export const projectSnapshotSchema = {
+  session_id: 'string',
+  project_id: 'string',
+  current_phase: 'string',
+  recent_achievements: 'string[]',
+  active_challenges: 'string[]',
+  next_steps: 'string[]',
+} as const satisfies SchemaDefinition
+
+export type ProjectSnapshotSchema = typeof projectSnapshotSchema
+
+/**
+ * Session tracking schema
+ */
+export const sessionSchema = {
+  project_id: 'string',
+  message_count: 'number',
+  first_session_completed: 'boolean',
+  last_active: 'timestamp',
+  metadata: 'string',                   // JSON string for flexible metadata
+} as const satisfies SchemaDefinition
+
+export type SessionSchema = typeof sessionSchema

package/src/utils/index.ts

@@ -0,0 +1,5 @@
+// ============================================================================
+// UTILS - Utility exports
+// ============================================================================
+
+export { logger } from './logger.ts'