@chude/memory 4.0.0

package/dist/domain/entities/session.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Session Entity
+ *
+ * Represents a Claude Code session - a collection of messages
+ * exchanged within a project directory over a period of time.
+ *
+ * Entity properties:
+ * - Has unique identity (id)
+ * - Immutable after construction (mutations return new instances)
+ * - Aggregates Message entities
+ */
+import type { ProjectPath } from "../value-objects/project-path.js";
+import type { Message } from "./message.js";
+interface SessionParams {
+    id: string;
+    projectPath: ProjectPath;
+    startTime: Date;
+    endTime?: Date | undefined;
+    messages?: readonly Message[] | undefined;
+    summary?: string | undefined;
+    messageCount?: number | undefined;
+}
+export declare class Session {
+    private readonly _id;
+    private readonly _projectPath;
+    private readonly _startTime;
+    private readonly _endTime?;
+    private readonly _messages;
+    private readonly _summary?;
+    private readonly _messageCount?;
+    private constructor();
+    /**
+     * Create a Session entity.
+     * @throws Error if id is empty or endTime is before startTime
+     */
+    static create(params: SessionParams): Session;
+    /**
+     * The unique session identifier.
+     */
+    get id(): string;
+    /**
+     * The project directory this session belongs to.
+     */
+    get projectPath(): ProjectPath;
+    /**
+     * When the session started.
+     */
+    get startTime(): Date;
+    /**
+     * When the session ended (undefined if still active).
+     */
+    get endTime(): Date | undefined;
+    /**
+     * All messages in this session.
+     */
+    get messages(): Message[];
+    /**
+     * LLM-generated summary of this session (undefined if not extracted).
+     */
+    get summary(): string | undefined;
+    /**
+     * Number of messages in this session.
+     * Returns explicit messageCount if set, otherwise falls back to messages.length.
+     * This allows displaying accurate counts from the database without loading all messages.
+     */
+    get messageCount(): number;
+    /**
+     * Session duration in milliseconds (undefined if not complete).
+     */
+    get durationMs(): number | undefined;
+    /**
+     * Check equality with another Session (based on id).
+     */
+    equals(other: Session): boolean;
+    /**
+     * Add a message to this session.
+     * Returns a new Session instance (immutability).
+     * Note: When adding messages, messageCount is no longer used (falls back to messages.length).
+     */
+    addMessage(message: Message): Session;
+    /**
+     * Mark this session as complete.
+     * Returns a new Session instance (immutability).
+     * @throws Error if endTime is before startTime
+     */
+    complete(endTime: Date): Session;
+    /**
+     * Set the summary for this session.
+     * Returns a new Session instance (immutability).
+     */
+    withSummary(summary: string): Session;
+}
+export {};

package/dist/domain/entities/tool-use.d.ts

@@ -0,0 +1,85 @@
+/**
+ * ToolUse Entity
+ *
+ * Represents a single tool invocation within a Claude Code session.
+ * Tracks the tool name, input parameters, result, and execution status.
+ *
+ * Entity properties:
+ * - Has unique identity (id)
+ * - Immutable after construction (status updates return new instances)
+ * - Tracks execution lifecycle (pending -> success/error)
+ */
+export type ToolUseStatus = "pending" | "success" | "error";
+interface ToolUseParams {
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+    timestamp: Date;
+    status?: ToolUseStatus | undefined;
+    result?: string | undefined;
+}
+export declare class ToolUse {
+    private readonly _id;
+    private readonly _name;
+    private readonly _input;
+    private readonly _timestamp;
+    private readonly _status;
+    private readonly _result?;
+    private constructor();
+    /**
+     * Create a ToolUse entity.
+     * @throws Error if id or name is empty, or status is invalid
+     */
+    static create(params: ToolUseParams): ToolUse;
+    /**
+     * The unique tool use identifier.
+     */
+    get id(): string;
+    /**
+     * The name of the tool that was invoked.
+     */
+    get name(): string;
+    /**
+     * The input parameters passed to the tool.
+     */
+    get input(): Record<string, unknown>;
+    /**
+     * When the tool was invoked.
+     */
+    get timestamp(): Date;
+    /**
+     * The execution status (pending, success, or error).
+     */
+    get status(): ToolUseStatus;
+    /**
+     * The result of the tool execution (output or error message).
+     */
+    get result(): string | undefined;
+    /**
+     * Whether the tool execution is still pending.
+     */
+    get isPending(): boolean;
+    /**
+     * Whether the tool execution completed successfully.
+     */
+    get isSuccess(): boolean;
+    /**
+     * Whether the tool execution failed.
+     */
+    get isError(): boolean;
+    /**
+     * Check equality with another ToolUse (based on id).
+     */
+    equals(other: ToolUse): boolean;
+    /**
+     * Mark this tool use as successfully completed.
+     * Returns a new ToolUse instance (immutability).
+     */
+    completeSuccess(result: string): ToolUse;
+    /**
+     * Mark this tool use as failed.
+     * Returns a new ToolUse instance (immutability).
+     */
+    completeError(errorMessage: string): ToolUse;
+}
+export {};

