@lumenflow/memory 2.11.0 → 2.12.0

package/dist/mem-id.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Memory ID Generator (WU-1465)
+ *
+ * Hash-based collision-free ID generation for memory nodes.
+ * 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
+ */
+/**
+ * Regex patterns for memory ID validation
+ */
+export declare const MEM_ID_PATTERNS: {
+    /**
+     * Base memory ID format: mem-[a-f0-9]{4}
+     * Only lowercase hex characters (0-9, a-f)
+     */
+    BASE_ID: RegExp;
+    /**
+     * Hierarchical memory ID format: mem-[a-f0-9]{4}(.[1-9][0-9]*)*
+     * Base ID followed by optional dot-separated positive integers
+     * Examples: mem-a1b2, mem-a1b2.1, mem-a1b2.1.2
+     */
+    HIERARCHICAL_ID: RegExp;
+};
+/**
+ * Generates a deterministic memory ID from content.
+ *
+ * Uses SHA-256 hash of the content, taking the first 4 hex characters.
+ * Same content always produces the same ID (deterministic).
+ *
+ * @param content - Content to hash for ID generation
+ * @returns Memory ID in format mem-[a-f0-9]{4}
+ *
+ * @example
+ * const id = generateMemId('discovered file at src/utils.mjs');
+ * // Returns something like 'mem-a3f2'
+ */
+export declare function generateMemId(content: string): string;
+/**
+ * Generates a hierarchical memory ID by appending an index to a parent ID.
+ *
+ * Used for sub-task decomposition where a parent task (mem-a1b2) has
+ * child tasks (mem-a1b2.1, mem-a1b2.2) and grandchildren (mem-a1b2.1.1).
+ *
+ * @param parentId - Parent memory ID (base or hierarchical)
+ * @param index - Positive integer index (1-based)
+ * @returns Hierarchical memory ID
+ * @throws If parentId is invalid or index is not positive
+ *
+ * @example
+ * generateHierarchicalId('mem-a1b2', 1);     // 'mem-a1b2.1'
+ * generateHierarchicalId('mem-a1b2.1', 2);  // 'mem-a1b2.1.2'
+ */
+export declare function generateHierarchicalId(parentId: string, index: number): string;
+/**
+ * Validation result from validateMemId
+ */
+export interface MemIdValidationResult {
+    /** Whether the ID is valid */
+    valid: boolean;
+    /** Type of ID if valid */
+    type?: 'base' | 'hierarchical';
+    /** Base ID portion if hierarchical */
+    baseId?: string;
+    /** Hierarchical indices (empty for base IDs) */
+    indices: number[];
+    /** Error message if invalid */
+    error?: string;
+}
+/**
+ * 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.
+ *
+ * @param id - Memory ID to validate
+ * @returns Validation result with parsed components
+ *
+ * @example
+ * validateMemId('mem-a1b2');
+ * // { valid: true, type: 'base', baseId: 'mem-a1b2', indices: [] }
+ *
+ * validateMemId('mem-a1b2.1.2');
+ * // { valid: true, type: 'hierarchical', baseId: 'mem-a1b2', indices: [1, 2] }
+ *
+ * validateMemId('invalid');
+ * // { valid: false, error: 'Invalid memory ID format', indices: [] }
+ */
+export declare function validateMemId(id: string): MemIdValidationResult;

package/dist/mem-id.js

@@ -134,3 +134,4 @@ export function validateMemId(id) {
         indices,
     };
 }
+//# sourceMappingURL=mem-id.js.map

