claude-memory-layer 1.0.27 → 1.0.28

package/src/cli/retrieval-disclosure-output.ts

@@ -0,0 +1,2 @@
+/** Compatibility re-exports for the CLI disclosure formatters. */
+export * from '../apps/cli/retrieval-disclosure-output.js';

package/src/compat/index.ts

@@ -0,0 +1,5 @@
+/**
+ * Compatibility layer for incremental thin-core migration.
+ */
+
+export {};

package/src/core/derive/fact-deriver.ts

@@ -0,0 +1,170 @@
+import { createHash } from 'crypto';
+
+import type { MemoryEvent } from '../types.js';
+import type { MemoryFact, MemoryFactType } from '../model/memory-fact.js';
+
+export interface FactDerivationOptions {
+  /** Fallback project hash when the source event metadata does not carry scope.project.hash. */
+  projectHash?: string;
+  /** Optional current time hook for deterministic tests. */
+  now?: Date;
+}
+
+const DEFAULT_PROJECT_HASH = 'default';
+const MAX_FACT_TEXT_LENGTH = 600;
+
+/**
+ * Create a stable, rebuild-safe fact id for an event-derived fact.
+ *
+ * Format intentionally avoids UUID randomness so derived fact stores can be
+ * dropped and rebuilt without producing duplicate logical facts.
+ */
+export function makeEventDerivedFactId(
+  eventId: string,
+  factType: MemoryFactType,
+  ordinal = 0
+): string {
+  const digest = createHash('sha1')
+    .update(`${eventId}:${factType}:${ordinal}`)
+    .digest('hex')
+    .slice(0, 16);
+
+  return `fact:event:${eventId}:${factType}:${ordinal}:${digest}`;
+}
+
+export class FactDeriver {
+  deriveFromEvent(event: MemoryEvent, options: FactDerivationOptions = {}): MemoryFact[] {
+    const text = this.toFactText(event);
+    if (!text) return [];
+
+    const factType = this.inferFactType(event);
+    const now = (options.now ?? new Date()).toISOString();
+    const metadata = this.asRecord(event.metadata);
+    const projectHash = this.getProjectHash(metadata) ?? options.projectHash ?? DEFAULT_PROJECT_HASH;
+    const tags = this.getTags(metadata);
+
+    return [{
+      factId: makeEventDerivedFactId(event.id, factType),
+      projectHash,
+      factType,
+      text,
+      derivedFromEventIds: [event.id],
+      sourceKind: this.getSourceKind(event),
+      confidence: this.getConfidence(event),
+      importance: this.getImportance(event),
+      tags,
+      ...(this.getFileRefs(metadata).length > 0 ? { fileRefs: this.getFileRefs(metadata) } : {}),
+      createdAt: now,
+      updatedAt: now
+    }];
+  }
+
+  private toFactText(event: MemoryEvent): string | null {
+    const content = event.content.trim().replace(/\s+/g, ' ');
+    if (!content) return null;
+
+    const clipped = content.length > MAX_FACT_TEXT_LENGTH
+      ? `${content.slice(0, MAX_FACT_TEXT_LENGTH - 1)}…`
+      : content;
+
+    switch (event.eventType) {
+      case 'user_prompt':
+        return `User asked: ${clipped}`;
+      case 'agent_response':
+        return `Assistant responded: ${clipped}`;
+      case 'session_summary':
+        return `Session summary: ${clipped}`;
+      case 'tool_observation': {
+        const metadata = this.asRecord(event.metadata);
+        const toolName = typeof metadata.toolName === 'string' ? metadata.toolName : 'unknown_tool';
+        const success = typeof metadata.success === 'boolean'
+          ? metadata.success
+          : undefined;
+        const status = success === undefined ? '' : success ? ' succeeded' : ' failed';
+        return `Tool ${toolName}${status}: ${clipped}`;
+      }
+    }
+  }
+
+  private inferFactType(event: MemoryEvent): MemoryFactType {
+    if (event.eventType === 'tool_observation') return 'tool_observation';
+    if (event.eventType === 'session_summary') return 'summary_fact';
+
+    const content = event.content.toLowerCase();
+    if (/\b(decided|decision|선택|결정)\b/.test(content)) return 'decision';
+    if (/\b(must|should not|constraint|requirement|제약|필수|금지)\b/.test(content)) return 'constraint';
+    if (/\b(todo|task|next|pending|해야|작업|진행)\b/.test(content)) return 'task_state';
+    if (/\b(prefer|preference|선호)\b/.test(content)) return 'preference';
+    if (/\b(src\/|tests\/|\.ts|\.tsx|\.js|\.py|function|class)\b/.test(content)) return 'code_context';
+
+    return 'task_state';
+  }
+
+  private getSourceKind(event: MemoryEvent): MemoryFact['sourceKind'] {
+    switch (event.eventType) {
+      case 'user_prompt':
+        return 'prompt';
+      case 'agent_response':
+      case 'session_summary':
+        return 'assistant';
+      case 'tool_observation':
+        return 'tool';
+    }
+  }
+
+  private getConfidence(event: MemoryEvent): number {
+    switch (event.eventType) {
+      case 'session_summary':
+        return 0.8;
+      case 'tool_observation':
+        return 0.75;
+      case 'agent_response':
+        return 0.7;
+      case 'user_prompt':
+        return 0.65;
+    }
+  }
+
+  private getImportance(event: MemoryEvent): number {
+    const metadata = this.asRecord(event.metadata);
+    const importance = metadata.importance;
+    if (typeof importance === 'number' && Number.isFinite(importance)) {
+      return Math.max(0, Math.min(1, importance));
+    }
+
+    if (event.eventType === 'session_summary') return 0.8;
+    if (event.eventType === 'tool_observation') return 0.6;
+    return 0.5;
+  }
+
+  private getProjectHash(metadata: Record<string, unknown>): string | undefined {
+    const scope = this.asRecord(metadata.scope);
+    const project = this.asRecord(scope.project);
+    return typeof project.hash === 'string' && project.hash.length > 0
+      ? project.hash
+      : undefined;
+  }
+
+  private getTags(metadata: Record<string, unknown>): string[] {
+    return Array.isArray(metadata.tags)
+      ? metadata.tags.filter((tag): tag is string => typeof tag === 'string' && tag.length > 0)
+      : [];
+  }
+
+  private getFileRefs(metadata: Record<string, unknown>): string[] {
+    const refs = metadata.fileRefs ?? metadata.files;
+    return Array.isArray(refs)
+      ? refs.filter((ref): ref is string => typeof ref === 'string' && ref.length > 0)
+      : [];
+  }
+
+  private asRecord(value: unknown): Record<string, unknown> {
+    return value && typeof value === 'object' && !Array.isArray(value)
+      ? value as Record<string, unknown>
+      : {};
+  }
+}
+
+export function createFactDeriver(): FactDeriver {
+  return new FactDeriver();
+}

