@lumenflow/memory 2.2.1 → 2.3.1

package/dist/decay/scoring.js

@@ -0,0 +1,143 @@
+/**
+ * Decay Scoring (WU-1238)
+ *
+ * Compute decay scores for memory nodes to manage relevance over time.
+ * Frequently accessed, recent memories rank higher than stale, rarely-used ones.
+ *
+ * Decay scoring algorithm:
+ * - recencyScore = exp(-age / HALF_LIFE_MS)
+ * - accessScore = log1p(access_count) / 10
+ * - importanceScore = priority P0=2, P1=1.5, P2=1, P3=0.5
+ * - decayScore = recencyScore * (1 + accessScore) * importanceScore
+ *
+ * @see {@link packages/@lumenflow/memory/__tests__/decay-scoring.test.ts} - Tests
+ */
+/**
+ * Default half-life for decay scoring: 30 days in milliseconds
+ */
+export const DEFAULT_HALF_LIFE_MS = 30 * 24 * 60 * 60 * 1000;
+/**
+ * Importance multipliers by priority level.
+ * P0 (critical) gets highest importance, P3 (low) gets lowest.
+ */
+export const IMPORTANCE_BY_PRIORITY = {
+    P0: 2,
+    P1: 1.5,
+    P2: 1,
+    P3: 0.5,
+};
+/**
+ * Default importance for nodes without priority
+ */
+const DEFAULT_IMPORTANCE = 1;
+/**
+ * Gets the reference timestamp for a node (most recent of created_at/updated_at).
+ *
+ * @param node - Memory node
+ * @returns Timestamp in milliseconds
+ */
+function getNodeTimestamp(node) {
+    const createdAt = new Date(node.created_at).getTime();
+    if (!node.updated_at) {
+        return createdAt;
+    }
+    const updatedAt = new Date(node.updated_at).getTime();
+    // Use the more recent timestamp
+    return Math.max(createdAt, updatedAt);
+}
+/**
+ * Compute recency score based on exponential decay.
+ *
+ * Formula: exp(-age / halfLife)
+ * - Returns 1 for brand new nodes
+ * - Returns exp(-1) ~= 0.368 at half-life
+ * - Approaches 0 for very old nodes
+ *
+ * @param node - Memory node to score
+ * @param halfLifeMs - Half-life in milliseconds
+ * @param now - Current timestamp (default: Date.now())
+ * @returns Recency score between 0 and 1
+ *
+ * @example
+ * const score = computeRecencyScore(node, DEFAULT_HALF_LIFE_MS);
+ * // Returns ~1 for recent nodes, ~0.368 at half-life, ~0 for old nodes
+ */
+export function computeRecencyScore(node, halfLifeMs = DEFAULT_HALF_LIFE_MS, now = Date.now()) {
+    const nodeTimestamp = getNodeTimestamp(node);
+    const age = now - nodeTimestamp;
+    // Exponential decay: exp(-age / halfLife)
+    return Math.exp(-age / halfLifeMs);
+}
+/**
+ * Compute access score based on access count.
+ *
+ * Formula: log1p(access_count) / 10
+ * - Returns 0 for nodes with no access
+ * - Logarithmic scaling prevents runaway scores for frequently accessed nodes
+ * - Bounded contribution (log1p(1000)/10 ~= 0.691)
+ *
+ * @param node - Memory node to score
+ * @returns Access score (0 to ~0.7 for typical access counts)
+ *
+ * @example
+ * const score = computeAccessScore(node);
+ * // Returns 0 for no access, ~0.07 for 1 access, ~0.24 for 10 accesses
+ */
+export function computeAccessScore(node) {
+    const accessCount = node.metadata?.access?.count ?? 0;
+    // log1p(x) = ln(1 + x), divided by 10 to keep contribution bounded
+    return Math.log1p(accessCount) / 10;
+}
+/**
+ * Compute importance score based on priority level.
+ *
+ * Priority multipliers:
+ * - P0: 2 (critical, highest importance)
+ * - P1: 1.5 (high)
+ * - P2: 1 (medium, default)
+ * - P3: 0.5 (low)
+ *
+ * @param node - Memory node to score
+ * @returns Importance multiplier (0.5 to 2)
+ *
+ * @example
+ * const score = computeImportanceScore(node);
+ * // Returns 2 for P0, 1.5 for P1, 1 for P2/default, 0.5 for P3
+ */
+export function computeImportanceScore(node) {
+    const priority = node.metadata?.priority;
+    if (!priority) {
+        return DEFAULT_IMPORTANCE;
+    }
+    return IMPORTANCE_BY_PRIORITY[priority] ?? DEFAULT_IMPORTANCE;
+}
+/**
+ * Compute the overall decay score for a memory node.
+ *
+ * Formula: recencyScore * (1 + accessScore) * importanceScore
+ *
+ * The score combines:
+ * - Recency: Exponential decay based on age
+ * - Access: Logarithmic boost for frequently accessed nodes
+ * - Importance: Priority-based multiplier
+ *
+ * Higher scores indicate more relevant nodes that should be retained.
+ * Lower scores indicate stale nodes that may be archived.
+ *
+ * @param node - Memory node to score
+ * @param options - Scoring options (now, halfLifeMs)
+ * @returns Decay score (0 to ~2 for typical nodes)
+ *
+ * @example
+ * const score = computeDecayScore(node, { now: Date.now() });
+ * // Returns high score for recent/accessed/important nodes
+ * // Returns low score for old/unused/low-priority nodes
+ */
+export function computeDecayScore(node, options = {}) {
+    const { now = Date.now(), halfLifeMs = DEFAULT_HALF_LIFE_MS } = options;
+    const recencyScore = computeRecencyScore(node, halfLifeMs, now);
+    const accessScore = computeAccessScore(node);
+    const importanceScore = computeImportanceScore(node);
+    // Combined formula: recency * (1 + access) * importance
+    return recencyScore * (1 + accessScore) * importanceScore;
+}

