Building Agent Persistence in Astreus

Agents that forget everything after each restart provide limited value. Persistence enables agents to maintain conversation history and context across application restarts, creating continuous experiences for users.

The Astreus framework provides built-in database storage for agents. This allows them to recall previous interactions and build on past conversations.

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

JavaScriptCopy
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 enables conversation history storage. Every interaction with this agent is persisted to the database automatically.

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

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

SQLite works well for development and testing. For production, consider PostgreSQL or MySQL for better scalability.

Once memory is enabled, agents automatically remember previous interactions:

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

This information persists even after application restarts. The agent can recall it in future conversations without any additional code.

Retrieve previously created agents by name using findByName():

JavaScriptCopy
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. It responds as if the conversation never stopped.

Persistent agents in Astreus provide several important capabilities:

• Database Storage: Agent state survives application restarts
• Memory Integration: Conversation history is automatically maintained
• Named Access: Retrieve agents using unique identifiers
• Reusability: Define once, use across multiple sessions

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

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

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

The example repository demonstrates all persistence features with working code:

BashCopy
npm run dev

This starts an interactive demo where you can create agents, have conversations, restart the application, and see memory persistence in action.

Persistent agents enable several practical use cases:

• Customer support bots that remember user issues across sessions
• Personal assistants that learn user preferences over time
• Project management tools that track ongoing tasks and deadlines
• Educational tutors that adapt to student progress

Understand what gets persisted versus what stays in code:

Persisted to Database:

• Complete conversation history
• User interactions and responses
• Facts learned during conversations

Stays in Code:

• System prompts and instructions
• Model configuration (GPT-4, Claude, etc.)
• Tool definitions and capabilities

This separation allows you to update agent behavior without migrating database state. Change the system prompt in code, and the agent applies new instructions to existing conversation history.

Create multiple specialized agents with persistence:

JavaScriptCopy
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 maintains its own conversation history and specialization. They can work together while preserving independent context.

Astreus handles schema creation automatically. On first run, it creates tables for storing agent configurations and conversation history.

No manual database setup or migrations required. Just provide the connection URL and Astreus manages the rest.

For production deployments, consider these factors:

• Use PostgreSQL or MySQL instead of SQLite for better concurrent access
• Implement conversation pruning for long-running agents to manage costs
• Set up database backups to prevent data loss
• Monitor database size as conversation history grows

The fastest way to learn is to run the example:

BashCopy
git clone https://github.com/astreus-ai/agent-persistence
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.

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.