@lumenflow/memory 2.9.0 → 2.11.0

package/dist/mem-export-core.d.ts

@@ -1,33 +0,0 @@
-/**
- * Memory Export Core (WU-1137)
- *
- * Render memory.jsonl as markdown or JSON with basic filters.
- * Designed for human-readable inspection without changing storage format.
- */
-import type { MemoryNode } from './memory-schema.js';
-/** Supported output formats for export */
-export type ExportFormat = 'markdown' | 'json';
-/** Export filters */
-export interface ExportOptions {
-    /** WU ID filter (e.g., WU-1234) */
-    wuId?: string;
-    /** Node type filter (e.g., discovery, checkpoint) */
-    type?: string;
-    /** Lifecycle filter (ephemeral, session, wu, project) */
-    lifecycle?: string;
-    /** Output format (markdown or json) */
-    format?: ExportFormat;
-}
-/** Export result */
-export interface ExportResult {
-    format: ExportFormat;
-    nodes: MemoryNode[];
-    output: string;
-}
-/**
- * Export memory nodes in the requested format.
- *
- * @param baseDir - Project base directory
- * @param options - Export options
- */
-export declare function exportMemory(baseDir: string, options?: ExportOptions): Promise<ExportResult>;

package/dist/mem-id.d.ts

@@ -1,91 +0,0 @@
-/**
- * Memory ID Generator (WU-1465)
- *
- * Hash-based collision-free ID generation for memory nodes.
- * Format: mem-[4 hex chars] derived from content hash.
- * Supports hierarchical IDs (mem-a1b2.1.2) for sub-task decomposition.
- *
- * @see {@link tools/lib/__tests__/mem-id.test.mjs} - Tests
- * @see {@link tools/lib/memory-schema.mjs} - Schema definitions
- */
-/**
- * Regex patterns for memory ID validation
- */
-export declare const MEM_ID_PATTERNS: {
-    /**
-     * Base memory ID format: mem-[a-f0-9]{4}
-     * Only lowercase hex characters (0-9, a-f)
-     */
-    BASE_ID: RegExp;
-    /**
-     * Hierarchical memory ID format: mem-[a-f0-9]{4}(.[1-9][0-9]*)*
-     * Base ID followed by optional dot-separated positive integers
-     * Examples: mem-a1b2, mem-a1b2.1, mem-a1b2.1.2
-     */
-    HIERARCHICAL_ID: RegExp;
-};
-/**
- * Generates a deterministic memory ID from content.
- *
- * Uses SHA-256 hash of the content, taking the first 4 hex characters.
- * Same content always produces the same ID (deterministic).
- *
- * @param content - Content to hash for ID generation
- * @returns Memory ID in format mem-[a-f0-9]{4}
- *
- * @example
- * const id = generateMemId('discovered file at src/utils.mjs');
- * // Returns something like 'mem-a3f2'
- */
-export declare function generateMemId(content: string): string;
-/**
- * Generates a hierarchical memory ID by appending an index to a parent ID.
- *
- * Used for sub-task decomposition where a parent task (mem-a1b2) has
- * child tasks (mem-a1b2.1, mem-a1b2.2) and grandchildren (mem-a1b2.1.1).
- *
- * @param parentId - Parent memory ID (base or hierarchical)
- * @param index - Positive integer index (1-based)
- * @returns Hierarchical memory ID
- * @throws If parentId is invalid or index is not positive
- *
- * @example
- * generateHierarchicalId('mem-a1b2', 1);     // 'mem-a1b2.1'
- * generateHierarchicalId('mem-a1b2.1', 2);  // 'mem-a1b2.1.2'
- */
-export declare function generateHierarchicalId(parentId: string, index: number): string;
-/**
- * Validation result from validateMemId
- */
-export interface MemIdValidationResult {
-    /** Whether the ID is valid */
-    valid: boolean;
-    /** Type of ID if valid */
-    type?: 'base' | 'hierarchical';
-    /** Base ID portion if hierarchical */
-    baseId?: string;
-    /** Hierarchical indices (empty for base IDs) */
-    indices: number[];
-    /** Error message if invalid */
-    error?: string;
-}
-/**
- * Validates a memory ID and extracts its components.
- *
- * Returns validation result with type classification and parsed components.
- * Compatible with MEMORY_PATTERNS.MEMORY_ID from memory-schema.mjs.
- *
- * @param id - Memory ID to validate
- * @returns Validation result with parsed components
- *
- * @example
- * validateMemId('mem-a1b2');
- * // { valid: true, type: 'base', baseId: 'mem-a1b2', indices: [] }
- *
- * validateMemId('mem-a1b2.1.2');
- * // { valid: true, type: 'hierarchical', baseId: 'mem-a1b2', indices: [1, 2] }
- *
- * validateMemId('invalid');
- * // { valid: false, error: 'Invalid memory ID format', indices: [] }
- */
-export declare function validateMemId(id: string): MemIdValidationResult;

