saico 2.8.1 → 2.9.0

package/README.md

@@ -1,13 +1,13 @@
 # Saico - Hierarchical AI Conversation Orchestrator
 
-Saico is a Node.js library for building AI agents with hierarchical conversations, automatic context aggregation, and enterprise-grade tool calling. It manages nested task trees where each node can have its own conversation context, system prompt, tools, and state — and the library automatically assembles the full payload sent to the LLM by walking the tree.
+Saico is a Node.js library for building AI agents with hierarchical conversations, automatic context aggregation, and enterprise-grade tool calling. It manages nested task trees where each node can have its own message queue, system prompt, tools, and state — and the library automatically assembles the full payload sent to the LLM by walking the tree.
 
 ## Features
 
 - **Hierarchical conversations** — Parent-child task trees with automatic prompt, tool, and state summary aggregation
 - **Token-aware summarization** — Automatic summarization when message history approaches token limits
 - **Tool calling** — Depth control, deferred execution, duplicate detection, repetition prevention, and timeout handling
-- **Pluggable storage** — Optional Redis persistence (auto-save via proxy) and pluggable DB backends (DynamoDB adapter included)
+- **Pluggable storage** — Optional Redis persistence (auto-save via proxy), library-level backend registration (`Saico.registerBackend`), and pluggable DB backends (DynamoDB adapter included)
 - **Isolation boundaries** — `opt.isolate` stops ancestor aggregation at any node in the tree
 - **Serialization** — Full state save/restore for long-running agents
 
@@ -54,7 +54,7 @@ agent.activate({ createQ: true });
 // Backend message (prefixed with [BACKEND] automatically)
 const reply = await agent.sendMessage('What is the weather in Tokyo?');
 
-// User-facing chat message (routed to deepest active context)
+// User-facing chat message (routed to deepest active msgs Q)
 const chatReply = await agent.recvChatMessage('Hello!');
 ```
 
@@ -83,7 +83,7 @@ agent.activate();
 await agent.sendMessage('Do something');
 await agent.recvChatMessage('User says hello');
 
-// 4. Deactivate — bubbles cleaned messages to parent, closes context
+// 4. Deactivate — bubbles cleaned messages to parent, closes msgs Q
 await agent.deactivate();
 ```
 
@@ -124,7 +124,7 @@ Root Saico (prompt: "You are a manager")
     Functions aggregated from all levels.
 ```
 
-- **`sendMessage(content, functions, opts)`** — Sends a backend message (auto-prefixed `[BACKEND]`). Uses the current or nearest ancestor context.
+- **`sendMessage(content, functions, opts)`** — Sends a backend message (auto-prefixed `[BACKEND]`). Uses the current or nearest ancestor msgs Q.
 - **`recvChatMessage(content, opts)`** — Routes a user chat message DOWN to the deepest descendant with a message queue.
 
 ### Isolation
@@ -151,12 +151,12 @@ class OrderAgent extends Saico {
 }
 ```
 
-When a Saico's context is not the deepest active one, its last 5 user/assistant messages are also included in the state summary automatically.
+When a Saico's msgs Q is not the deepest active one, its last 5 user/assistant messages are also included in the state summary automatically.
 
 ### Spawning Child Saico Instances
 
 ```js
-// Child with its own conversation context (auto-activated by spawn)
+// Child with its own msgs Q (auto-activated by spawn)
 const child = new Saico({
     name: 'subtask',
     prompt: 'Handle this specific sub-task',
@@ -166,7 +166,7 @@ const child = new Saico({
 agent.spawn(child);
 await child.sendMessage('Working on subtask...');
 
-// Child without context (uses parent's via findContext())
+// Child without msgs Q (uses parent's via findMsgs())
 const simple = new Saico({ name: 'simple' });
 agent.spawn(simple);
 await simple.sendMessage('Quick operation');
@@ -210,7 +210,8 @@ new Saico({
     // Storage
     redis: true,               // Set false to skip Redis proxy
     key: 'custom-redis-key',
-    dynamodb: {                // DynamoDB config (creates adapter)
+    store: 'my-table',         // Table name for instance persistence (closeSession/rehydrate)
+    dynamodb: {                // DynamoDB config (creates instance-level adapter)
         region: 'us-east-1',
         credentials: { accessKeyId: '...', secretAccessKey: '...' },
     },
@@ -257,15 +258,15 @@ agent.getSessionInfo();
 //   userData, uptime
 // }
 
-await agent.closeSession();  // Saves full state to Store, cancels task
+await agent.closeSession();  // prepareForStorage + save to registered backend, cancels task
 
-// Restore from Store
-const restored = await Saico.rehydrate(agent.id, { store });
+// Restore from registered backend
+const restored = await Saico.rehydrate(agent.id, { store: 'sessions' });
 ```
 
 ## Database Access
 
