@chude/memory 4.0.0

package/README.md

@@ -0,0 +1,294 @@
+# @chude/memory
+
+Cross-project context persistence for Claude Code sessions.
+
+## Problem
+
+Claude Code sessions are per-directory and deleted after 30 days. Context does not transfer between projects. Knowledge gained in one project is invisible to work in another.
+
+## Solution
+
+Extract session JSONL files into a searchable SQLite database accessible from any project via the `memory` CLI.
+
+## Installation
+
+```bash
+bun add -g @chude/memory
+```
+
+## Setup
+
+Install Claude Code hooks for automatic session sync:
+
+```bash
+memory install
+```
+
+Verify installation:
+
+```bash
+memory doctor
+```
+
+## Usage
+
+```bash
+# Sync sessions to database
+memory sync
+
+# Search across all sessions
+memory search "authentication patterns"
+
+# Get context for a specific project
+memory context wow-system
+
+# List recent sessions
+memory list
+
+# Show session details
+memory show <session-id>
+
+# Find related sessions
+memory related <session-id>
+
+# Browse sessions interactively
+memory browse
+```
+
+## How It Works
+
+1. Claude Code stores sessions as JSONL files in `~/.claude/projects/`
+2. `memory sync` extracts messages, topics, and entities into a SQLite database with FTS5
+3. Claude Code hooks trigger background sync automatically on session end
+4. `memory search` and `memory context` query the database from any project directory
+
+## Data Paths
+
+| Purpose | Path | Override |
+|---------|------|----------|
+| Config | `~/.config/memory/config.json` | `XDG_CONFIG_HOME` |
+| Database | `~/.local/share/memory/memory.db` | `XDG_DATA_HOME` |
+| Logs | `~/.local/share/memory/logs/` | `XDG_DATA_HOME` |
+| Legacy memory files | `~/.memory/` | `MEMORY_HOME` |
+
+Tool-managed paths follow the XDG Base Directory Specification. Override with `XDG_CONFIG_HOME` and `XDG_DATA_HOME`.
+
+Legacy memory files are retained for compatibility with pre-v4 markdown sidecars. They are not read or written by default. To index them during sync, use `memory sync --include-memory-files`, set `MEMORY_LEGACY_MEMORY_FILES=1`, or set `legacyMemoryFiles.enabled=true` in config. To generate legacy daily logs with `memory backfill`, pass `--write-memory-files` or use the same env/config opt-in. `MEMORY_HOME` follows the `GNUPGHOME` / `JAVA_HOME` tradition: the value is the exact directory path, not a base directory under which a subdirectory is appended. Empty string is ignored; no `~` expansion.
+
+## Secret Handling
+
+Remote provider credentials should come from environment injection, not plaintext config files. `embedding.apiKey` is retained only as deprecated compatibility input.
+
+Use `apiKeyEnv` when a provider needs a runtime key:
+
+```json
+{
+  "embedding": {
+    "provider": "openai",
+    "apiKeyEnv": "OPENAI_API_KEY"
+  }
+}
+```
+
+Use `apiKeyRef` only as opaque metadata for an external secret manager:
+
+```json
+{
+  "embedding": {
+    "provider": "openai",
+    "apiKeyRef": "authkey://memory/openai-api-key"
+  }
+}
+```
+
+`memory` never resolves `apiKeyRef` to a raw secret and never calls `authkey get`. If you use authkey, inject secrets into the child process:
+
+```bash
+authkey run --env memory -- memory sync --embed
+authkey run --env memory -- memory extract memory-nexus
+```
+
+Known secret patterns in newly synced transcript content, tool inputs/results, extraction payloads, embeddings, and CLI JSON exports are redacted before storage or provider egress. Raw JSON backups require explicit opt-in:
+
+```bash
+memory export backup.json --include-sensitive
+```
+
+## Provider Support
+
+Provider support is explicit and registry-backed. Built-in embedding providers are `local`, `openai`, `ollama`, and `openai-compatible`. Built-in extraction providers are `claude-cli`, `anthropic`, `openai`, `ollama`, and `openai-compatible`.
+
+Use `openai-compatible` for gateways or providers that expose OpenAI-compatible APIs:
+
+```json
+{
+  "embedding": {
+    "provider": "openai-compatible",
+    "baseUrl": "https://gateway.example.com/v1",
+    "apiKeyEnv": "MEMORY_GATEWAY_API_KEY"
+  }
+}
+```
+
+`LLM_PROVIDER` selects the extraction provider. `LLM_MODEL` overrides the extraction model without changing embedding configuration.
+
+## AI-First Design
+
+This tool is designed for Claude to use via the Bash tool:
+
+```bash
+# Claude runs these commands to access cross-project knowledge
+memory context <project-name>
+memory search "query" --limit 5
+```
+
+Standard CLI output works for both humans and AI agents.
+
+## Programmatic API
+
+Install as a dependency:
+
+```bash
+bun add @chude/memory
+```
+
+Import and call execute functions:
+
+```typescript
+import {
+  executeSyncCommand,
+  executeSearchCommand,
+  executeContextCommand,
+  type CommandResult,
+  type SyncCommandOptions,
+  type SearchCommandOptions,
+  type SearchMode,
+} from "@chude/memory";
+
+// Sync sessions to database
+const syncResult = await executeSyncCommand({ quiet: true });
+// syncResult: { exitCode: 0 }
+
+// Search sessions
+const searchResult = await executeSearchCommand("authentication patterns", {
+  limit: "5",
+  json: true,
+});
+
+// Get project context
+const contextResult = await executeContextCommand("my-project", {
+  json: true,
+  days: 7,
+});
+```
+
+### Exported Functions
+
+| Function | Parameters | Returns |
+|----------|------------|---------|
+| `executeSyncCommand` | `options: SyncCommandOptions` | `Promise<CommandResult>` |
+| `executeSearchCommand` | `query: string, options: SearchCommandOptions` | `Promise<CommandResult>` |
+| `executeListCommand` | `options: ListCommandOptions` | `Promise<CommandResult>` |
+| `executeStatsCommand` | `options: StatsCommandOptions` | `Promise<CommandResult>` |
+| `executeContextCommand` | `project: string, options: ContextCommandOptions` | `Promise<CommandResult>` |
+| `executeRelatedCommand` | `sessionId: string, options: RelatedCommandOptions` | `Promise<CommandResult>` |
+| `executeShowCommand` | `sessionId: string, options: ShowCommandOptions` | `Promise<CommandResult>` |
+| `executeBrowseCommand` | `options: BrowseCommandOptions` | `Promise<CommandResult>` |
+| `executeInstallCommand` | `options: InstallOptions` | `Promise<CommandResult>` |
+| `executeUninstallCommand` | `options: UninstallOptions` | `Promise<CommandResult>` |
+| `executeStatusCommand` | `options: StatusOptions` | `Promise<CommandResult>` |
+| `executeDoctorCommand` | `options: DoctorOptions` | `Promise<CommandResult>` |
+| `executePurgeCommand` | `options: PurgeCommandOptions` | `Promise<CommandResult>` |
+| `executeExportCommand` | `outputPath: string, options: ExportOptions` | `Promise<CommandResult>` |
+| `executeImportCommand` | `inputPath: string, options: ImportOptions` | `Promise<CommandResult>` |
+| `executeCompletionCommand` | `shell: string` | `CommandResult` |
+
+### CommandResult
+
+```typescript
+interface CommandResult {
+  exitCode: number; // 0 = success, 1 = error/not found
+}
+```
+
+All functions handle their own database initialization and teardown. They never call `process.exit()`.
+
+### Domain Types
+
+The following domain types are exported for TypeScript consumers who need typed search and stats operations:
+
+| Type | Description |
+|------|-------------|
+| `SearchMode` | Union type: `"auto" \| "fts" \| "vector" \| "hybrid"`. Controls search strategy. |
+| `HybridSearchOptions` | Extends `SearchOptions` with `mode` and `noDecay` fields for hybrid search. |
+| `IStatsService` | Port interface for database statistics queries. |
+| `StatsResult` | Return type from `IStatsService.getStats()`: session/message/tool-use totals, database size, and per-project breakdown. |
+| `ProjectStats` | Per-project statistics: `projectName`, `sessionCount`, `messageCount`. |
+
+```typescript
+import type {
+  SearchMode,
+  HybridSearchOptions,
+  IStatsService,
+  StatsResult,
+  ProjectStats,
+} from "@chude/memory";
+
+// Typed search options
+const opts: HybridSearchOptions = {
+  mode: "hybrid" satisfies SearchMode,
+  limit: 10,
+};
+
+// Typed stats result
+function processStats(stats: StatsResult): void {
+  console.log(`${stats.totalSessions} sessions, ${stats.totalMessages} messages`);
+  stats.projectBreakdown.forEach((p: ProjectStats) => {
+    console.log(`  ${p.projectName}: ${p.messageCount} messages`);
+  });
+}
+```
+
+## Previously Published As
+
+This package was previously published as `memory-nexus`. The old package name now installs a deprecation stub. See [MIGRATION.md](MIGRATION.md) for upgrade instructions.
+
+## Development
+
+### Quality gates
+
+```bash
+bun run typecheck
+bun run build
+bun test --timeout 15000
+bun run test:isolation
+bun run test:coverage
+bun audit
+```
+
+`bun run quality` runs the release gate sequence. `bun run test:coverage` uses an Istanbul-backed Bun harness and is intentionally strict: statements, branches, functions, and lines must each be available and at least 95%. Missing metrics fail the gate.
+
+### Running tests on Windows
+
+Current 2026-05-28 verification has `bun test --timeout 15000` passing on Windows 11 with Bun 1.3.5. A previous full-suite run crashed with Bun's `panic(main thread): integer overflow` signature at ~6.8GB peak memory pressure; keep the subdirectory workaround available if that upstream runtime crash returns.
+
+Fallback workaround: run the suite by subdirectory.
+
+```bash
+bun test src/infrastructure/
+bun test src/presentation/
+bun test src/application src/domain
+bun test tests/helpers tests/generators tests/infrastructure tests/integration tests/smoke
+```
+
+Or run a single file directly:
+
+```bash
+bun test src/path/to/file.test.ts
+```
+
+Linux and macOS contributors should run the full suite normally.
+
+## License
+
+MIT

