@chude/memory 4.0.0

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

@@ -0,0 +1,180 @@
+/**
+ * Service Port Interfaces
+ *
+ * Defines contracts for domain services that may have infrastructure
+ * dependencies. These interfaces allow the domain to define what
+ * services it needs without knowing the implementation details.
+ */
+import type { SearchQuery } from "../value-objects/search-query.js";
+import type { SearchResult } from "../value-objects/search-result.js";
+import type { MessageRole } from "../entities/message.js";
+/**
+ * Options for filtering and limiting search results.
+ *
+ * All properties are optional. When not specified:
+ * - limit defaults to implementation-specific value
+ * - filters are not applied
+ */
+export interface SearchOptions {
+    /** Maximum number of results to return */
+    limit?: number | undefined;
+    /** Filter results to a specific project name (case-insensitive substring match) */
+    projectFilter?: string | undefined;
+    /** Filter by message role (user or assistant). Can be single role or array of roles. */
+    roleFilter?: MessageRole | MessageRole[] | undefined;
+    /** Only include results after this date */
+    sinceDate?: Date | undefined;
+    /** Only include results before this date */
+    beforeDate?: Date | undefined;
+    /** Filter results to a specific session ID */
+    sessionFilter?: string | undefined;
+}
+/** Search mode for hybrid search */
+export type SearchMode = "auto" | "fts" | "vector" | "hybrid";
+/**
+ * Extended search options with hybrid mode support.
+ */
+export interface HybridSearchOptions extends SearchOptions {
+    /** Search mode selection. Default: 'auto' */
+    mode?: SearchMode | undefined;
+    /** Disable temporal decay scoring for this search */
+    noDecay?: boolean | undefined;
+}
+/**
+ * Service for full-text search across session content.
+ *
+ * Implementations use FTS5 for efficient text matching.
+ * Results are ranked by relevance score.
+ */
+export interface ISearchService {
+    /**
+     * Search for content matching the query.
+     *
+     * Uses full-text search with ranking. Results are ordered by
+     * relevance score (highest first).
+     *
+     * @param query The search query (validated)
+     * @param options Optional search filters and limits
+     * @returns Array of search results, ranked by relevance
+     */
+    search(query: SearchQuery, options?: SearchOptions): Promise<SearchResult[]>;
+}
+/**
+ * Per-project statistics.
+ */
+export interface ProjectStats {
+    projectName: string;
+    sessionCount: number;
+    messageCount: number;
+}
+/**
+ * Database statistics result.
+ */
+export interface StatsResult {
+    totalSessions: number;
+    totalMessages: number;
+    totalToolUses: number;
+    databaseSizeBytes: number;
+    projectBreakdown: ProjectStats[];
+}
+/**
+ * Service for database statistics queries.
+ */
+export interface IStatsService {
+    /**
+     * Get database-wide statistics with per-project breakdown.
+     *
+     * @param projectLimit Maximum projects to include in breakdown (default 10)
+     * @returns Statistics including totals and per-project breakdown
+     */
+    getStats(projectLimit?: number): Promise<StatsResult>;
+}
+/**
+ * Port for generating structured summaries from session content.
+ *
+ * Implementations invoke an LLM (e.g., claude -p) to produce
+ * a daily log entry from raw session messages.
+ */
+export interface ISummaryGenerator {
+    /**
+     * Generate a structured daily log summary from session content.
+     *
+     * @param content Extracted session content (user messages + assistant text)
+     * @param sessionId Session identifier for the summary header
+     * @param projectName Project name for context
+     * @param startTime Session start time (ISO string)
+     * @param endTime Session end time (ISO string)
+     * @returns Formatted markdown summary in daily log format
+     */
+    generateSummary(content: string, sessionId: string, projectName: string, startTime: string, endTime: string): Promise<string>;
+}
+/**
+ * Result from an external markdown file search (e.g., qmd).
+ *
+ * Fields match qmd's --json output shape. Optional fields may not
+ * be present depending on the external tool's configuration and
+ * index state.
+ */
+export interface QmdSearchResult {
+    /** Document ID from the external tool's index */
+    docid?: string;
+    /** Relevance score */
+    score: number;
+    /** File path (may use tool-specific URI format, e.g., qmd://) */
+    file: string;
+    /** Document title extracted from markdown */
+    title: string;
+    /** Surrounding text context */
+    context?: string;
+    /** Highlighted match snippet */
+    snippet?: string;
+}
+/**
+ * Health information for an external search provider.
+ */
+export interface QmdHealthInfo {
+    /** Whether the external tool binary was found in PATH */
+    available: boolean;
+    /** Resolved binary path, null if not found */
+    path: string | null;
+}
+/**
+ * Port for delegating search to an external tool (e.g., qmd).
+ *
+ * Implementations invoke the tool as a subprocess and parse its
+ * output into typed results. The domain defines the contract;
+ * infrastructure implements the subprocess invocation.
+ */
+export interface IExternalSearchProvider {
+    /** Execute search against external tool, return parsed results */
+    search(query: string): Promise<QmdSearchResult[]>;
+    /** Synchronous check if the external tool is available in PATH */
+    isAvailable(): boolean;
+    /** Synchronous check returning availability and resolved binary path */
+    getHealthInfo(): QmdHealthInfo;
+}
+/**
+ * Port for writing ambient context artifacts.
+ *
+ * Implementations handle filesystem operations to write context.md
+ * (complete overwrite) and update MEMORY.md (marker-based merge).
+ */
+export interface IAmbientContextWriter {
+    /**
+     * Write the full context file (complete overwrite).
+     *
+     * @param autoMemoryDir Directory path for the auto-memory artifacts
+     * @param content Content to write as context.md
+     */
+    writeContextFile(autoMemoryDir: string, content: string): Promise<void>;
+    /**
+     * Update the MEMORY.md block using marker-based merge.
+     *
+     * Content between `<!-- memory-cli:start -->` and `<!-- memory-cli:end -->`
+     * markers is replaced. Content outside markers is preserved.
+     *
+     * @param autoMemoryDir Directory path for the auto-memory artifacts
+     * @param blockContent Content to place between markers
+     */
+    updateMemoryBlock(autoMemoryDir: string, blockContent: string): Promise<void>;
+}

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