-Saico provides backend-agnostic DB methods. Configure via `opt.dynamodb` (auto-creates DynamoDB adapter) or `opt.db` (any adapter). Table name is required on every call. Child Saico instances without their own DB inherit the parent's adapter automatically via `_getDb()`.
+Saico provides backend-agnostic DB methods. Configure via `Saico.registerBackend('dynamodb', config)` (library-level), `opt.dynamodb` (instance-level auto-creates adapter), or `opt.db` (any adapter). Table name is required on every call. Child Saico instances without their own DB inherit the parent's adapter automatically via `_getDb()`, which also falls back to the registered backend.
 
 ```js
 // CRUD — table name required on every call
@@ -300,28 +301,42 @@ class MyAgent extends Saico {
 
 ## Serialization
 
+Both `serialize()` and `Saico.deserialize()` are async. `serialize()` calls `prepareForStorage()` first (strips `_` props, skips functions/states, compresses msgs) then `JSON.stringify`s the result.
+
 ```js
-// In-memory snapshot (raw msgs, used by Redis proxy)
-const json = agent.serialize();
-const restored = Saico.deserialize(json);
+// prepareForStorage — clean snapshot
+const data = await agent.prepareForStorage();
+
+// serialize/deserialize
+const json = await agent.serialize();
+const restored = await Saico.deserialize(json);
 
-// Durable persistence (compressed msgs, saved to Store)
+// Durable persistence (uses registered backend + opt.store table name)
 await agent.closeSession();
-const restored2 = await Saico.rehydrate(agent.id, { store });
+const restored2 = await Saico.rehydrate(agent.id, { store: 'sessions' });
 ```
 
-`serialize()` includes: id, name, prompt, userData, sessionConfig, tm_create, isolate, and full context state (raw messages, tool_digest). `closeSession()` saves the same shape but with compressed messages for durable storage.
-
-## Redis Persistence
+`prepareForStorage()` automatically picks up all non-underscore properties (id, name, prompt, userData, sessionConfig, tm_create, isolate, etc.) and produces compressed chat_history for the msgs Q.
 
-When Redis is initialized, Saico instances are automatically wrapped in an observable proxy. Any property change triggers a debounced save to Redis.
+## Initialization
 
 ```js
-const { init } = require('saico');
+const { Saico, init } = require('saico');
+
+// Initialize Redis (default: enabled) and register DynamoDB backend
+await init({
+    dynamodb: { region: 'us-east-1', credentials: { accessKeyId: 'AK', secretAccessKey: 'SK' } },
+});
+
+// Or register backend directly
+Saico.registerBackend('dynamodb', { region: 'us-east-1', credentials: { ... } });
+```
 
-// Initialize with Redis
-await init({ redis: true });
+## Redis Persistence
+
+When Redis is initialized (default: enabled via `init()`), Saico instances are automatically wrapped in an observable proxy. Any property change triggers a debounced save to Redis.
 
+```js
 const agent = new Saico({ name: 'persistent-agent' });
 agent.someProperty = 'value';  // Auto-saved to Redis
 ```
@@ -374,11 +389,11 @@ const reply = await ctx.sendMessage('user', 'Hello', functions);
 ```
 saico/
 +-- index.js      # Thin barrel file, exports all components
-+-- saico.js      # Saico master class — owns context, spawn, DB, orchestration
++-- saico.js      # Saico master class — owns msgs Q, spawn, DB, orchestration
 +-- itask.js      # Pure task runner — hierarchy, states, cancellation, promises
 +-- msgs.js       # Conversation context (message queue, tool calls, summarization)
 +-- dynamo.js     # DynamoDB storage adapter
-+-- store.js      # Storage abstraction (Redis + pluggable backends)
++-- store.js      # Minimal storage shell (Redis helper + ID generation)
 +-- openai.js     # OpenAI API wrapper with retry logic
 +-- redis.js      # Redis persistence with observable proxy
 +-- util.js       # Utilities (token counting, logging)
