@lumenflow/memory 2.2.2 → 2.3.1

package/dist/mem-profile-core.js

@@ -0,0 +1,184 @@
+/**
+ * Memory Profile Core (WU-1237)
+ *
+ * Generates project knowledge profiles for agent context injection.
+ *
+ * Features:
+ * - Filters to lifecycle=project nodes only
+ * - Configurable limit (default N=20)
+ * - Tag-based filtering
+ * - Output format compatible with mem:context
+ * - Deterministic ordering by recency
+ *
+ * @see {@link packages/@lumenflow/cli/src/mem-profile.ts} - CLI wrapper
+ * @see {@link packages/@lumenflow/memory/__tests__/mem-profile-core.test.ts} - Tests
+ */
+import path from 'node:path';
+import { loadMemory } from './memory-store.js';
+import { LUMENFLOW_MEMORY_PATHS } from './paths.js';
+/**
+ * Default maximum number of nodes to include in profile
+ */
+export const DEFAULT_PROFILE_LIMIT = 20;
+/**
+ * Section header for profile output
+ */
+const PROFILE_SECTION_HEADER = '## Project Profile';
+/**
+ * Comparator for sorting nodes by recency (most recent first).
+ * Uses created_at as primary sort, id as secondary for stability.
+ *
+ * @param a - First node
+ * @param b - Second node
+ * @returns Comparison result
+ */
+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);
+}
+/**
+ * Filters nodes by lifecycle=project
+ *
+ * @param nodes - All nodes
+ * @returns Only project-level nodes
+ */
+function filterProjectNodes(nodes) {
+    return nodes.filter((node) => node.lifecycle === 'project');
+}
+/**
+ * Filters nodes by tag
+ *
+ * @param nodes - Nodes to filter
+ * @param tag - Tag to filter by
+ * @returns Nodes with the specified tag
+ */
+function filterByTag(nodes, tag) {
+    return nodes.filter((node) => node.tags?.includes(tag));
+}
+/**
+ * Formats a single node for profile output
+ *
+ * @param node - Node to format
+ * @returns Formatted line
+ */
+function formatNode(node) {
+    const timestamp = new Date(node.created_at).toISOString().split('T')[0];
+    return `- [${node.id}] (${timestamp}): ${node.content}`;
+}
+/**
+ * Formats all nodes into a profile block
+ *
+ * @param nodes - Nodes to format
+ * @returns Formatted profile block
+ */
+function formatProfileBlock(nodes) {
+    if (nodes.length === 0) {
+        return '';
+    }
+    const lines = [PROFILE_SECTION_HEADER, ''];
+    for (const node of nodes) {
+        lines.push(formatNode(node));
+    }
+    lines.push('');
+    return lines.join('\n');
+}
+/**
+ * Calculates tag statistics for nodes
+ *
+ * @param nodes - Nodes to analyze
+ * @returns Tag counts
+ */
+function calculateTagStats(nodes) {
+    const tagCounts = {};
+    for (const node of nodes) {
+        if (node.tags) {
+            for (const tag of node.tags) {
+                tagCounts[tag] = (tagCounts[tag] || 0) + 1;
+            }
+        }
+    }
+    return tagCounts;
+}
+/**
+ * Generates a project knowledge profile for context injection.
+ *
+ * Filters to project-level nodes, applies tag filter if specified,
+ * sorts by recency, and limits to the configured maximum.
+ *
+ * Output is formatted for integration with mem:context.
+ *
+ * @param baseDir - Base directory containing .lumenflow/memory
+ * @param options - Profile generation options
+ * @returns Result with nodes and formatted profile block
+ *
+ * @example
+ * // Get top 20 project memories
+ * const result = await generateProfile('/path/to/project');
+ * console.log(result.profileBlock);
+ *
+ * @example
+ * // Get top 10 decisions
+ * const result = await generateProfile('/path/to/project', {
+ *   limit: 10,
+ *   tag: 'decision',
+ * });
+ */
+export async function generateProfile(baseDir, options = {}) {
+    const { limit = DEFAULT_PROFILE_LIMIT, tag } = options;
+    const memoryDir = path.join(baseDir, LUMENFLOW_MEMORY_PATHS.MEMORY_DIR);
+    // Load all memory nodes
+    let allNodes = [];
+    try {
+        const memory = await loadMemory(memoryDir);
+        allNodes = memory.nodes;
+    }
+    catch (error) {
+        // If memory directory doesn't exist or is empty, return empty result
+        const err = error;
+        if (err.code === 'ENOENT') {
+            return {
+                success: true,
+                nodes: [],
+                profileBlock: '',
+                stats: {
+                    totalProjectNodes: 0,
+                    includedNodes: 0,
+                    byTag: {},
+                },
+            };
+        }
+        throw error;
+    }
+    // Filter to project lifecycle only
+    let projectNodes = filterProjectNodes(allNodes);
+    // Store total before any additional filtering
+    const totalProjectNodes = projectNodes.length;
+    // Apply tag filter if specified
+    if (tag) {
+        projectNodes = filterByTag(projectNodes, tag);
+    }
+    // Sort by recency (most recent first)
+    const sortedNodes = [...projectNodes].sort(compareByRecency);
+    // Apply limit
+    const limitedNodes = sortedNodes.slice(0, limit);
+    // Calculate statistics
+    const stats = {
+        totalProjectNodes,
+        includedNodes: limitedNodes.length,
+        byTag: calculateTagStats(limitedNodes),
+    };
+    // Format the profile block
+    const profileBlock = formatProfileBlock(limitedNodes);
+    return {
+        success: true,
+        nodes: limitedNodes,
+        profileBlock,
+        stats,
+    };
+}