package/dist/domain/errors/error-codes.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Error Codes
+ *
+ * Stable error codes for programmatic handling.
+ * These codes are used in JSON error responses and for scripting.
+ */
+/**
+ * Error code constant object.
+ * All error types with stable string identifiers.
+ */
+export declare const ErrorCode: {
+    readonly DB_CONNECTION_FAILED: "DB_CONNECTION_FAILED";
+    readonly DB_CORRUPTED: "DB_CORRUPTED";
+    readonly DB_LOCKED: "DB_LOCKED";
+    readonly INVALID_SESSION_ID: "INVALID_SESSION_ID";
+    readonly SESSION_NOT_FOUND: "SESSION_NOT_FOUND";
+    readonly SOURCE_INACCESSIBLE: "SOURCE_INACCESSIBLE";
+    readonly DISK_FULL: "DISK_FULL";
+    readonly INVALID_JSON: "INVALID_JSON";
+    readonly UNKNOWN_FORMAT: "UNKNOWN_FORMAT";
+    readonly SYNC_INTERRUPTED: "SYNC_INTERRUPTED";
+    readonly SYNC_FAILED: "SYNC_FAILED";
+    readonly INVALID_ARGUMENT: "INVALID_ARGUMENT";
+    readonly MISSING_ARGUMENT: "MISSING_ARGUMENT";
+    readonly VECTOR_UNAVAILABLE: "VECTOR_UNAVAILABLE";
+    readonly PROVIDER_TIMEOUT: "PROVIDER_TIMEOUT";
+    readonly PROVIDER_CONFIG_INVALID: "PROVIDER_CONFIG_INVALID";
+    readonly EMBEDDING_DIMENSION_MISMATCH: "EMBEDDING_DIMENSION_MISMATCH";
+    readonly MODEL_CORRUPTED: "MODEL_CORRUPTED";
+    readonly NOT_FOUND: "NOT_FOUND";
+    readonly INVALID_STATE: "INVALID_STATE";
+    readonly UNKNOWN: "UNKNOWN";
+};
+/**
+ * Union type of all error codes.
+ */
+export type ErrorCodeType = (typeof ErrorCode)[keyof typeof ErrorCode];

package/dist/domain/errors/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Domain Errors Barrel Export
+ *
+ * Error codes and base error class for structured error handling.
+ */
+export { ErrorCode, type ErrorCodeType } from "./error-codes.js";
+export { MemoryError, type ErrorContext, type ErrorJson, } from "./memory-error.js";
+export { unknownErrorMessage } from "./unknown-error.js";

