@lumenflow/memory 2.10.0 → 2.11.0

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 {};

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

@@ -1,127 +0,0 @@
-/**
- * Memory Triage Core (WU-1470)
- *
- * Review discovery nodes and promote to WUs or archive.
- *
- * Features:
- * - List open discovery nodes with deterministic ordering
- * - Promote discovery to WU (integrates with wu:create)
- * - Archive discovery without promotion
- *
- * @see {@link tools/mem-triage.mjs} - CLI wrapper
- * @see {@link tools/__tests__/mem-triage.test.mjs} - Tests
- */
-/**
- * Memory node structure for triage operations
- */
-interface TriageMemoryNode {
-    id: string;
-    type: string;
-    lifecycle: string;
-    content: string;
-    created_at: string;
-    updated_at?: string;
-    wu_id?: string;
-    session_id?: string;
-    metadata?: Record<string, unknown>;
-    tags?: string[];
-}
-/**
- * Options for listing discoveries
- */
-export interface ListOptions {
-    /** Filter by WU ID (or 'unlinked' for nodes without wu_id) */
-    wuId?: string;
-    /** Filter by tag */
-    tag?: string;
-}
-/**
- * List open discovery nodes.
- *
- * Returns unblocked, non-archived discovery nodes in deterministic order.
- *
- * @param baseDir - Base directory
- * @param options - Filter options
- * @returns Open discovery nodes
- */
-export declare function listOpenDiscoveries(baseDir: string, options?: ListOptions): Promise<TriageMemoryNode[]>;
-/**
- * Options for archiving a discovery
- */
-export interface ArchiveOptions {
-    /** Node ID to archive */
-    nodeId: string;
-    /** Archive reason */
-    reason: string;
-}
-/**
- * Result of archiving a discovery
- */
-export interface ArchiveResult {
-    /** Whether archiving succeeded */
-    success: boolean;
-    /** Archived node ID */
-    nodeId: string;
-}
-/**
- * Archive a discovery node without promotion.
- *
- * Sets metadata.status to 'archived' and records the reason.
- *
- * @param baseDir - Base directory
- * @param options - Archive options
- * @returns Archive result
- * @throws If node not found, not a discovery, or already archived
- */
-export declare function archiveDiscovery(baseDir: string, options: ArchiveOptions): Promise<ArchiveResult>;
-/**
- * Options for promoting a discovery to a WU
- */
-export interface PromoteOptions {
-    /** Node ID to promote */
-    nodeId: string;
-    /** WU lane */
-    lane: string;
-    /** Custom WU title (defaults to discovery content) */
-    title?: string;
-    /** Explicit WU ID (defaults to next available) */
-    wuId?: string;
-    /** Priority override */
-    priority?: string;
-    /** If true, return spec without creating WU */
-    dryRun?: boolean;
-}
-/**
- * WU specification generated from promotion
- */
-export interface WUSpec {
-    /** WU ID */
-    id: string;
-    /** WU title */
-    title: string;
-    /** WU lane */
-    lane: string;
-    /** WU priority */
-    priority: string;
-    /** WU notes with provenance */
-    notes: string;
-}
-/**
- * Result of promoting a discovery
- */
-export interface PromoteResult {
-    /** Whether promotion succeeded */
-    success: boolean;
-    /** Generated WU specification */
-    wuSpec: WUSpec;
-}
-/**
- * Promote a discovery node to a WU.
- *
- * @param baseDir - Base directory
- * @param options - Promote options
- * @returns Promotion result
- * @throws If node not found, not a discovery, or already closed
- */
-export declare function promoteDiscovery(baseDir: string, options: PromoteOptions): Promise<PromoteResult>;
-export {};

package/dist/memory-schema.d.ts