@@ -0,0 +1,82 @@
+/**
+ * Signal Port Interfaces
+ *
+ * Defines contracts for abort signaling, checkpoint management,
+ * and sync logging. These interfaces abstract infrastructure concerns
+ * (filesystem, process signals) from application services.
+ */
+/**
+ * Checkpoint data for recovering from interrupted sync operations.
+ *
+ * Tracks which sessions have been completed so that a resumed sync
+ * can skip already-processed sessions.
+ */
+export interface SyncCheckpoint {
+    /** When the sync began (ISO timestamp) */
+    startedAt: string;
+    /** Total number of sessions to sync */
+    totalSessions: number;
+    /** Number of sessions completed */
+    completedSessions: number;
+    /** List of completed session IDs */
+    completedSessionIds: string[];
+    /** When last session was completed (ISO timestamp, null if none) */
+    lastCompletedAt: string | null;
+}
+/**
+ * Abort signal for long-running sync operations.
+ *
+ * Implementations check process signals (SIGINT/SIGTERM) or other
+ * abort triggers. The sync loop checks this between sessions.
+ */
+export interface ISyncAbortSignal {
+    /**
+     * Check if abort has been requested.
+     *
+     * @returns true if the operation should stop
+     */
+    shouldAbort(): boolean;
+}
+/**
+ * Checkpoint persistence for sync recovery.
+ *
+ * Implementations store checkpoint state to disk so that interrupted
+ * syncs can resume from where they left off.
+ */
+export interface ICheckpointManager {
+    /**
+     * Load the most recent checkpoint.
+     *
+     * @returns Checkpoint data, or null if no checkpoint exists
+     */
+    load(): SyncCheckpoint | null;
+    /**
+     * Save checkpoint state.
+     *
+     * @param checkpoint Checkpoint data to persist
+     */
+    save(checkpoint: SyncCheckpoint): void;
+    /**
+     * Clear checkpoint after successful sync completion.
+     */
+    clear(): void;
+}
+/**
+ * Structured logger for sync operations.
+ *
+ * Implementations write log entries to structured storage
+ * (JSON lines files, databases, etc.).
+ */
+export interface ISyncLogger {
+    /**
+     * Write a structured log entry.
+     *
+     * @param entry Log entry with level, message, and optional context
+     */
+    log(entry: {
+        level: "debug" | "info" | "warn" | "error";
+        message: string;
+        sessionId?: string;
+        error?: string;
+    }): void;
+}

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