package/dist/domain/errors/memory-error.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Memory Error
+ *
+ * Base error class with structured JSON output for programmatic handling.
+ */
+import type { ErrorCodeType } from "./error-codes.js";
+/**
+ * Context for error details.
+ */
+export type ErrorContext = Record<string, unknown>;
+/**
+ * JSON representation of a MemoryError.
+ */
+export interface ErrorJson {
+    error: {
+        code: ErrorCodeType;
+        message: string;
+        context?: ErrorContext;
+    };
+}
+/**
+ * Base error class for memory.
+ *
+ * Provides structured error information with:
+ * - Stable error codes for programmatic handling
+ * - Contextual information (file paths, line numbers, etc.)
+ * - JSON serialization for machine-readable output
+ */
+export declare class MemoryError extends Error {
+    /**
+     * Stable error code for programmatic handling.
+     */
+    readonly code: ErrorCodeType;
+    /**
+     * Optional context with additional error details.
+     */
+    readonly context?: ErrorContext | undefined;
+    /**
+     * Create a new MemoryError.
+     *
+     * @param code Stable error code for programmatic handling
+     * @param message Human-readable error message
+     * @param context Optional additional context (file paths, line numbers, etc.)
+     */
+    constructor(code: ErrorCodeType, message: string, context?: ErrorContext | undefined);
+    /**
+     * Convert error to JSON representation.
+     *
+     * @returns Structured error object for JSON output
+     */
+    toJSON(): ErrorJson;
+}

package/dist/domain/errors/unknown-error.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Normalize unknown throwables for user-facing messages and diagnostics.
+ *
+ * JavaScript allows throwing any value. Keeping this branch in one tested
+ * domain helper prevents every catch block from growing its own subtly
+ * different fallback.
+ */
+export declare function unknownErrorMessage(error: unknown): string;
+export declare function unknownToError(error: unknown): Error;

package/dist/domain/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Domain Layer
+ *
+ * Pure business logic with zero external dependencies.
+ * Contains entities, value objects, and domain services.
+ */
+export * from "./entities/index.js";
+export * from "./value-objects/index.js";
+export * from "./services/index.js";
+export * from "./errors/index.js";
+export * from "./ports/index.js";

package/dist/domain/ports/embedding.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Embedding Provider Port
+ *
+ * Defines the contract for embedding providers that generate vector
+ * representations of text. Implementations live in the infrastructure
+ * layer (e.g., TransformersJsProvider, OpenAiProvider, OllamaProvider).
+ *
+ * This port has ZERO external dependencies -- it uses only domain
+ * value objects and primitive types.
+ */
+import type { EmbeddingResult } from "../value-objects/embedding-result.js";
+/**
+ * Progress update during model download or initialization.
+ */
+export interface DownloadProgress {
+    /** Current status of the download/initialization */
+    status: "downloading" | "ready";
+    /** Name of the file being downloaded */
+    file: string;
+    /** Bytes loaded so far */
+    loaded: number;
+    /** Total bytes expected */
+    total: number;
+}
+/**
+ * Metadata describing an embedding model.
+ */
+export interface EmbeddingModelInfo {
+    /** Model identifier (e.g., "all-MiniLM-L6-v2") */
+    name: string;
+    /** Number of dimensions in the embedding vector */
+    dimensions: number;
+    /** Model file size in bytes */
+    sizeBytes: number;
+    /** Human-readable description of the model */
+    description?: string;
+}
+/**
+ * Port interface for embedding providers.
+ *
+ * Embedding providers transform text into dense vector representations
+ * (embeddings) that capture semantic meaning. These embeddings enable
+ * similarity search via cosine distance.
+ *
+ * Lifecycle: initialize() -> embed()/embedBatch() -> dispose()
+ *
+ * Implementations must:
+ * - Return Float32Array embeddings with consistent dimensions
+ * - Support lazy initialization (ONNX runtime loads only when needed)
+ * - Clean up resources via dispose()
+ * - Report download progress during first-time model setup
+ */
+export interface IEmbeddingProvider {
+    /** Provider identifier (e.g., "transformers-js", "openai", "ollama") */
+    readonly name: string;
+    /** Number of dimensions in the embedding vectors */
+    readonly dimensions: number;
+    /** Model identifier currently in use */
+    readonly model: string;
+    /**
+     * Generate an embedding for a single text.
+     *
+     * @param text The text to embed
+     * @returns The embedding result with vector, model, and dimensions
+     */
+    embed(text: string): Promise<EmbeddingResult>;
+    /**
+     * Generate embeddings for multiple texts in a single batch.
+     *
+     * Batch processing is more efficient than calling embed() repeatedly
+     * because it reduces ONNX runtime overhead.
+     *
+     * @param texts Array of texts to embed
+     * @returns Array of embedding results in the same order as input
+     */
+    embedBatch(texts: string[]): Promise<EmbeddingResult[]>;
+    /**
+     * Check whether the provider is initialized and ready to embed.
+     *
+     * @returns true if embed() can be called, false if initialize() is needed
+     */
+    isReady(): boolean;
+    /**
+     * Initialize the provider (download model, load ONNX runtime, etc.).
+     *
+     * First-time initialization may download model files. The optional
+     * onProgress callback reports download progress for UI display.
+     *
+     * @param onProgress Optional callback for download progress updates
+     */
+    initialize(onProgress?: (progress: DownloadProgress) => void): Promise<void>;
+    /**
+     * Release resources held by the provider (ONNX session, model cache, etc.).
+     */
+    dispose(): Promise<void>;
+}

