@lumenflow/memory 2.2.2 → 2.3.1

package/dist/mem-delete-core.js

@@ -0,0 +1,277 @@
+/**
+ * Memory Delete Core (WU-1284)
+ *
+ * Soft delete memory nodes via metadata.status=deleted.
+ * Respects append-only pattern by updating nodes in-place rather than removing.
+ *
+ * Features:
+ * - Delete by node ID(s)
+ * - Bulk delete via tag filter
+ * - Bulk delete via older-than filter
+ * - Dry-run preview mode
+ * - Preserves all original node data
+ *
+ * @see {@link packages/@lumenflow/memory/__tests__/mem-delete.test.ts} - Tests
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { loadMemory, MEMORY_FILE_NAME } from './memory-store.js';
+import { LUMENFLOW_MEMORY_PATHS } from './paths.js';
+/**
+ * Duration multipliers in milliseconds
+ */
+const DURATION_MULTIPLIERS = {
+    h: 60 * 60 * 1000,
+    d: 24 * 60 * 60 * 1000,
+    w: 7 * 24 * 60 * 60 * 1000,
+};
+/**
+ * Parse a duration string (e.g., '7d', '24h', '2w') to milliseconds
+ *
+ * @param duration - Duration string
+ * @returns Duration in milliseconds
+ * @throws If duration format is invalid
+ */
+function parseDuration(duration) {
+    const durationRegex = /^(\d+)([hdw])$/;
+    const match = durationRegex.exec(duration);
+    if (!match || match.length < 3) {
+        throw new Error(`Invalid duration format: ${duration}. Use format like '7d', '24h', '2w'`);
+    }
+    const valueStr = match[1];
+    const unit = match[2];
+    if (!valueStr || !unit) {
+        throw new Error(`Invalid duration format: ${duration}. Use format like '7d', '24h', '2w'`);
+    }
+    const value = parseInt(valueStr, 10);
+    const multiplier = DURATION_MULTIPLIERS[unit];
+    if (!multiplier) {
+        throw new Error(`Unknown duration unit: ${unit}`);
+    }
+    return value * multiplier;
+}
+/**
+ * Check if a node matches the tag filter
+ */
+function matchesTag(node, tag) {
+    return Array.isArray(node.tags) && node.tags.includes(tag);
+}
+/**
+ * Check if a node is older than the specified duration
+ */
+function isOlderThan(node, durationMs, referenceDate) {
+    const nodeDate = new Date(node.created_at);
+    const cutoffDate = new Date(referenceDate.getTime() - durationMs);
+    return nodeDate < cutoffDate;
+}
+/**
+ * Check if a node is already marked as deleted
+ */
+function isAlreadyDeleted(node) {
+    return node.metadata?.status === 'deleted';
+}
+/**
+ * Mark a node as deleted by updating its metadata
+ */
+function markAsDeleted(node) {
+    return {
+        ...node,
+        metadata: {
+            ...node.metadata,
+            status: 'deleted',
+            deleted_at: new Date().toISOString(),
+        },
+    };
+}
+/**
+ * Process nodeIds filter and add matches to delete set
+ */
+function processNodeIdsFilter(nodeIds, nodeMap, toDeleteSet, errors) {
+    for (const nodeId of nodeIds) {
+        const node = nodeMap.get(nodeId);
+        if (node) {
+            toDeleteSet.add(nodeId);
+        }
+        else {
+            errors.push(`Node not found: ${nodeId}`);
+        }
+    }
+}
+/**
+ * Process tag filter and add matches to delete set
+ */
+function processTagFilter(nodes, tag, toDeleteSet) {
+    for (const node of nodes) {
+        if (matchesTag(node, tag)) {
+            toDeleteSet.add(node.id);
+        }
+    }
+}
+/**
+ * Process olderThan filter, optionally intersected with tag filter
+ */
+function processOlderThanFilter(nodes, olderThan, referenceDate, tag, hasNodeIds, toDeleteSet) {
+    const durationMs = parseDuration(olderThan);
+    for (const node of nodes) {
+        const nodeIsOld = isOlderThan(node, durationMs, referenceDate);
+        if (tag) {
+            // Intersection: node must match BOTH tag and age filters
+            const shouldInclude = nodeIsOld && matchesTag(node, tag);
+            if (shouldInclude) {
+                toDeleteSet.add(node.id);
+            }
+            else {
+                // Remove if previously added by tag filter but not matching age
+                toDeleteSet.delete(node.id);
+            }
+        }
+        else if (!hasNodeIds && nodeIsOld) {
+            // No tag filter, no nodeIds: add all old nodes
+            toDeleteSet.add(node.id);
+        }
+    }
+}
+/**
+ * Find nodes to delete based on filters
+ */
+function findNodesToDelete(nodes, options) {
+    const { nodeIds, tag, olderThan, referenceDate = new Date() } = options;
+    const errors = [];
+    const toDeleteSet = new Set();
+    // Build a map for quick lookups
+    const nodeMap = new Map();
+    for (const node of nodes) {
+        nodeMap.set(node.id, node);
+    }
+    // Process nodeIds filter
+    if (nodeIds && nodeIds.length > 0) {
+        processNodeIdsFilter(nodeIds, nodeMap, toDeleteSet, errors);
+    }
+    // Process tag filter (before olderThan to allow intersection)
+    if (tag) {
+        processTagFilter(nodes, tag, toDeleteSet);
+    }
+    // Process olderThan filter (may intersect with tag filter)
+    if (olderThan) {
+        const hasNodeIds = Boolean(nodeIds && nodeIds.length > 0);
+        processOlderThanFilter(nodes, olderThan, referenceDate, tag, hasNodeIds, toDeleteSet);
+    }
+    // Get the actual nodes to delete
+    const toDelete = [];
+    for (const nodeId of toDeleteSet) {
+        const node = nodeMap.get(nodeId);
+        if (node) {
+            toDelete.push(node);
+        }
+    }
+    return { toDelete, errors };
+}
+/**
+ * Write updated nodes back to the JSONL file
+ * Rewrites the file to update nodes in-place (soft delete pattern)
+ */
+async function writeUpdatedNodes(baseDir, nodes) {
+    const filePath = path.join(baseDir, MEMORY_FILE_NAME);
+    const content = nodes.map((node) => JSON.stringify(node)).join('\n') + '\n';
+    // eslint-disable-next-line security/detect-non-literal-fs-filename -- path computed from known base and constant
+    await fs.writeFile(filePath, content, 'utf-8');
+}
+/**
+ * Delete memory nodes using soft-delete pattern (metadata.status=deleted)
+ *
+ * Respects the append-only pattern by updating nodes in-place rather than
+ * physically removing them from the file.
+ *
+ * @param baseDir - Project root directory containing .lumenflow/memory/
+ * @param options - Delete options (filters and dry-run)
+ * @returns Result with deleted IDs and any errors
+ *
+ * @example
+ * // Delete by ID
+ * await deleteMemoryNodes('/path', { nodeIds: ['mem-abc1'] });
+ *
+ * @example
+ * // Delete by tag (dry-run)
+ * await deleteMemoryNodes('/path', { tag: 'obsolete', dryRun: true });
+ *
+ * @example
+ * // Delete old nodes
+ * await deleteMemoryNodes('/path', { olderThan: '30d' });
+ */
+export async function deleteMemoryNodes(baseDir, options) {
+    const { nodeIds, tag, olderThan, dryRun = false } = options;
+    // Validate: at least one filter must be provided
+    if ((!nodeIds || nodeIds.length === 0) && !tag && !olderThan) {
+        return {
+            success: false,
+            deletedCount: 0,
+            deletedIds: [],
+            skippedIds: [],
+            dryRun,
+            errors: ['At least one filter (nodeIds, tag, or olderThan) is required'],
+        };
+    }
+    // WU-1285: Compute the memory directory path from baseDir
+    // The memory file lives at .lumenflow/memory/memory.jsonl
+    const memoryDir = path.join(baseDir, LUMENFLOW_MEMORY_PATHS.MEMORY_DIR);
+    // Load all memory including archived/deleted nodes
+    let memory;
+    try {
+        memory = await loadMemory(memoryDir, { includeArchived: true });
+    }
+    catch (err) {
+        const errMsg = err instanceof Error ? err.message : String(err);
+        return {
+            success: false,
+            deletedCount: 0,
+            deletedIds: [],
+            skippedIds: [],
+            dryRun,
+            errors: [`Failed to load memory: ${errMsg}`],
+        };
+    }
+    // Find nodes to delete
+    const { toDelete, errors } = findNodesToDelete(memory.nodes, options);
+    // Separate already-deleted nodes
+    const deletedIds = [];
+    const skippedIds = [];
+    const nodesToUpdate = [];
+    for (const node of toDelete) {
+        if (isAlreadyDeleted(node)) {
+            skippedIds.push(node.id);
+            errors.push(`Node already deleted: ${node.id}`);
+        }
+        else {
+            deletedIds.push(node.id);
+            nodesToUpdate.push(node);
+        }
+    }
+    // Apply deletion if not dry-run
+    if (!dryRun && nodesToUpdate.length > 0) {
+        // Build updated node list
+        const deletedIdSet = new Set(deletedIds);
+        const updatedNodes = memory.nodes.map((node) => {
+            if (deletedIdSet.has(node.id)) {
+                return markAsDeleted(node);
+            }
+            return node;
+        });
+        // Write back to file (using memoryDir, not baseDir)
+        await writeUpdatedNodes(memoryDir, updatedNodes);
+    }
+    // Determine success:
+    // - True if any nodes were deleted
+    // - True if all requested nodes were already deleted (skipped but valid)
+    // - False only if requested nodes don't exist (not found errors)
+    const hasNotFoundErrors = errors.some((e) => e.startsWith('Node not found:'));
+    const allNodesHandled = deletedIds.length > 0 || skippedIds.length > 0;
+    const success = !hasNotFoundErrors || allNodesHandled;
+    return {
+        success,
+        deletedCount: deletedIds.length,
+        deletedIds,
+        skippedIds,
+        dryRun,
+        errors,
+    };
+}