@@ -390,7 +405,7 @@ saico/
 npm test
 ```
 
-290 tests covering Saico lifecycle, context ownership, spawn/spawnAndRun, task hierarchy, message handling, tool calls, DB adapters, serialization, persistence (closeSession/rehydrate), and integration flows.
+300 tests covering Saico lifecycle, msgs Q ownership, spawn/spawnAndRun, task hierarchy, message handling, tool calls, DB adapters, async serialization, prepareForStorage, backend registration, persistence (closeSession/rehydrate via registered backend), storage integration, and full hierarchy flows.
 
 ## Requirements
 

package/index.js

@@ -2,28 +2,30 @@
 
 const Itask = require('./itask.js');
 const { Msgs, createMsgs } = require('./msgs.js');
-const { Store, DynamoBackend } = require('./store.js');
+const { Store } = require('./store.js');
 const { Saico } = require('./saico.js');
 const { DynamoDBAdapter } = require('./dynamo.js');
 
 /**
  * Initialize Saico with storage configuration.
- * Sets up the Store singleton and optionally initializes Redis.
+ * Registers the backend 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}
+ * @param {boolean} [config.redis=true] - Set false to skip Redis init
+ * @param {Object} [config.dynamodb] - DynamoDB config { region, credentials, client }
  * @returns {Store} The initialized Store instance
  */
 async function init(config = {}) {
-    const store = Store.init(config);
-
-    if (config.redis) {
+    if (config.redis !== false) {
         const redis = require('./redis.js');
         await redis.init();
-        store.setRedis(redis.rclient);
     }
 
+    if (config.dynamodb)
+        Saico.registerBackend('dynamodb', config.dynamodb);
+
+    // Legacy: still init Store shell
+    const store = Store.init(config);
     return store;
 }
 
@@ -36,7 +38,6 @@ module.exports = {
     Itask,
     Msgs,
     Store,
-    DynamoBackend,
 
     // Initialization
     init,

package/itask.js

@@ -534,6 +534,9 @@ Itask.prototype.continue = function(ret){
     return this;
 };
 
+/* ---------- serialization ---------- */
+Itask.prototype.serialize = function(){ return JSON.stringify({}); };
+
 /* ---------- introspection / ps ---------- */
 Itask.prototype.is_running = function(){ return this.running && !this._completed; };
 Itask.prototype.is_completed = function(){ return this._completed; };

package/msgs.js

@@ -393,7 +393,15 @@ class Msgs {
         return this._msgs.length;
     }
 
-    serialize() { return JSON.stringify(this._msgs); }
+    async serialize() {
+        const { chat_history, tool_digest } = await this.prepareForStorage();
+        return JSON.stringify({
+            tag: this.tag,
+            chat_history,
+            tool_digest,
+            functions: this.functions,
+        });
+    }
 
     getSummaries() { return this._msgs.filter(m => m.opts.summary); }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "saico",
-  "version": "2.8.1",
+  "version": "2.9.0",
   "main": "index.js",
   "type": "commonjs",
   "description": "Hierarchical AI Conversation Orchestrator - Task hierarchy with conversation contexts",

package/redis.js

@@ -39,11 +39,13 @@ function createObservableForRedis(key, obj) {
     let lastSavedObject = null; // Cache for the last-saved sanitized object
     let lastSavedTimestamp = null; // Timestamp of the last save to Redis
 
-    const saveToRedis = debounce(() => {
+    const saveToRedis = debounce(async () => {
         const sanitizedObj = sanitizeObject(obj);
 
         // Compare sanitized object with the last-saved object
-        if (serialize(sanitizedObj) === serialize(lastSavedObject)) {
+        const serializedNew = await serialize(sanitizedObj);
+        const serializedOld = await serialize(lastSavedObject);
+        if (serializedNew === serializedOld) {
             logDebug("No changes detected, skipping save.");
             return;
         }
@@ -51,7 +53,7 @@ function createObservableForRedis(key, obj) {
         lastSavedObject = sanitizedObj;
         lastSavedTimestamp = Date.now(); // Update the last saved timestamp
 		sanitizedObj.lastSave = lastSavedTimestamp;
-        rclient.set(key, serialize(sanitizedObj));
+        await rclient.set(key, serializedNew);
         logDebug("Saved to Redis:", key, `at ${lastSavedTimestamp}`);
     }, 1000);
 
@@ -100,9 +102,9 @@ function createObservableForRedis(key, obj) {
         },
     };
 
-    function serialize(obj) {
+    async function serialize(obj) {
 		if (typeof obj == 'object' && typeof obj?.serialize == 'function')
-			return obj.serialize();
+			return await obj.serialize();
         return JSON.stringify(obj);
 	}
 

package/saico.js

@@ -3,7 +3,6 @@
 const crypto = require('crypto');
 const Itask = require('./itask.js');
 const { Msgs } = require('./msgs.js');
-const { Store } = require('./store.js');
 const util = require('./util.js');
 
 function makeId(len = 12){
@@ -19,7 +18,7 @@ function makeId(len = 12){
  *   - Construction: sets up storage (Redis observable + optional DynamoDB),
  *     class-level prompt, tool config. No Itask is created yet.
  *   - activate(opts): creates the internal Itask and optionally attaches a
- *     message Q context (when opts.createQ is true).
+ *     message Q (when opts.createQ is true).
  *   - DB access works before and after activation.
  *
  * Saico orchestrates the full message payload sent to the LLM by walking its
@@ -37,11 +36,11 @@ class Saico {
      * @param {Array} [opt.functions] - Available AI functions
      * @param {string} [opt.key] - Redis key override (default: 'saico:<id>')
      * @param {boolean} [opt.redis=true] - Set false to skip Redis proxy
-     * @param {boolean} [opt.createQ] - Create message Q context on activate()
+     * @param {boolean} [opt.createQ] - Create message Q on activate()
      * @param {boolean} [opt.isolate] - Isolate: don't aggregate from ancestors
      * @param {Object} [opt.dynamodb] - DynamoDB config { region, credentials: { accessKeyId, secretAccessKey }, client }
      * @param {Object} [opt.db] - Pluggable DB backend
-     * @param {Object} [opt.store] - Store instance override
+     * @param {string} [opt.store] - Table name for instance persistence
      * @param {Object} [opt.userData] - Initial user data
      * @param {Object} [opt.sessionConfig] - Session config overrides
      */
@@ -49,13 +48,13 @@ class Saico {
         // Internal properties (underscore-prefixed, not persisted to Redis)
         this.id = opt.id || crypto.randomBytes(8).toString('hex');
         this._task = null;
-        this._store = opt.store || Store.instance || null;
+        this._storeName = (typeof opt.store === 'string') ? opt.store : null;
         this._opt = opt;
-        this._isolate = opt.isolate || false;
+        this.isolate = opt.isolate || false;
 
-        // Context owned directly by Saico (not Itask)
-        this.context = null;
-        this.context_id = null;
+        // Msgs Q owned directly by Saico (not Itask)
+        this.msgs = null;
+        this.msgs_id = null;
 
         // Public configuration
         this.name = opt.name || this.constructor.name || 'saico';
@@ -98,7 +97,7 @@ class Saico {
     }
 
     /**
-     * Create the internal Itask and optionally a message Q context.
+     * Create the internal Itask and optionally a message Q.
      *
      * @param {Object} opts
      * @param {boolean} [opts.createQ] - Override this.createQ for this activation
@@ -106,7 +105,7 @@ class Saico {
      * @param {Array} [opts.functions] - Override functions
      * @param {Array} [opts.states] - Override this.states for this activation
      * @param {string} [opts.taskId] - Custom task ID
-     * @param {number} [opts.token_limit] - Token limit for context
+     * @param {number} [opts.token_limit] - Token limit for msgs Q
      * @param {number} [opts.max_depth] - Max tool call depth
      * @param {number} [opts.max_tool_repetition] - Max tool repetition
      * @param {number} [opts.queue_limit] - Message queue limit
@@ -114,14 +113,22 @@ class Saico {
      * @param {boolean} [opts.sequential_mode] - Sequential message processing
      * @param {Array} [opts.msgs] - Initial messages
      * @param {*} [opts.chat_history] - Chat history to restore
-     * @param {Object} [opts.contextConfig] - Additional Context config overrides
+     * @param {Object} [opts.msgsConfig] - Additional Msgs config overrides
      * @returns {Saico} this instance (for chaining)
      */
     activate(opts = {}) {
         if (this._task)
             throw new Error('Already activated. Call deactivate() first.');
 
-        const states = opts.states || this.states || [];
+        const defaultStates = [
+            async function main() {
+                return this._task.wait();
+            },
+            async function catch$error_handler(err) {
+                console.error(`${this.name} caught error:`, err);
+            },
+        ];
+        const states = opts.states || this.states || defaultStates;
 
         // Build effective prompt: class-level + activation-level
         const effectivePrompt = [this.prompt, opts.prompt].filter(Boolean).join('\n');
@@ -138,10 +145,10 @@ class Saico {
         // Store Saico reference on task for parent chain traversal
         this._task._saico = this;
 
-        // Create message Q context if requested (class-level or activate-level)
+        // Create message Q if requested (class-level or activate-level)
         if (opts.createQ ?? this.createQ) {
             const functions = opts.functions || this.functions;
-            const contextConfig = {
+            const msgsConfig = {
                 tag: opts.tag || this._task.id,
                 token_limit: opts.token_limit ?? this.sessionConfig.token_limit,
                 max_depth: opts.max_depth ?? this.sessionConfig.max_depth,
@@ -153,16 +160,16 @@ class Saico {
                 msgs: opts.msgs,
                 chat_history: opts.chat_history,
                 tool_digest: opts.tool_digest,
-                ...opts.contextConfig,
+                ...opts.msgsConfig,
             };
 
             const augmentedPrompt = effectivePrompt
                 ? effectivePrompt + Saico.BACKEND_EXPLANATION
                 : '';
-            const msgs = new Msgs(augmentedPrompt, contextConfig);
-            this.context = msgs;
-            this.context_id = makeId(16);
-            msgs.tag = this.context_id;
+            const msgs = new Msgs(augmentedPrompt, msgsConfig);
+            this.msgs = msgs;
+            this.msgs_id = makeId(16);
+            msgs.tag = this.msgs_id;
 
             // Wire callbacks for hierarchy access
             msgs._findToolImpl = (toolName) => this._findToolImpl(toolName);
@@ -175,63 +182,63 @@ class Saico {
     // ---- Context management (owned by Saico, not Itask) ----
 
     /**
-     * Find the nearest context walking UP the Saico/task hierarchy.
+     * Find the nearest msgs Q walking UP the Saico/task hierarchy.
      */
-    findContext() {
-        if (this.context) return this.context;
+    findMsgs() {
+        if (this.msgs) return this.msgs;
         let task = this._task?.parent;
         while (task) {
-            if (task._saico?.context) return task._saico.context;
+            if (task._saico?.msgs) return task._saico.msgs;
             task = task.parent;
         }
         return null;
     }
 
     /**
-     * Walk DOWN to find the deepest active descendant with a context.
+     * Walk DOWN to find the deepest active descendant with a msgs Q.
      */
-    findDeepestContext() {
-        if (!this._task) return this.context || null;
-        let deepest = this.context ? { context: this.context, depth: 0 } : null;
+    findDeepestMsgs() {
+        if (!this._task) return this.msgs || null;
+        let deepest = this.msgs ? { msgs: this.msgs, depth: 0 } : null;
         const search = (task, depth) => {
             for (const child of task.child) {
                 if (child._completed) continue;
-                if (child._saico?.context) {
+                if (child._saico?.msgs) {
                     if (!deepest || depth + 1 >= deepest.depth)
-                        deepest = { context: child._saico.context, depth: depth + 1 };
+                        deepest = { msgs: child._saico.msgs, depth: depth + 1 };
                 }
                 search(child, depth + 1);
             }
         };
         search(this._task, 0);
-        return deepest ? deepest.context : null;
+        return deepest ? deepest.msgs : null;
     }
 
     /**
-     * Deactivate — bubble cleaned messages to parent, close context, cancel task.
+     * Deactivate — bubble cleaned messages to parent, close msgs Q, cancel task.
      * Pushes cleaned messages (no tool calls, no BACKEND) into the parent's Q,
-     * then closes the context without the default summary bubbling.
+     * then closes the msgs Q without the default summary bubbling.
      */
     async deactivate() {
         if (!this._task) return;
-        if (this.context) {
-            // Find parent context to bubble cleaned messages
+        if (this.msgs) {
+            // Find parent msgs to bubble cleaned messages
             let parentTask = this._task.parent;
-            let parentCtx = null;
+            let parentMsgs = null;
             while (parentTask) {
-                if (parentTask._saico?.context) { parentCtx = parentTask._saico.context; break; }
+                if (parentTask._saico?.msgs) { parentMsgs = parentTask._saico.msgs; break; }
                 parentTask = parentTask.parent;
             }
-            if (parentCtx) {
+            if (parentMsgs) {
                 const cleaned = this.getRecentMessages(Infinity);
                 for (const msg of cleaned)
-                    parentCtx.push(msg);
+                    parentMsgs.push(msg);
             }
-            // Clean tool calls and close context without additional summary bubbling.
-            if (this.context_id && typeof this.context.cleanToolCallsByTag === 'function')
-                this.context.cleanToolCallsByTag(this.context_id);
-            this.context = null;
-            this.context_id = null;
+            // Clean tool calls and close msgs Q without additional summary bubbling.
+            if (this.msgs_id && typeof this.msgs.cleanToolCallsByTag === 'function')
+                this.msgs.cleanToolCallsByTag(this.msgs_id);
+            this.msgs = null;
+            this.msgs_id = null;
         }
         this._task._ecancel();
         this._task = null;
@@ -276,7 +283,7 @@ class Saico {
      */
     _getSaicoAncestors() {
         const chain = [this];
-        if (this._isolate) return chain;
+        if (this.isolate) return chain;
         let task = this._task?.parent;
         while (task) {
             if (task._saico) {
@@ -290,7 +297,7 @@ class Saico {
 
     /**
      * Build preamble and aggregated functions by walking the Saico chain.
-     * @param {Context} activeCtx - The deepest active context (for state summary logic)
+     * @param {Msgs} activeCtx - The deepest active msgs Q (for state summary logic)
      * @returns {{ preamble: Array, allFunctions: Array }}
      */
     _buildPreamble(activeCtx) {
@@ -317,8 +324,8 @@ class Saico {
             }
 
             // Tools digest
-            if (saico.context?.tool_digest?.length > 0) {
-                const digestText = saico.context.tool_digest.map(entry =>
+            if (saico.msgs?.tool_digest?.length > 0) {
+                const digestText = saico.msgs.tool_digest.map(entry =>
                     `[${new Date(entry.tm).toISOString()}] ${entry.tool}: ${entry.result}`
                 ).join('\n');
                 preamble.push({ role: 'system', content: '[Tool Activity Log]\n' + digestText });
@@ -337,20 +344,20 @@ class Saico {
         if (!this._task)
             throw new Error('Not activated. Call activate() first.');
 
-        // Find the active context (own or walk up)
-        let ctx = this.findContext();
+        // Find the active msgs Q (own or walk up)
+        let ctx = this.findMsgs();
         if (!ctx)
-            throw new Error('No context available');
+            throw new Error('No msgs Q available');
 
         // Build preamble by walking Saico chain
-        const activeCtx = this.findDeepestContext() || ctx;
+        const activeCtx = this.findDeepestMsgs() || ctx;
         const { preamble, allFunctions } = this._buildPreamble(activeCtx);
 
         // Merge with call-specific functions
         if (functions) allFunctions.push(...(Array.isArray(functions) ? functions : [functions]));
 
         opts = Object.assign({}, opts, {
-            tag: this.context_id,
+            tag: this.msgs_id,
             _preamble: preamble,
             _aggregatedFunctions: allFunctions.length > 0 ? allFunctions : null,
         });
@@ -362,9 +369,9 @@ class Saico {
             throw new Error('Not activated. Call activate() first.');
 
         // Route DOWN to deepest descendant with a msg Q
-        const ctx = this.findDeepestContext();
+        const ctx = this.findDeepestMsgs();
         if (!ctx)
-            throw new Error('No context available');
+            throw new Error('No msgs Q available');
 
         // Build preamble by walking Saico chain
         const { preamble, allFunctions } = this._buildPreamble(ctx);
@@ -396,8 +403,8 @@ class Saico {
      * @returns {Array<{role: string, content: string}>}
      */
     getRecentMessages(n = 5) {
-        if (!this.context) return [];
-        return this.context._msgs
+        if (!this.msgs) return [];
+        return this.msgs._msgs
             .filter(m => {
                 if (m.msg.role === 'tool' || m.msg.tool_calls) return false;
                 if (typeof m.msg.content === 'string' && m.msg.content.startsWith('[BACKEND]')) return false;
@@ -409,8 +416,8 @@ class Saico {
 
     /**
      * Internal state summary builder. Includes own getStateSummary() and,
-     * if this context is NOT the active (deepest) Q, includes recent messages.
-     * @param {Context} activeCtx - The deepest active context
+     * if this msgs Q is NOT the active (deepest) Q, includes recent messages.
+     * @param {Msgs} activeCtx - The deepest active msgs Q
      * @returns {Array|string|null}
      */
     _getStateSummary(activeCtx) {
@@ -418,8 +425,8 @@ class Saico {
         const own = this.getStateSummary();
         if (own) parts.push(own);
 
-        // If this context is NOT the active (deepest) Q, include recent messages
-        if (this.context && activeCtx && this.context !== activeCtx) {
+        // If this msgs Q is NOT the active (deepest) Q, include recent messages
+        if (this.msgs && activeCtx && this.msgs !== activeCtx) {
             const recent = this.getRecentMessages(5);
             if (recent.length > 0) parts.push(...recent);
         }
@@ -486,7 +493,7 @@ class Saico {
             name: this.name,
             running: this._task?.running || false,
             completed: this._task?._completed || false,
-            messageCount: this.context?.length || 0,
+            messageCount: this.msgs?.length || 0,
             childCount: this._task?.child?.size || 0,
             userData: this.userData,
             uptime: Date.now() - this.tm_create,
@@ -494,35 +501,17 @@ class Saico {
     }
 
     /**
-     * Close the session — compress msgs, save full state to Store, cancel task.
-     * The saved object has the same shape as serialize() but with compressed
-     * context messages (chat_history) instead of raw _msgs.
+     * Close the session — save state to registered backend, cancel task.
      */
     async closeSession() {
         if (!this._task) return;
 
-        // Save full state to Store with compressed msgs
-        const store = this._store || Store.instance;
-        if (store && this.context) {
-            const { chat_history, tool_digest } = await this.context.prepareForStorage();
-            const data = {
-                id: this.id,
-                name: this.name,
-                prompt: this.prompt,
-                userData: this.userData,
-                sessionConfig: this.sessionConfig,
-                tm_create: this.tm_create,
-                isolate: this._isolate,
-                taskId: this._task.id,
-                context_id: this.context_id,
-                context: {
-                    tag: this.context.tag,
-                    chat_history,
-                    tool_digest,
-                    functions: this.context.functions,
-                },
-            };
-            await store.save(this.id, data);
+        if (this._storeName && this.msgs) {
+            const backend = Saico.getBackend();
+            if (backend) {
+                const data = await this.prepareForStorage();
+                await backend.put(data, this._storeName);
+            }
         }
 
         this._task._ecancel();
@@ -541,7 +530,8 @@ class Saico {
             if (task._saico?._db) return task._saico._db;
             task = task.parent;
         }
-        throw new Error('No DB backend configured. Set opt.dynamodb or opt.db on this Saico or an ancestor.');
+        if (Saico._backend) return Saico._backend;
+        throw new Error('No DB backend configured. Call Saico.registerBackend() or set opt.db.');
     }
 
     async dbPutItem(item, table) {
@@ -628,42 +618,64 @@ class Saico {
 
     // ---- Serialization ----
 
+    /**
+     * Prepare this instance for storage. Creates a clean snapshot:
+     * - Strips all '_' prefixed properties
+     * - Strips functions (including states)
+     * - Builds compressed chat_history from msgs Q (via Msgs.prepareForStorage)
+     * - Adds taskId from internal Itask
+     * @returns {Promise<Object>} Plain serializable object
+     */
+    async prepareForStorage() {
+        const data = {};
+        for (const key of Object.keys(this)) {
+            if (key.startsWith('_')) continue;
+            if (typeof this[key] === 'function') continue;
+            if (key === 'msgs') continue;       // handled specially below
+            if (key === 'states') continue;      // function array, not serializable
+            data[key] = this[key];
+        }
+
+        // Deep clone to detach from live instance
+        const cloned = JSON.parse(JSON.stringify(data));
+
+        // Handle msgs — compress via Msgs.prepareForStorage
+        if (this.msgs) {
+            const { chat_history, tool_digest } = await this.msgs.prepareForStorage();
+            cloned.msgs = {
+                tag: this.msgs.tag,
+                chat_history,
+                tool_digest,
+                functions: this.msgs.functions,
+            };
+        } else {
+            cloned.msgs = null;
+        }
+
+        // Derived properties from underscore-prefixed internals
+        cloned.taskId = this._task?.id || null;
+
+        return cloned;
+    }
+
     /**
      * Serialize the Saico instance to a JSON string.
-     * Context messages are included as raw _msgs (for Redis / in-memory use).
-     * For durable storage with compressed msgs, use closeSession().
+     * Calls prepareForStorage() to build a clean snapshot, then JSON.stringify.
      */
-    serialize() {
-        const data = {
-            id: this.id,
-            name: this.name,
-            prompt: this.prompt,
-            userData: this.userData,
-            sessionConfig: this.sessionConfig,
-            tm_create: this.tm_create,
-            isolate: this._isolate,
-        };
-        data.taskId = this._task?.id || null;
-        data.context_id = this.context_id || null;
-        data.context = this.context ? {
-            tag: this.context.tag,
-            msgs: this.context._msgs,
-            functions: this.context.functions,
-            tool_digest: this.context.tool_digest,
-        } : null;
-        return JSON.stringify(data);
+    async serialize() {
+        const prepared = await this.prepareForStorage();
+        return JSON.stringify(prepared);
     }
 
     /**
      * Restore a Saico instance from serialized data.
-     * Supports both raw msgs (from serialize/Redis) and compressed
-     * chat_history (from closeSession/Store).
      * @param {string|Object} data - Serialized data (JSON string or object)
      * @param {Object} opt - Options (functions, store, states, etc.)
-     * @returns {Saico}
+     * @returns {Promise<Saico>}
      */
-    static deserialize(data, opt = {}) {
+    static async deserialize(data, opt = {}) {
         const parsed = typeof data === 'string' ? JSON.parse(data) : data;
+        const msgsData = parsed.msgs;
 
         const instance = new Saico({
             id: parsed.id,
@@ -672,7 +684,7 @@ class Saico {
             userData: parsed.userData,
             sessionConfig: parsed.sessionConfig,
             isolate: parsed.isolate,
-            functions: opt.functions || parsed.context?.functions,
+            functions: opt.functions || msgsData?.functions,
             store: opt.store,
             redis: false, // No Redis proxy during deserialization
         });
@@ -681,48 +693,67 @@ class Saico {
 
         // Activate with restored state if taskId exists
         if (parsed.taskId) {
-            const ctx = parsed.context;
             instance.activate({
-                createQ: !!ctx,
+                createQ: !!msgsData,
                 taskId: parsed.taskId,
-                tag: ctx?.tag,
-                chat_history: ctx?.chat_history,
-                functions: opt.functions || ctx?.functions,
-                tool_digest: ctx?.tool_digest,
+                tag: msgsData?.tag,
+                chat_history: msgsData?.chat_history,
+                functions: opt.functions || msgsData?.functions,
+                tool_digest: msgsData?.tool_digest,
                 states: opt.states || [],
                 ...opt,
             });
 
-            // Restore raw msgs (from serialize/Redis) — takes priority over chat_history
-            if (ctx?.msgs && instance.context) {
-                instance.context._msgs = ctx.msgs;
-            }
+            // Decompress chat_history into _msgs
+            if (instance.msgs)
+                await instance.msgs.initHistory();
         }
 
         return instance;
     }
 
     /**
-     * Load a Saico instance from Store by id.
+     * Load a Saico instance from the registered backend by id.
      * @param {string} id - The Saico instance id
-     * @param {Object} opt - Options (store, functions, states, etc.)
+     * @param {Object} opt - Options (store: table name, backend, functions, states, etc.)
      * @returns {Promise<Saico|null>}
      */
     static async rehydrate(id, opt = {}) {
-        const store = opt.store || Store.instance;
-        if (!store)
-            throw new Error('No store available for rehydrate');
-        const data = await store.load(id);
+        const backend = opt.backend || Saico.getBackend();
+        if (!backend)
+            throw new Error('No backend registered. Call Saico.registerBackend() first.');
+        const table = opt.store;
+        if (!table)
+            throw new Error('No table specified. Pass opt.store.');
+        const data = await backend.get('id', id, table);
         if (!data) return null;
-        const instance = Saico.deserialize(data, opt);
-        // Decompress chat_history into _msgs if present
-        if (instance.context)
-            await instance.context.initHistory();
-        return instance;
+        return Saico.deserialize(data, opt);
     }
 }
 
-// [BACKEND] explanation text appended to context prompts
+// ---- Static backend registration ----
+
+Saico._backend = null;
+
+/**
+ * Register a storage backend at library level (once, outside instance context).
+ * @param {string} type - Backend type ('dynamodb')
+ * @param {Object} config - Backend config (passed to adapter constructor)
+ */
+Saico.registerBackend = function(type, config) {
+    if (type === 'dynamodb') {
+        const { DynamoDBAdapter } = require('./dynamo.js');
+        Saico._backend = new DynamoDBAdapter(config);
+    } else {
+        throw new Error('Unknown backend type: ' + type);
+    }
+};
+
+Saico.getBackend = function() {
+    return Saico._backend;
+};
+
+// [BACKEND] explanation text appended to msgs Q prompts
 Saico.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.';

package/store.js

@@ -4,46 +4,10 @@ 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() {
@@ -56,7 +20,6 @@ class Store {
 
     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;
@@ -67,97 +30,9 @@ class Store {
         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 };
+module.exports = { Store };