claude-memory-layer 1.0.11 → 1.0.13

package/src/ui/app.js

@@ -11,6 +11,7 @@ const state = {
   sharedStats: null,
   mostAccessed: null,
   helpfulness: null,
+  retrievalTraces: null,
   currentLevel: 'L0',
   currentSort: 'recent',
   currentView: 'overview',
@@ -235,17 +236,19 @@ async function refreshData() {
   if(btn) btn.classList.add('loading');
 
   try {
-    const [stats, shared, mostAccessed, helpfulness] = await Promise.all([
+    const [stats, shared, mostAccessed, helpfulness, retrievalTraces] = await Promise.all([
       fetch(apiUrl(`${API_BASE}/stats`)).then(r => r.json()).catch(() => null),
       fetch(apiUrl(`${API_BASE}/stats/shared`)).then(r => r.json()).catch(() => null),
       fetch(apiUrl(`${API_BASE}/stats/most-accessed`, { limit: 10 })).then(r => r.json()).catch(() => null),
-      fetch(apiUrl(`${API_BASE}/stats/helpfulness`, { limit: 5 })).then(r => r.json()).catch(() => null)
+      fetch(apiUrl(`${API_BASE}/stats/helpfulness`, { limit: 5 })).then(r => r.json()).catch(() => null),
+      fetch(apiUrl(`${API_BASE}/stats/retrieval-traces`, { limit: 20 })).then(r => r.json()).catch(() => null)
     ]);
 
     state.stats = stats;
     state.sharedStats = shared;
     state.mostAccessed = mostAccessed;
     state.helpfulness = helpfulness;
+    state.retrievalTraces = retrievalTraces;
 
     updateStatsUI();
     updateSharedUI();
@@ -397,6 +400,7 @@ function updateMemoryUsageUI() {
   updateGraduationBars();
   updateHelpfulnessUI();
   updateMostHelpfulList();
+  updateRetrievalTraceUI();
 }
 
 function updateGraduationBars() {
@@ -483,6 +487,69 @@ function updateMostHelpfulList() {
   }).join('');
 }
 
+
+function updateRetrievalTraceUI() {
+  const summaryEl = document.getElementById('retrieval-trace-summary');
+  const listEl = document.getElementById('retrieval-trace-list');
+  if (!summaryEl || !listEl) return;
+
+  const payload = state.retrievalTraces;
+  const stats = payload?.stats;
+  const traces = payload?.traces || [];
+
+  if (!stats || !Number.isFinite(stats.totalQueries) || stats.totalQueries === 0) {
+    summaryEl.innerHTML = '<span style="color:var(--text-muted);">No retrieval traces yet.</span>';
+    listEl.innerHTML = '<div style="padding:12px; text-align:center; color:var(--text-muted); font-size:13px;">No query/context trace data</div>';
+    return;
+  }
+
+  const selectionRate = ((stats.selectionRate || 0) * 100).toFixed(1);
+  summaryEl.innerHTML = `
+    <div style="display:flex; gap:14px; flex-wrap:wrap; font-size:12px;">
+      <span><strong>${formatNumber(stats.totalQueries)}</strong> queries</span>
+      <span><strong>${Number(stats.avgCandidateCount || 0).toFixed(1)}</strong> avg candidates</span>
+      <span><strong>${Number(stats.avgSelectedCount || 0).toFixed(1)}</strong> avg selected</span>
+      <span><strong>${selectionRate}%</strong> selection rate</span>
+    </div>
+  `;
+
+  listEl.innerHTML = traces.slice(0, 8).map((t) => {
+    const ts = t.createdAt ? new Date(t.createdAt).toLocaleString() : '-';
+    const confidence = t.confidence || 'n/a';
+    const selected = Number(t.selectedCount || 0);
+    const candidates = Number(t.candidateCount || 0);
+    const selectedDetails = (t.selectedDetails || []).slice(0, 2);
+    const candidateDetails = (t.candidateDetails || []).slice(0, 3);
+    const selectedIdsHtml = selectedDetails.length > 0
+      ? selectedDetails.map((d) => {
+          const breakdown = `score=${Number(d.score || 0).toFixed(3)} · s=${Number(d.semanticScore || 0).toFixed(3)} · l=${Number(d.lexicalScore || 0).toFixed(3)} · r=${Number(d.recencyScore || 0).toFixed(3)}`;
+          return `<span class="event-type-badge" style="cursor:pointer;" onclick="openDetailModal('${d.eventId}')" title="${escapeHtml(breakdown)}">${escapeHtml((d.eventId || '').slice(0, 8))}...</span>`;
+        }).join(' ')
+      : ((t.selectedEventIds || []).slice(0, 2).map((id) => `<span class="event-type-badge" style="cursor:pointer;" onclick="openDetailModal('${id}')">${escapeHtml((id || '').slice(0, 8))}...</span>`).join(' ') || '-');
+
+    const scoreBreakdownHtml = selectedDetails.length > 0
+      ? selectedDetails.map((d) => `<div style="font-size:10px; color:var(--text-muted);">${escapeHtml((d.eventId || '').slice(0, 8))}... → score ${Number(d.score || 0).toFixed(3)} (s ${Number(d.semanticScore || 0).toFixed(3)}, l ${Number(d.lexicalScore || 0).toFixed(3)}, r ${Number(d.recencyScore || 0).toFixed(3)})</div>`).join('')
+      : '';
+
+    return `
+      <div class="shared-item" style="align-items:flex-start;">
+        <div class="shared-info" style="align-items:flex-start; flex-direction:column; gap:4px;">
+          <span style="font-size:12px; color:var(--text-secondary);"><strong>Q:</strong> ${escapeHtml((t.queryText || '').slice(0, 120))}</span>
+          <span style="font-size:11px; color:var(--text-muted);">${ts} · strategy=${escapeHtml(t.strategy || 'auto')} · conf=${escapeHtml(confidence)}</span>
+          <span style="font-size:11px; color:var(--text-muted);">selected IDs: ${selectedIdsHtml}</span>
+          <span style="font-size:11px; color:var(--text-muted);">candidates: ${candidateDetails.map((d) => `<span class=\"event-type-badge\" style=\"cursor:pointer;\" onclick=\"openDetailModal('${d.eventId}')\">${escapeHtml((d.eventId || '').slice(0, 8))}...</span>`).join(' ') || '-'}</span>
+          ${scoreBreakdownHtml}
+        </div>
+        <div style="display:flex; flex-direction:column; align-items:flex-end; gap:2px; min-width:68px;">
+          <span style="font-size:13px; font-weight:600; color:var(--accent-primary);">${selected}/${candidates}</span>
+          <span style="font-size:10px; color:var(--text-muted);">sel/cand</span>
+        </div>
+      </div>
+    `;
+  }).join('');
+}
+
+
 // --- Charts ---
 
 async function initActivityChart() {

package/src/ui/index.html

@@ -271,6 +271,14 @@
                   <div style="padding:12px; text-align:center; color:var(--text-muted); font-size:13px;">Loading...</div>
                 </div>
               </div>
+
+              <div style="margin-top:20px;">
+                <div class="section-label">Retrieval Trace (1:1)</div>
+                <div id="retrieval-trace-summary" style="padding:8px 0; font-size:13px; color:var(--text-muted);">Loading...</div>
+                <div id="retrieval-trace-list" class="shared-list">
+                  <div style="padding:12px; text-align:center; color:var(--text-muted); font-size:13px;">Loading...</div>
+                </div>
+              </div>
             </div>
 
           </div>

package/tests/bootstrap-organizer.test.ts

@@ -0,0 +1,111 @@
+import { describe, it, expect } from 'vitest';
+import * as fs from 'node:fs/promises';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { execSync } from 'node:child_process';
+import { bootstrapKnowledgeBase } from '../src/services/bootstrap-organizer.js';
+
+async function makeTempRepo(): Promise<string> {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), 'cml-bootstrap-'));
+  execSync('git init', { cwd: root, stdio: 'ignore' });
+  execSync('git config user.email test@example.com', { cwd: root, stdio: 'ignore' });
+  execSync('git config user.name test-bot', { cwd: root, stdio: 'ignore' });
+
+  await fs.mkdir(path.join(root, 'src'), { recursive: true });
+  await fs.mkdir(path.join(root, 'tests'), { recursive: true });
+
+  await fs.writeFile(path.join(root, 'src', 'index.ts'), 'export const hello = () => "world";\n', 'utf8');
+  await fs.writeFile(path.join(root, 'src', 'worker.ts'), 'export const runWorker = () => true;\n', 'utf8');
+  await fs.writeFile(path.join(root, 'tests', 'index.test.ts'), 'describe("x", () => {});\n', 'utf8');
+
+  execSync('git add .', { cwd: root, stdio: 'ignore' });
+  execSync('git commit -m "feat: initial project scaffolding"', { cwd: root, stdio: 'ignore' });
+
+  await fs.writeFile(path.join(root, 'src', 'worker.ts'), 'export const runWorker = () => "ok";\n', 'utf8');
+  execSync('git add src/worker.ts', { cwd: root, stdio: 'ignore' });
+  execSync('git commit -m "refactor: stabilize worker return type"', { cwd: root, stdio: 'ignore' });
+
+  return root;
+}
+
+describe('bootstrapKnowledgeBase', () => {
+  it('generates structured bootstrap outputs with metadata', async () => {
+    const repo = await makeTempRepo();
+    const outDir = path.join(repo, '.generated-kb');
+
+    const result = await bootstrapKnowledgeBase({
+      repoPath: repo,
+      outDir,
+      since: '365 days ago',
+      maxCommits: 50
+    });
+
+    expect(result.fileCount).toBeGreaterThan(0);
+    expect(result.commitCount).toBeGreaterThan(0);
+
+    const expected = [
+      path.join(outDir, 'overview', 'overview.md'),
+      path.join(outDir, 'modules', 'src.md'),
+      path.join(outDir, 'decisions', 'decisions.md'),
+      path.join(outDir, 'timeline', 'timeline.md'),
+      path.join(outDir, 'glossary', 'glossary.md'),
+      path.join(outDir, 'sources', 'manifest.md'),
+      path.join(outDir, 'sources', 'manifest.json')
+    ];
+
+    for (const file of expected) {
+      const stat = await fs.stat(file);
+      expect(stat.isFile()).toBe(true);
+    }
+
+    const overview = await fs.readFile(path.join(outDir, 'overview', 'overview.md'), 'utf8');
+    expect(overview).toContain('deterministicPipeline: true');
+    expect(overview).toContain('- confidence:');
+    expect(overview).toContain('- source:');
+
+    const decisions = await fs.readFile(path.join(outDir, 'decisions', 'decisions.md'), 'utf8');
+    expect(decisions).toContain('commit:');
+
+    const manifestJson = JSON.parse(await fs.readFile(path.join(outDir, 'sources', 'manifest.json'), 'utf8')) as {
+      deterministicPipeline: boolean;
+      outputs: string[];
+    };
+    expect(manifestJson.deterministicPipeline).toBe(true);
+    expect(manifestJson.outputs.length).toBeGreaterThan(0);
+  });
+
+  it('supports incremental bootstrap mode with manifest baseline', async () => {
+    const repo = await makeTempRepo();
+    const outDir = path.join(repo, '.generated-kb');
+
+    await bootstrapKnowledgeBase({
+      repoPath: repo,
+      outDir,
+      since: '365 days ago',
+      maxCommits: 50,
+      incremental: false
+    });
+
+    await fs.writeFile(path.join(repo, 'src', 'index.ts'), 'export const hello = () => "world2";\n', 'utf8');
+    execSync('git add src/index.ts', { cwd: repo, stdio: 'ignore' });
+    execSync('git commit -m "feat: change index output"', { cwd: repo, stdio: 'ignore' });
+
+    const result = await bootstrapKnowledgeBase({
+      repoPath: repo,
+      outDir,
+      maxCommits: 50,
+      incremental: true
+    });
+
+    expect(result.commitCount).toBeGreaterThan(0);
+
+    const manifestJson = JSON.parse(await fs.readFile(path.join(outDir, 'sources', 'manifest.json'), 'utf8')) as {
+      mode: string;
+      options?: { incremental?: boolean };
+      stats?: { modulesGenerated?: number };
+    };
+    expect(manifestJson.mode).toBe('incremental');
+    expect(manifestJson.options?.incremental).toBe(true);
+    expect((manifestJson.stats?.modulesGenerated ?? 0)).toBeGreaterThan(0);
+  });
+});

package/tests/consolidation-worker.test.ts

@@ -0,0 +1,75 @@
+import { describe, it, expect } from 'vitest';
+
+import { ConsolidationWorker } from '../src/core/consolidation-worker.js';
+import type { EndlessModeConfig, MemoryEvent } from '../src/core/types.js';
+
+function makeEvent(id: string, content: string, hoursAgo = 20): MemoryEvent {
+  return {
+    id,
+    eventType: 'user_prompt',
+    sessionId: 's1',
+    timestamp: new Date(Date.now() - hoursAgo * 60 * 60 * 1000),
+    content,
+    canonicalKey: id,
+    dedupeKey: id,
+    metadata: {},
+  };
+}
+
+describe('ConsolidationWorker hierarchy automation', () => {
+  it('creates consolidated memories, promotes rules, and returns cost-quality report', async () => {
+    const events = [
+      makeEvent('e1', 'implement auth bug fix and add tests for token refresh'),
+      makeEvent('e2', 'fix auth error in middleware and update tests'),
+      makeEvent('e3', 'auth feature update with regression test and bug notes'),
+      makeEvent('e4', 'implement retry logic for auth and fix issue with token cache'),
+      makeEvent('e5', 'add integration test for auth flow and bug reproduction'),
+    ];
+
+    const created: Array<{ memoryId: string; summary: string; topics: string[]; sourceEvents: string[]; confidence: number }> = [];
+    const rules: Array<{ rule: string; sourceMemoryIds: string[] }> = [];
+
+    const workingSetStore = {
+      async get() {
+        return { recentEvents: events, lastActivity: new Date(), continuityScore: 0.8 };
+      },
+      async prune(_ids: string[]) {
+        return;
+      }
+    };
+
+    const consolidatedStore = {
+      async isAlreadyConsolidated() { return false; },
+      async create(input: any) {
+        const memoryId = `m-${created.length + 1}`;
+        created.push({ memoryId, ...input });
+        return memoryId;
+      },
+      async get(memoryId: string) {
+        return created.find((m) => m.memoryId === memoryId) || null;
+      },
+      async hasRuleForSourceMemory() { return false; },
+      async createRule(input: any) {
+        rules.push({ rule: input.rule, sourceMemoryIds: input.sourceMemoryIds });
+        return `r-${rules.length}`;
+      }
+    };
+
+    const config: EndlessModeConfig = {
+      enabled: true,
+      workingSet: { maxEvents: 100, timeWindowHours: 24, minRelevanceScore: 0.5 },
+      consolidation: { triggerIntervalMs: 3600000, triggerEventCount: 3, triggerIdleMs: 1000, useLLMSummarization: false },
+      continuity: { minScoreForSeamless: 0.7, topicDecayHours: 48 }
+    };
+
+    const worker = new ConsolidationWorker(workingSetStore as any, consolidatedStore as any, config);
+    const out = await worker.forceRunWithReport();
+
+    expect(out.consolidatedCount).toBeGreaterThan(0);
+    expect(out.promotedRuleCount).toBeGreaterThan(0);
+    expect(out.report.beforeTokenEstimate).toBeGreaterThan(0);
+    expect(out.report.reductionRatio).toBeGreaterThanOrEqual(0);
+    expect(out.report.qualityGuardPassed).toBe(true);
+    expect(rules[0]?.sourceMemoryIds?.length).toBeGreaterThan(0);
+  });
+});

package/tests/ingest-interceptor.test.ts

@@ -0,0 +1,38 @@
+import { describe, it, expect } from 'vitest';
+import { IngestInterceptorRegistry, mergeHierarchicalMetadata } from '../src/core/ingest-interceptor.js';
+
+describe('IngestInterceptorRegistry', () => {
+  it('runs before/after interceptors in staged order', async () => {
+    const registry = new IngestInterceptorRegistry();
+    const stages: string[] = [];
+
+    registry.registerBefore((ctx) => stages.push(`before:${ctx.operation}`));
+    registry.registerAfter((ctx) => stages.push(`after:${ctx.operation}`));
+
+    const event = {
+      eventType: 'user_prompt' as const,
+      sessionId: 's1',
+      timestamp: new Date(),
+      content: 'hello'
+    };
+
+    await registry.run('before', { operation: 'user_prompt', sessionId: 's1', event });
+    await registry.run('after', { operation: 'user_prompt', sessionId: 's1', event });
+
+    expect(stages).toEqual(['before:user_prompt', 'after:user_prompt']);
+  });
+});
+
+describe('mergeHierarchicalMetadata', () => {
+  it('deep merges nested metadata without clobbering siblings', () => {
+    const merged = mergeHierarchicalMetadata(
+      { scope: { project: { id: 'alpha', env: 'dev' } }, ingest: { source: 'hook' } },
+      { scope: { project: { env: 'prod' }, turn: { id: 't1' } } }
+    );
+
+    expect(merged).toEqual({
+      scope: { project: { id: 'alpha', env: 'prod' }, turn: { id: 't1' } },
+      ingest: { source: 'hook' }
+    });
+  });
+});

package/tests/markdown-mirror.test.ts

@@ -0,0 +1,85 @@
+import { describe, it, expect } from 'vitest';
+import * as os from 'os';
+import * as path from 'path';
+import * as fs from 'fs/promises';
+import { randomUUID } from 'crypto';
+import { buildMirrorPath, MarkdownMirror } from '../src/core/markdown-mirror.js';
+import { SQLiteEventStore } from '../src/core/sqlite-event-store.js';
+
+describe('markdown mirror', () => {
+  it('builds sanitized path with defaults', () => {
+    const event = {
+      id: randomUUID(),
+      eventType: 'user_prompt' as const,
+      sessionId: 's1',
+      timestamp: new Date('2026-02-24T00:49:00.000Z'),
+      content: 'hello',
+      canonicalKey: 'k',
+      dedupeKey: 'd',
+      metadata: {
+        namespace: 'Team ../Prod',
+        categoryPath: ['Ops & Alerts', 'Night Shift']
+      }
+    };
+
+    const out = buildMirrorPath('/tmp/root', event);
+    expect(out).toContain(path.join('memory', 'team-prod', 'ops-alerts', 'night-shift', '2026-02-24.md'));
+  });
+
+  it('appends without overwriting existing content', async () => {
+    const root = await fs.mkdtemp(path.join(os.tmpdir(), 'cml-md-mirror-'));
+    try {
+      const file = path.join(root, 'memory', 'default', 'session_summary', '2026-02-24.md');
+      await fs.mkdir(path.dirname(file), { recursive: true });
+      await fs.writeFile(file, 'PREEXISTING\n', 'utf8');
+
+      const mirror = new MarkdownMirror(root);
+      await mirror.append({
+        id: randomUUID(),
+        eventType: 'session_summary',
+        sessionId: 's2',
+        timestamp: new Date('2026-02-24T11:00:00.000Z'),
+        content: 'summary line',
+        canonicalKey: 'k2',
+        dedupeKey: 'd2',
+        metadata: {}
+      });
+
+      const content = await fs.readFile(file, 'utf8');
+      expect(content.startsWith('PREEXISTING\n')).toBe(true);
+      expect(content).toContain('summary line');
+    } finally {
+      await fs.rm(root, { recursive: true, force: true });
+    }
+  });
+
+  it('is wired to sqlite append flow', async () => {
+    const root = await fs.mkdtemp(path.join(os.tmpdir(), 'cml-md-flow-'));
+    try {
+      const store = new SQLiteEventStore(path.join(root, 'events.sqlite'), {
+        markdownMirrorRoot: root
+      });
+      const ts = new Date('2026-02-24T12:00:00.000Z');
+      const result = await store.append({
+        eventType: 'agent_response',
+        sessionId: 'sess-flow',
+        timestamp: ts,
+        content: 'flow content',
+        metadata: { namespace: 'app', category: 'responses' }
+      });
+
+      expect(result.success).toBe(true);
+
+      // mirror append is async fire-and-forget; allow small delay
+      await new Promise((r) => setTimeout(r, 50));
+
+      const file = path.join(root, 'memory', 'app', 'responses', '2026-02-24.md');
+      const content = await fs.readFile(file, 'utf8');
+      expect(content).toContain('flow content');
+
+      await store.close();
+    } finally {
+      await fs.rm(root, { recursive: true, force: true });
+    }
+  });
+});

package/tests/md-mirror.test.ts

@@ -0,0 +1,50 @@
+import { describe, it, expect } from 'vitest';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import * as fs from 'node:fs';
+import { buildMirrorPath, MarkdownMirror } from '../src/core/md-mirror.js';
+import type { MemoryEventInput } from '../src/core/types.js';
+
+function makeEvent(): MemoryEventInput {
+  return {
+    eventType: 'user_prompt',
+    sessionId: 'agent:main:test',
+    timestamp: new Date('2026-02-24T01:00:00.000Z'),
+    content: '아침 브리핑 포맷 기억해줘',
+    metadata: {
+      namespace: 'Briefing',
+      categoryPath: ['Preferences', 'Morning']
+    }
+  };
+}
+
+describe('MarkdownMirror', () => {
+  it('builds sanitized categorized path', () => {
+    const p = buildMirrorPath('/tmp/demo', makeEvent());
+    expect(p).toContain(path.join('memory', 'briefing', 'preferences', 'morning', '2026-02-24.md'));
+  });
+
+  it('uses uncategorized when category is missing', () => {
+    const ev = { ...makeEvent(), metadata: { namespace: 'Briefing' } };
+    const p = buildMirrorPath('/tmp/demo', ev);
+    expect(p).toContain(path.join('memory', 'briefing', 'uncategorized', '2026-02-24.md'));
+  });
+
+  it('appends without overwrite', async () => {
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'cl-md-mirror-'));
+    const mirror = new MarkdownMirror(tmp);
+    const ev = makeEvent();
+
+    await mirror.append(ev, 'e1');
+    await mirror.append({ ...ev, content: '두번째 기록' }, 'e2');
+
+    const out = buildMirrorPath(tmp, ev);
+    const text = fs.readFileSync(out, 'utf8');
+    expect(text).toContain('e1');
+    expect(text).toContain('e2');
+    expect(text).toContain('두번째 기록');
+
+    const index = fs.readFileSync(path.join(tmp, 'memory', '_index.md'), 'utf8');
+    expect(index).toContain('memory/briefing/preferences/morning/2026-02-24.md');
+  });
+});