feat(core): add retention decay scoring, entity state tracking, and chunk enrichment

- Replace static importance scoring with Ebbinghaus decay formula:
  R = salience × e^(-λ × Δt) + σ × Σ(1/(t - t_access))
- Add frame_access_log table and recordFrameAccess() for reinforcement
- Add entity_states table with git-style append-only temporal model
  (recordEntityState, getEntityState, getEntityHistory, getEntityDiff)
- Add LLM-based chunk enrichment (frame-enrichment.ts) for pronoun
  resolution and entity extraction at ingest time
- Update gc.test.ts to use relative assertions matching decay formula
- 14 new tests for retention decay, access logging, entity state

Author: StackMemory Bot (CLI)

src/core/config/config-manager.ts

@@ -12,6 +12,7 @@ import {
   DEFAULT_CONFIG,
   PRESET_PROFILES,
   ScoringWeights,
+  DEFAULT_ENRICHMENT,
 } from './types.js';
 
 export interface ValidationResult {
@@ -95,6 +96,7 @@ export class ConfigManager {
         },
       },
       performance: { ...DEFAULT_CONFIG.performance, ...loaded.performance },
+      enrichment: { ...DEFAULT_ENRICHMENT, ...loaded.enrichment },
       profiles: { ...PRESET_PROFILES, ...loaded.profiles },
     };
 

src/core/config/types.ts

@@ -42,6 +42,12 @@ export interface RetentionConfig {
   };
 }
 
+export interface EnrichmentConfig {
+  enabled: boolean;
+  lookbackDepth: number;
+  extractEntities: boolean;
+}
+
 export interface PerformanceConfig {
   max_stack_depth: number;
   max_frame_events: number;
@@ -69,6 +75,7 @@ export interface StackMemoryConfig {
   };
   retention: RetentionConfig;
   performance: PerformanceConfig;
+  enrichment: EnrichmentConfig;
   profiles?: Record<string, ProfileConfig>;
 }
 
@@ -166,6 +173,12 @@ export const PRESET_PROFILES: Record<string, ProfileConfig> = {
   },
 };
 
