@hotmeshio/hotmesh 0.4.3 → 0.5.0

package/README.md

@@ -211,15 +211,156 @@ async function externalHookExample() {
 
 ## 🤖 Building Durable AI Agents
 
-Permanent memory unlocks a straightforward pattern for agentic systems:
+HotMesh's permanent memory enables a revolutionary approach to AI agents: **perspective-oriented intelligence**. Instead of monolithic agents, you build **multi-faceted agents** where:
 
-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.
+* **Entity state** = the agent's living, evolving context
+* **Hooks** = different perspectives that operate on that context
+* **Child workflows** = specialized co-agents with their own entity types
+* **Shared memory** = enables rich self-reflection and multi-agent collaboration
 
-Because every step is durable *and* shares the same knowledge object, agents can pause,
-restart, scale horizontally, and keep evolving their world-model indefinitely.
+### Example: A Research Agent with Multiple Perspectives
+
+```typescript
+/* ------------ Main Research Agent ------------ */
+export async function researchAgent(query: string): Promise<any> {
+  const entity = await MemFlow.workflow.entity();
+  
+  // Initialize agent context
+  await entity.set({
+    query,
+    findings: [],
+    perspectives: {},
+    confidence: 0,
+    status: 'researching'
+  });
+
+  // Spawn perspective hooks that operate on shared context
+  const optimisticView = MemFlow.workflow.execHook({
+    taskQueue: 'perspectives',
+    workflowName: 'optimisticPerspective',
+    args: [query]
+  });
+
+  const skepticalView = MemFlow.workflow.execHook({
+    taskQueue: 'perspectives', 
+    workflowName: 'skepticalPerspective',
+    args: [query]
+  });
+
+  // Spawn a fact-checker child agent with its own entity type
+  const factChecker = await MemFlow.workflow.execChild({
+    entity: 'fact-checker',
+    workflowName: 'factCheckAgent',
+    workflowId: `fact-check-${Date.now()}`,
+    args: [query],
+    taskQueue: 'agents'
+  });
+
+  // Wait for all perspectives to contribute
+  await Promise.all([optimisticView, skepticalView, factChecker]);
+
+  // Self-reflection: analyze conflicting perspectives
+  await MemFlow.workflow.execHook({
+    taskQueue: 'perspectives',
+    workflowName: 'synthesizePerspectives',
+    args: []
+  });
+
+  const finalContext = await entity.get();
+  return finalContext;
+}
+
+/* ------------ Optimistic Perspective Hook ------------ */
+export async function optimisticPerspective(query: string): Promise<void> {
+  const entity = await MemFlow.workflow.entity();
+  
+  // Optimistic perspective: look for supporting evidence
+  const findings = await searchForSupportingEvidence(query);
+  
+  await entity.merge({
+    perspectives: {
+      optimistic: {
+        findings,
+        confidence: 0.8,
+        bias: 'Tends to emphasize positive evidence'
+      }
+    }
+  });
+}
+
+/* ------------ Skeptical Perspective Hook ------------ */
+export async function skepticalPerspective(query: string): Promise<void> {
+  const entity = await MemFlow.workflow.entity();
+  
+  // Skeptical perspective: challenge assumptions
+  const counterEvidence = await searchForCounterEvidence(query);
+  
+  await entity.merge({
+    perspectives: {
+      skeptical: {
+        counterEvidence,
+        confidence: 0.6,
+        bias: 'Challenges assumptions and seeks contradictory evidence'
+      }
+    }
+  });
+}
+
+/* ------------ Fact-Checker Child Agent ------------ */
+export async function factCheckAgent(query: string): Promise<any> {
+  // This child has its own entity type for specialized fact-checking context
+  const entity = await MemFlow.workflow.entity();
+  
+  await entity.set({
+    query,
+    sources: [],
+    verifications: [],
+    credibilityScore: 0
+  });
+
+  // Fact-checker can spawn its own specialized hooks
+  await MemFlow.workflow.execHook({
+    taskQueue: 'verification',
+    workflowName: 'verifySourceCredibility',
+    args: [query]
+  });
+
+  return await entity.get();
+}
+
+/* ------------ Synthesis Perspective Hook ------------ */
+export async function synthesizePerspectives(): Promise<void> {
+  const entity = await MemFlow.workflow.entity();
+  const context = await entity.get();
+  
+  // Analyze conflicting perspectives and synthesize
+  const synthesis = await analyzePerspectives(context.perspectives);
+  
+  await entity.merge({
+    perspectives: {
+      synthesis: {
+        finalAssessment: synthesis,
+        confidence: calculateConfidence(context.perspectives),
+        reasoning: 'Balanced analysis of optimistic and skeptical viewpoints'
+      }
+    },
+    status: 'completed'
+  });
+}
+```
+
+### The Power of Perspective-Oriented Agents
+
+This approach enables agents that can:
+
+* **Question themselves** – different hooks challenge each other's assumptions
+* **Spawn specialized co-agents** – child workflows with their own entity types tackle specific domains
+* **Maintain rich context** – all perspectives contribute to a shared, evolving knowledge base
+* **Scale horizontally** – each perspective can run on different workers
+* **Learn continuously** – entity state accumulates insights across all interactions
+* **Self-reflect** – synthesis hooks analyze conflicting perspectives and improve decision-making
+
+Because every perspective operates on the same durable entity, agents can pause, restart, and evolve their world-model indefinitely while maintaining coherent, multi-faceted intelligence.
 
 ---
 

package/build/modules/errors.d.ts

@@ -35,6 +35,7 @@ declare class MemFlowProxyError extends Error {
 }
 declare class MemFlowChildError extends Error {
     await: boolean;
+    entity: string;
     arguments: string[];
     backoffCoefficient: number;
     code: number;

package/build/modules/errors.js

@@ -56,6 +56,7 @@ class MemFlowChildError extends Error {
         this.persistent = params.persistent;
         this.signalIn = params.signalIn;
         this.originJobId = params.originJobId;
+        this.entity = params.entity;
         this.index = params.index;
         this.workflowDimension = params.workflowDimension;
         this.code = enums_1.HMSH_CODE_MEMFLOW_CHILD;

package/build/package.json

@@ -1,10 +1,10 @@
 {
     "name": "@hotmeshio/hotmesh",
-    "version": "0.4.2",
+    "version": "0.5.0",
     "description": "Permanent-Memory Workflows & AI Agents",
     "main": "./build/index.js",
     "types": "./build/index.d.ts",
-    "homepage": "https://hotmesh.io/",
+    "homepage": "https://github.com/hotmeshio/sdk-typescript/",
     "publishConfig": {
         "access": "public"
     },

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, entity?: string): Promise<void>;
+    setStateNX(status?: number, entity?: string | undefined): Promise<void>;
     setStats(transaction?: ProviderTransaction): Promise<void>;
 }
 export { Trigger };

package/build/services/activities/trigger.js

@@ -9,6 +9,7 @@ const reporter_1 = require("../reporter");
 const serializer_1 = require("../serializer");
 const telemetry_1 = require("../telemetry");
 const activity_1 = require("./activity");
+const mapper_1 = require("../mapper");
 class Trigger extends activity_1.Activity {
     constructor(config, data, metadata, hook, engine, context) {
         super(config, data, metadata, hook, engine, context);
@@ -27,7 +28,9 @@ 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, options?.entity);
+            //config.entity is a pipe expression; if 'entity' exists, it will resolve
+            const resolvedEntity = new mapper_1.MapperService({ entity: this.config.entity }, this.context).mapRules()?.entity;
+            await this.setStateNX(initialStatus, options?.entity || resolvedEntity);
             await this.setStatus(initialStatus);
             this.bindSearchData(options);
             this.bindMarkerData(options);

package/build/services/memflow/schemas/factory.d.ts

@@ -17,7 +17,7 @@
  * * Service Meshes
  * * Master Data Management systems
  */
-declare const APP_VERSION = "4";
+declare const APP_VERSION = "5";
 declare const APP_ID = "memflow";
 /**
  * returns a new memflow workflow schema

package/build/services/memflow/schemas/factory.js

@@ -20,7 +20,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.APP_ID = exports.APP_VERSION = exports.getWorkflowYAML = void 0;
-const APP_VERSION = '4';
+const APP_VERSION = '5';
 exports.APP_VERSION = APP_VERSION;
 const APP_ID = 'memflow';
 exports.APP_ID = APP_ID;
@@ -86,6 +86,9 @@ const getWorkflowYAML = (app, version) => {
             signalIn:
               description: if false, the job will not support subordinated hooks
               type: boolean
+            entity:
+              description: the entity type for this workflow instance
+              type: string
 
       output:
         schema:
@@ -120,6 +123,7 @@ const getWorkflowYAML = (app, version) => {
         trigger:
           title: Main Flow Trigger
           type: trigger
+          entity: '{$self.input.data.entity}'
           job:
             maps:
               done: false
@@ -249,6 +253,9 @@ const getWorkflowYAML = (app, version) => {
                   await:
                     type: string
                     description: when set to false, do not await the child flow's completion
+                  entity:
+                    type: string
+                    description: the entity type for the child workflow
             591:
               schema:
                 type: object
@@ -367,6 +374,9 @@ const getWorkflowYAML = (app, version) => {
                   description: the arguments to pass to the activity
                   items:
                     type: string
+                entity:
+                  type: string
+                  description: the entity type for the child workflow
             maps:
               arguments: '{worker.output.data.arguments}'
               workflowDimension: '{worker.output.data.workflowDimension}'
@@ -379,6 +389,7 @@ const getWorkflowYAML = (app, version) => {
               workflowId: '{worker.output.data.workflowId}'
               workflowName: '{worker.output.data.workflowName}'
               workflowTopic: '{worker.output.data.workflowTopic}'
+              entity: '{worker.output.data.entity}'
               backoffCoefficient:
                 '@pipe':
                   - ['{worker.output.data.backoffCoefficient}','{trigger.output.data.backoffCoefficient}']
@@ -992,6 +1003,9 @@ const getWorkflowYAML = (app, version) => {
                   await:
                     type: string
                     description: when set to false, do not await the child flow's completion
+                  entity:
+                    type: string
+                    description: the entity type for the child workflow
             591:
               schema:
                 type: object
@@ -1109,6 +1123,9 @@ const getWorkflowYAML = (app, version) => {
                   description: the arguments to pass to the activity
                   items:
                     type: string
+                entity:
+                  type: string
+                  description: the entity type for the child workflow
             maps:
               arguments: '{signaler_worker.output.data.arguments}'
               workflowDimension: '{signaler_worker.output.data.workflowDimension}'
@@ -1121,6 +1138,7 @@ const getWorkflowYAML = (app, version) => {
               workflowId: '{signaler_worker.output.data.workflowId}'
               workflowName: '{signaler_worker.output.data.workflowName}'
               workflowTopic: '{signaler_worker.output.data.workflowTopic}'
+              entity: '{signaler_worker.output.data.entity}'
               backoffCoefficient:
                 '@pipe':
                   - ['{signaler_worker.output.data.backoffCoefficient}','{trigger.output.data.backoffCoefficient}']
@@ -1875,6 +1893,9 @@ const getWorkflowYAML = (app, version) => {
                   description: the arguments to pass to the activity
                   items:
                     type: string
+                entity:
+                  type: string
+                  description: the entity type for the child workflow
             maps:
               arguments:
                 '@pipe':
@@ -1946,6 +1967,11 @@ const getWorkflowYAML = (app, version) => {
                   - ['{collator_trigger.output.data.items}', '{collator_cycle_hook.output.data.cur_index}']
                   - ['{@array.get}', maximumInterval]
                   - ['{@object.get}']
+              entity:
+                '@pipe':
+                  - ['{collator_trigger.output.data.items}', '{collator_cycle_hook.output.data.cur_index}']
+                  - ['{@array.get}', entity]
+                  - ['{@object.get}']
           output:
             schema:
               type: object

package/build/services/memflow/worker.js

@@ -431,6 +431,7 @@ class WorkerService {
                             maximumAttempts: err.maximumAttempts || enums_1.HMSH_MEMFLOW_MAX_ATTEMPTS,
                             maximumInterval: err.maximumInterval || (0, utils_1.s)(enums_1.HMSH_MEMFLOW_MAX_INTERVAL),
                             originJobId: err.originJobId,
+                            entity: err.entity,
                             parentWorkflowId: err.parentWorkflowId,
                             expire: err.expire,
                             persistent: err.persistent,

package/build/services/memflow/workflow/execChild.js

@@ -22,7 +22,7 @@ function getChildInterruptPayload(context, options, execIndex) {
     }
     const parentWorkflowId = workflowId;
     const taskQueueName = options.taskQueue ?? options.entity;
-    const workflowName = options.entity ?? options.workflowName;
+    const workflowName = options.taskQueue ? options.workflowName : (options.entity ?? options.workflowName);
     const workflowTopic = `${taskQueueName}-${workflowName}`;
     return {
         arguments: [...(options.args || [])],
@@ -32,6 +32,7 @@ function getChildInterruptPayload(context, options, execIndex) {
         maximumAttempts: options?.config?.maximumAttempts ?? common_1.HMSH_MEMFLOW_MAX_ATTEMPTS,
         maximumInterval: (0, common_1.s)(options?.config?.maximumInterval ?? common_1.HMSH_MEMFLOW_MAX_INTERVAL),
         originJobId: originJobId ?? workflowId,
+        entity: options.entity,
         expire: options.expire ?? expire,
         persistent: options.persistent,
         signalIn: options.signalIn,

package/build/types/activity.d.ts

@@ -9,6 +9,7 @@ interface BaseActivity {
     statusThreshold?: number;
     statusThresholdType?: 'stop' | 'throw' | 'stall';
     input?: Record<string, any>;
+    entity?: string;
     output?: Record<string, any>;
     settings?: Record<string, any>;
     job?: Record<string, any>;
@@ -73,6 +74,7 @@ interface TriggerActivityStats {
 interface TriggerActivity extends BaseActivity {
     type: 'trigger';
     stats?: TriggerActivityStats;
+    entity?: string;
 }
 interface AwaitActivity extends BaseActivity {
     type: 'await';

package/build/types/error.d.ts

@@ -6,6 +6,7 @@ export type MemFlowChildErrorType = {
     expire?: number;
     persistent?: boolean;
     signalIn?: boolean;
+    entity?: string;
     maximumAttempts?: number;
     maximumInterval?: number;
     originJobId: string | null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hotmeshio/hotmesh",
-  "version": "0.4.3",
+  "version": "0.5.0",
   "description": "Permanent-Memory Workflows & AI Agents",
   "main": "./build/index.js",
   "types": "./build/index.d.ts",