package/dist/application/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Application Layer
+ *
+ * Use cases and application services that orchestrate domain logic.
+ */
+export * from "./services/index.js";

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

@@ -0,0 +1,90 @@
+/**
+ * Ambient Context Service
+ *
+ * Application-layer service that composes SmartContextService and
+ * IAmbientContextWriter to generate ambient context files for
+ * Claude Code's auto memory directory.
+ *
+ * After a sync, this service:
+ * 1. Queries SmartContextService for structured project context
+ * 2. Formats context.md via an injected formatter
+ * 3. Builds a concise MEMORY.md summary block with counts
+ * 4. Writes both artifacts via IAmbientContextWriter
+ *
+ * Dependencies are injected via constructor (hexagonal architecture).
+ * Zero imports from infrastructure or presentation layers.
+ */
+import type { IAmbientContextWriter } from "../../domain/ports/services.js";
+import type { SmartContextService, SmartContextResult } from "./smart-context-service.js";
+/**
+ * Options for ambient context generation.
+ */
+export interface AmbientContextOptions {
+    /** Human-readable project name for SmartContextService lookup */
+    projectName: string;
+    /** Path to the auto memory directory (e.g., ~/.claude/projects/<encoded>/memory/) */
+    autoMemoryDir: string;
+    /** Token budget for context.md (from config) */
+    budget: number;
+}
+/**
+ * Result of ambient context generation.
+ */
+export interface AmbientContextResult {
+    /** Whether context was successfully generated */
+    success: boolean;
+    /** Reason for failure (only when success=false) */
+    reason?: "project-not-found" | "no-context" | "error";
+    /** Estimated token count of context.md content */
+    contextTokens?: number;
+}
+/**
+ * Structural type for the formatter dependency.
+ * Accepts any object with a formatSmartContext method.
+ * This avoids importing from the presentation layer.
+ */
+interface SmartContextFormatter {
+    formatSmartContext(result: SmartContextResult): string;
+}
+/**
+ * Ambient Context Service.
+ *
+ * Orchestrates SmartContextService, a formatter, and IAmbientContextWriter
+ * to produce context.md and update MEMORY.md in the auto memory directory.
+ */
+export declare class AmbientContextService {
+    private readonly smartContext;
+    private readonly contextWriter;
+    private readonly formatter;
+    constructor(smartContext: SmartContextService, contextWriter: IAmbientContextWriter, formatter: SmartContextFormatter);
+    /**
+     * Generate ambient context for the given project.
+     *
+     * Queries SmartContextService for structured context, formats it
+     * for context.md, builds a summary block for MEMORY.md, and
+     * writes both artifacts.
+     *
+     * @param options Generation options
+     * @returns Result indicating success or failure with reason
+     */
+    generateAmbientContext(options: AmbientContextOptions): Promise<AmbientContextResult>;
+    /**
+     * Build a concise summary block for MEMORY.md.
+     *
+     * Extracts counts from SmartContextResult sections and produces
+     * a block under 10 lines matching the CONTEXT.md spec.
+     *
+     * @param result SmartContextResult with sections
+     * @returns Formatted summary block content
+     */
+    private buildSummaryBlock;
+    /**
+     * Count non-empty lines in a section by key.
+     *
+     * @param sections Context sections from SmartContextResult
+     * @param key Section key to look for
+     * @returns Number of non-empty lines, or 0 if section not found
+     */
+    private countSectionLines;
+}
+export {};

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