package/dist/mem-id.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mem-id.js","sourceRoot":"","sources":["../src/mem-id.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC;;GAEG;AACH,MAAM,aAAa,GAAG,MAAM,CAAC;AAE7B;;GAEG;AACH,MAAM,iBAAiB,GAAG,CAAC,CAAC;AAE5B;;GAEG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B;;;OAGG;IACH,OAAO,EAAE,mBAAmB;IAE5B;;;;OAIG;IACH,eAAe,EAAE,mCAAmC;CACrD,CAAC;AAEF;;GAEG;AACH,MAAM,cAAc,GAAG;IACrB,UAAU,EAAE,0BAA0B;IACtC,eAAe,EAAE,+BAA+B;IAChD,aAAa,EAAE,kCAAkC;CAClD,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,aAAa,CAAC,OAAe;IAC3C,MAAM,IAAI,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAEzE,wCAAwC;IACxC,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,iBAAiB,CAAC,CAAC;IAEhD,OAAO,GAAG,aAAa,GAAG,MAAM,EAAE,CAAC;AACrC,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,sBAAsB,CAAC,QAAgB,EAAE,KAAa;IACpE,qBAAqB;IACrB,IAAI,CAAC,eAAe,CAAC,eAAe,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;QACpD,MAAM,IAAI,KAAK,CAAC,GAAG,cAAc,CAAC,eAAe,KAAK,QAAQ,EAAE,CAAC,CAAC;IACpE,CAAC;IAED,qCAAqC;IACrC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;QAC1C,MAAM,IAAI,KAAK,CAAC,GAAG,cAAc,CAAC,aAAa,KAAK,KAAK,EAAE,CAAC,CAAC;IAC/D,CAAC;IAED,OAAO,GAAG,QAAQ,IAAI,KAAK,EAAE,CAAC;AAChC,CAAC;AAkBD;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,aAAa,CAAC,EAAU;IACtC,+BAA+B;IAC/B,IAAI,CAAC,eAAe,CAAC,eAAe,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC;QAC9C,OAAO;YACL,KAAK,EAAE,KAAK;YACZ,KAAK,EAAE,cAAc,CAAC,UAAU;YAChC,OAAO,EAAE,EAAE;SACZ,CAAC;IACJ,CAAC;IAED,qDAAqD;IACrD,IAAI,eAAe,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC;QACrC,OAAO;YACL,KAAK,EAAE,IAAI;YACX,IAAI,EAAE,MAAM;YACZ,MAAM,EAAE,EAAE;YACV,OAAO,EAAE,EAAE;SACZ,CAAC;IACJ,CAAC;IAED,4CAA4C;IAC5C,MAAM,KAAK,GAAG,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAC5B,MAAM,MAAM,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;IACxB,MAAM,OAAO,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,QAAQ,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC;IAEjE,OAAO;QACL,KAAK,EAAE,IAAI;QACX,IAAI,EAAE,cAAc;QACpB,MAAM;QACN,OAAO;KACR,CAAC;AACJ,CAAC"}

package/dist/mem-index-core.js

@@ -305,3 +305,4 @@ export async function indexProject(baseDir, options = {}) {
 export function getDefaultSources() {
     return [...DEFAULT_SOURCES];
 }
+//# sourceMappingURL=mem-index-core.js.map

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

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

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

@@ -0,0 +1,93 @@
+/**
+ * Memory Init Core (WU-1464)
+ *
+ * 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
+ */
+/**
+ * Memory layer file/directory paths
+ *
+ * Uses LUMENFLOW_MEMORY_PATHS from local paths.ts to avoid circular dependency.
+ */
+export declare const MEMORY_PATHS: {
+    /** Memory directory relative to project root */
+    MEMORY_DIR: ".lumenflow/memory";
+    /** Memory JSONL file name */
+    MEMORY_FILE: string;
+    /** Config YAML file name */
+    CONFIG_FILE: string;
+};
+/**
+ * Default memory layer configuration
+ *
+ * Retention values are in seconds:
+ * - ephemeral: 0 (immediate discard)
+ * - session: 3600 (1 hour)
+ * - wu: 604800 (7 days)
+ * - project: -1 (never expire)
+ */
+export declare const DEFAULT_CONFIG: {
+    /** Config schema version */
+    version: number;
+    /** Retention policy for each lifecycle */
+    retention: {
+        /** Ephemeral nodes are discarded immediately after use */
+        ephemeral: number;
+        /** Session nodes expire after 1 hour */
+        session: number;
+        /** WU nodes expire after 7 days */
+        wu: number;
+        /** Project nodes never expire (-1 = infinite) */
+        project: number;
+    };
+};
+/**
+ * Memory initialization paths
+ */
+interface InitMemoryPaths {
+    memoryDir: string;
+    memoryJsonl: string;
+    configYaml: string;
+}
+/**
+ * Memory initialization created flags
+ */
+interface InitMemoryCreated {
+    directory: boolean;
+    memoryJsonl: boolean;
+    configYaml: boolean;
+}
+/**
+ * Memory initialization result
+ */
+export interface InitMemoryResult {
+    success: boolean;
+    alreadyInitialized: boolean;
+    paths: InitMemoryPaths;
+    created: InitMemoryCreated;
+}
+/**
+ * Initialize memory layer in a repository.
+ *
+ * Creates:
+ * - .lumenflow/memory/ directory
+ * - memory.jsonl (empty if not exists)
+ * - config.yaml (default settings if not exists)
+ *
+ * Idempotent: Running multiple times does not corrupt existing data.
+ *
+ * @param baseDir - Base directory of the repository
+ * @returns Result object with success, paths, and created flags
+ *
+ * @example
+ * const result = await initMemory(process.cwd());
+ * if (result.success) {
+ *   console.log('Memory initialized at:', result.paths.memoryDir);
+ * }
+ */
+export declare function initMemory(baseDir: string): Promise<InitMemoryResult>;
+export {};

package/dist/mem-init-core.js

@@ -139,3 +139,4 @@ export async function initMemory(baseDir) {
     result.success = true;
     return result;
 }
+//# sourceMappingURL=mem-init-core.js.map

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

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

package/dist/mem-profile-core.js

@@ -182,3 +182,4 @@ export async function generateProfile(baseDir, options = {}) {
         stats,
     };
 }
