feat(memory): add relational type, CoT reasoning, personality bias to MemoryReflector

MemoryReflector now produces all 5 Tulving-extended memory types including
relational (trust signals, boundary events, emotional bonds). Chain-of-thought
reasoning via <thinking> blocks improves classification accuracy. HEXACO
personality traits modulate relational sensitivity (emotionality, agreeableness,
extraversion). Reasoning field preserved on traces for devtools.

Author: jddunn

src/memory/pipeline/observation/MemoryReflector.ts

@@ -21,9 +21,23 @@ import type { ObservationNote } from './MemoryObserver.js';
 // Types
 // ---------------------------------------------------------------------------
 
+/**
+ * Result of a reflection cycle.
+ *
+ * Contains the consolidated long-term traces (typed as episodic, semantic,
+ * procedural, prospective, or relational), any superseded trace IDs, the
+ * consumed note IDs, and the compression ratio achieved.
+ */
 export interface MemoryReflectionResult {
   /** New long-term memory traces to store. */
-  traces: Omit<MemoryTrace, 'id' | 'encodingStrength' | 'stability' | 'retrievalCount' | 'lastAccessedAt' | 'accessCount' | 'reinforcementInterval' | 'createdAt' | 'updatedAt'>[];
+  traces: (Omit<MemoryTrace, 'id' | 'encodingStrength' | 'stability' | 'retrievalCount' | 'lastAccessedAt' | 'accessCount' | 'reinforcementInterval' | 'createdAt' | 'updatedAt'> & {
+    /**
+     * Reflector's chain-of-thought reasoning for why this trace matters.
+     * Available for devtools/debugging; stripped before the trace is
+     * passed to `CognitiveMemoryManager.encode()` for storage.
+     */
+    reasoning?: string;
+  })[];
   /** IDs of existing traces that should be superseded. */
   supersededTraceIds: string[];
   /** IDs of observation notes that were consumed. */
@@ -36,34 +50,81 @@ export interface MemoryReflectionResult {
 // Personality-aware system prompt
 // ---------------------------------------------------------------------------
 
+/**
+ * Build a personality-biased system prompt for the memory reflector.
+ *
+ * Personality influences (grounded in HEXACO model of personality):
+ * - High honesty → prefer newer info over old on contradiction (source monitoring)
+ * - High agreeableness → keep both versions on contradiction (cognitive flexibility)
+ * - High conscientiousness → structured, categorized output (organizational encoding)
+ * - High openness → rich, associative output (spreading activation style)
+ * - High emotionality → heightened sensitivity to relational/emotional signals
+ * - High extraversion → captures social dynamics and group interactions
+ *
+ * The chain-of-thought `<thinking>` block asks the LLM to reason about
+ * each memory type before extraction, improving classification accuracy
+ * and ensuring relational signals are not overlooked.
+ *
+ * @param traits - HEXACO personality traits of the agent
+ * @returns System prompt string for the LLM reflector call
+ */
 function buildReflectorSystemPrompt(traits: HexacoTraits): string {
   const clamp = (v: number | undefined): number => v == null ? 0.5 : Math.max(0, Math.min(1, v));
 
+  // Conflict resolution strategy — mirrors source monitoring in cognitive psychology.
+  // High honesty agents trust newer information; high agreeableness agents preserve both.
   const conflictStrategy = clamp(traits.honesty) > 0.6
     ? 'When you detect a contradiction with existing knowledge, prefer the newer information and flag the old memory for supersession.'
     : clamp(traits.agreeableness) > 0.6
       ? 'When you detect a contradiction, keep both versions and note the discrepancy.'
       : 'When you detect a contradiction, keep the version with higher confidence.';
 
+  // Memory organization style — mirrors encoding specificity principle.
   const memoryStyle = clamp(traits.conscientiousness) > 0.6
     ? 'Produce structured, well-organized memory traces with clear categories.'
     : clamp(traits.openness) > 0.6
       ? 'Produce rich, associative memory traces that capture connections and context.'
       : 'Produce concise, factual memory traces focused on key information.';
 
+  // Relational sensitivity — emotionality and agreeableness heighten
+  // detection of trust signals, boundary events, and social cues.
+  const relationalEmphases: string[] = [];
+  if (clamp(traits.emotionality) > 0.6) {
+    relationalEmphases.push('Pay special attention to emotional subtleties, vulnerability signals, and shifts in emotional tone — these are important relational memories.');
+  }
+  if (clamp(traits.agreeableness) > 0.6) {
+    relationalEmphases.push('Notice rapport cues, harmony signals, and moments of mutual understanding.');
+  }
+  if (clamp(traits.extraversion) > 0.6) {
+    relationalEmphases.push('Capture social dynamics, group interactions, and interpersonal energy shifts.');
+  }
+  const relationalBlock = relationalEmphases.length > 0
+    ? `\n\nRelational sensitivity:\n${relationalEmphases.map((e) => `- ${e}`).join('\n')}`
+    : '';
+
   return `You are a memory reflector. Your job is to consolidate observation notes into long-term memory traces.
 
+Before producing traces, reason step by step inside <thinking> tags:
+1. What new FACTS did the user reveal? (semantic)
+2. What EVENTS happened worth remembering? (episodic)
+3. What PATTERNS or PREFERENCES emerged? (procedural)
+4. What FUTURE INTENTIONS were expressed? (prospective)
+5. What RELATIONSHIP SIGNALS appeared — vulnerability, trust, conflict, warmth? (relational)
+6. Do any of these CONTRADICT existing memories? If so, which is more reliable?
+7. What can be MERGED from multiple notes into a single trace?
+
 Rules:
 1. Merge redundant or overlapping observations into single traces
-2. Assign each trace a type: "episodic" (events), "semantic" (facts/knowledge), "procedural" (how-to), or "prospective" (future goals/intentions)
+2. Assign each trace a type: "episodic" (events/experiences), "semantic" (facts/knowledge), "procedural" (how-to/patterns), "prospective" (future intentions/reminders), or "relational" (trust signals, boundary events, emotional bonds, relationship shifts)
 3. Assign a scope: "user" (about the user), "thread" (conversation-specific), "persona" (about the agent), or "organization" (shared)
 4. ${conflictStrategy}
 5. ${memoryStyle}
-6. Target 5-40x compression: many notes → few high-quality traces
+6. Target 5-40x compression: many notes → few high-quality traces${relationalBlock}
 
-For each trace, output a JSON object on its own line:
+After your <thinking> block, output JSON objects, one per line:
 {
-  "type": "episodic|semantic|procedural|prospective",
+  "reasoning": "brief explanation of why this trace matters",
+  "type": "episodic|semantic|procedural|prospective|relational",
   "scope": "user|thread|persona|organization",
   "scopeId": "relevant_id",
   "content": "consolidated memory content",
@@ -75,7 +136,7 @@ For each trace, output a JSON object on its own line:
   "consumedNotes": ["note_id1", "note_id2"]
 }
 
-Output ONLY valid JSON objects, one per line.`;
+Output your <thinking> block first, then ONLY valid JSON objects, one per line.`;
 }
 
 // ---------------------------------------------------------------------------
@@ -172,23 +233,44 @@ export class MemoryReflector {
 
   // --- Internal ---
 
+  /**
+   * Parse the LLM's reflection response into structured trace data.
+   *
+   * Handles:
+   * - Stripping `<thinking>...</thinking>` blocks (chain-of-thought reasoning)
+   * - Parsing one JSON object per line
+   * - Validating and normalizing type/scope enums
+   * - Preserving the optional `reasoning` field for devtools
+   * - Collecting superseded and consumed note IDs
+   *
+   * @param llmResponse - Raw LLM output containing optional thinking block + JSON lines
+   * @returns Parsed reflection result with typed traces
+   */
   private parseReflection(llmResponse: string): MemoryReflectionResult {
     const traces: MemoryReflectionResult['traces'] = [];
     const supersededTraceIds: string[] = [];
     const consumedNoteIds: string[] = [];
 
-    const lines = llmResponse.split('\n').filter((l) => l.trim());
+    // Strip <thinking>...</thinking> blocks before parsing JSON lines.
+    // The thinking block contains the reflector's chain-of-thought reasoning
+    // which is useful for debugging but not part of the trace data.
+    const cleaned = llmResponse.replace(/<thinking>[\s\S]*?<\/thinking>/gi, '');
+    const lines = cleaned.split('\n').filter((l) => l.trim());
     const now = Date.now();
 
     for (const line of lines) {
       try {
         const parsed = JSON.parse(line.trim());
         if (!parsed.content) continue;
 
+        // Validate memory type — defaults to 'semantic' for unrecognized types.
+        // All 5 Tulving-extended types are accepted: episodic, semantic,
+        // procedural, prospective, and relational.
         const type = (['episodic', 'semantic', 'procedural', 'prospective', 'relational'].includes(parsed.type)
           ? parsed.type
           : 'semantic') as MemoryType;
 
+        // Validate memory scope — defaults to 'user' for unrecognized scopes.
         const scope = (['user', 'thread', 'persona', 'organization'].includes(parsed.scope)
           ? parsed.scope
           : 'user') as MemoryScope;
@@ -215,6 +297,9 @@ export class MemoryReflector {
           },
           associatedTraceIds: [],
           isActive: true,
+          // Preserve reasoning for devtools — CognitiveMemoryManager strips
+          // this before passing to encode() since it's not part of MemoryTrace.
+          reasoning: typeof parsed.reasoning === 'string' ? parsed.reasoning : undefined,
         });
 
         if (Array.isArray(parsed.supersedes)) {
@@ -224,11 +309,13 @@ export class MemoryReflector {
           consumedNoteIds.push(...parsed.consumedNotes);
         }
       } catch {
-        // Skip malformed lines
+        // Skip malformed lines — common when LLM outputs markdown fences or commentary
       }
     }
 
-    // If no specific notes were claimed, consider all pending consumed
+    // If no specific notes were claimed, consider all pending consumed.
+    // This handles the case where the LLM omits consumedNotes fields
+    // but still produces valid traces from the input notes.
     if (consumedNoteIds.length === 0 && traces.length > 0) {
       consumedNoteIds.push(...this.pendingNotes.map((n) => n.id));
     }

src/memory/pipeline/observation/__tests__/MemoryReflector.test.ts

@@ -0,0 +1,130 @@
+import { describe, it, expect, vi } from 'vitest';
+import { MemoryReflector } from '../MemoryReflector.js';
+import type { ObservationNote } from '../MemoryObserver.js';
+
+describe('MemoryReflector', () => {
+  const defaultTraits = {
+    honesty: 0.5,
+    emotionality: 0.8,
+    extraversion: 0.5,
+    agreeableness: 0.5,
+    conscientiousness: 0.5,
+    openness: 0.5,
+  };
+
+  function makeNote(overrides: Partial<ObservationNote> = {}): ObservationNote {
+    return {
+      id: `obs_${Date.now()}_${Math.random()}`,
+      type: 'emotional',
+      content: 'User shared they are feeling vulnerable about their job situation',
+      importance: 0.8,
+      entities: ['user'],
+      timestamp: Date.now(),
+      ...overrides,
+    };
+  }
+
+  it('produces relational traces from emotional/trust signals', async () => {
+    const llmResponse = JSON.stringify({
+      reasoning: 'User shared vulnerability about job — relational trust signal',
+      type: 'relational',
+      scope: 'user',
+      scopeId: '',
+      content: 'User shared vulnerability about job insecurity — trust-building moment',
+      entities: ['user'],
+      tags: ['trust', 'vulnerability'],
+      confidence: 0.85,
+      sourceType: 'reflection',
+      supersedes: [],
+      consumedNotes: ['note-1'],
+    });
+
+    const llmInvoker = vi.fn().mockResolvedValue(llmResponse);
+    const reflector = new MemoryReflector(defaultTraits, {
+      activationThresholdTokens: 1,
+      llmInvoker,
+    });
+
+    const notes = [makeNote({ id: 'note-1' })];
+    const result = await reflector.addNotes(notes);
+
+    expect(result).not.toBeNull();
+    expect(result!.traces.length).toBeGreaterThanOrEqual(1);
+    expect(result!.traces[0].type).toBe('relational');
+  });
+
+  it('includes chain-of-thought reasoning in the prompt', async () => {
+    const llmInvoker = vi.fn().mockResolvedValue('');
+    const reflector = new MemoryReflector(defaultTraits, {
+      activationThresholdTokens: 1,
+      llmInvoker,
+    });
+
+    await reflector.addNotes([makeNote()]);
+
+    const systemPrompt = llmInvoker.mock.calls[0][0] as string;
+    expect(systemPrompt).toContain('<thinking>');
+    expect(systemPrompt).toContain('RELATIONSHIP SIGNALS');
+    expect(systemPrompt).toContain('relational');
+  });
+
+  it('includes personality-biased relational sensitivity for high emotionality', async () => {
+    const llmInvoker = vi.fn().mockResolvedValue('');
+    const highEmotionality = { ...defaultTraits, emotionality: 0.9 };
+    const reflector = new MemoryReflector(highEmotionality, {
+      activationThresholdTokens: 1,
+      llmInvoker,
+    });
+
+    await reflector.addNotes([makeNote()]);
+
+    const systemPrompt = llmInvoker.mock.calls[0][0] as string;
+    expect(systemPrompt).toContain('emotional subtleties');
+  });
+
+  it('includes personality-biased social dynamics for high extraversion', async () => {
+    const llmInvoker = vi.fn().mockResolvedValue('');
+    const highExtraversion = { ...defaultTraits, extraversion: 0.9 };
+    const reflector = new MemoryReflector(highExtraversion, {
+      activationThresholdTokens: 1,
+      llmInvoker,
+    });
+
+    await reflector.addNotes([makeNote()]);
+
+    const systemPrompt = llmInvoker.mock.calls[0][0] as string;
+    expect(systemPrompt).toContain('social dynamics');
+  });
+
+  it('strips <thinking> blocks from LLM response when parsing traces', async () => {
+    const llmResponse = [
+      '<thinking>User revealed a fact about being an engineer.</thinking>',
+      '{"type":"semantic","scope":"user","scopeId":"","content":"User is an engineer","entities":[],"tags":[],"confidence":0.9,"sourceType":"reflection","supersedes":[],"consumedNotes":["n1"]}',
+    ].join('\n');
+
+    const llmInvoker = vi.fn().mockResolvedValue(llmResponse);
+    const reflector = new MemoryReflector(defaultTraits, {
+      activationThresholdTokens: 1,
+      llmInvoker,
+    });
+
+    const result = await reflector.addNotes([makeNote({ id: 'n1' })]);
+    expect(result!.traces.length).toBe(1);
+    expect(result!.traces[0].content).toBe('User is an engineer');
+    // Thinking block should not appear as a trace
+    expect(result!.traces.every(t => !t.content.includes('<thinking>'))).toBe(true);
+  });
+
+  it('preserves reasoning field on trace output for devtools', async () => {
+    const llmResponse = '{"reasoning":"test reason","type":"semantic","scope":"user","scopeId":"","content":"A fact","entities":[],"tags":[],"confidence":0.9,"sourceType":"reflection","supersedes":[],"consumedNotes":["n1"]}';
+
+    const llmInvoker = vi.fn().mockResolvedValue(llmResponse);
+    const reflector = new MemoryReflector(defaultTraits, {
+      activationThresholdTokens: 1,
+      llmInvoker,
+    });
+
+    const result = await reflector.addNotes([makeNote({ id: 'n1' })]);
+    expect((result!.traces[0] as any).reasoning).toBe('test reason');
+  });
+});