package/dist/domain/ports/extraction.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Extraction Provider Port
+ *
+ * Defines the contract for LLM adapters that extract facts
+ * from developer interaction messages.
+ */
+import { Message } from "../entities/message.js";
+import { CandidateFact } from "../entities/fact.js";
+export interface IExtractionProvider {
+    readonly providerId: string;
+    readonly modelName: string;
+    extract(messages: Message[]): Promise<CandidateFact[]>;
+}

package/dist/domain/ports/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Domain Ports
+ *
+ * Interfaces defining how the domain interacts with the outside world.
+ * Implemented by infrastructure adapters.
+ */
+export type { ISessionRepository, IMessageRepository, IToolUseRepository, ILinkRepository, IExtractionStateRepository, IEmbeddingRepository, IMemoryFileRepository, IFrictionRepository, IBackfillStateRepository, BackfillStatusCounts, FrictionStats, UnembeddedMessage, EmbeddingBatchItem, EmbeddingServiceConfig, IFactRepository, IExtractionLogRepository, ExtractionLogEntry, } from "./repositories.js";
+export type { IEmbeddingProvider, DownloadProgress, EmbeddingModelInfo, } from "./embedding.js";
+export type { IExtractionProvider, } from "./extraction.js";
+export type { IRedactor, JsonRedactionResult, RedactionFinding, RedactionKind, RedactionResult, } from "./redactor.js";
+export type { ISearchService, SearchOptions, SearchMode, HybridSearchOptions, IStatsService, StatsResult, ProjectStats, ISummaryGenerator, QmdSearchResult, QmdHealthInfo, IExternalSearchProvider, IAmbientContextWriter, } from "./services.js";
+export type { ISessionSource, IEventParser, IProjectNameResolver, IMemoryFileScanner, SessionFileInfo, MemoryFileInfo, } from "./sources.js";
+export type { SyncCheckpoint, ISyncAbortSignal, ICheckpointManager, ISyncLogger, } from "./signals.js";
+export type { ParsedEvent, UserEventData, AssistantEventData, ToolUseEventData, ToolResultEventData, SummaryEventData, SystemEventData, ContentBlock, } from "./types.js";

package/dist/domain/ports/redactor.d.ts

@@ -0,0 +1,17 @@
+export type RedactionKind = "api_key" | "aws_access_key" | "bearer_token" | "env_secret" | "jwt" | "private_key";
+export interface RedactionFinding {
+    kind: RedactionKind;
+    placeholder: string;
+}
+export interface RedactionResult {
+    text: string;
+    findings: RedactionFinding[];
+}
+export interface JsonRedactionResult<T> {
+    value: T;
+    findings: RedactionFinding[];
+}
+export interface IRedactor {
+    redactText(input: string): RedactionResult;
+    redactJson<T>(input: T): JsonRedactionResult<T>;
+}