Persistence - Agentbase Docs

Persistence ensures your agent workflows maintain continuity by preserving conversation history, computational state, and environmental configurations across requests and sessions.

Overview

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

How Persistence Works

Two-Tier Model

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.

Session-Scoped Persistence

Each session maintains its own isolated persistence scope:

Session Creation: New session starts with empty state
State Accumulation: Messages, files, and environment changes persist within session
Cross-Request Continuity: State remains available across all requests in the session
Automatic Cleanup: Sessions eventually expire after extended inactivity
Isolation: Complete separation between different sessions

Code Examples

Basic Persistence Pattern

import { Agentbase } from '@agentbase/sdk';

const agentbase = new Agentbase({
  apiKey: process.env.AGENTBASE_API_KEY
});

// Request 1: Agent creates files
const 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

from agentbase import Agentbase

agentbase = Agentbase(api_key=os.environ['AGENTBASE_API_KEY'])

# Request 1: Agent creates files
step1 = agentbase.run_agent(
    message="Create a file called data.json with sample user data"
)

session_id = step1.session
print(f"Session ID: {session_id}")

# Request 2: Agent accesses previous work (same session)
step2 = agentbase.run_agent(
    message="Read data.json and count the number of users",
    session=session_id  # Reuse session - files persist
)

# Files created in step1 are still available in step2

# Request 1: Create files
curl -X POST https://api.agentbase.sh \
  -H "Authorization: Bearer $AGENTBASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Create a file called data.json with sample user data"
  }'

# Response includes session ID
# { "session": "agent_session_abc123...", ... }

# Request 2: Access previous work
curl -X POST "https://api.agentbase.sh?session=agent_session_abc123" \
  -H "Authorization: Bearer $AGENTBASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Read data.json and count the number of users"
  }'

Long-Running Project Persistence

// Day 1: Initialize project
const init = await agentbase.runAgent({
  message: "Create a Python web scraper project with proper structure"
});

const projectSession = init.session;

// Store session ID for later use
await 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 refine
const day3 = await agentbase.runAgent({
  message: "Run the scraper and fix any errors",
  session: savedProject.sessionId
});

// All previous work persists across days

# Day 1: Initialize project
init = agentbase.run_agent(
    message="Create a Python web scraper project with proper structure"
)

project_session = init.session

# Store session ID for later use
db.projects.create({
    'name': 'web-scraper',
    'session_id': project_session,
    'created_at': datetime.now()
})

# Day 2: Continue development (hours or days later)
saved_project = db.projects.find_one({'name': 'web-scraper'})

day2 = agentbase.run_agent(
    message="Add error handling and retry logic to the scraper",
    session=saved_project.session_id
)

# Day 3: Test and refine
day3 = agentbase.run_agent(
    message="Run the scraper and fix any errors",
    session=saved_project.session_id
)

# All previous work persists across days

Multi-Step Workflow with Persistence

async function dataAnalysisWorkflow(dataUrl: string) {
  // Step 1: Download data
  const download = await agentbase.runAgent({
    message: `Download dataset from ${dataUrl} and save as data.csv`
  });

  const session = download.session;

  // Step 2: Clean data (uses downloaded file)
  const clean = await agentbase.runAgent({
    message: "Clean data.csv: remove duplicates, handle missing values",
    session
  });

  // Step 3: Analyze (uses cleaned data)
  const analyze = await agentbase.runAgent({
    message: "Perform statistical analysis and create visualizations",
    session
  });

  // Step 4: Generate report (uses all previous work)
  const report = await agentbase.runAgent({
    message: "Generate comprehensive analysis report with charts",
    session
  });

  return {
    sessionId: session,
    report: report.message
  };
}

// All intermediate files and results persist throughout workflow

