@chude/memory 4.0.0

package/dist/infrastructure/hooks/hook-runner.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Hook Runner
+ *
+ * Background process spawner for sync operations.
+ * Spawns detached processes that survive parent termination.
+ *
+ * Also provides entity extraction for SessionStop hooks.
+ *
+ * Design:
+ * - Detached process runs in own process group
+ * - Parent can exit without waiting (unref)
+ * - Output redirected to sync.log for debugging
+ * - MEMORY_HOOK env var allows sync to detect hook invocation
+ * - Entity extraction runs after session sync when hook is triggered
+ */
+import type { Database } from "bun:sqlite";
+/**
+ * LogWriter interface for hook execution logging.
+ */
+export interface LogWriter {
+    debug(message: string): void;
+    warn(message: string): void;
+}
+/**
+ * Options for spawnBackgroundSync
+ */
+export interface SpawnOptions {
+    /** Override CLI command (default: "aidev") */
+    command?: string;
+    /** Include --quiet flag (default: true) */
+    quiet?: boolean;
+    /** Override log directory (for testing) */
+    logDir?: string;
+}
+/**
+ * Result of spawn operation
+ */
+export interface SpawnResult {
+    /** Process ID of spawned child, or undefined if spawn failed */
+    pid: number | undefined;
+}
+/**
+ * Get the path to the sync log file
+ *
+ * @returns Path to logs/sync.log
+ */
+export declare function getLogPath(): string;
+/**
+ * Ensure the log directory exists
+ *
+ * Creates the directory recursively if it doesn't exist.
+ * Safe to call multiple times.
+ *
+ * @param logDir Optional custom log directory path
+ */
+export declare function ensureLogDirectory(logDir?: string): void;
+/**
+ * Spawn a background sync process for the given session
+ *
+ * Creates a detached child process that:
+ * - Runs independently of the parent process
+ * - Survives parent termination
+ * - Logs output to sync.log
+ *
+ * The spawned command runs:
+ * `aidev memory sync --session <sessionId> [--quiet]`
+ *
+ * Key implementation details:
+ * - detached: true - Process runs in own process group
+ * - stdio: Redirect stdout/stderr to log file (stdin ignored)
+ * - unref() - Parent can exit without waiting
+ * - MEMORY_HOOK=1 - Sync can detect hook invocation
+ *
+ * @param sessionId Session identifier to sync
+ * @param options Configuration options
+ * @returns Spawn result with PID (if successful)
+ */
+export declare function spawnBackgroundSync(sessionId: string, options?: SpawnOptions): SpawnResult;
+/**
+ * Result of entity extraction operation
+ */
+export interface EntityExtractionResult {
+    /** Number of entities extracted and saved */
+    entitiesExtracted: number;
+    /** Whether extraction succeeded */
+    success: boolean;
+    /** Error message if extraction failed */
+    error?: string | undefined;
+    /** Session summary text (if extracted) */
+    summary?: string | undefined;
+}
+/**
+ * Options for entity extraction
+ */
+export interface EntityExtractionOptions {
+    /** Log writer for debug output (optional) */
+    logWriter?: LogWriter;
+}
+/**
+ * Extract entities from a session using LLM.
+ *
+ * This function is called during SessionStop hook processing after
+ * messages have been synced. It:
+ * 1. Retrieves messages for the session
+ * 2. Uses LlmExtractor to extract entities
+ * 3. Persists entities via EntityRepository
+ * 4. Links entities to the session
+ *
+ * LLM extraction failures are logged but don't fail the sync.
+ *
+ * @param sessionId Session identifier
+ * @param db Database instance
+ * @param options Optional configuration
+ * @returns Extraction result with entity count
+ */
+export declare function extractEntitiesFromSession(sessionId: string, db: Database, options?: EntityExtractionOptions): Promise<EntityExtractionResult>;
+/**
+ * Check if the current process was invoked by a hook.
+ *
+ * The hook runner sets MEMORY_HOOK=1 when spawning sync processes.
+ * This allows the sync command to detect hook invocation and enable
+ * additional processing like LLM extraction.
+ *
+ * @returns true if invoked by hook, false otherwise
+ */
+export declare function isInvokedByHook(): boolean;

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