package/dist/mem-promote-core.js

@@ -0,0 +1,233 @@
+/**
+ * Memory Promote Core (WU-1237)
+ *
+ * Promotes session/WU learnings into project-level knowledge nodes.
+ *
+ * Features:
+ * - Promote individual nodes to project lifecycle
+ * - Promote all summaries from a WU
+ * - Enforced taxonomy tags (decision, convention, pattern, etc.)
+ * - Creates discovered_from relationships for provenance
+ * - Dry-run mode for preview without writes
+ *
+ * @see {@link packages/@lumenflow/cli/src/mem-promote.ts} - CLI wrapper
+ * @see {@link packages/@lumenflow/memory/__tests__/mem-promote-core.test.ts} - Tests
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { loadMemory, appendNode } from './memory-store.js';
+import { MEMORY_PATTERNS } from './memory-schema.js';
+import { generateMemId } from './mem-id.js';
+import { LUMENFLOW_MEMORY_PATHS } from './paths.js';
+/**
+ * Relationships file name
+ */
+const RELATIONSHIPS_FILE_NAME = 'relationships.jsonl';
+/**
+ * Allowed tags for promoted nodes.
+ * These form the project knowledge taxonomy.
+ */
+export const ALLOWED_PROMOTION_TAGS = [
+    'decision',
+    'convention',
+    'pattern',
+    'pitfall',
+    'interface',
+    'invariant',
+    'faq',
+];
+/**
+ * Error messages for validation
+ */
+const ERROR_MESSAGES = {
+    NODE_NOT_FOUND: 'Node not found',
+    ALREADY_PROJECT: 'Node is already at project lifecycle',
+    INVALID_TAG: `Tag must be one of: ${ALLOWED_PROMOTION_TAGS.join(', ')}`,
+    INVALID_WU_ID: 'Invalid WU ID format. Expected pattern: WU-XXX (e.g., WU-1234)',
+};
+/**
+ * Validates the promotion tag against allowed taxonomy
+ *
+ * @param tag - Tag to validate
+ * @throws If tag is not in ALLOWED_PROMOTION_TAGS
+ */
+function validateTag(tag) {
+    if (!ALLOWED_PROMOTION_TAGS.includes(tag)) {
+        throw new Error(ERROR_MESSAGES.INVALID_TAG);
+    }
+}
+/**
+ * Validates WU ID format
+ *
+ * @param wuId - WU ID to validate
+ * @throws If WU ID is invalid
+ */
+function validateWuId(wuId) {
+    if (!MEMORY_PATTERNS.WU_ID.test(wuId)) {
+        throw new Error(ERROR_MESSAGES.INVALID_WU_ID);
+    }
+}
+/**
+ * Appends a relationship to the relationships.jsonl file
+ *
+ * @param memoryDir - Memory directory path
+ * @param relationship - Relationship to append
+ */
+async function appendRelationship(memoryDir, relationship) {
+    const filePath = path.join(memoryDir, RELATIONSHIPS_FILE_NAME);
+    const line = JSON.stringify(relationship) + '\n';
+    await fs.appendFile(filePath, line, { encoding: 'utf-8' });
+}
+/**
+ * Creates a promoted node from a source node
+ *
+ * @param sourceNode - Source node to promote
+ * @param tag - Taxonomy tag to apply
+ * @returns New node with project lifecycle
+ */
+function createPromotedNode(sourceNode, tag) {
+    const now = new Date().toISOString();
+    // Generate new ID based on content + timestamp for uniqueness
+    const newId = generateMemId(`${sourceNode.content}${now}`);
+    // Build tags array, ensuring the promotion tag is included
+    const existingTags = sourceNode.tags ?? [];
+    const tags = existingTags.includes(tag) ? existingTags : [...existingTags, tag];
+    return {
+        id: newId,
+        type: sourceNode.type,
+        lifecycle: 'project',
+        content: sourceNode.content,
+        created_at: now,
+        wu_id: sourceNode.wu_id,
+        session_id: sourceNode.session_id,
+        metadata: {
+            ...sourceNode.metadata,
+            promoted_from: sourceNode.id,
+            promoted_at: now,
+        },
+        tags,
+    };
+}
+/**
+ * Creates a discovered_from relationship between promoted and source nodes
+ *
+ * @param promotedNodeId - ID of the promoted node
+ * @param sourceNodeId - ID of the source node
+ * @returns Relationship object
+ */
+function createRelationship(promotedNodeId, sourceNodeId) {
+    return {
+        from_id: promotedNodeId,
+        to_id: sourceNodeId,
+        type: 'discovered_from',
+        created_at: new Date().toISOString(),
+        metadata: {},
+    };
+}
+/**
+ * Promotes a single node to project lifecycle.
+ *
+ * Creates a new project-level node with the same content and a
+ * discovered_from relationship back to the source node.
+ *
+ * @param baseDir - Base directory containing .lumenflow/memory
+ * @param options - Promotion options
+ * @returns Result with the promoted node
+ * @throws If node not found, already project level, or invalid tag
+ *
+ * @example
+ * const result = await promoteNode('/path/to/project', {
+ *   nodeId: 'mem-abc1',
+ *   tag: 'pattern',
+ * });
+ * console.log(`Promoted to ${result.promotedNode.id}`);
+ */
+export async function promoteNode(baseDir, options) {
+    const { nodeId, tag, dryRun = false } = options;
+    // Validate tag
+    validateTag(tag);
+    const memoryDir = path.join(baseDir, LUMENFLOW_MEMORY_PATHS.MEMORY_DIR);
+    // Load memory and find the source node
+    const memory = await loadMemory(memoryDir);
+    const sourceNode = memory.byId.get(nodeId);
+    if (!sourceNode) {
+        throw new Error(`${ERROR_MESSAGES.NODE_NOT_FOUND}: ${nodeId}`);
+    }
+    if (sourceNode.lifecycle === 'project') {
+        throw new Error(`${ERROR_MESSAGES.ALREADY_PROJECT}: ${nodeId}`);
+    }
+    // Create the promoted node
+    const promotedNode = createPromotedNode(sourceNode, tag);
+    // Create the relationship
+    const relationship = createRelationship(promotedNode.id, sourceNode.id);
+    // Write if not dry run
+    if (!dryRun) {
+        await appendNode(memoryDir, promotedNode);
+        await appendRelationship(memoryDir, relationship);
+    }
+    return {
+        success: true,
+        promotedNode,
+        relationship,
+        dryRun,
+    };
+}
+/**
+ * Promotes all summaries from a WU to project lifecycle.
+ *
+ * Finds all summary-type nodes linked to the WU and promotes each one
+ * to project level with discovered_from relationships.
+ *
+ * @param baseDir - Base directory containing .lumenflow/memory
+ * @param options - Promotion options
+ * @returns Result with all promoted nodes
+ * @throws If WU ID is invalid or tag is invalid
+ *
+ * @example
+ * const result = await promoteFromWu('/path/to/project', {
+ *   wuId: 'WU-1234',
+ *   tag: 'decision',
+ * });
+ * console.log(`Promoted ${result.promotedNodes.length} summaries`);
+ */
+export async function promoteFromWu(baseDir, options) {
+    const { wuId, tag, dryRun = false } = options;
+    // Validate inputs
+    validateWuId(wuId);
+    validateTag(tag);
+    const memoryDir = path.join(baseDir, LUMENFLOW_MEMORY_PATHS.MEMORY_DIR);
+    // Load memory
+    const memory = await loadMemory(memoryDir);
+    // Find all summaries for this WU that aren't already project level
+    const wuNodes = memory.byWu.get(wuId) ?? [];
+    const summaries = wuNodes.filter((node) => node.type === 'summary' && node.lifecycle !== 'project');
+    // If no summaries, return empty result
+    if (summaries.length === 0) {
+        return {
+            success: true,
+            promotedNodes: [],
+            relationships: [],
+            dryRun,
+        };
+    }
+    const promotedNodes = [];
+    const relationships = [];
+    // Promote each summary
+    for (const summary of summaries) {
+        const promotedNode = createPromotedNode(summary, tag);
+        const relationship = createRelationship(promotedNode.id, summary.id);
+        promotedNodes.push(promotedNode);
+        relationships.push(relationship);
+        // Write if not dry run
+        if (!dryRun) {
+            await appendNode(memoryDir, promotedNode);
+            await appendRelationship(memoryDir, relationship);
+        }
+    }
+    return {
+        success: true,
+        promotedNodes,
+        relationships,
+        dryRun,
+    };
+}