async def data_analysis_workflow(data_url: str):
    # Step 1: Download data
    download = agentbase.run_agent(
        message=f"Download dataset from {data_url} and save as data.csv"
    )

    session = download.session

    # Step 2: Clean data (uses downloaded file)
    clean = agentbase.run_agent(
        message="Clean data.csv: remove duplicates, handle missing values",
        session=session
    )

    # Step 3: Analyze (uses cleaned data)
    analyze = agentbase.run_agent(
        message="Perform statistical analysis and create visualizations",
        session=session
    )

    # Step 4: Generate report (uses all previous work)
    report = agentbase.run_agent(
        message="Generate comprehensive analysis report with charts",
        session=session
    )

    return {
        'session_id': session,
        'report': report.message
    }

# All intermediate files and results persist throughout workflow

What Persists

Message History

Everything in the conversation persists automatically:

User Messages: All requests sent to the agent
Agent Responses: Complete responses including reasoning
Tool Calls: Record of all tools used and their inputs
Tool Results: Outputs from tool executions
Timestamps: When each interaction occurred
Metadata: Session information, modes used, cost tracking

Computational Environment

When a computational environment is created, these persist:

Files: All files created, modified, or downloaded
Installed Packages: npm, pip, apt packages remain installed
Environment Variables: Custom environment configurations
Working Directory: Current directory state and structure
Process State: Background processes and their status
System Modifications: Configuration changes and system state

What Doesn’t Persist

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.

Use Cases

1. Iterative Development Projects

Build software projects across multiple sessions:

Web Application Development

// Session 1: Project setup
const setup = await agentbase.runAgent({
  message: "Create a Next.js project with TypeScript and Tailwind"
});

const devSession = setup.session;

// Session 2: Add features
await agentbase.runAgent({
  message: "Add authentication with NextAuth.js",
  session: devSession
});

// Session 3: Database integration
await agentbase.runAgent({
  message: "Set up Prisma with PostgreSQL",
  session: devSession
});

// Session 4: Testing
await agentbase.runAgent({
  message: "Add unit tests with Jest",
  session: devSession
});

// All code, dependencies, and configurations persist

Data Science Pipeline

// Build complex data pipeline over multiple sessions
const pipeline = await agentbase.runAgent({
  message: "Set up Python environment with pandas, numpy, scikit-learn"
});

const pipelineSession = pipeline.session;

// Add data processing steps
await agentbase.runAgent({
  message: "Create data preprocessing module with validation",
  session: pipelineSession
});

// Add ML model
await agentbase.runAgent({
  message: "Implement random forest classifier with cross-validation",
  session: pipelineSession
});

// All datasets, models, and code remain available

2. Customer Support Conversations

Maintain context throughout support interactions:

async function handleSupportTicket(customerId: string, initialMessage: string) {
  // Create support session
  const initial = await agentbase.runAgent({
    message: `Customer ${customerId}: ${initialMessage}`,
    system: "You are a customer support specialist.",
    mcpServers: [{
      serverName: 'customer-api',
      serverUrl: 'https://api.company.com/mcp'
    }]
  });

  const supportSession = initial.session;

  // Store session with ticket
  await db.tickets.create({
    customerId,
    sessionId: supportSession,
    status: 'open',
    createdAt: new Date()
  });

  return supportSession;
}

// Hours later, customer responds
async function continueSupport(ticketId: string, message: string) {
  const ticket = await db.tickets.findById(ticketId);

  // Continue in same session - agent remembers everything
  return await agentbase.runAgent({
    message: `Customer: ${message}`,
    session: ticket.sessionId
  });
}

3. Research and Analysis

Accumulate research over extended periods:

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
}

4. Scheduled Jobs and Automation

Maintain state across scheduled executions:

// Daily report generation with historical context
async function generateDailyReport() {
  const reportConfig = await db.config.findOne({ name: 'daily-report' });

  let sessionId = reportConfig?.sessionId;

  if (!sessionId) {
    // First run: initialize
    const init = await agentbase.runAgent({
      message: "Initialize daily reporting system, create templates"
    });
    sessionId = init.session;

    await db.config.create({
      name: 'daily-report',
      sessionId
    });
  }

  // Generate today's report with access to all previous reports
  const report = await agentbase.runAgent({
    message: "Generate today's report and compare to previous days",
    session: sessionId
  });

  return report;
}