@@ -0,0 +1,12 @@
+/**
+ * Hooks Infrastructure Module
+ *
+ * Configuration management, logging, and hook runner for hook system.
+ * Exports config-manager, log-writer, and hook-runner utilities.
+ */
+export { loadConfig, saveConfig, getConfigPath, getConfigDir, resolveEmbeddingApiKey, DEFAULT_CONFIG, DEFAULT_EMBEDDING_CONFIG, type MemoryConfig, type EmbeddingConfigData, type ApiKeyResolution, } from "./config-manager.js";
+export { logSync, rotateLogsIfNeeded, readRecentLogs, getLogPath, getLogDir, type LogEntry, type LogEntryInput, } from "./log-writer.js";
+export { spawnBackgroundSync, getLogPath as getHookLogPath, ensureLogDirectory, type SpawnOptions, type SpawnResult, } from "./hook-runner.js";
+export { type HookInput, readStdinJson } from "./sync-hook-script.js";
+export { FileSyncLogger } from "./sync-logger-adapter.js";
+export { getClaudeSettingsPath, getBackupPath, getHookScriptPath, loadClaudeSettings, backupSettings, restoreFromBackup, installHooks, uninstallHooks, checkHooksInstalled, type HookEntry, type HookConfig, type ClaudeSettings, type HookStatus, type OperationResult, type PathOverrides, } from "./settings-manager.js";

package/dist/infrastructure/hooks/log-writer.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Log Writer
+ *
+ * Structured JSON log writer with rotation support.
+ * Logs stored at the XDG data path via centralized paths module.
+ *
+ * Features:
+ * - Append-only JSON lines format (machine-parseable)
+ * - Automatic directory creation
+ * - Date-based log rotation
+ * - Recent log reading for status display
+ *
+ * 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.
+ */
+/**
+ * Log entry structure for sync operations
+ *
+ * Includes all relevant fields for debugging and monitoring:
+ * - timestamp: ISO 8601 format
+ * - level: Log severity
+ * - message: Human-readable description
+ * - sessionId: Optional session identifier
+ * - durationMs: Optional operation duration
+ * - error: Optional error message
+ * - hookEvent: Optional hook trigger (SessionEnd or PreCompact)
+ */
+export interface LogEntry {
+    /** ISO 8601 timestamp */
+    timestamp: string;
+    /** Log severity level */
+    level: "debug" | "info" | "warn" | "error";
+    /** Human-readable message */
+    message: string;
+    /** Session identifier (if applicable) */
+    sessionId?: string | undefined;
+    /** Operation duration in milliseconds */
+    durationMs?: number | undefined;
+    /** Error message (if applicable) */
+    error?: string | undefined;
+    /** Hook event that triggered this (SessionEnd or PreCompact) */
+    hookEvent?: string | undefined;
+}
+/**
+ * Input type for logSync (timestamp added automatically)
+ */
+export type LogEntryInput = Omit<LogEntry, "timestamp">;
+/**
+ * Get the directory containing the log file.
+ *
+ * @param logPathOverride Optional explicit log file path. The directory
+ *   is derived from this path. Used by tests.
+ * @returns Path to the logs directory
+ */
+export declare function getLogDir(logPathOverride?: string): string;
+/**
+ * Get the path to the sync log file.
+ *
+ * @param logPathOverride Optional explicit log file path. Used by tests.
+ * @returns Path to sync.log
+ */
+export declare function getLogPath(logPathOverride?: string): string;
+/**
+ * Write a log entry to the sync log
+ *
+ * Creates the log directory if it doesn't exist.
+ * Adds timestamp automatically in ISO 8601 format.
+ * Appends as JSON line (newline-delimited JSON).
+ *
+ * Handles write errors gracefully to never break sync operations.
+ *
+ * @param entry Log entry data (without timestamp)
+ * @param logPathOverride Optional explicit log file path (used by tests)
+ */
+export declare function logSync(entry: LogEntryInput, logPathOverride?: string): void;
+/**
+ * Rotate logs if they exceed the retention period
+ *
+ * Checks the sync.log file modification time.
+ * If older than retentionDays, renames to sync.log.YYYY-MM-DD.
+ * This clears the main log for fresh writes.
+ *
+ * Handles missing file gracefully (no-op).
+ *
+ * @param retentionDays Number of days before rotation
+ * @param logPathOverride Optional explicit log file path (used by tests)
+ */
+export declare function rotateLogsIfNeeded(retentionDays: number, logPathOverride?: string): void;
+/**
+ * Read recent log entries for status display
+ *
+ * Reads the sync.log file and parses JSON lines.
+ * Returns the last `limit` entries.
+ *
+ * Handles gracefully:
+ * - Missing file (returns empty array)
+ * - Malformed lines (skips them)
+ *
+ * @param limit Maximum number of entries to return (default 100)
+ * @param logPathOverride Optional explicit log file path (used by tests)
+ * @returns Array of parsed log entries
+ */
+export declare function readRecentLogs(limit?: number, logPathOverride?: string): LogEntry[];

