@lumenflow/memory 1.0.0

package/dist/mem-checkpoint-core.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mem-checkpoint-core.js","sourceRoot":"","sources":["../src/mem-checkpoint-core.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,202 @@
+/**
+ * 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 .beacon/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-cleanup-core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mem-cleanup-core.d.ts","sourceRoot":"","sources":["../src/mem-cleanup-core.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAYH;;;;GAIG;AACH,eAAO,MAAM,gBAAgB;IAC3B,4DAA4D;;;;;IAG5D,mDAAmD;;;;;IAGnD,wDAAwD;;;;;IAGxD,gEAAgE;;;;;;CAEjE,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,cAAc,cAAc,CAAC;AAO1C;;GAEG;AAEH;;;;;;;GAOG;AAEH;;;;;;;;;;;;;;;;GAgBG;AAEH;;;;;;;;;;;;;GAaG;AACH,wBAAgB,QAAQ,CAAC,SAAS,KAAA,OAkBjC;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,IAAI,KAAA,EAAE,KAAK,KAAA,EAAE,GAAG,SAAa,WAc1D;AAgDD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,KAAA,EAAE,OAAO,KAAK;;;EA+ClD;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,KAAA,UAGrC;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,YAAY,KAAA,EAAE,UAAU,KAAA,UAK1D;AAyCD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAsB,aAAa,CAAC,OAAO,KAAA,EAAE,OAAO,KAAK;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoExD"}

package/dist/mem-cleanup-core.js

@@ -0,0 +1,364 @@
+/**
+ * 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 fs from 'node:fs/promises';
+import path from 'node:path';
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const ms = require('ms');
+import { loadMemory, MEMORY_FILE_NAME } from './memory-store.js';
+/**
+ * Memory directory path relative to base directory
+ */
+const MEMORY_DIR = '.beacon/memory';
+/**
+ * Lifecycle policy definitions
+ *
+ * Determines which nodes are eligible for cleanup based on lifecycle.
+ */
+export const LIFECYCLE_POLICY = {
+    /** Ephemeral nodes are always removed - scratch pad data */
+    ephemeral: { alwaysRemove: true, requiresSummarized: false },
+    /** Session nodes removed when session is closed */
+    session: { alwaysRemove: false, requiresSummarized: true },
+    /** WU nodes removed only when summarized_into is set */
+    wu: { alwaysRemove: false, requiresSummarized: true },
+    /** Project nodes are never removed - architectural knowledge */
+    project: { alwaysRemove: false, requiresSummarized: false, protected: true },
+};
+/**
+ * Metadata flag that indicates sensitive data requiring stricter retention
+ */
+export const SENSITIVE_FLAG = 'sensitive';
+/**
+ * Status value indicating an active session (WU-1554)
+ */
+const ACTIVE_SESSION_STATUS = 'active';
+/**
+ * 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 function parseTtl(ttlString) {
+    if (!ttlString || typeof ttlString !== 'string') {
+        throw new Error('Invalid TTL format: TTL string is required');
+    }
+    const trimmed = ttlString.trim();
+    if (!trimmed) {
+        throw new Error('Invalid TTL format: TTL string is required');
+    }
+    // Use ms package to parse the duration
+    const result = ms(trimmed);
+    if (result === undefined || result <= 0) {
+        throw new Error(`Invalid TTL format: "${ttlString}" is not a valid duration`);
+    }
+    return result;
+}
+/**
+ * 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 function isNodeExpired(node, ttlMs, now = Date.now()) {
+    if (!node.created_at) {
+        return false; // No timestamp means we can't determine age - safer to retain
+    }
+    const createdAt = new Date(node.created_at).getTime();
+    // Invalid date - safer to retain
+    if (Number.isNaN(createdAt)) {
+        return false;
+    }
+    const age = now - createdAt;
+    return age > ttlMs;
+}
+/**
+ * Check if a node is an active session (WU-1554).
+ *
+ * Active sessions are protected from all cleanup including TTL.
+ *
+ * @param node - Memory node to check
+ * @returns True if node is an active session
+ */
+function isActiveSession(node) {
+    if (node.type !== 'session') {
+        return false;
+    }
+    if (!node.metadata) {
+        return false;
+    }
+    return node.metadata.status === ACTIVE_SESSION_STATUS;
+}
+/**
+ * Check if a node has the sensitive flag set in metadata.
+ *
+ * @param node - Memory node to check
+ * @returns True if sensitive flag is set
+ */
+function hasSensitiveFlag(node) {
+    if (!node.metadata) {
+        return false;
+    }
+    return Object.hasOwn(node.metadata, SENSITIVE_FLAG) && node.metadata[SENSITIVE_FLAG] === true;
+}
+/**
+ * Get the lifecycle policy for a node's lifecycle.
+ *
+ * @param lifecycle - Lifecycle name
+ * @returns Policy object or undefined if not found
+ */
+function getLifecyclePolicy(lifecycle) {
+    if (!Object.hasOwn(LIFECYCLE_POLICY, lifecycle)) {
+        return undefined;
+    }
+    return LIFECYCLE_POLICY[lifecycle];
+}
+/**
+ * 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 function shouldRemoveNode(node, options = {}) {
+    const { sessionId, ttlMs, now = Date.now() } = options;
+    // WU-1554: Active sessions are always protected first
+    if (isActiveSession(node)) {
+        return { remove: false, reason: 'active-session-protected' };
+    }
+    // Check sensitive flag - stricter retention
+    if (hasSensitiveFlag(node)) {
+        return { remove: false, reason: 'sensitive-retained' };
+    }
+    const policy = getLifecyclePolicy(node.lifecycle);
+    // Unknown lifecycle - retain for safety
+    if (!policy) {
+        return { remove: false, reason: 'unknown-lifecycle' };
+    }
+    // Protected lifecycle (project) - never remove
+    if (policy.protected) {
+        return { remove: false, reason: 'protected-lifecycle' };
+    }
+    // WU-1554: TTL-based expiration (after protection checks)
+    if (ttlMs && isNodeExpired(node, ttlMs, now)) {
+        return { remove: true, reason: 'ttl-expired' };
+    }
+    // Ephemeral lifecycle - always remove
+    if (policy.alwaysRemove) {
+        return { remove: true, reason: 'ephemeral-cleanup' };
+    }
+    // Session lifecycle - remove if session is closed
+    if (node.lifecycle === 'session' && sessionId && node.session_id === sessionId) {
+        return { remove: true, reason: 'session-closed' };
+    }
+    // WU lifecycle - remove only if summarized
+    if (policy.requiresSummarized && node.metadata?.summarized_into) {
+        return { remove: true, reason: 'summarized-archived' };
+    }
+    // Default: retain
+    return { remove: false, reason: 'policy-retained' };
+}
+/**
+ * Calculate approximate byte size of a node when serialized.
+ *
+ * @param node - Memory node
+ * @returns Approximate byte size
+ */
+export function estimateNodeBytes(node) {
+    // JSON.stringify + newline character
+    return JSON.stringify(node).length + 1;
+}
+/**
+ * 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 function getCompactionRatio(removedCount, totalCount) {
+    if (totalCount === 0) {
+        return 0;
+    }
+    return removedCount / totalCount;
+}
+/**
+ * Reason-to-breakdown-key mapping for tracking cleanup statistics.
+ */
+const REASON_TO_BREAKDOWN_KEY = {
+    'ephemeral-cleanup': 'ephemeral',
+    'session-closed': 'session',
+    'summarized-archived': 'wu',
+    'sensitive-retained': 'sensitive',
+    'ttl-expired': 'ttlExpired',
+    'active-session-protected': 'activeSessionProtected',
+};
+/**
+ * Update breakdown statistics based on removal decision.
+ *
+ * @param breakdown - Breakdown object to update
+ * @param decision - Removal decision with reason
+ */
+function updateBreakdown(breakdown, decision) {
+    const key = REASON_TO_BREAKDOWN_KEY[decision.reason];
+    if (key && Object.hasOwn(breakdown, key)) {
+        breakdown[key]++;
+    }
+}
+/**
+ * Write retained nodes to memory file.
+ *
+ * @param memoryDir - Memory directory path
+ * @param retainedNodes - Nodes to write
+ */
+async function writeRetainedNodes(memoryDir, retainedNodes) {
+    const filePath = path.join(memoryDir, MEMORY_FILE_NAME);
+    const content = retainedNodes.map((n) => JSON.stringify(n)).join('\n') + (retainedNodes.length > 0 ? '\n' : '');
+    // eslint-disable-next-line security/detect-non-literal-fs-filename -- CLI tool writes known path
+    await fs.writeFile(filePath, content, { encoding: 'utf-8' });
+}
+/**
+ * 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 .beacon/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 async function cleanupMemory(baseDir, options = {}) {
+    const { dryRun = false, sessionId, ttl, ttlMs: providedTtlMs, now = Date.now() } = options;
+    const memoryDir = path.join(baseDir, MEMORY_DIR);
+    // WU-1554: Parse TTL if provided as string
+    let ttlMs = providedTtlMs;
+    if (ttl && !ttlMs) {
+        ttlMs = parseTtl(ttl);
+    }
+    // Load existing memory
+    const memory = await loadMemory(memoryDir);
+    // Track cleanup decisions
+    const removedIds = [];
+    const retainedIds = [];
+    const retainedNodes = [];
+    let bytesFreed = 0;
+    const breakdown = {
+        ephemeral: 0,
+        session: 0,
+        wu: 0,
+        sensitive: 0,
+        ttlExpired: 0,
+        activeSessionProtected: 0,
+    };
+    // Process each node
+    for (const node of memory.nodes) {
+        const decision = shouldRemoveNode(node, { sessionId, ttlMs, now });
+        if (decision.remove) {
+            removedIds.push(node.id);
+            bytesFreed += estimateNodeBytes(node);
+        }
+        else {
+            retainedIds.push(node.id);
+            retainedNodes.push(node);
+        }
+        updateBreakdown(breakdown, decision);
+    }
+    const compactionRatio = getCompactionRatio(removedIds.length, memory.nodes.length);
+    const baseResult = {
+        success: true,
+        removedIds,
+        retainedIds,
+        bytesFreed,
+        compactionRatio,
+        breakdown,
+    };
+    // WU-1554: Include TTL in result if provided
+    if (ttlMs) {
+        baseResult.ttlMs = ttlMs;
+    }
+    // If dry-run, return preview without modifications
+    if (dryRun) {
+        return { ...baseResult, dryRun: true };
+    }
+    // Write retained nodes back to file (rewrite entire file)
+    if (removedIds.length > 0) {
+        await writeRetainedNodes(memoryDir, retainedNodes);
+    }
+    return baseResult;
+}

package/dist/mem-cleanup-core.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mem-cleanup-core.js","sourceRoot":"","sources":["../src/mem-cleanup-core.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,93 @@
+/**
+ * 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 .beacon/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 {};

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

@@ -0,0 +1 @@
+{"version":3,"file":"mem-create-core.d.ts","sourceRoot":"","sources":["../src/mem-create-core.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAwPH;;;;;;;;;;;GAWG;AAEH;;;;;;;GAOG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAsB,gBAAgB,CAAC,OAAO,KAAA,EAAE,OAAO,KAAA;;;;;;;;;GA8HtD"}