@chude/memory 4.0.0

package/dist/application/services/pattern-extractor.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Pattern Extractor Service
+ *
+ * Extracts file paths and tool usage statistics from tool uses
+ * using pattern matching (not LLM-based extraction).
+ */
+import type { ToolUse } from "../../domain/entities/tool-use.js";
+import { Entity } from "../../domain/entities/entity.js";
+/**
+ * Represents a file modification operation
+ */
+export interface FileModification {
+    /** The file path that was modified */
+    path: string;
+    /** The type of modification operation */
+    operation: "Write" | "Edit" | "NotebookEdit";
+    /** When the modification occurred */
+    timestamp: Date;
+}
+/**
+ * Statistics for a specific tool
+ */
+export interface ToolStats {
+    /** The tool name */
+    name: string;
+    /** Total number of invocations */
+    count: number;
+    /** Number of successful invocations */
+    successCount: number;
+    /** Number of failed invocations */
+    errorCount: number;
+}
+/**
+ * Pattern-based extractor for file paths and tool statistics.
+ *
+ * Provides static methods for extracting structured data from tool uses
+ * without requiring LLM inference.
+ */
+export declare class PatternExtractor {
+    /**
+     * Extract file paths from tool uses.
+     *
+     * Handles:
+     * - Read, Write, Edit tools (input.file_path)
+     * - Glob, Grep tools (input.path)
+     * - Glob results (newline-separated file paths in result)
+     *
+     * @param toolUses Array of tool uses to extract from
+     * @returns Deduplicated array of file paths
+     */
+    static extractFilePaths(toolUses: ToolUse[]): string[];
+    /**
+     * Extract file modifications (Write, Edit, NotebookEdit).
+     *
+     * Only includes successful operations.
+     *
+     * @param toolUses Array of tool uses to extract from
+     * @returns Array of file modifications with operation type
+     */
+    static extractFileModifications(toolUses: ToolUse[]): FileModification[];
+    /**
+     * Extract tool usage statistics.
+     *
+     * Groups by tool name with success/error counts.
+     *
+     * @param toolUses Array of tool uses to extract from
+     * @returns Array of tool statistics
+     */
+    static extractToolStats(toolUses: ToolUse[]): ToolStats[];
+    /**
+     * Extract unique tool names used in session.
+     *
+     * @param toolUses Array of tool uses to extract from
+     * @returns Array of unique tool names
+     */
+    static extractToolNames(toolUses: ToolUse[]): string[];
+    /**
+     * Convert extracted file paths to Entity objects.
+     *
+     * File paths become 'file' entities with path as name.
+     *
+     * @param paths Array of file paths
+     * @returns Array of file Entity objects
+     */
+    static toFileEntities(paths: string[]): Entity[];
+    /**
+     * Convert file modifications to Entity objects with metadata.
+     *
+     * Includes operation type in metadata.
+     *
+     * @param modifications Array of file modifications
+     * @returns Array of file Entity objects with metadata
+     */
+    static toFileModificationEntities(modifications: FileModification[]): Entity[];
+}

package/dist/application/services/recovery-service.d.ts