@@ -0,0 +1,122 @@
+/**
+ * Source Port Interfaces
+ *
+ * Defines contracts for accessing external data sources.
+ * These interfaces abstract filesystem and parsing operations.
+ */
+import type { MemoryFileType } from "../entities/memory-file.js";
+import type { ProjectPath } from "../value-objects/project-path.js";
+import type { ParsedEvent } from "./types.js";
+/**
+ * Information about a discovered session file.
+ *
+ * Used during session discovery to identify available sessions
+ * without loading their full content.
+ */
+export interface SessionFileInfo {
+    /** Session UUID (derived from filename) */
+    id: string;
+    /** Full path to the JSONL file */
+    path: string;
+    /** Project this session belongs to */
+    projectPath: ProjectPath;
+    /** Last modification time of the file */
+    modifiedTime: Date;
+    /** File size in bytes */
+    size: number;
+}
+/**
+ * Source for discovering Claude Code session files.
+ *
+ * Implementations scan the Claude Code projects directory
+ * to find available session JSONL files.
+ */
+export interface ISessionSource {
+    /**
+     * Discover all available session files.
+     *
+     * Scans the Claude Code projects directory structure:
+     * ~/.claude/projects/<encoded-path>/<session-uuid>.jsonl
+     *
+     * @returns Array of session file information
+     */
+    discoverSessions(): Promise<SessionFileInfo[]>;
+    /**
+     * Get the full path to a session file by ID.
+     *
+     * @param sessionId The session UUID
+     * @returns Full path to the JSONL file, or null if not found
+     */
+    getSessionFile(sessionId: string): Promise<string | null>;
+}
+/**
+ * Parser for extracting events from JSONL session files.
+ *
+ * Uses streaming to handle large files efficiently without
+ * loading the entire file into memory.
+ */
+export interface IEventParser {
+    /**
+     * Parse events from a session file.
+     *
+     * Returns an async iterable that yields events one at a time.
+     * Events that cannot be parsed or are not relevant are yielded
+     * as "skipped" events with a reason.
+     *
+     * @param filePath Full path to the JSONL file
+     * @returns Async iterable of parsed events
+     */
+    parse(filePath: string): AsyncIterable<ParsedEvent>;
+}
+/**
+ * Resolver for mapping encoded directory paths to project names.
+ *
+ * Claude Code encodes directory paths in a lossy way (spaces, hyphens,
+ * slashes all become dashes). Implementations resolve the actual project
+ * name by walking the filesystem or using cached mappings.
+ */
+export interface IProjectNameResolver {
+    /**
+     * Resolve a project name from a full encoded path.
+     *
+     * @param encodedPath The encoded directory path (e.g., "C--Users-Destiny-Projects-memory-nexus")
+     * @returns The resolved project name (e.g., "memory-nexus")
+     */
+    resolveFromEncodedPath(encodedPath: string): string;
+}
+/**
+ * Information about a discovered memory file.
+ *
+ * Returned by IMemoryFileScanner during file discovery.
+ * Contains all data needed to create a MemoryFile entity.
+ */
+export interface MemoryFileInfo {
+    /** Path relative to the legacy memory-file root (uses forward slashes) */
+    filePath: string;
+    /** Absolute path for reading */
+    absolutePath: string;
+    /** Classified file type */
+    fileType: MemoryFileType;
+    /** Encoded project path, or undefined for global files */
+    projectEncoded?: string | undefined;
+    /** SHA-256 hash of file content */
+    contentHash: string;
+    /** Full file content */
+    content: string;
+}
+/**
+ * Scanner for discovering legacy markdown memory files.
+ *
+ * Implementations discover .md files, classify their type from
+ * path patterns, extract project encoded names, and compute
+ * content hashes. Returns empty array when the directory does
+ * not exist (graceful no-op).
+ */
+export interface IMemoryFileScanner {
+    /**
+     * Discover all legacy memory files.
+     *
+     * @returns Array of discovered file info, empty if directory missing
+     */
+    discoverFiles(): Promise<MemoryFileInfo[]>;
+}

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