+export const DEFAULT_ENRICHMENT: EnrichmentConfig = {
+  enabled: false,
+  lookbackDepth: 3,
+  extractEntities: true,
+};
+
 export const DEFAULT_CONFIG: StackMemoryConfig = {
   version: '1.0',
   scoring: {
@@ -196,5 +209,6 @@ export const DEFAULT_CONFIG: StackMemoryConfig = {
     retrieval_timeout_ms: 500,
     batch_upload_size: 100,
   },
+  enrichment: DEFAULT_ENRICHMENT,
   profiles: PRESET_PROFILES,
 };

src/core/context/frame-database.ts

@@ -227,6 +227,54 @@ export class FrameDatabase {
         INSERT OR IGNORE INTO schema_version (version) VALUES (1);
       `);
 
+      // Migration: add access_count column if missing
+      try {
+        this.db.exec(
+          'ALTER TABLE frames ADD COLUMN access_count INTEGER DEFAULT 0'
+        );
+      } catch {
+        // Column already exists
+      }
+
+      // Migration: add last_accessed column if missing
+      try {
+        this.db.exec('ALTER TABLE frames ADD COLUMN last_accessed INTEGER');
+      } catch {
+        // Column already exists
+      }
+
+      // Frame access log for retention decay scoring
+      this.db.exec(`
+        CREATE TABLE IF NOT EXISTS frame_access_log (
+          id INTEGER PRIMARY KEY AUTOINCREMENT,
+          frame_id TEXT NOT NULL,
+          accessed_at INTEGER NOT NULL DEFAULT (unixepoch()),
+          FOREIGN KEY (frame_id) REFERENCES frames(frame_id) ON DELETE CASCADE
+        );
+        CREATE INDEX IF NOT EXISTS idx_frame_access_log_frame
+          ON frame_access_log(frame_id);
+      `);
+
+      // Temporal entity state table (append-only knowledge graph)
+      this.db.exec(`
+        CREATE TABLE IF NOT EXISTS entity_states (
+          id INTEGER PRIMARY KEY AUTOINCREMENT,
+          project_id TEXT NOT NULL,
+          entity_name TEXT NOT NULL,
+          relation TEXT NOT NULL,
+          value TEXT NOT NULL,
+          context TEXT,
+          source_frame_id TEXT,
+          valid_from INTEGER NOT NULL DEFAULT (unixepoch()),
+          superseded_at INTEGER,
+          FOREIGN KEY (source_frame_id) REFERENCES frames(frame_id)
+        );
+        CREATE INDEX IF NOT EXISTS idx_entity_name
+          ON entity_states(project_id, entity_name, relation);
+        CREATE INDEX IF NOT EXISTS idx_entity_temporal
+          ON entity_states(entity_name, valid_from DESC);
+      `);
+
       // Cord task orchestration table (dependency DAG for multi-agent coordination)
       this.db.exec(`
         CREATE TABLE IF NOT EXISTS cord_tasks (

src/core/context/frame-enrichment.ts

@@ -0,0 +1,136 @@
+/**
+ * Frame Enrichment - Optional LLM-based chunk enrichment at frame close.
+ * Resolves pronouns/entities and extracts entity states from frame content.
+ * Registers as a frame lifecycle close hook.
+ */
+
+import { logger } from '../monitoring/logger.js';
+import { frameLifecycleHooks } from './frame-lifecycle-hooks.js';
+import type { Frame } from './frame-types.js';
+import type { EnrichmentConfig } from '../config/types.js';
+
+export interface EnrichmentResult {
+  enrichedDigest: string;
+  entities: ExtractedEntity[];
+}
+
+export interface ExtractedEntity {
+  name: string;
+  relation: string;
+  value: string;
+  context?: string;
+}
+
+export interface FrameEnrichmentDeps {
+  getParentFrames: (frameId: string, depth: number) => Promise<Frame[]>;
+  updateDigest: (frameId: string, digest: string) => Promise<void>;
+  recordEntity: (
+    projectId: string,
+    name: string,
+    relation: string,
+    value: string,
+    context?: string,
+    sourceFrameId?: string
+  ) => void;
+}
+
+const ENRICHMENT_PROMPT = `You are a context enrichment engine. Given a frame digest and its parent context, do two things:
+1. Rewrite the digest to be fully self-contained — resolve all pronouns ("it", "that", "the project") using parent context.
+2. Extract entity-relation-value triples from the content.
+
+Respond in JSON only:
+{"enrichedDigest":"...","entities":[{"name":"...","relation":"...","value":"...","context":"..."}]}`;
+
+function buildEnrichmentInput(frame: Frame, parents: Frame[]): string {
+  const parentCtx = parents
+    .map((p) => `[${p.name}]: ${p.digest_text ?? ''}`)
+    .join('\n');
+  return `Parent context:\n${parentCtx}\n\nCurrent frame "${frame.name}":\n${frame.digest_text ?? ''}`;
+}
+
+export async function enrichFrame(
+  frame: Frame,
+  parents: Frame[],
+  apiKey: string
+): Promise<EnrichmentResult | undefined> {
+  try {
+    const Anthropic = (await import('@anthropic-ai/sdk')).default;
+    const client = new Anthropic({ apiKey });
+    const input = buildEnrichmentInput(frame, parents);
+
+    const response = await client.messages.create({
+      model: 'claude-3-5-haiku-latest',
+      max_tokens: 1024,
+      system: ENRICHMENT_PROMPT,
+      messages: [{ role: 'user', content: input }],
+    });
+
+    const text =
+      response.content[0].type === 'text' ? response.content[0].text : '';
+    return JSON.parse(text) as EnrichmentResult;
+  } catch (err) {
+    logger.warn('Frame enrichment LLM call failed', {
+      error: err instanceof Error ? err.message : String(err),
+      frameId: frame.frame_id,
+    });
+    return undefined;
+  }
+}
+
+let unregister: (() => void) | null = null;
+
+export function registerEnrichmentHook(
+  config: EnrichmentConfig,
+  deps: FrameEnrichmentDeps
+): () => void {
+  if (unregister) unregister();
+  if (!config.enabled) return () => {};
+
+  const apiKey = process.env.ANTHROPIC_API_KEY;
+  if (!apiKey) {
+    logger.warn('Enrichment enabled but ANTHROPIC_API_KEY not set');
+    return () => {};
+  }
+
+  unregister = frameLifecycleHooks.onFrameClosed(
+    'frame-enrichment',
+    async (data) => {
+      if (!data.frame.digest_text) return;
+
+      const parents = await deps.getParentFrames(
+        data.frame.frame_id,
+        config.lookbackDepth
+      );
+
+      const result = await enrichFrame(data.frame, parents, apiKey);
+      if (!result) return;
+
+      await deps.updateDigest(data.frame.frame_id, result.enrichedDigest);
+
+      if (config.extractEntities) {
+        for (const entity of result.entities) {
+          try {
+            deps.recordEntity(
+              data.frame.project_id,
+              entity.name,
+              entity.relation,
+              entity.value,
+              entity.context,
+              data.frame.frame_id
+            );
+          } catch {
+            // best-effort per entity
+          }
+        }
+      }
+    },
+    -10 // low priority — runs after other hooks
+  );
+
+  return () => {
+    if (unregister) {
+      unregister();
+      unregister = null;
+    }
+  };
+}

src/core/database/__tests__/gc.test.ts

@@ -413,8 +413,9 @@ describe('Garbage Collection', () => {
       });
 
       const score = adapter.computeImportanceScore('empty-frame');
-      // Base score: 0.3 (no anchors, no events > 3, no digest, no children, not recent)
-      expect(score).toBe(0.3);
+      // Ebbinghaus decay: salience(0.3) * exp(-0.05 * 10) ≈ 0.18
+      expect(score).toBeGreaterThanOrEqual(0.05);
+      expect(score).toBeLessThan(0.3);
     });
 
     it('should increase score for frames with DECISION anchors', async () => {
@@ -424,9 +425,15 @@ describe('Garbage Collection', () => {
       });
       insertAnchor('decision-frame', 'anc-decision', 'DECISION');
 
+      const baseScore = adapter.computeImportanceScore('empty-frame-baseline');
+      insertFrame({ frameId: 'empty-frame-baseline', createdAt: daysAgo(10) });
+      const baselineScore = adapter.computeImportanceScore(
+        'empty-frame-baseline'
+      );
+
       const score = adapter.computeImportanceScore('decision-frame');
-      // Base 0.3 + 0.15 (DECISION) = 0.45
-      expect(score).toBe(0.45);
+      // DECISION anchor increases salience, so score should be higher than baseline
+      expect(score).toBeGreaterThan(baselineScore);
     });
 
     it('should increase score for frames with digest_text', async () => {
@@ -435,10 +442,12 @@ describe('Garbage Collection', () => {
         createdAt: daysAgo(10),
         digestText: 'This frame has a digest',
       });
+      insertFrame({ frameId: 'no-digest-frame', createdAt: daysAgo(10) });
 
-      const score = adapter.computeImportanceScore('digest-frame');
-      // Base 0.3 + 0.15 (digest) = 0.45
-      expect(score).toBe(0.45);
+      const digestScore = adapter.computeImportanceScore('digest-frame');
+      const baseScore = adapter.computeImportanceScore('no-digest-frame');
+      // digest_text increases salience
+      expect(digestScore).toBeGreaterThan(baseScore);
     });
 
     it('should increase score for frames with many events', async () => {
@@ -449,10 +458,12 @@ describe('Garbage Collection', () => {
       for (let i = 0; i < 5; i++) {
         insertEvent('eventful-frame', `evt-${i}`);
       }
+      insertFrame({ frameId: 'quiet-frame', createdAt: daysAgo(10) });
 
-      const score = adapter.computeImportanceScore('eventful-frame');
-      // Base 0.3 + 0.1 (events > 3) = 0.4
-      expect(score).toBe(0.4);
+      const eventScore = adapter.computeImportanceScore('eventful-frame');
+      const baseScore = adapter.computeImportanceScore('quiet-frame');
+      // >3 events increases salience
+      expect(eventScore).toBeGreaterThan(baseScore);
     });
 
     it('should increase score for recent frames', async () => {
@@ -461,10 +472,15 @@ describe('Garbage Collection', () => {
         frameId: 'recent-frame',
         createdAt: nowSec - 3600, // 1 hour ago
       });
+      insertFrame({
+        frameId: 'old-frame-compare',
+        createdAt: daysAgo(30),
+      });
 
-      const score = adapter.computeImportanceScore('recent-frame');
-      // Base 0.3 + 0.1 (recency) = 0.4
-      expect(score).toBe(0.4);
+      const recentScore = adapter.computeImportanceScore('recent-frame');
+      const oldScore = adapter.computeImportanceScore('old-frame-compare');
+      // Recent frames decay less, so score should be higher
+      expect(recentScore).toBeGreaterThan(oldScore);
     });
 
     it('should cap score at 1.0', async () => {
@@ -486,8 +502,8 @@ describe('Garbage Collection', () => {
       ).run(nowSec);
 
       const score = adapter.computeImportanceScore('max-frame');
-      // 0.3 + 0.15 (DECISION) + 0.1 (events) + 0.15 (digest) + 0.1 (children) + 0.1 (recency) = 0.9
-      expect(score).toBe(0.9);
+      // All factors + recent → high score, still capped at 1.0
+      expect(score).toBeGreaterThan(0.5);
       expect(score).toBeLessThanOrEqual(1.0);
     });
 
@@ -833,15 +849,15 @@ describe('Garbage Collection', () => {
 
       const updated = adapter.recomputeImportanceScores(100);
 
-      // score-1 should get recomputed (0.3 + 0.15 digest = 0.45, != 0.5 so updated)
-      // score-2 should get recomputed (0.3, != 0.5 so updated)
+      // Both should get recomputed (decay formula produces values != 0.5)
       expect(updated).toBe(2);
 
       const score1 = getImportanceScore('score-1');
-      expect(score1).toBe(0.45);
-
       const score2 = getImportanceScore('score-2');
-      expect(score2).toBe(0.3);
+      // score-1 has digest → higher salience → higher score than score-2
+      expect(score1).toBeGreaterThan(score2);
+      expect(score1).not.toBe(0.5);
+      expect(score2).not.toBe(0.5);
     });
   });
 });