@@ -0,0 +1,81 @@
+/**
+ * RecoveryService
+ *
+ * Detects sessions that haven't been synced and optionally syncs them.
+ * Useful for crash recovery when hooks failed or were disabled.
+ *
+ * Features:
+ * - Scan for pending sessions (not synced or incomplete)
+ * - Dry run mode for reporting without syncing
+ * - Limit sync count for controlled recovery
+ * - Integration with config for recoveryOnStartup setting
+ */
+import type { ISessionSource } from "../../domain/ports/sources.js";
+import type { IExtractionStateRepository } from "../../domain/ports/repositories.js";
+import type { ISyncLogger } from "../../domain/ports/signals.js";
+import type { SyncService } from "./sync-service.js";
+/**
+ * Result of a recovery operation
+ */
+export interface RecoveryResult {
+    /** Paths of sessions that haven't been synced */
+    pendingSessions: string[];
+    /** Number of sessions successfully synced */
+    syncedSessions: number;
+    /** Errors encountered during sync */
+    errors: Array<{
+        sessionPath: string;
+        error: string;
+    }>;
+    /** True if recovery was skipped due to config */
+    skipped: boolean;
+}
+/**
+ * Options for recovery operation
+ */
+export interface RecoveryOptions {
+    /** Just report pending, don't sync */
+    dryRun?: boolean;
+    /** Limit number of sessions to sync */
+    maxSessions?: number;
+}
+/**
+ * Service for detecting and recovering unsynced sessions.
+ *
+ * Called on startup when recoveryOnStartup is enabled, or manually
+ * via CLI. Useful for crash recovery when hooks failed.
+ */
+export declare class RecoveryService {
+    private readonly sessionSource;
+    private readonly extractionStateRepo;
+    private readonly syncService;
+    private readonly syncLogger;
+    private readonly recoveryEnabled;
+    constructor(sessionSource: ISessionSource, extractionStateRepo: IExtractionStateRepository, syncService: SyncService, syncLogger: ISyncLogger, recoveryEnabled: boolean);
+    /**
+     * Check for sessions that haven't been synced and optionally sync them.
+     *
+     * Called on startup when recoveryOnStartup is enabled, or manually
+     * via CLI. Useful for crash recovery when hooks failed.
+     *
+     * @param options Recovery options
+     * @returns Recovery result with pending sessions and sync counts
+     */
+    recover(options?: RecoveryOptions): Promise<RecoveryResult>;
+    /**
+     * Get count of pending sessions without syncing.
+     * Fast operation for status display.
+     *
+     * @returns Number of sessions not yet synced
+     */
+    getPendingCount(): Promise<number>;
+}
+/**
+ * Extract session ID from a session file path.
+ *
+ * Handles both Unix and Windows path separators.
+ *
+ * @param sessionPath Full path to session JSONL file
+ * @returns Session ID (filename without .jsonl extension)
+ */
+export declare function extractSessionId(sessionPath: string): string;

package/dist/application/services/rrf-fusion.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Reciprocal Rank Fusion
+ *
+ * Pure function implementing RRF to combine ranked result lists
+ * from FTS5 and vector search. Uses rank positions (not raw scores)
+ * to avoid score normalization problems between rankers.
+ *
+ * Formula: score(d) = sum(1 / (k + rank_i(d))) for each ranker i
+ * Reference: Cormack, Clarke, Buettcher (2009)
+ */
+/**
+ * A candidate from a single ranker with its rank position.
+ */
+export interface RankedCandidate {
+    /** The message rowid */
+    rowid: number;
+    /** Rank position (1 = best match) */
+    rank: number;
+    /** Which ranker produced this candidate */
+    source: "fts" | "vector";
+    /** Raw score from the ranker (BM25 or cosine distance) */
+    rawScore: number;
+}
+/**
+ * A fused result after RRF combining multiple ranker outputs.
+ */
+export interface FusedResult {
+    /** The message rowid */
+    rowid: number;
+    /** Raw RRF score (sum of 1/(k+rank) across rankers) */
+    rrfScore: number;
+    /** Normalized score (0-1, highest RRF maps to 1.0) */
+    normalizedScore: number;
+    /** Sources that contributed to this result with their rank and raw score */
+    sources: Array<{
+        source: "fts" | "vector";
+        rank: number;
+        rawScore: number;
+    }>;
+}
+/**
+ * Combine ranked result lists using Reciprocal Rank Fusion.
+ *
+ * Takes pre-ranked candidates from FTS5 and vector search,
+ * computes RRF scores, filters noise, normalizes to 0-1,
+ * and returns the top results.
+ *
+ * @param ftsResults Ranked candidates from FTS5 (rank 1 = best BM25)
+ * @param vectorResults Ranked candidates from vector search (rank 1 = lowest distance)
+ * @param limit Maximum number of results to return
+ * @returns Fused results sorted by RRF score descending, normalized to 0-1
+ */
+export declare function reciprocalRankFusion(ftsResults: RankedCandidate[], vectorResults: RankedCandidate[], limit: number): FusedResult[];

