@chude/memory 4.0.0

package/dist/infrastructure/migration.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Migration Module
+ *
+ * Detects legacy ~/.memory-nexus/ directory and migrates data to new
+ * XDG-compliant paths. All operations are synchronous with rollback
+ * safety on failure.
+ *
+ * After successful data moves, re-installs hooks with new binary name
+ * by calling uninstallHooks() then installHooks().
+ */
+/**
+ * Migration status values.
+ *
+ * - not-needed: No legacy directory exists (fresh install or already migrated+cleaned)
+ * - pending: Legacy directory exists but new paths do not
+ * - complete: New paths exist and no legacy directory remains
+ * - partial: Both legacy and new paths exist (interrupted migration or manual partial copy)
+ */
+export type MigrationStatus = "not-needed" | "pending" | "complete" | "partial";
+/**
+ * Result of getMigrationStatus().
+ */
+export interface MigrationStatusResult {
+    /** Whether the legacy directory exists */
+    legacyExists: boolean;
+    /** Whether the new config or data directory exists */
+    newExists: boolean;
+    /** Computed migration status */
+    status: MigrationStatus;
+}
+/**
+ * Result of migrateFromLegacy().
+ */
+export interface MigrationResult {
+    /** Whether migration completed successfully (data was moved) */
+    migrated: boolean;
+    /** List of item names that were moved */
+    itemsMoved: string[];
+    /** Error messages (empty on full success) */
+    errors: string[];
+}
+/**
+ * Check migration status by examining legacy and new paths.
+ *
+ * @returns Status result with legacy/new existence flags and computed status
+ */
+export declare function getMigrationStatus(): MigrationStatusResult;
+/**
+ * Check whether a legacy database needs migration to XDG paths.
+ *
+ * Returns true when the legacy ~/.memory-nexus/memory.db exists AND either:
+ *   (a) no XDG database exists yet, OR
+ *   (b) the legacy database is larger than the XDG database (empty stub).
+ *
+ * This is a lightweight check for the CLI entry point to decide whether
+ * to run migrateFromLegacy() before any command action can create an
+ * empty database via initializeDatabase().
+ *
+ * ORDERING CONTRACT: The CLI entry point (index.ts) must call this
+ * function and, if true, call migrateFromLegacy() BEFORE program.parse()
+ * dispatches to any command that calls initializeDatabase(). This
+ * prevents the empty-stub race condition where initializeDatabase()
+ * creates a 221KB empty database before migration can move the real
+ * 266MB legacy database into place.
+ *
+ * This function does NOT import from connection.ts. The guard lives
+ * at the presentation layer (index.ts), not the infrastructure layer
+ * (connection.ts), to avoid coupling between independent modules.
+ */
+export declare function isMigrationPending(): boolean;
+/**
+ * Migrate data from legacy ~/.memory-nexus/ to new XDG paths.
+ *
+ * This function is SYNCHRONOUS. All filesystem operations use sync variants.
+ *
+ * Migration order (by priority):
+ * 1. Database (memory.db) - most critical
+ * 2. Config (config.json) - user preferences
+ * 3. Checkpoint (sync-checkpoint.json) - sync progress
+ * 4. Logs directory - debugging data
+ * 5. Hooks directory - hook scripts
+ * 6. Backups directory - settings backups
+ *
+ * On any move failure, all completed moves are rolled back in reverse order.
+ * After successful data moves, hooks are re-installed with new binary name.
+ * Hook re-install failure is logged but does not fail the migration.
+ *
+ * @returns Migration result with moved items list and any errors
+ */
+export declare function migrateFromLegacy(): MigrationResult;
+/**
+ * Move a file or directory, handling cross-filesystem (EXDEV) errors.
+ *
+ * First attempts renameSync (atomic on same filesystem).
+ * On EXDEV error, falls back to copy + delete.
+ *
+ * Exported for testing EXDEV fallback logic.
+ *
+ * @param source Source path
+ * @param dest Destination path
+ * @param isDir Whether the source is a directory
+ */
+export declare function moveFileOrDir(source: string, dest: string, isDir: boolean): void;

