@chude/memory 4.0.0

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

@@ -0,0 +1,225 @@
+/**
+ * Export/Import Service
+ *
+ * Provides database backup and restore functionality through JSON serialization.
+ * Supports full database export, validation, and import with round-trip integrity.
+ */
+import type { Database } from "bun:sqlite";
+import type { IRedactor } from "../../domain/ports/redactor.js";
+/**
+ * Exported session data structure.
+ */
+export interface SessionExport {
+    id: string;
+    projectPathEncoded: string;
+    projectPathDecoded: string;
+    projectName: string;
+    startTime: string;
+    endTime: string | null;
+    messageCount: number;
+    summary: string | null;
+}
+/**
+ * Exported message data structure.
+ */
+export interface MessageExport {
+    id: string;
+    sessionId: string;
+    role: "user" | "assistant";
+    content: string;
+    timestamp: string;
+    toolUseIds: string | null;
+}
+/**
+ * Exported tool use data structure.
+ */
+export interface ToolUseExport {
+    id: string;
+    sessionId: string;
+    name: string;
+    input: string;
+    timestamp: string;
+    status: string;
+    result: string | null;
+}
+/**
+ * Exported entity data structure.
+ */
+export interface EntityExport {
+    id: number;
+    type: string;
+    name: string;
+    metadata: string | null;
+    confidence: number;
+}
+/**
+ * Exported link data structure.
+ */
+export interface LinkExport {
+    sourceType: string;
+    sourceId: string;
+    targetType: string;
+    targetId: string;
+    relationship: string;
+    weight: number;
+}
+/**
+ * Exported session-entity relationship.
+ */
+export interface SessionEntityExport {
+    sessionId: string;
+    entityId: number;
+    frequency: number;
+}
+/**
+ * Exported entity-entity relationship.
+ */
+export interface EntityLinkExport {
+    sourceId: number;
+    targetId: number;
+    relationship: string;
+    weight: number;
+}
+/**
+ * Exported extraction state.
+ */
+export interface ExtractionStateExport {
+    id: string;
+    sessionPath: string;
+    startedAt: string;
+    status: string;
+    completedAt: string | null;
+    messagesExtracted: number;
+    errorMessage: string | null;
+    fileMtime: string | null;
+    fileSize: number | null;
+}
+/**
+ * Exported fact data structure.
+ */
+export interface FactExport {
+    uuid: string;
+    type: string;
+    project: string;
+    content: string;
+    metadata: string | null;
+    observedAt: string;
+    supersededAt: string | null;
+    supersededBy: string | null;
+}
+/**
+ * Complete export data structure with version and statistics.
+ */
+export interface ExportData {
+    version: string;
+    exportedAt: string;
+    stats: {
+        sessions: number;
+        messages: number;
+        toolUses: number;
+        entities: number;
+        links: number;
+        sessionEntities: number;
+        entityLinks: number;
+        extractionStates: number;
+        facts?: number;
+    };
+    sessions: SessionExport[];
+    messages: MessageExport[];
+    toolUses: ToolUseExport[];
+    entities: EntityExport[];
+    links: LinkExport[];
+    sessionEntities: SessionEntityExport[];
+    entityLinks: EntityLinkExport[];
+    extractionStates: ExtractionStateExport[];
+    facts?: FactExport[];
+}
+/**
+ * Export operation result statistics.
+ */
+export interface ExportStats {
+    sessions: number;
+    messages: number;
+    toolUses: number;
+    entities: number;
+    links: number;
+    bytes: number;
+    facts?: number;
+}
+/**
+ * Import operation result statistics.
+ */
+export interface ImportStats {
+    sessions: number;
+    messages: number;
+    toolUses: number;
+    entities: number;
+    links: number;
+    facts?: number;
+}
+/**
+ * Validation result for export files.
+ */
+export interface ValidationResult {
+    valid: boolean;
+    version?: string;
+    error?: string;
+}
+/**
+ * Options for import operations.
+ */
+export interface ImportOptions {
+    /** Clear existing data before import. Default: false */
+    clearExisting?: boolean | undefined;
+}
+/**
+ * Options for export operations.
+ */
+export interface ExportToJsonOptions {
+    /** Redactor to apply before writing exported content. */
+    redactor?: IRedactor | undefined;
+    /** Write raw sensitive values. Requires explicit opt-in at the CLI boundary. */
+    includeSensitive?: boolean | undefined;
+}
+/**
+ * Export database contents to a JSON file.
+ *
+ * Queries all data tables and writes a complete backup to the specified path.
+ * The export includes a version field for future compatibility checks.
+ *
+ * @param db - Database connection
+ * @param outputPath - Path to write the JSON file
+ * @returns Statistics about the exported data
+ */
+export declare function exportToJson(db: Database, outputPath: string, options?: ExportToJsonOptions): Promise<ExportStats>;
+/**
+ * Validate an export file before importing.
+ *
+ * Checks that the file exists, contains valid JSON, and has the required
+ * fields and version information.
+ *
+ * @param path - Path to the export file
+ * @returns Validation result with version if valid
+ */
+export declare function validateExportFile(path: string): Promise<ValidationResult>;
+/**
+ * Import data from a JSON export file.
+ *
+ * Validates the file, optionally clears existing data, and inserts all
+ * records from the export. Uses batched inserts within transactions for
+ * performance.
+ *
+ * @param db - Database connection
+ * @param inputPath - Path to the export file
+ * @param options - Import options (clearExisting)
+ * @returns Statistics about the imported data
+ * @throws Error if validation fails
+ */
+export declare function importFromJson(db: Database, inputPath: string, options?: ImportOptions): Promise<ImportStats>;
+/**
+ * Check if database has existing data.
+ *
+ * @param db - Database connection
+ * @returns true if any tables have data
+ */
+export declare function hasExistingData(db: Database): boolean;

