squish-memory 1.1.5 → 1.2.0

package/core/runtime/trust-report.ts

@@ -0,0 +1,195 @@
+export interface CurrentProjectSummary {
+  id: string;
+  name: string;
+  path: string;
+  resolution: 'explicit' | 'inferred' | 'auto-created' | 'legacy-placeholder';
+}
+
+export interface ContextReportInput {
+  currentProject: CurrentProjectSummary;
+  otherProjects: CurrentProjectSummary[];
+  runtime: {
+    sessionSummary: string;
+    activePlaces: string[];
+    signalSummary: {
+      captured: number;
+      suppressed: number;
+      sessionOnly: number;
+      durable: number;
+      durableWithRaw: number;
+    };
+    graphSummary: string;
+  };
+  durableMemories: Array<{
+    id: string;
+    type: string;
+    content: string;
+    place?: string | null;
+  }>;
+  beliefs?: Array<{
+    type: string;
+    statement: string;
+    status: string;
+  }>;
+  nextStep: string | null;
+}
+
+export interface HealthReportInput {
+  severity: 'ok' | 'degraded' | 'broken';
+  currentProject: string;
+  checks: Array<{ name: string; status: 'ok' | 'degraded' | 'broken'; detail: string }>;
+  diagnostics?: Array<{ name: string; status: 'ok' | 'degraded' | 'broken'; detail: string; fix?: string }>;
+  nextStep: string | null;
+}
+
+export interface StatsReportInput {
+  currentProject: string;
+  totals: { memories: number; durable: number; sessionLocal: number };
+  signal: {
+    captured: number;
+    suppressed: number;
+    sessionOnly: number;
+    durable: number;
+    durableWithRaw: number;
+    tokensSaved: number;
+    placeRouted: number;
+    graphEnriched: number;
+  };
+  places: { active: number; named: string[] };
+  graph: { status: string; enrichments: number };
+  wakeUp: string;
+  signalNote?: string | null;
+}
+
+export interface InspectReportInput {
+  id: string;
+  classification: string;
+  storageReason: string;
+  durability: 'session-only' | 'durable';
+  place?: string | null;
+  placeType?: string | null;
+  graphStatus?: string | null;
+  rawFallback?: string | null;
+  wakeUpPriority?: string | null;
+  metadataAvailability?: string | null;
+  beliefs?: Array<{
+    id: string;
+    type: string;
+    statement: string;
+    status: string;
+    confidence: number;
+  }>;
+}
+
+export function formatContextReport(input: ContextReportInput): string {
+  const lines = [
+    'Current project',
+    `- ${input.currentProject.name} (${input.currentProject.path})`,
+    `- resolution: ${input.currentProject.resolution}`,
+    '',
+    'Runtime state',
+    `- session working set: ${input.runtime.sessionSummary || 'none'}`,
+    `- active places: ${input.runtime.activePlaces.join(', ') || 'none'}`,
+    `- signals: captured ${input.runtime.signalSummary.captured}, suppressed ${input.runtime.signalSummary.suppressed}, session-only ${input.runtime.signalSummary.sessionOnly}, durable ${input.runtime.signalSummary.durable}, durable+raw ${input.runtime.signalSummary.durableWithRaw}`,
+    `- graph: ${input.runtime.graphSummary}`,
+    '',
+    'Recent durable memories',
+  ];
+
+  if (input.durableMemories.length === 0) {
+    lines.push('- none yet');
+  } else {
+    for (const memory of input.durableMemories) {
+      lines.push(`- [${memory.type}] ${memory.content}${memory.place ? ` @ ${memory.place}` : ''}`);
+    }
+  }
+
+  if (input.otherProjects.length > 0) {
+    lines.push('', 'Other projects');
+    for (const project of input.otherProjects) {
+      lines.push(`- ${project.name} (${project.path}) [${project.resolution}]`);
+    }
+  }
+
+  if (input.beliefs && input.beliefs.length > 0) {
+    lines.push('', 'Derived beliefs');
+    for (const belief of input.beliefs) {
+      lines.push(`- [${belief.type}] ${belief.statement} (${belief.status})`);
+    }
+  }
+
+  if (input.nextStep) {
+    lines.push('', `Next step: ${input.nextStep}`);
+  }
+
+  return lines.join('\n');
+}
+
+export function formatHealthReport(input: HealthReportInput): string {
+  const lines = [
+    `Status: ${input.severity}`,
+    `Current project: ${input.currentProject}`,
+    '',
+    'Subsystems',
+    ...input.checks.map((check) => `- ${check.name}: ${check.status} (${check.detail})`),
+  ];
+  if (input.diagnostics && input.diagnostics.length > 0) {
+    lines.push('', 'Diagnostics');
+    for (const diagnostic of input.diagnostics) {
+      lines.push(`- ${diagnostic.name}: ${diagnostic.status} (${diagnostic.detail})`);
+      if (diagnostic.fix) {
+        lines.push(`  fix: ${diagnostic.fix}`);
+      }
+    }
+  }
+  if (input.nextStep) lines.push('', `Next step: ${input.nextStep}`);
+  return lines.join('\n');
+}
+
+export function formatStatsReport(input: StatsReportInput): string {
+  const lines = [
+    `Current project: ${input.currentProject}`,
+    `Memory totals: ${input.totals.memories} total, ${input.totals.durable} durable, ${input.totals.sessionLocal} session-local`,
+    '',
+    'Capture-era signals',
+    `- captured: ${input.signal.captured}`,
+    `- suppressed: ${input.signal.suppressed}`,
+    `- session-only: ${input.signal.sessionOnly}`,
+    `- signal-tracked durable: ${input.signal.durable}`,
+    `- signal-tracked durable+raw: ${input.signal.durableWithRaw}`,
+    `- token savings: ${input.signal.tokensSaved}`,
+    `- place routed: ${input.signal.placeRouted}`,
+    `- graph enriched: ${input.signal.graphEnriched}`,
+    '',
+    `Places: ${input.places.active} active (${input.places.named.join(', ') || 'none'})`,
+    `Graph: ${input.graph.status}; ${input.graph.enrichments} enrichments`,
+    `Wake-up: ${input.wakeUp}`,
+  ];
+  if (input.signalNote) {
+    lines.push(`Signal note: ${input.signalNote}`);
+  }
+  return lines.join('\n');
+}
+
+export function formatInspectReport(input: InspectReportInput): string {
+  const lines = [
+    `Memory ${input.id}`,
+    `Classification: ${input.classification}`,
+    `Storage reason: ${input.storageReason}`,
+    `Durability: ${input.durability}`,
+    `Place: ${input.place ?? 'none'}${input.placeType ? ` (${input.placeType})` : ''}`,
+    `Graph: ${input.graphStatus ?? 'none'}`,
+    `Raw fallback: ${input.rawFallback ?? 'none'}`,
+    `Wake-up priority: ${input.wakeUpPriority ?? 'n/a'}`,
+  ];
+  if (input.metadataAvailability) {
+    lines.push(`Metadata: ${input.metadataAvailability}`);
+  }
+  if (input.beliefs && input.beliefs.length > 0) {
+    lines.push('Beliefs:');
+    for (const belief of input.beliefs) {
+      lines.push(`- [${belief.type}] ${belief.statement} (${belief.status}, c=${belief.confidence.toFixed(2)})`);
+    }
+  }
+  return lines.join('\n');
+}

