@lumenflow/memory 2.9.0 → 2.11.0

package/dist/index.js

@@ -19,6 +19,7 @@ export * from './mem-index-core.js';
 export * from './mem-promote-core.js';
 export * from './mem-profile-core.js';
 export * from './mem-delete-core.js';
+export * from './mem-recover-core.js';
 export * from './memory-schema.js';
 export * from './memory-store.js';
 // WU-1238: Decay scoring and access tracking

package/dist/mem-recover-core.js

@@ -0,0 +1,258 @@
+/**
+ * Memory Recovery Core (WU-1390)
+ *
+ * Generates post-compaction recovery context for agents that have lost
+ * their LumenFlow instructions due to context compaction.
+ *
+ * Features:
+ * - Loads last checkpoint from memory layer
+ * - Extracts compact constraints from .lumenflow/constraints.md
+ * - Provides essential CLI commands reference
+ * - Size-limited output (default 2KB) to prevent truncation
+ * - Vendor-agnostic (works for any client)
+ *
+ * @see {@link packages/@lumenflow/cli/src/mem-recover.ts} - CLI wrapper
+ * @see {@link packages/@lumenflow/memory/__tests__/mem-recover-core.test.ts} - Tests
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { loadMemory } from './memory-store.js';
+import { MEMORY_PATTERNS } from './memory-schema.js';
+import { LUMENFLOW_MEMORY_PATHS } from './paths.js';
+/**
+ * Default maximum recovery context size in bytes (2KB)
+ * Smaller than spawn context to ensure it doesn't get truncated
+ */
+const DEFAULT_MAX_SIZE = 2048;
+/**
+ * Node type constant for checkpoint filtering
+ * @see {@link MEMORY_NODE_TYPES} in memory-schema.ts
+ */
+const NODE_TYPE_CHECKPOINT = 'checkpoint';
+/**
+ * Constraints file name within .lumenflow directory
+ */
+const CONSTRAINTS_FILENAME = 'constraints.md';
+/**
+ * Default value for unknown timestamps
+ */
+const TIMESTAMP_UNKNOWN = 'unknown';
+/**
+ * Error messages for validation
+ */
+const ERROR_MESSAGES = {
+    WU_ID_REQUIRED: 'wuId is required',
+    WU_ID_EMPTY: 'wuId cannot be empty',
+    WU_ID_INVALID: 'Invalid WU ID format. Expected pattern: WU-XXX (e.g., WU-1234)',
+};
+/**
+ * Section headers for recovery context formatting
+ */
+const SECTION_HEADERS = {
+    RECOVERY_TITLE: 'POST-COMPACTION RECOVERY',
+    LAST_CHECKPOINT: 'Last Checkpoint',
+    CRITICAL_RULES: 'Critical Rules (DO NOT FORGET)',
+    CLI_COMMANDS: 'CLI Commands',
+    NEXT_ACTION: 'Next Action',
+};
+/**
+ * Essential CLI commands for recovery (hardcoded, ~400 bytes)
+ */
+const ESSENTIAL_CLI_COMMANDS = `| Command | Purpose |
+|---------|---------|
+| pnpm wu:status --id WU-XXX | Check WU status and location |
+| pnpm wu:spawn --id WU-XXX | Generate fresh agent spawn prompt |
+| pnpm gates | Run quality gates before completion |
+| pnpm mem:checkpoint | Save progress checkpoint |`;
+/**
+ * Compact constraints (hardcoded fallback, ~800 bytes)
+ * Used when constraints.md cannot be loaded
+ */
+const FALLBACK_CONSTRAINTS = `1. **Worktree Discipline**: Work only in worktrees, treat main as read-only
+2. **WUs Are Specs**: Respect code_paths boundaries, no feature creep
+3. **Docs-Only vs Code**: Documentation WUs use --docs-only gates
+4. **LLM-First Inference**: Use LLMs for semantic tasks, no brittle regex
+5. **Gates Required**: Run pnpm gates before wu:done
+6. **Safety & Governance**: No secrets in code, stop-and-ask for sensitive ops
+7. **Test Ratchet**: NEW test failures block, pre-existing show warning only`;
+/**
+ * Validates WU ID format
+ */
+function validateWuId(wuId) {
+    if (wuId === undefined || wuId === null) {
+        throw new Error(ERROR_MESSAGES.WU_ID_REQUIRED);
+    }
+    if (wuId === '') {
+        throw new Error(ERROR_MESSAGES.WU_ID_EMPTY);
+    }
+    if (!MEMORY_PATTERNS.WU_ID.test(wuId)) {
+        throw new Error(ERROR_MESSAGES.WU_ID_INVALID);
+    }
+}
+/**
+ * Gets the most recent checkpoint for a WU from memory
+ */
+async function getLastCheckpoint(baseDir, wuId) {
+    const memoryDir = path.join(baseDir, LUMENFLOW_MEMORY_PATHS.MEMORY_DIR);
+    try {
+        const memory = await loadMemory(memoryDir);
+        const wuNodes = memory.byWu.get(wuId) ?? [];
+        // Filter to checkpoint nodes and sort by timestamp (most recent first)
+        const checkpoints = wuNodes
+            .filter((node) => node.type === NODE_TYPE_CHECKPOINT)
+            .sort((a, b) => {
+            const aTime = new Date(a.created_at).getTime();
+            const bTime = new Date(b.created_at).getTime();
+            return bTime - aTime; // Most recent first
+        });
+        if (checkpoints.length === 0) {
+            return null;
+        }
+        const latest = checkpoints[0];
+        return {
+            content: latest.content,
+            timestamp: latest.created_at,
+            progress: latest.metadata?.progress,
+            nextSteps: latest.metadata?.nextSteps,
+        };
+    }
+    catch {
+        // Memory layer not initialized or error loading
+        return null;
+    }
+}
+/**
+ * Loads compact constraints from .lumenflow/constraints.md
+ * Extracts just the rule summary from each of the 7 sections
+ */
+async function loadCompactConstraints(baseDir) {
+    const constraintsPath = path.join(baseDir, LUMENFLOW_MEMORY_PATHS.BASE, CONSTRAINTS_FILENAME);
+    try {
+        // eslint-disable-next-line security/detect-non-literal-fs-filename
+        const content = await fs.readFile(constraintsPath, 'utf-8');
+        // Extract section headers and their Rule lines
+        const rules = [];
+        const sectionPattern = /### (\d+)\. ([^\n]+)\n\n\*\*Rule:\*\* ([^\n]+)/g;
+        let match;
+        while ((match = sectionPattern.exec(content)) !== null) {
+            const [, num, title, rule] = match;
+            rules.push(`${num}. **${title}**: ${rule}`);
+        }
+        if (rules.length > 0) {
+            return rules.join('\n');
+        }
+        // Fallback if parsing failed
+        return FALLBACK_CONSTRAINTS;
+    }
+    catch {
+        // File not found or read error - use fallback
+        return FALLBACK_CONSTRAINTS;
+    }
+}
+/**
+ * Formats the recovery prompt with size budget
+ */
+function formatRecoveryPrompt(wuId, checkpoint, constraints, cliRef, maxSize) {
+    const header = `# ${SECTION_HEADERS.RECOVERY_TITLE}
+
+You are resuming work after context compaction. Your previous context was lost.
+**WU:** ${wuId}
+
+`;
+    const checkpointSection = checkpoint
+        ? `## ${SECTION_HEADERS.LAST_CHECKPOINT}
+- **Progress:** ${checkpoint.content}
+- **Timestamp:** ${checkpoint.timestamp}
+${checkpoint.nextSteps ? `- **Next Steps:** ${checkpoint.nextSteps}` : ''}
+
+`
+        : `## ${SECTION_HEADERS.LAST_CHECKPOINT}
+No checkpoint found for this WU.
+
+`;
+    // Only include sections if they have content
+    const constraintsSection = constraints
+        ? `## ${SECTION_HEADERS.CRITICAL_RULES}
+${constraints}
+
+`
+        : '';
+    const cliSection = cliRef
+        ? `## ${SECTION_HEADERS.CLI_COMMANDS}
+${cliRef}
+
+`
+        : '';
+    const footer = `## ${SECTION_HEADERS.NEXT_ACTION}
+Run \`pnpm wu:spawn --id ${wuId}\` to spawn a fresh agent with full context.
+`;
+    // Build sections in priority order
+    // Priority: header > checkpoint > constraints > CLI > footer
+    // If over budget, truncate checkpoint content first
+    const fixedContent = header + constraintsSection + cliSection + footer;
+    const fixedSize = Buffer.byteLength(fixedContent, 'utf-8');
+    if (fixedSize > maxSize) {
+        // Even fixed content exceeds budget - return minimal recovery
+        const minimal = `# ${SECTION_HEADERS.RECOVERY_TITLE}
+WU: ${wuId}
+Run: pnpm wu:spawn --id ${wuId}
+`;
+        return { context: minimal, truncated: true };
+    }
+    const remainingBudget = maxSize - fixedSize;
+    const checkpointSize = Buffer.byteLength(checkpointSection, 'utf-8');
+    if (checkpointSize <= remainingBudget) {
+        // Full checkpoint fits
+        const fullContext = header + checkpointSection + constraintsSection + cliSection + footer;
+        return { context: fullContext, truncated: false };
+    }
+    // Truncate checkpoint to fit
+    const truncatedCheckpoint = `## ${SECTION_HEADERS.LAST_CHECKPOINT}
+- **Progress:** (truncated - run mem:ready --wu ${wuId} for details)
+- **Timestamp:** ${checkpoint?.timestamp ?? TIMESTAMP_UNKNOWN}
+
+`;
+    const context = header + truncatedCheckpoint + constraintsSection + cliSection + footer;
+    return { context, truncated: true };
+}
+/**
+ * Generates post-compaction recovery context for an agent.
+ *
+ * The recovery context includes:
+ * - Last checkpoint for the WU (from memory layer)
+ * - Compact constraints (7 rules from constraints.md)
+ * - Essential CLI commands reference
+ * - Guidance to spawn fresh agent
+ *
+ * Size is limited to prevent the recovery context itself from being
+ * truncated or compacted.
+ *
+ * @param options - Recovery options
+ * @returns Recovery context result
+ *
+ * @example
+ * const result = await generateRecoveryContext({
+ *   wuId: 'WU-1390',
+ *   maxSize: 2048,
+ * });
+ * console.log(result.context);
+ */
+export async function generateRecoveryContext(options) {
+    const { wuId, baseDir = '.', maxSize = DEFAULT_MAX_SIZE, includeConstraints = true, includeCLIRef = true, } = options;
+    // Validate WU ID
+    validateWuId(wuId);
+    // Load checkpoint from memory
+    const checkpoint = await getLastCheckpoint(baseDir, wuId);
+    // Load constraints (or use empty if disabled)
+    const constraints = includeConstraints ? await loadCompactConstraints(baseDir) : '';
+    // Get CLI reference (or empty if disabled)
+    const cliRef = includeCLIRef ? ESSENTIAL_CLI_COMMANDS : '';
+    // Format with size budget
+    const { context, truncated } = formatRecoveryPrompt(wuId, checkpoint, constraints, cliRef, maxSize);
+    return {
+        success: true,
+        context,
+        size: Buffer.byteLength(context, 'utf-8'),
+        truncated,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumenflow/memory",
-  "version": "2.9.0",
+  "version": "2.11.0",
   "description": "Memory layer for LumenFlow workflow framework - session tracking, context recovery, and agent coordination",
   "keywords": [
     "lumenflow",
@@ -49,7 +49,7 @@
     "ms": "^2.1.3",
     "yaml": "^2.8.2",
     "zod": "^4.3.5",
-    "@lumenflow/core": "2.9.0"
+    "@lumenflow/core": "2.11.0"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "^4.0.17",

package/dist/index.d.ts

@@ -1,17 +0,0 @@
-/**
- * @lumenflow/memory - Session tracking and context recovery
- * @module @lumenflow/memory
- */
-export * from './mem-checkpoint-core.js';
-export * from './mem-cleanup-core.js';
-export * from './mem-create-core.js';
-export * from './mem-export-core.js';
-export * from './mem-id.js';
-export * from './mem-init-core.js';
-export * from './mem-ready-core.js';
-export * from './mem-signal-core.js';
-export * from './mem-start-core.js';
-export { filterSummarizableNodes, summarizeWu, getCompactionRatio as getSummarizeCompactionRatio, } from './mem-summarize-core.js';
-export * from './mem-triage-core.js';
-export * from './memory-schema.js';
-export * from './memory-store.js';

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

@@ -1,91 +0,0 @@
-/**
- * Memory Checkpoint Core (WU-1467, WU-1748)
- *
- * Core logic for creating checkpoint nodes for context snapshots.
- * Used before /clear or session handoff to preserve progress state.
- *
- * Features:
- * - Creates checkpoint nodes with progress summary and next steps
- * - Optional linking to sessions and WUs
- * - Supports handoff trigger detection
- * - Auto-initializes memory layer if not present
- * - WU-1748: Persists to wu-events.jsonl for cross-agent visibility
- *
- * @see {@link tools/mem-checkpoint.mjs} - CLI wrapper
- * @see {@link tools/__tests__/mem-checkpoint.test.mjs} - Tests
- * @see {@link tools/lib/memory-schema.mjs} - Schema definitions
- */
-/**
- * Checkpoint creation options
- */
-export interface CreateCheckpointOptions {
-    /** Checkpoint note/description (required) */
-    note: string;
-    /** Session ID to link checkpoint to */
-    sessionId?: string;
-    /** Work Unit ID to link checkpoint to */
-    wuId?: string;
-    /** Progress summary */
-    progress?: string;
-    /** Next steps description */
-    nextSteps?: string;
-    /** Handoff trigger (e.g., 'clear', 'handoff') */
-    trigger?: string;
-}
-/**
- * Checkpoint metadata stored in the node
- */
-interface CheckpointMetadata {
-    progress?: string;
-    nextSteps?: string;
-    trigger?: string;
-    [key: string]: unknown;
-}
-/**
- * Memory node structure for checkpoints
- */
-interface CheckpointNode {
-    id: string;
-    type: 'checkpoint';
-    lifecycle: 'session';
-    content: string;
-    created_at: string;
-    wu_id?: string;
-    session_id?: string;
-    metadata?: CheckpointMetadata;
-}
-/**
- * Checkpoint creation result
- */
-export interface CreateCheckpointResult {
-    /** Whether the operation succeeded */
-    success: boolean;
-    /** Created checkpoint node */
-    checkpoint: CheckpointNode;
-}
-/**
- * Creates a new checkpoint node for context preservation.
- *
- * Creates a checkpoint-type memory node with:
- * - Unique ID (mem-XXXX format)
- * - User-provided note in content
- * - Optional session and WU linking
- * - Progress summary and next steps in metadata
- *
- * @param baseDir - Base directory containing .lumenflow/memory/
- * @param options - Checkpoint options
- * @returns Result with created checkpoint node
- * @throws If note is missing or WU ID is invalid
- *
- * @example
- * const result = await createCheckpoint(baseDir, {
- *   note: 'Before /clear - completed TDD tests',
- *   sessionId: 'session-uuid',
- *   wuId: 'WU-1467',
- *   progress: 'TDD tests passing, core module implemented',
- *   nextSteps: 'Implement CLI wrapper, add package.json script',
- * });
- * console.log(result.checkpoint.id); // 'mem-a1b2'
- */
-export declare function createCheckpoint(baseDir: string, options: CreateCheckpointOptions): Promise<CreateCheckpointResult>;
-export {};

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

@@ -1,202 +0,0 @@
-/**
- * Memory Cleanup Core (WU-1472, WU-1554)
- *
- * Prune closed memory nodes based on lifecycle policy.
- * Implements compaction to prevent memory bloat.
- *
- * Features:
- * - Remove ephemeral nodes (always discarded)
- * - Remove session nodes when session is closed
- * - Archive summarized nodes (marked with summarized_into)
- * - Respect sensitive:true flag for stricter retention
- * - Support dry-run mode for preview
- * - Report compaction metrics (ratio, bytes freed)
- * - WU-1554: TTL-based expiration for old nodes
- * - WU-1554: Active session protection regardless of age
- *
- * Lifecycle Policy:
- * - ephemeral: Always removed (scratch pad data)
- * - session: Removed when session is closed
- * - wu: Removed when marked with summarized_into (after WU completion)
- * - project: Never removed (architectural knowledge)
- *
- * TTL Policy (WU-1554):
- * - Nodes older than TTL are removed regardless of lifecycle
- * - Active sessions (status: 'active') are never removed
- * - Project and sensitive nodes are protected from TTL removal
- *
- * @see {@link tools/mem-cleanup.mjs} - CLI wrapper
- * @see {@link tools/__tests__/mem-cleanup.test.mjs} - Tests
- */
-import type { MemoryNode } from './memory-schema.js';
-/**
- * Lifecycle policy definition
- */
-interface LifecyclePolicyEntry {
-    alwaysRemove: boolean;
-    requiresSummarized: boolean;
-    protected?: boolean;
-}
-/**
- * Lifecycle policy type for indexed access
- */
-type LifecycleType = 'ephemeral' | 'session' | 'wu' | 'project';
-/**
- * Lifecycle policy definitions
- *
- * Determines which nodes are eligible for cleanup based on lifecycle.
- */
-export declare const LIFECYCLE_POLICY: Record<LifecycleType, LifecyclePolicyEntry>;
-/**
- * Metadata flag that indicates sensitive data requiring stricter retention
- */
-export declare const SENSITIVE_FLAG = "sensitive";
-/**
- * Cleanup options for memory pruning
- */
-export interface CleanupOptions {
-    /** If true, preview without modifications */
-    dryRun?: boolean;
-    /** Session ID to consider closed (removes session lifecycle nodes) */
-    sessionId?: string;
-    /** TTL duration string (e.g., '30d', '7d', '24h') for age-based cleanup */
-    ttl?: string;
-    /** TTL in milliseconds (alternative to ttl string) */
-    ttlMs?: number;
-    /** Current timestamp for testing (defaults to Date.now()) */
-    now?: number;
-}
-/**
- * Breakdown of cleanup by lifecycle type
- */
-interface CleanupBreakdown {
-    ephemeral: number;
-    session: number;
-    wu: number;
-    sensitive: number;
-    ttlExpired: number;
-    activeSessionProtected: number;
-}
-/**
- * Result of cleanup operation
- */
-export interface CleanupResult {
-    /** Whether cleanup succeeded */
-    success: boolean;
-    /** IDs of removed nodes */
-    removedIds: string[];
-    /** IDs of retained nodes */
-    retainedIds: string[];
-    /** Approximate bytes freed (0 if dry-run) */
-    bytesFreed: number;
-    /** Ratio of removed to total nodes */
-    compactionRatio: number;
-    /** True if in dry-run mode */
-    dryRun?: boolean;
-    /** TTL in milliseconds if TTL was provided */
-    ttlMs?: number;
-    /** Breakdown by lifecycle */
-    breakdown: CleanupBreakdown;
-}
-/**
- * Parse a TTL duration string into milliseconds (WU-1554).
- *
- * Uses the `ms` package to parse human-readable duration strings.
- *
- * @param ttlString - TTL string (e.g., '30d', '7d', '24h', '60m')
- * @returns TTL in milliseconds
- * @throws If TTL format is invalid
- *
- * @example
- * parseTtl('30d'); // 2592000000 (30 days in ms)
- * parseTtl('7d');  // 604800000 (7 days in ms)
- * parseTtl('24h'); // 86400000 (24 hours in ms)
- */
-export declare function parseTtl(ttlString: string): number;
-/**
- * Check if a node has expired based on TTL (WU-1554).
- *
- * @param node - Memory node to check
- * @param ttlMs - TTL in milliseconds
- * @param now - Current timestamp (defaults to Date.now())
- * @returns True if node is older than TTL
- *
- * @example
- * // Check if node is older than 30 days
- * const expired = isNodeExpired(node, 30 * 24 * 60 * 60 * 1000);
- */
-export declare function isNodeExpired(node: MemoryNode, ttlMs: number, now?: number): boolean;
-/**
- * Check if a node should be removed based on lifecycle policy and TTL.
- *
- * Policy rules (checked in order):
- * 1. Active sessions are always retained (WU-1554)
- * 2. Sensitive nodes are always retained
- * 3. Protected lifecycle (project) nodes are never removed
- * 4. TTL expiration removes old nodes (WU-1554)
- * 5. Ephemeral nodes are always removed
- * 6. Session nodes are removed when their session is closed
- * 7. WU nodes are removed only when marked with summarized_into
- *
- * @param {MemoryNode} node - Memory node to check
- * @param {CleanupOptions} options - Cleanup options
- * @returns {{remove: boolean, reason: string}} Removal decision with reason
- */
-export declare function shouldRemoveNode(node: MemoryNode, options?: CleanupOptions): {
-    remove: boolean;
-    reason: string;
-};
-/**
- * Calculate approximate byte size of a node when serialized.
- *
- * @param node - Memory node
- * @returns Approximate byte size
- */
-export declare function estimateNodeBytes(node: MemoryNode): number;
-/**
- * Calculate compaction ratio (removed / total).
- *
- * @param removedCount - Number of removed nodes
- * @param totalCount - Total number of nodes
- * @returns Compaction ratio (0 to 1, or 0 if no nodes)
- */
-export declare function getCompactionRatio(removedCount: number, totalCount: number): number;
-/**
- * Perform memory cleanup based on lifecycle policy and TTL.
- *
- * Removes nodes according to lifecycle policy:
- * - Active sessions are never removed (WU-1554)
- * - Sensitive nodes are always retained
- * - Project nodes are never removed
- * - TTL-expired nodes are removed (WU-1554)
- * - Ephemeral nodes are always removed
- * - Session nodes are removed when their session is closed
- * - WU nodes are removed only when marked with summarized_into
- *
- * In dry-run mode, no modifications are made but the result shows
- * what would be removed.
- *
- * @param {string} baseDir - Base directory containing .lumenflow/memory/
- * @param {CleanupOptions} options - Cleanup options
- * @returns {Promise<CleanupResult>} Result with removed nodes and metrics
- *
- * @example
- * // Cleanup with dry-run to preview
- * const preview = await cleanupMemory(baseDir, { dryRun: true });
- * console.log(`Would remove ${preview.removedIds.length} nodes`);
- * console.log(`Would free ${preview.bytesFreed} bytes`);
- *
- * @example
- * // Cleanup session nodes when session closes
- * const result = await cleanupMemory(baseDir, {
- *   sessionId: 'abc-123-def-456',
- * });
- * console.log(`Removed ${result.removedIds.length} nodes`);
- *
- * @example
- * // WU-1554: TTL-based cleanup
- * const result = await cleanupMemory(baseDir, { ttl: '30d' });
- * console.log(`Removed ${result.breakdown.ttlExpired} expired nodes`);
- */
-export declare function cleanupMemory(baseDir: string, options?: CleanupOptions): Promise<CleanupResult>;
-export {};

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

@@ -1,93 +0,0 @@
-/**
- * Memory Create Core (WU-1469)
- *
- * Core logic for creating memory nodes with discovered-from provenance.
- * KEY DIFFERENTIATOR: supports discovered-from relationship for scope-creep
- * forensics. Creates audit trail of WHY work expanded, not just WHAT changed.
- *
- * Features:
- * - Creates all 5 node types: session, discovery, checkpoint, note, summary
- * - Auto-generates hash-based ID using mem-id
- * - Validates node against memory-schema
- * - Supports discovered-from relationship for provenance tracking
- *
- * @see {@link tools/mem-create.mjs} - CLI wrapper
- * @see {@link tools/__tests__/mem-create.test.mjs} - Tests
- * @see {@link tools/lib/memory-schema.mjs} - Schema definitions
- */
-import { type MemoryNode } from './memory-schema.js';
-/**
- * Memory node creation options
- */
-export interface CreateMemoryNodeOptions {
-    /** Node title/content (required) */
-    title: string;
-    /** Node type (session, discovery, checkpoint, note, summary) */
-    type?: string;
-    /** Work Unit ID to link node to */
-    wuId?: string;
-    /** Session ID to link node to */
-    sessionId?: string;
-    /** Parent node ID for provenance tracking */
-    discoveredFrom?: string;
-    /** Tags for categorization */
-    tags?: string[];
-    /** Priority level (P0, P1, P2, P3) */
-    priority?: string;
-}
-/**
- * Relationship between memory nodes
- */
-interface Relationship {
-    from_id: string;
-    to_id: string;
-    type: string;
-    created_at: string;
-}
-/**
- * Memory node creation result
- */
-export interface CreateMemoryNodeResult {
-    /** Whether the operation succeeded */
-    success: boolean;
-    /** Created memory node */
-    node: MemoryNode;
-    /** Created relationship (if discoveredFrom provided) */
-    relationship?: Relationship;
-}
-/**
- * Creates a new memory node with optional discovered-from provenance.
- *
- * Creates a memory node with:
- * - Unique ID (mem-XXXX format) generated from content hash
- * - User-provided title as content
- * - Type-appropriate lifecycle
- * - Optional discovered-from relationship for provenance tracking
- *
- * @param {string} baseDir - Base directory containing .lumenflow/memory/
- * @param {CreateMemoryNodeOptions} options - Node creation options
- * @returns {Promise<CreateMemoryNodeResult>} Result with created node and optional relationship
- * @throws {Error} If title is missing, type is invalid, or IDs are malformed
- *
- * @example
- * // Create a simple discovery node
- * const result = await createMemoryNode(baseDir, {
- *   title: 'Found relevant file at src/utils.mjs',
- *   type: 'discovery',
- *   wuId: 'WU-1469',
- * });
- *
- * @example
- * // Create a node with provenance (scope-creep tracking)
- * const parent = await createMemoryNode(baseDir, {
- *   title: 'Found src/components/',
- *   type: 'discovery',
- * });
- * const child = await createMemoryNode(baseDir, {
- *   title: 'Found src/components/Button.tsx',
- *   type: 'discovery',
- *   discoveredFrom: parent.node.id, // Track where this came from
- * });
- */
-export declare function createMemoryNode(baseDir: string, options: CreateMemoryNodeOptions): Promise<CreateMemoryNodeResult>;
-export {};