package/dist/application/services/extraction-pipeline.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Extraction Pipeline Application Service
+ *
+ * Coordinates the full comparative knowledge extraction workflow:
+ * 1. Validates session extraction idempotency.
+ * 2. Fetches session message history.
+ * 3. Invokes LLM extraction providers to generate candidate facts.
+ * 4. Compares candidate facts to existing active facts using semantic vector cosine
+ *    similarity or a fallback word-level Jaccard similarity.
+ * 5. Appends new fact events and event-sourced supersedence markers to the SSOT.
+ * 6. Dynamic database projection replay to keep SQLite derived projections aligned.
+ * 7. Records the extraction audit log.
+ */
+import type { Database } from "bun:sqlite";
+import type { IExtractionProvider } from "../../domain/ports/extraction.js";
+import type { IEmbeddingProvider } from "../../domain/ports/embedding.js";
+import type { IRedactor } from "../../domain/ports/redactor.js";
+import type { IFactRepository, IExtractionLogRepository, IMessageRepository } from "../../domain/ports/repositories.js";
+export interface ExtractionPipelineResult {
+    skippedSession: boolean;
+    added: number;
+    updated: number;
+    superseded: number;
+    skipped: number;
+}
+export declare class ExtractionPipeline {
+    private readonly db;
+    private readonly factRepo;
+    private readonly logRepo;
+    private readonly messageRepo;
+    private readonly extractionProvider;
+    private readonly embeddingProvider?;
+    private readonly eventLogPath?;
+    private readonly redactor;
+    constructor(db: Database, factRepo: IFactRepository, logRepo: IExtractionLogRepository, messageRepo: IMessageRepository, extractionProvider: IExtractionProvider, embeddingProvider?: IEmbeddingProvider | undefined, eventLogPath?: string | undefined, redactor?: IRedactor);
+    /**
+     * Run extraction workflow on a specific session.
+     */
+    extractFromSession(sessionId: string, projectName: string, options?: {
+        force?: boolean;
+    }): Promise<ExtractionPipelineResult>;
+    /**
+     * Computes Cosine Similarity between two Float32Array vectors.
+     */
+    private cosineSimilarity;
+    /**
+     * Fallback word-level Jaccard similarity.
+     */
+    private jaccardWordSimilarity;
+}

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