@@ -1,150 +0,0 @@
-/**
- * Memory Schema (WU-1462)
- *
- * Zod schema for runtime validation of memory node structure.
- * Foundation for the entire memory layer (INIT-007 Phase 1).
- *
- * Defines schemas for:
- * - Memory nodes (5 types: session, discovery, checkpoint, note, summary)
- * - Lifecycles (4 levels: ephemeral, session, wu, project)
- * - Relationships (4 types: blocks, parent_child, related, discovered_from)
- *
- * @see {@link tools/lib/__tests__/memory-schema.test.mjs} - Tests
- */
-import { z } from 'zod';
-/**
- * Memory node types
- *
- * - session: Session-level context (agent startup, context snapshot)
- * - discovery: Found information (file locations, code patterns)
- * - checkpoint: Progress marker (task milestone, state save)
- * - note: Free-form annotation (observation, decision rationale)
- * - summary: Condensed context (session summary, WU summary)
- */
-export declare const MEMORY_NODE_TYPES: readonly ["session", "discovery", "checkpoint", "note", "summary"];
-/**
- * Memory lifecycle durations
- *
- * - ephemeral: Discarded immediately after use (scratch pad)
- * - session: Lives for current agent session only
- * - wu: Lives for WU duration (cleared on wu:done)
- * - project: Persists across WUs (architectural knowledge)
- */
-export declare const MEMORY_LIFECYCLES: readonly ["ephemeral", "session", "wu", "project"];
-/**
- * Relationship types between memory nodes
- *
- * - blocks: This node blocks another (dependency)
- * - parent_child: Hierarchical relationship (session contains discoveries)
- * - related: Semantic similarity or topical connection
- * - discovered_from: Source attribution (discovered from another node)
- */
-export declare const RELATIONSHIP_TYPES: readonly ["blocks", "parent_child", "related", "discovered_from"];
-/**
- * Regex patterns for memory validation
- */
-export declare const MEMORY_PATTERNS: {
-    /** Memory ID format: mem-[a-z0-9]{4} */
-    MEMORY_ID: RegExp;
-    /** WU ID format (reused from wu-schema) */
-    WU_ID: RegExp;
-};
-/**
- * Zod schema for Memory Node
- *
- * Validates memory nodes against the memory layer requirements.
- * All memory operations should validate against this schema.
- */
-export declare const MemoryNodeSchema: z.ZodObject<{
-    id: z.ZodString;
-    type: z.ZodEnum<{
-        session: "session";
-        discovery: "discovery";
-        checkpoint: "checkpoint";
-        note: "note";
-        summary: "summary";
-    }>;
-    lifecycle: z.ZodEnum<{
-        session: "session";
-        ephemeral: "ephemeral";
-        wu: "wu";
-        project: "project";
-    }>;
-    content: z.ZodString;
-    created_at: z.ZodString;
-    updated_at: z.ZodOptional<z.ZodString>;
-    wu_id: z.ZodOptional<z.ZodString>;
-    session_id: z.ZodOptional<z.ZodString>;
-    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
-}, z.core.$strip>;
-/**
- * Zod schema for Relationship between memory nodes
- *
- * Validates relationships between memory nodes.
- * Used for building the memory graph.
- */
-export declare const RelationshipSchema: z.ZodObject<{
-    from_id: z.ZodString;
-    to_id: z.ZodString;
-    type: z.ZodEnum<{
-        blocks: "blocks";
-        parent_child: "parent_child";
-        related: "related";
-        discovered_from: "discovered_from";
-    }>;
-    created_at: z.ZodOptional<z.ZodString>;
-    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-}, z.core.$strip>;
-/**
- * TypeScript types inferred from schemas
- */
-export type MemoryNode = z.infer<typeof MemoryNodeSchema>;
-export type Relationship = z.infer<typeof RelationshipSchema>;
-/**
- * Validates memory node data against schema
- *
- * @param data - Data to validate
- * @returns Validation result
- *
- * @example
- * const result = validateMemoryNode(nodeData);
- * if (!result.success) {
- *   result.error.issues.forEach(issue => {
- *     console.error(`${issue.path.join('.')}: ${issue.message}`);
- *   });
- * }
- */
-export declare function validateMemoryNode(data: unknown): z.ZodSafeParseResult<{
-    id: string;
-    type: "session" | "discovery" | "checkpoint" | "note" | "summary";
-    lifecycle: "session" | "ephemeral" | "wu" | "project";
-    content: string;
-    created_at: string;
-    updated_at?: string;
-    wu_id?: string;
-    session_id?: string;
-    metadata?: Record<string, unknown>;
-    tags?: string[];
-}>;
-/**
- * Validates relationship data against schema
- *
- * @param data - Data to validate
- * @returns Validation result
- *
- * @example
- * const result = validateRelationship(relData);
- * if (!result.success) {
- *   result.error.issues.forEach(issue => {
- *     console.error(`${issue.path.join('.')}: ${issue.message}`);
- *   });
- * }
- */
-export declare function validateRelationship(data: unknown): z.ZodSafeParseResult<{
-    from_id: string;
-    to_id: string;
-    type: "blocks" | "parent_child" | "related" | "discovered_from";
-    created_at?: string;
-    metadata?: Record<string, unknown>;
-}>;