package/dist/mem-init-core.d.ts

@@ -1,93 +0,0 @@
-/**
- * Memory Init Core (WU-1464)
- *
- * Core logic for initializing memory layer in a repository.
- * Creates .lumenflow/memory/ directory with empty memory.jsonl and config.yaml.
- *
- * @see {@link tools/__tests__/mem-init.test.mjs} - Tests
- * @see {@link tools/lib/memory-store.mjs} - Memory store operations
- * @see {@link tools/lib/memory-schema.mjs} - Memory schema definitions
- */
-/**
- * Memory layer file/directory paths
- *
- * Uses LUMENFLOW_MEMORY_PATHS from local paths.ts to avoid circular dependency.
- */
-export declare const MEMORY_PATHS: {
-    /** Memory directory relative to project root */
-    MEMORY_DIR: ".lumenflow/memory";
-    /** Memory JSONL file name */
-    MEMORY_FILE: string;
-    /** Config YAML file name */
-    CONFIG_FILE: string;
-};
-/**
- * Default memory layer configuration
- *
- * Retention values are in seconds:
- * - ephemeral: 0 (immediate discard)
- * - session: 3600 (1 hour)
- * - wu: 604800 (7 days)
- * - project: -1 (never expire)
- */
-export declare const DEFAULT_CONFIG: {
-    /** Config schema version */
-    version: number;
-    /** Retention policy for each lifecycle */
-    retention: {
-        /** Ephemeral nodes are discarded immediately after use */
-        ephemeral: number;
-        /** Session nodes expire after 1 hour */
-        session: number;
-        /** WU nodes expire after 7 days */
-        wu: number;
-        /** Project nodes never expire (-1 = infinite) */
-        project: number;
-    };
-};
-/**
- * Memory initialization paths
- */
-interface InitMemoryPaths {
-    memoryDir: string;
-    memoryJsonl: string;
-    configYaml: string;
-}
-/**
- * Memory initialization created flags
- */
-interface InitMemoryCreated {
-    directory: boolean;
-    memoryJsonl: boolean;
-    configYaml: boolean;
-}
-/**
- * Memory initialization result
- */
-export interface InitMemoryResult {
-    success: boolean;
-    alreadyInitialized: boolean;
-    paths: InitMemoryPaths;
-    created: InitMemoryCreated;
-}
-/**
- * Initialize memory layer in a repository.
- *
- * Creates:
- * - .lumenflow/memory/ directory
- * - memory.jsonl (empty if not exists)
- * - config.yaml (default settings if not exists)
- *
- * Idempotent: Running multiple times does not corrupt existing data.
- *
- * @param baseDir - Base directory of the repository
- * @returns Result object with success, paths, and created flags
- *
- * @example
- * const result = await initMemory(process.cwd());
- * if (result.success) {
- *   console.log('Memory initialized at:', result.paths.memoryDir);
- * }
- */
-export declare function initMemory(baseDir: string): Promise<InitMemoryResult>;
-export {};

package/dist/mem-ready-core.d.ts