package/dist/index.js

@@ -3,6 +3,7 @@
  * @module @lumenflow/memory
  */
 export * from './mem-checkpoint-core.js';
+export * from './mem-context-core.js';
 export * from './mem-cleanup-core.js';
 export * from './mem-create-core.js';
 export * from './mem-export-core.js';
@@ -10,8 +11,17 @@ 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 './signal-cleanup-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 './mem-index-core.js';
+export * from './mem-promote-core.js';
+export * from './mem-profile-core.js';
+export * from './mem-delete-core.js';
 export * from './memory-schema.js';
 export * from './memory-store.js';
+// WU-1238: Decay scoring and access tracking
+export * from './decay/scoring.js';
+export * from './decay/access-tracking.js';
+export * from './decay/archival.js';

package/dist/mem-checkpoint-core.js

@@ -11,9 +11,9 @@
  * - 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
+ * @see {@link packages/@lumenflow/cli/src/mem-checkpoint.ts} - CLI wrapper
+ * @see {@link packages/@lumenflow/cli/src/__tests__/mem-checkpoint.test.ts} - Tests
+ * @see {@link packages/@lumenflow/cli/src/lib/memory-schema.ts} - Schema definitions
  */
 import fs from 'node:fs/promises';
 import path from 'node:path';

package/dist/mem-cleanup-core.js

@@ -1,5 +1,5 @@
 /**
- * Memory Cleanup Core (WU-1472, WU-1554)
+ * Memory Cleanup Core (WU-1472, WU-1554, WU-1238)
  *
  * Prune closed memory nodes based on lifecycle policy.
  * Implements compaction to prevent memory bloat.
@@ -13,6 +13,7 @@
  * - Report compaction metrics (ratio, bytes freed)
  * - WU-1554: TTL-based expiration for old nodes
  * - WU-1554: Active session protection regardless of age
+ * - WU-1238: Decay-based archival for stale nodes
  *
  * Lifecycle Policy:
  * - ephemeral: Always removed (scratch pad data)
@@ -25,15 +26,23 @@
  * - 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
+ * Decay Policy (WU-1238):
+ * - Nodes with decay score below threshold are archived (not deleted)
+ * - Project lifecycle nodes are never archived
+ * - Already archived nodes are skipped
+ *
+ * @see {@link packages/@lumenflow/cli/src/mem-cleanup.ts} - CLI wrapper
+ * @see {@link packages/@lumenflow/cli/src/__tests__/mem-cleanup.test.ts} - Tests
  */
 import fs from 'node:fs/promises';
 import path from 'node:path';
