saico 2.0.0 → 2.2.0

package/context.js

@@ -34,6 +34,9 @@ class Context {
         this._deferred_tool_calls = [];
         this._tool_call_sequence = [];
 
+        // Chat history persistence
+        this.chat_history = config.chat_history || null;
+
         this._msgs = [];
         this._waitingQueue = [];
         this._active_tool_calls = new Map();
@@ -43,6 +46,14 @@ class Context {
         this._processing_sequential = false;
         this._sequential_mode = config.sequential_mode || false;
 
+        // Queue structure limits
+        this.QUEUE_LIMIT = config.queue_limit ?? 30;
+        this.TOOL_DIGEST_LIMIT = config.tool_digest_limit ?? 10;
+        this.MIN_CHAT_MESSAGES = config.min_chat_messages ?? 10;
+
+        // Tool digest — persistent history of tool calls that mutated task state
+        this.tool_digest = config.tool_digest || [];
+
         // Initialize messages if provided
         (config.msgs || []).forEach(m => this.push(m));
 
@@ -58,6 +69,35 @@ class Context {
             this.functions = task?.functions;
     }
 
+    // Overridable: extending classes provide current state summary
+    getStateSummary() { return ''; }
+
+    // Snapshot all public (non-underscore) task properties for dirty detection.
+    // Mirrors the observable proxy convention: _ prefix = internal, ignored.
+    // Does NOT call serialize() — that is for persistence, not dirty detection.
+    _snapshotPublicProps(obj, seen = new Set()) {
+        if (typeof obj !== 'object' || obj === null) return obj;
+        if (seen.has(obj)) return undefined; // circular ref — skip
+        seen.add(obj);
+        const out = Array.isArray(obj) ? [] : {};
+        for (const key of Object.keys(obj)) {
+            if (!key.startsWith('_') && typeof obj[key] !== 'function')
+                out[key] = this._snapshotPublicProps(obj[key], seen);
+        }
+        seen.delete(obj);
+        return out;
+    }
+
+    // Append a tool result to the persistent tool digest
+    _appendToolDigest(toolName, resultContent) {
+        const truncated = typeof resultContent === 'string'
+            ? resultContent.slice(0, 500)
+            : String(resultContent ?? '').slice(0, 500);
+        this.tool_digest.push({ tool: toolName, result: truncated, tm: Date.now() });
+        if (this.tool_digest.length > this.TOOL_DIGEST_LIMIT)
+            this.tool_digest = this.tool_digest.slice(-this.TOOL_DIGEST_LIMIT);
+    }
+
     // Get the parent context by traversing task hierarchy
     getParentContext() {
         if (!this.task || !this.task.parent)
@@ -245,6 +285,8 @@ class Context {
                     };
                 } else {
                     this._trackActiveToolCall(call);
+                    const _snap = this.task
+                        ? JSON.stringify(this._snapshotPublicProps(this.task)) : null;
 
                     try {
                         const correspondingDeferred = deferredGroup.find(d => d.call.id === call.id);
@@ -252,6 +294,9 @@ class Context {
                         const timeout = correspondingDeferred?.originalMessage.opts.timeout;
 
                         result = await this._executeToolCallWithTimeout(call, handler, timeout);
+                        if (_snap !== null &&
+                            _snap !== JSON.stringify(this._snapshotPublicProps(this.task)))
+                            this._appendToolDigest(call.function.name, result?.content || '');
                     } finally {
                         this._completeActiveToolCall(call);
                     }
@@ -397,6 +442,48 @@ class Context {
         _log('Finished closing Context tag', this.tag);
     }
 
+    // Load chat history from store into message queue
+    async loadHistory(store) {
+        if (!store || !this.tag)
+            return;
+        const data = await store.load(this.tag);
+        if (!data)
+            return;
+        if (Array.isArray(data.tool_digest))
+            this.tool_digest = data.tool_digest;
+        if (!data.chat_history)
+            return;
+        const messages = await util.decompressMessages(data.chat_history);
+        if (!Array.isArray(messages) || messages.length === 0)
+            return;
+        // Find the index after the last system message to insert history
+        let insertIdx = 0;
+        for (let i = 0; i < this._msgs.length; i++) {
+            if (this._msgs[i].msg.role === 'system')
+                insertIdx = i + 1;
+        }
+        const historyMsgs = messages.map(m => ({
+            msg: m,
+            opts: {},
+            msgid: crypto.randomBytes(2).toString('hex'),
+            replied: 1
+        }));
+        this._msgs.splice(insertIdx, 0, ...historyMsgs);
+    }
+
+    // Remove tool-related messages tagged with a specific tag
+    cleanToolCallsByTag(tag) {
+        this._msgs = this._msgs.filter(m => {
+            if (m.opts.tag !== tag)
+                return true;
+            if (m.msg.tool_calls)
+                return false;
+            if (m.msg.role === 'tool')
+                return false;
+            return true;
+        });
+    }
+
     async _summarizeContext(close, targetCtx) {
         const keep = this._msgs.filter(m => !close && m.summary);
         const summarize = this._msgs.filter(m => (!close || !m.summary) && m.replied);
@@ -677,50 +764,82 @@ class Context {
         return validatedMsgs;
     }
 
-    // Build message queue - aggregates from task hierarchy
+    // Slice the last `limit` messages, walking back to avoid orphaning tool responses
+    // and expanding if fewer than MIN_CHAT_MESSAGES user/assistant messages are included.
+    _getQueueSlice(msgs, limit) {
+        if (msgs.length <= limit) return msgs;
+
+        let startIdx = msgs.length - limit;
+
+        // Walk backward if we'd start mid-tool-pair (tool response without its call)
+        while (startIdx > 0 && msgs[startIdx] && msgs[startIdx].role === 'tool')
+            startIdx--;
+
+        // Count user/assistant messages in the current window
+        let chatCount = 0;
+        for (let i = startIdx; i < msgs.length; i++) {
+            const role = msgs[i].role;
+            if (role === 'user' || role === 'assistant') chatCount++;
+        }
+
+        // Expand backward until we have at least MIN_CHAT_MESSAGES chat messages
+        while (chatCount < this.MIN_CHAT_MESSAGES && startIdx > 0) {
+            startIdx--;
+            const role = msgs[startIdx].role;
+            if (role === 'user' || role === 'assistant') chatCount++;
+        }
+
+        return msgs.slice(startIdx);
+    }
+
+    // Build message queue — layered structure:
+    //   Layer 1: System prompts from ancestor hierarchy + own prompt (transient)
+    //   Layer 2: [State Summary] from getStateSummary() override (transient, if non-empty)
+    //   Layer 3: [Tool Activity Log] from tool_digest (transient, if non-empty)
+    //   Layer 4: Ancestor summaries only + last QUEUE_LIMIT of own messages (persistent)
     _createMsgQ(add_tag, tag_filter) {
         const fullQueue = [];
-
-        // Get messages from ancestor contexts via task hierarchy
         const ancestorContexts = this.getAncestorContexts();
+
+        // Layer 1: System prompts from ancestor hierarchy + own prompt
         for (const ctx of ancestorContexts) {
             if (ctx.prompt) {
                 const prompt = {role: 'system', content: ctx.prompt};
-                if (add_tag)
-                    prompt.tag = ctx.tag;
+                if (add_tag) prompt.tag = ctx.tag;
                 fullQueue.push(prompt);
             }
-
-            let ctxMsgs;
-            if (tag_filter !== undefined) {
-                ctxMsgs = ctx._msgs.filter(m => {
-                    if (m.msg.role === 'system') return true;
-                    if (m.opts.summary) return true;
-                    if (m.opts.tag === tag_filter) return true;
-                    return false;
-                }).map(m => m.msg);
-            } else {
-                ctxMsgs = ctx.__msgs;
-            }
-
-            if (add_tag)
-                ctxMsgs = ctxMsgs.map(m => Object.assign({tag: ctx.tag}, m));
-
-            fullQueue.push(...ctxMsgs);
         }
-
-        // Add this context's prompt and messages
         if (this.prompt) {
             const prompt = {role: 'system', content: this.prompt};
-            if (add_tag)
-                prompt.tag = this.tag;
+            if (add_tag) prompt.tag = this.tag;
             fullQueue.push(prompt);
         }
 
+        // Layer 2: State summary (if non-empty)
+        const stateSummary = this.getStateSummary();
+        if (stateSummary)
+            fullQueue.push({role: 'system', content: '[State Summary]\n' + stateSummary});
+
+        // Layer 3: Tool digest (if non-empty)
+        if (this.tool_digest.length > 0) {
+            const digestText = this.tool_digest.map(entry =>
+                `[${new Date(entry.tm).toISOString()}] ${entry.tool}: ${entry.result}`
+            ).join('\n');
+            fullQueue.push({role: 'system', content: '[Tool Activity Log]\n' + digestText});
+        }
+
+        // Layer 4: Ancestor summaries only (no full ancestor messages)
+        for (const ctx of ancestorContexts) {
+            const summaries = ctx._msgs
+                .filter(m => m.opts.summary)
+                .map(m => add_tag ? Object.assign({}, m.msg, {tag: ctx.tag}) : m.msg);
+            fullQueue.push(...summaries);
+        }
+
+        // Own messages — filter by tag if requested, then slice to QUEUE_LIMIT
         let my_msgs;
         if (tag_filter !== undefined) {
             my_msgs = this._msgs.filter(m => {
-                if (m.msg.role === 'system') return true;
                 if (m.opts.summary) return true;
                 if (m.opts.tag === tag_filter) return true;
                 return false;
@@ -730,9 +849,9 @@ class Context {
         }
 
         if (add_tag)
-            my_msgs = my_msgs.map(m => Object.assign({tag: this.tag}, m));
+            my_msgs = my_msgs.map(m => Object.assign({}, m, {tag: this.tag}));
 
-        fullQueue.push(...my_msgs);
+        fullQueue.push(...this._getQueueSlice(my_msgs, this.QUEUE_LIMIT));
 
         return this._validateToolResponses(fullQueue);
     }
@@ -823,7 +942,6 @@ class Context {
                 this._processWaitingQueue();
             }
 
-            await this.summarizeMessages();
             Q = this._createMsgQ(false, o.opts?.tag);
 
             // Aggregate functions from hierarchy and merge with message-specific functions
@@ -898,11 +1016,16 @@ class Context {
 
                 for (const { call, isDuplicate } of toolCallsWithResults) {
                     if (!isDuplicate) {
+                        const _snap = this.task
+                            ? JSON.stringify(this._snapshotPublicProps(this.task)) : null;
                         try {
                             const result = await this._executeToolCallWithTimeout(
                                 call, o.opts?.handler, o.opts?.timeout);
                             const item = toolCallsWithResults.find(item => item.call.id === call.id);
                             if (item) item.result = result;
+                            if (_snap !== null &&
+                                _snap !== JSON.stringify(this._snapshotPublicProps(this.task)))
+                                this._appendToolDigest(call.function.name, result?.content || '');
                         } finally {
                             this._completeActiveToolCall(call);
                         }
@@ -971,7 +1094,10 @@ class Context {
         if (content && typeof content !== 'string')
             content = JSON.stringify(content);
         else if (!content)
-            content = `tool call ${call.function.name} ${call.id} completed. do not reply. wait for the next msg from the user`;
+        {
+            content = `tool call ${call.function.name} ${call.id} completed. do not reply. wait for the next msg `
+                +`from the user`;
+        }
 
         _log('FUNCTION RESULT', call.function.name, call.id, content.substring(0, 50) + '...',
             functions ? 'with functions' : 'no functions');

package/index.js

@@ -9,20 +9,44 @@
  * - Optional conversation contexts attached to tasks
  * - Hierarchical message aggregation with function collection
  * - Full tool_calls support with depth control
+ * - Storage persistence (Redis cache + optional DB backend)
  *
  * Main Components:
  * - Itask: Base task class for all tasks (supports states, cancellation, promises)
  * - Context: Conversation context with message handling and tool calls
  * - Sid: Session root task (extends Itask, always has a context)
+ * - Store: Storage abstraction layer (Redis + optional backends like DynamoDB)
  */
 
 const Itask = require('./itask.js');
 const { Context, createContext } = require('./context.js');
 const { Sid, createSid } = require('./sid.js');
+const { Store, DynamoBackend } = require('./store.js');
 
 // Wire up Context class reference in Itask to avoid circular dependency
 Itask.Context = Context;
 
+/**
+ * Initialize Saico with storage configuration.
+ * Sets up the Store singleton and optionally initializes Redis.
+ *
+ * @param {Object} config - Configuration options
+ * @param {boolean} config.redis - Whether to initialize Redis
+ * @param {Object} config.dynamodb - DynamoDB backend config {table, aws}
+ * @returns {Store} The initialized Store instance
+ */
+async function init(config = {}) {
+    const store = Store.init(config);
+
+    if (config.redis) {
+        const redis = require('./redis.js');
+        await redis.init();
+        store.setRedis(redis.rclient);
+    }
+
+    return store;
+}
+
 /**
  * Create a new task with optional context.
  *
@@ -35,6 +59,7 @@ Itask.Context = Context;
  * @param {Object} opt.bind - Bind context for state functions
  * @param {Itask} opt.spawn_parent - Parent task to spawn under
  * @param {boolean} opt.async - If true, don't auto-run
+ * @param {Object} opt.store - Store instance for persistence
  * @param {Array} states - Array of state functions
  * @returns {Itask} The created task
  */
@@ -42,6 +67,9 @@ function createTask(opt, states = []) {
     if (typeof opt === 'string')
         opt = { name: opt };
 
+    if (!opt.store)
+        opt.store = Store.instance;
+
     const task = new Itask(opt, states);
 
     // Auto-create context if prompt is provided
@@ -95,7 +123,8 @@ function createQ(prompt, parent, tag, token_limit, msgs, tool_handler, config =
         const childTask = new Itask({
             name: tag || 'child-context',
             async: true,
-            spawn_parent: parent.task
+            spawn_parent: parent.task,
+            store: Store.instance
         }, []);
         context.setTask(childTask);
         childTask.setContext(context);
@@ -110,6 +139,11 @@ module.exports = {
     Itask,
     Context,
     Sid,
+    Store,
+    DynamoBackend,
+
+    // Initialization
+    init,
 
     // Factory functions
     createTask,

package/itask.js

@@ -18,6 +18,7 @@ const assert = require('assert');
 const EventEmitter = require('events');
 const crypto = require('crypto');
 const util = require('./util.js');
+const { Store } = require('./store.js');
 
 const { _log, lerr , _ldbg, daysSince, minSince, shallowEqual, filterArray, logEvent } = util;
 
@@ -102,6 +103,10 @@ function Itask(opt, states){
     this.context = null;
     this._contextConfig = opt.contextConfig || {};
 
+    // Storage persistence
+    this.context_id = opt.context_id || null;
+    this._store = opt.store || Store.instance || null;
+
     // Store options for context creation (prompt, functions, etc.)
     this.prompt = opt.prompt;
     this.functions = opt.functions;
@@ -370,6 +375,15 @@ Itask.prototype.spawn = function spawn(child){
             Itask.root.delete(child);
             child._root_registered = false;
         }
+        // Auto-wrap with redis observable for live state persistence
+        if (child.context_id) {
+            try {
+                const redis = require('./redis.js');
+                if (redis.rclient) {
+                    redis.createObservableForRedis('saico:' + child.context_id, child);
+                }
+            } catch (e) { /* redis not available */ }
+        }
         // ensure async-created children begin execution
         if (!child.running && !child._completed){
             process.nextTick(() => {
@@ -578,6 +592,11 @@ Itask.ps = function ps(){
 };
 
 /* ---------- context management ---------- */
+// [BACKEND] explanation text appended to context prompts
+Itask.BACKEND_EXPLANATION = '\nNote: Messages prefixed with [BACKEND] are from the backend ' +
+    'server, not the user. They contain server instructions, data updates, or system context. ' +
+    'Treat them as authoritative system-level information.';
+
 // Get the context for this task, optionally creating one if needed
 Itask.prototype.getContext = function getContext(createIfMissing = false){
     if (this.context)
@@ -585,7 +604,9 @@ Itask.prototype.getContext = function getContext(createIfMissing = false){
     if (createIfMissing && this.prompt){
         // Lazy context creation - requires Context class to be set
         if (Itask.Context){
-            this.context = new Itask.Context(this.prompt, this, this._contextConfig);
+            const augmentedPrompt = this.prompt + Itask.BACKEND_EXPLANATION;
+            this.context = new Itask.Context(augmentedPrompt, this, this._contextConfig);
+            this.setContext(this.context);
             return this.context;
         }
     }
@@ -595,8 +616,20 @@ Itask.prototype.getContext = function getContext(createIfMissing = false){
 // Set context for this task
 Itask.prototype.setContext = function setContext(context){
     this.context = context;
-    if (context && typeof context.setTask === 'function')
-        context.setTask(this);
+    // Generate context_id if not already set
+    if (!this.context_id) {
+        if (this._store)
+            this.context_id = this._store.generateId();
+        else if (Store.instance)
+            this.context_id = Store.instance.generateId();
+        else
+            this.context_id = makeId(16);
+    }
+    if (context) {
+        context.tag = this.context_id;
+        if (typeof context.setTask === 'function')
+            context.setTask(this);
+    }
     return this;
 };
 
@@ -623,9 +656,10 @@ Itask.prototype.findContext = function findContext(){
     return null;
 };
 
-// Send a message using the context hierarchy
-// Delegates to the task's context, or walks up to find one
-Itask.prototype.sendMessage = async function sendMessage(role, content, functions, opts){
+// Send a backend message using the context hierarchy
+// New signature: sendMessage(content, functions, opts)
+// Always sends as role='user' with '[BACKEND] ' prefix
+Itask.prototype.sendMessage = async function sendMessage(content, functions, opts){
     // First try our own context
     let ctx = this.getContext();
     if (!ctx){
@@ -635,9 +669,21 @@ Itask.prototype.sendMessage = async function sendMessage(role, content, function
     if (!ctx){
         throw new Error('No context available in task hierarchy to send message');
     }
-    // Don't pass functions here - let context aggregate from hierarchy
-    // If caller wants to override, they can pass functions in opts
-    return ctx.sendMessage(role, content, functions, opts);
+    opts = Object.assign({}, opts, { tag: this.context_id });
+    return ctx.sendMessage('user', '[BACKEND] ' + content, functions, opts);
+};
+
+// Receive a user chat message (no [BACKEND] prefix)
+Itask.prototype.recvChatMessage = async function recvChatMessage(content, opts){
+    let ctx = this.getContext();
+    if (!ctx){
+        ctx = this.findContext();
+    }
+    if (!ctx){
+        throw new Error('No context available in task hierarchy to receive message');
+    }
+    opts = Object.assign({}, opts, { tag: this.context_id });
+    return ctx.sendMessage('user', content, null, opts);
 };
 
 // Aggregate functions from all contexts in the hierarchy
@@ -658,6 +704,45 @@ Itask.prototype.getHierarchyFunctions = function getHierarchyFunctions(){
 Itask.prototype.closeContext = async function closeContext(){
     if (!this.context)
         return;
+
+    // Clean tool call messages tagged with this context_id
+    if (this.context_id && typeof this.context.cleanToolCallsByTag === 'function')
+        this.context.cleanToolCallsByTag(this.context_id);
+
+    // Filter out tool calls and [BACKEND] messages, compress remaining as chat_history
+    const cleanedMsgs = this.context._msgs.filter(m => {
+        if (m.msg.tool_calls)
+            return false;
+        if (m.msg.role === 'tool')
+            return false;
+        if (typeof m.msg.content === 'string' && m.msg.content.startsWith('[BACKEND]'))
+            return false;
+        return true;
+    }).map(m => m.msg);
+
+    // Trim to last QUEUE_LIMIT before persisting
+    const queueLimit = this.context.QUEUE_LIMIT || 30;
+    const trimmedMsgs = cleanedMsgs.length > queueLimit
+        ? cleanedMsgs.slice(-queueLimit)
+        : cleanedMsgs;
+
+    if (trimmedMsgs.length > 0) {
+        const chat_history = await util.compressMessages(trimmedMsgs);
+        this.context.chat_history = chat_history;
+
+        // Persist to store
+        const store = this._store || Store.instance;
+        if (store && this.context_id) {
+            await store.save(this.context_id, {
+                chat_history,
+                tool_digest: this.context.tool_digest || [],
+                prompt: this.context.prompt,
+                tag: this.context.tag,
+                tm_closed: Date.now()
+            });
+        }
+    }
+
     await this.context.close();
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "saico",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "main": "index.js",
   "type": "commonjs",
   "description": "Hierarchical AI Conversation Orchestrator - Task hierarchy with conversation contexts",
@@ -20,6 +20,7 @@
     "openai.js",
     "util.js",
     "redis.js",
+    "store.js",
     "README.md",
     "LICENSE"
   ],
@@ -43,7 +44,16 @@
     "test": "NODE_ENV=test mocha --exit 'test/**/*.test.js'",
     "start": "node server.js"
   },
-  "keywords": ["ai", "conversation", "orchestrator", "task", "hierarchy", "openai", "chatgpt", "llm"],
+  "keywords": [
+    "ai",
+    "conversation",
+    "orchestrator",
+    "task",
+    "hierarchy",
+    "openai",
+    "chatgpt",
+    "llm"
+  ],
   "author": "wanderli-ai",
   "license": "ISC"
 }

package/sid.js

@@ -2,6 +2,7 @@
 
 const Itask = require('./itask.js');
 const { Context, createContext } = require('./context.js');
+const { Store } = require('./store.js');
 
 /**
  * Sid - Session/User Context root task.
@@ -25,6 +26,7 @@ class Sid extends Itask {
             ...opt,
             name,
             prompt,
+            store: opt.store || Store.instance || null,
             async: true // We'll manage running ourselves
         }, states);
 
@@ -39,16 +41,23 @@ class Sid extends Itask {
             ...opt.sessionConfig
         };
 
+        // Generate context_id if not already set by parent constructor
+        if (!this.context_id) {
+            const store = this._store || Store.instance;
+            this.context_id = store ? store.generateId() : require('crypto').randomBytes(8).toString('hex');
+        }
+
         // Always create a context for Sid (root session task)
         const contextConfig = {
-            tag: opt.tag || this.id,
+            tag: this.context_id,
             token_limit: this.sessionConfig.token_limit,
             max_depth: this.sessionConfig.max_depth,
             max_tool_repetition: this.sessionConfig.max_tool_repetition,
             tool_handler: opt.tool_handler,
             functions: opt.functions,
             sequential_mode: opt.sequential_mode,
-            msgs: opt.msgs
+            msgs: opt.msgs,
+            chat_history: opt.chat_history
         };
 
         this.context = new Context(prompt, this, contextConfig);
@@ -61,9 +70,17 @@ class Sid extends Itask {
         }
     }
 
-    // Override sendMessage to always use our context
-    async sendMessage(role, content, functions, opts) {
-        return this.context.sendMessage(role, content, functions || this.functions, opts);
+    // Override sendMessage — new signature: sendMessage(content, functions, opts)
+    // Always sends as role='user' with '[BACKEND] ' prefix
+    async sendMessage(content, functions, opts) {
+        opts = Object.assign({}, opts, { tag: this.context_id });
+        return this.context.sendMessage('user', '[BACKEND] ' + content, functions || this.functions, opts);
+    }
+
+    // Receive a user chat message (no [BACKEND] prefix)
+    async recvChatMessage(content, opts) {
+        opts = Object.assign({}, opts, { tag: this.context_id });
+        return this.context.sendMessage('user', content, null, opts);
     }
 
     // Serialize the session for persistence
@@ -72,12 +89,15 @@ class Sid extends Itask {
             id: this.id,
             name: this.name,
             prompt: this.prompt,
+            context_id: this.context_id,
             userData: this.userData,
             sessionConfig: this.sessionConfig,
             context: {
                 tag: this.context.tag,
                 msgs: this.context._msgs,
-                functions: this.context.functions
+                functions: this.context.functions,
+                chat_history: this.context.chat_history,
+                tool_digest: this.context.tool_digest
             },
             tm_create: this.tm_create
         });
@@ -90,11 +110,14 @@ class Sid extends Itask {
         const sid = new Sid({
             name: parsed.name,
             prompt: parsed.prompt,
+            context_id: parsed.context_id,
             userData: parsed.userData,
             sessionConfig: parsed.sessionConfig,
             tag: parsed.context?.tag,
             tool_handler: opt.tool_handler,
             functions: opt.functions || parsed.context?.functions,
+            chat_history: parsed.context?.chat_history,
+            store: opt.store,
             async: true, // Don't auto-run states
             ...opt
         }, opt.states || []);
@@ -108,6 +131,16 @@ class Sid extends Itask {
             sid.context._msgs = parsed.context.msgs;
         }
 
+        // Restore tool_digest
+        if (Array.isArray(parsed.context?.tool_digest)) {
+            sid.context.tool_digest = parsed.context.tool_digest;
+        }
+
+        // Load history from store if available
+        if (opt.store && parsed.context?.chat_history) {
+            sid.context.chat_history = parsed.context.chat_history;
+        }
+
         return sid;
     }
 
@@ -119,6 +152,7 @@ class Sid extends Itask {
         const childTask = new Itask({
             ...opt,
             spawn_parent: this,
+            store: this._store,
             async: true
         }, states);
 
@@ -150,6 +184,7 @@ class Sid extends Itask {
         const childTask = new Itask({
             ...opt,
             spawn_parent: this,
+            store: this._store,
             async: true
         }, states);
 

package/store.js

@@ -0,0 +1,163 @@
+'use strict';
+
+const crypto = require('crypto');
+
+let _instance = null;
+
+class DynamoBackend {
+    constructor({ table, aws }) {
+        this.table = table;
+        this.aws = aws;
+    }
+
+    async save(id, data) {
+        await this.aws.dynamoPutItem(this.table, {
+            id,
+            data: typeof data === 'string' ? data : JSON.stringify(data),
+            updated_at: Date.now()
+        });
+    }
+
+    async load(id) {
+        const item = await this.aws.dynamoGetItem(this.table, 'id', id);
+        if (!item)
+            return null;
+        const data = item.data;
+        if (typeof data === 'string') {
+            try { return JSON.parse(data); }
+            catch (e) { return data; }
+        }
+        return data;
+    }
+
+    async delete(id) {
+        await this.aws.dynamoDeleteItem(this.table, 'id', id);
+    }
+}
+
+class Store {
+    constructor(config = {}) {
+        this._redis = null;
+        this._backends = {};
+        this._config = config;
+
+        if (config.dynamodb) {
+            this._backends.dynamodb = new DynamoBackend(config.dynamodb);
+        }
+    }
+
+    static get instance() {
+        return _instance;
+    }
+
+    static set instance(val) {
+        _instance = val;
+    }
+
+    static init(config = {}) {
+        _instance = new Store(config);
+        // If redis module provided or redis is already initialized, grab the client
+        const redis = require('./redis.js');
+        if (redis.rclient)
+            _instance._redis = redis.rclient;
+        return _instance;
+    }
+
+    setRedis(rclient) {
+        this._redis = rclient;
+    }
+
+    addBackend(name, backend) {
+        this._backends[name] = backend;
+    }
+
+    generateId() {
+        return crypto.randomBytes(8).toString('hex');
+    }
+
+    async save(id, data) {
+        const key = 'saico:' + id;
+        const serialized = typeof data === 'string' ? data : JSON.stringify(data);
+
+        // Always save to Redis if available
+        if (this._redis) {
+            try {
+                await this._redis.set(key, serialized);
+            } catch (e) {
+                console.error('Store: Redis save error:', e.message);
+            }
+        }
+
+        // Save to all configured backends
+        for (const [name, backend] of Object.entries(this._backends)) {
+            try {
+                await backend.save(id, data);
+            } catch (e) {
+                console.error(`Store: ${name} backend save error:`, e.message);
+            }
+        }
+    }
+
+    async load(id) {
+        const key = 'saico:' + id;
+
+        // Try Redis first
+        if (this._redis) {
+            try {
+                const cached = await this._redis.get(key);
+                if (cached) {
+                    try { return JSON.parse(cached); }
+                    catch (e) { return cached; }
+                }
+            } catch (e) {
+                console.error('Store: Redis load error:', e.message);
+            }
+        }
+
+        // Fall back to backends
+        for (const [name, backend] of Object.entries(this._backends)) {
+            try {
+                const data = await backend.load(id);
+                if (data) {
+                    // Cache to Redis for next time
+                    if (this._redis) {
+                        try {
+                            const serialized = typeof data === 'string'
+                                ? data : JSON.stringify(data);
+                            await this._redis.set(key, serialized);
+                        } catch (e) {
+                            console.error('Store: Redis cache-back error:', e.message);
+                        }
+                    }
+                    return data;
+                }
+            } catch (e) {
+                console.error(`Store: ${name} backend load error:`, e.message);
+            }
+        }
+
+        return null;
+    }
+
+    async delete(id) {
+        const key = 'saico:' + id;
+
+        if (this._redis) {
+            try {
+                await this._redis.del(key);
+            } catch (e) {
+                console.error('Store: Redis delete error:', e.message);
+            }
+        }
+
+        for (const [name, backend] of Object.entries(this._backends)) {
+            try {
+                await backend.delete(id);
+            } catch (e) {
+                console.error(`Store: ${name} backend delete error:`, e.message);
+            }
+        }
+    }
+}
+
+module.exports = { Store, DynamoBackend };

package/util.js

@@ -1,5 +1,9 @@
 const is_mocha = process.env.NODE_ENV == 'test';
 const tiktoken = require('tiktoken');
+const zlib = require('zlib');
+const { promisify } = require('util');
+const gzip = promisify(zlib.gzip);
+const gunzip = promisify(zlib.gunzip);
 
 const debug = process.env.DEBUG === '1' || process.env.DEBUG === 'true';
 
@@ -58,6 +62,8 @@ const lerr = _lerr;
 
 module.exports = {
     countTokens,
+    compressMessages,
+    decompressMessages,
     is_mocha,
     _log,
     _lerr,
@@ -70,6 +76,34 @@ module.exports = {
     logEvent,
 }
 
+async function compressMessages(messages) {
+    const json = JSON.stringify(messages);
+    const compressed = await gzip(Buffer.from(json, 'utf8'));
+    return compressed.toString('base64');
+}
+
+async function decompressMessages(data) {
+    if (Array.isArray(data))
+        return data;
+    if (typeof data === 'string') {
+        // Try JSON parse first (plain JSON string)
+        try {
+            const parsed = JSON.parse(data);
+            if (Array.isArray(parsed))
+                return parsed;
+        } catch (e) { /* not plain JSON, try base64/gzip */ }
+        // Try base64 gzip
+        try {
+            const buf = Buffer.from(data, 'base64');
+            const decompressed = await gunzip(buf);
+            return JSON.parse(decompressed.toString('utf8'));
+        } catch (e) {
+            throw new Error('decompressMessages: unable to decompress data: ' + e.message);
+        }
+    }
+    throw new Error('decompressMessages: unsupported data type: ' + typeof data);
+}
+
 function countTokens(messages, model = "gpt-4o") {
 	// Load the encoding for the specified model
 	const encoding = tiktoken.encoding_for_model(model);