@@ -0,0 +1,71 @@
+/**
+ * BackfillService
+ *
+ * Application service that orchestrates session backfilling:
+ * 1. Query sessions without backfill state (unprocessed)
+ * 2. Extract content from messages
+ * 3. Generate structured summary via ISummaryGenerator
+ * 4. Write daily log file via IDailyLogWriter
+ * 5. Save BackfillState record for idempotency
+ *
+ * Depends on domain ports only. Infrastructure is injected via constructor.
+ */
+import type { ISessionRepository } from "../../domain/ports/repositories.js";
+import type { IBackfillStateRepository } from "../../domain/ports/repositories.js";
+import type { IMessageRepository } from "../../domain/ports/repositories.js";
+import type { ISummaryGenerator } from "../../domain/ports/index.js";
+export interface BackfillProgress {
+    current: number;
+    total: number;
+    sessionId: string;
+    action: "processing" | "skipped" | "error";
+}
+export interface BackfillResult {
+    sessionsProcessed: number;
+    sessionsFailed: number;
+    sessionsSkipped: number;
+    dailyLogsCreated: number;
+    dailyLogsUpdated: number;
+    errors: Array<{
+        sessionId: string;
+        error: string;
+    }>;
+}
+export interface DryRunResult {
+    unprocessedCount: number;
+    estimatedCost: number;
+}
+export interface BackfillOptions {
+    batch?: number | undefined;
+    project?: string | undefined;
+    onProgress?: ((progress: BackfillProgress) => void) | undefined;
+}
+/**
+ * File writer abstraction for daily log files.
+ *
+ * Allows the service to write daily log files without importing
+ * filesystem modules directly. Infrastructure provides the implementation.
+ */
+export interface IDailyLogWriter {
+    /**
+     * Write or append content to a daily log file.
+     * Creates parent directories if needed.
+     *
+     * @param datePath Date-based path relative to memory dir (e.g., "daily/2026-03-08.md")
+     * @param content Markdown content to write or append
+     * @returns Whether the file was created (true) or appended to (false)
+     */
+    writeOrAppend(datePath: string, content: string): Promise<boolean>;
+}
+export declare class BackfillService {
+    private readonly sessionRepo;
+    private readonly messageRepo;
+    private readonly backfillStateRepo;
+    private readonly summaryGenerator;
+    private readonly dailyLogWriter;
+    constructor(sessionRepo: ISessionRepository, messageRepo: IMessageRepository, backfillStateRepo: IBackfillStateRepository, summaryGenerator: ISummaryGenerator, dailyLogWriter: IDailyLogWriter);
+    dryRun(options?: Pick<BackfillOptions, "project">): Promise<DryRunResult>;
+    backfill(options?: BackfillOptions): Promise<BackfillResult>;
+    private getUnprocessedSessions;
+    private extractContent;
+}

