@lumenflow/memory 2.2.2 → 2.3.2

package/README.md

@@ -98,6 +98,264 @@ await sendSignal('/path/to/project', {
 });
 ```
 
+### Context Injection (WU-1234)
+
+Generate deterministic context blocks for wu:spawn prompts:
+
+```typescript
+import { generateContext } from '@lumenflow/memory/context';
+
+// Generate context for a WU
+const result = await generateContext('/path/to/project', {
+  wuId: 'WU-123',
+  maxSize: 4096, // default: 4KB
+});
+
+console.log(result.contextBlock);
+// <!-- mem:context for WU-123 -->
+//
+// ## Project Profile
+// - [mem-abc1] (2025-01-15): Project architecture decision...
+//
+// ## WU Context
+// - [mem-def2] (2025-01-20): Checkpoint: completed port definitions...
+```
+
+The context block includes:
+
+- **Project Profile**: lifecycle=project memories (architectural knowledge)
+- **Summaries**: summary-type nodes for the WU
+- **WU Context**: checkpoints and notes linked to the WU
+- **Discoveries**: discovered information for the WU
+
+Selection is deterministic (filter by lifecycle, wu_id, recency). Max size is configurable (default 4KB). Returns empty block if no memories match.
+
+#### Decay-Based Ranking (WU-1238)
+
+Enable decay-based ranking to prioritize memories by relevance rather than recency:
+
+```typescript
+const result = await generateContext('/path/to/project', {
+  wuId: 'WU-123',
+  sortByDecay: true, // Sort by decay score instead of recency
+  trackAccess: true, // Track access for included nodes
+});
+
+console.log(result.stats.accessTracked); // Number of nodes with access tracked
+```
+
+Decay scoring considers:
+
+- **Recency**: Exponential decay based on age (half-life: 30 days default)
+- **Access frequency**: Boost for frequently accessed nodes
+- **Priority**: P0=2x, P1=1.5x, P2=1x, P3=0.5x multiplier
+
+### Access Tracking and Decay Scoring (WU-1238)
+
+Track memory access patterns and compute decay scores for relevance management:
+
+```typescript
+import {
+  recordAccess,
+  recordAccessBatch,
+  getAccessStats,
+  computeDecayScore,
+  DEFAULT_HALF_LIFE_MS,
+  IMPORTANCE_BY_PRIORITY,
+} from '@lumenflow/memory';
+
+// Record access for a single node
+const updated = await recordAccess('/path/to/project', 'mem-abc1');
+console.log(updated.metadata.access.count); // Incremented
+console.log(updated.metadata.access.last_accessed_at); // ISO timestamp
+
+// Record access for multiple nodes (efficient batch operation)
+const updatedNodes = await recordAccessBatch('/path/to/project', ['mem-abc1', 'mem-def2']);
+
+// Get access statistics
+const stats = await getAccessStats('/path/to/project', 'mem-abc1');
+console.log(stats?.count, stats?.last_accessed_at);
+
+// Compute decay score for a node
+const score = computeDecayScore(node, {
+  now: Date.now(),
+  halfLifeMs: DEFAULT_HALF_LIFE_MS, // 30 days
+});
+```
+
+Decay scoring formula:
+
+```
+decayScore = recencyScore * (1 + accessScore) * importanceScore
+
+Where:
+- recencyScore = exp(-age / halfLife)
+- accessScore = log1p(access_count) / 10
+- importanceScore = { P0: 2, P1: 1.5, P2: 1, P3: 0.5 }
+```
+
+### Archival by Decay (WU-1238)
+
+Archive stale nodes with low decay scores:
+
+```typescript
+import { archiveByDecay, isArchived, DEFAULT_DECAY_THRESHOLD } from '@lumenflow/memory';
+
+// Archive nodes below threshold (default: 0.1)
+const result = await archiveByDecay('/path/to/project', {
+  threshold: 0.1,
+  dryRun: true, // Preview without modifying
+});
+
+console.log(result.archivedIds); // Nodes that would be archived
+console.log(result.retainedIds); // Nodes above threshold
+console.log(result.skippedIds); // Already archived or protected nodes
+
+// Execute archival
+await archiveByDecay('/path/to/project', { threshold: 0.1 });
+
+// Check if a node is archived
+if (isArchived(node)) {
+  console.log('Node has metadata.status = archived');
+}
+```
+
+Archival rules:
+
+- Nodes below threshold get `metadata.status = 'archived'`
+- Project lifecycle nodes are never archived (protected)
+- Already archived nodes are skipped
+- Nothing is deleted (append-only pattern)
+
+### Memory Cleanup with Decay (WU-1238)
+
+The `cleanupMemory` function now supports decay-based archival:
+
+```typescript
+import { cleanupMemory } from '@lumenflow/memory';
+
+// Run cleanup with decay archival
+const result = await cleanupMemory('/path/to/project', {
+  decay: true,
+  decayThreshold: 0.1, // Archive nodes below this score
+  halfLifeMs: 30 * 24 * 60 * 60 * 1000, // 30 days
+  dryRun: true, // Preview first
+});
+
+console.log(result.breakdown.decayArchived); // Number of nodes archived by decay
+console.log(result.decayResult); // Detailed archival result
+```
+
+### Including Archived Nodes (WU-1238)
+
+By default, queries exclude archived nodes. Use `includeArchived` to include them:
+
+```typescript
+import { loadMemory, queryReady, queryByWu } from '@lumenflow/memory';
+
+// Load including archived nodes
+const allMemory = await loadMemory('/path/to/project', { includeArchived: true });
+
+// Query including archived nodes
+const allNodes = await queryReady('/path/to/project', 'WU-123', { includeArchived: true });
+const allWuNodes = await queryByWu('/path/to/project', 'WU-123', { includeArchived: true });
+```
+
+### Knowledge Promotion (WU-1237)
+
+Promote session/WU learnings to project-level knowledge:
+
+```typescript
+import { promoteNode, promoteFromWu, ALLOWED_PROMOTION_TAGS } from '@lumenflow/memory';
+
+// Promote a single node to project-level
+const result = await promoteNode('/path/to/project', {
+  nodeId: 'mem-abc1',
+  tag: 'pattern', // decision|convention|pattern|pitfall|interface|invariant|faq
+});
+console.log(`Promoted to ${result.promotedNode.id}`);
+
+// Promote all summaries from a WU
+const wuResult = await promoteFromWu('/path/to/project', {
+  wuId: 'WU-123',
+  tag: 'decision',
+});
+console.log(`Promoted ${wuResult.promotedNodes.length} summaries`);
+
+// Dry-run mode (preview without writing)
+const dryResult = await promoteNode('/path/to/project', {
+  nodeId: 'mem-abc1',
+  tag: 'pattern',
+  dryRun: true,
+});
+```
+
+Promotion creates:
+
+- A new node with `lifecycle=project`
+- A `discovered_from` relationship to the source node
+- The specified taxonomy tag on the promoted node
+
+Allowed tags: `decision`, `convention`, `pattern`, `pitfall`, `interface`, `invariant`, `faq`.
+
+### Project Profile (WU-1237)
+
+Generate aggregated project knowledge for context injection:
+
+```typescript
+import { generateProfile, DEFAULT_PROFILE_LIMIT } from '@lumenflow/memory';
+
+// Get top 20 project memories (default)
+const result = await generateProfile('/path/to/project');
+console.log(result.profileBlock);
+// ## Project Profile
+// - [mem-abc1] (2025-01-15): Architecture decision...
+// - [mem-def2] (2025-01-20): Naming convention...
+
+// Filter by tag
+const decisions = await generateProfile('/path/to/project', {
+  tag: 'decision',
+  limit: 10,
+});
+
+// Access statistics
+console.log(result.stats.totalProjectNodes);
+console.log(result.stats.byTag); // { decision: 5, pattern: 3, ... }
+```
+
+The profile output is formatted for integration with `mem:context`.
+
+### Project Indexing (WU-1235)
+
+Index project conventions for agent context awareness:
+
+```typescript
+import { indexProject, getDefaultSources } from '@lumenflow/memory/index';
+
+// Index project conventions
+const result = await indexProject('/path/to/project');
+console.log(`Created: ${result.nodesCreated}, Updated: ${result.nodesUpdated}`);
+
+// Dry-run mode (no writes)
+const dryResult = await indexProject('/path/to/project', { dryRun: true });
+console.log('Would index:', dryResult.sourcesScanned);
+
+// Get default sources that will be scanned
+const sources = getDefaultSources();
+// ['README.md', 'LUMENFLOW.md', 'package.json', ...]
+```
+
+Default sources scanned:
+
+- **README.md**: Project overview (tagged: `index:architecture`)
+- **LUMENFLOW.md**: Workflow conventions (tagged: `index:conventions`)
+- **package.json**: Monorepo structure (tagged: `index:architecture`)
+- **.lumenflow.config.yaml**: Workflow config (tagged: `index:commands`, `index:conventions`)
+- **.lumenflow/constraints.md**: Project invariants (tagged: `index:invariants`)
+
+Each node includes provenance metadata: `source_path`, `source_hash`, `indexed_at`.
+Idempotent: re-running updates or skips existing nodes based on content hash.
+
 ## Subpath Exports
 
 ```typescript
