claude-memory-layer 1.0.26 → 1.0.28

package/src/core/model/memory-fact.ts

@@ -0,0 +1,30 @@
+import { z } from 'zod';
+
+export const MemoryFactTypeSchema = z.enum([
+  'decision',
+  'constraint',
+  'task_state',
+  'tool_observation',
+  'preference',
+  'code_context',
+  'summary_fact'
+]);
+export type MemoryFactType = z.infer<typeof MemoryFactTypeSchema>;
+
+export const MemoryFactSchema = z.object({
+  factId: z.string(),
+  projectHash: z.string(),
+  factType: MemoryFactTypeSchema,
+  text: z.string(),
+  derivedFromEventIds: z.array(z.string()).default([]),
+  sourceKind: z.enum(['prompt', 'assistant', 'tool', 'import']),
+  confidence: z.number().min(0).max(1),
+  importance: z.number().min(0).max(1).default(0.5),
+  tags: z.array(z.string()).default([]),
+  entityRefs: z.array(z.string()).optional(),
+  fileRefs: z.array(z.string()).optional(),
+  symbolRefs: z.array(z.string()).optional(),
+  createdAt: z.string(),
+  updatedAt: z.string()
+});
+export type MemoryFact = z.infer<typeof MemoryFactSchema>;

package/src/core/model/memory-rule.ts

@@ -0,0 +1,14 @@
+import { z } from 'zod';
+
+export const MemoryRuleSchema = z.object({
+  ruleId: z.string(),
+  projectHash: z.string().optional(),
+  scope: z.enum(['project', 'shared']),
+  ruleType: z.enum(['preference', 'workflow', 'convention', 'constraint']),
+  text: z.string(),
+  confidence: z.number().min(0).max(1),
+  evidenceIds: z.array(z.string()).default([]),
+  createdAt: z.string(),
+  updatedAt: z.string()
+});
+export type MemoryRule = z.infer<typeof MemoryRuleSchema>;

package/src/core/model/memory-summary.ts

@@ -0,0 +1,21 @@
+import { z } from 'zod';
+
+export const MemorySummaryTypeSchema = z.enum([
+  'turn',
+  'session',
+  'project',
+  'continuity',
+  'timeline_digest'
+]);
+export type MemorySummaryType = z.infer<typeof MemorySummaryTypeSchema>;
+
+export const MemorySummarySchema = z.object({
+  summaryId: z.string(),
+  summaryType: MemorySummaryTypeSchema,
+  refId: z.string(),
+  text: z.string(),
+  sourceEventIds: z.array(z.string()).default([]),
+  sourceFactIds: z.array(z.string()).default([]),
+  createdAt: z.string()
+});
+export type MemorySummary = z.infer<typeof MemorySummarySchema>;

package/src/core/model/raw-event.ts

@@ -0,0 +1,28 @@
+import { z } from 'zod';
+
+export const RawEventTypeSchema = z.enum([
+  'user_prompt',
+  'assistant_response',
+  'tool_output',
+  'session_marker',
+  'imported_turn'
+]);
+export type RawEventType = z.infer<typeof RawEventTypeSchema>;
+
+export const PrivacyLevelSchema = z.enum(['public', 'internal', 'private', 'masked']);
+export type PrivacyLevel = z.infer<typeof PrivacyLevelSchema>;
+
+export const RawEventSchema = z.object({
+  eventId: z.string(),
+  projectHash: z.string(),
+  sessionId: z.string(),
+  turnId: z.string().optional(),
+  eventType: RawEventTypeSchema,
+  content: z.string(),
+  toolName: z.string().optional(),
+  sourceRef: z.string().optional(),
+  metadata: z.record(z.unknown()).default({}),
+  privacyLevel: PrivacyLevelSchema.default('internal'),
+  createdAt: z.string()
+});
+export type RawEvent = z.infer<typeof RawEventSchema>;

package/src/core/model/retrieval-result.ts

