@lumenflow/memory 1.0.0

package/dist/mem-signal-core.js

@@ -0,0 +1,249 @@
+/**
+ * Memory Signal Core Logic (WU-1473)
+ *
+ * Core logic for creating coordination signals between parallel agents.
+ * Enables sub-100ms agent communication via JSONL append operations.
+ *
+ * Features:
+ * - Append-only writes for sub-100ms performance
+ * - WU-scoped signals for focused coordination
+ * - 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
+ */
+import { randomBytes } from 'node:crypto';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+/**
+ * Signal file name constant
+ */
+export const SIGNAL_FILE_NAME = 'signals.jsonl';
+/**
+ * Memory directory path within project
+ */
+const MEMORY_DIR = '.beacon/memory';
+/**
+ * WU ID validation pattern (from memory-schema.mjs)
+ */
+const WU_ID_PATTERN = /^WU-\d+$/;
+/**
+ * Signal ID prefix
+ */
+const SIGNAL_ID_PREFIX = 'sig-';
+/**
+ * Number of hex characters in signal ID suffix
+ */
+const SIGNAL_ID_LENGTH = 8;
+/**
+ * Error messages for validation
+ */
+const ERROR_MESSAGES = {
+    MESSAGE_REQUIRED: 'message is required and cannot be empty',
+    INVALID_WU_ID: 'Invalid WU ID format. Expected WU-XXX (e.g., WU-1473)',
+};
+/**
+ * Generates a unique signal ID using random bytes.
+ *
+ * Format: sig-[8 hex chars]
+ * Uses crypto.randomBytes for uniqueness (not content-based like mem-id).
+ *
+ * @returns {string} Signal ID in format sig-XXXXXXXX
+ */
+function generateSignalId() {
+    const bytes = randomBytes(4);
+    const hex = bytes.toString('hex').slice(0, SIGNAL_ID_LENGTH);
+    return `${SIGNAL_ID_PREFIX}${hex}`;
+}
+/**
+ * Gets the memory directory path for a project.
+ *
+ * @param baseDir - Project base directory
+ * @returns Full path to memory directory
+ */
+function getMemoryDir(baseDir) {
+    return path.join(baseDir, MEMORY_DIR);
+}
+/**
+ * Gets the signals file path for a project.
+ *
+ * @param baseDir - Project base directory
+ * @returns Full path to signals.jsonl
+ */
+function getSignalsPath(baseDir) {
+    return path.join(getMemoryDir(baseDir), SIGNAL_FILE_NAME);
+}
+/**
+ * Validates a WU ID format.
+ *
+ * @param wuId - WU ID to validate
+ * @returns True if valid
+ */
+function isValidWuId(wuId) {
+    return WU_ID_PATTERN.test(wuId);
+}
+/**
+ * Creates a coordination signal between parallel agents.
+ *
+ * Signals are appended to signals.jsonl using append-only writes
+ * for sub-100ms performance. Signals can be scoped to a specific
+ * WU or targeted at a specific lane.
+ *
+ * @param {string} baseDir - Project base directory
+ * @param {CreateSignalOptions} options - Signal options
+ * @returns {Promise<CreateSignalResult>} Result with created signal
+ * @throws {Error} If message is missing or WU ID is invalid
+ *
+ * @example
+ * const result = await createSignal('/project', {
+ *   message: 'Starting feature implementation',
+ *   wuId: 'WU-1473',
+ *   lane: 'Operations: Tooling',
+ * });
+ */
+export async function createSignal(baseDir, options) {
+    const { message, wuId, lane } = options;
+    // Validate message is provided and non-empty
+    if (!message || typeof message !== 'string' || message.trim().length === 0) {
+        throw new Error(ERROR_MESSAGES.MESSAGE_REQUIRED);
+    }
+    // Validate WU ID format if provided
+    if (wuId !== undefined && !isValidWuId(wuId)) {
+        throw new Error(ERROR_MESSAGES.INVALID_WU_ID);
+    }
+    // Build signal object
+    const signal = {
+        id: generateSignalId(),
+        message: message.trim(),
+        created_at: new Date().toISOString(),
+        read: false,
+    };
+    // Add optional fields
+    if (wuId) {
+        signal.wu_id = wuId;
+    }
+    if (lane) {
+        signal.lane = lane;
+    }
+    // Ensure memory directory exists
+    const memoryDir = getMemoryDir(baseDir);
+    // eslint-disable-next-line security/detect-non-literal-fs-filename -- CLI tool creates known directory
+    await fs.mkdir(memoryDir, { recursive: true });
+    // Append signal to file (append-only for speed)
+    const signalsPath = getSignalsPath(baseDir);
+    const line = `${JSON.stringify(signal)}\n`;
+    // eslint-disable-next-line security/detect-non-literal-fs-filename -- CLI tool writes signals file
+    await fs.appendFile(signalsPath, line, 'utf-8');
+    return {
+        success: true,
+        signal,
+    };
+}
+/**
+ * Loads signals from the signals file with optional filtering.
+ *
+ * Signals are returned in chronological order (oldest first).
+ * Supports filtering by WU ID, lane, and read status.
+ *
+ * @param {string} baseDir - Project base directory
+ * @param {LoadSignalsOptions} [options={}] - Filter options
+ * @returns {Promise<Signal[]>} Array of signals matching filters
+ *
+ * @example
+ * // Load all signals
+ * const all = await loadSignals('/project');
+ *
+ * // Load unread signals for a specific WU
+ * const unread = await loadSignals('/project', {
+ *   wuId: 'WU-1473',
+ *   unreadOnly: true,
+ * });
+ */
+export async function loadSignals(baseDir, options = {}) {
+    const { wuId, lane, unreadOnly, since } = options;
+    const signalsPath = getSignalsPath(baseDir);
+    // Read file content
+    let content;
+    try {
+        // eslint-disable-next-line security/detect-non-literal-fs-filename -- CLI tool reads signals file
+        content = await fs.readFile(signalsPath, { encoding: 'utf-8' });
+    }
+    catch (err) {
+        const error = err;
+        if (error.code === 'ENOENT') {
+            // File doesn't exist - return empty array
+            return [];
+        }
+        throw error;
+    }
+    // Parse JSONL content
+    const lines = content.split('\n').filter((line) => line.trim());
+    const signals = lines.map((line) => JSON.parse(line));
+    // Apply filters
+    let filtered = signals;
+    if (wuId) {
+        filtered = filtered.filter((sig) => sig.wu_id === wuId);
+    }
+    if (lane) {
+        filtered = filtered.filter((sig) => sig.lane === lane);
+    }
+    if (unreadOnly) {
+        filtered = filtered.filter((sig) => sig.read === false);
+    }
+    if (since) {
+        const sinceTime = since instanceof Date ? since : new Date(since);
+        filtered = filtered.filter((sig) => new Date(sig.created_at) > sinceTime);
+    }
+    // Return in chronological order (file order is already chronological due to append-only)
+    return filtered;
+}
+/**
+ * Marks signals as read by updating the signals file.
+ *
+ * Reads the entire file, updates the read status for matching IDs,
+ * and writes back. Only signals that were previously unread are counted.
+ *
+ * @param baseDir - Project base directory
+ * @param signalIds - Array of signal IDs to mark as read
+ * @returns Result with count of signals marked
+ *
+ * @example
+ * const result = await markSignalsAsRead('/project', ['sig-abc12345', 'sig-def67890']);
+ * console.log(result.markedCount); // 2
+ */
+export async function markSignalsAsRead(baseDir, signalIds) {
+    const signalsPath = getSignalsPath(baseDir);
+    const idSet = new Set(signalIds);
+    let markedCount = 0;
+    // Read file content
+    let content;
+    try {
+        // eslint-disable-next-line security/detect-non-literal-fs-filename -- CLI tool reads signals file
+        content = await fs.readFile(signalsPath, { encoding: 'utf-8' });
+    }
+    catch (err) {
+        const error = err;
+        if (error.code === 'ENOENT') {
+            // No signals file - nothing to mark
+            return { markedCount: 0 };
+        }
+        throw error;
+    }
+    // Parse JSONL content
+    const lines = content.split('\n').filter((line) => line.trim());
+    const updatedLines = lines.map((line) => {
+        const signal = JSON.parse(line);
+        if (idSet.has(signal.id) && signal.read === false) {
+            signal.read = true;
+            markedCount++;
+        }
+        return JSON.stringify(signal);
+    });
+    // Write back updated content
+    // eslint-disable-next-line security/detect-non-literal-fs-filename -- CLI tool writes signals file
+    await fs.writeFile(signalsPath, `${updatedLines.join('\n')}\n`, {
+        encoding: 'utf-8',
+    });
+    return { markedCount };
+}

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

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

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