+//# sourceMappingURL=mem-profile-core.js.map

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

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

package/dist/mem-promote-core.js

@@ -231,3 +231,4 @@ export async function promoteFromWu(baseDir, options) {
         dryRun,
     };
 }
+//# sourceMappingURL=mem-promote-core.js.map

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

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

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

@@ -0,0 +1,56 @@
+/**
+ * Memory Ready Core (WU-1468)
+ *
+ * Deterministic ready-work query for "what next?" oracle.
+ * Returns open nodes with no blockers, ordered by priority then createdAt.
+ *
+ * Ordering algorithm:
+ * 1. Priority ASC (P0 first, then P1, P2, P3; nodes without priority last)
+ * 2. CreatedAt ASC (oldest first for same priority)
+ * 3. ID ASC (stable sort for identical priority and timestamp)
+ *
+ * A node is "ready" if:
+ * - Linked to the specified WU
+ * - Not blocked by another node (no `blocks` relationship pointing to it)
+ * - No `metadata.blocked_by` array set
+ * - 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
+ */
+import { type MemoryNode } from './memory-schema.js';
+/**
+ * Query options for ready nodes
+ */
+export interface QueryOptions {
+    /** WU ID to query (required) */
+    wuId: string;
+    /** Filter by node type (optional) */
+    type?: string;
+}
+/**
+ * Query ready nodes for a WU.
+ *
+ * Returns unblocked, open nodes linked to the WU in deterministic order:
+ * 1. Priority (P0 first, then P1, P2, P3; nodes without priority last)
+ * 2. CreatedAt (oldest first for same priority)
+ * 3. ID (alphabetical for stable sort)
+ *
+ * @param baseDir - Base directory containing .lumenflow/memory
+ * @param options - Query options
+ * @returns Deterministically ordered ready nodes
+ * @throws If WU ID format is invalid or file contains malformed JSON
+ *
+ * @example
+ * const ready = await queryReadyNodes('/path/to/project', { wuId: 'WU-1234' });
+ * console.log(`${ready.length} nodes ready for processing`);
+ *
+ * @example
+ * // Filter by type
+ * const discoveries = await queryReadyNodes('/path/to/project', {
+ *   wuId: 'WU-1234',
+ *   type: 'discovery',
+ * });
+ */
+export declare function queryReadyNodes(baseDir: string, options: QueryOptions): Promise<MemoryNode[]>;

package/dist/mem-ready-core.js

@@ -231,3 +231,4 @@ export async function queryReadyNodes(baseDir, options) {
     // Sort deterministically
     return readyNodes.sort(compareNodes);
 }
+//# sourceMappingURL=mem-ready-core.js.map

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

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

package/dist/mem-recover-core.js

@@ -256,3 +256,4 @@ export async function generateRecoveryContext(options) {
         truncated,
     };
 }
