​
Advanced Memory System

The advanced memory system provides sophisticated memory management with short-term, long-term, entity, and user-specific storage, enhanced by quality scoring and optional graph database support.

​
Key Features

Separate short-term and long-term memory systems

4-metric quality assessment for stored memories

User, agent, and run-specific memory scoping

Automatic entity extraction and storage

Optional Neo4j/Memgraph for relationships

Quality-based filtering and relevance ranking

​
Quick Start

from praisonaiagents import Agent, PraisonAIAgents

# Single agent with memory
agent = Agent(
    name="Assistant",
    instructions="You are a helpful assistant with memory.",
    memory=True,
    user_id="user123"
)

# Multi-agent with shared memory
agents = PraisonAIAgents(
    agents=[agent1, agent2],
    memory=True,
    memory_config={
        "provider": "rag",
        "use_embedding": True
    }
)

​
Memory Tiers

​
Short-term Memory (STM)

Short-term memory is cleared between sessions and used for immediate context.

# Store temporary context
memory.store_short_term(
    text="User is asking about Python programming",
    user_id="user123",
    metadata={"context": "current_conversation"}
)

# Search recent context
context = memory.search_short_term(
    query="Python",
    user_id="user123",
    limit=5
)

​
Long-term Memory (LTM)

Long-term memory persists across sessions and stores important information.

# Store persistent knowledge
memory.store_long_term(
    text="User works as a data scientist at TechCorp",
    user_id="user123",
    quality=0.95,
    metadata={"type": "user_info", "category": "professional"}
)

# Retrieve with quality filter
memories = memory.search_long_term(
    query="user profession",
    user_id="user123",
    min_quality=0.8
)

​
Entity Memory

Entity memory stores information about specific people, places, or things.

# Store entity information
memory.store_entity(
    name="TechCorp",
    text="TechCorp is a leading AI company founded in 2020",
    entity_type="organization",
    metadata={"industry": "technology", "size": "large"}
)

# Search entity information
entity_info = memory.search_entity(
    name="TechCorp",
    query="company details"
)

​
User Memory

User memory stores personalised information and preferences.

# Store user preferences
memory.store_user_memory(
    user_id="user123",
    text="Prefers concise explanations with code examples",
    extra={"preference_type": "communication_style"}
)

# Retrieve user context
user_context = memory.search_user_memory(
    user_id="user123",
    query="preferences",
    limit=3
)

​
Configuration Options

​
RAG Configuration (Default)

memory_config = {
    "provider": "rag",
    "use_embedding": True,
    "short_db": ".praison/short_term.db",
    "long_db": ".praison/long_term.db",
    "entity_db": ".praison/entity.db",
    "rag_db_path": ".praison/chroma_db",
    "embedding_model": "text-embedding-3-small"
}

​
Mem0 Configuration

memory_config = {
    "provider": "mem0",
    "config": {
        "api_key": "your-mem0-api-key",
        "org_id": "your-org-id",
        "project_id": "your-project-id"
    }
}

​
Graph Memory Configuration

memory_config = {
    "provider": "mem0",
    "config": {
        "graph_store": {
            "provider": "neo4j",
            "config": {
                "url": "bolt://localhost:7687",
                "username": "neo4j",
                "password": "password"
            }
        },
        "vector_store": {
            "provider": "qdrant",
            "config": {
                "host": "localhost",
                "port": 6333
            }
        },
        "version": "v1.1"
    }
}

​
Quality Scoring System

​
Quality Metrics

Completeness

Measures how complete and comprehensive the information is

Relevance

Measures how relevant the information is to the context

Clarity

Measures how clear and understandable the information is

Accuracy

Measures the factual accuracy of the information

​
Quality Calculation

# Default weights
weights = {
    "completeness": 0.25,
    "relevance": 0.35,
    "clarity": 0.20,
    "accuracy": 0.20
}

# Overall quality = weighted average
quality = (
    completeness * weights["completeness"] +
    relevance * weights["relevance"] +
    clarity * weights["clarity"] +
    accuracy * weights["accuracy"]
)

​
Advanced Features

​
Context Building

Build comprehensive context for tasks:

# Automatically merge relevant memories
context = memory.build_context_for_task(
    task_descr="Write a Python tutorial",
    user_id="user123",
    additional="Focus on data science applications",
    max_items=5
)

# Context includes:
# - Relevant long-term memories
# - User preferences
# - Recent short-term context

​
Task Output Finalisation

Store task results with quality assessment:

from praisonaiagents.agent.task import TaskOutput

# Create task output
output = TaskOutput(
    raw="Tutorial content...",
    agent_name="Writer",
    task_description="Write Python tutorial"
)

# Finalise with quality scoring
memory.finalize_task_output(
    task_output=output,
    user_id="user123"
)

​
Memory Citations

Automatically cite memory sources:

# Memories include source information
result = memory.search_long_term("Python", user_id="user123")
# Returns: {
#     'text': 'Python is...',
#     'metadata': {'source': 'conversation_2024_01_15', ...}
# }

​
Performance Optimisation

# Batch store memories
memories = [
    ("Fact 1", 0.9),
    ("Fact 2", 0.85),
    ("Fact 3", 0.95)
]

for text, quality in memories:
    memory.store_long_term(
        text=text,
        quality=quality,
        user_id="user123"
    )

​
Complete Example

from praisonaiagents import Agent, Task, PraisonAIAgents
from praisonaiagents.memory import Memory

# Configure memory with quality scoring
memory_config = {
    "provider": "rag",
    "use_embedding": True,
    "embedding_model": "text-embedding-3-small"
}

# Create memory instance
memory = Memory(memory_config)

# Create assistant agent
assistant = Agent(
    name="Personal Assistant",
    instructions="""You are a personal assistant with perfect memory.
    Remember user preferences, important information, and context.
    Always use your memory to provide personalised responses.""",
    memory=memory,
    user_id="john_doe"
)

# Create task with memory integration
task = Task(
    description="Help me plan my day based on my preferences",
    agent=assistant,
    expected_output="Personalised daily schedule"
)

# Run the system
agents = PraisonAIAgents(
    agents=[assistant],
    tasks=[task],
    memory=memory
)

# Memory automatically:
# 1. Retrieves user preferences
# 2. Searches relevant past interactions
# 3. Builds context for the task
# 4. Stores the interaction with quality score
result = agents.start()

# Store user feedback as high-quality memory
memory.store_long_term(
    text="User preferred morning schedule with exercise first",
    user_id="john_doe",
    completeness=0.9,
    relevance=1.0,
    clarity=0.95,
    accuracy=1.0
)

​
Best Practices

  • Set minimum quality for critical information (0.8+)
  • Use lower thresholds for exploratory searches
  • Regular quality audits

  • Periodically review and clean old memories
  • Update quality scores as information ages
  • Deduplicate similar memories

  • Use user_id for personalisation
  • Use agent_id for agent-specific knowledge
  • Use run_id for session isolation

  • Enable embeddings for semantic search
  • Use quality filters to reduce search space
  • Implement caching for frequent queries

​
Next Steps

Integrate with document knowledge bases

Learn about stateful sessions