@@ -0,0 +1,150 @@
+/**
+ * Parsed Event Types
+ *
+ * Defines the discriminated union for events parsed from JSONL files.
+ * These types represent the domain's view of Claude Code session events.
+ *
+ * Based on research in: .planning/research/JSONL-EVENT-SCHEMA.md
+ */
+/**
+ * Content block within an assistant message.
+ * Can be text or a tool use invocation.
+ */
+export type ContentBlock = {
+    type: "text";
+    text: string;
+} | {
+    type: "tool_use";
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+};
+/**
+ * Data extracted from a user message event.
+ */
+export interface UserEventData {
+    /** Unique event identifier */
+    uuid: string;
+    /** User message content */
+    message: {
+        content: string;
+    };
+    /** ISO 8601 timestamp */
+    timestamp: string;
+    /** Working directory at time of message */
+    cwd?: string;
+    /** Git branch if in a repository */
+    gitBranch?: string;
+}
+/**
+ * Data extracted from an assistant message event.
+ */
+export interface AssistantEventData {
+    /** Unique event identifier */
+    uuid: string;
+    /** Assistant message with content blocks */
+    message: {
+        content: ContentBlock[];
+        /** Model used for this response */
+        model?: string;
+    };
+    /** ISO 8601 timestamp */
+    timestamp: string;
+    /** Token usage statistics */
+    usage?: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+}
+/**
+ * Data extracted from a tool use event.
+ * Represents when Claude invokes a tool.
+ */
+export interface ToolUseEventData {
+    /** Unique tool use identifier */
+    uuid: string;
+    /** Name of the tool invoked */
+    name: string;
+    /** Input parameters passed to the tool */
+    input: Record<string, unknown>;
+    /** ISO 8601 timestamp */
+    timestamp: string;
+}
+/**
+ * Data extracted from a tool result event.
+ * Represents the output from a tool invocation.
+ */
+export interface ToolResultEventData {
+    /** Unique result identifier */
+    uuid: string;
+    /** ID of the tool use this result corresponds to */
+    toolUseId: string;
+    /** Result content (output or error message) */
+    content: string;
+    /** Whether the tool execution resulted in an error */
+    isError: boolean;
+    /** ISO 8601 timestamp */
+    timestamp: string;
+}
+/**
+ * Data extracted from a summary event.
+ * Summaries are compressed session history for context management.
+ */
+export interface SummaryEventData {
+    /** Condensed session content */
+    content: string;
+    /** ISO 8601 timestamp */
+    timestamp: string;
+    /** UUID of the last event this summary covers */
+    leafUuid?: string;
+}
+/**
+ * Data extracted from a system event.
+ * System events track timing and configuration.
+ */
+export interface SystemEventData {
+    /** System event subtype (e.g., "turn_duration") */
+    subtype: string;
+    /** Event-specific data */
+    data: unknown;
+    /** ISO 8601 timestamp */
+    timestamp: string;
+}
+/**
+ * Discriminated union of all parsed event types.
+ *
+ * Use type narrowing with switch/case on the `type` field:
+ * ```typescript
+ * switch (event.type) {
+ *   case "user":
+ *     // event.data is UserEventData
+ *     break;
+ *   case "assistant":
+ *     // event.data is AssistantEventData
+ *     break;
+ *   // ...
+ * }
+ * ```
+ */
+export type ParsedEvent = {
+    type: "user";
+    data: UserEventData;
+} | {
+    type: "assistant";
+    data: AssistantEventData;
+} | {
+    type: "tool_use";
+    data: ToolUseEventData;
+} | {
+    type: "tool_result";
+    data: ToolResultEventData;
+} | {
+    type: "summary";
+    data: SummaryEventData;
+} | {
+    type: "system";
+    data: SystemEventData;
+} | {
+    type: "skipped";
+    reason: string;
+};

package/dist/domain/services/content-extractor.d.ts