package/src/core/derive/index.ts

@@ -0,0 +1,2 @@
+export * from './fact-deriver.js';
+export * from './summary-deriver.js';

package/src/core/derive/summary-deriver.ts

@@ -0,0 +1,76 @@
+import type { MemoryEvent } from '../types.js';
+
+export interface SessionSummaryDerivation {
+  text: string;
+  metadata: {
+    generated: 'rule-based';
+    eventCount: number;
+  };
+}
+
+const MAX_FIRST_PROMPT_LENGTH = 120;
+const MAX_TOOL_NAMES = 6;
+
+export class SummaryDeriver {
+  /**
+   * Derive the current lightweight rule-based session summary from raw events.
+   *
+   * The deriver is intentionally pure: callers own persistence and lifecycle
+   * orchestration, while this class owns summary text and metadata decisions.
+   */
+  deriveSessionSummary(events: MemoryEvent[]): SessionSummaryDerivation | null {
+    if (events.length < 3) return null;
+    if (events.some((event) => event.eventType === 'session_summary')) return null;
+
+    const prompts = events.filter((event) => event.eventType === 'user_prompt');
+    const toolObservations = events.filter((event) => event.eventType === 'tool_observation');
+    const toolNames = Array.from(new Set(
+      toolObservations
+        .map((event) => this.asRecord(event.metadata).toolName)
+        .filter((toolName): toolName is string => typeof toolName === 'string' && toolName.length > 0)
+    ));
+    const errorObservations = toolObservations.filter((event) => this.isErrorObservation(event));
+
+    const datePart = events[0].timestamp.toISOString().split('T')[0];
+    const parts: string[] = [`[${datePart}] ${prompts.length}턴 세션`];
+
+    if (prompts.length > 0) {
+      parts.push(`주요 작업: ${this.firstPromptPreview(prompts[0].content)}`);
+    }
+    if (toolNames.length > 0) {
+      parts.push(`사용 툴: ${toolNames.slice(0, MAX_TOOL_NAMES).join(', ')}`);
+    }
+    if (errorObservations.length > 0) {
+      parts.push(`오류 ${errorObservations.length}건 발생`);
+    }
+
+    return {
+      text: parts.join('. '),
+      metadata: { generated: 'rule-based', eventCount: events.length }
+    };
+  }
+
+  private firstPromptPreview(content: string): string {
+    return content.slice(0, MAX_FIRST_PROMPT_LENGTH).replace(/\r?\n/g, ' ');
+  }
+
+  private isErrorObservation(event: MemoryEvent): boolean {
+    const metadata = this.asRecord(event.metadata);
+
+    if (metadata.exitCode !== undefined) {
+      return metadata.exitCode !== 0;
+    }
+
+    return metadata.success === false;
+  }
+
+  private asRecord(value: unknown): Record<string, unknown> {
+    return value && typeof value === 'object' && !Array.isArray(value)
+      ? value as Record<string, unknown>
+      : {};
+  }
+}
+
+export function createSummaryDeriver(): SummaryDeriver {
+  return new SummaryDeriver();
+}