package/dist/infrastructure/parsers/event-classifier.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Event Classifier
+ *
+ * Routes raw JSON events from JSONL files to the appropriate ParsedEvent type.
+ * Implements extraction logic for each event type.
+ *
+ * Based on research in: .planning/research/JSONL-EVENT-SCHEMA.md
+ */
+import type { ParsedEvent, ToolUseEventData, ToolResultEventData } from "../../domain/ports/types.js";
+/**
+ * Raw event structure from JSONL files.
+ */
+interface RawEvent {
+    type: string;
+    uuid?: string;
+    timestamp?: string;
+    [key: string]: unknown;
+}
+/**
+ * Raw user event structure.
+ */
+interface RawUserEvent extends RawEvent {
+    type: "user";
+    uuid: string;
+    timestamp: string;
+    message: {
+        role: "user";
+        content: string | RawToolResultBlock[];
+    };
+    cwd?: string;
+    gitBranch?: string;
+}
+/**
+ * Raw tool result block in user message content.
+ */
+interface RawToolResultBlock {
+    type: "tool_result";
+    tool_use_id: string;
+    content: string | unknown;
+    is_error?: boolean;
+}
+/**
+ * Raw assistant event structure.
+ */
+interface RawAssistantEvent extends RawEvent {
+    type: "assistant";
+    uuid: string;
+    timestamp: string;
+    message: {
+        model?: string;
+        content: RawContentBlock[];
+        usage?: {
+            input_tokens: number;
+            output_tokens: number;
+        };
+    };
+}
+/**
+ * Raw content block types in assistant message.
+ */
+type RawContentBlock = {
+    type: "text";
+    text: string;
+} | {
+    type: "tool_use";
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+} | {
+    type: "thinking";
+    thinking: string;
+    signature?: string;
+};
+/**
+ * Check if a value is a valid event object.
+ *
+ * @param value The value to check
+ * @returns true if the value is a valid event object
+ */
+export declare function isValidEvent(value: unknown): value is RawEvent;
+/**
+ * Classify a raw JSON event into a ParsedEvent.
+ *
+ * Routes the event to the appropriate extractor based on type,
+ * or returns a skipped event for non-extracted types.
+ *
+ * @param raw The raw JSON event object
+ * @returns Classified ParsedEvent
+ */
+export declare function classifyEvent(raw: unknown): ParsedEvent;
+/**
+ * Extract tool use events from an assistant event.
+ *
+ * Creates separate ToolUseEventData for each tool_use block,
+ * enabling easier querying of tool usage.
+ *
+ * @param raw The raw assistant event
+ * @returns Array of tool use event data
+ */
+export declare function extractToolUseEvents(raw: RawAssistantEvent): ToolUseEventData[];
+/**
+ * Extract tool result events from a user event.
+ *
+ * Creates separate ToolResultEventData for each tool_result block,
+ * enabling easier querying of tool outputs.
+ *
+ * @param raw The raw user event
+ * @returns Array of tool result event data
+ */
+export declare function extractToolResultEvents(raw: RawUserEvent): ToolResultEventData[];
+export {};

package/dist/infrastructure/parsers/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Parser Adapters
+ *
+ * Implementations for parsing Claude Code session files.
+ */
+export { JsonlEventParser } from "./jsonl-parser.js";
+export { classifyEvent, isValidEvent, extractToolUseEvents, extractToolResultEvents, } from "./event-classifier.js";
+export { normalizeTimestamp } from "./timestamp.js";

package/dist/infrastructure/parsers/jsonl-parser.d.ts

@@ -0,0 +1,25 @@
+/**
+ * JSONL Parser Adapter
+ *
+ * Implements streaming JSONL parsing for Claude Code session files.
+ * Uses readline.createInterface for memory-efficient line-by-line processing.
+ */
+import type { IEventParser, ParsedEvent } from "../../domain/ports/index.js";
+/**
+ * Streaming JSONL parser for Claude Code session files.
+ *
+ * Parses session files line-by-line without loading the entire file
+ * into memory. Handles malformed JSON gracefully by yielding
+ * "skipped" events with error details.
+ *
+ * @implements {IEventParser}
+ */
+export declare class JsonlEventParser implements IEventParser {
+    /**
+     * Parse events from a JSONL session file.
+     *
+     * @param filePath Full path to the JSONL file
+     * @yields ParsedEvent for each line (or skipped event for errors)
+     */
+    parse(filePath: string): AsyncGenerator<ParsedEvent>;
+}