package/dist/memory-store.d.ts

@@ -1,108 +0,0 @@
-/**
- * Memory Store (WU-1463)
- *
- * JSONL-based memory store with load, query, and append operations.
- * Git-friendly format with one node per line for merge-safe diffs.
- *
- * Features:
- * - Append-only writes (no full file rewrite)
- * - Indexed lookups by ID and WU
- * - Deterministic queryReady() ordering by priority then createdAt
- *
- * @see {@link tools/lib/__tests__/memory-store.test.mjs} - Tests
- * @see {@link tools/lib/memory-schema.mjs} - Schema definitions
- */
-import { type MemoryNode } from './memory-schema.js';
-/**
- * Memory file name constant
- */
-export declare const MEMORY_FILE_NAME = "memory.jsonl";
-/**
- * Indexed memory result from loadMemory
- */
-export interface IndexedMemory {
-    /** All loaded nodes in file order */
-    nodes: MemoryNode[];
-    /** Nodes indexed by ID */
-    byId: Map<string, MemoryNode>;
-    /** Nodes indexed by WU ID */
-    byWu: Map<string, MemoryNode[]>;
-}
-/**
- * Loads memory from JSONL file and returns indexed nodes.
- *
- * Handles:
- * - Missing file: returns empty result
- * - Empty file: returns empty result
- * - Empty lines: skipped gracefully
- * - Malformed JSON: throws error with line info
- * - Invalid nodes: throws validation error
- *
- * @param baseDir - Directory containing memory.jsonl
- * @returns Indexed memory nodes
- * @throws If file contains malformed JSON or invalid nodes
- *
- * @example
- * const memory = await loadMemory('/path/to/project');
- * const node = memory.byId.get('mem-abc1');
- * const wuNodes = memory.byWu.get('WU-1463') ?? [];
- */
-export declare function loadMemory(baseDir: string): Promise<IndexedMemory>;
-/**
- * Appends a single node to the memory file.
- *
- * Uses append mode to avoid full file rewrite.
- * Creates file if it doesn't exist.
- * Validates node before appending.
- *
- * @param baseDir - Directory containing memory.jsonl
- * @param node - Node to append
- * @returns The appended node
- * @throws If node fails validation
- *
- * @example
- * const node = await appendNode('/path/to/project', {
- *   id: 'mem-abc1',
- *   type: 'discovery',
- *   lifecycle: 'wu',
- *   content: 'Found relevant file',
- *   created_at: new Date().toISOString(),
- *   wu_id: 'WU-1463',
- * });
- */
-export declare function appendNode(baseDir: string, node: MemoryNode): Promise<MemoryNode>;
-/**
- * Queries nodes ready for processing by WU ID.
- *
- * Returns nodes linked to the WU in deterministic order:
- * 1. Priority (P0 first, then P1, P2, P3; nodes without priority last)
- * 2. Created timestamp (oldest first for same priority)
- * 3. ID (for stable sort when priority and timestamp match)
- *
- * @param baseDir - Directory containing memory.jsonl
- * @param wuId - WU ID to query (e.g., 'WU-1463')
- * @returns Deterministically ordered nodes for WU
- *
- * @example
- * const ready = await queryReady('/path/to/project', 'WU-1463');
- * // Process highest priority, oldest items first
- * for (const node of ready) {
- *   await processNode(node);
- * }
- */
-export declare function queryReady(baseDir: string, wuId: string): Promise<MemoryNode[]>;
-/**
- * Queries all nodes linked to a WU ID.
- *
- * Returns nodes in file order (insertion order).
- * Use queryReady() instead if you need deterministic priority ordering.
- *
- * @param baseDir - Directory containing memory.jsonl
- * @param wuId - WU ID to query (e.g., 'WU-1463')
- * @returns All nodes for WU in file order
- *
- * @example
- * const nodes = await queryByWu('/path/to/project', 'WU-1463');
- * console.log(`Found ${nodes.length} nodes for WU-1463`);
- */
-export declare function queryByWu(baseDir: string, wuId: string): Promise<MemoryNode[]>;