package/dist/mem-ready-core.js

@@ -16,8 +16,8 @@
  * - Lifecycle is not `ephemeral`
  * - Status is not `closed` (metadata.status !== 'closed')
  *
- * @see {@link tools/mem-ready.mjs} - CLI implementation
- * @see {@link tools/__tests__/mem-ready.test.mjs} - Tests
+ * @see {@link packages/@lumenflow/cli/src/mem-ready.ts} - CLI implementation
+ * @see {@link packages/@lumenflow/cli/src/__tests__/mem-ready.test.ts} - Tests
  */
 import fs from 'node:fs/promises';
 import path from 'node:path';

package/dist/mem-signal-core.js

@@ -10,8 +10,8 @@
  * - 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
+ * @see {@link packages/@lumenflow/cli/src/mem-signal.ts} - CLI wrapper
+ * @see {@link packages/@lumenflow/cli/src/__tests__/mem-signal.test.ts} - Tests
  */
 import { randomBytes } from 'node:crypto';
 import fs from 'node:fs/promises';
@@ -22,7 +22,7 @@ import { LUMENFLOW_MEMORY_PATHS } from './paths.js';
  */
 export const SIGNAL_FILE_NAME = 'signals.jsonl';
 /**
- * WU ID validation pattern (from memory-schema.mjs)
+ * WU ID validation pattern (from memory-schema.ts)
  */
 const WU_ID_PATTERN = /^WU-\d+$/;
 /**

package/dist/mem-start-core.js

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

package/dist/mem-summarize-core.js

@@ -10,8 +10,8 @@
  * - 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
+ * @see {@link packages/@lumenflow/cli/src/mem-summarize.ts} - CLI wrapper
+ * @see {@link packages/@lumenflow/cli/src/__tests__/mem-summarize.test.ts} - Tests
  */
 import { loadMemory, appendNode } from './memory-store.js';
 import { generateMemId } from './mem-id.js';