package/dist/infrastructure/hooks/settings-manager.d.ts

@@ -0,0 +1,163 @@
+/**
+ * Settings Manager
+ *
+ * Safe manipulation of Claude Code settings.json for hook installation.
+ * Provides backup/restore capabilities and idempotent operations.
+ *
+ * Features:
+ * - Install hooks into ~/.claude/settings.json
+ * - Create backups before modifications
+ * - Restore from backup on uninstall
+ * - Check installation status
+ * - Idempotent installation (won't duplicate)
+ */
+/**
+ * Hook entry in Claude Code settings
+ */
+export interface HookEntry {
+    /** Hook type - always "command" for shell commands */
+    type: "command";
+    /** Shell command to execute */
+    command: string;
+    /** Timeout in seconds */
+    timeout?: number;
+}
+/**
+ * Hook configuration block
+ */
+export interface HookConfig {
+    /** Matcher for PreCompact: "auto" or "manual" */
+    matcher?: string;
+    /** Array of hook entries */
+    hooks: HookEntry[];
+}
+/**
+ * Claude Code settings.json structure
+ */
+export interface ClaudeSettings {
+    /** Hook configurations by event name */
+    hooks?: {
+        /** SessionEnd hook configurations */
+        SessionEnd?: HookConfig[];
+        /** PreCompact hook configurations */
+        PreCompact?: HookConfig[];
+        /** Other hook types */
+        [key: string]: HookConfig[] | undefined;
+    };
+    /** Other settings */
+    [key: string]: unknown;
+}
+/**
+ * Hook installation status
+ */
+export interface HookStatus {
+    /** SessionEnd hook is installed */
+    sessionEnd: boolean;
+    /** PreCompact hook is installed */
+    preCompact: boolean;
+    /** Hook script file exists */
+    hookScriptExists: boolean;
+    /** Backup file exists */
+    backupExists: boolean;
+}
+/**
+ * Operation result
+ */
+export interface OperationResult {
+    /** Operation succeeded */
+    success: boolean;
+    /** Human-readable message */
+    message: string;
+}
+/**
+ * Path overrides for testing
+ *
+ * When set, these paths will be used instead of the default locations.
+ * This allows tests to operate in isolated directories.
+ */
+export interface PathOverrides {
+    /** Override ~/.claude/settings.json */
+    settingsPath?: string;
+    /** Override backups/settings.json.backup */
+    backupPath?: string;
+    /** Override hooks/sync-hook.js */
+    hookScriptPath?: string;
+}
+/**
+ * Get the path to Claude Code settings.json.
+ *
+ * @param overrides Optional path overrides (used by tests)
+ * @returns Path to ~/.claude/settings.json
+ */
+export declare function getClaudeSettingsPath(overrides?: PathOverrides): string;
+/**
+ * Get the path to the settings backup file.
+ *
+ * @param overrides Optional path overrides (used by tests)
+ * @returns Path to backups/settings.json.backup
+ */
+export declare function getBackupPath(overrides?: PathOverrides): string;
+/**
+ * Get the path to the hook script.
+ *
+ * @param overrides Optional path overrides (used by tests)
+ * @returns Path to hooks/sync-hook.js
+ */
+export declare function getHookScriptPath(overrides?: PathOverrides): string;
+/**
+ * Load Claude Code settings from disk
+ *
+ * Returns empty object if file doesn't exist or is invalid.
+ *
+ * @returns Parsed settings object
+ */
+export declare function loadClaudeSettings(overrides?: PathOverrides): ClaudeSettings;
+/**
+ * Backup current settings.json
+ *
+ * Creates a copy of the current settings to the backups directory.
+ * Safe to call even if settings don't exist.
+ *
+ * @returns true if backup was created, false if no settings to backup
+ */
+export declare function backupSettings(overrides?: PathOverrides): boolean;
+/**
+ * Restore settings.json from backup
+ *
+ * Replaces current settings with the backup copy.
+ * Safe to call even if backup doesn't exist.
+ *
+ * @returns true if restore was successful, false if no backup exists
+ */
+export declare function restoreFromBackup(overrides?: PathOverrides): boolean;
+/**
+ * Install memory hooks into Claude Code settings
+ *
+ * Adds SessionEnd and PreCompact hooks to settings.json.
+ * Creates backup before modifying.
+ * Idempotent - won't duplicate if already installed.
+ *
+ * @returns Operation result with success status and message
+ */
+export declare function installHooks(overrides?: PathOverrides): OperationResult;
+/**
+ * Uninstall memory hooks from Claude Code settings
+ *
+ * Removes SessionEnd and PreCompact hooks containing the memory marker.
+ * Preserves other hooks and settings.
+ *
+ * @returns Operation result with success status and message
+ */
+export declare function uninstallHooks(overrides?: PathOverrides): OperationResult;
+/**
+ * Check if memory hooks are installed
+ *
+ * Returns status of each component:
+ * - SessionEnd hook in settings.json
+ * - PreCompact hook in settings.json
+ * - Hook script file exists
+ * - Backup file exists
+ *
+ * @returns Hook installation status
+ */
+export declare function checkHooksInstalled(overrides?: PathOverrides): HookStatus;