package/dist/infrastructure/parsers/timestamp.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Timestamp Normalization
+ *
+ * Normalizes various timestamp formats to ISO 8601 for consistent storage.
+ */
+/**
+ * Normalize various timestamp formats to ISO 8601.
+ *
+ * Handles:
+ * - Already ISO 8601 strings
+ * - Unix timestamps (seconds or milliseconds)
+ * - Date objects
+ * - Other parseable date strings
+ *
+ * @param value The value to normalize (string, number, Date, or unknown)
+ * @returns ISO 8601 formatted timestamp string
+ */
+export declare function normalizeTimestamp(value: unknown): string;

package/dist/infrastructure/paths.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Centralized Paths Module
+ *
+ * Single source of truth for all filesystem paths used by memory.
+ * Respects XDG Base Directory Specification with correct fallbacks.
+ *
+ * Config paths: $XDG_CONFIG_HOME/memory (default: ~/.config/memory)
+ * Data paths:   $XDG_DATA_HOME/memory  (default: ~/.local/share/memory)
+ * Legacy memory files: $MEMORY_HOME   (default: ~/.memory)
+ * Legacy path:  ~/.memory-nexus (for migration detection; not overridable)
+ */
+/**
+ * Get the configuration directory.
+ *
+ * Resolution order:
+ * 1. $XDG_CONFIG_HOME/memory (if XDG_CONFIG_HOME set)
+ * 2. ~/.config/memory (default)
+ *
+ * @returns Absolute path to the config directory
+ */
+export declare function getConfigDir(): string;
+/**
+ * Get the data directory.
+ *
+ * Resolution order:
+ * 1. $XDG_DATA_HOME/memory (if XDG_DATA_HOME set)
+ * 2. ~/.local/share/memory (default)
+ *
+ * @returns Absolute path to the data directory
+ */
+export declare function getDataDir(): string;
+/**
+ * Get the legacy directory path.
+ *
+ * Always returns ~/.memory-nexus regardless of XDG vars or test overrides.
+ * Used solely for migration detection.
+ *
+ * @returns Absolute path to the legacy directory
+ */
+export declare function getLegacyDir(): string;
+/**
+ * Get the memory directory path.
+ *
+ * Returns the directory where agent-written markdown files are stored
+ * (DECISIONS.md, LEARNINGS.md, USER-PREFS.md, daily logs, per-project notes).
+ * Not under XDG -- this is a content directory authored directly by the user
+ * and Claude, separate from the tool's own config/data.
+ *
+ * Resolution order:
+ * 1. $MEMORY_HOME (if set and non-empty)
+ * 2. ~/.memory (default)
+ *
+ * Env-var semantics (GNUPGHOME / JAVA_HOME tradition: exact tool-root path,
+ * NOT the XDG_*_HOME "base + APP_NAME" convention):
+ *  - $MEMORY_HOME=/foo means the memory dir IS /foo, not /foo/memory
+ *  - empty string is ignored (falls through to default)
+ *  - no `~` expansion -- pass an absolute or fully-resolved path
+ *  - relative paths are used as-is and resolved by the consuming syscall
+ *
+ * Use cases for $MEMORY_HOME (production, beyond tests):
+ *  - sandboxed runs where you don't want to touch the user's real ~/.memory
+ *  - container/CI workflows that need a writable location under a chosen mount
+ *  - multi-instance setups (e.g., per-profile development)
+ *
+ * @returns Absolute path to the memory directory
+ */
+export declare function getMemoryDir(): string;
+/**
+ * Get the path to the config file.
+ *
+ * @returns Absolute path to config.json
+ */
+export declare function getConfigPath(): string;
+/**
+ * Get the path to the database file.
+ *
+ * @returns Absolute path to memory.db
+ */
+export declare function getDbPath(): string;
+/**
+ * Get the path to the logs directory.
+ *
+ * @returns Absolute path to the logs directory
+ */
+export declare function getLogDir(): string;
+/**
+ * Get the path to the hooks directory.
+ *
+ * @returns Absolute path to the hooks directory
+ */
+export declare function getHookDir(): string;
+/**
+ * Get the path to the backups directory.
+ *
+ * @returns Absolute path to the backups directory
+ */
+export declare function getBackupDir(): string;
+/**
+ * Get the path to the sync checkpoint file.
+ *
+ * @returns Absolute path to sync-checkpoint.json
+ */
+export declare function getCheckpointPath(): string;
+/**
+ * Get the path to the events directory.
+ *
+ * @returns Absolute path to the events directory
+ */
+export declare function getEventsDir(): string;
+/**
+ * Get the path to the event log file.
+ *
+ * @returns Absolute path to events.jsonl
+ */
+export declare function getEventLogPath(): string;
+/**
+ * Get the path to a machine-specific event log file.
+ *
+ * @param machineId The unique identifier of the machine
+ * @returns Absolute path to events-<machineId>.jsonl
+ */
+export declare function getMachineLogPath(machineId: string): string;
+/**
+ * Get all event log files (both machine-specific events-*.jsonl and legacy events.jsonl).
+ *
+ * @param eventsDir Optional directory override (primarily for test isolation)
+ * @returns Array of absolute paths to event log files
+ */
+export declare function getAllLogFiles(eventsDir?: string): string[];