@@ -0,0 +1,148 @@
+/**
+ * FrictionService
+ *
+ * Application service for friction logging operations.
+ * Orchestrates business rules around friction entries using
+ * constructor-injected IFrictionRepository.
+ *
+ * Business rules enforced here (not in entity or repository):
+ * - Default severity/category/tool when logging
+ * - Entry existence validation before resolve/wontFix
+ * - Status guard: cannot resolve/wontFix already-closed entries
+ * - wontFix flow: resolve() then updateStatus() for correct final state
+ * - Auto-ingest: reads friction.jsonl fallback file, saves entries, deletes file
+ */
+import type { IFrictionRepository, FrictionStats, FrictionPattern } from "../../domain/ports/repositories.js";
+import { FrictionEntry, type FrictionSeverity, type FrictionCategory } from "../../domain/entities/friction-entry.js";
+/**
+ * Parameters for logging a new friction entry.
+ */
+export interface LogFrictionParams {
+    description: string;
+    severity?: FrictionSeverity | undefined;
+    category?: FrictionCategory | undefined;
+    tool?: string | undefined;
+    context?: string | undefined;
+    sourceProject?: string | undefined;
+    loggedAt?: Date | undefined;
+}
+/**
+ * Options for listing friction entries.
+ */
+export interface ListFrictionOptions {
+    all?: boolean | undefined;
+    status?: string | undefined;
+    category?: string | undefined;
+    tool?: string | undefined;
+    sourceProject?: string | undefined;
+    limit?: number | undefined;
+}
+/**
+ * Application service for friction logging operations.
+ *
+ * Constructor-injected IFrictionRepository for hexagonal architecture.
+ * Enforces business rules: defaults, validation, state transitions.
+ */
+export declare class FrictionService {
+    private readonly repository;
+    constructor(repository: IFrictionRepository);
+    /**
+     * Log a new friction entry.
+     *
+     * Creates a FrictionEntry with status "open", loggedAt = now (or provided),
+     * severity defaults to "medium", category defaults to "cli", tool defaults to "memory".
+     *
+     * @param params Friction entry parameters
+     * @returns The saved entry with database id
+     */
+    log(params: LogFrictionParams): Promise<FrictionEntry>;
+    /**
+     * List friction entries.
+     *
+     * By default returns only open entries. Pass `all: true` to include
+     * resolved and wont-fix entries. Optional status/category/tool/sourceProject/limit filters.
+     *
+     * @param options Listing options
+     * @returns Array of matching friction entries
+     */
+    list(options?: ListFrictionOptions): Promise<FrictionEntry[]>;
+    /**
+     * Resolve a friction entry.
+     *
+     * Validates:
+     * 1. Entry exists (throws NOT_FOUND if missing)
+     * 2. Entry is open (throws INVALID_STATE if already resolved/wont-fix)
+     *
+     * @param id Friction entry database ID
+     * @param resolution How the friction was resolved
+     * @throws MemoryError with NOT_FOUND if entry doesn't exist
+     * @throws MemoryError with INVALID_STATE if entry already closed
+     */
+    resolve(id: number, resolution: string): Promise<void>;
+    /**
+     * Mark a friction entry as won't fix.
+     *
+     * Same validation as resolve(). Implements the wont-fix flow:
+     * 1. Call resolve() to set resolution text and resolved_at timestamp
+     * 2. Call updateStatus() to overwrite status from "resolved" to "wont-fix"
+     *
+     * @param id Friction entry database ID
+     * @param resolution Why it won't be fixed
+     * @throws MemoryError with NOT_FOUND if entry doesn't exist
+     * @throws MemoryError with INVALID_STATE if entry already closed
+     */
+    wontFix(id: number, resolution: string): Promise<void>;
+    /**
+     * Get friction statistics.
+     *
+     * @returns Aggregated friction stats
+     */
+    getStats(): Promise<FrictionStats>;
+    /**
+     * Get weekly trends for friction entries.
+     *
+     * @param weeks Number of weeks to include (default 4)
+     * @returns Array of weekly new/resolved counts
+     */
+    getWeeklyTrends(weeks?: number): Promise<Array<{
+        week: string;
+        newCount: number;
+        resolvedCount: number;
+    }>>;
+    /**
+     * Ingest friction entries from a fallback JSONL file.
+     *
+     * Reads each line as JSON, maps fields to LogFrictionParams, saves via log(),
+     * then deletes the file. Malformed lines are skipped with a warning to stderr.
+     *
+     * Field mapping from fallback format:
+     * - project -> sourceProject
+     * - date -> loggedAt (as Date)
+     * - tool defaults to "unknown" if missing
+     * - category defaults to "cli" if missing
+     *
+     * @param fallbackPath Path to the friction.jsonl file
+     * @returns Number of entries successfully ingested
+     */
+    ingestFallbackFile(fallbackPath: string): Promise<number>;
+    /**
+     * Detect recurring friction patterns above a threshold count.
+     *
+     * @param threshold Minimum entry count to qualify as a pattern (default 3)
+     * @returns Array of patterns grouped by tool and category
+     */
+    detectPatterns(threshold?: number): Promise<FrictionPattern[]>;
+    /**
+     * Mark all entries for a tool as reviewed at the current time.
+     *
+     * @param tool The tool name to mark as reviewed
+     */
+    markReviewed(tool: string): Promise<void>;
+    /**
+     * Delete friction entries whose description matches a pattern.
+     * Uses SQL LIKE matching (% for wildcard).
+     * @param pattern Description pattern to match
+     * @returns Number of entries deleted
+     */
+    purge(pattern: string): Promise<number>;
+}