package/dist/mem-triage-core.js

@@ -8,18 +8,15 @@
  * - 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
+ * @see {@link packages/@lumenflow/cli/src/mem-triage.ts} - CLI wrapper
+ * @see {@link packages/@lumenflow/cli/src/__tests__/mem-triage.test.ts} - Tests
  */
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import { loadMemory, appendNode } from './memory-store.js';
 import { validateLaneFormat } from '@lumenflow/core/lane-checker';
+import { createWuPaths } from '@lumenflow/core/lib/wu-paths.js';
 import { LUMENFLOW_MEMORY_PATHS } from './paths.js';
-/**
- * WU directory path relative to base
- */
-const WU_DIR = 'docs/04-operations/tasks/wu';
 /**
  * Relationships file name
  */
@@ -244,7 +241,8 @@ export async function archiveDiscovery(baseDir, options) {
  * @returns Next WU ID (e.g., 'WU-1502')
  */
 async function getNextWuId(baseDir) {
-    const wuDir = path.join(baseDir, WU_DIR);
+    const paths = createWuPaths({ projectRoot: baseDir });
+    const wuDir = path.join(baseDir, paths.WU_DIR());
     let maxId = 0;
     try {
         const files = await fs.readdir(wuDir);

package/dist/memory-schema.js

@@ -9,7 +9,7 @@
  * - 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
+ * @see {@link packages/@lumenflow/cli/src/lib/__tests__/memory-schema.test.ts} - Tests
  */
 import { z } from 'zod';
 /**