@@ -0,0 +1,76 @@
+/**
+ * Memory Start Core (WU-1466)
+ *
+ * Core logic for creating session nodes linked to WUs.
+ * Called by wu:claim enhancement for context restoration after /clear.
+ *
+ * Features:
+ * - Creates session nodes with WU reference
+ * - Stores agent type, start timestamp, context tier
+ * - 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
+ */
+/**
+ * Session start options
+ */
+export interface StartSessionOptions {
+    /** Work Unit ID (required) */
+    wuId: string;
+    /** Agent type (defaults to 'unknown') */
+    agentType?: string;
+    /** Context tier (defaults to 'full') */
+    contextTier?: string;
+}
+/**
+ * Session node structure
+ */
+interface SessionNode {
+    id: string;
+    type: 'session';
+    lifecycle: 'wu';
+    content: string;
+    created_at: string;
+    wu_id: string;
+    session_id: string;
+    metadata: {
+        agentType: string;
+        contextTier: string;
+    };
+}
+/**
+ * Session start result
+ */
+export interface StartSessionResult {
+    /** Whether the operation succeeded */
+    success: boolean;
+    /** Created session node */
+    session: SessionNode;
+}
+/**
+ * Creates a new session node linked to a WU.
+ *
+ * Creates a session-type memory node with:
+ * - Unique ID (mem-XXXX format)
+ * - Link to WU via wu_id field
+ * - Agent type and context tier in metadata
+ * - UUID session_id for unique identification
+ *
+ * @param baseDir - Base directory containing .beacon/memory/
+ * @param options - Session options
+ * @returns Result with created session node
+ * @throws If wuId is missing or invalid
+ *
+ * @example
+ * const result = await startSession('/path/to/project', {
+ *   wuId: 'WU-1234',
+ *   agentType: 'general-purpose',
+ *   contextTier: 'core',
+ * });
+ * console.log(result.session.id); // 'mem-a1b2'
+ */
+export declare function startSession(baseDir: string, options: StartSessionOptions): Promise<StartSessionResult>;
+export {};

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