@@ -0,0 +1,61 @@
+/**
+ * ContentExtractor Domain Service
+ *
+ * Extracts structured content from Claude Code session JSONL lines.
+ * Handles parsing of messages, tool uses, and tool results.
+ *
+ * Service properties:
+ * - Stateless operations
+ * - Pure functions (no side effects)
+ * - Domain logic only (no infrastructure concerns)
+ */
+interface MessageContent {
+    role: "user" | "assistant";
+    content: string;
+}
+interface ToolUseContent {
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+}
+interface ToolResultContent {
+    toolUseId: string;
+    content: string;
+    isError: boolean;
+}
+export declare class ContentExtractor {
+    /**
+     * Extract message content from a JSONL line.
+     * @param jsonLine A single line from a JSONL file
+     * @returns Message content or null if not a message line
+     */
+    static extractMessageContent(jsonLine: string): MessageContent | null;
+    /**
+     * Extract tool uses from a JSONL line.
+     * @param jsonLine A single line from a JSONL file
+     * @returns Array of tool use objects (empty if none found)
+     */
+    static extractToolUses(jsonLine: string): ToolUseContent[];
+    /**
+     * Extract tool results from a JSONL line.
+     * @param jsonLine A single line from a JSONL file
+     * @returns Array of tool result objects (empty if none found)
+     */
+    static extractToolResults(jsonLine: string): ToolResultContent[];
+    /**
+     * Check if a JSONL line represents a message (human or assistant).
+     * @param jsonLine A single line from a JSONL file
+     * @returns true if line is a message
+     */
+    static isMessageLine(jsonLine: string): boolean;
+    /**
+     * Extract timestamp from a JSONL line.
+     * @param jsonLine A single line from a JSONL file
+     * @returns Date object or null if no valid timestamp
+     */
+    static extractTimestamp(jsonLine: string): Date | null;
+    private static parseJson;
+    private static isMessageType;
+    private static extractTextContent;
+}
+export {};

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

@@ -0,0 +1,8 @@
+/**
+ * Domain Services
+ *
+ * Stateless operations that don't naturally fit in entities or value objects.
+ */
+export { ContentExtractor } from "./content-extractor.js";
+export { PathDecoder } from "./path-decoder.js";
+export { QueryParser, type ParsedQuery, type QueryFilters, } from "./query-parser.js";

package/dist/domain/services/path-decoder.d.ts

@@ -0,0 +1,56 @@
+/**
+ * PathDecoder Domain Service
+ *
+ * Handles decoding of encoded project directory names from Claude Code's
+ * session storage format back to their original file system paths.
+ *
+ * Service properties:
+ * - Stateless operations
+ * - Pure functions (no side effects)
+ * - Domain logic only (no infrastructure concerns)
+ */
+import { ProjectPath } from "../value-objects/index.js";
+export declare class PathDecoder {
+    /**
+     * Decode an encoded project directory name to a ProjectPath value object.
+     * @param encoded The encoded directory name (e.g., "C--Users-Destiny-Projects-foo")
+     * @returns ProjectPath value object with decoded path
+     */
+    static decodeProjectDirectory(encoded: string): ProjectPath;
+    /**
+     * Check if a string appears to be an encoded path from Claude Code.
+     * @param value The string to check
+     * @returns true if it matches encoded path patterns
+     */
+    static isEncodedPath(value: string): boolean;
+    /**
+     * Extract the project name from an encoded path.
+     * Note: This is a convenience method that decodes and extracts.
+     * @param encoded The encoded directory name
+     * @returns The project name (last segment of the path)
+     */
+    static extractProjectName(encoded: string): string;
+    /**
+     * Filter a list of strings to only include encoded paths.
+     * Useful for processing directory listings from Claude Code's session storage.
+     * @param items List of directory/file names
+     * @returns Only the items that appear to be encoded paths
+     */
+    static filterEncodedPaths(items: string[]): string[];
+    /**
+     * Translates absolute paths between Windows (e.g. C:\foo\bar) and WSL Unix mount (/mnt/c/foo/bar) styles.
+     * @param path The path to translate
+     * @param targetPlatform The target platform to translate for (defaults to process.platform)
+     * @returns The translated path string
+     */
+    static translatePath(path: string, targetPlatform?: string): string;
+    /**
+     * Resolves a path, optionally translating it if the target file/directory
+     * does not exist at the original path but exists at the translated path.
+     * @param path The path to resolve
+     * @param existsSyncFn Function to check file existence (optional)
+     * @param targetPlatform The target platform (defaults to process.platform)
+     * @returns The resolved or translated path string
+     */
+    static resolveExistingPath(path: string, existsSyncFn?: (p: string) => boolean, targetPlatform?: string): string;
+}