> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Database & Persistence

> Give Agents persistent memory across sessions

Give your Agents persistent memory so they remember conversations across restarts.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    Agent([Agent]) --> DB[(Database)]
    DB --> Session([Session])

    classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef tool fill:#189AB4,stroke:#7C90A0,color:#fff

    class Agent agent
    class DB,Session tool
    classDef agent fill:#8B0000,color:#fff
    classDef tool fill:#189AB4,color:#fff

```

## Quick Start

<Steps>
  <Step title="Simple Usage">
    ```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    import { Agent, db } from 'praisonai';

    const agent = new Agent({
      name: 'Support Agent',
      instructions: 'You are a helpful support agent.',
      db: db('sqlite:./conversations.db'),
      sessionId: 'user-123',
    });

    await agent.chat('My name is Alice');
    ```
  </Step>

  <Step title="With Configuration">
    ```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    const agent = new Agent({
      name: 'Analytics Agent',
      db: db('postgres://localhost/analytics'),
      sessionId: 'analysis-session',
    });
    ```
  </Step>
</Steps>

***

## Agent with Persistent Memory

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import { Agent, db } from 'praisonai';

// Create Agent with SQLite persistence
const agent = new Agent({
  name: 'Support Agent',
  instructions: 'You are a helpful support agent.',
  db: db('sqlite:./conversations.db'),
  sessionId: 'user-123'
});

// First conversation
await agent.chat('My name is Alice and I need help with billing');
// Agent remembers this

// Later (even after restart)
await agent.chat('What was my issue?');
// Agent recalls: "You mentioned billing issues, Alice"
```

## Agent with Different Databases

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import { Agent, db } from 'praisonai';

// SQLite (local file)
const localAgent = new Agent({
  instructions: 'You are helpful.',
  db: db('sqlite:./data.db')
});

// PostgreSQL (production)
const prodAgent = new Agent({
  instructions: 'You are helpful.',
  db: db('postgres://user:pass@localhost:5432/mydb')
});

// Redis (distributed)
const redisAgent = new Agent({
  instructions: 'You are helpful.',
  db: db('redis://localhost:6379')
});

// In-memory (testing)
const testAgent = new Agent({
  instructions: 'You are helpful.',
  db: db('memory:')
});
```

## Multi-Agent with Shared Database

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import { Agent, Agents, db } from 'praisonai';

// Shared database for all Agents
const sharedDb = db('sqlite:./team.db');

const researcher = new Agent({
  name: 'Researcher',
  instructions: 'Research topics thoroughly.',
  db: sharedDb,
  sessionId: 'project-alpha'
});

const writer = new Agent({
  name: 'Writer',
  instructions: 'Write based on research.',
  db: sharedDb,
  sessionId: 'project-alpha'
});

// Both Agents share conversation history
const agents = new AgentTeam([researcher, writer]);
await agents.start();
```

## Agent Session Management

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import { Agent, db } from 'praisonai';

const database = db('sqlite:./support.db');

// Create Agent for specific user session
function createAgentForUser(userId: string) {
  return new Agent({
    name: 'Support Agent',
    instructions: 'You provide personalized support.',
    db: database,
    sessionId: `user-${userId}`
  });
}

// Each user gets their own conversation history
const aliceAgent = createAgentForUser('alice');
const bobAgent = createAgentForUser('bob');

await aliceAgent.chat('I prefer dark mode');
await bobAgent.chat('I prefer light mode');

// Later
await aliceAgent.chat('What theme do I prefer?'); // "dark mode"
await bobAgent.chat('What theme do I prefer?');   // "light mode"
```

## Advanced: Direct Database Operations

For advanced use cases, access the database adapter directly:

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import { Agent, db } from 'praisonai';

const database = db('sqlite:./data.db');

// Get conversation history
const messages = await database.getMessages('session-123', 50);
console.log(`Found ${messages.length} messages`);

// Create Agent with existing session
const agent = new Agent({
  instructions: 'Continue the conversation.',
  db: database,
  sessionId: 'session-123'
});

// Agent has access to previous messages
await agent.chat('Summarize our conversation so far');
```

## Auto-Restore and Caching

Agents automatically restore conversation history and can cache responses:

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import { Agent, db } from 'praisonai';

const agent = new Agent({
  instructions: 'You are helpful.',
  db: db('sqlite:./data.db'),
  sessionId: 'user-123',
  
  // Auto-restore history on first chat (default: true)
  autoRestore: true,
  
  // Auto-persist messages (default: true)
  autoPersist: true,
  
  // Limit restored messages (default: 100)
  historyLimit: 50,
  
  // Enable response caching
  cache: true,
  cacheTTL: 3600  // 1 hour
});

// History is automatically restored on first chat
await agent.chat('Continue our conversation');

// Access history
console.log(agent.getHistory());

// Clear history
await agent.clearHistory();
```

## Database URL Formats

| Database   | URL Format                          |
| ---------- | ----------------------------------- |
| SQLite     | `sqlite:./path/to/file.db`          |
| PostgreSQL | `postgres://user:pass@host:5432/db` |
| Neon       | `neon://user:pass@host/db`          |
| Redis      | `redis://host:6379`                 |
| Upstash    | `upstash://user:pass@host`          |
| Memory     | `memory:`                           |

## Agent with Run Tracking

Track Agent runs for analytics:

```typescript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import { Agent, db } from 'praisonai';

const agent = new Agent({
  name: 'Analytics Agent',
  instructions: 'You analyze data.',
  db: db('postgres://localhost/analytics'),
  sessionId: 'analysis-session'
});

// Each chat creates a tracked run
const response = await agent.chat('Analyze sales trends');

// Access run information
console.log('Session:', agent.getSessionId());
console.log('Run:', agent.getRunId());
```

## Related

<CardGroup cols={2}>
  <Card title="Database CLI" icon="terminal" href="/docs/js/database-cli">
    CLI database commands
  </Card>

  <Card title="Memory" icon="database" href="/docs/js/memory">
    Agent memory systems
  </Card>

  <Card title="Sessions" icon="database" href="/docs/js/sessions">
    Conversation persistence
  </Card>
</CardGroup>