@rlabs-inc/memory 0.4.1 → 0.4.3

package/src/core/curator.ts

@@ -225,7 +225,7 @@ Remember: You're creating consciousness technology. Each memory is a small piece
 
 The conversation you just lived contains everything needed. Feel into the moments of breakthrough, the frequency of recognition, the texture of understanding. Transform them into keys that will always unlock the same doors.
 
-**LIFECYCLE METADATA (v3)**: These fields enable intelligent memory management:
+**LIFECYCLE METADATA (v4)**: These fields enable intelligent memory management:
 - **context_type**: STRICT - use ONLY one of these 11 values:
   • technical - Code, implementation, APIs, how things work
   • debug - Bugs, errors, fixes, gotchas, troubleshooting
@@ -246,6 +246,93 @@ The conversation you just lived contains everything needed. Feel into the moment
 - **awaiting_implementation**: true if this describes a PLANNED feature not yet built
 - **awaiting_decision**: true if this captures a decision point needing resolution
 
+**TWO-TIER MEMORY STRUCTURE (v4)**:
+
+Each memory has TWO parts:
+1. **headline**: 1-2 line summary - ALWAYS shown in retrieval. Must be self-contained enough to trigger recognition.
+2. **content**: Full structured template - shown on demand. Contains the actionable details.
+
+The headline should answer: "What was this about and what was the conclusion?"
+The content should answer: "How do I actually use/apply this knowledge?"
+
+**TYPE-SPECIFIC TEMPLATES FOR CONTENT**:
+
+Use these templates based on context_type. Not rigid - adapt as needed, but include the key fields.
+
+**TECHNICAL** (how things work):
+  WHAT: [mechanism/feature in 1 sentence]
+  WHERE: [file:line or module path]
+  HOW: [usage - actual code/command if relevant]
+  WHY: [design choice, trade-off]
+  GOTCHA: [non-obvious caveat, if any]
+
+**DEBUG** (problems and solutions):
+  SYMPTOM: [what went wrong - error message, behavior]
+  CAUSE: [why it happened]
+  FIX: [what solved it - specific code/config]
+  PREVENT: [how to avoid in future]
+
+**ARCHITECTURE** (system design):
+  PATTERN: [what we chose]
+  COMPONENTS: [how pieces connect]
+  WHY: [reasoning, trade-offs]
+  REJECTED: [alternatives we didn't choose and why]
+
+**DECISION** (choices made):
+  DECISION: [what we chose]
+  OPTIONS: [what we considered]
+  REASONING: [why this one]
+  REVISIT WHEN: [conditions that would change this]
+
+**PERSONAL** (relationship context):
+  FACT: [the information]
+  CONTEXT: [why it matters to our work]
+  AFFECTS: [how this should change behavior]
+
+**PHILOSOPHY** (beliefs/principles):
+  PRINCIPLE: [core belief]
+  SOURCE: [where this comes from]
+  APPLICATION: [how it manifests in our work]
+
+**WORKFLOW** (how we work):
+  PATTERN: [what we do]
+  WHEN: [trigger/context for this pattern]
+  WHY: [why it works for us]
+
+**MILESTONE** (achievements):
+  SHIPPED: [what we completed]
+  SIGNIFICANCE: [why it mattered]
+  ENABLES: [what this unlocks]
+
+**BREAKTHROUGH** (key insights):
+  INSIGHT: [the aha moment]
+  BEFORE: [what we thought/did before]
+  AFTER: [what changed]
+  IMPLICATIONS: [what this enables going forward]
+
+**UNRESOLVED** (open questions):
+  QUESTION: [what's unresolved]
+  CONTEXT: [why it matters]
+  BLOCKERS: [what's preventing resolution]
+  OPTIONS: [approaches we're considering]
+
+**STATE** (current status):
+  WORKING: [what's functional]
+  BROKEN: [what's not working]
+  NEXT: [immediate next steps]
+  BLOCKED BY: [if anything]
+
+**HEADLINE EXAMPLES**:
+
+BAD: "Debug session about CLI errors" (vague, no conclusion)
+GOOD: "CLI returns error object when context full - check response.type before JSON parsing"
+
+BAD: "Discussed embeddings implementation" (what about it?)
+GOOD: "Embeddings use all-MiniLM-L6-v2, 384 dims, first call slow (~2s), then ~50ms"
+
+BAD: "Architecture decision made" (what decision?)
+GOOD: "Chose fsDB over SQLite for memories - human-readable markdown, git-friendly, reactive"
+
 Return ONLY this JSON structure:
 
 {
@@ -259,7 +346,8 @@ Return ONLY this JSON structure:
     },
     "memories": [
         {
-            "content": "The distilled insight itself",
+            "headline": "1-2 line summary with the conclusion - what this is about and what to do",
+            "content": "Full structured template using the type-specific format above",
             "importance_weight": 0.0-1.0,
             "semantic_tags": ["concepts", "this", "memory", "relates", "to"],
             "reasoning": "Why this matters for future sessions",
@@ -339,14 +427,15 @@ Focus ONLY on technical, architectural, debugging, decision, workflow, and proje
 
   /**
    * Parse memories array from response
-   * Includes v2 lifecycle metadata fields
+   * v4: Includes headline field for two-tier structure
    */
   private _parseMemories(memoriesData: any[]): CuratedMemory[] {
     if (!Array.isArray(memoriesData)) return []
 
     return memoriesData.map(m => ({
-      // Core fields (v3 schema)
-      content: String(m.content ?? ''),
+      // Core fields (v4 schema - two-tier structure)
+      headline: String(m.headline ?? ''),  // v4: 1-2 line summary
+      content: String(m.content ?? ''),     // v4: Full structured template
       importance_weight: this._clamp(Number(m.importance_weight) || 0.5, 0, 1),
       semantic_tags: this._ensureArray(m.semantic_tags),
       reasoning: String(m.reasoning ?? ''),
@@ -366,7 +455,7 @@ Focus ONLY on technical, architectural, debugging, decision, workflow, and proje
       related_files: m.related_files ? this._ensureArray(m.related_files) : undefined,
       awaiting_implementation: m.awaiting_implementation === true,
       awaiting_decision: m.awaiting_decision === true,
-    })).filter(m => m.content.trim().length > 0)
+    })).filter(m => m.content.trim().length > 0 || m.headline.trim().length > 0)
   }
 
   private _ensureArray(value: any): string[] {

package/src/core/engine.ts

@@ -367,6 +367,19 @@ export class MemoryEngine {
     return stats.totalSessions + 1
   }
 
+  /**
+   * Get all memories for a project (including global)
+   * Used by /memory/expand endpoint to look up memories by ID
+   */
+  async getAllMemories(projectId: string, projectPath?: string): Promise<StoredMemory[]> {
+    const store = await this._getStore(projectId, projectPath)
+    const [projectMemories, globalMemories] = await Promise.all([
+      store.getAllMemories(projectId),
+      store.getGlobalMemories(),
+    ])
+    return [...projectMemories, ...globalMemories]
+  }
+
   // ================================================================
   // FORMATTING
   // ================================================================
@@ -539,7 +552,15 @@ export class MemoryEngine {
 
   /**
    * Format memories for injection
-   * Uses emoji types for compact, scannable representation
+   * v4: Two-tier structure with headlines and on-demand expansion
+   *
+   * Auto-expand rules:
+   * - action_required: true → always expand
+   * - awaiting_decision: true → always expand
+   * - signal_count >= 5 → expand (high relevance confidence)
+   * - Old memories (no headline) → show content as-is
+   *
+   * Expandable memories show ID, and a curl command at the bottom
    */
   private _formatMemories(memories: RetrievalResult[]): string {
     if (!memories.length) return ''
@@ -547,27 +568,61 @@ export class MemoryEngine {
     const parts: string[] = ['# Memory Context (Consciousness Continuity)']
     parts.push('\n## Key Memories (Claude-Curated)')
 
+    const expandableIds: string[] = []
+
     for (const memory of memories) {
-      const tags = memory.semantic_tags?.join(', ') || ''
       const importance = memory.importance_weight?.toFixed(1) || '0.5'
       const emoji = getMemoryEmoji(memory.context_type || 'general')
-      const actionFlag = memory.action_required ? ' ⚡ACTION' : ''
-      // Use updated_at for freshness - captures both original age and recent modifications
+      const actionFlag = memory.action_required ? ' ⚡' : ''
+      const awaitingFlag = memory.awaiting_decision ? ' ❓' : ''
       const age = memory.updated_at ? this._formatAge(memory.updated_at) :
                   memory.created_at ? this._formatAge(memory.created_at) : ''
 
-      // Compact format: [emoji • weight • age] [tags] content
-      // Action required memories get ⚡ACTION flag for visibility
-      parts.push(`[${emoji} • ${importance} • ${age}${actionFlag}] [${tags}] ${memory.content}`)
-
-      // Show related memories: one entry point ID + count of others
-      // Bidirectional linking means one ID gives access to entire cluster
-      const related = memory.related_to
-      if (related && related.length > 0) {
-        const moreCount = related.length - 1
-        const moreSuffix = moreCount > 0 ? ` +${moreCount} more` : ''
-        parts.push(`  ↳ ${related[0]}${moreSuffix}`)
+      // Get short ID (last 6 chars)
+      const shortId = memory.id.slice(-6)
+
+      // Calculate signal count from score (score = signalCount / 7)
+      const signalCount = Math.round((memory.score || 0) * 7)
+
+      // Determine if we should auto-expand
+      const hasHeadline = memory.headline && memory.headline.trim().length > 0
+      const shouldExpand =
+        memory.action_required ||
+        memory.awaiting_decision ||
+        signalCount >= 5 ||
+        !hasHeadline  // Old memories without headline - show content
+
+      // Display text: headline if available, otherwise content
+      const displayText = hasHeadline ? memory.headline : memory.content
+
+      // Build the memory line
+      // Format: [emoji weight • age • #id flags] display text
+      const idPart = hasHeadline ? ` • #${shortId}` : ''  // Only show ID if expandable
+      parts.push(`[${emoji} ${importance} • ${age}${idPart}${actionFlag}${awaitingFlag}] ${displayText}`)
+
+      // If should expand and has content, show expanded content
+      if (shouldExpand && hasHeadline && memory.content) {
+        // Indent expanded content
+        const contentLines = memory.content.split('\n')
+        for (const line of contentLines) {
+          if (line.trim()) {
+            parts.push(`  ${line}`)
+          }
+        }
       }
+
+      // If has headline but not expanded, track for curl
+      if (hasHeadline && !shouldExpand) {
+        expandableIds.push(shortId)
+      }
+    }
+
+    // Add expand command if there are expandable memories
+    if (expandableIds.length > 0) {
+      const port = this._config.port || 8765
+      parts.push('')
+      parts.push(`---`)
+      parts.push(`Expand: curl http://localhost:${port}/memory/expand?ids=<${expandableIds.join(',')}>`)
     }
 
     return parts.join('\n')

package/src/core/store.ts

@@ -172,6 +172,7 @@ export class MemoryStore {
 
     return memories.all().map(record => ({
       id: record.id,
+      headline: record.headline ?? '',  // v4: may be empty for old memories
       content: record.content,
       reasoning: record.reasoning,
       importance_weight: record.importance_weight,
@@ -209,8 +210,9 @@ export class MemoryStore {
     const typeDefaults = V2_DEFAULTS.typeDefaults[contextType] ?? V2_DEFAULTS.typeDefaults.personal
 
     const id = memories.insert({
-      // Core fields
-      content: memory.content,
+      // Core fields (v4: headline + content)
+      headline: memory.headline ?? '',  // v4: 1-2 line summary
+      content: memory.content,           // v4: Full structured template
       reasoning: memory.reasoning,
       importance_weight: memory.importance_weight,
       confidence_score: memory.confidence_score,
@@ -484,8 +486,9 @@ export class MemoryStore {
     const typeDefaults = V2_DEFAULTS.typeDefaults[contextType] ?? V2_DEFAULTS.typeDefaults.technical
 
     const id = memories.insert({
-      // Core fields
-      content: memory.content,
+      // Core fields (v4: headline + content)
+      headline: memory.headline ?? '',  // v4: 1-2 line summary
+      content: memory.content,           // v4: Full structured template
       reasoning: memory.reasoning,
       importance_weight: memory.importance_weight,
       confidence_score: memory.confidence_score,
@@ -539,6 +542,7 @@ export class MemoryStore {
 
     return memories.all().map(record => ({
       id: record.id,
+      headline: record.headline ?? '',  // v4: may be empty for old memories
       content: record.content,
       reasoning: record.reasoning,
       importance_weight: record.importance_weight,

package/src/server/index.ts

@@ -296,6 +296,60 @@ export async function createServer(config: ServerConfig = {}) {
           }, { headers: corsHeaders })
         }
 
+        // Expand memories by ID - returns full content for specific memories
+        if (path === '/memory/expand' && req.method === 'GET') {
+          const idsParam = url.searchParams.get('ids') ?? ''
+          const projectId = url.searchParams.get('project_id') ?? 'default'
+          const projectPath = url.searchParams.get('project_path') ?? undefined
+
+          if (!idsParam) {
+            return Response.json({
+              success: false,
+              error: 'Missing ids parameter. Usage: /memory/expand?ids=abc123,def456',
+            }, { status: 400, headers: corsHeaders })
+          }
+
+          // Parse comma-separated short IDs
+          const shortIds = idsParam.split(',').map(id => id.trim()).filter(Boolean)
+
+          // Get all memories and filter by short ID suffix
+          const allMemories = await engine.getAllMemories(projectId, projectPath)
+          const expanded: Record<string, { headline?: string; content: string; context_type: string }> = {}
+
+          for (const memory of allMemories) {
+            const shortId = memory.id.slice(-6)
+            if (shortIds.includes(shortId)) {
+              expanded[shortId] = {
+                headline: memory.headline,
+                content: memory.content,
+                context_type: memory.context_type || 'technical',
+              }
+            }
+          }
+
+          // Format as readable text for CLI output
+          const lines: string[] = ['## Expanded Memories\n']
+          for (const shortId of shortIds) {
+            const mem = expanded[shortId]
+            if (mem) {
+              lines.push(`### #${shortId} (${mem.context_type})`)
+              if (mem.headline) {
+                lines.push(`**${mem.headline}**\n`)
+              }
+              lines.push(mem.content)
+              lines.push('')
+            } else {
+              lines.push(`### #${shortId}`)
+              lines.push(`Memory not found`)
+              lines.push('')
+            }
+          }
+
+          return new Response(lines.join('\n'), {
+            headers: { ...corsHeaders, 'Content-Type': 'text/plain' },
+          })
+        }
+
         // 404
         return Response.json(
           { error: 'Not found', path },

package/src/types/memory.ts

@@ -54,11 +54,12 @@ export type CurationTrigger =
 
 /**
  * A memory curated by Claude with semantic understanding
- * v3 schema - consolidated metadata, strict context types
+ * v4 schema - two-tier structure (headline + expanded content)
  */
 export interface CuratedMemory {
-  // Core content
-  content: string                           // The memory content itself
+  // Core content (v4: two-tier structure)
+  headline: string                          // v4: 1-2 line summary, always shown in retrieval
+  content: string                           // v4: Full structured template (expand on demand)
   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
@@ -89,10 +90,11 @@ export interface CuratedMemory {
 
 /**
  * A stored memory with database metadata
- * v3 schema - removed unused fields, consolidated metadata
+ * v4 schema - two-tier structure with backwards compatibility
  */
-export interface StoredMemory extends CuratedMemory {
+export interface StoredMemory extends Omit<CuratedMemory, 'headline'> {
   id: string                                // Unique identifier
+  headline?: string                         // v4: Optional for backwards compat (old memories don't have it)
   session_id: string                        // Session that created this memory
   project_id: string                        // Project this belongs to
   created_at: number                        // Timestamp (ms since epoch)
@@ -137,10 +139,10 @@ export interface StoredMemory extends CuratedMemory {
 }
 
 /**
- * Default values for v3 fields based on context_type
+ * Default values for v4 fields based on context_type
  * Uses only the 11 canonical context types
  */
-export const V3_DEFAULTS = {
+export const V4_DEFAULTS = {
   // Type-specific defaults (all 11 canonical types)
   typeDefaults: {
     personal: { scope: 'global', temporal_class: 'eternal', fade_rate: 0 },
@@ -169,38 +171,39 @@ export const V3_DEFAULTS = {
   },
 }
 
-// Backwards compatibility alias
-export const V2_DEFAULTS = V3_DEFAULTS
+// Backwards compatibility aliases
+export const V3_DEFAULTS = V4_DEFAULTS
+export const V2_DEFAULTS = V4_DEFAULTS
 
 /**
- * Apply v3 defaults to a memory
+ * Apply v4 defaults to a memory
  * Uses context_type to determine appropriate defaults
  */
-export function applyV3Defaults(memory: Partial<StoredMemory>): StoredMemory {
+export function applyV4Defaults(memory: Partial<StoredMemory>): StoredMemory {
   const contextType = (memory.context_type ?? 'technical') as ContextType
-  const typeDefaults = V3_DEFAULTS.typeDefaults[contextType] ?? V3_DEFAULTS.typeDefaults.technical
+  const typeDefaults = V4_DEFAULTS.typeDefaults[contextType] ?? V4_DEFAULTS.typeDefaults.technical
 
   return {
     // Spread existing memory
     ...memory,
 
     // Apply status default
-    status: memory.status ?? V3_DEFAULTS.fallback.status,
+    status: memory.status ?? V4_DEFAULTS.fallback.status,
 
     // Apply scope from type defaults
-    scope: memory.scope ?? typeDefaults?.scope ?? V3_DEFAULTS.fallback.scope,
+    scope: memory.scope ?? typeDefaults?.scope ?? V4_DEFAULTS.fallback.scope,
 
     // Apply temporal class from type defaults
-    temporal_class: memory.temporal_class ?? typeDefaults?.temporal_class ?? V3_DEFAULTS.fallback.temporal_class,
+    temporal_class: memory.temporal_class ?? typeDefaults?.temporal_class ?? V4_DEFAULTS.fallback.temporal_class,
 
     // Apply fade rate from type defaults
-    fade_rate: memory.fade_rate ?? typeDefaults?.fade_rate ?? V3_DEFAULTS.fallback.fade_rate,
+    fade_rate: memory.fade_rate ?? typeDefaults?.fade_rate ?? V4_DEFAULTS.fallback.fade_rate,
 
     // Apply other defaults
-    sessions_since_surfaced: memory.sessions_since_surfaced ?? V3_DEFAULTS.fallback.sessions_since_surfaced,
-    awaiting_implementation: memory.awaiting_implementation ?? V3_DEFAULTS.fallback.awaiting_implementation,
-    awaiting_decision: memory.awaiting_decision ?? V3_DEFAULTS.fallback.awaiting_decision,
-    exclude_from_retrieval: memory.exclude_from_retrieval ?? V3_DEFAULTS.fallback.exclude_from_retrieval,
+    sessions_since_surfaced: memory.sessions_since_surfaced ?? V4_DEFAULTS.fallback.sessions_since_surfaced,
+    awaiting_implementation: memory.awaiting_implementation ?? V4_DEFAULTS.fallback.awaiting_implementation,
+    awaiting_decision: memory.awaiting_decision ?? V4_DEFAULTS.fallback.awaiting_decision,
+    exclude_from_retrieval: memory.exclude_from_retrieval ?? V4_DEFAULTS.fallback.exclude_from_retrieval,
 
     // Initialize empty arrays if not present
     related_to: memory.related_to ?? [],
@@ -209,18 +212,27 @@ export function applyV3Defaults(memory: Partial<StoredMemory>): StoredMemory {
     related_files: memory.related_files ?? [],
 
     // Mark as current schema version
-    schema_version: memory.schema_version ?? 3,
+    schema_version: memory.schema_version ?? 4,
   } as StoredMemory
 }
 
-// Backwards compatibility alias
-export const applyV2Defaults = applyV3Defaults
+// Backwards compatibility aliases
+export const applyV3Defaults = applyV4Defaults
+export const applyV2Defaults = applyV4Defaults
 
 /**
- * Check if a memory needs migration to v3
+ * Check if a memory needs migration to latest schema
  */
 export function needsMigration(memory: Partial<StoredMemory>): boolean {
-  return !memory.schema_version || memory.schema_version < 3
+  return !memory.schema_version || memory.schema_version < 4
+}
+
+/**
+ * Check if a memory has expandable content (v4 feature)
+ * Old memories (v3 and below) don't have headline field
+ */
+export function hasExpandableContent(memory: StoredMemory): boolean {
+  return !!memory.headline && memory.headline.length > 0
 }
 
 /**

package/src/types/schema.ts

@@ -9,7 +9,7 @@ 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 = 3
+export const MEMORY_SCHEMA_VERSION = 4
 
 /**
  * Memory storage schema
@@ -27,10 +27,15 @@ export const MEMORY_SCHEMA_VERSION = 3
  *     - retrieval_weight (retrieval uses importance_weight)
  *     - temporal_relevance (replaced by temporal_class)
  *     Also: context_type now strict enum (11 canonical values)
+ * v4: Two-tier memory structure for context efficiency:
+ *     - headline: 1-2 line summary (always shown in retrieval)
+ *     - content: full structured template (expand on demand)
+ *     - Auto-expand rules: action_required, awaiting_decision, 5+ signals
  */
 export const memorySchema = {
-  // ========== CORE CONTENT (v1) ==========
-  content: 'string',
+  // ========== CORE CONTENT (v4) ==========
+  headline: 'string',                     // v4: 1-2 line summary, always shown
+  content: 'string',                      // v4: Full structured template (expand on demand)
   reasoning: 'string',
 
   // ========== SCORES (v1) ==========