package/dist/mem-id.js

@@ -5,8 +5,8 @@
  * Format: mem-[4 hex chars] derived from content hash.
  * Supports hierarchical IDs (mem-a1b2.1.2) for sub-task decomposition.
  *
- * @see {@link tools/lib/__tests__/mem-id.test.mjs} - Tests
- * @see {@link tools/lib/memory-schema.mjs} - Schema definitions
+ * @see {@link packages/@lumenflow/cli/src/lib/__tests__/mem-id.test.ts} - Tests
+ * @see {@link packages/@lumenflow/cli/src/lib/memory-schema.ts} - Schema definitions
  */
 import { createHash } from 'node:crypto';
 /**
@@ -51,7 +51,7 @@ const ERROR_MESSAGES = {
  * @returns Memory ID in format mem-[a-f0-9]{4}
  *
  * @example
- * const id = generateMemId('discovered file at src/utils.mjs');
+ * const id = generateMemId('discovered file at src/utils.ts');
  * // Returns something like 'mem-a3f2'
  */
 export function generateMemId(content) {
@@ -90,7 +90,7 @@ export function generateHierarchicalId(parentId, index) {
  * Validates a memory ID and extracts its components.
  *
  * Returns validation result with type classification and parsed components.
- * Compatible with MEMORY_PATTERNS.MEMORY_ID from memory-schema.mjs.
+ * Compatible with MEMORY_PATTERNS.MEMORY_ID from memory-schema.ts.
  *
  * @param id - Memory ID to validate
  * @returns Validation result with parsed components

package/dist/mem-index-core.js

@@ -0,0 +1,307 @@
+/**
+ * Memory Index Core (WU-1235)
+ *
+ * Scans predictable project sources and produces project-lifecycle summary nodes.
+ * Creates memory nodes tagged with index:architecture, index:conventions,
+ * index:commands, index:invariants for agent context awareness.
+ *
+ * Features:
+ * - Scans README.md, LUMENFLOW.md, package.json, .lumenflow.config.yaml
+ * - Creates summary nodes with lifecycle=project
+ * - Includes provenance metadata (source_path, source_hash, indexed_at)
+ * - Idempotent: re-running updates/skips existing nodes
+ *
+ * @see {@link packages/@lumenflow/cli/src/mem-index.ts} - CLI wrapper
+ * @see {@link packages/@lumenflow/memory/__tests__/mem-index-core.test.ts} - Tests
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { generateMemId } from './mem-id.js';
+import { loadMemory, appendNode } from './memory-store.js';
+import { LUMENFLOW_MEMORY_PATHS } from './paths.js';
+/**
+ * Default sources to scan for project conventions
+ */
+const DEFAULT_SOURCES = [
+    {
+        path: 'README.md',
+        tags: ['index:architecture'],
+        description: 'Project overview and structure',
+    },
+    {
+        path: 'LUMENFLOW.md',
+        tags: ['index:conventions'],
+        description: 'Workflow conventions and guidelines',
+    },
+    {
+        path: 'package.json',
+        tags: ['index:architecture'],
+        description: 'Monorepo structure and dependencies',
+    },
+    {
+        path: '.lumenflow.config.yaml',
+        tags: ['index:commands', 'index:conventions'],
+        description: 'Workflow configuration and lane definitions',
+    },
+    {
+        path: '.lumenflow/constraints.md',
+        tags: ['index:invariants'],
+        description: 'Non-negotiable project constraints',
+    },
+];
+/** Maximum summary length in characters */
+const MAX_SUMMARY_LENGTH = 2000;
+/**
+ * Computes SHA-256 hash of content
+ *
+ * @param content - Content to hash
+ * @returns Hex-encoded hash
+ */
+function computeHash(content) {
+    return crypto.createHash('sha256').update(content).digest('hex').slice(0, 16);
+}
+/**
+ * Extracts summary from package.json content
+ *
+ * @param content - Raw JSON content
+ * @returns Summarized package info or null if parse fails
+ */
+function extractPackageJsonSummary(content) {
+    try {
+        const pkg = JSON.parse(content);
+        const summary = [];
+        if (pkg.name) {
+            summary.push(`Project: ${pkg.name}`);
+        }
+        if (pkg.description) {
+            summary.push(`Description: ${pkg.description}`);
+        }
+        if (pkg.workspaces) {
+            const workspaces = Array.isArray(pkg.workspaces)
+                ? pkg.workspaces
+                : pkg.workspaces.packages || [];
+            summary.push(`Workspaces: ${workspaces.join(', ')}`);
+        }
+        if (pkg.scripts) {
+            const scripts = Object.keys(pkg.scripts).slice(0, 10);
+            summary.push(`Key scripts: ${scripts.join(', ')}`);
+        }
+        return summary.join('\n');
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Extracts summary from Markdown content
+ *
+ * @param content - Raw Markdown content
+ * @returns Summarized content with headings and paragraphs
+ */
+function extractMarkdownSummary(content) {
+    const lines = content.split('\n');
+    const summary = [];
+    let currentLength = 0;
+    for (const line of lines) {
+        if (currentLength + line.length > MAX_SUMMARY_LENGTH) {
+            break;
+        }
+        // Include headings
+        if (line.startsWith('#')) {
+            summary.push(line);
+            currentLength += line.length + 1;
+            continue;
+        }
+        // Include non-empty lines until we hit length limit
+        if (line.trim()) {
+            summary.push(line);
+            currentLength += line.length + 1;
+        }
+        else if (summary.length > 0) {
+            // Preserve paragraph breaks
+            summary.push('');
+        }
+    }
+    return summary.join('\n').trim();
+}
+/**
+ * Extracts summary content from a source file
+ *
+ * @param sourcePath - Path of the source file
+ * @param content - Raw file content
+ * @returns Summarized content for memory node
+ */
+function extractSummary(sourcePath, content) {
+    // For package.json, extract key fields
+    if (sourcePath === 'package.json') {
+        const pkgSummary = extractPackageJsonSummary(content);
+        if (pkgSummary) {
+            return pkgSummary;
+        }
+    }
+    // For YAML files, preserve structure
+    if (sourcePath.endsWith('.yaml') || sourcePath.endsWith('.yml')) {
+        return content.slice(0, MAX_SUMMARY_LENGTH);
+    }
+    // For Markdown files, extract headings and first paragraphs
+    if (sourcePath.endsWith('.md')) {
+        return extractMarkdownSummary(content);
+    }
+    // Default: truncate
+    return content.slice(0, MAX_SUMMARY_LENGTH);
+}
+/**
+ * Finds existing index nodes for a source
+ *
+ * @param nodes - All memory nodes
+ * @param sourcePath - Source path to find
+ * @returns Existing node or undefined
+ */
+function findExistingNode(nodes, sourcePath) {
+    return nodes.find((n) => {
+        const metadata = n.metadata;
+        return metadata?.source_path === sourcePath;
+    });
+}
+/**
+ * Creates a memory node for a source
+ *
+ * @param source - Source definition
+ * @param content - File content
+ * @param contentHash - Content hash
+ * @param indexedAt - Timestamp
+ * @param existingNodeId - ID of existing node being replaced (if update)
+ * @returns Memory node
+ */
+function createSourceNode(source, content, contentHash, indexedAt, existingNodeId) {
+    const node = {
+        id: generateMemId(`${source.path}-${indexedAt}`),
+        type: 'summary',
+        lifecycle: 'project',
+        content: extractSummary(source.path, content),
+        created_at: indexedAt,
+        tags: source.tags,
+        metadata: {
+            source_path: source.path,
+            source_hash: contentHash,
+            indexed_at: indexedAt,
+            description: source.description,
+        },
+    };
+    if (existingNodeId) {
+        node.updated_at = indexedAt;
+        node.metadata.replaces = existingNodeId;
+    }
+    return node;
+}
+/**
+ * Processes a single source file and creates/updates memory node
+ *
+ * @param source - Source definition
+ * @param content - File content
+ * @param ctx - Processing context
+ * @returns Result indicating what action was taken
+ */
+async function processSource(source, content, ctx) {
+    const contentHash = computeHash(content);
+    const existingNode = findExistingNode(ctx.existingNodes, source.path);
+    // Check if content unchanged
+    if (existingNode) {
+        const existingHash = existingNode.metadata?.source_hash;
+        if (existingHash === contentHash) {
+            return 'skipped';
+        }
+    }
+    // Write node (unless dry-run)
+    if (!ctx.dryRun) {
+        const node = createSourceNode(source, content, contentHash, ctx.indexedAt, existingNode?.id);
+        await appendNode(ctx.memoryDir, node);
+    }
+    return existingNode ? 'updated' : 'created';
+}
+/**
+ * Loads existing memory nodes from memory directory
+ *
+ * @param memoryDir - Memory directory path
+ * @returns Array of existing memory nodes
+ */
+async function loadExistingNodes(memoryDir) {
+    try {
+        const memory = await loadMemory(memoryDir);
+        return memory.nodes;
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Indexes project sources and creates/updates memory nodes
+ *
+ * @param baseDir - Project base directory
+ * @param options - Indexing options
+ * @returns Index result
+ *
+ * @example
+ * const result = await indexProject('/path/to/project');
+ * console.log(`Created: ${result.nodesCreated}, Updated: ${result.nodesUpdated}`);
+ *
+ * @example
+ * // Dry-run mode
+ * const result = await indexProject('/path/to/project', { dryRun: true });
+ * console.log('Would create:', result.nodesCreated);
+ */
+export async function indexProject(baseDir, options = {}) {
+    const { dryRun = false, additionalSources = [] } = options;
+    const result = {
+        success: true,
+        nodesCreated: 0,
+        nodesUpdated: 0,
+        nodesSkipped: 0,
+        sourcesScanned: [],
+        sourcesMissing: [],
+    };
+    const sources = [...DEFAULT_SOURCES, ...additionalSources];
+    const memoryDir = path.join(baseDir, LUMENFLOW_MEMORY_PATHS.MEMORY_DIR);
+    const indexedAt = new Date().toISOString();
+    // Ensure memory directory exists (unless dry-run)
+    if (!dryRun) {
+        await fs.mkdir(memoryDir, { recursive: true });
+    }
+    const existingNodes = await loadExistingNodes(memoryDir);
+    const ctx = { memoryDir, indexedAt, dryRun, existingNodes };
+    // Process each source
+    for (const source of sources) {
+        const sourcePath = path.join(baseDir, source.path);
+        // Try to read file content
+        let content;
+        try {
+            content = await fs.readFile(sourcePath, 'utf-8');
+        }
+        catch {
+            result.sourcesMissing.push(source.path);
+            continue;
+        }
+        result.sourcesScanned.push(source.path);
+        // Process the source
+        const action = await processSource(source, content, ctx);
+        if (action === 'created') {
+            result.nodesCreated++;
+        }
+        else if (action === 'updated') {
+            result.nodesUpdated++;
+        }
+        else {
+            result.nodesSkipped++;
+        }
+    }
+    return result;
+}
+/**
+ * Gets the default sources that will be scanned
+ *
+ * @returns Array of source definitions
+ */
+export function getDefaultSources() {
+    return [...DEFAULT_SOURCES];
+}

package/dist/mem-init-core.js

@@ -4,9 +4,9 @@
  * Core logic for initializing memory layer in a repository.
  * Creates .lumenflow/memory/ directory with empty memory.jsonl and config.yaml.
  *
- * @see {@link tools/__tests__/mem-init.test.mjs} - Tests
- * @see {@link tools/lib/memory-store.mjs} - Memory store operations
- * @see {@link tools/lib/memory-schema.mjs} - Memory schema definitions
+ * @see {@link packages/@lumenflow/cli/src/__tests__/mem-init.test.ts} - Tests
+ * @see {@link packages/@lumenflow/cli/src/lib/memory-store.ts} - Memory store operations
+ * @see {@link packages/@lumenflow/cli/src/lib/memory-schema.ts} - Memory schema definitions
  */
 import fs from 'node:fs/promises';
 import path from 'node:path';