Maintain state, context, and computational environments across agent sessions
Persistence ensures your agent workflows maintain continuity by preserving conversation history, computational state, and environmental configurations across requests and sessions.
The Persistence primitive is a foundational capability that enables agents to maintain state across multiple interactions. Unlike stateless systems that forget everything between requests, Agentbase’s persistence model allows agents to build on previous work, remember context, and preserve computational environments.Persistence operates at two distinct tiers:
Chat & Message History: Automatic, zero-cost persistence of all conversation messages
Computational Environment: On-demand persistence of files, packages, and system state
Zero-Cost Chat History
All messages persist automatically with no storage fees or configuration required
Smart Environment Management
Computational resources auto-pause when idle and resume instantly when needed
Session-Based Architecture
Isolated persistence scopes per session for security and multi-tenancy
Long-Term Continuity
Maintain workflows over hours, days, or weeks with automatic state preservation
Agentbase implements a sophisticated two-tier persistence model optimized for both cost and performance:Tier 1: Message History (Always Active)
Automatically persists all messages and responses
Zero storage cost
Instantly available for context
No configuration required
Unlimited retention
Tier 2: Computational Environment (On-Demand)
Created when agents need code execution, file operations, or web browsing
Persists files, installed packages, and system state
Auto-pauses after 5 minutes of inactivity
Resumes in 1-2 seconds when accessed again
Full environment preservation across sessions
Cost Optimization: Message history is completely free. Computational environments are only created when needed and automatically pause to minimize costs.
import { Agentbase } from '@agentbase/sdk';const agentbase = new Agentbase({ apiKey: process.env.AGENTBASE_API_KEY});// Request 1: Agent creates filesconst step1 = await agentbase.runAgent({ message: "Create a file called data.json with sample user data"});const sessionId = step1.session;console.log('Session ID:', sessionId);// Request 2: Agent accesses previous work (same session)const step2 = await agentbase.runAgent({ message: "Read data.json and count the number of users", session: sessionId // Reuse session - files persist});// Files created in step1 are still available in step2
// Day 1: Initialize projectconst init = await agentbase.runAgent({ message: "Create a Python web scraper project with proper structure"});const projectSession = init.session;// Store session ID for later useawait db.projects.create({ name: 'web-scraper', sessionId: projectSession, createdAt: new Date()});// Day 2: Continue development (hours or days later)const savedProject = await db.projects.findOne({ name: 'web-scraper' });const day2 = await agentbase.runAgent({ message: "Add error handling and retry logic to the scraper", session: savedProject.sessionId});// Day 3: Test and refineconst day3 = await agentbase.runAgent({ message: "Run the scraper and fix any errors", session: savedProject.sessionId});// All previous work persists across days
Some ephemeral state is intentionally not persisted:
Memory State: RAM contents are cleared on pause
Network Connections: Active connections are closed
Temporary Files: /tmp contents may be cleaned up
Running Processes: Processes terminate on pause (but can be restarted)
Important: While files and packages persist, active processes stop when the environment pauses. Design workflows to handle process restarts gracefully.
// Session 1: Project setupconst setup = await agentbase.runAgent({ message: "Create a Next.js project with TypeScript and Tailwind"});const devSession = setup.session;// Session 2: Add featuresawait agentbase.runAgent({ message: "Add authentication with NextAuth.js", session: devSession});// Session 3: Database integrationawait agentbase.runAgent({ message: "Set up Prisma with PostgreSQL", session: devSession});// Session 4: Testingawait agentbase.runAgent({ message: "Add unit tests with Jest", session: devSession});// All code, dependencies, and configurations persist
Data Science Pipeline
Copy
// Build complex data pipeline over multiple sessionsconst pipeline = await agentbase.runAgent({ message: "Set up Python environment with pandas, numpy, scikit-learn"});const pipelineSession = pipeline.session;// Add data processing stepsawait agentbase.runAgent({ message: "Create data preprocessing module with validation", session: pipelineSession});// Add ML modelawait agentbase.runAgent({ message: "Implement random forest classifier with cross-validation", session: pipelineSession});// All datasets, models, and code remain available
async function researchProject(topic: string) { // Week 1: Initial research const research = await agentbase.runAgent({ message: `Research ${topic} and create initial notes document` }); const researchSession = research.session; // Week 2: Deep dive into specific areas await agentbase.runAgent({ message: "Expand section on recent developments with citations", session: researchSession }); // Week 3: Add case studies await agentbase.runAgent({ message: "Find and document 5 real-world case studies", session: researchSession }); // Week 4: Compile final report await agentbase.runAgent({ message: "Compile all research into comprehensive report", session: researchSession }); // All notes, sources, and documents accumulated over weeks}
// Periodically export important artifactsasync function exportWorkflowArtifacts(sessionId: string) { const export_request = await agentbase.runAgent({ message: "Create a zip file of all important project files", session: sessionId }); // Download and store externally const artifacts = await downloadArtifacts(export_request); await s3.upload(`backups/${sessionId}.zip`, artifacts);}// Clear temporary data to optimize performanceasync function cleanupSession(sessionId: string) { await agentbase.runAgent({ message: "Delete all files in /tmp and clear build caches", session: sessionId });}
Persistence is session-scoped - each session maintains its own state:
Copy
// Session A: Isolated persistenceconst sessionA = await agentbase.runAgent({ message: "Create project A files"});// Session B: Separate isolated persistenceconst sessionB = await agentbase.runAgent({ message: "Create project B files"});// Each session has completely separate file systems and state
Combine persistence with versioning for rollback capabilities:
Copy
// Create versioned checkpointsawait agentbase.runAgent({ message: "Create git repository and commit current state as v1.0", session: projectSession});// Later, rollback if neededawait agentbase.runAgent({ message: "Revert to v1.0", session: projectSession});
Remember: Chat history persists automatically and free, while computational environments are created only when needed and persist for ongoing work. Always pass session IDs to maintain continuity.