Building Agents with Memory in Astreus

Most AI agents treat every conversation as brand new. They forget everything the moment you close the tab. Astreus changes this by adding persistent memory to your agents.

With memory enabled, agents can remember past conversations, reference previous interactions, and maintain context across sessions. This makes them genuinely useful over time.

## Installation

First, install the Astreus package:

```bash
npm install @astreus-ai/astreus
```

Or clone the complete example from GitHub:

```bash
git clone https://github.com/astreus-ai/agent-with-memory
cd agent-with-memory
npm install
```

## Environment Setup

Create a `.env` file with your API key and database configuration:

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

Astreus stores conversation history in a database. Use SQLite for local development or PostgreSQL for production.

## Creating an Agent with Memory

Enabling memory is simple - just set the `memory` flag to `true`:

```javascript
import { Agent } from '@astreus-ai/astreus';

const agent = await Agent.create({
name: 'MemoryBot',
model: 'gpt-4o',
memory: true,
systemPrompt: 'You remember our conversation history.'
});
```

That's all it takes. Astreus automatically handles database setup, stores conversations, and retrieves relevant context for each interaction.

## How Memory Works

When you interact with a memory-enabled agent, Astreus follows a simple pattern:

1. The first interaction stores information in the database
2. Subsequent interactions retrieve that stored context
3. The agent uses the context to provide informed responses

Here's the pattern in action:

```javascript
// First interaction - stores information
const response1 = await agent.ask("My name is John and I like TypeScript");
console.log(response1);

// Second interaction - retrieves stored context
const response2 = await agent.ask("What's my name and what do I like?");
console.log(response2); // Should remember John and TypeScript
```

The agent automatically recalls that your name is John and you like TypeScript, even though this is a separate interaction.

## Key API Methods

Astreus provides two core methods for working with memory-enabled agents:

**Agent.create()** - Initializes an agent with configuration options. Pass `memory: true` to enable persistent memory.

**agent.ask()** - Submits a query to the agent. When memory is enabled, this automatically includes relevant conversation context.

## Running the Example

To run the complete example application:

```bash
npm run dev
```

This starts the agent and demonstrates the memory persistence pattern in action.

## Memory Persistence

The database is the source of truth for agent memory. When you restart your application or deploy a new version, the agent's memory remains intact. Previous conversations are automatically loaded when you create an agent with the same name.

This makes it easy to build agents that learn over time and maintain context across sessions.

## Complete Example Repository

The full implementation with additional examples is available on GitHub:

https://github.com/astreus-ai/agent-with-memory

Clone the repository to explore different configurations and see how memory changes what's possible with AI agents.

## What's Next

Memory transforms agents from stateless tools into assistants that remember you. Instead of repeating yourself every time, you're talking to someone who knows your context.

Explore the Astreus documentation for advanced features like fact extraction, multi-user isolation, and custom memory configurations.

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