// Each day's report has context of all previous reports

Best Practices

Session Management

Store Session IDs Securely

// Good: Store in database with proper access control
interface WorkflowRecord {
  id: string;
  userId: string;
  sessionId: string;
  workflowType: string;
  createdAt: Date;
  lastAccess: Date;
}

async function createWorkflow(userId: string, type: string) {
  const result = await agentbase.runAgent({
    message: `Initialize ${type} workflow`
  });

  await db.workflows.create({
    id: generateId(),
    userId,
    sessionId: result.session,
    workflowType: type,
    createdAt: new Date(),
    lastAccess: new Date()
  });
}

// Avoid: Storing in client-side storage without encryption

Track Session Activity

async function updateSessionActivity(sessionId: string) {
  await db.workflows.updateOne(
    { sessionId },
    {
      $set: { lastAccess: new Date() },
      $inc: { requestCount: 1 }
    }
  );
}

// Monitor for stale sessions
async function cleanupStaleSessions() {
  const threshold = new Date();
  threshold.setDate(threshold.getDate() - 30);

  const staleSessions = await db.workflows.find({
    lastAccess: { $lt: threshold }
  });

  for (const session of staleSessions) {
    await archiveAndDelete(session);
  }
}

Use Descriptive Session Metadata

// Tag sessions with meaningful metadata
await db.sessions.create({
  sessionId: result.session,
  tags: ['data-analysis', 'customer-insights', 'q1-2025'],
  description: 'Customer behavior analysis for Q1 2025',
  owner: userId,
  team: 'analytics'
});

// Easy retrieval and organization
const analyticsSessions = await db.sessions.find({
  tags: { $in: ['data-analysis'] },
  team: 'analytics'
});

Performance Optimization

Keep Active Sessions Warm

Make requests within 5 minutes to avoid auto-pause overhead

Separate Independent Workflows

Use different sessions for unrelated work to keep context focused

Clean Up Large Files

Remove unnecessary files to reduce storage and improve performance

Periodic Checkpoints

Save important state externally for critical long-running workflows

Data Management

// Periodically export important artifacts
async 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 performance
async function cleanupSession(sessionId: string) {
  await agentbase.runAgent({
    message: "Delete all files in /tmp and clear build caches",
    session: sessionId
  });
}

Integration with Other Primitives

With Sessions

Persistence is session-scoped - each session maintains its own state:

// Session A: Isolated persistence
const sessionA = await agentbase.runAgent({
  message: "Create project A files"
});

// Session B: Separate isolated persistence
const sessionB = await agentbase.runAgent({
  message: "Create project B files"
});

// Each session has completely separate file systems and state

Learn more: Sessions Primitive

With States

States represent the current snapshot of persisted data:

// State evolves as persistence accumulates
const initial = await agentbase.runAgent({
  message: "Create config.json"
});
// State: config.json exists

const updated = await agentbase.runAgent({
  message: "Add database settings to config.json",
  session: initial.session
});
// State: config.json exists with database settings

Learn more: States Primitive

With Versioning

Combine persistence with versioning for rollback capabilities:

// Create versioned checkpoints
await agentbase.runAgent({
  message: "Create git repository and commit current state as v1.0",
  session: projectSession
});

// Later, rollback if needed
await agentbase.runAgent({
  message: "Revert to v1.0",
  session: projectSession
});

Learn more: Versioning Primitive

Performance Considerations

Environment Startup Times

New Environment: 2-5 seconds to create from scratch
Warm Environment: Instant access if active (< 5 min since last request)
Resume from Pause: 1-2 seconds to wake up paused environment

Storage Impact

Message history is free and unlimited. For computational environments:

Small Projects (< 100 MB): Negligible impact
Medium Projects (100 MB - 1 GB): Normal performance
Large Projects (> 1 GB): Consider periodic cleanup

Optimization Strategies