package/src/core/embedder.ts

@@ -1,152 +1,4 @@
-/**
- * Local Embedding Generator using @xenova/transformers
- * AXIOMMIND Principle 7: Standard JSON format for vectors
- */
-
-import { pipeline, Pipeline } from '@huggingface/transformers';
-
-export interface EmbeddingResult {
-  vector: number[];
-  model: string;
-  dimensions: number;
-}
-
-export class Embedder {
-  private pipeline: Pipeline | null = null;
-  private readonly modelName: string;
-  private activeModelName: string;
-  private initialized = false;
-
-  constructor(modelName: string = 'jinaai/jina-embeddings-v5-text-nano-text-matching') {
-    this.modelName = modelName;
-    this.activeModelName = modelName;
-  }
-
-  /**
-   * Initialize the embedding pipeline
-   */
-  async initialize(): Promise<void> {
-    if (this.initialized) return;
-
-    try {
-      this.pipeline = await pipeline('feature-extraction', this.modelName);
-      this.activeModelName = this.modelName;
-      this.initialized = true;
-      return;
-    } catch (primaryError) {
-      const fallbackModel = process.env.CLAUDE_MEMORY_EMBEDDING_FALLBACK_MODEL || 'onnx-community/embeddinggemma-300m-ONNX';
-      if (fallbackModel === this.modelName) {
-        throw primaryError;
-      }
-
-      console.warn(`[Embedder] Primary model failed (${this.modelName}). Falling back to ${fallbackModel}`);
-      this.pipeline = await pipeline('feature-extraction', fallbackModel);
-      this.activeModelName = fallbackModel;
-      this.initialized = true;
-    }
-  }
-
-  // ~4 chars per token; 512 tokens * 4 = 2048, use 2000 to be safe
-  private static readonly MAX_CHARS = 2000;
-
-  private truncate(text: string): string {
-    return text.length > Embedder.MAX_CHARS ? text.slice(0, Embedder.MAX_CHARS) : text;
-  }
-
-  /**
-   * Generate embedding for a single text
-   */
-  async embed(text: string): Promise<EmbeddingResult> {
-    await this.initialize();
-
-    if (!this.pipeline) {
-      throw new Error('Embedding pipeline not initialized');
-    }
-
-    const output = await this.pipeline(this.truncate(text), {
-      pooling: 'mean',
-      normalize: true,
-      truncation: true,
-      max_length: 512
-    });
-
-    const vector = Array.from(output.data as Float32Array);
-
-    return {
-      vector,
-      model: this.activeModelName,
-      dimensions: vector.length
-    };
-  }
-
-  /**
-   * Generate embeddings for multiple texts in batch
-   */
-  async embedBatch(texts: string[]): Promise<EmbeddingResult[]> {
-    await this.initialize();
-
-    if (!this.pipeline) {
-      throw new Error('Embedding pipeline not initialized');
-    }
-
-    const results: EmbeddingResult[] = [];
-
-    // Process in batches of 32 for memory efficiency
-    const batchSize = 32;
-    for (let i = 0; i < texts.length; i += batchSize) {
-      const batch = texts.slice(i, i + batchSize);
-
-      for (const text of batch) {
-        const output = await this.pipeline(this.truncate(text), {
-          pooling: 'mean',
-          normalize: true,
-          truncation: true,
-          max_length: 512
-        });
-
-        const vector = Array.from(output.data as Float32Array);
-
-        results.push({
-          vector,
-          model: this.activeModelName,
-          dimensions: vector.length
-        });
-      }
-    }
-
-    return results;
-  }
-
-  /**
-   * Get embedding dimensions for the current model
-   */
-  async getDimensions(): Promise<number> {
-    const result = await this.embed('test');
-    return result.dimensions;
-  }
-
-  /**
-   * Check if embedder is ready
-   */
-  isReady(): boolean {
-    return this.initialized && this.pipeline !== null;
-  }
-
-  /**
-   * Get model name
-   */
-  getModelName(): string {
-    return this.activeModelName;
-  }
-}
-
-// Singleton instance for reuse
-let defaultEmbedder: Embedder | null = null;
-
-export function getDefaultEmbedder(): Embedder {
-  const envModel = process.env.CLAUDE_MEMORY_EMBEDDING_MODEL;
-  if (!defaultEmbedder) {
-    defaultEmbedder = new Embedder(envModel || undefined);
-  }
-  return defaultEmbedder;
-}
+// Compatibility re-export. Embedding is an optional vector extension, but
+// existing core/engine imports still resolve through this path during the
+// strangler migration.
+export * from '../extensions/vector/index.js';

