Building Agent Persistence in Astreus

## Why Agent Persistence Matters

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.

## Creating Persistent Agents

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

```javascript
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.

## Environment Setup

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

```bash
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.

## Using Memory-Enabled Agents

Once memory is enabled, agents automatically remember previous interactions:

```javascript
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.

## Loading Saved Agents

Retrieve previously created agents by name using `findByName()`:

```javascript
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.

## Key Features

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

## Installation Options

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

```bash
# 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
```

## Running the Example

The example repository demonstrates all persistence features with working code:

```bash
npm run dev
```

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

## Real-World Applications

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

## Memory vs Configuration

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.

## Multi-Agent Systems

Create multiple specialized agents with persistence:

```javascript
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.'
});
```

Each agent maintains its own conversation history and specialization. They can work together while preserving independent context.

## Database Schema

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.

## Production Considerations

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

## Getting Started

The fastest way to learn is to run the example:

```bash
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.

## Resources

Explore the complete implementation on GitHub: [astreus-ai/agent-persistence](https://github.com/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.