package/dist/application/services/budget-allocator.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Budget Allocator
+ *
+ * Pure function that distributes a token budget across prioritized sections.
+ * Sections are filled in priority order (1 = highest). Lower-priority sections
+ * are truncated first when budget is exceeded.
+ *
+ * Token estimation: ~4 characters per token for English text.
+ */
+/**
+ * A section of content with a priority for budget allocation.
+ */
+export interface BudgetSection {
+    /** Section identifier (e.g., "decisions", "learnings") */
+    key: string;
+    /** Priority (1 = highest, filled first) */
+    priority: number;
+    /** Section content text */
+    content: string;
+}
+/**
+ * A section after budget allocation, with truncation info.
+ */
+export interface AllocatedSection extends BudgetSection {
+    /** Content after budget truncation (prefix of original) */
+    truncatedContent: string;
+    /** Estimated tokens allocated to this section */
+    allocated: number;
+    /** Whether this section was truncated */
+    truncated: boolean;
+}
+/**
+ * Result of budget allocation across sections.
+ */
+export interface BudgetAllocationResult {
+    /** Sections with allocation details */
+    sections: AllocatedSection[];
+    /** Total estimated tokens used across all sections */
+    totalTokensUsed: number;
+    /** Whether the total content exceeded the budget */
+    budgetExceeded: boolean;
+}
+/**
+ * Distribute a token budget across prioritized sections.
+ *
+ * Sections are sorted by priority (1 = highest) and allocated budget
+ * in order. Lower-priority sections are truncated or dropped first.
+ *
+ * When totalBudget is 0 or negative, no constraint is applied and all
+ * sections are returned untruncated.
+ *
+ * @param sections Array of content sections to allocate budget to
+ * @param totalBudget Maximum tokens allowed (0 or negative = no limit)
+ * @param charsPerToken Characters per token heuristic (default: 4)
+ * @returns Allocation result with sections, token usage, and overflow flag
+ */
+export declare function allocateBudget(sections: BudgetSection[], totalBudget: number, charsPerToken?: number): BudgetAllocationResult;

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