@@ -0,0 +1,35 @@
+import { z } from 'zod';
+
+export const RetrievalReasonSchema = z.enum([
+  'semantic_match',
+  'keyword_match',
+  'recent_relevance',
+  'continuity_link',
+  'entity_overlap',
+  'tool_followup',
+  'summary_fallback'
+]);
+export type RetrievalReason = z.infer<typeof RetrievalReasonSchema>;
+
+export const RetrievalResultTypeSchema = z.enum([
+  'fact',
+  'summary',
+  'tool_evidence',
+  'rule',
+  'source'
+]);
+export type RetrievalResultType = z.infer<typeof RetrievalResultTypeSchema>;
+
+export const RetrievalResultEnvelopeSchema = z.object({
+  id: z.string(),
+  resultType: RetrievalResultTypeSchema,
+  title: z.string().optional(),
+  snippet: z.string(),
+  score: z.number().min(0).max(1),
+  reasons: z.array(RetrievalReasonSchema).default([]),
+  sourceRef: z.string().optional(),
+  sessionId: z.string().optional(),
+  turnId: z.string().optional(),
+  metadata: z.record(z.unknown()).optional()
+});
+export type RetrievalResultEnvelope = z.infer<typeof RetrievalResultEnvelopeSchema>;

package/src/core/privacy/filter.ts

