Building Agent Persistence in Astreus

Why Agent Persistence Matters

An agent that forgets everything every time it restarts is not worth much. Persistence lets an agent keep its conversation history and context across application restarts, so the user gets one continuous experience instead of a string of first meetings.

The Astreus framework gives agents built-in database storage. That is what lets them recall previous interactions and build on past conversations.

Creating Persistent Agents

Use the Agent.create() method to create agents that automatically save to the database:

JavaScript
Copy
import { Agent } from '@astreus-ai/astreus';

const agent = await Agent.create({
  name: 'ProjectAssistant',
  model: 'gpt-4o',
  memory: true,
  systemPrompt: 'You are a project management assistant.'
});

The memory: true flag turns on conversation history storage. From then on, every interaction with this agent is persisted to the database automatically.

Environment Setup

Configure your database connection before creating agents. Create a .env file with your credentials:

Bash
Copy
OPENAI_API_KEY=sk-your-openai-api-key-here
DB_URL=sqlite://./astreus.db

SQLite works well for development and testing. For production I would look at PostgreSQL or MySQL, which scale better.

Using Memory-Enabled Agents

Once memory is enabled, the agent remembers previous interactions on its own:

JavaScript
Copy
await agent.ask("Remember that our project deadline is March 15th");

That fact survives an application restart. The agent can recall it in future conversations without any extra code on your side.

Loading Saved Agents

Retrieve a previously created agent by name with findByName():

JavaScript
Copy
const loadedAgent = await Agent.findByName('ProjectAssistant');
const response = await loadedAgent?.ask("What is our project deadline?");
console.log(response); // Returns: March 15th

The agent loads its complete conversation history from the database and answers as if the conversation never stopped.

Key Features

Put together, this gives you four things. Agent state lives in database storage, so it survives application restarts. Memory is integrated, so conversation history is maintained without you managing it. Agents have named access, so you retrieve them by a unique identifier. And they are reusable: you define an agent once and use it across as many sessions as you like.

Installation Options

You can start with a complete example or add Astreus to an existing project:

Bash
Copy
# Clone complete example
git clone https://github.com/astreus-ai/astreus
cd agent-persistence
npm install

# Or install package only
npm install @astreus-ai/astreus

Running the Example

The example repository demonstrates all persistence features with working code:

Bash
Copy
npm run dev

This starts an interactive demo where you can create agents, have conversations, restart the application, and watch memory persistence do its job.

Real-World Applications

Anything that benefits from continuity is a good fit. A customer support bot can remember a user's issue from one session to the next. A personal assistant can learn the user's preferences over time. A project management tool can keep track of ongoing tasks and deadlines. An educational tutor can adapt to how a student is progressing.

Memory vs Configuration

It is worth being clear about what goes into the database and what stays in your code. The database holds the complete conversation history: the user's interactions, the agent's responses and the facts it learned along the way. The code holds everything that defines the agent's behavior: the system prompt and instructions, the model configuration (GPT-4, Claude and so on), and the tool definitions and capabilities.

This separation means you can change how an agent behaves without migrating any database state. Change the system prompt in code, and the agent applies the new instructions to its existing conversation history.

Multi-Agent Systems

Create multiple specialized agents with persistence:

JavaScript
Copy
const scheduler = await Agent.create({
  name: 'ScheduleAssistant',
  model: 'gpt-4o',
  memory: true,
  systemPrompt: 'You manage calendars and appointments.'
});

const researcher = await Agent.create({
  name: 'ResearchAssistant',
  model: 'gpt-4o',
  memory: true,
  systemPrompt: 'You help find and analyze information.'
});
more

Each agent keeps its own conversation history and its own specialization. They can work together while each one keeps an independent context.

Database Schema

Astreus creates the schema for you. On the first run it creates the tables for agent configurations and conversation history.

There is no manual database setup and no migrations to write. You provide the connection URL and Astreus handles the rest.

Production Considerations

A few things change when you go to production. Move from SQLite to PostgreSQL or MySQL for better concurrent access. Long-running agents accumulate a lot of history, so implement conversation pruning to keep costs under control, and monitor database size as that history grows. And set up database backups, because losing the database means losing every agent's memory.

Getting Started

The fastest way to learn is to run the example:

Bash
Copy
git clone https://github.com/astreus-ai/astreus
cd agent-persistence
npm install

Add your OpenAI API key to .env and run npm run dev. Create an agent, have a conversation, restart the app, and see persistence work.

Resources

Explore the complete implementation on GitHub: astreus-ai/agent-persistence

The repository includes working examples, configuration templates, and documentation for all persistence features.

This experiment is written for Astreus v0.5.37. Please ensure you are using a compatible version.