Memory Overview
AiQarus agents have access to a 5-level hierarchical memory system that enables learning, context retention, and knowledge sharing.
Memory Hierarchy
┌─────────────────────────────────────────────────────────────┐
│ Organizational Memory │
│ (Shared across all agents in org) │
├─────────────────────────────────────────────────────────────┤
│ Semantic Memory │
│ (Long-term facts and knowledge) │
├─────────────────────────────────────────────────────────────┤
│ Episodic Memory │
│ (Past run experiences and outcomes) │
├─────────────────────────────────────────────────────────────┤
│ Short-term Memory │
│ (Cross-run temporary storage) │
├─────────────────────────────────────────────────────────────┤
│ Working Memory │
│ (Within-run context) │
└─────────────────────────────────────────────────────────────┘The Five Levels
1. Working Memory
Scope: Single run Lifespan: Until run completes Use Case: Current task context
Working memory holds information needed for the current execution:
- Input data
- Intermediate results
- Current step context
- Accumulated observations
{
"level": "working",
"run_id": "run_123",
"data": {
"employee": "Sarah Chen",
"access_list": ["aws", "github", "slack"],
"risk_score": 85,
"completed_actions": ["gathered_info", "assessed_risk"]
}
}2. Short-term Memory
Scope: Single agent Lifespan: Hours to days (configurable) Use Case: Recent task history
Short-term memory persists across runs for a limited time:
- Recently processed items
- Temporary caches
- Session continuity
{
"level": "short_term",
"agent_id": "agent_456",
"ttl_hours": 24,
"data": {
"recent_offboardings": ["john_doe", "jane_smith"],
"pending_approvals": 3
}
}3. Episodic Memory
Scope: Single agent Lifespan: Permanent Use Case: Past run experiences
Episodic memory stores experiences and lessons from past runs:
- Successful strategies
- Encountered problems
- Learned patterns
{
"level": "episodic",
"agent_id": "agent_456",
"episodes": [
{
"run_id": "run_100",
"context": "engineering_offboarding",
"lesson": "Check for personal SSH keys in production servers",
"importance": 0.9
},
{
"run_id": "run_95",
"context": "executive_offboarding",
"lesson": "Verify delegation of authority before access removal",
"importance": 0.85
}
]
}4. Semantic Memory
Scope: Single agent Lifespan: Permanent Use Case: Facts and knowledge
Semantic memory stores long-term factual knowledge:
- Domain concepts
- Learned rules
- Reference information
{
"level": "semantic",
"agent_id": "agent_456",
"knowledge": {
"offboarding_checklist": ["access_revocation", "knowledge_transfer", "exit_interview"],
"high_risk_systems": ["aws-production", "customer-db", "billing-system"],
"approval_required_actions": ["admin_revocation", "data_export", "external_communication"]
}
}5. Organizational Memory
Scope: All agents in organization Lifespan: Permanent Use Case: Shared company knowledge
Organizational memory is shared across all agents:
- Company policies
- Standard procedures
- Organizational structure
{
"level": "organizational",
"org_id": "org_789",
"knowledge": {
"company_policies": {
"data_retention": "7 years",
"exit_interview_required": true
},
"org_structure": {
"engineering_head": "cto@company.com",
"hr_head": "chro@company.com"
}
}
}Memory Operations
Reading Memory
Agents can read from any accessible memory level:
capabilities:
- memory_read:working
- memory_read:short_term
- memory_read:episodic
- memory_read:semantic
- memory_read:organizationalWriting Memory
Write access is more restricted:
capabilities:
- memory_write:working # Always allowed during run
- memory_write:short_term # For caching
- memory_write:episodic # For learning
# semantic and organizational typically admin-onlyLearning Loop
The memory system enables agents to learn from experience:
┌─────────────────────────────────────────────────────────────────────┐
│ Learning Loop │
│ │
│ Run Completed │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ Lesson Extraction (LLM) │ │
│ │ │ │
│ │ "Engineering departures often have secondary email │ │
│ │ accounts in monitoring systems (PagerDuty, Datadog)" │ │
│ │ │ │
│ │ Applicability: [engineering, developer] │ │
│ │ Importance: 0.8 │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ Stored in Episodic Memory │
│ │ │
│ ═══════════════════════════════════════════════════════════════ │
│ │ │
│ Next Run: Similar Context │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ Lesson Injection │ │
│ │ │ │
│ │ System Prompt: │ │
│ │ "Based on past experience with similar offboardings: │ │
│ │ - Check for secondary email accounts in PagerDuty, Datadog"│ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘Memory Tools
Agents use these tools to interact with memory:
| Tool | Operation | Memory Levels |
|---|---|---|
memory_read | Read data | All accessible |
memory_write | Write data | Working, Short-term |
memory_search | Search by query | Episodic, Semantic, Org |
memory_delete | Remove data | Working, Short-term |
Example: Reading Lessons
{
"tool": "memory_search",
"input": {
"level": "episodic",
"query": "engineering departure",
"limit": 5
},
"output": {
"results": [
{
"lesson": "Check for personal SSH keys",
"importance": 0.9,
"context": ["engineering", "infrastructure"]
}
]
}
}Best Practices
Use Appropriate Levels
| Need | Memory Level |
|---|---|
| Current task data | Working |
| Cache between runs | Short-term |
| Learn from experience | Episodic |
| Store facts | Semantic |
| Share across agents | Organizational |
Set TTLs for Short-term
Prevent memory bloat:
memory:
short_term:
default_ttl_hours: 24
max_ttl_hours: 168 # 1 weekCurate Organizational Memory
Organizational memory affects all agents. Review and curate:
- Remove outdated information
- Update policies regularly
- Verify accuracy
Monitor Memory Usage
Track memory consumption by level and agent:
- Set quotas if needed
- Archive old data
- Clean up unused namespaces