@@ -20,6 +20,10 @@ export interface FilterResult {
 
 // Sensitive data patterns
 const SENSITIVE_PATTERNS = [
+  // Credential-bearing URLs/connection strings with userinfo before the host.
+  // Redact the whole URI so usernames, credentials, hosts, paths, and query
+  // params do not leak either.
+  /\b[a-z][a-z0-9+.-]*:\/\/[^\s'"`<>/@]+@[^\s'"`<>]+/gi,
   /password\s*[:=]\s*['"]?[^\s'"]+/gi,
   /api[_-]?key\s*[:=]\s*['"]?[^\s'"]+/gi,
   /secret\s*[:=]\s*['"]?[^\s'"]+/gi,
@@ -32,6 +36,15 @@ const SENSITIVE_PATTERNS = [
   /sk-[a-zA-Z0-9]{48}/g,   // OpenAI API Key
 ];
 
+function maskSensitiveString(value: string): string {
+  let filtered = value;
+  for (const pattern of SENSITIVE_PATTERNS) {
+    pattern.lastIndex = 0;
+    filtered = filtered.replace(pattern, '[REDACTED]');
+  }
+  return filtered;
+}
+
 /**
  * Apply privacy filter to content
  */
@@ -118,20 +131,18 @@ export function maskSensitiveInput(
       result[key] = '[REDACTED]';
     } else if (typeof value === 'string') {
       // Apply pattern filtering to string values
-      let filtered = value;
-      for (const pattern of SENSITIVE_PATTERNS) {
-        pattern.lastIndex = 0;
-        filtered = filtered.replace(pattern, '[REDACTED]');
-      }
-      result[key] = filtered;
+      result[key] = maskSensitiveString(value);
     } else if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
       result[key] = maskSensitiveInput(value as Record<string, unknown>);
     } else if (Array.isArray(value)) {
-      result[key] = value.map(item =>
-        typeof item === 'object' && item !== null
+      result[key] = value.map(item => {
+        if (typeof item === 'string') {
+          return isSensitiveKey ? '[REDACTED]' : maskSensitiveString(item);
+        }
+        return typeof item === 'object' && item !== null
           ? maskSensitiveInput(item as Record<string, unknown>)
-          : item
-      );
+          : item;
+      });
     } else {
       result[key] = value;
     }

package/src/core/product-validation-matrix.ts

@@ -0,0 +1,314 @@
+/**
+ * Product-level validation matrix for claude-memory-layer.
+ *
+ * This module is intentionally data-first so CLI/reporting/docs can reuse the
+ * same surface -> requirement -> evidence map that tests assert stays covered.
+ */
+
+export type ProductValidationArea = 'claude' | 'codex' | 'hermes' | 'mcp' | 'cli' | 'safety';
+export type ProductValidationStatus = 'ready' | 'covered' | 'partial' | 'planned';
+export type ProductValidationEvidenceKind = 'test' | 'source' | 'command' | 'doc';
+
+export interface ProductValidationEvidence {
+  kind: ProductValidationEvidenceKind;
+  ref: string;
+  note: string;
+}
+
+export interface ProductValidationSurface {
+  id: string;
+  area: ProductValidationArea;
+  title: string;
+  status: ProductValidationStatus;
+  requirements: string[];
+  evidence: ProductValidationEvidence[];
+}
+
+export interface ProductValidationMatrixSummary {
+  totalSurfaces: number;
+  requirementCount: number;
+  evidenceCount: number;
+  surfacesByArea: Record<ProductValidationArea, number>;
+  statusCounts: Record<ProductValidationStatus, number>;
+}
+
+export const productValidationMatrix: readonly ProductValidationSurface[] = [
+  {
+    id: 'claude.adapter.import',
+    area: 'claude',
+    title: 'Claude adapter import',
+    status: 'covered',
+    requirements: [
+      'Import Claude Code JSONL transcripts without storing tool-result noise as user prompts.',
+      'Preserve session/project mapping and turn grouping for retrieval continuity.'
+    ],
+    evidence: [
+      { kind: 'test', ref: 'tests/core/session-history-importer-filter.test.ts', note: 'Filters local-command artifacts and keeps substantive prompts.' },
+      { kind: 'source', ref: 'src/services/session-history-importer.ts', note: 'Claude JSONL import pipeline and project/session registration.' }
+    ]
+  },
+  {
+    id: 'claude.adapter.search',
+    area: 'claude',
+    title: 'Claude adapter search',
+    status: 'covered',
+    requirements: [
+      'Expose semantic memory search with project/session scoping and fast/deep strategies.',
+      'Return plain and disclosure-aware search output without mutating memory.'
+    ],
+    evidence: [
+      { kind: 'test', ref: 'tests/core/retrieval-services.test.ts', note: 'Core retrieval service behavior.' },
+      { kind: 'test', ref: 'tests/apps/cli-disclosure-output.test.ts', note: 'CLI disclosure output formatting.' },
+      { kind: 'source', ref: 'src/apps/cli/index.ts', note: 'search command supports disclosure, scope, and strategy flags.' }
+    ]
+  },
+  {
+    id: 'claude.adapter.disclosure',
+    area: 'claude',
+    title: 'Claude adapter disclosure',
+    status: 'covered',
+    requirements: [
+      'Support progressive search -> expand -> source disclosure flow.',
+      'Render source/citation evidence for retrieved memories.'
+    ],
+    evidence: [
+      { kind: 'test', ref: 'tests/core/retrieval-disclosure-service.test.ts', note: 'Disclosure service search/expand/source flow.' },
+      { kind: 'test', ref: 'tests/apps/ui-disclosure-output.test.ts', note: 'Dashboard disclosure formatting.' },
+      { kind: 'source', ref: 'src/core/engine/retrieval-disclosure-service.ts', note: 'Core disclosure orchestration.' }
+    ]
+  },
+  {
+    id: 'codex.adapter.scan',
+    area: 'codex',
+    title: 'Codex adapter scan',
+    status: 'ready',
+    requirements: [
+      'Read ~/.codex/sessions recursively without writes by default.',
+      'Match sessions to a project via session_meta.payload.cwd when available and summarize all sessions otherwise.',
+      'Count missing cwd, malformed JSONL lines, and unsupported/tool-ish records.'
+    ],
+    evidence: [
+      { kind: 'test', ref: 'tests/core/codex-session-history-importer-validation.test.ts', note: 'Dry-run scan, cwd matching, missing cwd, malformed and unsupported counts.' },
+      { kind: 'source', ref: 'src/services/codex-session-history-importer.ts', note: 'validateCodexSessions and normalizeCodexSessionFile.' }
+    ]
+  },
+  {
+    id: 'codex.adapter.import',
+    area: 'codex',
+    title: 'Codex adapter import',
+    status: 'covered',
+    requirements: [
+      'Import explicit Codex session files/project sessions into memory only through import APIs.',
+      'Expose a user-facing codex import command for project, session, and all-session imports.',
+      'Preserve turn grouping and truncate oversized assistant content before storage.'
+    ],
+    evidence: [
+      { kind: 'test', ref: 'tests/apps/codex-import-runner.test.ts', note: 'Asserts project-scoped, session, and explicit global all-session import routing.' },
+      { kind: 'source', ref: 'src/apps/cli/codex-import-runner.ts', note: 'Safe Codex import command runner with project/default/global storage decisions.' },
+      { kind: 'source', ref: 'src/services/codex-session-history-importer.ts', note: 'CodexSessionHistoryImporter importProject/importAll/importSessionFile.' },
+      { kind: 'doc', ref: 'docs/PRODUCT_VALIDATION_MATRIX.md', note: 'Documents that validation/replay is read-only; mutation remains explicit import-only.' }
+    ]
+  },
+  {
+    id: 'codex.adapter.replay',
+    area: 'codex',
+    title: 'Codex adapter replay',
+    status: 'ready',
+    requirements: [
+      'Normalize response_item message records with user/assistant roles and text/input_text/output_text blocks.',
+      'Handle string content, empty assistant turns, large/truncated content, malformed lines, and tool-ish records robustly.',
+      'Emit aggregate replay counts without transcript content.'
+    ],
+    evidence: [
+      { kind: 'test', ref: 'tests/core/codex-session-history-importer-validation.test.ts', note: 'Realistic fixture replay covers supported and malformed Codex JSONL shapes.' },
+      { kind: 'source', ref: 'src/services/codex-session-history-importer.ts', note: 'normalizeCodexSessionFile parses and counts replay records.' }
+    ]
+  },
+  {
+    id: 'hermes.adapter.scan',
+    area: 'hermes',
+    title: 'Hermes adapter scan',
+    status: 'ready',
+    requirements: [
+      'Read Hermes ~/.hermes/state.db in read-only mode by default.',
+      'Match sessions to a project via Hermes session context/title when available.',
+      'Count unsupported/tool messages, empty assistant messages, missing project context, and truncated content without exposing transcript text.'
+    ],
+    evidence: [
+      { kind: 'test', ref: 'tests/core/hermes-session-history-importer-validation.test.ts', note: 'Dry-run SessionDB fixture covers project matching, unsupported/tool skipping, empty assistant messages, and transcript exclusion.' },
+      { kind: 'source', ref: 'src/services/hermes-session-history-importer.ts', note: 'validateHermesSessions reads SessionDB and emits aggregate replay reports.' }
+    ]
+  },
+  {
+    id: 'hermes.adapter.import',
+    area: 'hermes',
+    title: 'Hermes adapter import',
+    status: 'covered',
+    requirements: [
+      'Import explicit Hermes SessionDB project/session/all selections into memory only through import APIs.',
+      'Default to project-scoped memory for current-project imports and require --all for intentional global imports.',
+      'Skip tool/system records and redact sensitive user/assistant content before storage.'
+    ],
+    evidence: [
+      { kind: 'test', ref: 'tests/core/hermes-session-history-importer-validation.test.ts', note: 'Imports only matched user/assistant turns, redacts secrets, and skips tool messages.' },
+      { kind: 'test', ref: 'tests/apps/hermes-import-runner.test.ts', note: 'Asserts project-scoped, session, and explicit global all-session import routing.' },
+      { kind: 'source', ref: 'src/apps/cli/hermes-import-runner.ts', note: 'Safe Hermes import command runner with project/default/global storage decisions.' },
+      { kind: 'source', ref: 'src/services/hermes-session-history-importer.ts', note: 'HermesSessionHistoryImporter importProject/importAll/importSession.' }
+    ]
+  },
+  {
+    id: 'hermes.adapter.replay',
+    area: 'hermes',
+    title: 'Hermes adapter replay',
+    status: 'ready',
+    requirements: [
+      'Normalize Hermes SessionDB user/assistant rows into aggregate replay counts.',
+      'Keep Hermes raw transcript source-of-truth in SessionDB and treat CML as explicit derived memory.',
+      'Emit validation reports without transcript content or secrets.'
+    ],
+    evidence: [
+      { kind: 'test', ref: 'tests/core/hermes-session-history-importer-validation.test.ts', note: 'Validation report excludes prompt/response text and synthetic secrets.' },
+      { kind: 'source', ref: 'src/apps/cli/hermes-validation-output.ts', note: 'JSON/Markdown report output helpers for Hermes aggregate replay.' },
+      { kind: 'doc', ref: 'docs/HERMES_MEMORY_INGESTION_ANALYSIS.md', note: 'Documents explicit import first; live sync later if needed.' }
+    ]
+  },
+  {
+    id: 'mcp.context.pack',
+    area: 'mcp',
+    title: 'MCP context pack',
+    status: 'covered',
+    requirements: [
+      'Expose an agent-ready project context pack that combines relevant retrieval results with recent project timeline.',
+      'Support projectPath scoping so Hermes, Codex, and Claude Code can share the same project memory backend.',
+      'Keep output compact and citation-oriented so agents can follow up with source-ref or timeline tools.'
+    ],
+    evidence: [
+      { kind: 'test', ref: 'tests/extensions/mcp-context-tools.test.ts', note: 'Asserts context-pack output, projectPath routing, compact relevant memory citations, and recent timeline inclusion.' },
+      { kind: 'source', ref: 'src/extensions/mcp/handlers.ts', note: 'mem-context-pack handler formats relevant memories plus session summaries.' },
+      { kind: 'source', ref: 'src/extensions/mcp/tools.ts', note: 'MCP tool schema advertises projectPath, topK, recentLimit, and sessionLimit options.' }
+    ]
+  },
+  {
+    id: 'mcp.project.timeline',
+    area: 'mcp',
+    title: 'MCP project timeline',
+    status: 'covered',
+    requirements: [
+      'Summarize recent project memories by session, source agent, event counts, and last safe preview.',
+      'Avoid raw transcript dumps while still giving enough continuity for another agent to resume work.'
+    ],
+    evidence: [
+      { kind: 'test', ref: 'tests/extensions/mcp-context-tools.test.ts', note: 'Asserts session grouping, source-agent metadata, and event type counts.' },
+      { kind: 'source', ref: 'src/extensions/mcp/handlers.ts', note: 'mem-project-timeline groups recent events by session and source.' },
+      { kind: 'source', ref: 'src/extensions/mcp/tools.ts', note: 'MCP tool schema advertises limit/sessionLimit/projectPath options.' }
+    ]
+  },
+  {
+    id: 'mcp.source.ref',
+    area: 'mcp',
+    title: 'MCP source reference',
+    status: 'covered',
+    requirements: [
+      'Resolve event IDs, event: references, and mem citation IDs into source references.',
+      'Return privacy-safe redacted previews and a narrow allowlist of metadata instead of raw transcript content.',
+      'Support projectPath scoping for project-specific memory stores.'
+    ],
+    evidence: [
+      { kind: 'test', ref: 'tests/extensions/mcp-context-tools.test.ts', note: 'Asserts citation lookup, secret redaction, and safe metadata allowlist.' },
+      { kind: 'source', ref: 'src/extensions/mcp/handlers.ts', note: 'mem-source-ref applies privacy filtering and safe metadata selection.' },
+      { kind: 'source', ref: 'src/core/privacy/filter.ts', note: 'Shared privacy filter masks sensitive patterns before output.' }
+    ]
+  },
+  {
+    id: 'cli.api.reporting',
+    area: 'cli',
+    title: 'CLI / API / reporting',
+    status: 'ready',
+    requirements: [
+      'Expose user-facing Codex validation commands with --project, --sessions-dir, --limit, --format, --output, and --dry-run options.',
+      'Expose user-facing Hermes validation commands with --project, --state-db, --limit, --format, --output, and --dry-run options.',
+      'Expose explicit Codex and Hermes import commands with project, session, all-session, limit, force, and no-process-embeddings options.',
+      'Render JSON and Markdown reports with totals, warnings, top projects/sources, and source paths.'
+    ],
+    evidence: [
+      { kind: 'test', ref: 'tests/apps/codex-validation-output.test.ts', note: 'Codex JSON/Markdown report formatting.' },
+      { kind: 'test', ref: 'tests/apps/codex-import-runner.test.ts', note: 'Codex import CLI runner behavior and storage-scope routing.' },
+      { kind: 'test', ref: 'tests/apps/hermes-import-runner.test.ts', note: 'Hermes import CLI runner behavior and storage-scope routing.' },
+      { kind: 'source', ref: 'src/apps/cli/index.ts', note: 'codex and hermes validate/replay/import commands.' },
+      { kind: 'source', ref: 'src/apps/cli/codex-validation-output.ts', note: 'Codex report output helpers.' },
+      { kind: 'source', ref: 'src/apps/cli/hermes-validation-output.ts', note: 'Hermes report output helpers.' },
+      { kind: 'source', ref: 'src/apps/cli/codex-import-runner.ts', note: 'Codex import runner.' },
+      { kind: 'source', ref: 'src/apps/cli/hermes-import-runner.ts', note: 'Hermes import runner.' }
+    ]
+  },
+  {
+    id: 'safety.dryRun',
+    area: 'safety',
+    title: 'Safety / dry-run',
+    status: 'ready',
+    requirements: [
+      'Codex validation/replay is read-only by default and never initializes memory storage or changes Claude settings.',
+      'Reports exclude transcript content and can anonymize project paths for real-data validation artifacts.'
+    ],
+    evidence: [
+      { kind: 'test', ref: 'tests/core/codex-session-history-importer-validation.test.ts', note: 'Asserts dryRun=true, willMutate=false, and no transcript content in reports.' },
+      { kind: 'command', ref: 'claude-memory-layer codex validate --dry-run', note: 'User-facing dry-run validation command.' },
+      { kind: 'doc', ref: 'docs/PRODUCT_VALIDATION_MATRIX.md', note: 'Documents safety expectations and read-only validation scope.' }
+    ]
+  }
+];
+
+function emptyAreaCounts(): Record<ProductValidationArea, number> {
+  return { claude: 0, codex: 0, hermes: 0, mcp: 0, cli: 0, safety: 0 };
+}
+
+function emptyStatusCounts(): Record<ProductValidationStatus, number> {
+  return { ready: 0, covered: 0, partial: 0, planned: 0 };
+}
+
+export function getProductValidationMatrixSummary(
+  matrix: readonly ProductValidationSurface[] = productValidationMatrix
+): ProductValidationMatrixSummary {
+  const summary: ProductValidationMatrixSummary = {
+    totalSurfaces: matrix.length,
+    requirementCount: 0,
+    evidenceCount: 0,
+    surfacesByArea: emptyAreaCounts(),
+    statusCounts: emptyStatusCounts()
+  };
+
+  for (const surface of matrix) {
+    summary.surfacesByArea[surface.area] += 1;
+    summary.statusCounts[surface.status] += 1;
+    summary.requirementCount += surface.requirements.length;
+    summary.evidenceCount += surface.evidence.length;
+  }
+
+  return summary;
+}
+
+export function renderProductValidationMatrixMarkdown(
+  matrix: readonly ProductValidationSurface[] = productValidationMatrix
+): string {
+  const summary = getProductValidationMatrixSummary(matrix);
+  const lines: string[] = [
+    '# Product Validation Matrix',
+    '',
+    `Surfaces: ${summary.totalSurfaces}`,
+    `Requirements: ${summary.requirementCount}`,
+    `Evidence items: ${summary.evidenceCount}`,
+    '',
+    '| Area | Surface | Status | Requirements | Evidence |',
+    '| --- | --- | --- | --- | --- |'
+  ];
+
+  for (const surface of matrix) {
+    const requirements = surface.requirements.map((requirement) => requirement.replace(/\|/g, '\\|')).join('<br>');
+    const evidence = surface.evidence
+      .map((item) => `${item.kind}: ${item.ref}`.replace(/\|/g, '\\|'))
+      .join('<br>');
+    lines.push(`| ${surface.area} | ${surface.title} | ${surface.status} | ${requirements} | ${evidence} |`);
+  }
+
+  return `${lines.join('\n')}\n`;
+}

package/src/core/progressive-retriever.ts

@@ -12,8 +12,7 @@ import type {
   FullDetail,
   ProgressiveSearchResult,
   ProgressiveDisclosureConfig,
-  MemoryEvent,
-  Citation
+  MemoryEvent
 } from './types.js';
 import { generateCitationId } from './citation-generator.js';
 

package/src/core/registry/project-path.ts

@@ -0,0 +1,54 @@
+/**
+ * Project path registry utilities.
+ *
+ * These helpers are intentionally core-level and Claude-agnostic.
+ */
+
+import * as crypto from 'crypto';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+
+/**
+ * Normalize and resolve a project path, handling symlinks when possible.
+ */
+export function normalizeProjectPath(projectPath: string): string {
+  const expanded = projectPath.startsWith('~')
+    ? path.join(os.homedir(), projectPath.slice(1))
+    : projectPath;
+
+  try {
+    return fs.realpathSync(expanded);
+  } catch {
+    return path.resolve(expanded);
+  }
+}
+
+/**
+ * Generate a stable 8-character hash from a normalized project path.
+ */
+export function hashProjectPath(projectPath: string): string {
+  const normalizedPath = normalizeProjectPath(projectPath);
+  return crypto.createHash('sha256')
+    .update(normalizedPath)
+    .digest('hex')
+    .slice(0, 8);
+}
+
+/**
+ * Get the storage path for a project-local memory database.
+ */
+export function getProjectStoragePath(projectPath: string): string {
+  const hash = hashProjectPath(projectPath);
+  return path.join(os.homedir(), '.claude-code', 'memory', 'projects', hash);
+}
+
+/**
+ * Resolve either an explicit project hash or a project path into a storage path.
+ */
+export function resolveProjectStoragePath(projectOrHash: string): string {
+  const isHash = /^[a-f0-9]{8}$/.test(projectOrHash);
+  return isHash
+    ? path.join(os.homedir(), '.claude-code', 'memory', 'projects', projectOrHash)
+    : getProjectStoragePath(projectOrHash);
+}

package/src/core/registry/session-registry.ts

@@ -0,0 +1,69 @@
+/**
+ * Session registry for mapping Claude session IDs to project-local storage.
+ */
+
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { hashProjectPath, normalizeProjectPath } from './project-path.js';
+
+const REGISTRY_PATH = path.join(os.homedir(), '.claude-code', 'memory', 'session-registry.json');
+
+export interface SessionRegistryEntry {
+  projectPath: string;
+  projectHash: string;
+  registeredAt: string;
+}
+
+export interface SessionRegistry {
+  version: number;
+  sessions: Record<string, SessionRegistryEntry>;
+}
+
+export function loadSessionRegistry(): SessionRegistry {
+  try {
+    if (fs.existsSync(REGISTRY_PATH)) {
+      const data = fs.readFileSync(REGISTRY_PATH, 'utf-8');
+      return JSON.parse(data);
+    }
+  } catch (error) {
+    console.error('Failed to load session registry:', error);
+  }
+  return { version: 1, sessions: {} };
+}
+
+function saveSessionRegistry(registry: SessionRegistry): void {
+  const dir = path.dirname(REGISTRY_PATH);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+
+  const tempPath = REGISTRY_PATH + '.tmp';
+  fs.writeFileSync(tempPath, JSON.stringify(registry, null, 2));
+  fs.renameSync(tempPath, REGISTRY_PATH);
+}
+
+export function registerSession(sessionId: string, projectPath: string): void {
+  const registry = loadSessionRegistry();
+
+  registry.sessions[sessionId] = {
+    projectPath: normalizeProjectPath(projectPath),
+    projectHash: hashProjectPath(projectPath),
+    registeredAt: new Date().toISOString()
+  };
+
+  const entries = Object.entries(registry.sessions);
+  if (entries.length > 1000) {
+    const sorted = entries.sort((a, b) =>
+      new Date(b[1].registeredAt).getTime() - new Date(a[1].registeredAt).getTime()
+    );
+    registry.sessions = Object.fromEntries(sorted.slice(0, 1000));
+  }
+
+  saveSessionRegistry(registry);
+}
+
+export function getSessionProject(sessionId: string): SessionRegistryEntry | null {
+  const registry = loadSessionRegistry();
+  return registry.sessions[sessionId] || null;
+}