// Keep sessions warm for interactive workflows
setInterval(async () => {
  await agentbase.runAgent({
    message: "status",
    session: activeSessionId
  });
}, 4 * 60 * 1000); // Every 4 minutes

// Lazy load for batch workflows
async function batchProcess(items: string[]) {
  let sessionId: string | undefined;

  for (const item of items) {
    const result = await agentbase.runAgent({
      message: `Process ${item}`,
      session: sessionId
    });

    sessionId = result.session; // Reuse session for efficiency
  }
}

Troubleshooting

Files Not Persisting

Problem: Files created in one request don’t appear in the nextSolutions:

Verify you’re passing the same session ID
Check that files are created in persistent directories (not /tmp)
Ensure session hasn’t expired

// Verify session continuity
const step1 = await agentbase.runAgent({
  message: "Create file.txt"
});

console.log('Session:', step1.session);

const step2 = await agentbase.runAgent({
  message: "Read file.txt",
  session: step1.session  // Must match!
});

Session Not Found Error

Problem: Error when trying to use a session IDSolutions:

Session may have expired after extended inactivity
Session ID may be incorrect or corrupted
Start a new session and restore state if needed

try {
  await agentbase.runAgent({
    message: "Continue work",
    session: maybeExpiredSession
  });
} catch (error) {
  if (error.code === 'SESSION_NOT_FOUND') {
    // Start new session
    const fresh = await agentbase.runAgent({
      message: "Restore project from backup"
    });

    await updateStoredSession(fresh.session);
  }
}

Slow Environment Resume

Problem: Noticeable delay when resuming paused environmentSolutions:

This is expected behavior (1-2 second resume time)
Keep environment warm with periodic requests if low latency is critical
Consider if you really need environment persistence for simple tasks

// For latency-critical workflows, keep warm
const keepWarm = setInterval(async () => {
  await agentbase.runAgent({
    message: "ping",
    session: criticalSession
  });
}, 4 * 60 * 1000);

// Stop when done
clearInterval(keepWarm);

Sessions

Session containers that enable persistence

States

Current snapshot of persisted data

Versioning

Version control for persisted state

Background Tasks

Long-running tasks with persistence

Additional Resources

API Reference

Session and persistence parameters

Agent Computer

Environment capabilities and tools

Use Cases

Real-world persistence patterns

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.

​Overview

Zero-Cost Chat History

Smart Environment Management

Session-Based Architecture

Long-Term Continuity

​How Persistence Works

​Two-Tier Model

​Session-Scoped Persistence

​Code Examples

​Basic Persistence Pattern

​Long-Running Project Persistence

​Multi-Step Workflow with Persistence

​What Persists

​Message History

​Computational Environment

​What Doesn’t Persist

​Use Cases

​1. Iterative Development Projects

​2. Customer Support Conversations

​3. Research and Analysis

​4. Scheduled Jobs and Automation

​Best Practices

​Session Management

​Performance Optimization

Keep Active Sessions Warm

Separate Independent Workflows

Clean Up Large Files

Periodic Checkpoints

​Data Management

​Integration with Other Primitives

​With Sessions

​With States

​With Versioning

​Performance Considerations

​Environment Startup Times

​Storage Impact

​Optimization Strategies

​Troubleshooting

​Related Primitives

Sessions

States

Versioning

Background Tasks

​Additional Resources

API Reference

Agent Computer

Use Cases

Overview

How Persistence Works

Two-Tier Model

Session-Scoped Persistence

Code Examples

Basic Persistence Pattern

Long-Running Project Persistence

Multi-Step Workflow with Persistence

What Persists

Message History

Computational Environment

What Doesn’t Persist

Use Cases

1. Iterative Development Projects

2. Customer Support Conversations

3. Research and Analysis

4. Scheduled Jobs and Automation

Best Practices

Session Management

Performance Optimization

Data Management

Integration with Other Primitives

With Sessions

With States

With Versioning

Performance Considerations

Environment Startup Times

Storage Impact

Optimization Strategies

Troubleshooting

Related Primitives

Additional Resources