@lumenflow/memory 1.0.0

package/LICENSE

@@ -0,0 +1,190 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to the Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2026 HellmAI
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,181 @@
+# @lumenflow/memory
+
+Memory layer for LumenFlow workflow framework - session tracking, context recovery, and agent coordination.
+
+## Installation
+
+```bash
+npm install @lumenflow/memory
+```
+
+## Overview
+
+This package provides a persistent memory layer for AI agents working within the LumenFlow framework. It enables:
+
+- **Session tracking**: Track agent sessions across context window boundaries
+- **Context recovery**: Resume work after `/clear` or session handoff
+- **Agent coordination**: Signal between parallel agents via inbox/outbox
+- **Progress checkpoints**: Save state at milestones for recovery
+
+## Usage
+
+### Memory Store
+
+The memory store uses JSONL format for git-friendly, append-only persistence.
+
+```typescript
+import { loadMemory, appendNode, queryReady, queryByWu } from '@lumenflow/memory';
+
+// Load all memory nodes
+const memory = await loadMemory('/path/to/project');
+const node = memory.byId.get('mem-abc1');
+const wuNodes = memory.byWu.get('WU-123') ?? [];
+
+// Append a new node
+await appendNode('/path/to/project', {
+  id: 'mem-xyz9',
+  type: 'checkpoint',
+  lifecycle: 'wu',
+  content: 'Completed port definitions',
+  created_at: new Date().toISOString(),
+  wu_id: 'WU-123',
+});
+
+// Query nodes ready for processing (priority-ordered)
+const ready = await queryReady('/path/to/project', 'WU-123');
+
+// Query all nodes for a WU (file order)
+const nodes = await queryByWu('/path/to/project', 'WU-123');
+```
+
+### Memory Schema
+
+Validate memory nodes against the schema:
+
+```typescript
+import {
+  validateMemoryNode,
+  MemoryNodeSchema,
+  MEMORY_NODE_TYPES,
+  MEMORY_LIFECYCLES,
+} from '@lumenflow/memory';
+
+// Node types: session, discovery, checkpoint, note, summary
+// Lifecycles: ephemeral, session, wu, project
+
+const result = validateMemoryNode(nodeData);
+if (!result.success) {
+  console.error(result.error.issues);
+}
+```
+
+### Checkpoints
+
+Create progress checkpoints for context recovery:
+
+```typescript
+import { createCheckpoint } from '@lumenflow/memory/checkpoint';
+
+await createCheckpoint('/path/to/project', {
+  wuId: 'WU-123',
+  content: 'Completed acceptance criteria 1-3',
+  metadata: { milestone: 'ports-complete' },
+});
+```
+
+### Signals
+
+Send and receive coordination signals between agents:
+
+```typescript
+import { sendSignal } from '@lumenflow/memory/signal';
+
+// Signal completion to other agents
+await sendSignal('/path/to/project', {
+  wuId: 'WU-123',
+  type: 'completion',
+  content: 'WU-123 done, WU-124 unblocked',
+});
+```
+
+## Subpath Exports
+
+```typescript
+// Main entry (all exports)
+import { loadMemory, MemoryNodeSchema } from '@lumenflow/memory';
+
+// Specific modules
+import { createCheckpoint } from '@lumenflow/memory/checkpoint';
+import { initMemory } from '@lumenflow/memory/init';
+import { startSession } from '@lumenflow/memory/start';
+import { queryReadyNodes } from '@lumenflow/memory/ready';
+import { sendSignal } from '@lumenflow/memory/signal';
+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 { MemoryNodeSchema } from '@lumenflow/memory/schema';
+import { loadMemory, appendNode } from '@lumenflow/memory/store';
+```
+
+## API Reference
+
+### Memory Store
+
+| Function                    | Description                                |
+| --------------------------- | ------------------------------------------ |
+| `loadMemory(baseDir)`       | Load and index all memory nodes from JSONL |
+| `appendNode(baseDir, node)` | Append a validated node to the memory file |
+| `queryReady(baseDir, wuId)` | Get nodes for WU in priority order         |
+| `queryByWu(baseDir, wuId)`  | Get all nodes for WU in file order         |
+
+### Memory Schema
+
+| Export                       | Description                               |
+| ---------------------------- | ----------------------------------------- |
+| `MemoryNodeSchema`           | Zod schema for memory nodes               |
+| `RelationshipSchema`         | Zod schema for node relationships         |
+| `validateMemoryNode(data)`   | Validate data against node schema         |
+| `validateRelationship(data)` | Validate data against relationship schema |
+| `MEMORY_NODE_TYPES`          | Valid node types array                    |
+| `MEMORY_LIFECYCLES`          | Valid lifecycle values array              |
+| `RELATIONSHIP_TYPES`         | Valid relationship types array            |
+
+### Types
+
+```typescript
+interface MemoryNode {
+  id: string; // mem-[a-z0-9]{4}
+  type: 'session' | 'discovery' | 'checkpoint' | 'note' | 'summary';
+  lifecycle: 'ephemeral' | 'session' | 'wu' | 'project';
+  content: string;
+  created_at: string; // ISO 8601
+  updated_at?: string;
+  wu_id?: string; // WU-XXX
+  session_id?: string; // UUID
+  metadata?: Record<string, unknown>;
+  tags?: string[];
+}
+
+interface IndexedMemory {
+  nodes: MemoryNode[];
+  byId: Map<string, MemoryNode>;
+  byWu: Map<string, MemoryNode[]>;
+}
+```
+
+## Features
+
+- **Append-only writes**: No full file rewrites, git-merge friendly
+- **Indexed lookups**: O(1) access by ID and WU
+- **Priority ordering**: Deterministic query results (P0 > P1 > P2 > P3)
+- **Schema validation**: Zod-based runtime validation
+- **Modern**: Node 22+, ESM-only, TypeScript
+
+## Documentation
+
+For complete documentation, see the [LumenFlow documentation](https://github.com/hellmai/os).
+
+## License
+
+Apache-2.0

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @lumenflow/memory - Session tracking and context recovery
+ * @module @lumenflow/memory
+ */
+export * from './mem-checkpoint-core.js';
+export * from './mem-cleanup-core.js';
+export * from './mem-create-core.js';
+export * from './mem-id.js';
+export * from './mem-init-core.js';
+export * from './mem-ready-core.js';
+export * from './mem-signal-core.js';
+export * from './mem-start-core.js';
+export { filterSummarizableNodes, summarizeWu, getCompactionRatio as getSummarizeCompactionRatio, } from './mem-summarize-core.js';
+export * from './mem-triage-core.js';
+export * from './memory-schema.js';
+export * from './memory-store.js';

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,cAAc,0BAA0B,CAAC;AACzC,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,aAAa,CAAC;AAC5B,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC;AACpC,cAAc,yBAAyB,CAAC;AACxC,cAAc,sBAAsB,CAAC;AACrC,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC"}

package/dist/index.js

@@ -0,0 +1,16 @@
+/**
+ * @lumenflow/memory - Session tracking and context recovery
+ * @module @lumenflow/memory
+ */
+export * from './mem-checkpoint-core.js';
+export * from './mem-cleanup-core.js';
+export * from './mem-create-core.js';
+export * from './mem-id.js';
+export * from './mem-init-core.js';
+export * from './mem-ready-core.js';
+export * from './mem-signal-core.js';
+export * from './mem-start-core.js';
+export { filterSummarizableNodes, summarizeWu, getCompactionRatio as getSummarizeCompactionRatio, } from './mem-summarize-core.js';
+export * from './mem-triage-core.js';
+export * from './memory-schema.js';
+export * from './memory-store.js';

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,cAAc,0BAA0B,CAAC;AACzC,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,aAAa,CAAC;AAC5B,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC;AACpC,cAAc,yBAAyB,CAAC;AACxC,cAAc,sBAAsB,CAAC;AACrC,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC"}

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

@@ -0,0 +1,91 @@
+/**
+ * Memory Checkpoint Core (WU-1467, WU-1748)
+ *
+ * Core logic for creating checkpoint nodes for context snapshots.
+ * Used before /clear or session handoff to preserve progress state.
+ *
+ * Features:
+ * - Creates checkpoint nodes with progress summary and next steps
+ * - Optional linking to sessions and WUs
+ * - Supports handoff trigger detection
+ * - Auto-initializes memory layer if not present
+ * - WU-1748: Persists to wu-events.jsonl for cross-agent visibility
+ *
+ * @see {@link tools/mem-checkpoint.mjs} - CLI wrapper
+ * @see {@link tools/__tests__/mem-checkpoint.test.mjs} - Tests
+ * @see {@link tools/lib/memory-schema.mjs} - Schema definitions
+ */
+/**
+ * Checkpoint creation options
+ */
+export interface CreateCheckpointOptions {
+    /** Checkpoint note/description (required) */
+    note: string;
+    /** Session ID to link checkpoint to */
+    sessionId?: string;
+    /** Work Unit ID to link checkpoint to */
+    wuId?: string;
+    /** Progress summary */
+    progress?: string;
+    /** Next steps description */
+    nextSteps?: string;
+    /** Handoff trigger (e.g., 'clear', 'handoff') */
+    trigger?: string;
+}
+/**
+ * Checkpoint metadata stored in the node
+ */
+interface CheckpointMetadata {
+    progress?: string;
+    nextSteps?: string;
+    trigger?: string;
+    [key: string]: unknown;
+}
+/**
+ * Memory node structure for checkpoints
+ */
+interface CheckpointNode {
+    id: string;
+    type: 'checkpoint';
+    lifecycle: 'session';
+    content: string;
+    created_at: string;
+    wu_id?: string;
+    session_id?: string;
+    metadata?: CheckpointMetadata;
+}
+/**
+ * Checkpoint creation result
+ */
+export interface CreateCheckpointResult {
+    /** Whether the operation succeeded */
+    success: boolean;
+    /** Created checkpoint node */
+    checkpoint: CheckpointNode;
+}
+/**
+ * Creates a new checkpoint node for context preservation.
+ *
+ * Creates a checkpoint-type memory node with:
+ * - Unique ID (mem-XXXX format)
+ * - User-provided note in content
+ * - Optional session and WU linking
+ * - Progress summary and next steps in metadata
+ *
+ * @param baseDir - Base directory containing .beacon/memory/
+ * @param options - Checkpoint options
+ * @returns Result with created checkpoint node
+ * @throws If note is missing or WU ID is invalid
+ *
+ * @example
+ * const result = await createCheckpoint(baseDir, {
+ *   note: 'Before /clear - completed TDD tests',
+ *   sessionId: 'session-uuid',
+ *   wuId: 'WU-1467',
+ *   progress: 'TDD tests passing, core module implemented',
+ *   nextSteps: 'Implement CLI wrapper, add package.json script',
+ * });
+ * console.log(result.checkpoint.id); // 'mem-a1b2'
+ */
+export declare function createCheckpoint(baseDir: string, options: CreateCheckpointOptions): Promise<CreateCheckpointResult>;
+export {};

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

@@ -0,0 +1 @@
+{"version":3,"file":"mem-checkpoint-core.d.ts","sourceRoot":"","sources":["../src/mem-checkpoint-core.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAwEH;;;;;;;;;;GAUG;AAEH;;;;;;GAMG;AAEH;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,gBAAgB,CAAC,OAAO,KAAA,EAAE,OAAO,KAAA;;;;;;;;;GAmFtD"}

package/dist/mem-checkpoint-core.js

@@ -0,0 +1,175 @@
+/**
+ * Memory Checkpoint Core (WU-1467, WU-1748)
+ *
+ * Core logic for creating checkpoint nodes for context snapshots.
+ * Used before /clear or session handoff to preserve progress state.
+ *
+ * Features:
+ * - Creates checkpoint nodes with progress summary and next steps
+ * - Optional linking to sessions and WUs
+ * - Supports handoff trigger detection
+ * - Auto-initializes memory layer if not present
+ * - WU-1748: Persists to wu-events.jsonl for cross-agent visibility
+ *
+ * @see {@link tools/mem-checkpoint.mjs} - CLI wrapper
+ * @see {@link tools/__tests__/mem-checkpoint.test.mjs} - Tests
+ * @see {@link tools/lib/memory-schema.mjs} - Schema definitions
+ */
+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';
+import { WUStateStore } from '@lumenflow/core/dist/wu-state-store.js';
+/**
+ * Memory directory path relative to base directory
+ */
+const MEMORY_DIR = '.beacon/memory';
+/**
+ * WU state directory path relative to base directory (WU-1748)
+ */
+const STATE_DIR = '.beacon/state';
+/**
+ * Error messages for validation
+ */
+const ERROR_MESSAGES = {
+    NOTE_REQUIRED: 'note is required',
+    NOTE_EMPTY: 'note cannot be empty',
+    WU_ID_INVALID: 'Invalid WU ID format. Expected pattern: WU-XXX (e.g., WU-123)',
+};
+/**
+ * Checkpoint node type constant
+ */
+const NODE_TYPE_CHECKPOINT = 'checkpoint';
+/**
+ * Checkpoint lifecycle constant (session-scoped for handoff context)
+ */
+const LIFECYCLE_SESSION = 'session';
+/**
+ * Validates WU ID format if provided
+ *
+ * @param wuId - WU ID to validate
+ * @returns True if valid or not provided
+ */
+function isValidWuId(wuId) {
+    if (!wuId)
+        return true;
+    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 checkpoint node
+ *
+ * @param note - User-provided checkpoint note
+ * @returns Content description
+ */
+function generateCheckpointContent(note) {
+    return `Checkpoint: ${note}`;
+}
+/**
+ * Creates a new checkpoint node for context preservation.
+ *
+ * Creates a checkpoint-type memory node with:
+ * - Unique ID (mem-XXXX format)
+ * - User-provided note in content
+ * - Optional session and WU linking
+ * - Progress summary and next steps in metadata
+ *
+ * @param baseDir - Base directory containing .beacon/memory/
+ * @param options - Checkpoint options
+ * @returns Result with created checkpoint node
+ * @throws If note is missing or WU ID is invalid
+ *
+ * @example
+ * const result = await createCheckpoint(baseDir, {
+ *   note: 'Before /clear - completed TDD tests',
+ *   sessionId: 'session-uuid',
+ *   wuId: 'WU-1467',
+ *   progress: 'TDD tests passing, core module implemented',
+ *   nextSteps: 'Implement CLI wrapper, add package.json script',
+ * });
+ * console.log(result.checkpoint.id); // 'mem-a1b2'
+ */
+export async function createCheckpoint(baseDir, options) {
+    const { note, sessionId, wuId, progress, nextSteps, trigger } = options;
+    // Validate required fields
+    if (note === undefined || note === null) {
+        throw new Error(ERROR_MESSAGES.NOTE_REQUIRED);
+    }
+    if (note === '') {
+        throw new Error(ERROR_MESSAGES.NOTE_EMPTY);
+    }
+    // Validate WU ID format if provided
+    if (wuId && !isValidWuId(wuId)) {
+        throw new Error(ERROR_MESSAGES.WU_ID_INVALID);
+    }
+    // Ensure memory directory exists
+    const memoryDir = await ensureMemoryDir(baseDir);
+    // Generate checkpoint node
+    const timestamp = new Date().toISOString();
+    const content = generateCheckpointContent(note);
+    // Generate deterministic ID from content + timestamp for uniqueness
+    const idContent = `${content}-${timestamp}`;
+    const id = generateMemId(idContent);
+    // Build metadata object
+    const metadata = {};
+    if (progress) {
+        metadata.progress = progress;
+    }
+    if (nextSteps) {
+        metadata.nextSteps = nextSteps;
+    }
+    if (trigger) {
+        metadata.trigger = trigger;
+    }
+    const checkpointNode = {
+        id,
+        type: NODE_TYPE_CHECKPOINT,
+        lifecycle: LIFECYCLE_SESSION,
+        content,
+        created_at: timestamp,
+    };
+    // Add optional fields
+    if (wuId) {
+        checkpointNode.wu_id = wuId;
+    }
+    if (sessionId) {
+        checkpointNode.session_id = sessionId;
+    }
+    if (Object.keys(metadata).length > 0) {
+        checkpointNode.metadata = metadata;
+    }
+    // Persist to memory store
+    await appendNode(memoryDir, checkpointNode);
+    // WU-1748: Also persist to wu-events.jsonl for cross-agent visibility
+    if (wuId) {
+        try {
+            const stateDir = path.join(baseDir, STATE_DIR);
+            const store = new WUStateStore(stateDir);
+            await store.checkpoint(wuId, note, {
+                sessionId,
+                progress,
+                nextSteps,
+            });
+        }
+        catch {
+            // Non-fatal: if state store write fails, checkpoint is still in memory store
+            // This can happen if the WU hasn't been claimed yet
+        }
+    }
+    return {
+        success: true,
+        checkpoint: checkpointNode,
+    };
+}