package/dist/application/services/fts-sanitizer.d.ts

@@ -0,0 +1,25 @@
+/**
+ * FTS5 Query Sanitizer
+ *
+ * Strips characters that FTS5 treats as syntax operators from user queries
+ * before passing to MATCH. The porter unicode61 tokenizer strips these during
+ * indexing, so queries need the same treatment for consistent matching.
+ *
+ * Preserves:
+ * - FTS5 keyword operators (AND, OR, NOT, NEAR) -- uppercase words, not special chars
+ * - Asterisks (*) -- valid FTS5 prefix search operator (e.g., auth*)
+ * - Balanced double quotes ("phrase") -- valid FTS5 phrase search syntax
+ */
+/**
+ * Sanitize a user query for safe use in FTS5 MATCH expressions.
+ *
+ * Replaces FTS5 operator characters with spaces and collapses whitespace.
+ * Preserves asterisks for prefix search and balanced double quotes for phrase search.
+ * Strips unmatched quotes to prevent "unterminated string" FTS5 errors.
+ * If the result is empty after sanitization, falls back to extracting
+ * alphanumeric parts from the original query.
+ *
+ * @param query Raw user query string
+ * @returns Sanitized query safe for FTS5 MATCH
+ */
+export declare function sanitizeFtsQuery(query: string): string;

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

@@ -0,0 +1,34 @@
+/**
+ * Application Services
+ *
+ * Services that orchestrate domain logic and infrastructure.
+ */
+export { SyncService } from "./sync-service.js";
+export type { SyncOptions, SyncProgress, SyncResult, } from "./sync-service.js";
+export { RecoveryService, extractSessionId } from "./recovery-service.js";
+export type { RecoveryResult, RecoveryOptions, } from "./recovery-service.js";
+export { PatternExtractor } from "./pattern-extractor.js";
+export type { FileModification, ToolStats, } from "./pattern-extractor.js";
+export { LlmExtractor } from "./llm-extractor.js";
+export type { ExtractionResult, LlmExtractorOptions, } from "./llm-extractor.js";
+export { EmbeddingService, computeModelHash } from "./embedding-service.js";
+export type { EmbedOptions, EmbedProgress, EmbedResult, ModelState, } from "./embedding-service.js";
+export { exportToJson, validateExportFile, importFromJson, hasExistingData, } from "./export-service.js";
+export type { ExportData, ExportStats, ImportStats, ValidationResult, ImportOptions, SessionExport, MessageExport, ToolUseExport, EntityExport, LinkExport, } from "./export-service.js";
+export { reciprocalRankFusion } from "./rrf-fusion.js";
+export type { RankedCandidate, FusedResult, } from "./rrf-fusion.js";
+export { applyTemporalDecay, applyTemporalDecayWithExemptions, CURATED_FILE_TYPES, } from "./temporal-decay.js";
+export type { DecayableResult, DecayedResult, } from "./temporal-decay.js";
+export { sanitizeFtsQuery } from "./fts-sanitizer.js";
+export { MemoryFileSyncService } from "./memory-file-sync-service.js";
+export type { MemoryFileSyncResult, MemoryFileSyncProgress, MemoryFileSyncOptions, } from "./memory-file-sync-service.js";
+export { FrictionService } from "./friction-service.js";
+export type { LogFrictionParams, ListFrictionOptions, } from "./friction-service.js";
+export { BackfillService } from "./backfill-service.js";
+export type { BackfillResult, BackfillProgress, DryRunResult, BackfillOptions, IDailyLogWriter, } from "./backfill-service.js";
+export { allocateBudget } from "./budget-allocator.js";
+export type { BudgetSection, AllocatedSection, BudgetAllocationResult, } from "./budget-allocator.js";
+export { SmartContextService } from "./smart-context-service.js";
+export type { SmartContextOptions, SmartContextResult, ContextSection, IProjectResolver, SmartContextDeps, } from "./smart-context-service.js";
+export { AmbientContextService } from "./ambient-context-service.js";
+export type { AmbientContextOptions, AmbientContextResult, } from "./ambient-context-service.js";

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