package/dist/infrastructure/providers/provider-defaults.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Provider defaults shared by configuration loading and provider registry.
+ *
+ * This file intentionally contains only data. It lets config-manager apply
+ * provider-specific embedding defaults without importing provider factories.
+ */
+export declare const EMBEDDING_PROVIDER_DEFAULTS: Record<string, {
+    model: string;
+    dimensions: number;
+}>;
+export declare const EXTRACTION_PROVIDER_DEFAULT_MODELS: Record<string, string>;

package/dist/infrastructure/providers/provider-registry.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Provider Registry
+ *
+ * Internal registry for runtime provider capabilities. This is deliberately
+ * not an external plugin loader: provider support is explicit, testable, and
+ * wired through typed factories.
+ */
+import type { IEmbeddingProvider } from "../../domain/ports/embedding.js";
+import type { IExtractionProvider } from "../../domain/ports/extraction.js";
+import type { EmbeddingConfigData, MemoryConfig } from "../hooks/config-manager.js";
+export interface ProviderReadiness {
+    ready: boolean;
+    readyReason?: string | undefined;
+}
+export declare function listEmbeddingProviderIds(): string[];
+export declare function listExtractionProviderIds(): string[];
+export declare function unsupportedEmbeddingProviderMessage(providerId: string): string;
+export declare function unsupportedExtractionProviderMessage(providerId: string): string;
+export declare function getEmbeddingProviderDefaults(providerId: string): {
+    model: string;
+    dimensions: number;
+} | undefined;
+export declare function checkEmbeddingProviderReadiness(config: EmbeddingConfigData): ProviderReadiness;
+export declare function createEmbeddingProvider(config: EmbeddingConfigData): IEmbeddingProvider;
+export declare function resolveExtractionProviderId(config: Pick<MemoryConfig, "embedding">, env?: NodeJS.ProcessEnv): string;
+export declare function getExtractionModel(_config: Pick<MemoryConfig, "embedding">, providerId: string, env?: NodeJS.ProcessEnv): string;
+export declare function checkExtractionProviderReadiness(config: Pick<MemoryConfig, "embedding">, providerId?: string): ProviderReadiness;
+export declare function createExtractionProvider(config: Pick<MemoryConfig, "embedding">): IExtractionProvider;

package/dist/infrastructure/security/pattern-redactor.d.ts