package/dist/infrastructure/hooks/sync-hook-script.d.ts

@@ -0,0 +1,83 @@
+#!/usr/bin/env bun
+/**
+ * Sync Hook Script
+ *
+ * Entry point for Claude Code hooks (SessionEnd, PreCompact).
+ * Reads hook input from stdin, checks configuration, and spawns
+ * background sync process.
+ *
+ * Design:
+ * - Always exits 0 (never blocks Claude Code)
+ * - Logs all operations for debugging
+ * - Checks config before processing
+ * - Graceful handling of missing session_id
+ * - Hook event name tracked in logs
+ *
+ * Usage in settings.json:
+ * ```json
+ * {
+ *   "hooks": {
+ *     "SessionEnd": [{
+ *       "hooks": [{
+ *         "type": "command",
+ *         "command": "bun ~/.local/share/memory/hooks/sync-hook.js",
+ *         "timeout": 5
+ *       }]
+ *     }]
+ *   }
+ * }
+ * ```
+ */
+import type { MemoryConfig } from "./config-manager.js";
+import { logSync } from "./log-writer.js";
+import { spawnBackgroundSync } from "./hook-runner.js";
+/**
+ * Hook input from Claude Code
+ *
+ * Sent via stdin as JSON when hooks fire.
+ * Fields vary by hook event type.
+ */
+export interface HookInput {
+    /** Session identifier */
+    session_id?: string;
+    /** Path to session JSONL transcript */
+    transcript_path?: string;
+    /** Which hook event fired */
+    hook_event_name: string;
+    /** SessionEnd reason: "clear", "logout", "prompt_input_exit", "other" */
+    reason?: string;
+    /** PreCompact trigger: "manual" or "auto" */
+    trigger?: string;
+    /** Current working directory */
+    cwd?: string;
+    /** Permission mode ("default", etc.) */
+    permission_mode?: string;
+}
+export interface SyncHookDeps {
+    loadConfig: () => MemoryConfig;
+    readInput: () => Promise<HookInput>;
+    log: typeof logSync;
+    spawnSync: typeof spawnBackgroundSync;
+    writeStdout: (message: string) => void;
+    exit: (code: number) => void;
+}
+/**
+ * Read JSON from stdin
+ *
+ * Collects all chunks until EOF, then parses as JSON.
+ * Handles errors gracefully.
+ *
+ * @returns Parsed hook input
+ * @throws Error if stdin is empty or JSON is invalid
+ */
+type HookInputStream = Pick<NodeJS.ReadStream, "setEncoding" | "on">;
+export declare function readJsonFromStream(stream: HookInputStream): Promise<HookInput>;
+export declare function readStdinJson(): Promise<HookInput>;
+export declare function createDefaultSyncHookDeps(): SyncHookDeps;
+export declare function executeSyncHook(deps: SyncHookDeps): Promise<void>;
+export declare function runSyncHookMain(deps?: SyncHookDeps, onFatal?: (entry: {
+    level: "error";
+    message: string;
+    error?: string | undefined;
+}) => void): Promise<void>;
+export {};

