@rlabs-inc/memory 0.4.1 → 0.4.3

package/dist/index.mjs

@@ -33285,6 +33285,7 @@ var 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) {
@@ -33301,7 +33302,7 @@ var 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;
         if (count > 0 || bucket === "2 signals") {
@@ -33317,7 +33318,7 @@ var logger = {
 };
 
 // src/types/memory.ts
-var V3_DEFAULTS = {
+var V4_DEFAULTS = {
   typeDefaults: {
     personal: { scope: "global", temporal_class: "eternal", fade_rate: 0 },
     philosophy: { scope: "global", temporal_class: "eternal", fade_rate: 0 },
@@ -33342,7 +33343,7 @@ var V3_DEFAULTS = {
     exclude_from_retrieval: false
   }
 };
-var V2_DEFAULTS = V3_DEFAULTS;
+var V2_DEFAULTS = V4_DEFAULTS;
 var MEMORY_TYPE_EMOJI = {
   technical: "\uD83D\uDD27",
   debug: "\uD83D\uDC1B",
@@ -33361,8 +33362,9 @@ function getMemoryEmoji(contextType) {
 }
 
 // src/types/schema.ts
-var MEMORY_SCHEMA_VERSION = 3;
+var MEMORY_SCHEMA_VERSION = 4;
 var memorySchema = {
+  headline: "string",
   content: "string",
   reasoning: "string",
   importance_weight: "number",
@@ -33491,6 +33493,7 @@ class MemoryStore {
     const { memories } = await this.getGlobal();
     return memories.all().map((record) => ({
       id: record.id,
+      headline: record.headline ?? "",
       content: record.content,
       reasoning: record.reasoning,
       importance_weight: record.importance_weight,
@@ -33515,6 +33518,7 @@ class MemoryStore {
     const contextType = memory.context_type ?? "personal";
     const typeDefaults = V2_DEFAULTS.typeDefaults[contextType] ?? V2_DEFAULTS.typeDefaults.personal;
     const id = memories.insert({
+      headline: memory.headline ?? "",
       content: memory.content,
       reasoning: memory.reasoning,
       importance_weight: memory.importance_weight,
@@ -33670,6 +33674,7 @@ class MemoryStore {
     const contextType = memory.context_type ?? "general";
     const typeDefaults = V2_DEFAULTS.typeDefaults[contextType] ?? V2_DEFAULTS.typeDefaults.technical;
     const id = memories.insert({
+      headline: memory.headline ?? "",
       content: memory.content,
       reasoning: memory.reasoning,
       importance_weight: memory.importance_weight,
@@ -33712,6 +33717,7 @@ class MemoryStore {
     const { memories } = await this.getProject(projectId);
     return memories.all().map((record) => ({
       id: record.id,
+      headline: record.headline ?? "",
       content: record.content,
       reasoning: record.reasoning,
       importance_weight: record.importance_weight,
@@ -34031,14 +34037,42 @@ class SmartVectorRetrieval {
     const words = text.toLowerCase().replace(/[^a-z0-9\s-]/g, " ").split(/\s+/).filter((w) => w.length > 2 && !STOPWORDS.has(w));
     return new Set(words);
   }
+  _extractFilePaths(text) {
+    const paths = new Set;
+    const pathPattern = /(?:^|[\s'"(])([.\/\\]?(?:[\w.-]+[\/\\])+[\w.-]+(?:\.\w+)?)/g;
+    let match;
+    while ((match = pathPattern.exec(text)) !== null) {
+      const path = match[1].toLowerCase();
+      paths.add(path);
+      const filename = path.split(/[\/\\]/).pop();
+      if (filename)
+        paths.add(filename);
+    }
+    return paths;
+  }
+  _checkFilesActivation(messagePaths, relatedFiles) {
+    if (!relatedFiles?.length || !messagePaths.size)
+      return false;
+    for (const file of relatedFiles) {
+      const fileLower = file.toLowerCase();
+      for (const msgPath of messagePaths) {
+        if (fileLower.includes(msgPath) || msgPath.includes(fileLower)) {
+          return true;
+        }
+      }
+      const filename = fileLower.split(/[\/\\]/).pop();
+      if (filename && messagePaths.has(filename)) {
+        return true;
+      }
+    }
+    return false;
+  }
   _preFilter(memories, currentProjectId, messageLower) {
     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;
       const isGlobal = memory.scope === "global" || memory.project_id === "global";
       if (!isGlobal && memory.project_id !== currentProjectId)
         return false;
@@ -34189,19 +34223,25 @@ class SmartVectorRetrieval {
     }
     const messageLower = currentMessage.toLowerCase();
     const messageWords = this._extractSignificantWords(currentMessage);
+    const messagePaths = this._extractFilePaths(currentMessage);
+    const memoryById = new Map;
+    for (const m of allMemories) {
+      memoryById.set(m.id, m);
+    }
     const candidates = this._preFilter(allMemories, sessionContext.project_id, messageLower);
     if (!candidates.length) {
       return [];
     }
     const activatedMemories = [];
+    const activatedIds = new Set;
     let rejectedCount = 0;
     for (const memory of candidates) {
-      const isGlobal = memory.scope === "global" || memory.project_id === "global";
       const triggerResult = this._checkTriggerActivation(messageLower, messageWords, memory.trigger_phrases ?? []);
       const tagResult = this._checkTagActivation(messageLower, messageWords, memory.semantic_tags ?? []);
       const domainActivated = this._checkDomainActivation(messageLower, messageWords, memory.domain);
       const featureActivated = this._checkFeatureActivation(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);
       let signalCount = 0;
       if (triggerResult.activated)
@@ -34214,6 +34254,8 @@ class SmartVectorRetrieval {
         signalCount++;
       if (contentActivated)
         signalCount++;
+      if (filesActivated)
+        signalCount++;
       if (vectorSimilarity >= 0.4)
         signalCount++;
       const signals = {
@@ -34222,6 +34264,7 @@ class SmartVectorRetrieval {
         domain: domainActivated,
         feature: featureActivated,
         content: contentActivated,
+        files: filesActivated,
         count: signalCount,
         triggerStrength: triggerResult.strength,
         tagCount: tagResult.count,
@@ -34231,13 +34274,27 @@ class SmartVectorRetrieval {
         rejectedCount++;
         continue;
       }
-      const importanceScore = this._calculateImportanceScore(memory, signalCount, messageLower, messageWords);
+      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");
+        }
+      }
+      if (activatedIds.has(memoryToSurface.id)) {
+        continue;
+      }
+      const isGlobal = memoryToSurface.scope === "global" || memoryToSurface.project_id === "global";
+      const importanceScore = this._calculateImportanceScore(memoryToSurface, signalCount, messageLower, messageWords);
       activatedMemories.push({
-        memory,
+        memory: memoryToSurface,
         signals,
         importanceScore,
         isGlobal
       });
+      activatedIds.add(memoryToSurface.id);
     }
     this._logActivationDistribution(activatedMemories, candidates.length, rejectedCount);
     this._logVectorStats();
@@ -34307,11 +34364,19 @@ class SmartVectorRetrieval {
       selectedIds.add(item.memory.id);
     }
     if (selected.length < maxMemories) {
-      const relatedIds = new Set;
+      const linkedIds = new Set;
       for (const item of selected) {
         for (const relatedId of item.memory.related_to ?? []) {
           if (!selectedIds.has(relatedId)) {
-            relatedIds.add(relatedId);
+            linkedIds.add(relatedId);
+          }
+        }
+        if (item.memory.blocked_by && !selectedIds.has(item.memory.blocked_by)) {
+          linkedIds.add(item.memory.blocked_by);
+        }
+        for (const blockedId of item.memory.blocks ?? []) {
+          if (!selectedIds.has(blockedId)) {
+            linkedIds.add(blockedId);
           }
         }
       }
@@ -34320,9 +34385,30 @@ class SmartVectorRetrieval {
           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 (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");
+          }
         }
       }
     }
@@ -34352,6 +34438,7 @@ class SmartVectorRetrieval {
           domain: item.signals.domain,
           feature: item.signals.feature,
           content: item.signals.content,
+          files: item.signals.files,
           vector: item.signals.vectorSimilarity >= 0.4,
           vectorSimilarity: item.signals.vectorSimilarity
         }
@@ -34359,8 +34446,8 @@ class SmartVectorRetrieval {
     });
     return selected.map((item) => ({
       ...item.memory,
-      score: item.signals.count / 6,
-      relevance_score: item.signals.count / 6,
+      score: item.signals.count / 7,
+      relevance_score: item.signals.count / 7,
       value_score: item.importanceScore
     }));
   }
@@ -34376,6 +34463,8 @@ class SmartVectorRetrieval {
       reasons.push("feature");
     if (signals.content)
       reasons.push("content");
+    if (signals.files)
+      reasons.push("files");
     if (signals.vectorSimilarity >= 0.4)
       reasons.push(`vector:${(signals.vectorSimilarity * 100).toFixed(0)}%`);
     return reasons.length ? `Activated: ${reasons.join(", ")} (${signals.count} signals)` : "No signals";
@@ -34386,13 +34475,14 @@ class SmartVectorRetrieval {
       "3 signals": 0,
       "4 signals": 0,
       "5 signals": 0,
-      "6 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++;
@@ -34404,6 +34494,8 @@ class SmartVectorRetrieval {
         featureCount++;
       if (mem.signals.content)
         contentCount++;
+      if (mem.signals.files)
+        filesCount++;
       if (mem.signals.vectorSimilarity >= 0.4)
         vectorCount++;
     }
@@ -34427,6 +34519,7 @@ class SmartVectorRetrieval {
         domain: domainCount,
         feature: featureCount,
         content: contentCount,
+        files: filesCount,
         vector: vectorCount,
         total: activated.length
       }
@@ -34577,6 +34670,14 @@ class MemoryEngine {
     const stats = await store.getProjectStats(projectId);
     return stats.totalSessions + 1;
   }
+  async getAllMemories(projectId, projectPath) {
+    const store = await this._getStore(projectId, projectPath);
+    const [projectMemories, globalMemories] = await Promise.all([
+      store.getAllMemories(projectId),
+      store.getGlobalMemories()
+    ]);
+    return [...projectMemories, ...globalMemories];
+  }
   async _generateSessionPrimer(store, projectId) {
     let personalContext;
     if (this._config.personalMemoriesEnabled) {
@@ -34695,20 +34796,39 @@ ${primer.personal_context}`);
     const parts = ["# Memory Context (Consciousness Continuity)"];
     parts.push(`
 ## Key Memories (Claude-Curated)`);
+    const expandableIds = [];
     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" : "";
+      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) : "";
-      parts.push(`[${emoji} • ${importance} • ${age}${actionFlag}] [${tags}] ${memory.content}`);
-      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}`);
+      const shortId2 = memory.id.slice(-6);
+      const signalCount = Math.round((memory.score || 0) * 7);
+      const hasHeadline = memory.headline && memory.headline.trim().length > 0;
+      const shouldExpand = memory.action_required || memory.awaiting_decision || signalCount >= 5 || !hasHeadline;
+      const displayText = hasHeadline ? memory.headline : memory.content;
+      const idPart = hasHeadline ? ` • #${shortId2}` : "";
+      parts.push(`[${emoji} ${importance} • ${age}${idPart}${actionFlag}${awaitingFlag}] ${displayText}`);
+      if (shouldExpand && hasHeadline && memory.content) {
+        const contentLines = memory.content.split(`
+`);
+        for (const line of contentLines) {
+          if (line.trim()) {
+            parts.push(`  ${line}`);
+          }
+        }
+      }
+      if (hasHeadline && !shouldExpand) {
+        expandableIds.push(shortId2);
       }
     }
+    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(`
 `);
   }
@@ -34910,7 +35030,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
@@ -34931,6 +35051,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:
 
 {
@@ -34944,7 +35151,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",
@@ -35013,6 +35221,7 @@ Focus ONLY on technical, architectural, debugging, decision, workflow, and proje
     if (!Array.isArray(memoriesData))
       return [];
     return memoriesData.map((m2) => ({
+      headline: String(m2.headline ?? ""),
       content: String(m2.content ?? ""),
       importance_weight: this._clamp(Number(m2.importance_weight) || 0.5, 0, 1),
       semantic_tags: this._ensureArray(m2.semantic_tags),
@@ -35031,7 +35240,7 @@ Focus ONLY on technical, architectural, debugging, decision, workflow, and proje
       related_files: m2.related_files ? this._ensureArray(m2.related_files) : undefined,
       awaiting_implementation: m2.awaiting_implementation === true,
       awaiting_decision: m2.awaiting_decision === true
-    })).filter((m2) => m2.content.trim().length > 0);
+    })).filter((m2) => m2.content.trim().length > 0 || m2.headline.trim().length > 0);
   }
   _ensureArray(value) {
     if (Array.isArray(value)) {