+//# sourceMappingURL=mem-recover-core.js.map

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

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

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

@@ -0,0 +1,132 @@
+/**
+ * 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
+ */
+/**
+ * Signal file name constant
+ */
+export declare const SIGNAL_FILE_NAME = "signals.jsonl";
+/**
+ * Signal structure
+ */
+export interface Signal {
+    /** Unique signal identifier (sig-XXXXXXXX) */
+    id: string;
+    /** Signal content/message */
+    message: string;
+    /** ISO 8601 timestamp */
+    created_at: string;
+    /** Whether signal has been read */
+    read: boolean;
+    /** Optional WU ID scope */
+    wu_id?: string;
+    /** Optional target lane */
+    lane?: string;
+}
+/**
+ * Result of creating a signal
+ */
+export interface CreateSignalResult {
+    /** Whether signal was created successfully */
+    success: boolean;
+    /** The created signal object */
+    signal: Signal;
+}
+/**
+ * Options for creating a signal
+ */
+export interface CreateSignalOptions {
+    /** Signal message content (required) */
+    message: string;
+    /** WU ID to scope signal to */
+    wuId?: string;
+    /** Lane to target signal to */
+    lane?: string;
+}
+/**
+ * Options for loading signals
+ */
+export interface LoadSignalsOptions {
+    /** Filter by WU ID */
+    wuId?: string;
+    /** Filter by lane */
+    lane?: string;
+    /** Only return unread signals */
+    unreadOnly?: boolean;
+    /** Only return signals created after this time */
+    since?: Date | string;
+}
+/**
+ * Result of marking signals as read
+ */
+export interface MarkAsReadResult {
+    /** Number of signals marked as read */
+    markedCount: number;
+}
+/**
+ * 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 declare function createSignal(baseDir: string, options: CreateSignalOptions): Promise<CreateSignalResult>;
+/**
+ * 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 declare function loadSignals(baseDir: string, options?: LoadSignalsOptions): Promise<Signal[]>;
+/**
+ * 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 declare function markSignalsAsRead(baseDir: string, signalIds: string[]): Promise<MarkAsReadResult>;

package/dist/mem-signal-core.js

@@ -21,6 +21,14 @@ import { LUMENFLOW_MEMORY_PATHS } from './paths.js';
  * Signal file name constant
  */
 export const SIGNAL_FILE_NAME = 'signals.jsonl';
+/**
+ * Signal receipts file name constant (WU-1472)
+ *
+ * Append-only file that stores read receipts for signals.
+ * This avoids rewriting signals.jsonl when marking signals as read,
+ * enabling concurrent-safe consumption by multiple agents.
+ */
+export const SIGNAL_RECEIPTS_FILE_NAME = 'signal-receipts.jsonl';
 /**
  * WU ID validation pattern (from memory-schema.ts)
  */