package/dist/infrastructure/hooks/sync-logger-adapter.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Domain Port Adapter for Sync Logging
+ *
+ * Wraps the logSync() free function from log-writer into a
+ * class-based adapter implementing the ISyncLogger domain port.
+ */
+import type { ISyncLogger } from "../../domain/ports/signals.js";
+type SyncLogEntry = Parameters<ISyncLogger["log"]>[0];
+/**
+ * Adapter wrapping the file-based structured logger.
+ */
+export declare class FileSyncLogger implements ISyncLogger {
+    private readonly writeLog;
+    constructor(writeLog?: (entry: SyncLogEntry) => void);
+    log(entry: SyncLogEntry): void;
+}
+export {};

package/dist/infrastructure/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Infrastructure Layer
+ *
+ * Adapters implementing domain ports.
+ * Database, filesystem, and external service integrations.
+ */
+export * from "./database/index.js";
+export * from "./hooks/index.js";
+export * from "./parsers/index.js";
+export * from "./signals/index.js";
+export * from "./sources/index.js";

package/dist/infrastructure/llm/anthropic-extractor.d.ts

@@ -0,0 +1,20 @@
+/**
+ * AnthropicExtractionProvider
+ *
+ * Infrastructure adapter connecting directly to the Anthropic API
+ * using the official SDK.
+ */
+import type { IExtractionProvider } from "../../domain/ports/extraction.js";
+import type { Message } from "../../domain/entities/message.js";
+import type { CandidateFact } from "../../domain/entities/fact.js";
+export interface AnthropicExtractorConfig {
+    apiKey: string;
+    model?: string | undefined;
+}
+export declare class AnthropicExtractionProvider implements IExtractionProvider {
+    readonly providerId = "anthropic";
+    readonly modelName: string;
+    private readonly anthropic;
+    constructor(config: AnthropicExtractorConfig);
+    extract(messages: Message[]): Promise<CandidateFact[]>;
+}

package/dist/infrastructure/llm/claude-cli-extractor.d.ts