package/dist/application/services/smart-context-service.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Smart Context Service
+ *
+ * Application-layer service that composes memory files, friction entries,
+ * and session data into structured briefings. Produces ordered sections
+ * with priority-based token budget allocation.
+ *
+ * Data source priority (1 = highest):
+ * 1. Active Decisions (project DECISIONS.md)
+ * 2. Recent Learnings (project LEARNINGS.md)
+ * 3. Recent Activity (daily log files)
+ * 4. Cross-Project Decisions (global DECISIONS.md, when crossProject=true)
+ * 5. Cross-Project Learnings (tagged learnings, when crossProject=true)
+ * 6. Open Friction (filtered by project when possible)
+ * 7. Session Summary (legacy fallback)
+ *
+ * Dependencies injected via constructor for hexagonal architecture.
+ * Zero imports from infrastructure layer.
+ */
+import type { IFactRepository, IFrictionRepository } from "../../domain/ports/repositories.js";
+/**
+ * Options for smart context retrieval.
+ */
+export interface SmartContextOptions {
+    /** Project name or filter string */
+    projectFilter: string;
+    /** Maximum token budget (0 or undefined = no limit) */
+    budget?: number | undefined;
+    /** Limit daily logs to last N days */
+    days?: number | undefined;
+    /** Include cross-project sections (default: false) */
+    crossProject?: boolean | undefined;
+}
+/**
+ * Result of smart context retrieval.
+ */
+export interface SmartContextResult {
+    /** Resolved project display name */
+    projectName: string;
+    /** Resolved encoded project path (null if not found) */
+    projectEncoded: string | null;
+    /** Ordered context sections */
+    sections: ContextSection[];
+    /** Total estimated tokens across all sections */
+    totalTokensEstimate: number;
+    /** Whether any section was truncated due to budget */
+    truncated: boolean;
+}
+/**
+ * A single section of context output.
+ */
+export interface ContextSection {
+    /** Section identifier */
+    key: string;
+    /** Human-readable section title */
+    title: string;
+    /** Priority (1 = highest) */
+    priority: number;
+    /** Section content text */
+    content: string;
+    /** Whether this section was truncated */
+    truncated: boolean;
+    /** Estimated token count for this section */
+    tokenEstimate: number;
+}
+/**
+ * Port for resolving project names to encoded paths.
+ */
+export interface IProjectResolver {
+    /**
+     * Resolve a human-readable project name to its encoded path.
+     * Returns null if no sessions match the project name.
+     */
+    resolveProjectEncoded(projectFilter: string): string | null;
+    /**
+     * Get the display name for a resolved project.
+     */
+    resolveProjectName(projectFilter: string): string | null;
+}
+/**
+ * Dependencies for SmartContextService (constructor injection).
+ */
+export interface SmartContextDeps {
+    projectResolver: IProjectResolver;
+    factRepo: IFactRepository;
+    frictionRepo: IFrictionRepository;
+    /** Optional legacy session summary provider */
+    getSessionSummary?: (projectFilter: string, days?: number) => Promise<string | null>;
+    now?: () => Date;
+}
+/**
+ * Smart Context Service.
+ *
+ * Composes data from facts, friction entries, and legacy session
+ * data into structured briefings with optional token budget allocation.
+ */
+export declare class SmartContextService {
+    private readonly projectResolver;
+    private readonly factRepo;
+    private readonly frictionRepo;
+    private readonly getSessionSummary?;
+    constructor(deps: SmartContextDeps);
+    /**
+     * Get structured context for a project.
+     *
+     * Resolves the project, assembles sections from available data sources
+     * in priority order, and optionally applies token budget allocation.
+     *
+     * @param options Context retrieval options
+     * @returns SmartContextResult or null if project not found
+     */
+    getContext(options: SmartContextOptions): Promise<SmartContextResult | null>;
+    /**
+     * Build a context section from content.
+     */
+    private buildSection;
+    /**
+     * Build friction section content from open entries.
+     * Returns null if no friction entries exist.
+     */
+    private buildFrictionContent;
+    /**
+     * Apply budget allocation and return result with truncation info.
+     */
+    private applyBudget;
+}

package/dist/application/services/sync-service.d.ts

