Skip to main content
Configure agents to learn from interactions, capturing patterns, preferences, and insights to improve future responses.

​
Quick Start

1

Simple Enable

Enable learning with default settings:
from praisonaiagents import Agent

agent = Agent(
    name="Learning Agent",
    instructions="You are a helpful assistant",
    learn=True
)
2

With Configuration

Enable specific learning capabilities:
from praisonaiagents import Agent, LearnConfig

agent = Agent(
    name="Learning Agent",
    instructions="You are a helpful assistant",
    learn=LearnConfig(
        persona=True,      # User preferences
        insights=True,     # Observations
        patterns=True,     # Reusable knowledge
        scope="private"
    )
)
3

With Bounded Retention

Cap store size and expire stale entries automatically:
from praisonaiagents import Agent, LearnConfig

agent = Agent(
    name="Assistant",
    instructions="Adapts to user preferences",
    learn=LearnConfig(
        persona=True,
        max_entries=1000,        # Cap per store
        retention_days=90,       # Drop stale entries after 90 days
    ),
)

​
Configuration Options

from praisonaiagents import LearnConfig

config = LearnConfig(
    # Learning capabilities
    persona=True,           # User preferences and profile
    insights=True,          # Observations and learnings
    thread=True,            # Session/conversation context
    patterns=False,         # Reusable knowledge patterns
    decisions=False,        # Decision logging
    feedback=False,         # Outcome signals
    improvements=False,     # Self-improvement proposals
    
    # Scope configuration
    scope="private",
    
    # Storage configuration
    store_path=None,        # Custom storage path
    backend="file",         # Storage backend (file, sqlite, redis, mongodb)
    
    # Retention (0 = unbounded, existing data unaffected)
    max_entries=0,          # Max entries per store (0 = no cap)
    retention_days=0,       # Days until stale (0 = never expires)
    
    # Learning mode
    mode="disabled",        # How to extract learnings automatically
)
ParameterTypeDefaultDescription
personaboolTrueLearn user preferences and profile
insightsboolTrueCapture observations and learnings
threadboolTrueMaintain session/conversation context
patternsboolFalseStore reusable knowledge patterns
decisionsboolFalseLog decision-making process
feedbackboolFalseCapture outcome signals
improvementsboolFalseStore self-improvement proposals
scopestr | LearnScope"private"Visibility scope (private, shared)
store_pathstr | NoneNoneCustom path for learning storage
backendstr | LearnBackend"file"Storage backend (file, sqlite, redis, mongodb)
modestr | LearnMode"disabled"Learning extraction mode (disabled, agentic)
max_entriesint0Maximum entries per store. 0 = unbounded (default, existing behaviour unchanged). When the cap is exceeded, the store prunes least-used / oldest entries on the next write or prune() call. Evicted entries are archived to a .archive.json sidecar.
retention_daysint0Soft expiry in days. 0 = no time-based pruning (default). Entries older than this with no recent use become eligible for pruning.
Both max_entries and retention_days default to 0 (unbounded). Existing agents are unaffected unless you explicitly set these values. There is no silent eviction — entries are only pruned when a cap is set.

​
Bounded Retention

Retention limits keep long-running agents healthy without losing data — evicted entries are saved to a .archive.json sidecar file next to the store, so nothing is permanently lost.

​
How pruning works

TriggerWhen
On writeAutomatically when max_entries > 0 and the cap is exceeded
On prune() callManually, for one-off cleanup
Entries are scored by least used first, then oldest — the most valuable, recently accessed learnings are always kept. The archive sidecar is written to the same directory as the store file, named <store>.archive.json (e.g., persona.archive.json).

​
Manual pruning

from praisonaiagents import Agent, LearnConfig

agent = Agent(
    learn=LearnConfig(max_entries=1000, retention_days=90)
)

# Run across all configured stores; returns evicted count per store
evicted = agent.memory.learn().prune()
print(f"Pruned: {evicted}")
# e.g. {"persona": 12, "insights": 3}
prune() is also called automatically on every write when limits are set. Manual calls are only needed for one-off cleanup of a long-running agent.

​
Common Patterns

​
Pattern 1: Full Learning Profile

from praisonaiagents import Agent, LearnConfig

agent = Agent(
    name="Full Learning Agent",
    instructions="You are a personalized assistant",
    learn=LearnConfig(
        persona=True,
        insights=True,
        thread=True,
        patterns=True,
        decisions=True,
        feedback=True,
        improvements=True
    )
)

​
Pattern 2: Shared Team Learning

from praisonaiagents import Agent, LearnConfig

agent = Agent(
    name="Team Agent",
    instructions="Share learnings with team",
    learn=LearnConfig(
        patterns=True,
        insights=True,
        scope="shared"
    )
)

​
Pattern 3: Compliance-Ready Agent

from praisonaiagents import Agent, LearnConfig

agent = Agent(
    name="Compliance Agent",
    instructions="Process requests with data retention limits",
    learn=LearnConfig(
        persona=True,
        insights=True,
        max_entries=500,
        retention_days=30,   # Purge entries older than 30 days
    )
)

​
Best Practices

Both max_entries and retention_days default to 0 (unbounded). Unless your agent runs for months or handles compliance requirements, the defaults are fine. Stores only grow with actual interactions.
For agents that run continuously and interact with many users, set max_entries=1000 to keep store files small and search fast. The archive sidecar preserves evicted entries if you need to audit them.
For compliance requirements (e.g., GDPR, data minimization), set retention_days to automatically make old entries eligible for pruning. Pair with max_entries for proactive pruning on every write.
Keep learnings private unless you explicitly need shared team knowledge. This protects user data.
Evicted entries are never hard-deleted. Find the .archive.json sidecar (same directory as the store file) to recover them. The archive is append-only JSON.

Bounded Learning

User-flow guide: retention caps, archival, and the prune API

Agent Learn

Learn about the Agent Learn concept