@@ -0,0 +1 @@
+{"version":3,"file":"mem-start-core.d.ts","sourceRoot":"","sources":["../src/mem-start-core.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AA2EH;;;;;;;GAOG;AAEH;;;;;;GAMG;AAEH;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,YAAY,CAAC,OAAO,KAAA,EAAE,OAAO,KAAA;;;;;;;;;;;;;;;GA+ClD"}

package/dist/mem-start-core.js

@@ -0,0 +1,133 @@
+/**
+ * Memory Start Core (WU-1466)
+ *
+ * Core logic for creating session nodes linked to WUs.
+ * Called by wu:claim enhancement for context restoration after /clear.
+ *
+ * Features:
+ * - Creates session nodes with WU reference
+ * - Stores agent type, start timestamp, context tier
+ * - 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
+ */
+import { randomUUID } from 'node:crypto';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { generateMemId } from './mem-id.js';
+import { appendNode } from './memory-store.js';
+import { MEMORY_PATTERNS } from './memory-schema.js';
+/**
+ * Memory directory path relative to base directory
+ */
+const MEMORY_DIR = '.beacon/memory';
+/**
+ * Default values for session metadata
+ */
+const DEFAULTS = {
+    AGENT_TYPE: 'unknown',
+    CONTEXT_TIER: 'full',
+};
+/**
+ * Error messages for validation
+ */
+const ERROR_MESSAGES = {
+    WU_ID_REQUIRED: 'wuId is required',
+    WU_ID_INVALID: 'Invalid WU ID format. Expected pattern: WU-XXX (e.g., WU-123)',
+};
+/**
+ * Validates WU ID format
+ *
+ * @param wuId - WU ID to validate
+ * @returns True if valid
+ */
+function isValidWuId(wuId) {
+    return MEMORY_PATTERNS.WU_ID.test(wuId);
+}
+/**
+ * Ensures the memory directory exists
+ *
+ * @param baseDir - Base directory
+ * @returns Memory directory path
+ */
+async function ensureMemoryDir(baseDir) {
+    const memoryDir = path.join(baseDir, MEMORY_DIR);
+    // eslint-disable-next-line security/detect-non-literal-fs-filename -- Known directory path
+    await fs.mkdir(memoryDir, { recursive: true });
+    return memoryDir;
+}
+/**
+ * Generates content description for session node
+ *
+ * @param wuId - WU ID
+ * @param agentType - Agent type
+ * @param contextTier - Context tier
+ * @returns Content description
+ */
+function generateSessionContent(wuId, agentType, contextTier) {
+    return `Session started for ${wuId}. Agent: ${agentType}, Context: ${contextTier}`;
+}
+/**
+ * Creates a new session node linked to a WU.
+ *
+ * Creates a session-type memory node with:
+ * - Unique ID (mem-XXXX format)
+ * - Link to WU via wu_id field
+ * - Agent type and context tier in metadata
+ * - UUID session_id for unique identification
+ *
+ * @param baseDir - Base directory containing .beacon/memory/
+ * @param options - Session options
+ * @returns Result with created session node
+ * @throws If wuId is missing or invalid
+ *
+ * @example
+ * const result = await startSession('/path/to/project', {
+ *   wuId: 'WU-1234',
+ *   agentType: 'general-purpose',
+ *   contextTier: 'core',
+ * });
+ * console.log(result.session.id); // 'mem-a1b2'
+ */
+export async function startSession(baseDir, options) {
+    const { wuId, agentType = DEFAULTS.AGENT_TYPE, contextTier = DEFAULTS.CONTEXT_TIER } = options;
+    // Validate required fields
+    if (!wuId) {
+        throw new Error(ERROR_MESSAGES.WU_ID_REQUIRED);
+    }
+    // Validate WU ID format
+    if (!isValidWuId(wuId)) {
+        throw new Error(ERROR_MESSAGES.WU_ID_INVALID);
+    }
+    // Ensure memory directory exists
+    const memoryDir = await ensureMemoryDir(baseDir);
+    // Generate session node
+    const timestamp = new Date().toISOString();
+    const sessionId = randomUUID();
+    const content = generateSessionContent(wuId, agentType, contextTier);
+    // Generate deterministic ID from content + timestamp for uniqueness
+    const idContent = `${content}-${timestamp}-${sessionId}`;
+    const id = generateMemId(idContent);
+    const sessionNode = {
+        id,
+        type: 'session',
+        lifecycle: 'wu',
+        content,
+        created_at: timestamp,
+        wu_id: wuId,
+        session_id: sessionId,
+        metadata: {
+            agentType,
+            contextTier,
+        },
+    };
+    // Persist to memory store
+    await appendNode(memoryDir, sessionNode);
+    return {
+        success: true,
+        session: sessionNode,
+    };
+}

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

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

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

@@ -0,0 +1,105 @@
+/**
+ * Memory Summarize Core (WU-1471)
+ *
+ * Rollup older memory nodes into summary nodes for compaction.
+ * Implements forgetting as first-class feature.
+ *
+ * Features:
+ * - Aggregate checkpoint/note/discovery nodes into summaries
+ * - Mark originals for cleanup after summary creation
+ * - 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
+ */
+import { type MemoryNode } from './memory-schema.js';
+/**
+ * Summarize options
+ */
+export interface SummarizeOptions {
+    /** WU ID to summarize (e.g., 'WU-1234') */
+    wuId: string;
+    /** If true, preview without modifications */
+    dryRun?: boolean;
+}
+/**
+ * Summary node structure
+ */
+interface SummaryNode {
+    id: string;
+    type: 'summary';
+    lifecycle: 'project';
+    content: string;
+    created_at: string;
+    wu_id: string;
+    metadata: {
+        source_nodes: string[];
+        source_count: number;
+        summarized_at: string;
+    };
+}
+/**
+ * Summarize result
+ */
+export interface SummarizeResult {
+    /** Whether summarization succeeded */
+    success: boolean;
+    /** Created summary node */
+    summary: SummaryNode;
+    /** Node IDs marked for cleanup */
+    markedForCleanup: string[];
+    /** True if in dry-run mode */
+    dryRun?: boolean;
+    /** Ratio of source nodes to summary */
+    compactionRatio: number;
+}
+/**
+ * Filter nodes that can be summarized for a given WU.
+ *
+ * Excludes:
+ * - Nodes from different WUs
+ * - Ephemeral lifecycle nodes (already transient)
+ * - Already-summarized nodes (have summarized_into metadata)
+ * - Summary nodes themselves
+ *
+ * @param nodes - All memory nodes
+ * @param wuId - WU ID to filter by
+ * @returns Summarizable nodes
+ */
+export declare function filterSummarizableNodes(nodes: MemoryNode[], wuId: string): MemoryNode[];
+/**
+ * Calculate compaction ratio (source nodes / summary nodes).
+ *
+ * @param sourceCount - Number of source nodes
+ * @param summaryCount - Number of summary nodes created
+ * @returns Compaction ratio (0 if invalid input)
+ */
+export declare function getCompactionRatio(sourceCount: number, summaryCount: number): number;
+/**
+ * Summarize memory nodes for a closed WU.
+ *
+ * Aggregates checkpoint, note, and discovery nodes into a single
+ * summary node. Original nodes are marked for cleanup (unless
+ * they have project lifecycle).
+ *
+ * @param baseDir - Base directory containing .beacon/memory/
+ * @param options - Summarization options
+ * @returns Result with summary and cleanup info
+ * @throws If no summarizable nodes found for WU
+ *
+ * @example
+ * // Summarize nodes for a completed WU
+ * const result = await summarizeWu(baseDir, { wuId: 'WU-1234' });
+ * console.log(`Created summary ${result.summary.id}`);
+ * console.log(`Compaction ratio: ${result.compactionRatio}:1`);
+ *
+ * @example
+ * // Preview without modifications
+ * const preview = await summarizeWu(baseDir, {
+ *   wuId: 'WU-1234',
+ *   dryRun: true,
+ * });
+ */
+export declare function summarizeWu(baseDir: string, options: SummarizeOptions): Promise<SummarizeResult>;
+export {};

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

@@ -0,0 +1 @@
+{"version":3,"file":"mem-summarize-core.d.ts","sourceRoot":"","sources":["../src/mem-summarize-core.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAuBH;;GAEG;AAEH;;;;GAIG;AAEH;;;;;;;GAOG;AAEH;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,KAAA,EAAE,IAAI,KAAA,OAyBlD;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,KAAA,EAAE,YAAY,KAAA,UAK3D;AAqID;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAsB,WAAW,CAAC,OAAO,KAAA,EAAE,OAAO,KAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDjD"}