@@ -0,0 +1,157 @@
+/**
+ * SyncService Application Layer
+ *
+ * Orchestrates session discovery, parsing, and storage for the sync workflow.
+ * Implements incremental sync detection using file mtime and size comparison.
+ *
+ * Per-session transaction boundary ensures atomicity and error isolation.
+ * Supports checkpoint-based recovery from interrupted syncs.
+ */
+import type { Database } from "bun:sqlite";
+import type { ISessionSource, IEventParser, IProjectNameResolver, ISyncAbortSignal, ICheckpointManager, IRedactor } from "../../domain/ports/index.js";
+import type { ISessionRepository, IMessageRepository, IToolUseRepository, IExtractionStateRepository } from "../../domain/ports/repositories.js";
+/**
+ * Options for controlling sync behavior
+ */
+export interface SyncOptions {
+    /** Re-extract all sessions regardless of state */
+    force?: boolean;
+    /** Filter by project path substring */
+    projectFilter?: string;
+    /** Sync specific session only */
+    sessionFilter?: string;
+    /** Progress callback invoked for each session */
+    onProgress?: (progress: SyncProgress) => void;
+    /** Enable checkpoint-based recovery (default: true) */
+    checkpointEnabled?: boolean;
+    /** Callback invoked after each session completes */
+    onSessionComplete?: (sessionId: string) => void;
+}
+/**
+ * Progress information for sync operations
+ */
+export interface SyncProgress {
+    /** Current session index (1-based) */
+    current: number;
+    /** Total sessions to process */
+    total: number;
+    /** Current session being processed */
+    sessionId: string;
+    /** Current phase of sync */
+    phase: "discovering" | "extracting" | "complete";
+}
+/**
+ * Result of a sync operation
+ */
+export interface SyncResult {
+    /** Overall success (true if no errors) */
+    success: boolean;
+    /** Total sessions found */
+    sessionsDiscovered: number;
+    /** Sessions successfully processed */
+    sessionsProcessed: number;
+    /** Sessions skipped (already up-to-date) */
+    sessionsSkipped: number;
+    /** Total messages inserted */
+    messagesInserted: number;
+    /** Total tool uses inserted */
+    toolUsesInserted: number;
+    /** Errors encountered during sync */
+    errors: Array<{
+        sessionPath: string;
+        error: string;
+    }>;
+    /** Duration in milliseconds */
+    durationMs: number;
+    /** Whether sync was aborted via signal */
+    aborted?: boolean;
+    /** Number of sessions recovered from checkpoint */
+    recoveredFromCheckpoint?: number;
+}
+/**
+ * Application service that orchestrates the sync workflow.
+ *
+ * Responsibilities:
+ * - Discover sessions via ISessionSource
+ * - Filter sessions based on options
+ * - Detect sessions needing extraction (incremental sync)
+ * - Parse events via IEventParser
+ * - Extract messages and tool uses from events
+ * - Persist to repositories within per-session transactions
+ * - Track extraction state for incremental sync
+ * - Support checkpoint-based recovery from interruption
+ */
+export declare class SyncService {
+    private readonly sessionSource;
+    private readonly eventParser;
+    private readonly sessionRepo;
+    private readonly messageRepo;
+    private readonly toolUseRepo;
+    private readonly extractionStateRepo;
+    private readonly db;
+    private readonly abortSignal;
+    private readonly checkpointManager;
+    private readonly redactor;
+    constructor(sessionSource: ISessionSource, eventParser: IEventParser, sessionRepo: ISessionRepository, messageRepo: IMessageRepository, toolUseRepo: IToolUseRepository, extractionStateRepo: IExtractionStateRepository, db: Database, abortSignal: ISyncAbortSignal, checkpointManager: ICheckpointManager, redactor?: IRedactor);
+    /**
+     * Sync sessions to the database.
+     *
+     * Discovers all sessions, applies filters, checks for changes,
+     * and extracts sessions that need processing. Each session is
+     * processed in its own transaction for error isolation.
+     *
+     * Supports checkpoint-based recovery from interrupted syncs.
+     * Respects abort signals for graceful shutdown.
+     *
+     * @param options Configuration for sync behavior
+     * @returns Result with counts and any errors
+     */
+    sync(options?: SyncOptions): Promise<SyncResult>;
+    /**
+     * Fix project names in existing sessions by resolving them via filesystem lookup.
+     *
+     * Queries all distinct encoded project paths from the database, resolves the
+     * correct project name for each via the filesystem resolver, and updates
+     * all sessions with that encoded path.
+     *
+     * @param resolver The filesystem-based project name resolver
+     * @returns Total number of session rows updated
+     */
+    fixProjectNames(resolver: IProjectNameResolver): Promise<number>;
+    /**
+     * Wrap an error in MemoryError with appropriate code and context.
+     */
+    private wrapError;
+    /**
+     * Filter sessions based on options and extraction state.
+     *
+     * Applies projectFilter and sessionFilter, then checks extraction
+     * state to skip sessions that are already up-to-date.
+     */
+    private filterSessions;
+    /**
+     * Determine if a session needs extraction.
+     *
+     * A session needs extraction if:
+     * - force=true
+     * - No existing extraction state
+     * - Existing state is not "complete"
+     * - File metadata has changed (mtime or size differs)
+     * - Stored metadata is null (legacy state)
+     */
+    private needsExtraction;
+    /**
+     * Extract a single session within a transaction.
+     *
+     * Parses events, creates entities, and persists everything atomically.
+     * On error, saves error state and re-throws.
+     */
+    private extractSession;
+    /**
+     * Extract Message and ToolUse entities from parsed events.
+     *
+     * Iterates through events and creates domain entities for
+     * user messages, assistant messages, and tool uses with results.
+     */
+    private extractEntities;
+}