@@ -114,6 +372,8 @@ import { cleanupExpired } from '@lumenflow/memory/cleanup';
 import { createMemoryNode } from '@lumenflow/memory/create';
 import { summarizeWu } from '@lumenflow/memory/summarize';
 import { triageBugs } from '@lumenflow/memory/triage';
+import { generateContext } from '@lumenflow/memory/context';
+import { indexProject } from '@lumenflow/memory/index';
 import { MemoryNodeSchema } from '@lumenflow/memory/schema';
 import { loadMemory, appendNode } from '@lumenflow/memory/store';
 ```
@@ -129,6 +389,75 @@ import { loadMemory, appendNode } from '@lumenflow/memory/store';
 | `queryReady(baseDir, wuId)` | Get nodes for WU in priority order         |
 | `queryByWu(baseDir, wuId)`  | Get all nodes for WU in file order         |
 
+### Context Injection
+
+| Function                         | Description                                   |
+| -------------------------------- | --------------------------------------------- |
+| `generateContext(baseDir, opts)` | Generate formatted context block for wu:spawn |
+
+### Project Indexing
+
+| Function                      | Description                           |
+| ----------------------------- | ------------------------------------- |
+| `indexProject(baseDir, opts)` | Scan sources and create summary nodes |
+| `getDefaultSources()`         | Get list of default sources to scan   |
+
+### Knowledge Promotion
+
+| Function                       | Description                              |
+| ------------------------------ | ---------------------------------------- |
+| `promoteNode(baseDir, opts)`   | Promote single node to project lifecycle |
+| `promoteFromWu(baseDir, opts)` | Promote all summaries from a WU          |
+| `ALLOWED_PROMOTION_TAGS`       | Array of valid taxonomy tags             |
+
+### Project Profile
+
+| Function                         | Description                                   |
+| -------------------------------- | --------------------------------------------- |
+| `generateProfile(baseDir, opts)` | Generate aggregated project knowledge profile |
+| `DEFAULT_PROFILE_LIMIT`          | Default limit for profile generation (20)     |
+
+Options for `indexProject`:
+
+- `dryRun` (optional): If true, show what would be indexed without writing (default: false)
+- `additionalSources` (optional): Additional source definitions to scan
+
+Options for `generateContext`:
+
+- `wuId` (required): WU ID to generate context for
+- `maxSize` (optional): Maximum context size in bytes (default: 4096)
+- `sortByDecay` (optional): Sort by decay score instead of recency (default: false)
+- `trackAccess` (optional): Track access for included nodes (default: false)
+- `halfLifeMs` (optional): Half-life for decay calculation (default: 30 days)
+- `now` (optional): Current timestamp for decay calculation (default: Date.now())
+
+### Access Tracking (WU-1238)
+
+| Function                              | Description                                  |
+| ------------------------------------- | -------------------------------------------- |
+| `recordAccess(baseDir, nodeId)`       | Record access for a single node              |
+| `recordAccessBatch(baseDir, nodeIds)` | Record access for multiple nodes (efficient) |
+| `getAccessStats(baseDir, nodeId)`     | Get access statistics for a node             |
+
+### Decay Scoring (WU-1238)
+
+| Function                         | Description                                      |
+| -------------------------------- | ------------------------------------------------ |
+| `computeDecayScore(node, opts)`  | Compute overall decay score for a node           |
+| `computeRecencyScore(node, ...)` | Compute recency component (exponential decay)    |
+| `computeAccessScore(node)`       | Compute access component (logarithmic boost)     |
+| `computeImportanceScore(node)`   | Compute importance component (priority-based)    |
+| `DEFAULT_HALF_LIFE_MS`           | Default half-life: 30 days in milliseconds       |
+| `IMPORTANCE_BY_PRIORITY`         | Priority multipliers: P0=2, P1=1.5, P2=1, P3=0.5 |
+
+### Archival (WU-1238)
+
+| Function                        | Description                                    |
+| ------------------------------- | ---------------------------------------------- |
+| `archiveByDecay(baseDir, opts)` | Archive nodes below decay threshold            |
+| `isArchived(node)`              | Check if node has metadata.status = 'archived' |
+| `DEFAULT_DECAY_THRESHOLD`       | Default threshold: 0.1                         |
+
 ### Memory Schema
 
 | Export                       | Description                               |
@@ -171,6 +500,9 @@ interface IndexedMemory {
 - **Priority ordering**: Deterministic query results (P0 > P1 > P2 > P3)
 - **Schema validation**: Zod-based runtime validation
 - **Modern**: Node 22+, ESM-only, TypeScript
+- **Decay scoring** (WU-1238): Relevance management based on recency, access frequency, and priority
+- **Access tracking** (WU-1238): Track node access patterns for decay scoring
+- **Archival** (WU-1238): Archive stale nodes without deletion (append-only pattern)
 
 ## Documentation
 

package/dist/decay/access-tracking.js

@@ -0,0 +1,171 @@
+/**
+ * Access Tracking (WU-1238)
+ *
+ * Track access patterns for memory nodes to inform decay scoring.
+ * Access is recorded when nodes are returned by mem:search or mem:context.
+ *
+ * Tracks:
+ * - metadata.access.count: Number of times node was accessed
+ * - metadata.access.last_accessed_at: ISO timestamp of last access
+ * - metadata.decay.score: Computed decay score (updated on access)
+ *
+ * @see {@link packages/@lumenflow/memory/__tests__/access-tracking.test.ts} - Tests
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { loadMemory, MEMORY_FILE_NAME } from '../memory-store.js';
+import { computeDecayScore, DEFAULT_HALF_LIFE_MS } from './scoring.js';
+/**
+ * Write nodes back to memory file.
+ * Rewrites the entire file to update existing nodes.
+ *
+ * @param baseDir - Base directory containing memory.jsonl
+ * @param nodes - All nodes to write
+ */
+async function writeMemoryFile(baseDir, nodes) {
+    const filePath = path.join(baseDir, MEMORY_FILE_NAME);
+    const content = nodes.map((n) => JSON.stringify(n)).join('\n') + (nodes.length > 0 ? '\n' : '');
+    await fs.writeFile(filePath, content, { encoding: 'utf-8' });
+}
+/**
+ * Update a node's access metadata.
+ *
+ * @param node - Node to update
+ * @param now - Current timestamp
+ * @param halfLifeMs - Half-life for decay scoring
+ * @returns Updated node with new access metadata
+ */
+function updateNodeAccess(node, now = Date.now(), halfLifeMs = DEFAULT_HALF_LIFE_MS) {
+    const timestamp = new Date(now).toISOString();
+    // Get existing access metadata
+    const existingAccess = node.metadata?.access;
+    const currentCount = existingAccess?.count ?? 0;
+    // Create updated access metadata
+    const newAccess = {
+        count: currentCount + 1,
+        last_accessed_at: timestamp,
+    };
+    // Compute decay score
+    const updatedNodeForScoring = {
+        ...node,
+        metadata: {
+            ...node.metadata,
+            access: newAccess,
+        },
+    };
+    const decayScore = computeDecayScore(updatedNodeForScoring, { now, halfLifeMs });
+    const newDecay = {
+        score: decayScore,
+        computed_at: timestamp,
+    };
+    // Return updated node
+    return {
+        ...node,
+        metadata: {
+            ...node.metadata,
+            access: newAccess,
+            decay: newDecay,
+        },
+    };
+}
+/**
+ * Record access for a single memory node.
+ *
+ * Increments access count and updates last_accessed_at timestamp.
+ * Also recomputes the decay score.
+ *
+ * @param baseDir - Base directory containing memory.jsonl
+ * @param nodeId - ID of the node to record access for
+ * @param options - Optional configuration
+ * @returns Updated node with new access metadata
+ * @throws If node is not found
+ *
+ * @example
+ * const updatedNode = await recordAccess(baseDir, 'mem-abc1');
+ * console.log(updatedNode.metadata.access.count); // Incremented
+ */
+export async function recordAccess(baseDir, nodeId, options = {}) {
+    const { now = Date.now(), halfLifeMs = DEFAULT_HALF_LIFE_MS } = options;
+    // Load all nodes
+    const memory = await loadMemory(baseDir);
+    // Find the target node
+    const targetNode = memory.byId.get(nodeId);
+    if (!targetNode) {
+        throw new Error(`Node not found: ${nodeId}`);
+    }
+    // Update the node
+    const updatedNode = updateNodeAccess(targetNode, now, halfLifeMs);
+    // Replace the node in the nodes array
+    const updatedNodes = memory.nodes.map((n) => (n.id === nodeId ? updatedNode : n));
+    // Write back to file
+    await writeMemoryFile(baseDir, updatedNodes);
+    return updatedNode;
+}
+/**
+ * Record access for multiple memory nodes in a batch.
+ *
+ * More efficient than calling recordAccess individually because
+ * it only reads and writes the file once.
+ *
+ * @param baseDir - Base directory containing memory.jsonl
+ * @param nodeIds - IDs of nodes to record access for
+ * @param options - Optional configuration
+ * @returns Array of updated nodes (skips non-existent nodes)
+ *
+ * @example
+ * const updated = await recordAccessBatch(baseDir, ['mem-abc1', 'mem-def2']);
+ * console.log(`Updated ${updated.length} nodes`);
+ */
+export async function recordAccessBatch(baseDir, nodeIds, options = {}) {
+    const { now = Date.now(), halfLifeMs = DEFAULT_HALF_LIFE_MS } = options;
+    // Load all nodes
+    const memory = await loadMemory(baseDir);
+    // Track which nodes were updated
+    const updatedNodes = [];
+    const nodeIdSet = new Set(nodeIds);
+    // Update matching nodes
+    const allNodes = memory.nodes.map((node) => {
+        if (nodeIdSet.has(node.id)) {
+            const updated = updateNodeAccess(node, now, halfLifeMs);
+            updatedNodes.push(updated);
+            return updated;
+        }
+        return node;
+    });
+    // Write back to file if any nodes were updated
+    if (updatedNodes.length > 0) {
+        await writeMemoryFile(baseDir, allNodes);
+    }
+    return updatedNodes;
+}
+/**
+ * Get access statistics for a memory node.
+ *
+ * @param baseDir - Base directory containing memory.jsonl
+ * @param nodeId - ID of the node to get stats for
+ * @returns Access stats or null if node has no access data or doesn't exist
+ *
+ * @example
+ * const stats = await getAccessStats(baseDir, 'mem-abc1');
+ * if (stats) {
+ *   console.log(`Accessed ${stats.count} times`);
+ * }
+ */
+export async function getAccessStats(baseDir, nodeId) {
+    // Load all nodes
+    const memory = await loadMemory(baseDir);
+    // Find the target node
+    const node = memory.byId.get(nodeId);
+    if (!node) {
+        return null;
+    }
+    // Get access metadata
+    const access = node.metadata?.access;
+    if (!access || typeof access.count !== 'number') {
+        return null;
+    }
+    return {
+        count: access.count,
+        last_accessed_at: access.last_accessed_at,
+    };
+}

package/dist/decay/archival.js

@@ -0,0 +1,164 @@
+/**
+ * Archival (WU-1238)
+ *
+ * Archive memory nodes below decay threshold.
+ * Uses append-only pattern - nothing is deleted, nodes are marked with metadata.status = 'archived'.
+ *
+ * Archival rules:
+ * - Nodes below threshold get metadata.status = 'archived'
+ * - Project lifecycle nodes are never archived (protected)
+ * - Already archived nodes are skipped
+ * - Archived nodes excluded from default queries
+ *
+ * @see {@link packages/@lumenflow/memory/__tests__/archival.test.ts} - Tests
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { loadMemory, MEMORY_FILE_NAME } from '../memory-store.js';
+import { computeDecayScore, DEFAULT_HALF_LIFE_MS } from './scoring.js';
+/**
+ * Default decay threshold below which nodes are archived
+ */
+export const DEFAULT_DECAY_THRESHOLD = 0.1;
+/**
+ * Status value for archived nodes
+ */
+const ARCHIVED_STATUS = 'archived';
+/**
+ * Protected lifecycle that is never archived
+ */
+const PROTECTED_LIFECYCLE = 'project';
+/**
+ * Check if a node is already archived.
+ *
+ * @param node - Memory node to check
+ * @returns True if node has metadata.status = 'archived'
+ *
+ * @example
+ * if (isArchived(node)) {
+ *   console.log('Node is already archived');
+ * }
+ */
+export function isArchived(node) {
+    return node.metadata?.status === ARCHIVED_STATUS;
+}
+/**
+ * Check if a node is protected from archival.
+ *
+ * Protected nodes:
+ * - Project lifecycle nodes (architectural knowledge)
+ *
+ * @param node - Memory node to check
+ * @returns True if node should never be archived
+ */
+function isProtected(node) {
+    return node.lifecycle === PROTECTED_LIFECYCLE;
+}
+/**
+ * Mark a node as archived.
+ *
+ * @param node - Node to archive
+ * @param score - The decay score that triggered archival
+ * @param threshold - The threshold used
+ * @param now - Current timestamp
+ * @returns Node with archived status
+ */
+function markAsArchived(node, score, threshold, now) {
+    const timestamp = new Date(now).toISOString();
+    return {
+        ...node,
+        metadata: {
+            ...node.metadata,
+            status: ARCHIVED_STATUS,
+            archived_at: timestamp,
+            decay: {
+                ...node.metadata?.decay,
+                score,
+                reason: `Score ${score.toFixed(4)} below threshold ${threshold}`,
+                computed_at: timestamp,
+            },
+        },
+    };
+}
+/**
+ * Write nodes back to memory file.
+ *
+ * @param baseDir - Base directory containing memory.jsonl
+ * @param nodes - All nodes to write
+ */
+async function writeMemoryFile(baseDir, nodes) {
+    const filePath = path.join(baseDir, MEMORY_FILE_NAME);
+    const content = nodes.map((n) => JSON.stringify(n)).join('\n') + (nodes.length > 0 ? '\n' : '');
+    await fs.writeFile(filePath, content, { encoding: 'utf-8' });
+}
+/**
+ * Archive nodes with decay score below threshold.
+ *
+ * This function:
+ * 1. Computes decay score for each node
+ * 2. Archives nodes below the threshold
+ * 3. Skips already archived and protected nodes
+ * 4. Does NOT delete any nodes (append-only pattern)
+ *
+ * Archived nodes get:
+ * - metadata.status = 'archived'
+ * - metadata.archived_at = ISO timestamp
+ * - metadata.decay.score = computed score
+ * - metadata.decay.reason = explanation string
+ *
+ * @param baseDir - Base directory containing memory.jsonl
+ * @param options - Archive options
+ * @returns Result with lists of archived, retained, and skipped node IDs
+ *
+ * @example
+ * // Archive nodes with decay score below 0.1
+ * const result = await archiveByDecay(baseDir, { threshold: 0.1 });
+ * console.log(`Archived ${result.archivedIds.length} nodes`);
+ *
+ * @example
+ * // Dry-run to preview what would be archived
+ * const preview = await archiveByDecay(baseDir, { threshold: 0.1, dryRun: true });
+ * console.log(`Would archive: ${preview.archivedIds.join(', ')}`);
+ */
+export async function archiveByDecay(baseDir, options = {}) {
+    const { threshold = DEFAULT_DECAY_THRESHOLD, now = Date.now(), halfLifeMs = DEFAULT_HALF_LIFE_MS, dryRun = false, } = options;
+    // Load all nodes including archived ones (need to see everything for processing)
+    const memory = await loadMemory(baseDir, { includeArchived: true });
+    // Track results
+    const archivedIds = [];
+    const retainedIds = [];
+    const skippedIds = [];
+    // Process nodes and build updated list
+    const updatedNodes = memory.nodes.map((node) => {
+        // Skip already archived nodes
+        if (isArchived(node)) {
+            skippedIds.push(node.id);
+            return node;
+        }
+        // Skip protected nodes (project lifecycle)
+        if (isProtected(node)) {
+            skippedIds.push(node.id);
+            return node;
+        }
+        // Compute decay score
+        const score = computeDecayScore(node, { now, halfLifeMs });
+        // Check threshold
+        if (score < threshold) {
+            archivedIds.push(node.id);
+            return markAsArchived(node, score, threshold, now);
+        }
+        retainedIds.push(node.id);
+        return node;
+    });
+    // Write back to file if not dry-run and nodes were archived
+    if (!dryRun && archivedIds.length > 0) {
+        await writeMemoryFile(baseDir, updatedNodes);
+    }
+    return {
+        archivedIds,
+        retainedIds,
+        skippedIds,
+        totalProcessed: memory.nodes.length,
+        ...(dryRun ? { dryRun: true } : {}),
+    };
+}