@@ -1,56 +0,0 @@
-/**
- * Memory Ready Core (WU-1468)
- *
- * Deterministic ready-work query for "what next?" oracle.
- * Returns open nodes with no blockers, ordered by priority then createdAt.
- *
- * Ordering algorithm:
- * 1. Priority ASC (P0 first, then P1, P2, P3; nodes without priority last)
- * 2. CreatedAt ASC (oldest first for same priority)
- * 3. ID ASC (stable sort for identical priority and timestamp)
- *
- * A node is "ready" if:
- * - Linked to the specified WU
- * - Not blocked by another node (no `blocks` relationship pointing to it)
- * - No `metadata.blocked_by` array set
- * - Lifecycle is not `ephemeral`
- * - Status is not `closed` (metadata.status !== 'closed')
- *
- * @see {@link tools/mem-ready.mjs} - CLI implementation
- * @see {@link tools/__tests__/mem-ready.test.mjs} - Tests
- */
-import { type MemoryNode } from './memory-schema.js';
-/**
- * Query options for ready nodes
- */
-export interface QueryOptions {
-    /** WU ID to query (required) */
-    wuId: string;
-    /** Filter by node type (optional) */
-    type?: string;
-}
-/**
- * Query ready nodes for a WU.
- *
- * Returns unblocked, open nodes linked to the WU in deterministic order:
- * 1. Priority (P0 first, then P1, P2, P3; nodes without priority last)
- * 2. CreatedAt (oldest first for same priority)
- * 3. ID (alphabetical for stable sort)
- *
- * @param baseDir - Base directory containing .lumenflow/memory
- * @param options - Query options
- * @returns Deterministically ordered ready nodes
- * @throws If WU ID format is invalid or file contains malformed JSON
- *
- * @example
- * const ready = await queryReadyNodes('/path/to/project', { wuId: 'WU-1234' });
- * console.log(`${ready.length} nodes ready for processing`);
- *
- * @example
- * // Filter by type
- * const discoveries = await queryReadyNodes('/path/to/project', {
- *   wuId: 'WU-1234',
- *   type: 'discovery',
- * });
- */
-export declare function queryReadyNodes(baseDir: string, options: QueryOptions): Promise<MemoryNode[]>;

package/dist/mem-signal-core.d.ts