@@ -0,0 +1,6 @@
+import type { IRedactor, JsonRedactionResult, RedactionResult } from "../../domain/ports/redactor.js";
+export declare class PatternRedactor implements IRedactor {
+    redactText(input: string): RedactionResult;
+    redactJson<T>(input: T): JsonRedactionResult<T>;
+    private redactUnknown;
+}

package/dist/infrastructure/signals/adapters.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Domain Port Adapters for Signal Infrastructure
+ *
+ * Wraps free functions from signal-handler and checkpoint-manager
+ * into class-based adapters implementing domain port interfaces.
+ */
+import type { ISyncAbortSignal, ICheckpointManager, SyncCheckpoint } from "../../domain/ports/signals.js";
+/**
+ * Adapter wrapping the process signal handler's shouldAbort() function.
+ */
+export declare class ProcessAbortSignal implements ISyncAbortSignal {
+    shouldAbort(): boolean;
+}
+/**
+ * Adapter wrapping the filesystem checkpoint manager functions.
+ *
+ * @param path Optional explicit checkpoint file path. When omitted, the
+ *   production XDG-resolved path is used. Tests construct with a temp
+ *   path to achieve isolation without process-wide state.
+ */
+export declare class FileCheckpointManager implements ICheckpointManager {
+    private readonly path?;
+    constructor(path?: string | undefined);
+    load(): SyncCheckpoint | null;
+    save(checkpoint: SyncCheckpoint): void;
+    clear(): void;
+}

package/dist/infrastructure/signals/checkpoint-manager.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Checkpoint Manager
+ *
+ * Manages sync progress checkpointing for recovery from interrupted syncs.
+ * Checkpoints stored in ~/.memory-nexus/sync-checkpoint.json
+ *
+ * Implements graceful handling of missing/invalid checkpoint files.
+ *
+ * Each function accepts an optional `path` argument. When omitted, the
+ * production XDG-resolved path is used. When provided, that path is used
+ * directly (used by tests to point at a temp file). This avoids
+ * module-level mutable state and the test-pollution risk that comes with
+ * it; see scripts/check-test-isolation.ts.
+ */
+/**
+ * Sync checkpoint interface
+ *
+ * Tracks progress of an interrupted sync operation:
+ * - startedAt: When the sync began (ISO timestamp)
+ * - totalSessions: Total number of sessions to sync
+ * - completedSessions: Number of sessions completed
+ * - completedSessionIds: List of completed session IDs for filtering
+ * - lastCompletedAt: When last session was completed (ISO timestamp, null if none)
+ */
+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;
+}
+/**
+ * Get the path to the checkpoint file.
+ *
+ * @param override Optional explicit path (used by tests). When omitted,
+ *   resolves via the production paths module (XDG-respecting).
+ * @returns Path to sync-checkpoint.json
+ */
+export declare function getCheckpointPath(override?: string): string;
+/**
+ * Save checkpoint to disk
+ *
+ * Creates the directory if it doesn't exist.
+ * Handles errors gracefully (logs but doesn't throw).
+ *
+ * @param checkpoint Checkpoint data to save
+ * @param path Optional explicit path (used by tests)
+ */
+export declare function saveCheckpoint(checkpoint: SyncCheckpoint, path?: string): void;
+/**
+ * Load checkpoint from disk
+ *
+ * Gracefully handles:
+ * - Missing checkpoint file (returns null)
+ * - Invalid JSON (returns null with warning)
+ *
+ * @param path Optional explicit path (used by tests)
+ * @returns Checkpoint data or null if not found/invalid
+ */
+export declare function loadCheckpoint(path?: string): SyncCheckpoint | null;
+/**
+ * Clear checkpoint from disk
+ *
+ * Called on successful sync completion.
+ * Silently ignores missing file.
+ *
+ * @param path Optional explicit path (used by tests)
+ */
+export declare function clearCheckpoint(path?: string): void;
+/**
+ * Check if a checkpoint exists
+ *
+ * Quick existence check without loading the file.
+ *
+ * @param path Optional explicit path (used by tests)
+ * @returns true if checkpoint file exists
+ */
+export declare function hasCheckpoint(path?: string): boolean;