@@ -71,6 +79,46 @@ function getMemoryDir(baseDir) {
 function getSignalsPath(baseDir) {
     return path.join(getMemoryDir(baseDir), SIGNAL_FILE_NAME);
 }
+/**
+ * Gets the signal receipts file path for a project (WU-1472).
+ *
+ * @param baseDir - Project base directory
+ * @returns Full path to signal-receipts.jsonl
+ */
+function getReceiptsPath(baseDir) {
+    return path.join(getMemoryDir(baseDir), SIGNAL_RECEIPTS_FILE_NAME);
+}
+/**
+ * Loads read receipts from the receipts file (WU-1472).
+ *
+ * Returns a Set of signal IDs that have been marked as read via receipts.
+ * If the file does not exist, returns an empty Set.
+ *
+ * @param baseDir - Project base directory
+ * @returns Set of signal IDs with read receipts
+ */
+async function loadReceiptIds(baseDir) {
+    const receiptsPath = getReceiptsPath(baseDir);
+    let content;
+    try {
+        // eslint-disable-next-line security/detect-non-literal-fs-filename -- CLI tool reads known path
+        content = await fs.readFile(receiptsPath, { encoding: 'utf-8' });
+    }
+    catch (err) {
+        const error = err;
+        if (error.code === 'ENOENT') {
+            return new Set();
+        }
+        throw error;
+    }
+    const lines = content.split('\n').filter((line) => line.trim());
+    const ids = new Set();
+    for (const line of lines) {
+        const receipt = JSON.parse(line);
+        ids.add(receipt.signal_id);
+    }
+    return ids;
+}
 /**
  * Validates a WU ID format.
  *
@@ -177,6 +225,13 @@ export async function loadSignals(baseDir, options = {}) {
     // Parse JSONL content
     const lines = content.split('\n').filter((line) => line.trim());
     const signals = lines.map((line) => JSON.parse(line));
+    // Merge receipt-based read state (WU-1472)
+    const receiptIds = await loadReceiptIds(baseDir);
+    for (const signal of signals) {
+        if (!signal.read && receiptIds.has(signal.id)) {
+            signal.read = true;
+        }
+    }
     // Apply filters
     let filtered = signals;
     if (wuId) {
@@ -196,10 +251,14 @@ export async function loadSignals(baseDir, options = {}) {
     return filtered;
 }
 /**
- * Marks signals as read by updating the signals file.
+ * Marks signals as read by appending receipts to signal-receipts.jsonl (WU-1472).
  *
- * Reads the entire file, updates the read status for matching IDs,
- * and writes back. Only signals that were previously unread are counted.
+ * Instead of rewriting signals.jsonl (which causes lost updates under
+ * concurrency), this appends receipt records to a separate append-only file.
+ * The loadSignals function merges these receipts to derive effective read state.
+ *
+ * Only signals that are currently unread (no inline read:true AND no existing
+ * receipt) are counted in markedCount.
  *
  * @param baseDir - Project base directory
  * @param signalIds - Array of signal IDs to mark as read
@@ -212,12 +271,11 @@ export async function loadSignals(baseDir, options = {}) {
 export async function markSignalsAsRead(baseDir, signalIds) {
     const signalsPath = getSignalsPath(baseDir);
     const idSet = new Set(signalIds);
-    let markedCount = 0;
-    // Read file content
-    let content;
+    // Read signals file to determine which IDs exist and their inline read state
+    let signalContent;
     try {
         // eslint-disable-next-line security/detect-non-literal-fs-filename -- CLI tool reads signals file
-        content = await fs.readFile(signalsPath, { encoding: 'utf-8' });
+        signalContent = await fs.readFile(signalsPath, { encoding: 'utf-8' });
     }
     catch (err) {
         const error = err;
@@ -227,20 +285,38 @@ export async function markSignalsAsRead(baseDir, signalIds) {
         }
         throw error;
     }
-    // Parse JSONL content
-    const lines = content.split('\n').filter((line) => line.trim());
-    const updatedLines = lines.map((line) => {
+    // Build map of existing signal read states
+    const lines = signalContent.split('\n').filter((line) => line.trim());
+    const inlineReadIds = new Set();
+    const existingIds = new Set();
+    for (const line of lines) {
         const signal = JSON.parse(line);
-        if (idSet.has(signal.id) && signal.read === false) {
-            signal.read = true;
-            markedCount++;
+        existingIds.add(signal.id);
+        if (signal.read) {
+            inlineReadIds.add(signal.id);
         }
-        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 };
+    }
+    // Load existing receipts to check for duplicates
+    const existingReceiptIds = await loadReceiptIds(baseDir);
+    // Determine which signals need new receipts
+    const now = new Date().toISOString();
+    const newReceipts = [];
+    for (const id of idSet) {
+        // Only create receipt if: signal exists, not already inline read, no existing receipt
+        if (existingIds.has(id) && !inlineReadIds.has(id) && !existingReceiptIds.has(id)) {
+            newReceipts.push({ signal_id: id, read_at: now });
+        }
+    }
+    // Append receipts (append-only for concurrent safety)
+    if (newReceipts.length > 0) {
+        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 });
+        const receiptsPath = getReceiptsPath(baseDir);
+        const receiptLines = newReceipts.map((r) => JSON.stringify(r)).join('\n') + '\n';
+        // eslint-disable-next-line security/detect-non-literal-fs-filename -- CLI tool writes receipts file
+        await fs.appendFile(receiptsPath, receiptLines, 'utf-8');
+    }
+    return { markedCount: newReceipts.length };
 }
+//# sourceMappingURL=mem-signal-core.js.map