@rlabs-inc/memory 0.3.3 → 0.3.6

package/src/types/memory.ts

@@ -99,10 +99,20 @@ export interface CuratedMemory {
   prerequisite_understanding?: string[]     // Concepts user should know first
   follow_up_context?: string[]              // What might come next
   dependency_context?: string[]             // Other memories this relates to
+
+  // ========== V2 CURATOR FIELDS (optional - get smart defaults if not provided) ==========
+  scope?: 'global' | 'project'              // Shared across projects or project-specific
+  temporal_class?: 'eternal' | 'long_term' | 'medium_term' | 'short_term' | 'ephemeral'
+  domain?: string                           // Specific area (embeddings, auth, family)
+  feature?: string                          // Specific feature within domain
+  related_files?: string[]                  // Source files for technical memories
+  awaiting_implementation?: boolean         // Planned feature not yet built
+  awaiting_decision?: boolean               // Decision point needing resolution
 }
 
 /**
  * A stored memory with database metadata
+ * Includes v2 lifecycle management fields (optional for backwards compat)
  */
 export interface StoredMemory extends CuratedMemory {
   id: string                                // Unique identifier
@@ -112,6 +122,137 @@ export interface StoredMemory extends CuratedMemory {
   updated_at: number                        // Last update timestamp
   embedding?: Float32Array                  // Vector embedding (384 dimensions)
   stale?: boolean                           // Is embedding out of sync with content?
+
+  // ========== V2 LIFECYCLE FIELDS (optional for backwards compat) ==========
+  status?: 'active' | 'pending' | 'superseded' | 'deprecated' | 'archived'
+  scope?: 'global' | 'project'
+
+  // Temporal tracking
+  session_created?: number
+  session_updated?: number
+  last_surfaced?: number
+  sessions_since_surfaced?: number
+
+  // Temporal class & decay
+  temporal_class?: 'eternal' | 'long_term' | 'medium_term' | 'short_term' | 'ephemeral'
+  fade_rate?: number
+  expires_after_sessions?: number
+
+  // Categorization
+  domain?: string
+  feature?: string
+  component?: string
+
+  // Relationships
+  supersedes?: string
+  superseded_by?: string
+  related_to?: string[]
+  resolves?: string[]
+  resolved_by?: string
+  parent_id?: string
+  child_ids?: string[]
+
+  // Lifecycle triggers
+  awaiting_implementation?: boolean
+  awaiting_decision?: boolean
+  blocked_by?: string
+  blocks?: string[]
+  related_files?: string[]
+
+  // Retrieval control
+  retrieval_weight?: number
+  exclude_from_retrieval?: boolean
+
+  // Schema version
+  schema_version?: number
+}
+
+/**
+ * Default values for v2 fields based on context_type
+ * Used for backwards compatibility with v1 memories
+ */
+export const V2_DEFAULTS = {
+  // Type-specific defaults
+  typeDefaults: {
+    personal: { scope: 'global', temporal_class: 'eternal', fade_rate: 0 },
+    philosophy: { scope: 'global', temporal_class: 'eternal', fade_rate: 0 },
+    preference: { scope: 'global', temporal_class: 'long_term', fade_rate: 0.01 },
+    breakthrough: { scope: 'project', temporal_class: 'eternal', fade_rate: 0 },
+    decision: { scope: 'project', temporal_class: 'long_term', fade_rate: 0 },
+    milestone: { scope: 'project', temporal_class: 'eternal', fade_rate: 0 },
+    technical: { scope: 'project', temporal_class: 'medium_term', fade_rate: 0.03 },
+    architectural: { scope: 'project', temporal_class: 'long_term', fade_rate: 0.01 },
+    debugging: { scope: 'project', temporal_class: 'medium_term', fade_rate: 0.03 },
+    unresolved: { scope: 'project', temporal_class: 'medium_term', fade_rate: 0.05 },
+    todo: { scope: 'project', temporal_class: 'short_term', fade_rate: 0.1 },
+    technical_state: { scope: 'project', temporal_class: 'short_term', fade_rate: 0.1 },
+    workflow: { scope: 'project', temporal_class: 'long_term', fade_rate: 0.02 },
+    project_context: { scope: 'project', temporal_class: 'medium_term', fade_rate: 0.03 },
+  } as Record<string, { scope: string; temporal_class: string; fade_rate: number }>,
+
+  // Fallback defaults
+  fallback: {
+    status: 'active' as const,
+    scope: 'project' as const,
+    temporal_class: 'medium_term' as const,
+    fade_rate: 0.03,
+    sessions_since_surfaced: 0,
+    awaiting_implementation: false,
+    awaiting_decision: false,
+    exclude_from_retrieval: false,
+  },
+}
+
+/**
+ * Apply v2 defaults to a memory (for backwards compatibility)
+ * Uses context_type to determine appropriate defaults
+ */
+export function applyV2Defaults(memory: Partial<StoredMemory>): StoredMemory {
+  const contextType = memory.context_type ?? 'general'
+  const typeDefaults = V2_DEFAULTS.typeDefaults[contextType] ?? V2_DEFAULTS.typeDefaults.technical
+
+  return {
+    // Spread existing memory
+    ...memory,
+
+    // Apply status default
+    status: memory.status ?? V2_DEFAULTS.fallback.status,
+
+    // Apply scope from type defaults
+    scope: memory.scope ?? typeDefaults?.scope ?? V2_DEFAULTS.fallback.scope,
+
+    // Apply temporal class from type defaults
+    temporal_class: memory.temporal_class ?? typeDefaults?.temporal_class ?? V2_DEFAULTS.fallback.temporal_class,
+
+    // Apply fade rate from type defaults
+    fade_rate: memory.fade_rate ?? typeDefaults?.fade_rate ?? V2_DEFAULTS.fallback.fade_rate,
+
+    // Apply other defaults
+    sessions_since_surfaced: memory.sessions_since_surfaced ?? V2_DEFAULTS.fallback.sessions_since_surfaced,
+    awaiting_implementation: memory.awaiting_implementation ?? V2_DEFAULTS.fallback.awaiting_implementation,
+    awaiting_decision: memory.awaiting_decision ?? V2_DEFAULTS.fallback.awaiting_decision,
+    exclude_from_retrieval: memory.exclude_from_retrieval ?? V2_DEFAULTS.fallback.exclude_from_retrieval,
+
+    // Retrieval weight defaults to importance_weight
+    retrieval_weight: memory.retrieval_weight ?? memory.importance_weight ?? 0.5,
+
+    // Initialize empty arrays if not present
+    related_to: memory.related_to ?? [],
+    resolves: memory.resolves ?? [],
+    child_ids: memory.child_ids ?? [],
+    blocks: memory.blocks ?? [],
+    related_files: memory.related_files ?? [],
+
+    // Mark as current schema version
+    schema_version: memory.schema_version ?? 2,
+  } as StoredMemory
+}
+
+/**
+ * Check if a memory needs migration (is v1)
+ */
+export function needsMigration(memory: Partial<StoredMemory>): boolean {
+  return !memory.schema_version || memory.schema_version < 2
 }
 
 /**
@@ -166,6 +307,7 @@ 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.)
+  personal_context?: string                 // Personal primer (relationship context) - injected EVERY session
   session_summary?: string                  // Previous session summary
   project_status?: string                   // Current project state
   key_memories?: StoredMemory[]             // Essential memories to surface

package/src/types/schema.ts

@@ -5,40 +5,93 @@
 
 import type { SchemaDefinition } from '@rlabs-inc/fsdb'
 
+/**
+ * Schema version for migration tracking
+ * Increment this when adding new fields that require migration
+ */
+export const MEMORY_SCHEMA_VERSION = 2
+
 /**
  * Memory storage schema
  * Each field becomes a parallel reactive array in FatherStateDB
+ *
+ * VERSION HISTORY:
+ * v1: Original schema (content, reasoning, importance_weight, etc.)
+ * v2: Added lifecycle management fields (status, scope, domain, relationships, etc.)
  */
 export const memorySchema = {
-  // Core content
+  // ========== CORE CONTENT (v1) ==========
   content: 'string',
   reasoning: 'string',
 
-  // Numeric scores (for sorting and filtering)
+  // ========== SCORES (v1) ==========
   importance_weight: 'number',          // 0.0 to 1.0
   confidence_score: 'number',           // 0.0 to 1.0
 
-  // Classification (strings for flexibility)
+  // ========== CLASSIFICATION (v1) ==========
   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
+  // ========== FLAGS (v1) ==========
   action_required: 'boolean',
   problem_solution_pair: 'boolean',
 
-  // Arrays for semantic matching
+  // ========== ARRAYS (v1) ==========
   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/PROJECT (v1) ==========
   session_id: 'string',
   project_id: 'string',
 
-  // Vector embedding for semantic search (384 dimensions - MiniLM)
+  // ========== EMBEDDING (v1) ==========
   embedding: 'vector:384',
+
+  // ========== LIFECYCLE STATUS (v2) ==========
+  status: 'string',                     // active | pending | superseded | deprecated | archived
+  scope: 'string',                      // global | project
+
+  // ========== TEMPORAL TRACKING (v2) ==========
+  session_created: 'number',            // Session number when created
+  session_updated: 'number',            // Session number when last updated
+  last_surfaced: 'number',              // Session number when last retrieved
+  sessions_since_surfaced: 'number',    // Counter for decay
+
+  // ========== TEMPORAL CLASS & DECAY (v2) ==========
+  temporal_class: 'string',             // eternal | long_term | medium_term | short_term | ephemeral
+  fade_rate: 'number',                  // Decay rate per session
+  expires_after_sessions: 'number',     // For ephemeral only
+
+  // ========== CATEGORIZATION (v2) ==========
+  domain: 'string',                     // embeddings, gpu, auth, family, etc.
+  feature: 'string',                    // Specific feature within domain
+  component: 'string',                  // Code component if applicable
+
+  // ========== RELATIONSHIPS (v2) ==========
+  supersedes: 'string',                 // ID of memory this replaces
+  superseded_by: 'string',              // ID of memory that replaced this
+  related_to: 'string[]',               // IDs of related memories
+  resolves: 'string[]',                 // IDs of unresolved/debug/todo this solved
+  resolved_by: 'string',                // ID of solved memory that resolved this
+  parent_id: 'string',                  // For chains/sequences
+  child_ids: 'string[]',                // Children in chain
+
+  // ========== LIFECYCLE TRIGGERS (v2) ==========
+  awaiting_implementation: 'boolean',   // Set true for planned features
+  awaiting_decision: 'boolean',         // Waiting on a decision
+  blocked_by: 'string',                 // ID of blocking memory
+  blocks: 'string[]',                   // IDs this memory blocks
+  related_files: 'string[]',            // Source files for technical memories
+
+  // ========== RETRIEVAL CONTROL (v2) ==========
+  retrieval_weight: 'number',           // Current weight (affected by decay)
+  exclude_from_retrieval: 'boolean',    // Force exclusion
+
+  // ========== SCHEMA VERSION (v2) ==========
+  schema_version: 'number',             // Track which schema version this record uses
 } as const satisfies SchemaDefinition
 
 export type MemorySchema = typeof memorySchema
@@ -81,3 +134,23 @@ export const sessionSchema = {
 } as const satisfies SchemaDefinition
 
 export type SessionSchema = typeof sessionSchema
+
+/**
+ * Management log schema - tracks what the management agent did
+ */
+export const managementLogSchema = {
+  project_id: 'string',
+  session_number: 'number',
+  memories_processed: 'number',
+  superseded_count: 'number',
+  resolved_count: 'number',
+  linked_count: 'number',
+  primer_updated: 'boolean',
+  success: 'boolean',
+  duration_ms: 'number',
+  summary: 'string',                    // Agent's summary of what it did
+  error: 'string',                      // Error message if failed
+  details: 'string',                    // JSON string with full details
+} as const satisfies SchemaDefinition
+
+export type ManagementLogSchema = typeof managementLogSchema