@@ -0,0 +1,131 @@
+/**
+ * Embedding Service
+ *
+ * Application layer service that orchestrates the embedding pipeline:
+ * check model hash -> query unembedded -> batch embed -> store results.
+ *
+ * Does NOT own the IEmbeddingProvider lifecycle -- the caller creates
+ * and initializes the provider, then passes it in via constructor.
+ *
+ * Sits between the presentation layer (sync command) and infrastructure
+ * (repository + provider). Respects hexagonal architecture boundaries.
+ */
+import type { IEmbeddingProvider } from "../../domain/ports/embedding.js";
+import type { IRedactor } from "../../domain/ports/redactor.js";
+import type { IEmbeddingRepository, EmbeddingServiceConfig } from "../../domain/ports/repositories.js";
+/**
+ * Options for embedding operations.
+ */
+export interface EmbedOptions {
+    /** Callback invoked after each batch completes */
+    onProgress?: (progress: EmbedProgress) => void;
+}
+/**
+ * Progress report after each embedding batch.
+ */
+export interface EmbedProgress {
+    /** Number of messages embedded so far */
+    current: number;
+    /** Total number of messages to embed */
+    total: number;
+}
+/**
+ * Result of an embedding operation.
+ */
+export interface EmbedResult {
+    /** Number of messages successfully embedded */
+    embedded: number;
+    /** Number of messages skipped */
+    skipped: number;
+    /** Total duration in milliseconds */
+    durationMs: number;
+    /** Embedding rate in messages per second */
+    rate: number;
+}
+/**
+ * Model state comparison result.
+ *
+ * Used to detect model changes and determine whether re-embedding
+ * is needed. Carries human-readable model names for user prompts.
+ */
+export interface ModelState {
+    /** Whether the configured model differs from the stored model */
+    modelChanged: boolean;
+    /** Whether all embeddings need to be regenerated */
+    needsReEmbed: boolean;
+    /** Hash of the previously-used model (from embedding_state) */
+    storedHash?: string;
+    /** Hash of the currently-configured model */
+    currentHash: string;
+    /**
+     * Human-readable name of the previously-used model.
+     * Falls back to storedHash if the stored name is unavailable (legacy data).
+     */
+    storedModelName?: string;
+    /** Human-readable name of the currently-configured model (from config) */
+    currentModelName: string;
+    /** Number of existing embeddings (for re-embedding cost estimation) */
+    embeddedCount?: number;
+}
+/**
+ * Compute a model hash from embedding configuration.
+ *
+ * Generates a SHA-256 hash of the "provider:model:dimensions" string,
+ * truncated to 16 hex characters. Used for model change detection.
+ *
+ * @param config Embedding config with provider, model, and dimensions
+ * @returns 16-character hex hash string
+ */
+export declare function computeModelHash(config: Pick<EmbeddingServiceConfig, "provider" | "model" | "dimensions">): string;
+/**
+ * Application service for embedding orchestration.
+ *
+ * Manages the embedding lifecycle: model state detection, batch embedding,
+ * progress reporting, and re-embedding on model change. Dependencies are
+ * injected via constructor for testability.
+ */
+export declare class EmbeddingService {
+    private readonly repository;
+    private readonly provider;
+    private readonly batchSize;
+    private readonly modelHash;
+    private readonly modelName;
+    private readonly redactor;
+    constructor(deps: {
+        repository: IEmbeddingRepository;
+        provider: IEmbeddingProvider;
+        config: EmbeddingServiceConfig;
+        redactor?: IRedactor;
+    });
+    /**
+     * Check whether the configured model matches the stored model.
+     *
+     * Compares the current model hash against what is stored in
+     * embedding_state. Returns model state with human-readable names
+     * for user-facing prompts.
+     *
+     * @returns Model state comparison result
+     */
+    checkModelState(): ModelState;
+    /**
+     * Embed all unembedded messages in batches.
+     *
+     * Queries for unembedded messages, sends them to the provider in
+     * batch-sized chunks, and stores the results. Calls onProgress
+     * after each batch completes.
+     *
+     * @param options Embedding options (progress callback)
+     * @returns Summary of the embedding operation
+     */
+    embedUnembedded(options?: EmbedOptions): Promise<EmbedResult>;
+    /**
+     * Clear all existing embeddings and re-embed everything.
+     *
+     * Used when the model has changed and all embeddings need
+     * to be regenerated. Clears first, then embeds.
+     *
+     * @param options Embedding options (progress callback)
+     * @returns Summary of the re-embedding operation
+     */
+    clearAndReembed(options?: EmbedOptions): Promise<EmbedResult>;
+}