-// eslint-disable-next-line @typescript-eslint/no-require-imports
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
 const ms = require('ms');
-import { loadMemory, MEMORY_FILE_NAME } from './memory-store.js';
+import { loadMemoryAll, MEMORY_FILE_NAME } from './memory-store.js';
 import { LUMENFLOW_MEMORY_PATHS } from './paths.js';
+import { archiveByDecay, DEFAULT_DECAY_THRESHOLD, } from './decay/archival.js';
+import { DEFAULT_HALF_LIFE_MS } from './decay/scoring.js';
 /**
  * Lifecycle policy definitions
  *
@@ -299,17 +308,33 @@ async function writeRetainedNodes(memoryDir, retainedNodes) {
  * // WU-1554: TTL-based cleanup
  * const result = await cleanupMemory(baseDir, { ttl: '30d' });
  * console.log(`Removed ${result.breakdown.ttlExpired} expired nodes`);
+ *
+ * @example
+ * // WU-1238: Decay-based archival
+ * const result = await cleanupMemory(baseDir, { decay: true, decayThreshold: 0.1 });
+ * console.log(`Archived ${result.breakdown.decayArchived} stale nodes`);
  */
 export async function cleanupMemory(baseDir, options = {}) {
-    const { dryRun = false, sessionId, ttl, ttlMs: providedTtlMs, now = Date.now() } = options;
+    const { dryRun = false, sessionId, ttl, ttlMs: providedTtlMs, now = Date.now(), decay = false, decayThreshold = DEFAULT_DECAY_THRESHOLD, halfLifeMs = DEFAULT_HALF_LIFE_MS, } = options;
     const memoryDir = path.join(baseDir, LUMENFLOW_MEMORY_PATHS.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);
+    // WU-1238: Handle decay-based archival if requested
+    let decayResult;
+    if (decay) {
+        decayResult = await archiveByDecay(memoryDir, {
+            threshold: decayThreshold,
+            now,
+            halfLifeMs,
+            dryRun,
+        });
+    }
+    // Load existing memory (includes all nodes for policy-based cleanup)
+    // Note: We need to include archived nodes to properly track retained vs removed
+    const memory = await loadMemoryAll(memoryDir);
     // Track cleanup decisions
     const removedIds = [];
     const retainedIds = [];
@@ -322,6 +347,7 @@ export async function cleanupMemory(baseDir, options = {}) {
         sensitive: 0,
         ttlExpired: 0,
         activeSessionProtected: 0,
+        decayArchived: decayResult?.archivedIds.length ?? 0,
     };
     // Process each node
     for (const node of memory.nodes) {
@@ -349,6 +375,10 @@ export async function cleanupMemory(baseDir, options = {}) {
     if (ttlMs) {
         baseResult.ttlMs = ttlMs;
     }
+    // WU-1238: Add decay result if present
+    if (decayResult) {
+        baseResult.decayResult = decayResult;
+    }
     // If dry-run, return preview without modifications
     if (dryRun) {
         return { ...baseResult, dryRun: true };

package/dist/mem-context-core.js

@@ -0,0 +1,347 @@
+/**
+ * Memory Context Core (WU-1234, WU-1238, WU-1281)
+ *
+ * Core logic for generating deterministic, formatted context injection blocks
+ * for wu:spawn prompts. Produces structured markdown suitable for embedding
+ * into agent spawn prompts.
+ *
+ * Features:
+ * - Deterministic selection: filter by lifecycle, wu_id, recency
+ * - Structured output with clear sections (Project Profile, Summaries, WU Context, Discoveries)
+ * - Max context size configuration (default 4KB)
+ * - Graceful degradation (empty block if no memories match)
+ * - No LLM calls (vendor-agnostic)
+ * - WU-1238: Optional decay-based ranking (sortByDecay option)
+ * - WU-1238: Access tracking for nodes included in context (trackAccess option)
+ * - WU-1281: Lane filtering for project memories
+ * - WU-1281: Recency limits for summaries (maxRecentSummaries)
+ * - WU-1281: Bounded project nodes (maxProjectNodes)
+ * - WU-1281: WU-specific context prioritized over project-level
+ *
+ * @see {@link packages/@lumenflow/cli/src/mem-context.ts} - CLI wrapper
+ * @see {@link packages/@lumenflow/memory/__tests__/mem-context-core.test.ts} - Tests
+ */
+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';
+import { computeDecayScore, DEFAULT_HALF_LIFE_MS } from './decay/scoring.js';
+import { recordAccessBatch } from './decay/access-tracking.js';
+/**
+ * Default maximum context size in bytes (4KB)
+ */
+const DEFAULT_MAX_SIZE = 4096;
+/**
+ * WU-1281: Default maximum number of project nodes to include
+ * Prevents unbounded project memory growth from truncating WU-specific context
+ */
+const DEFAULT_MAX_PROJECT_NODES = 10;
+/**
+ * WU-1281: Default maximum number of recent summaries to include
+ * Ensures only the most relevant recent summaries are included
+ */
+const DEFAULT_MAX_RECENT_SUMMARIES = 5;
+/**
+ * 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 the context block
+ */
+const SECTION_HEADERS = {
+    PROJECT_PROFILE: '## Project Profile',
+    SUMMARIES: '## Summaries',
+    WU_CONTEXT: '## WU Context',
+    DISCOVERIES: '## Discoveries',
+};
+/**
+ * Validates WU ID format
+ *
+ * @param wuId - WU ID to validate
+ * @throws If WU ID is invalid
+ */
+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);
+    }
+}
+/**
+ * Comparator for sorting nodes by recency (most recent first)
+ * Uses created_at as primary sort, id as secondary for stability
+ */
+function compareByRecency(a, b) {
+    const aTime = new Date(a.created_at).getTime();
+    const bTime = new Date(b.created_at).getTime();
+    // Most recent first
+    if (aTime !== bTime) {
+        return bTime - aTime;
+    }
+    // Stable sort by ID for identical timestamps
+    return a.id.localeCompare(b.id);
+}
+/**
+ * WU-1238: Create comparator for sorting nodes by decay score (highest first)
+ * Uses decay score as primary sort, id as secondary for stability
+ */
+function createCompareByDecay(now, halfLifeMs) {
+    return (a, b) => {
+        const aScore = computeDecayScore(a, { now, halfLifeMs });
+        const bScore = computeDecayScore(b, { now, halfLifeMs });
+        // Highest score first
+        if (aScore !== bScore) {
+            return bScore - aScore;
+        }
+        // Stable sort by ID for identical scores
+        return a.id.localeCompare(b.id);
+    };
+}
+/**
+ * Filters nodes by lifecycle
+ */
+function filterByLifecycle(nodes, lifecycle) {
+    return nodes.filter((node) => node.lifecycle === lifecycle);
+}
+/**
+ * Filters nodes by WU ID
+ */
+function filterByWuId(nodes, wuId) {
+    return nodes.filter((node) => node.wu_id === wuId);
+}
+/**
+ * Filters nodes by type
+ */
+function filterByType(nodes, type) {
+    return nodes.filter((node) => node.type === type);
+}
+/**
+ * WU-1281: Filters nodes by lane
+ * Includes nodes that either:
+ * - Have matching metadata.lane
+ * - Have no lane set (general project knowledge)
+ */
+function filterByLane(nodes, lane) {
+    if (!lane) {
+        // No lane filter specified, include all
+        return nodes;
+    }
+    return nodes.filter((node) => {
+        const nodeLane = node.metadata?.lane;
+        // Include if no lane (general knowledge) or lane matches
+        return !nodeLane || nodeLane === lane;
+    });
+}
+/**
+ * WU-1281: Limits array to first N items
+ */
+function limitNodes(nodes, limit) {
+    if (limit === undefined || limit <= 0) {
+        return nodes;
+    }
+    return nodes.slice(0, limit);
+}
+/**
+ * Formats a single node for display
+ */
+function formatNode(node) {
+    const timestamp = new Date(node.created_at).toISOString().split('T')[0];
+    return `- [${node.id}] (${timestamp}): ${node.content}`;
+}
+/**
+ * Formats a section with header and nodes
+ */
+function formatSection(header, nodes) {
+    if (nodes.length === 0) {
+        return '';
+    }
+    const lines = [header, ''];
+    for (const node of nodes) {
+        lines.push(formatNode(node));
+    }
+    lines.push('');
+    return lines.join('\n');
+}
+/**
+ * Builds the context block header comment
+ * Note: Header does not include timestamp to ensure deterministic output
+ */
+function buildHeader(wuId) {
+    return `<!-- mem:context for ${wuId} -->\n\n`;
+}
+/**
+ * Creates an empty context result
+ */
+function createEmptyResult() {
+    return {
+        success: true,
+        contextBlock: '',
+        stats: {
+            totalNodes: 0,
+            byType: {},
+            truncated: false,
+            size: 0,
+        },
+    };
+}
+/**
+ * Adds a section to the sections array if it has content
+ */
+function addSectionIfNotEmpty(sections, header, nodes) {
+    const section = formatSection(header, nodes);
+    if (section) {
+        sections.push(section);
+    }
+}
+/**
+ * Truncates the context block to fit within max size
+ * Removes nodes from the end while keeping structure intact
+ */
+function truncateToSize(contextBlock, maxSize) {
+    if (contextBlock.length <= maxSize) {
+        return { content: contextBlock, truncated: false };
+    }
+    // Find the last complete section that fits
+    const lines = contextBlock.split('\n');
+    let currentSize = 0;
+    const truncatedLines = [];
+    let truncated = false;
+    for (const line of lines) {
+        const lineSize = line.length + 1; // +1 for newline
+        if (currentSize + lineSize > maxSize) {
+            truncated = true;
+            break;
+        }
+        truncatedLines.push(line);
+        currentSize += lineSize;
+    }
+    // Add truncation marker if truncated
+    if (truncated) {
+        truncatedLines.push('');
+        truncatedLines.push('<!-- truncated - context exceeded max size -->');
+    }
+    return { content: truncatedLines.join('\n'), truncated };
+}
+/**
+ * Generates a deterministic, formatted context injection block.
+ *
+ * Context block includes:
+ * 1. Project profile items (lifecycle=project memories)
+ * 2. Recent summaries relevant to the target WU
+ * 3. Current WU context (checkpoints, notes with wu_id match)
+ * 4. Open discoveries for the WU
+ *
+ * Selection is deterministic (filter by lifecycle, WU, tags, recency).
+ * No LLM calls are made (vendor-agnostic).
+ *
+ * @param baseDir - Base directory containing .lumenflow/memory
+ * @param options - Generation options
+ * @returns Result with context block and statistics
+ * @throws If WU ID is invalid or memory file is malformed
+ *
+ * @example
+ * const result = await generateContext('/path/to/project', {
+ *   wuId: 'WU-1234',
+ *   maxSize: 8192, // 8KB
+ * });
+ * console.log(result.contextBlock);
+ */
+export async function generateContext(baseDir, options) {
+    const { wuId, maxSize = DEFAULT_MAX_SIZE, sortByDecay = false, trackAccess = false, halfLifeMs = DEFAULT_HALF_LIFE_MS, now = Date.now(), 
+    // WU-1281: New options for lane filtering and limits
+    lane, maxRecentSummaries = DEFAULT_MAX_RECENT_SUMMARIES, maxProjectNodes = DEFAULT_MAX_PROJECT_NODES, } = options;
+    // Validate WU ID
+    validateWuId(wuId);
+    const memoryDir = path.join(baseDir, LUMENFLOW_MEMORY_PATHS.MEMORY_DIR);
+    const allNodes = await loadNodesOrEmpty(memoryDir);
+    if (allNodes.length === 0) {
+        return createEmptyResult();
+    }
+    // WU-1238: Choose comparator based on sortByDecay option
+    const sortComparator = sortByDecay ? createCompareByDecay(now, halfLifeMs) : compareByRecency;
+    // WU-1281: Collect WU-specific nodes FIRST (high priority)
+    // These are always included before project-level content
+    const summaryNodes = limitNodes([...filterByWuId(filterByType(allNodes, 'summary'), wuId)].sort(sortComparator), maxRecentSummaries);
+    const wuContextNodes = [...filterByWuId(allNodes, wuId)]
+        .filter((node) => node.type !== 'summary' && node.type !== 'discovery')
+        .sort(sortComparator);
+    const discoveryNodes = [...filterByWuId(filterByType(allNodes, 'discovery'), wuId)].sort(sortComparator);
+    // WU-1281: Collect project nodes with lane filtering and limits (lower priority)
+    const projectNodes = limitNodes(filterByLane([...filterByLifecycle(allNodes, 'project')].sort(sortComparator), lane), maxProjectNodes);
+    // WU-1281: Build context block with WU-specific content FIRST
+    // Order: WU Context -> Summaries -> Discoveries -> Project Profile
+    // This ensures WU-specific content is preserved when truncation occurs
+    const sections = [buildHeader(wuId)];
+    // WU-specific sections first (high priority)
+    addSectionIfNotEmpty(sections, SECTION_HEADERS.WU_CONTEXT, wuContextNodes);
+    addSectionIfNotEmpty(sections, SECTION_HEADERS.SUMMARIES, summaryNodes);
+    addSectionIfNotEmpty(sections, SECTION_HEADERS.DISCOVERIES, discoveryNodes);
+    // Project-level section last (lower priority, may be truncated)
+    addSectionIfNotEmpty(sections, SECTION_HEADERS.PROJECT_PROFILE, projectNodes);
+    // If no sections have content (only header), return empty
+    if (sections.length === 1) {
+        return createEmptyResult();
+    }
+    const rawContextBlock = sections.join('');
+    const { content: contextBlock, truncated } = truncateToSize(rawContextBlock, maxSize);
+    // Calculate statistics based on the limited node sets
+    const selectedNodes = [...wuContextNodes, ...summaryNodes, ...discoveryNodes, ...projectNodes];
+    const byType = {};
+    for (const node of selectedNodes) {
+        byType[node.type] = (byType[node.type] || 0) + 1;
+    }
+    // WU-1238: Track access for selected nodes if requested
+    const accessTracked = await trackAccessIfEnabled(trackAccess, selectedNodes, memoryDir, now, halfLifeMs);
+    return {
+        success: true,
+        contextBlock,
+        stats: {
+            totalNodes: selectedNodes.length,
+            byType,
+            truncated,
+            size: contextBlock.length,
+            ...(trackAccess ? { accessTracked } : {}),
+        },
+    };
+}
+/**
+ * Loads memory nodes, returning empty array if directory doesn't exist
+ */
+async function loadNodesOrEmpty(memoryDir) {
+    try {
+        const memory = await loadMemory(memoryDir);
+        return memory.nodes;
+    }
+    catch (error) {
+        const err = error;
+        if (err.code === 'ENOENT') {
+            return [];
+        }
+        throw error;
+    }
+}
+/**
+ * Tracks access for nodes if enabled, returns count of tracked nodes
+ */
+async function trackAccessIfEnabled(trackAccess, nodes, memoryDir, now, halfLifeMs) {
+    if (!trackAccess || nodes.length === 0) {
+        return 0;
+    }
+    try {
+        const nodeIds = nodes.map((n) => n.id);
+        const tracked = await recordAccessBatch(memoryDir, nodeIds, { now, halfLifeMs });
+        return tracked.length;
+    }
+    catch {
+        // Access tracking is best-effort; don't fail context generation
+        return 0;
+    }
+}

package/dist/mem-create-core.js

@@ -11,9 +11,9 @@
  * - 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
+ * @see {@link packages/@lumenflow/cli/src/mem-create.ts} - CLI wrapper
+ * @see {@link packages/@lumenflow/cli/src/__tests__/mem-create.test.ts} - Tests
+ * @see {@link packages/@lumenflow/cli/src/lib/memory-schema.ts} - Schema definitions
  */
 import fs from 'node:fs/promises';
 import path from 'node:path';
@@ -244,7 +244,7 @@ function getLifecycleForType(type) {
  * @example
  * // Create a simple discovery node
  * const result = await createMemoryNode(baseDir, {
- *   title: 'Found relevant file at src/utils.mjs',
+ *   title: 'Found relevant file at src/utils.ts',
  *   type: 'discovery',
  *   wuId: 'WU-1469',
  * });