@rlabs-inc/memory 0.4.0 → 0.4.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rlabs-inc/memory",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "AI Memory System - Consciousness continuity through intelligent memory curation and retrieval",
   "type": "module",
   "main": "dist/index.js",

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,115 @@ 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 +368,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 +449,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 +477,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/retrieval.ts

@@ -27,6 +27,7 @@ interface ActivationSignals {
   domain: boolean       // Domain word found in message
   feature: boolean      // Feature word found in message
   content: boolean      // Key content words found in message
+  files: boolean        // Related file path matched
   count: number         // Total signals activated
   triggerStrength: number  // How strong the trigger match was (0-1)
   tagCount: number      // How many tags matched
@@ -99,8 +100,54 @@ export class SmartVectorRetrieval {
     return new Set(words)
   }
 
+  /**
+   * Extract file paths from message
+   * Matches patterns like /path/to/file.ts, src/core/engine.ts, ./relative/path
+   */
+  private _extractFilePaths(text: string): Set<string> {
+    const paths = new Set<string>()
+    // Match file paths (with / or \ separators, optional extension)
+    const pathPattern = /(?:^|[\s'"(])([.\/\\]?(?:[\w.-]+[\/\\])+[\w.-]+(?:\.\w+)?)/g
+    let match
+    while ((match = pathPattern.exec(text)) !== null) {
+      const path = match[1].toLowerCase()
+      paths.add(path)
+      // Also add just the filename for partial matching
+      const filename = path.split(/[\/\\]/).pop()
+      if (filename) paths.add(filename)
+    }
+    return paths
+  }
+
+  /**
+   * Check if related_files activate for this message
+   */
+  private _checkFilesActivation(
+    messagePaths: Set<string>,
+    relatedFiles: string[] | undefined
+  ): boolean {
+    if (!relatedFiles?.length || !messagePaths.size) return false
+
+    for (const file of relatedFiles) {
+      const fileLower = file.toLowerCase()
+      // Check if any message path matches this file
+      for (const msgPath of messagePaths) {
+        if (fileLower.includes(msgPath) || msgPath.includes(fileLower)) {
+          return true
+        }
+      }
+      // Also check just the filename
+      const filename = fileLower.split(/[\/\\]/).pop()
+      if (filename && messagePaths.has(filename)) {
+        return true
+      }
+    }
+    return false
+  }
+
   /**
    * Pre-filter: Binary exclusions based on v2 lifecycle fields
+   * NOTE: superseded_by memories are NOT filtered here - they get redirected in Phase 1
    */
   private _preFilter(
     memories: StoredMemory[],
@@ -110,7 +157,7 @@ export class SmartVectorRetrieval {
     return memories.filter(memory => {
       if (memory.status && memory.status !== 'active') return false
       if (memory.exclude_from_retrieval === true) return false
-      if (memory.superseded_by) return false
+      // NOTE: Don't filter superseded_by here - we handle redirects in Phase 1
       const isGlobal = memory.scope === 'global' || memory.project_id === 'global'
       if (!isGlobal && memory.project_id !== currentProjectId) return false
       if (memory.anti_triggers?.length) {
@@ -355,6 +402,13 @@ export class SmartVectorRetrieval {
 
     const messageLower = currentMessage.toLowerCase()
     const messageWords = this._extractSignificantWords(currentMessage)
+    const messagePaths = this._extractFilePaths(currentMessage)
+
+    // Build lookup map for redirect resolution
+    const memoryById = new Map<string, StoredMemory>()
+    for (const m of allMemories) {
+      memoryById.set(m.id, m)
+    }
 
     // ================================================================
     // PHASE 0: PRE-FILTER (Binary exclusions)
@@ -368,13 +422,13 @@ export class SmartVectorRetrieval {
     // PHASE 1: ACTIVATION SIGNALS
     // Count how many signals agree this memory should activate
     // A memory is relevant if >= MIN_ACTIVATION_SIGNALS fire
+    // Handles redirects for superseded_by/resolved_by
     // ================================================================
     const activatedMemories: ActivatedMemory[] = []
+    const activatedIds = new Set<string>()
     let rejectedCount = 0
 
     for (const memory of candidates) {
-      const isGlobal = memory.scope === 'global' || memory.project_id === 'global'
-
       // Check each activation signal
       const triggerResult = this._checkTriggerActivation(
         messageLower, messageWords, memory.trigger_phrases ?? []
@@ -389,15 +443,17 @@ export class SmartVectorRetrieval {
         messageLower, messageWords, memory.feature
       )
       const contentActivated = this._checkContentActivation(messageWords, memory)
+      const filesActivated = this._checkFilesActivation(messagePaths, memory.related_files)
       const vectorSimilarity = this._calculateVectorSimilarity(queryEmbedding, memory.embedding)
 
-      // Count activated signals
+      // Count activated signals (now 7 possible signals)
       let signalCount = 0
       if (triggerResult.activated) signalCount++
       if (tagResult.activated) signalCount++
       if (domainActivated) signalCount++
       if (featureActivated) signalCount++
       if (contentActivated) signalCount++
+      if (filesActivated) signalCount++
       // Vector similarity as bonus signal only if very high
       if (vectorSimilarity >= 0.40) signalCount++
 
@@ -407,6 +463,7 @@ export class SmartVectorRetrieval {
         domain: domainActivated,
         feature: featureActivated,
         content: contentActivated,
+        files: filesActivated,
         count: signalCount,
         triggerStrength: triggerResult.strength,
         tagCount: tagResult.count,
@@ -419,15 +476,34 @@ export class SmartVectorRetrieval {
         continue
       }
 
+      // REDIRECT: If superseded_by or resolved_by exists, surface the replacement instead
+      let memoryToSurface = memory
+      if (memory.superseded_by || memory.resolved_by) {
+        const replacementId = memory.superseded_by ?? memory.resolved_by
+        const replacement = replacementId ? memoryById.get(replacementId) : undefined
+        if (replacement && replacement.status !== 'archived' && replacement.status !== 'deprecated') {
+          memoryToSurface = replacement
+          logger.debug(`Redirect: ${memory.id.slice(-8)} → ${replacement.id.slice(-8)} (${memory.superseded_by ? 'superseded' : 'resolved'})`, 'retrieval')
+        }
+      }
+
+      // Skip if we already added this memory (could happen from multiple redirects)
+      if (activatedIds.has(memoryToSurface.id)) {
+        continue
+      }
+
+      const isGlobal = memoryToSurface.scope === 'global' || memoryToSurface.project_id === 'global'
+
       // Calculate importance for ranking (Phase 2) - uses ALL rich metadata
-      const importanceScore = this._calculateImportanceScore(memory, signalCount, messageLower, messageWords)
+      const importanceScore = this._calculateImportanceScore(memoryToSurface, signalCount, messageLower, messageWords)
 
       activatedMemories.push({
-        memory,
+        memory: memoryToSurface,
         signals,
         importanceScore,
         isGlobal,
       })
+      activatedIds.add(memoryToSurface.id)
     }
 
     // Log diagnostics
@@ -517,23 +593,60 @@ export class SmartVectorRetrieval {
       selectedIds.add(item.memory.id)
     }
 
-    // PHASE 4: RELATED MEMORIES (if space remains)
+    // PHASE 4: LINKED MEMORIES (related_to, blocked_by, blocks)
+    // Pull in linked memories when space remains
     if (selected.length < maxMemories) {
-      const relatedIds = new Set<string>()
+      const linkedIds = new Set<string>()
+
       for (const item of selected) {
+        // related_to - explicit relationships
         for (const relatedId of item.memory.related_to ?? []) {
           if (!selectedIds.has(relatedId)) {
-            relatedIds.add(relatedId)
+            linkedIds.add(relatedId)
+          }
+        }
+        // blocked_by - show what's blocking this
+        if (item.memory.blocked_by && !selectedIds.has(item.memory.blocked_by)) {
+          linkedIds.add(item.memory.blocked_by)
+        }
+        // blocks - show what this blocks
+        for (const blockedId of item.memory.blocks ?? []) {
+          if (!selectedIds.has(blockedId)) {
+            linkedIds.add(blockedId)
           }
         }
       }
 
+      // First try to find linked memories in the activated list
       for (const item of activatedMemories) {
         if (selected.length >= maxMemories) break
         if (selectedIds.has(item.memory.id)) continue
-        if (relatedIds.has(item.memory.id)) {
+        if (linkedIds.has(item.memory.id)) {
           selected.push(item)
           selectedIds.add(item.memory.id)
+          logger.debug(`Linked: ${item.memory.id.slice(-8)} pulled by relationship`, 'retrieval')
+        }
+      }
+
+      // If linked memories weren't in activated list, pull them directly from allMemories
+      // (they might not have activated on their own but are important for context)
+      if (selected.length < maxMemories) {
+        for (const linkedId of linkedIds) {
+          if (selected.length >= maxMemories) break
+          if (selectedIds.has(linkedId)) continue
+
+          const linkedMemory = memoryById.get(linkedId)
+          if (linkedMemory && linkedMemory.status !== 'archived' && linkedMemory.status !== 'deprecated') {
+            const isGlobal = linkedMemory.scope === 'global' || linkedMemory.project_id === 'global'
+            selected.push({
+              memory: linkedMemory,
+              signals: { trigger: false, tags: false, domain: false, feature: false, content: false, files: false, count: 0, triggerStrength: 0, tagCount: 0, vectorSimilarity: 0 },
+              importanceScore: linkedMemory.importance_weight ?? 0.5,
+              isGlobal,
+            })
+            selectedIds.add(linkedId)
+            logger.debug(`Linked (direct): ${linkedId.slice(-8)} pulled for context`, 'retrieval')
+          }
         }
       }
     }
@@ -566,6 +679,7 @@ export class SmartVectorRetrieval {
           domain: item.signals.domain,
           feature: item.signals.feature,
           content: item.signals.content,
+          files: item.signals.files,
           vector: item.signals.vectorSimilarity >= 0.40,
           vectorSimilarity: item.signals.vectorSimilarity,
         },
@@ -575,8 +689,8 @@ export class SmartVectorRetrieval {
     // Convert to RetrievalResult format
     return selected.map(item => ({
       ...item.memory,
-      score: item.signals.count / 6,
-      relevance_score: item.signals.count / 6,
+      score: item.signals.count / 7,  // 7 possible signals
+      relevance_score: item.signals.count / 7,
       value_score: item.importanceScore,
     }))
   }
@@ -592,6 +706,7 @@ export class SmartVectorRetrieval {
     if (signals.domain) reasons.push('domain')
     if (signals.feature) reasons.push('feature')
     if (signals.content) reasons.push('content')
+    if (signals.files) reasons.push('files')
     if (signals.vectorSimilarity >= 0.40) reasons.push(`vector:${(signals.vectorSimilarity * 100).toFixed(0)}%`)
 
     return reasons.length
@@ -608,20 +723,21 @@ export class SmartVectorRetrieval {
     rejectedCount: number
   ): void {
     const signalBuckets: Record<string, number> = {
-      '2 signals': 0, '3 signals': 0, '4 signals': 0, '5 signals': 0, '6 signals': 0
+      '2 signals': 0, '3 signals': 0, '4 signals': 0, '5 signals': 0, '6 signals': 0, '7 signals': 0
     }
     for (const mem of activated) {
-      const key = `${Math.min(mem.signals.count, 6)} signals`
+      const key = `${Math.min(mem.signals.count, 7)} signals`
       signalBuckets[key] = (signalBuckets[key] ?? 0) + 1
     }
 
-    let triggerCount = 0, tagCount = 0, domainCount = 0, featureCount = 0, contentCount = 0, vectorCount = 0
+    let triggerCount = 0, tagCount = 0, domainCount = 0, featureCount = 0, contentCount = 0, filesCount = 0, vectorCount = 0
     for (const mem of activated) {
       if (mem.signals.trigger) triggerCount++
       if (mem.signals.tags) tagCount++
       if (mem.signals.domain) domainCount++
       if (mem.signals.feature) featureCount++
       if (mem.signals.content) contentCount++
+      if (mem.signals.files) filesCount++
       if (mem.signals.vectorSimilarity >= 0.40) vectorCount++
     }
 
@@ -645,6 +761,7 @@ export class SmartVectorRetrieval {
         domain: domainCount,
         feature: featureCount,
         content: contentCount,
+        files: filesCount,
         vector: vectorCount,
         total: activated.length,
       },

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) ==========

package/src/utils/logger.ts

@@ -574,6 +574,7 @@ export const logger = {
       domain: number
       feature: number
       content: number
+      files: number
       vector: number
       total: number
     }
@@ -600,6 +601,7 @@ export const logger = {
         { name: 'domain', count: signalBreakdown.domain },
         { name: 'feature', count: signalBreakdown.feature },
         { name: 'content', count: signalBreakdown.content },
+        { name: 'files', count: signalBreakdown.files },
         { name: 'vector', count: signalBreakdown.vector },
       ]
       for (const sig of signals) {
@@ -620,7 +622,7 @@ export const logger = {
     if (Object.keys(buckets).length > 0) {
       console.log(`      ${style('bold', 'Distribution:')}`)
       const maxBucketCount = Math.max(...Object.values(buckets), 1)
-      const bucketOrder = ['2 signals', '3 signals', '4 signals', '5 signals', '6 signals']
+      const bucketOrder = ['2 signals', '3 signals', '4 signals', '5 signals', '6 signals', '7 signals']
 
       for (const bucket of bucketOrder) {
         const count = buckets[bucket] ?? 0