@@ -1,132 +0,0 @@
-/**
- * Memory Signal Core Logic (WU-1473)
- *
- * Core logic for creating coordination signals between parallel agents.
- * Enables sub-100ms agent communication via JSONL append operations.
- *
- * Features:
- * - Append-only writes for sub-100ms performance
- * - WU-scoped signals for focused coordination
- * - Lane-targeted signals for cross-team communication
- * - Read/unread tracking for mem:inbox integration
- *
- * @see {@link tools/mem-signal.mjs} - CLI wrapper
- * @see {@link tools/__tests__/mem-signal.test.mjs} - Tests
- */
-/**
- * Signal file name constant
- */
-export declare const SIGNAL_FILE_NAME = "signals.jsonl";
-/**
- * Signal structure
- */
-export interface Signal {
-    /** Unique signal identifier (sig-XXXXXXXX) */
-    id: string;
-    /** Signal content/message */
-    message: string;
-    /** ISO 8601 timestamp */
-    created_at: string;
-    /** Whether signal has been read */
-    read: boolean;
-    /** Optional WU ID scope */
-    wu_id?: string;
-    /** Optional target lane */
-    lane?: string;
-}
-/**
- * Result of creating a signal
- */
-export interface CreateSignalResult {
-    /** Whether signal was created successfully */
-    success: boolean;
-    /** The created signal object */
-    signal: Signal;
-}
-/**
- * Options for creating a signal
- */
-export interface CreateSignalOptions {
-    /** Signal message content (required) */
-    message: string;
-    /** WU ID to scope signal to */
-    wuId?: string;
-    /** Lane to target signal to */
-    lane?: string;
-}
-/**
- * Options for loading signals
- */
-export interface LoadSignalsOptions {
-    /** Filter by WU ID */
-    wuId?: string;
-    /** Filter by lane */
-    lane?: string;
-    /** Only return unread signals */
-    unreadOnly?: boolean;
-    /** Only return signals created after this time */
-    since?: Date | string;
-}
-/**
- * Result of marking signals as read
- */
-export interface MarkAsReadResult {
-    /** Number of signals marked as read */
-    markedCount: number;
-}
-/**
- * Creates a coordination signal between parallel agents.
- *
- * Signals are appended to signals.jsonl using append-only writes
- * for sub-100ms performance. Signals can be scoped to a specific
- * WU or targeted at a specific lane.
- *
- * @param {string} baseDir - Project base directory
- * @param {CreateSignalOptions} options - Signal options
- * @returns {Promise<CreateSignalResult>} Result with created signal
- * @throws {Error} If message is missing or WU ID is invalid
- *
- * @example
- * const result = await createSignal('/project', {
- *   message: 'Starting feature implementation',
- *   wuId: 'WU-1473',
- *   lane: 'Operations: Tooling',
- * });
- */
-export declare function createSignal(baseDir: string, options: CreateSignalOptions): Promise<CreateSignalResult>;
-/**
- * Loads signals from the signals file with optional filtering.
- *
- * Signals are returned in chronological order (oldest first).
- * Supports filtering by WU ID, lane, and read status.
- *
- * @param {string} baseDir - Project base directory
- * @param {LoadSignalsOptions} [options={}] - Filter options
- * @returns {Promise<Signal[]>} Array of signals matching filters
- *
- * @example
- * // Load all signals
- * const all = await loadSignals('/project');
- *
- * // Load unread signals for a specific WU
- * const unread = await loadSignals('/project', {
- *   wuId: 'WU-1473',
- *   unreadOnly: true,
- * });
- */
-export declare function loadSignals(baseDir: string, options?: LoadSignalsOptions): Promise<Signal[]>;
-/**
- * Marks signals as read by updating the signals file.
- *
- * Reads the entire file, updates the read status for matching IDs,
- * and writes back. Only signals that were previously unread are counted.
- *
- * @param baseDir - Project base directory
- * @param signalIds - Array of signal IDs to mark as read
- * @returns Result with count of signals marked
- *
- * @example
- * const result = await markSignalsAsRead('/project', ['sig-abc12345', 'sig-def67890']);
- * console.log(result.markedCount); // 2
- */
-export declare function markSignalsAsRead(baseDir: string, signalIds: string[]): Promise<MarkAsReadResult>;

package/dist/mem-start-core.d.ts

@@ -1,76 +0,0 @@
-/**
- * Memory Start Core (WU-1466)
- *
- * Core logic for creating session nodes linked to WUs.
- * Called by wu:claim enhancement for context restoration after /clear.
- *
- * Features:
- * - Creates session nodes with WU reference
- * - Stores agent type, start timestamp, context tier
- * - Idempotent: multiple starts create separate sessions
- * - Auto-initializes memory layer if not present
- *
- * @see {@link tools/mem-start.mjs} - CLI wrapper
- * @see {@link tools/__tests__/mem-start.test.mjs} - Tests
- * @see {@link tools/lib/memory-schema.mjs} - Schema definitions
- */
-/**
- * Session start options
- */
-export interface StartSessionOptions {
-    /** Work Unit ID (required) */
-    wuId: string;
-    /** Agent type (defaults to 'unknown') */
-    agentType?: string;
-    /** Context tier (defaults to 'full') */
-    contextTier?: string;
-}
-/**
- * Session node structure
- */
-interface SessionNode {
-    id: string;
-    type: 'session';
-    lifecycle: 'wu';
-    content: string;
-    created_at: string;
-    wu_id: string;
-    session_id: string;
-    metadata: {
-        agentType: string;
-        contextTier: string;
-    };
-}
-/**
- * Session start result
- */
-export interface StartSessionResult {
-    /** Whether the operation succeeded */
-    success: boolean;
-    /** Created session node */
-    session: SessionNode;
-}
-/**
- * Creates a new session node linked to a WU.
- *
- * Creates a session-type memory node with:
- * - Unique ID (mem-XXXX format)
- * - Link to WU via wu_id field
- * - Agent type and context tier in metadata
- * - UUID session_id for unique identification
- *
- * @param baseDir - Base directory containing .lumenflow/memory/
- * @param options - Session options
- * @returns Result with created session node
- * @throws If wuId is missing or invalid
- *
- * @example
- * const result = await startSession('/path/to/project', {
- *   wuId: 'WU-1234',
- *   agentType: 'general-purpose',
- *   contextTier: 'core',
- * });
- * console.log(result.session.id); // 'mem-a1b2'
- */
-export declare function startSession(baseDir: string, options: StartSessionOptions): Promise<StartSessionResult>;
-export {};