package/src/core/engine/embedding-maintenance-service.ts

@@ -0,0 +1,187 @@
+import * as fs from 'fs';
+import * as path from 'path';
+
+export interface EmbeddingMaintenanceEvent {
+  id: string;
+  content: string;
+}
+
+export interface EmbeddingMaintenanceEventStore {
+  clearEmbeddingOutbox(): Promise<void>;
+  getEventsPage(limit: number, offset: number): Promise<EmbeddingMaintenanceEvent[]>;
+  enqueueForEmbedding(eventId: string, content: string): Promise<void>;
+}
+
+export interface EmbeddingMaintenanceVectorStore {
+  count(): Promise<number>;
+  clearAll(): Promise<void>;
+}
+
+export interface EmbeddingMaintenanceVectorWorker {
+  isRunning(): boolean;
+  stop(): void;
+  start(): void;
+}
+
+export interface EmbeddingMaintenanceFileSystem {
+  existsSync(targetPath: string): boolean;
+  readFileSync(targetPath: string, encoding: BufferEncoding): string;
+  writeFileSync(targetPath: string, content: string): void;
+}
+
+export interface EmbeddingModelMaintenanceOptions {
+  autoMigrate?: boolean;
+}
+
+export interface EmbeddingModelMaintenanceResult {
+  changed: boolean;
+  previousModel: string | null;
+  currentModel: string;
+  enqueued: number;
+  reason?: string;
+}
+
+export interface EmbeddingMaintenanceServiceOptions {
+  storagePath: string;
+  initialize: () => Promise<void>;
+  getEmbeddingModelName: () => string;
+  vectorStore: EmbeddingMaintenanceVectorStore;
+  eventStore: EmbeddingMaintenanceEventStore;
+  getVectorWorker: () => EmbeddingMaintenanceVectorWorker | null;
+  fileSystem?: EmbeddingMaintenanceFileSystem;
+}
+
+export interface EmbeddingMaintenanceService {
+  getEmbeddingModelName(): string;
+  ensureEmbeddingModelForImport(options?: EmbeddingModelMaintenanceOptions): Promise<EmbeddingModelMaintenanceResult>;
+}
+
+const DEFAULT_PAGE_SIZE = 1000;
+
+const defaultFileSystem: EmbeddingMaintenanceFileSystem = {
+  existsSync: fs.existsSync,
+  readFileSync: (targetPath, encoding) => fs.readFileSync(targetPath, encoding),
+  writeFileSync: (targetPath, content) => fs.writeFileSync(targetPath, content)
+};
+
+class DefaultEmbeddingMaintenanceService implements EmbeddingMaintenanceService {
+  private readonly fileSystem: EmbeddingMaintenanceFileSystem;
+
+  constructor(private readonly options: EmbeddingMaintenanceServiceOptions) {
+    this.fileSystem = options.fileSystem ?? defaultFileSystem;
+  }
+
+  getEmbeddingModelName(): string {
+    return this.options.getEmbeddingModelName();
+  }
+
+  async ensureEmbeddingModelForImport(
+    options?: EmbeddingModelMaintenanceOptions
+  ): Promise<EmbeddingModelMaintenanceResult> {
+    await this.options.initialize();
+
+    const currentModel = this.getEmbeddingModelName();
+    const metaPath = path.join(this.options.storagePath, 'embedding-meta.json');
+    const previousModel = this.readPreviousModel(metaPath);
+    const vectorCount = await this.options.vectorStore.count();
+    const hasExistingVectors = vectorCount > 0;
+
+    // First-time metadata write (no migration needed unless legacy vectors exist)
+    if (!previousModel && !hasExistingVectors) {
+      this.fileSystem.writeFileSync(
+        metaPath,
+        JSON.stringify({ model: currentModel, updatedAt: new Date().toISOString() }, null, 2)
+      );
+      return { changed: false, previousModel: null, currentModel, enqueued: 0, reason: 'initialized-meta' };
+    }
+
+    const modelChanged = previousModel !== currentModel;
+    const legacyUnknownButVectorsExist = !previousModel && hasExistingVectors;
+
+    if (!modelChanged && !legacyUnknownButVectorsExist) {
+      return { changed: false, previousModel, currentModel, enqueued: 0 };
+    }
+
+    if (options?.autoMigrate === false) {
+      return {
+        changed: true,
+        previousModel,
+        currentModel,
+        enqueued: 0,
+        reason: legacyUnknownButVectorsExist ? 'legacy-vectors-without-meta' : 'model-mismatch'
+      };
+    }
+
+    const worker = this.options.getVectorWorker();
+    const wasRunning = worker?.isRunning() || false;
+    if (wasRunning) worker?.stop();
+
+    await this.options.vectorStore.clearAll();
+    await this.options.eventStore.clearEmbeddingOutbox();
+
+    const enqueued = await this.reenqueueAllEvents();
+
+    this.fileSystem.writeFileSync(
+      metaPath,
+      JSON.stringify(
+        {
+          model: currentModel,
+          previousModel,
+          migratedAt: new Date().toISOString(),
+          enqueued
+        },
+        null,
+        2
+      )
+    );
+
+    if (wasRunning) worker?.start();
+
+    return {
+      changed: true,
+      previousModel,
+      currentModel,
+      enqueued,
+      reason: legacyUnknownButVectorsExist ? 'legacy-vectors-without-meta' : 'model-mismatch'
+    };
+  }
+
+  private readPreviousModel(metaPath: string): string | null {
+    try {
+      if (this.fileSystem.existsSync(metaPath)) {
+        const parsed = JSON.parse(this.fileSystem.readFileSync(metaPath, 'utf-8')) as { model?: string };
+        return parsed?.model || null;
+      }
+    } catch {
+      return null;
+    }
+
+    return null;
+  }
+
+  private async reenqueueAllEvents(): Promise<number> {
+    let offset = 0;
+    let enqueued = 0;
+
+    while (true) {
+      const page = await this.options.eventStore.getEventsPage(DEFAULT_PAGE_SIZE, offset);
+      if (page.length === 0) break;
+
+      for (const event of page) {
+        await this.options.eventStore.enqueueForEmbedding(event.id, event.content);
+        enqueued += 1;
+      }
+
+      offset += page.length;
+      if (page.length < DEFAULT_PAGE_SIZE) break;
+    }
+
+    return enqueued;
+  }
+}
+
+export function createEmbeddingMaintenanceService(
+  options: EmbeddingMaintenanceServiceOptions
+): EmbeddingMaintenanceService {
+  return new DefaultEmbeddingMaintenanceService(options);
+}

package/src/core/engine/endless-memory-services.ts

@@ -0,0 +1,4 @@
+// Compatibility re-export. Endless memory is an optional extension, but existing
+// engine/facade imports still resolve through this path during the strangler
+// migration.
+export * from '../../extensions/endless-memory/index.js';

package/src/core/engine/index.ts

@@ -0,0 +1,19 @@
+export * from './memory-ingest-service.js';
+export * from './memory-query-service.js';
+export * from './memory-engine-services.js';
+export * from './retrieval-orchestrator.js';
+export * from './retrieval-disclosure-service.js';
+export * from './retrieval-analytics-service.js';
+export * from './shared-memory-services.js';
+export * from './endless-memory-services.js';
+export * from './embedding-maintenance-service.js';
+export * from './memory-runtime-service.js';
+export {
+  createRetrievalServices
+} from './retrieval-services.js';
+export type {
+  CreateRetrieverFn,
+  RetrievalEventStore,
+  RetrievalServices,
+  RetrievalServicesDeps
+} from './retrieval-services.js';