package/dist/application/services/temporal-decay.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Temporal Decay
+ *
+ * Pure function applying exponential time-based decay to search scores.
+ * Recent results are ranked higher than older results.
+ *
+ * Formula: finalScore = score * 0.5^(ageDays / halfLifeDays)
+ * Inspired by OpenClaw's memory decay pattern.
+ */
+/**
+ * A result with a score that can be decayed.
+ */
+export interface DecayableResult {
+    /** The message rowid */
+    rowid: number;
+    /** The base score before decay */
+    score: number;
+}
+/**
+ * A result after temporal decay has been applied.
+ */
+export interface DecayedResult extends DecayableResult {
+    /** The score after temporal decay */
+    decayedScore: number;
+}
+/**
+ * Apply temporal decay to search results based on message age.
+ *
+ * Messages closer to `now` retain more of their score.
+ * Messages without a timestamp in the map are unaffected.
+ * Results are re-sorted by decayed score descending.
+ *
+ * @param results Array of results with base scores
+ * @param timestamps Map of rowid to message timestamp
+ * @param halfLifeDays Number of days for score to halve (default 30)
+ * @param now Reference time for age calculation (default: current time)
+ * @returns Results with decayedScore, sorted descending
+ */
+export declare function applyTemporalDecay<T extends DecayableResult>(results: T[], timestamps: Map<number, Date>, halfLifeDays?: number, now?: Date): Array<T & {
+    decayedScore: number;
+}>;
+/**
+ * Memory file types exempt from temporal decay.
+ * These files contain evergreen knowledge that remains relevant regardless of age.
+ */
+export declare const CURATED_FILE_TYPES: readonly string[];
+/**
+ * Apply temporal decay with exemptions for curated content.
+ *
+ * Identical to applyTemporalDecay but skips decay for rowids in the
+ * exemptions set. Exempt results retain their original score.
+ *
+ * @param results Array of results with base scores
+ * @param timestamps Map of rowid to message timestamp
+ * @param exemptRowids Set of rowids that should not be decayed
+ * @param halfLifeDays Number of days for score to halve (default 30)
+ * @param now Reference time for age calculation (default: current time)
+ * @returns Results with decayedScore, sorted descending
+ */
+export declare function applyTemporalDecayWithExemptions<T extends DecayableResult>(results: T[], timestamps: Map<number, Date>, exemptRowids: Set<number>, halfLifeDays?: number, now?: Date): Array<T & {
+    decayedScore: number;
+}>;

package/dist/domain/entities/backfill-state.d.ts

@@ -0,0 +1,56 @@
+/**
+ * BackfillState Entity
+ *
+ * Tracks the state of backfilling a session (generating daily log via Agent SDK).
+ * Enables idempotent backfill: processed sessions are skipped on re-run.
+ *
+ * Entity properties:
+ * - Has unique identity (sessionId)
+ * - Immutable after construction
+ * - Two terminal states: success or error (no lifecycle transitions)
+ */
+interface BackfillStateParams {
+    sessionId: string;
+    backfilledAt: Date;
+    dailyLogPath: string;
+    success?: boolean | undefined;
+    errorMessage?: string | undefined;
+}
+export declare class BackfillState {
+    private readonly _sessionId;
+    private readonly _backfilledAt;
+    private readonly _dailyLogPath;
+    private readonly _success;
+    private readonly _errorMessage?;
+    private constructor();
+    /**
+     * Create a BackfillState entity.
+     * @throws Error if sessionId or dailyLogPath is empty
+     */
+    static create(params: BackfillStateParams): BackfillState;
+    /**
+     * The session UUID that was backfilled.
+     */
+    get sessionId(): string;
+    /**
+     * When the backfill was performed.
+     */
+    get backfilledAt(): Date;
+    /**
+     * Path to the daily log file produced by backfill.
+     */
+    get dailyLogPath(): string;
+    /**
+     * Whether the backfill succeeded.
+     */
+    get success(): boolean;
+    /**
+     * Error message if the backfill failed.
+     */
+    get errorMessage(): string | undefined;
+    /**
+     * Convenience getter: whether the backfill succeeded.
+     */
+    get isSuccess(): boolean;
+}
+export {};