<!-- source: https://deepwiki.com/MervinPraison/PraisonAI/4.1-memory-management -->

# Memory Management

- api.md
- src/praisonai-agents/praisonaiagents/agents/agents.py

This document covers PraisonAI's memory system for persistent agent state and knowledge storage. Memory Management provides four memory types (short-term, long-term, entity, episodic) with multiple storage backends. For retrieval-augmented generation (RAG) and document-based knowledge, see [Knowledge Management](/MervinPraison/PraisonAI/4.2-knowledge-management). For session persistence, see [Context Management](/MervinPraison/PraisonAI/4.4-context-management).

The memory system operates at three levels: individual agents, shared across multi-agent orchestrations, and task-specific configurations. All memory operations are optional and have zero overhead when disabled.

## Memory Architecture

PraisonAI implements a multi-tier memory system with pluggable storage backends and automatic quality-based promotion from short-term to long-term storage.

```

```

**Sources:** [src/praisonai-agents/praisonaiagents/memory/memory.py126-186](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/memory/memory.py#L126-L186)

### Memory Class Implementation

The `Memory` class at [src/praisonai-agents/praisonaiagents/memory/memory.py126](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/memory/memory.py#L126-L126) provides a unified interface across all backends:

**Sources:** [src/praisonai-agents/praisonaiagents/memory/memory.py188-248](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/memory/memory.py#L188-L248) [README.md656-709](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L656-L709)

## Configuration System

Memory is configured via dictionaries passed to the `memory` parameter. The system uses lazy loading to avoid import overhead when memory is disabled.

### Basic Configuration

```

```

### Advanced Configuration Structure

```

```

**Sources:** [src/praisonai-agents/praisonaiagents/memory/memory.py137-186](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/memory/memory.py#L137-L186) [README.md656-700](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L656-L700)

### MongoDB Configuration

MongoDB requires additional connection parameters for production deployments:

```

```

**Sources:** [src/praisonai-agents/praisonaiagents/memory/memory.py137-186](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/memory/memory.py#L137-L186)

### Mem0 with Graph Memory

Mem0 supports optional graph stores for relationship-aware memory:

```

```

When graph memory is enabled, relationships between entities are automatically tracked.

**Sources:** [src/praisonai-agents/praisonaiagents/memory/memory.py306-349](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/memory/memory.py#L306-L349)

## Memory Types and Operations

```

```

**Sources:** [src/praisonai-agents/praisonaiagents/memory/memory.py273-523](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/memory/memory.py#L273-L523)

### Short-Term Memory (STM)

Short-term memory stores ephemeral context with automatic expiration. It implements a rolling buffer with quality scoring to determine promotion to long-term storage.

**Implementation:** [src/praisonai-agents/praisonaiagents/memory/memory.py274-289](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/memory/memory.py#L274-L289)

**Usage:**

```

```

**Sources:** [src/praisonai-agents/praisonaiagents/memory/memory.py554-621](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/memory/memory.py#L554-L621)

### Long-Term Memory (LTM)

Long-term memory persists important facts indefinitely. Items are promoted from STM based on quality scores or stored directly.

**Implementation:** [src/praisonai-agents/praisonaiagents/memory/memory.py290-304](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/memory/memory.py#L290-L304)

**Usage:**

```

```

**Sources:** [src/praisonai-agents/praisonaiagents/memory/memory.py623-686](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/memory/memory.py#L623-L686)

### Entity Memory

Entity memory stores structured information about people, places, organizations with typed attributes.

**Schema:**

- entity_name : Primary identifier
- entity_type : person, organization, place, etc.
- attributes : Key-value pairs (JSON)
- metadata : Additional context

**Usage:**

```

```

**Sources:** [src/praisonai-agents/praisonaiagents/memory/memory.py688-753](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/memory/memory.py#L688-L753)

### Episodic Memory

Episodic memory tracks interaction history with timestamps for temporal context.

**Schema:**

- timestamp : ISO datetime
- interaction : Conversation text
- metadata : Agent, task, context

**Usage:**

```

```

**Sources:** [src/praisonai-agents/praisonaiagents/memory/memory.py755-819](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/memory/memory.py#L755-L819)

## Storage Backends

### File-Based Storage

Default backend requiring zero dependencies. Stores each memory type in separate JSON files.

**Files:**

- .praison/short_term.json
- .praison/long_term.json
- .praison/entities.json
- .praison/episodic.json

**Configuration:**

```

```

**Sources:** [src/praisonai-agents/praisonaiagents/memory/memory.py188-248](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/memory/memory.py#L188-L248)

### SQLite Storage

Built-in Python backend with indexed queries for better performance.

**Tables:**

- short_mem : Short-term memory
- long_mem : Long-term memory
- Custom tables for entity/episodic

**Initialization:** [src/praisonai-agents/praisonaiagents/memory/memory.py274-304](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/memory/memory.py#L274-L304)

```

```

**Sources:** [src/praisonai-agents/praisonaiagents/memory/memory.py274-304](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/memory/memory.py#L274-L304)

### ChromaDB Storage

Vector database for semantic search using embeddings.

**Implementation:** [src/praisonai-agents/praisonaiagents/memory/memory.py351-384](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/memory/memory.py#L351-L384)

**Collections:**

- memory_store : Unified collection with metadata filtering

**Configuration:**

```

```

**Embedding Models:**
The system automatically determines embedding dimensions based on model name via [src/praisonai-agents/praisonaiagents/memory/memory.py225-227](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/memory/memory.py#L225-L227):

**Sources:** [src/praisonai-agents/praisonaiagents/memory/memory.py351-384](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/memory/memory.py#L351-L384) [src/praisonai-agents/praisonaiagents/memory/memory.py225-227](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/memory/memory.py#L225-L227)

### Mem0 Storage

Cloud or self-hosted agent memory service with optional graph support.

**Implementation:** [src/praisonai-agents/praisonaiagents/memory/memory.py306-349](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/memory/memory.py#L306-L349)

**Features:**

- Traditional memory client (cloud API)
- Graph memory (Neo4j/Memgraph integration)
- Automatic relationship extraction

**Configuration:**

```

```

**Graph Memory:** When enabled ([src/praisonai-agents/praisonaiagents/memory/memory.py314-339](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/memory/memory.py#L314-L339)), Mem0 automatically extracts and stores relationships between entities for relationship-aware retrieval.

**Sources:** [src/praisonai-agents/praisonaiagents/memory/memory.py306-349](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/memory/memory.py#L306-L349)

### MongoDB Storage

Production-ready document store with optional Atlas Vector Search.

**Implementation:** [src/praisonai-agents/praisonaiagents/memory/memory.py386-422](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/memory/memory.py#L386-L422)

**Collections:**

- short_term_memory
- long_term_memory
- entity_memory
- user_memory

**Indexes:** [src/praisonai-agents/praisonaiagents/memory/memory.py424-461](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/memory/memory.py#L424-L461)

- Text search indexes on content fields
- Compound indexes for filtering (created_at, quality)
- User-specific indexes
- Vector search indexes (Atlas only)

**Atlas Vector Search:** Requires index creation with dimension specification [src/praisonai-agents/praisonaiagents/memory/memory.py448-461](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/memory/memory.py#L448-L461):

```

```

**Sources:** [src/praisonai-agents/praisonaiagents/memory/memory.py386-461](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/memory/memory.py#L386-L461)

## Integration with Agents

```

```

**Sources:** [src/praisonai-agents/praisonaiagents/agents/agents.py472-513](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L472-L513)

### Agent-Level Memory

Memory at the agent level creates an isolated memory instance per agent with user-based separation.

**Configuration:**

```

```

**Implementation:** Memory is automatically injected into conversation context via [src/praisonai-agents/praisonaiagents/agents/agents.py385-389](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L385-L389)

**Sources:** [README.md656-672](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L656-L672) [src/praisonai-agents/praisonaiagents/agents/agents.py385-389](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L385-L389)

### Shared Memory Across Agents

Multi-agent orchestrations can share a single memory instance for cross-agent knowledge transfer.

**Configuration:**

```

```

**Implementation:** [src/praisonai-agents/praisonaiagents/agents/agents.py472-513](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L472-L513)

The shared memory instance is created once and propagated to all tasks:

1. Initialize agents.shared_memory from config
2. Assign to each task: task.memory = self.shared_memory
3. All agents access the same memory store

**Sources:** [src/praisonai-agents/praisonaiagents/agents/agents.py472-513](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L472-L513)

### Task-Level Memory

Individual tasks can override agent memory configuration for task-specific storage.

**Configuration:**

```

```

**Priority:** Task memory config takes precedence over agent memory config.

**Sources:** [src/praisonai-agents/praisonaiagents/task/task.py40-61](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/task/task.py#L40-L61)

## Advanced Features

### Session Management

Sessions provide save/resume capabilities for conversation history and memory state.

**Operations:**

**Usage:**

```

```

**Storage:** Sessions are stored in `.praison/sessions/` directory with JSON format.

**Sources:** [README.md686-689](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L686-L689)

### Context Compression

Context compression reduces memory size while preserving important information using LLM summarization.

**Method:** `memory.compress(llm_func, max_items)`

**Implementation:**

1. Retrieve all short-term memories
2. Use LLM to summarize and identify key facts
3. Store compressed facts in long-term memory
4. Clear short-term buffer

**Usage:**

```

```

**Sources:** [README.md690-691](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L690-L691)

### Checkpointing

Checkpoints provide version control for memory state with optional file backup.

**Operations:**

**Usage:**

```

```

**Storage:** Checkpoints are stored in `.praison/checkpoints/` with memory dump and optional file copies.

**Sources:** [README.md693-695](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L693-L695)

### Auto-Generated Memories

The `AutoMemory` class automatically extracts and stores structured memories from conversations.

**Implementation:**

```

```

**Extraction Process:**

1. Parse conversation text
2. Identify entities and facts
3. Categorize by type (person, preference, etc.)
4. Store in appropriate memory type

**Sources:** [README.md760-772](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L760-L772)

### Slash Commands

CLI-friendly commands for memory operations:

**Implementation:** [README.md697-700](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L697-L700)

**Sources:** [README.md697-700](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/README.md?plain=1#L697-L700)

## Memory Operations

### Store Operations

```

```

**Store Methods:**

```

```

**Sources:** [src/praisonai-agents/praisonaiagents/memory/memory.py554-819](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/memory/memory.py#L554-L819)

### Search Operations

Search operations support both exact matching and semantic search depending on the backend.

```

```

**Search Methods:**

```

```

**Result Format:**

```

```

**Sources:** [src/praisonai-agents/praisonaiagents/memory/memory.py821-904](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/memory/memory.py#L821-L904)

### Context Building

Context building assembles relevant memories for LLM prompts.

**Method:** `memory.build_context(query, user_id, max_items)`

**Process:**

1. Search for relevant memories
2. Rank by relevance score
3. Limit to max_items
4. Format as context string

**Implementation:**

```

```

**Automatic Context Injection:** Memory context is automatically injected into agent prompts when memory is enabled via [src/praisonai-agents/praisonaiagents/agents/agents.py630-647](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L630-L647)

**Sources:** [src/praisonai-agents/praisonaiagents/memory/memory.py906-1004](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/memory/memory.py#L906-L1004)

**Key Files:**

- src/praisonai-agents/praisonaiagents/memory/memory.py - Core Memory class
- src/praisonai-agents/praisonaiagents/agents/agents.py 472-513 - Shared memory integration
- src/praisonai-agents/praisonaiagents/task/task.py 40-61 - Task-level memory
- README.md 656-772 - Usage examples and features