package/core/runtime/trust-state.ts

@@ -0,0 +1,360 @@
+import { getDbClient } from '../lib/db-client.js';
+import { getRecent } from '../memory/memories.js';
+import { getMemoryStats } from '../memory/stats.js';
+import { explainMemory } from '../memory/explain.js';
+import { getLatestProjectWorkingSetSummary, getProjectSignalStats } from '../session/working-set.js';
+import { getGraphStats } from '../graph/index.js';
+import { getAllProjects, getProjectByPath, ensureProject, type ProjectRecord } from '../projects.js';
+import { getProjectPlaces } from '../places/places.js';
+import { getMemoryPlace } from '../places/memory-places.js';
+import { getPlace } from '../places/places.js';
+import { config } from '../../config.js';
+import { getBeliefsForMemory } from '../beliefs/store.js';
+import type {
+  ContextReportInput,
+  CurrentProjectSummary,
+  HealthReportInput,
+  InspectReportInput,
+  StatsReportInput,
+} from './trust-report.js';
+
+export interface TrustProjectScope {
+  currentProject: CurrentProjectSummary;
+  otherProjects: CurrentProjectSummary[];
+  nextStep: string | null;
+}
+
+function isLegacyPlaceholderProject(project: ProjectRecord, currentWorkspacePath?: string): boolean {
+  const normalizedPath = project.path.trim();
+  if (normalizedPath === '.') return true;
+  if (!currentWorkspacePath) return false;
+  return normalizedPath === currentWorkspacePath && String(project.metadata?.source ?? '') === 'mcp';
+}
+
+function filterNormalOtherProjects(projects: ProjectRecord[], currentProjectId: string, currentWorkspacePath?: string) {
+  return projects.filter((candidate) => {
+    if (candidate.id === currentProjectId) return false;
+    return !isLegacyPlaceholderProject(candidate, currentWorkspacePath);
+  });
+}
+
+function inferResolution(
+  project: ProjectRecord,
+  mode: 'explicit' | 'inferred' | 'auto-created',
+): CurrentProjectSummary['resolution'] {
+  if (mode !== 'inferred') return mode;
+  const source = String(project.metadata?.source ?? '');
+  return source === 'mcp' ? 'auto-created' : 'inferred';
+}
+
+function toProjectSummary(
+  project: ProjectRecord,
+  mode: 'explicit' | 'inferred' | 'auto-created',
+): CurrentProjectSummary {
+  return {
+    id: project.id,
+    name: project.name,
+    path: project.path,
+    resolution: inferResolution(project, mode),
+  };
+}
+
+export async function resolveProjectScope(projectPath?: string): Promise<TrustProjectScope> {
+  const projects = await getAllProjects();
+  const explicitPath = projectPath?.trim();
+
+  if (explicitPath) {
+    let project = await getProjectByPath(explicitPath);
+    let resolution: 'explicit' | 'auto-created' = 'explicit';
+    if (!project) {
+      project = await ensureProject(explicitPath);
+      resolution = 'auto-created';
+    }
+    if (!project) {
+      throw new Error(`Unable to resolve project: ${explicitPath}`);
+    }
+
+    return {
+      currentProject: toProjectSummary(project, resolution),
+      otherProjects: filterNormalOtherProjects(projects, project.id, explicitPath)
+        .map((candidate) => toProjectSummary(candidate, 'inferred')),
+      nextStep: null,
+    };
+  }
+
+  const cwd = process.cwd();
+  const cwdProject = await getProjectByPath(cwd);
+  if (cwdProject) {
+    return {
+      currentProject: toProjectSummary(cwdProject, 'inferred'),
+      otherProjects: filterNormalOtherProjects(projects, cwdProject.id, cwd)
+        .map((candidate) => toProjectSummary(candidate, 'inferred')),
+      nextStep: null,
+    };
+  }
+
+  if (projects.length === 1) {
+    return {
+      currentProject: toProjectSummary(projects[0], 'inferred'),
+      otherProjects: [],
+      nextStep: null,
+    };
+  }
+
+  const autoProject = await ensureProject(cwd);
+  if (!autoProject) {
+    throw new Error(`Unable to create project for current workspace: ${cwd}`);
+  }
+
+  const otherProjects = projects
+    .filter((candidate) => candidate.id !== autoProject.id)
+    .filter((candidate) => !isLegacyPlaceholderProject(candidate, cwd))
+    .map((candidate) => toProjectSummary(candidate, 'inferred'));
+
+  return {
+    currentProject: toProjectSummary(autoProject, 'auto-created'),
+    otherProjects,
+    nextStep:
+      otherProjects.length > 0
+        ? 'Pass --project with the intended workspace path if this is not the project you meant.'
+        : null,
+  };
+}
+
+async function getMemoryPlaceName(memoryId: string): Promise<string | null> {
+  const placeId = await getMemoryPlace(memoryId);
+  if (!placeId) return null;
+  const place = await getPlace(placeId);
+  return place?.name ?? null;
+}
+
+export async function buildContextState(projectPath?: string, limit: number = 10): Promise<ContextReportInput> {
+  const scope = await resolveProjectScope(projectPath);
+  const projectPathResolved = scope.currentProject.path;
+  const [sessionSummary, signalSummary, graphStats, memories] = await Promise.all([
+    getLatestProjectWorkingSetSummary(projectPathResolved),
+    getProjectSignalStats(projectPathResolved),
+    getGraphStats(projectPathResolved),
+    getRecent(projectPathResolved, limit),
+  ]);
+
+  const project = await getProjectByPath(projectPathResolved);
+  const places = project ? await getProjectPlaces(project.id) : [];
+  const activePlaces = places.filter((place) => place.memoryCount > 0).map((place) => place.name);
+
+  const durableMemories = await Promise.all(
+    memories.map(async (memory) => ({
+      id: memory.id,
+      type: memory.type,
+      content: memory.content,
+      place: await getMemoryPlaceName(memory.id),
+    })),
+  );
+  const beliefRows = await Promise.all(memories.map((memory) => getBeliefsForMemory(memory.id)));
+  const beliefs = beliefRows.flat().slice(0, 6).map((belief) => ({
+    type: belief.type,
+    statement: belief.statement,
+    status: belief.status,
+  }));
+
+  return {
+    currentProject: scope.currentProject,
+    otherProjects: scope.otherProjects,
+    runtime: {
+      sessionSummary,
+      activePlaces,
+      signalSummary: {
+        captured: signalSummary.captured,
+        suppressed: signalSummary.suppressed,
+        sessionOnly: signalSummary.sessionOnly,
+        durable: signalSummary.durable,
+        durableWithRaw: signalSummary.durableWithRaw,
+      },
+      graphSummary:
+        graphStats.entityCount > 0 || graphStats.relationCount > 0
+          ? `enabled; ${graphStats.entityCount} entities, ${graphStats.relationCount} relations`
+          : 'enabled; no graph enrichments yet',
+    },
+    durableMemories,
+    beliefs,
+    nextStep: scope.nextStep,
+  };
+}
+
+export async function buildStatsState(projectPath?: string): Promise<StatsReportInput> {
+  const scope = await resolveProjectScope(projectPath);
+  const projectPathResolved = scope.currentProject.path;
+  const [stats, graphStats, sessionSummary] = await Promise.all([
+    getMemoryStats(projectPathResolved),
+    getGraphStats(projectPathResolved),
+    getLatestProjectWorkingSetSummary(projectPathResolved),
+  ]);
+
+  const project = await getProjectByPath(projectPathResolved);
+  const places = project ? await getProjectPlaces(project.id) : [];
+
+  return {
+    currentProject: `${scope.currentProject.name} (${scope.currentProject.path})`,
+    totals: {
+      memories: stats.totalMemories,
+      durable: Math.max(
+        stats.totalMemories,
+        (stats.signal?.durable ?? 0) + (stats.signal?.durableWithRaw ?? 0),
+      ),
+      sessionLocal: stats.signal?.sessionOnly ?? 0,
+    },
+    signal: {
+      captured: stats.signal?.captured ?? 0,
+      suppressed: stats.signal?.suppressed ?? 0,
+      sessionOnly: stats.signal?.sessionOnly ?? 0,
+      durable: stats.signal?.durable ?? 0,
+      durableWithRaw: stats.signal?.durableWithRaw ?? 0,
+      tokensSaved: stats.signal?.tokensSaved ?? 0,
+      placeRouted: stats.signal?.placeRouted ?? 0,
+      graphEnriched: stats.signal?.graphEnriched ?? 0,
+    },
+    places: {
+      active: places.filter((place) => place.memoryCount > 0).length,
+      named: places.filter((place) => place.memoryCount > 0).map((place) => place.name),
+    },
+    graph: {
+      status:
+        graphStats.entityCount > 0 || graphStats.relationCount > 0 ? 'enabled' : 'enabled (idle)',
+      enrichments: stats.signal?.graphEnriched ?? 0,
+    },
+    wakeUp: sessionSummary || 'No working set yet',
+    signalNote:
+      stats.totalMemories > 0 && (stats.signal?.captured ?? 0) === 0
+        ? 'Signal counts cover capture-era writes only. Legacy durable memories may exist without signal telemetry.'
+        : 'Signal counts cover capture-era writes only.',
+  };
+}
+
+export async function buildHealthState(projectPath?: string): Promise<HealthReportInput> {
+  const scope = await resolveProjectScope(projectPath);
+  const checks: HealthReportInput['checks'] = [];
+  let severity: HealthReportInput['severity'] = 'ok';
+  let nextStep: string | null = scope.nextStep;
+
+  try {
+    await getDbClient();
+    checks.push({ name: 'database', status: 'ok', detail: 'Database connection succeeded.' });
+  } catch (error: any) {
+    severity = 'broken';
+    nextStep = 'Fix database initialization before relying on memory reads or writes.';
+    checks.push({
+      name: 'database',
+      status: 'broken',
+      detail: error?.message ?? 'Database initialization failed.',
+    });
+  }
+
+  checks.push({
+    name: 'project resolution',
+    status: 'ok',
+    detail: `${scope.currentProject.name} at ${scope.currentProject.path} (${scope.currentProject.resolution})`,
+  });
+
+  try {
+    await getRecent(scope.currentProject.path, 1);
+    checks.push({ name: 'memory write path', status: 'ok', detail: 'Memory store is readable for this project.' });
+  } catch (error: any) {
+    severity = severity === 'broken' ? 'broken' : 'degraded';
+    nextStep = nextStep ?? 'Run `squish doctor` to repair local storage before writing memories.';
+    checks.push({
+      name: 'memory write path',
+      status: 'degraded',
+      detail: error?.message ?? 'Memory store could not be read.',
+    });
+  }
+
+  try {
+    const sessionSummary = await getLatestProjectWorkingSetSummary(scope.currentProject.path);
+    checks.push({
+      name: 'session working set',
+      status: sessionSummary ? 'ok' : 'degraded',
+      detail: sessionSummary || 'No compact working set has been captured yet.',
+    });
+    if (!sessionSummary && severity === 'ok') {
+      severity = 'degraded';
+      nextStep = nextStep ?? 'Run a normal session or memory write so Squish can build a working-set wake-up summary.';
+    }
+  } catch (error: any) {
+    severity = severity === 'broken' ? 'broken' : 'degraded';
+    checks.push({
+      name: 'session working set',
+      status: 'degraded',
+      detail: error?.message ?? 'Working-set state could not be loaded.',
+    });
+  }
+
+  const project = await getProjectByPath(scope.currentProject.path);
+  const places = project ? await getProjectPlaces(project.id) : [];
+  const activePlaces = places.filter((place) => place.memoryCount > 0);
+  checks.push({
+    name: 'places',
+    status: activePlaces.length > 0 ? 'ok' : 'degraded',
+    detail:
+      activePlaces.length > 0
+        ? `${activePlaces.length} active places: ${activePlaces.map((place) => place.name).join(', ')}`
+        : 'No populated places yet.',
+  });
+  if (activePlaces.length === 0 && severity === 'ok') {
+    severity = 'degraded';
+    nextStep = nextStep ?? 'Store or recall project memories to populate place routing.';
+  }
+
+  const graphStats = await getGraphStats(scope.currentProject.path);
+  checks.push({
+    name: 'graph',
+    status: graphStats.entityCount > 0 || graphStats.relationCount > 0 ? 'ok' : 'degraded',
+    detail:
+      graphStats.entityCount > 0 || graphStats.relationCount > 0
+        ? `${graphStats.entityCount} entities and ${graphStats.relationCount} relations available.`
+        : 'Graph is enabled but has no extracted entities yet.',
+  });
+  if (graphStats.entityCount === 0 && graphStats.relationCount === 0 && severity === 'ok') {
+    severity = 'degraded';
+    nextStep = nextStep ?? 'Write or recall durable memories so graph enrichment has material to process.';
+  }
+
+  checks.push({
+    name: 'mode',
+    status: 'ok',
+    detail: `${config.isManagedMode ? 'managed' : 'local'} mode; embeddings ${config.embeddingsProvider}`,
+  });
+
+  return {
+    severity,
+    currentProject: `${scope.currentProject.name} (${scope.currentProject.path})`,
+    checks,
+    nextStep,
+  };
+}
+
+export async function buildInspectState(id: string): Promise<InspectReportInput | null> {
+  const inspection = await explainMemory(id);
+  if (!inspection) return null;
+
+  return {
+    id: inspection.id,
+    classification: inspection.classification,
+    storageReason: inspection.reasons.join('; ') || 'Stored as durable memory.',
+    durability: inspection.classification === 'session-only' ? 'session-only' : 'durable',
+    place: inspection.place ?? null,
+    placeType: inspection.placeType ?? null,
+    graphStatus: inspection.graphStatus ?? null,
+    rawFallback: inspection.rawFallbackSnapshotId ?? null,
+    wakeUpPriority: inspection.nuanceSuppressed ? 'high' : 'normal',
+    metadataAvailability: inspection.legacyMetadata
+      ? 'Legacy durable record; signal-era metadata is unavailable.'
+      : 'Signal metadata available.',
+    beliefs: (inspection.beliefs ?? []).map((belief) => ({
+      id: belief.id,
+      type: belief.type,
+      statement: belief.statement,
+      status: belief.status,
+      confidence: belief.confidence,
+    })),
+  };
+}