@@ -0,0 +1,96 @@
+/**
+ * LLM Extractor Service
+ *
+ * Claude-powered entity extraction from session content.
+ * Designed to run during SessionStop hook when Claude's session is still active.
+ *
+ * The extractor:
+ * 1. Receives session messages
+ * 2. Uses structured prompts to extract topics and summary
+ * 3. Returns Entity objects for persistence
+ */
+import { Entity } from "../../domain/entities/entity.js";
+import type { Message } from "../../domain/entities/message.js";
+/**
+ * Result of LLM-based entity extraction.
+ */
+export interface ExtractionResult {
+    /** Concept entities extracted from session */
+    topics: Entity[];
+    /** Term entities with definitions */
+    terms: Entity[];
+    /** Decision entities with structured metadata */
+    decisions: Entity[];
+    /** Session summary text */
+    summary: string;
+}
+/**
+ * Options for LLM extraction.
+ */
+export interface LlmExtractorOptions {
+    /** Session identifier for linking entities */
+    sessionId: string;
+    /** Messages to extract entities from */
+    messages: Message[];
+    /** Maximum tokens for extraction (default: 1000) */
+    maxTokens?: number;
+}
+/**
+ * LLM-based entity extraction service.
+ *
+ * Extracts topics, terms, decisions, and summaries from session content
+ * using Claude's language understanding.
+ *
+ * IMPORTANT: This is designed to run during SessionStop hook when Claude's
+ * session is still active. The extraction uses the existing session context.
+ */
+export declare class LlmExtractor {
+    /**
+     * Extract entities from session content using LLM.
+     *
+     * For unit tests and when no LLM context is available, returns empty result.
+     * In production (during hook execution), this would use Claude's session.
+     *
+     * @param options Extraction options including session ID and messages
+     * @returns Extraction result with entities and summary
+     */
+    static extract(options: LlmExtractorOptions): Promise<ExtractionResult>;
+    /**
+     * Create extraction prompt for Claude.
+     *
+     * Formats session messages and requests structured JSON output
+     * containing topics, terms, decisions, and summary.
+     *
+     * @param messages Session messages to include in prompt
+     * @returns Structured prompt requesting JSON output
+     */
+    static createExtractionPrompt(messages: Message[]): string;
+    /**
+     * Parse LLM response into Entity objects.
+     *
+     * Handles malformed JSON gracefully by returning empty result.
+     * Validates and clamps confidence scores to 0-1 range.
+     *
+     * @param response Raw LLM response text
+     * @param _sessionId Session ID for context (not used in entity creation)
+     * @returns Extraction result with parsed entities
+     */
+    static parseExtractionResponse(response: string, _sessionId: string): ExtractionResult;
+    /**
+     * Parse raw topics into concept entities.
+     */
+    private static parseTopics;
+    /**
+     * Parse raw terms into term entities.
+     */
+    private static parseTerms;
+    /**
+     * Parse raw decisions into decision entities.
+     */
+    private static parseDecisions;
+    /**
+     * Normalize confidence score to 0-1 range.
+     * Defaults to 0.5 if not provided.
+     */
+    private static normalizeConfidence;
+}

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

@@ -0,0 +1,58 @@
+/**
+ * MemoryFileSyncService
+ *
+ * Application service for syncing legacy markdown memory files to the database.
+ *
+ * Separate from SyncService to avoid constructor inflation.
+ * The CLI sync command orchestrates both services sequentially.
+ *
+ * Uses IMemoryFileScanner (domain port) to discover files and
+ * IMemoryFileRepository (domain port) to persist them, maintaining
+ * proper hexagonal architecture boundaries.
+ */
+import type { IMemoryFileRepository } from "../../domain/ports/repositories.js";
+import type { IMemoryFileScanner } from "../../domain/ports/sources.js";
+/**
+ * Progress callback for memory file sync.
+ */
+export interface MemoryFileSyncProgress {
+    current: number;
+    total: number;
+    filePath: string;
+    action: "indexing" | "skipped";
+}
+/**
+ * Result of memory file sync operation.
+ */
+export interface MemoryFileSyncResult {
+    filesIndexed: number;
+    filesSkipped: number;
+    errors: Array<{
+        filePath: string;
+        error: string;
+    }>;
+}
+/**
+ * Options for memory file sync.
+ */
+export interface MemoryFileSyncOptions {
+    onProgress?: (progress: MemoryFileSyncProgress) => void;
+}
+/**
+ * Application service for syncing legacy markdown memory files to the database.
+ *
+ * Separate from SyncService to avoid constructor inflation.
+ * The CLI sync command orchestrates both services sequentially.
+ */
+export declare class MemoryFileSyncService {
+    private readonly repository;
+    private readonly scanner;
+    constructor(repository: IMemoryFileRepository, scanner: IMemoryFileScanner);
+    /**
+     * Discover and index memory files.
+     *
+     * Performs incremental indexing: files where content hash matches
+     * the stored hash are skipped. New and changed files are upserted.
+     */
+    syncMemoryFiles(options?: MemoryFileSyncOptions): Promise<MemoryFileSyncResult>;
+}