package/dist/infrastructure/signals/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Signals Module
+ *
+ * Signal handling and checkpoint management for graceful shutdown.
+ */
+export * from "./checkpoint-manager.js";
+export * from "./signal-handler.js";
+export { ProcessAbortSignal, FileCheckpointManager } from "./adapters.js";

package/dist/infrastructure/signals/signal-handler.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Signal Handler
+ *
+ * Handles SIGINT (Ctrl+C) and SIGTERM for graceful shutdown.
+ * Provides 3-option prompt on first interrupt, force exit on second.
+ *
+ * Usage:
+ * 1. Call setupSignalHandlers() at CLI startup
+ * 2. Register cleanup functions with registerCleanup()
+ * 3. Check shouldAbort() in long-running loops
+ * 4. Unregister cleanups on successful completion
+ */
+/**
+ * Set TTY override for testing
+ *
+ * @param isTTY Value to use, or null to use actual stdin.isTTY
+ */
+export declare function setTtyOverride(isTTY: boolean | null): void;
+/**
+ * Set process exit override for testing
+ *
+ * @param exitFn Function to call instead of process.exit, or null for actual
+ */
+export declare function setExitOverride(exitFn: ((code: number) => void) | null): void;
+/**
+ * Set up signal handlers for SIGINT and SIGTERM
+ *
+ * Safe to call multiple times (handlers only registered once).
+ * SIGINT: Ctrl+C
+ * SIGTERM: Kill signal (e.g., from process manager)
+ */
+export declare function setupSignalHandlers(): void;
+/**
+ * Check if shutdown has been requested
+ *
+ * Long-running operations should check this periodically
+ * and exit gracefully when true.
+ *
+ * @returns true if shutdown requested
+ */
+export declare function shouldAbort(): boolean;
+/**
+ * Register a cleanup function
+ *
+ * Cleanup functions are called before exit, in registration order.
+ * Use for closing database connections, saving state, etc.
+ *
+ * @param fn Async function to call on shutdown
+ */
+export declare function registerCleanup(fn: () => Promise<void>): void;
+/**
+ * Unregister a cleanup function
+ *
+ * Call when a resource has been properly closed/released.
+ *
+ * @param fn Function to remove from cleanup list
+ */
+export declare function unregisterCleanup(fn: () => Promise<void>): void;
+/**
+ * Reset all signal handler state
+ *
+ * For testing purposes only.
+ * Note: Does not unregister process signal handlers.
+ */
+export declare function resetState(): void;
+/**
+ * Set shutdown state directly
+ *
+ * For testing purposes only.
+ *
+ * @param shutting Whether to set shutdown state
+ */
+export declare function setShuttingDown(shutting: boolean): void;
+/**
+ * Get current interrupt count
+ *
+ * For testing purposes only.
+ *
+ * @returns Number of interrupt signals received
+ */
+export declare function getInterruptCount(): number;
+/**
+ * Increment interrupt count
+ *
+ * For testing purposes only.
+ */
+export declare function incrementInterruptCount(): void;
+/**
+ * Get cleanup function count
+ *
+ * For testing purposes only.
+ *
+ * @returns Number of registered cleanup functions
+ */
+export declare function getCleanupCount(): number;
+/**
+ * Trigger signal handling directly.
+ *
+ * For testing purposes only.
+ */
+export declare function handleSignalForTesting(): Promise<void>;
+/**
+ * Trigger choice handling directly.
+ *
+ * For testing purposes only.
+ */
+export declare function handleChoiceForTesting(choice: 1 | 2 | 3): Promise<void>;
+/**
+ * Run registered cleanups directly.
+ *
+ * For testing purposes only.
+ */
+export declare function runCleanupsForTesting(): Promise<void>;

package/dist/infrastructure/sources/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Source Infrastructure
+ *
+ * Adapters for discovering and accessing Claude Code session files.
+ */
+export { FileSystemSessionSource, type SessionSourceOptions, } from "./session-source.js";
+export { ProjectNameResolver } from "./project-name-resolver.js";
+export { MemoryFileScanner } from "./memory-file-scanner.js";