@@ -0,0 +1,14 @@
+/**
+ * ClaudeCliExtractionProvider
+ *
+ * Infrastructure adapter that shells out to claude -p (print mode)
+ * within active Claude Code environments to perform structured fact extraction.
+ */
+import type { IExtractionProvider } from "../../domain/ports/extraction.js";
+import type { Message } from "../../domain/entities/message.js";
+import type { CandidateFact } from "../../domain/entities/fact.js";
+export declare class ClaudeCliExtractionProvider implements IExtractionProvider {
+    readonly providerId = "claude-cli";
+    readonly modelName = "claude-cli-print";
+    extract(messages: Message[]): Promise<CandidateFact[]>;
+}

package/dist/infrastructure/llm/claude-summary-generator.d.ts

@@ -0,0 +1,14 @@
+/**
+ * ClaudeSummaryGenerator
+ *
+ * Infrastructure adapter that shells out to claude -p (print mode)
+ * for generating structured daily log summaries from session content.
+ *
+ * Strips CLAUDECODE env var to prevent nested session detection
+ * when running inside a Claude Code session.
+ */
+import type { ISummaryGenerator } from "../../domain/ports/index.js";
+export declare class ClaudeSummaryGenerator implements ISummaryGenerator {
+    generateSummary(content: string, sessionId: string, projectName: string, startTime: string, endTime: string): Promise<string>;
+    private buildPrompt;
+}

package/dist/infrastructure/llm/extraction-helper.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Extraction Helper
+ *
+ * Common functions for preparing fact-extraction prompts and robustly parsing
+ * structured JSON arrays from LLM response texts.
+ */
+import type { Message } from "../../domain/entities/message.js";
+import type { CandidateFact } from "../../domain/entities/fact.js";
+/**
+ * Builds the standardized fact extraction instruction prompt.
+ */
+export declare function buildExtractionPrompt(messages: Message[]): string;
+/**
+ * Robustly parses and cleans a JSON array of CandidateFacts from the raw LLM output.
+ */
+export declare function parseLlmResponse(text: string): CandidateFact[];

package/dist/infrastructure/llm/ollama-extractor.d.ts

@@ -0,0 +1,20 @@
+/**
+ * OllamaExtractionProvider
+ *
+ * Infrastructure adapter connecting to local Ollama API completions endpoint
+ * via standard fetch request.
+ */
+import type { IExtractionProvider } from "../../domain/ports/extraction.js";
+import type { Message } from "../../domain/entities/message.js";
+import type { CandidateFact } from "../../domain/entities/fact.js";
+export interface OllamaExtractorConfig {
+    baseUrl?: string | undefined;
+    model?: string | undefined;
+}
+export declare class OllamaExtractionProvider implements IExtractionProvider {
+    readonly providerId = "ollama";
+    readonly modelName: string;
+    private readonly baseUrl;
+    constructor(config: OllamaExtractorConfig);
+    extract(messages: Message[]): Promise<CandidateFact[]>;
+}

package/dist/infrastructure/llm/openai-extractor.d.ts

@@ -0,0 +1,23 @@
+/**
+ * OpenAiExtractionProvider
+ *
+ * Infrastructure adapter connecting to OpenAI Chat Completions endpoint
+ * via standard fetch request.
+ */
+import type { IExtractionProvider } from "../../domain/ports/extraction.js";
+import type { Message } from "../../domain/entities/message.js";
+import type { CandidateFact } from "../../domain/entities/fact.js";
+export interface OpenAiExtractorConfig {
+    apiKey: string;
+    model?: string | undefined;
+    baseUrl?: string | undefined;
+    providerId?: string | undefined;
+}
+export declare class OpenAiExtractionProvider implements IExtractionProvider {
+    readonly providerId: string;
+    readonly modelName: string;
+    private readonly apiKey;
+    private readonly baseUrl;
+    constructor(config: OpenAiExtractorConfig);
+    extract(messages: Message[]): Promise<CandidateFact[]>;
+}