package/dist/mem-summarize-core.d.ts

@@ -1,105 +0,0 @@
-/**
- * Memory Summarize Core (WU-1471)
- *
- * Rollup older memory nodes into summary nodes for compaction.
- * Implements forgetting as first-class feature.
- *
- * Features:
- * - Aggregate checkpoint/note/discovery nodes into summaries
- * - Mark originals for cleanup after summary creation
- * - Respect lifecycle TTL (ephemeral, session, wu, project)
- * - Support dry-run mode for preview
- *
- * @see {@link tools/mem-summarize.mjs} - CLI wrapper
- * @see {@link tools/__tests__/mem-summarize.test.mjs} - Tests
- */
-import { type MemoryNode } from './memory-schema.js';
-/**
- * Summarize options
- */
-export interface SummarizeOptions {
-    /** WU ID to summarize (e.g., 'WU-1234') */
-    wuId: string;
-    /** If true, preview without modifications */
-    dryRun?: boolean;
-}
-/**
- * Summary node structure
- */
-interface SummaryNode {
-    id: string;
-    type: 'summary';
-    lifecycle: 'project';
-    content: string;
-    created_at: string;
-    wu_id: string;
-    metadata: {
-        source_nodes: string[];
-        source_count: number;
-        summarized_at: string;
-    };
-}
-/**
- * Summarize result
- */
-export interface SummarizeResult {
-    /** Whether summarization succeeded */
-    success: boolean;
-    /** Created summary node */
-    summary: SummaryNode;
-    /** Node IDs marked for cleanup */
-    markedForCleanup: string[];
-    /** True if in dry-run mode */
-    dryRun?: boolean;
-    /** Ratio of source nodes to summary */
-    compactionRatio: number;
-}
-/**
- * Filter nodes that can be summarized for a given WU.
- *
- * Excludes:
- * - Nodes from different WUs
- * - Ephemeral lifecycle nodes (already transient)
- * - Already-summarized nodes (have summarized_into metadata)
- * - Summary nodes themselves
- *
- * @param nodes - All memory nodes
- * @param wuId - WU ID to filter by
- * @returns Summarizable nodes
- */
-export declare function filterSummarizableNodes(nodes: MemoryNode[], wuId: string): MemoryNode[];
-/**
- * Calculate compaction ratio (source nodes / summary nodes).
- *
- * @param sourceCount - Number of source nodes
- * @param summaryCount - Number of summary nodes created
- * @returns Compaction ratio (0 if invalid input)
- */
-export declare function getCompactionRatio(sourceCount: number, summaryCount: number): number;
-/**
- * Summarize memory nodes for a closed WU.
- *
- * Aggregates checkpoint, note, and discovery nodes into a single
- * summary node. Original nodes are marked for cleanup (unless
- * they have project lifecycle).
- *
- * @param baseDir - Base directory containing .lumenflow/memory/
- * @param options - Summarization options
- * @returns Result with summary and cleanup info
- * @throws If no summarizable nodes found for WU
- *
- * @example
- * // Summarize nodes for a completed WU
- * const result = await summarizeWu(baseDir, { wuId: 'WU-1234' });
- * console.log(`Created summary ${result.summary.id}`);
- * console.log(`Compaction ratio: ${result.compactionRatio}:1`);
- *
- * @example
- * // Preview without modifications
- * const preview = await summarizeWu(baseDir, {
- *   wuId: 'WU-1234',
- *   dryRun: true,
- * });
- */
-export declare function summarizeWu(baseDir: string, options: SummarizeOptions): Promise<SummarizeResult>;
-export {};