@hotmeshio/hotmesh 0.4.1 → 0.4.3

package/README.md

@@ -1,15 +1,16 @@
-# HotMesh MemFlow
+# HotMesh
 
 **Permanent-Memory Workflows & AI Agents**
 
 ![beta release](https://img.shields.io/badge/release-beta-blue.svg)  ![made with typescript](https://img.shields.io/badge/built%20with-typescript-lightblue.svg)
 
-MemFlow is a drop-in Temporal-style engine that runs natively on Postgres — but with a twist:
-every workflow owns a *permanent*, JSON-backed context that lives beyond the main workflow.
-Any number of *hooks* (lightweight, thread-safe workers) can attach to that record at any
-time, read it, and safely write back incremental knowledge.
-Think **durable execution** + **shared, evolving memory** → perfect for human-in-the-loop
-processes and AI agents that learn over time.
+**HotMesh** is a Temporal-style workflow engine that runs natively on PostgreSQL — with a powerful twist: every workflow maintains permanent, state that persists independently of the workflow itself.
+
+This means:
+
+* Any number of lightweight, thread-safe **hook workers** can attach to the same workflow record at any time.
+* These hooks can safely **read and write** to shared state.
+* The result is a **durable execution model** with **evolving memory**, ideal for **human-in-the-loop processes** and **AI agents that learn over time**.
 
 ---
 
@@ -17,7 +18,7 @@ processes and AI agents that learn over time.
 
 1. 🚀 Quick Start
 2. 🧠 How Permanent Memory Works
-3. 🔌 Hooks & Context API
+3. 🔌 Hooks & Entity API
 4. 🤖 Building Durable AI Agents
 5. 🔬 Advanced Patterns & Recipes
 6. 📚 Documentation & Links
@@ -50,9 +51,11 @@ async function main() {
 
   // Kick off a workflow
   const handle = await mf.workflow.start({
-    workflowName: 'example',
+    entity: 'user',
+    workflowName: 'userExample',
+    workflowId: 'jane@hotmesh.com',
     args: ['Jane'],
-    taskQueue: 'contextual'
+    taskQueue: 'entityqueue'
   });
 
   console.log('Result:', await handle.result());
@@ -61,20 +64,20 @@ async function main() {
 main().catch(console.error);
 ```
 
+---
 
 ## 🧠 How Permanent Memory Works
 
-* **Context = JSONB row** in `<yourappname>.jobs` table
+* **Entity = persistent JSON record** – each workflow's memory is stored as a JSONB row in your Postgres database
 * **Atomic operations** (`set`, `merge`, `append`, `increment`, `toggle`, `delete`, …)
 * **Transactional** – every update participates in the workflow/DB transaction
 * **Time-travel-safe** – full replay compatibility; side-effect detector guarantees determinism
 * **Hook-friendly** – any worker with the record ID can attach and mutate its slice of the JSON
-
-* Context data is stored as JSONB; add partial indexes for improved query analysis.
+* **Index-friendly** - entity data is stored as JSONB; add partial indexes for improved query analysis.
 
 **Example: Adding a Partial Index for Specific Entity Types**
 ```sql
--- Create a partial index for 'user' entities with specific context values
+-- Create a partial index for 'user' entities with specific entity values
 CREATE INDEX idx_user_premium ON your_app.jobs (id)
 WHERE entity = 'user' AND (context->>'isPremium')::boolean = true;
 ```
@@ -82,42 +85,44 @@ This index will only be used for queries that match both conditions, making look
 
 ---
 
-## 🔌 Hooks & Context API – Full Example
+## 🔌 Hooks & Entity API – Full Example
+
+HotMesh hooks are powerful because they can be called both internally (from within a workflow) and externally (from outside, even after the workflow completes). This means you can:
+
+* Start a workflow that sets up initial state
+* Have the workflow call some hooks internally
+* Let the workflow complete
+* Continue to update the workflow's entity state from the outside via hooks
+* Build long-running processes that evolve over time
+
+Here's a complete example showing both internal and external hook usage:
 
 ```typescript
 import { MemFlow } from '@hotmeshio/hotmesh';
 
 /* ------------ Main workflow ------------ */
-export async function example(name: string): Promise<any> {
-  //the context method provides transactional, replayable access to shared job state 
-  const ctx = await MemFlow.workflow.context();
+export async function userExample(name: string): Promise<any> {
+  //the entity method provides transactional, replayable access to shared job state 
+  const entity = await MemFlow.workflow.entity();
 
-  //create the initial context (even arrays are supported)
-  await ctx.set({
+  //create the initial entity (even arrays are supported)
+  await entity.set({
     user: { name },
     hooks: {},
     metrics: { count: 0 }
   });
 
-  // Call two hooks in parallel to updaet the same shared context
-  const [r1, r2] = await Promise.all([
-    MemFlow.workflow.execHook({
-      taskQueue: 'contextual',
-      workflowName: 'hook1',
-      args: [name, 'hook1'],
-      signalId: 'hook1-complete',
-    }),
-    MemFlow.workflow.execHook({
-      taskQueue: 'contextual',
-      workflowName: 'hook2',
-      args: [name, 'hook2'],
-      signalId: 'hook2-complete',
-    })
-  ]);
-
-  // merge here (or have the hooks merge in...everyone can access context)
-  await ctx.merge({ hooks: { r1, r2 } });
-  await ctx.increment('metrics.count', 2);
+  // Call one hook internally
+  const result1 = await MemFlow.workflow.execHook({
+    taskQueue: 'entityqueue',
+    workflowName: 'hook1',
+    args: [name, 'hook1'],
+    signalId: 'hook1-complete'
+  });
+
+  // merge the result
+  await entity.merge({ hooks: { r1: result1 } });
+  await entity.increment('metrics.count', 1);
 
   return "The main has completed; the db record persists and can be hydrated; hook in from the outside!";
 }
@@ -129,20 +134,78 @@ export async function hook1(name: string, kind: string): Promise<any> {
   await MemFlow.workflow.signal('hook1-complete', res);
 }
 
-/* ------------ Hook 2 (hooks can access shared job context) ------------ */
+/* ------------ Hook 2 (hooks can access shared job entity) ------------ */
 export async function hook2(name: string, kind: string): Promise<void> {
-  const ctx = await MemFlow.workflow.context();
-  await ctx.merge({ user: { lastSeen: new Date().toISOString() } });
+  const entity = await MemFlow.workflow.entity();
+  await entity.merge({ user: { lastSeen: new Date().toISOString() } });
   await MemFlow.workflow.signal('hook2-complete', { ok: true });
 }
+
+/* ------------ Worker/Hook Registration ------------ */
+async function startWorker() {
+  const mf = await MemFlow.init({
+    appId: 'my-app',
+    engine: {
+      connection: {
+        class: Postgres,
+        options: { connectionString: process.env.DATABASE_URL }
+      }
+    }
+  });
+
+  const worker = await mf.worker.create({
+    taskQueue: 'entityqueue',
+    workflow: example
+  });
+
+  await mf.worker.create({
+    taskQueue: 'entityqueue',
+    workflow: hook1
+  });
+
+  await mf.worker.create({
+    taskQueue: 'entityqueue',
+    workflow: hook2
+  });
+
+  console.log('Workers and hooks started and listening...');
+}
 ```
 
-**Highlights**
+### The Power of External Hooks
+
+One of HotMesh's most powerful features is that workflow entities remain accessible even after the main workflow completes. By providing the original workflow ID, any authorized client can:
 
-* Hook functions are replay-safe.
-* Hook functions can safely read and write to the the *same* JSON context.
-* All context operations (`set`, `merge`, `append`, etc.) execute transactionally.
-* Context data is stored as JSONB; add partial indexes for improved query analysis.
+* Hook into existing workflow entities
+* Update state and trigger new processing
+* Build evolving, long-running processes
+* Enable human-in-the-loop workflows
+* Create AI agents that learn over time
+
+Here's how to hook into an existing workflow from the outside:
+
+```typescript
+/* ------------ External Hook Example ------------ */
+async function externalHookExample() {
+  const client = new MemFlow.Client({
+    appId: 'my-app',
+    engine: {
+      connection: {
+        class: Postgres,
+        options: { connectionString: process.env.DATABASE_URL }
+      }
+    }
+  });
+
+  // Start hook2 externally by providing the original workflow ID
+  await client.workflow.hook({
+    workflowId: 'jane@hotmesh.com', //id of the target workflow
+    taskQueue: 'entityqueue',
+    workflowName: 'hook2',
+    args: [name, 'external-hook']
+  });
+}
+```
 
 ---
 
@@ -150,10 +213,10 @@ export async function hook2(name: string, kind: string): Promise<void> {
 
 Permanent memory unlocks a straightforward pattern for agentic systems:
 
-1. **Planner workflow** – sketches a task list, seeds context.
-2. **Tool hooks** – execute individual tasks, feeding intermediate results back into context.
-3. **Reflector hook** – periodically summarises context into long-term memory embeddings.
-4. **Supervisor workflow** – monitors metrics stored in context and decides when to finish.
+1. **Planner workflow** – sketches a task list, seeds entity state.
+2. **Tool hooks** – execute individual tasks, feeding intermediate results back into state.
+3. **Reflector hook** – periodically summarizes state into long-term memory embeddings.
+4. **Supervisor workflow** – monitors metrics stored in state and decides when to finish.
 
 Because every step is durable *and* shares the same knowledge object, agents can pause,
 restart, scale horizontally, and keep evolving their world-model indefinitely.

package/build/index.d.ts

@@ -5,6 +5,7 @@ import { MemFlow } from './services/memflow';
 import { ClientService as Client } from './services/memflow/client';
 import { ConnectionService as Connection } from './services/memflow/connection';
 import { Search } from './services/memflow/search';
+import { Entity } from './services/memflow/entity';
 import { WorkerService as Worker } from './services/memflow/worker';
 import { WorkflowService as workflow } from './services/memflow/workflow';
 import { WorkflowHandleService as WorkflowHandle } from './services/memflow/handle';
@@ -21,5 +22,5 @@ import { RedisConnection as ConnectorIORedis } from './services/connector/provid
 import { RedisConnection as ConnectorRedis } from './services/connector/providers/redis';
 import { NatsConnection as ConnectorNATS } from './services/connector/providers/nats';
 export { Connector, //factory
-ConnectorIORedis, ConnectorNATS, ConnectorPostgres, ConnectorRedis, HotMesh, HotMeshConfig, MeshCall, MeshData, MemFlow, MeshOS, Client, Connection, proxyActivities, Search, Worker, workflow, WorkflowHandle, Enums, Errors, Utils, KeyStore, };
+ConnectorIORedis, ConnectorNATS, ConnectorPostgres, ConnectorRedis, HotMesh, HotMeshConfig, MeshCall, MeshData, MemFlow, MeshOS, Client, Connection, proxyActivities, Search, Entity, Worker, workflow, WorkflowHandle, Enums, Errors, Utils, KeyStore, };
 export * as Types from './types';

package/build/index.js

@@ -23,7 +23,7 @@ var __importStar = (this && this.__importStar) || function (mod) {
     return result;
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Types = exports.KeyStore = exports.Utils = exports.Errors = exports.Enums = exports.WorkflowHandle = exports.workflow = exports.Worker = exports.Search = exports.proxyActivities = exports.Connection = exports.Client = exports.MeshOS = exports.MemFlow = exports.MeshData = exports.MeshCall = exports.HotMesh = exports.ConnectorRedis = exports.ConnectorPostgres = exports.ConnectorNATS = exports.ConnectorIORedis = exports.Connector = void 0;
+exports.Types = exports.KeyStore = exports.Utils = exports.Errors = exports.Enums = exports.WorkflowHandle = exports.workflow = exports.Worker = exports.Entity = exports.Search = exports.proxyActivities = exports.Connection = exports.Client = exports.MeshOS = exports.MemFlow = exports.MeshData = exports.MeshCall = exports.HotMesh = exports.ConnectorRedis = exports.ConnectorPostgres = exports.ConnectorNATS = exports.ConnectorIORedis = exports.Connector = void 0;
 const hotmesh_1 = require("./services/hotmesh");
 Object.defineProperty(exports, "HotMesh", { enumerable: true, get: function () { return hotmesh_1.HotMesh; } });
 const meshcall_1 = require("./services/meshcall");
@@ -36,6 +36,8 @@ const connection_1 = require("./services/memflow/connection");
 Object.defineProperty(exports, "Connection", { enumerable: true, get: function () { return connection_1.ConnectionService; } });
 const search_1 = require("./services/memflow/search");
 Object.defineProperty(exports, "Search", { enumerable: true, get: function () { return search_1.Search; } });
+const entity_1 = require("./services/memflow/entity");
+Object.defineProperty(exports, "Entity", { enumerable: true, get: function () { return entity_1.Entity; } });
 const worker_1 = require("./services/memflow/worker");
 Object.defineProperty(exports, "Worker", { enumerable: true, get: function () { return worker_1.WorkerService; } });
 const workflow_1 = require("./services/memflow/workflow");

package/build/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@hotmeshio/hotmesh",
-    "version": "0.4.1",
+    "version": "0.4.2",
     "description": "Permanent-Memory Workflows & AI Agents",
     "main": "./build/index.js",
     "types": "./build/index.d.ts",
@@ -33,7 +33,8 @@
         "test:memflow:collision": "NODE_ENV=test jest ./tests/memflow/collision/*.test.ts --detectOpenHandles --forceExit --verbose",
         "test:memflow:fatal": "NODE_ENV=test jest ./tests/memflow/fatal/*.test.ts --detectOpenHandles --forceExit --verbose",
         "test:memflow:goodbye": "NODE_ENV=test jest ./tests/memflow/goodbye/*.test.ts --detectOpenHandles --forceExit --verbose",
-        "test:memflow:context": "NODE_ENV=test jest ./tests/memflow/context/postgres.test.ts --detectOpenHandles --forceExit --verbose",
+        "test:memflow:entity": "NODE_ENV=test HMSH_LOGLEVEL=debug jest ./tests/memflow/entity/postgres.test.ts --detectOpenHandles --forceExit --verbose",
+        "test:memflow:agent": "NODE_ENV=test HMSH_LOGLEVEL=debug jest ./tests/memflow/agent/postgres.test.ts --detectOpenHandles --forceExit --verbose",
         "test:memflow:hello": "HMSH_TELEMETRY=debug HMSH_LOGLEVEL=debug HMSH_IS_CLUSTER=true NODE_ENV=test jest ./tests/memflow/helloworld/*.test.ts --detectOpenHandles --forceExit --verbose",
         "test:memflow:hook": "NODE_ENV=test jest ./tests/memflow/hook/*.test.ts --detectOpenHandles --forceExit --verbose",
         "test:memflow:interrupt": "NODE_ENV=test jest ./tests/memflow/interrupt/*.test.ts --detectOpenHandles --forceExit --verbose",

package/build/services/activities/trigger.d.ts

@@ -31,7 +31,7 @@ declare class Trigger extends Activity {
     getJobStatus(): number;
     resolveJobId(context: Partial<JobState>): string;
     resolveJobKey(context: Partial<JobState>): string;
-    setStateNX(status?: number): Promise<void>;
+    setStateNX(status?: number, entity?: string): Promise<void>;
     setStats(transaction?: ProviderTransaction): Promise<void>;
 }
 export { Trigger };

package/build/services/activities/trigger.js

@@ -27,7 +27,7 @@ class Trigger extends activity_1.Activity {
             this.mapJobData();
             this.adjacencyList = await this.filterAdjacent();
             const initialStatus = this.initStatus(options, this.adjacencyList.length);
-            await this.setStateNX(initialStatus);
+            await this.setStateNX(initialStatus, options?.entity);
             await this.setStatus(initialStatus);
             this.bindSearchData(options);
             this.bindMarkerData(options);
@@ -228,9 +228,9 @@ class Trigger extends activity_1.Activity {
         const jobKey = this.config.stats?.key;
         return jobKey ? pipe_1.Pipe.resolve(jobKey, context) : '';
     }
-    async setStateNX(status) {
+    async setStateNX(status, entity) {
         const jobId = this.context.metadata.jid;
-        if (!await this.store.setStateNX(jobId, this.engine.appId, status)) {
+        if (!await this.store.setStateNX(jobId, this.engine.appId, status, entity)) {
             throw new errors_1.DuplicateJobError(jobId);
         }
     }

package/build/services/memflow/client.js

@@ -125,7 +125,7 @@ class ClientService {
              */
             start: async (options) => {
                 const taskQueueName = options.taskQueue ?? options.entity;
-                const workflowName = options.entity ?? options.workflowName;
+                const workflowName = options.taskQueue ? options.workflowName : (options.entity ?? options.workflowName);
                 const trc = options.workflowTrace;
                 const spn = options.workflowSpan;
                 //hotmesh `topic` is equivalent to `queue+workflowname` pattern in other systems
@@ -151,6 +151,7 @@ class ClientService {
                     search: options?.search?.data,
                     marker: options?.marker,
                     pending: options?.pending,
+                    entity: options?.entity,
                 });
                 return new handle_1.WorkflowHandleService(hotMeshClient, workflowTopic, jobId);
             },

package/build/services/memflow/{context.d.ts → entity.d.ts}

@@ -1,26 +1,26 @@
 import { HotMesh } from '../hotmesh';
 import { SearchService } from '../search';
 /**
- * The Context module provides methods for reading and writing
- * JSONB data to a workflow's context. The instance methods
+ * The Entity module provides methods for reading and writing
+ * JSONB data to a workflow's entity. The instance methods
  * exposed by this class are available for use from within
  * a running workflow.
  *
  * @example
  * ```typescript
- * //contextWorkflow.ts
+ * //entityWorkflow.ts
  * import { workflow } from '@hotmeshio/hotmesh';
  *
- * export async function contextExample(): Promise<void> {
- *   const context = await workflow.context();
- *   await context.set({ user: { id: 123 } });
- *   await context.merge({ user: { name: "John" } });
- *   const user = await context.get("user");
+ * export async function entityExample(): Promise<void> {
+ *   const entity = await workflow.entity();
+ *   await entity.set({ user: { id: 123 } });
+ *   await entity.merge({ user: { name: "John" } });
+ *   const user = await entity.get("user");
  *   // user = { id: 123, name: "John" }
  * }
  * ```
  */
-export declare class Context {
+export declare class Entity {
     /**
      * @private
      */
@@ -56,84 +56,84 @@ export declare class Context {
      */
     getSearchSessionGuid(): string;
     /**
-     * Sets the entire context object. This replaces any existing context.
+     * Sets the entire entity object. This replaces any existing entity.
      *
      * @example
-     * const context = await workflow.context();
-     * await context.set({ user: { id: 123, name: "John" } });
+     * const entity = await workflow.entity();
+     * await entity.set({ user: { id: 123, name: "John" } });
      */
     set(value: any): Promise<any>;
     /**
-     * Deep merges the provided object with the existing context
+     * Deep merges the provided object with the existing entity
      *
      * @example
-     * const context = await workflow.context();
-     * await context.merge({ user: { email: "john@example.com" } });
+     * const entity = await workflow.entity();
+     * await entity.merge({ user: { email: "john@example.com" } });
      */
     merge<T>(value: T): Promise<T>;
     /**
-     * Gets a value from the context by path
+     * Gets a value from the entity by path
      *
      * @example
-     * const context = await workflow.context();
-     * const user = await context.get("user");
-     * const email = await context.get("user.email");
+     * const entity = await workflow.entity();
+     * const user = await entity.get("user");
+     * const email = await entity.get("user.email");
      */
     get(path?: string): Promise<any>;
     /**
-     * Deletes a value from the context by path
+     * Deletes a value from the entity by path
      *
      * @example
-     * const context = await workflow.context();
-     * await context.delete("user.email");
+     * const entity = await workflow.entity();
+     * await entity.delete("user.email");
      */
     delete(path: string): Promise<any>;
     /**
      * Appends a value to an array at the specified path
      *
      * @example
-     * const context = await workflow.context();
-     * await context.append("items", { id: 1, name: "New Item" });
+     * const entity = await workflow.entity();
+     * await entity.append("items", { id: 1, name: "New Item" });
      */
     append(path: string, value: any): Promise<any[]>;
     /**
      * Prepends a value to an array at the specified path
      *
      * @example
-     * const context = await workflow.context();
-     * await context.prepend("items", { id: 0, name: "First Item" });
+     * const entity = await workflow.entity();
+     * await entity.prepend("items", { id: 0, name: "First Item" });
      */
     prepend(path: string, value: any): Promise<any[]>;
     /**
      * Removes an item from an array at the specified path and index
      *
      * @example
-     * const context = await workflow.context();
-     * await context.remove("items", 0); // Remove first item
+     * const entity = await workflow.entity();
+     * await entity.remove("items", 0); // Remove first item
      */
     remove(path: string, index: number): Promise<any[]>;
     /**
      * Increments a numeric value at the specified path
      *
      * @example
-     * const context = await workflow.context();
-     * await context.increment("counter", 5);
+     * const entity = await workflow.entity();
+     * await entity.increment("counter", 5);
      */
     increment(path: string, value?: number): Promise<number>;
     /**
      * Toggles a boolean value at the specified path
      *
      * @example
-     * const context = await workflow.context();
-     * await context.toggle("settings.enabled");
+     * const entity = await workflow.entity();
+     * await entity.toggle("settings.enabled");
      */
     toggle(path: string): Promise<boolean>;
     /**
      * Sets a value at the specified path only if it doesn't already exist
      *
      * @example
-     * const context = await workflow.context();
-     * await context.setIfNotExists("user.id", 123);
+     * const entity = await workflow.entity();
+     * await entity.setIfNotExists("user.id", 123);
      */
     setIfNotExists(path: string, value: any): Promise<any>;
     /**