Documentation/Core Concepts/Memory Types

Memory Types

Engrami provides four distinct memory systems, each optimized for different types of information storage and retrieval. Understanding these memory types is essential for building effective AI agents.

Semantic Memory

Vector embeddings for knowledge retrieval. Used for FAQs, documentation, and factual information.

Episodic Memory

Conversation history and temporal events. Enables agents to recall past interactions.

Procedural Memory

Learned skills and behavioral patterns. Allows agents to improve through experience.

Decision Graph

Executable reasoning chains. For complex decision-making with full auditability.

Semantic Memory

Semantic memory stores factual knowledge as vector embeddings, enabling similarity-based retrieval. This is the foundation for building knowledge bases, FAQ systems, and document search capabilities.

Key Characteristics

Storage Backend: ChromaDB (vector database)
Embedding Model: OpenAI text-embedding-3-small (configurable)
Retrieval Method: Cosine similarity search
Best For: FAQs, documentation, product catalogs, knowledge bases

Usage Example

# Add knowledge to semantic memory
agent.memory.semantic.add([
    {
        "content": "Our premium plan costs $49/month and includes unlimited agents.",
        "metadata": {
            "category": "pricing",
            "product": "premium",
            "updated_at": "2024-01-15"
        }
    },
    {
        "content": "Password reset can be done from Settings > Security > Reset Password.",
        "metadata": {
            "category": "account",
            "topic": "password"
        }
    }
])

# Query semantic memory
results = agent.memory.semantic.search(
    query="How much does the premium plan cost?",
    limit=5,
    filters={"category": "pricing"}
)

for result in results:
    print(f"Score: {result.score:.2f} - {result.content}")

Best Practice

Chunk large documents into smaller, semantically meaningful pieces (300-500 tokens) for optimal retrieval performance. Include relevant metadata for filtering.

Episodic Memory

Episodic memory stores conversation history and temporal events, allowing agents to maintain context across interactions and recall past conversations with specific users.

Key Characteristics

Storage Backend: PostgreSQL with Redis caching
Organization: Session-based with user context
Retrieval Method: Temporal and contextual queries
Best For: Conversation continuity, user preferences, interaction history

Usage Example

# Episodic memory is automatically managed during conversations
response = agent.chat(
    message="I'd like to upgrade my subscription",
    user_id="user_123",
    session_id="session_abc"
)

# Access conversation history
history = agent.memory.episodic.get_history(
    user_id="user_123",
    limit=20,
    include_metadata=True
)

# Search past interactions
relevant_conversations = agent.memory.episodic.search(
    user_id="user_123",
    query="subscription upgrade",
    time_range={"days": 30}
)

# The agent automatically uses this context
response = agent.chat("What did we discuss last time?")
# Agent recalls the subscription upgrade conversation

Procedural Memory

Procedural memory stores learned behaviors, skills, and patterns. It enables agents to improve their responses over time based on feedback and successful interactions.

Key Characteristics

Storage Backend: Neo4j (graph database)
Organization: Skill graphs with weighted relationships
Learning Method: Reinforcement from feedback
Best For: Learned behaviors, best practices, procedural knowledge

Usage Example

# Define a procedure the agent should learn
agent.memory.procedural.add_skill({
    "name": "handle_refund_request",
    "trigger": "customer requests refund",
    "steps": [
        "Acknowledge the request empathetically",
        "Ask for order number and reason",
        "Check refund eligibility in system",
        "Process refund if eligible or explain policy"
    ],
    "success_criteria": "customer satisfaction confirmed"
})

# Provide feedback to reinforce learning
agent.memory.procedural.reinforce(
    skill_id="handle_refund_request",
    outcome="success",
    feedback="Customer was satisfied with the resolution"
)

# Agent automatically applies learned procedures
response = agent.chat("I want a refund for my order")
# Agent follows the learned refund handling procedure

Decision Graph

Decision graphs provide structured, auditable reasoning chains for complex decisions. They're essential for compliance-sensitive applications where decision transparency is required.

Key Characteristics

Storage Backend: Neo4j (graph database)
Organization: Directed acyclic graphs (DAGs)
Execution: Step-by-step with logging
Best For: Approval workflows, diagnostic processes, compliance decisions

Usage Example

# Define a decision graph for loan approval
decision_graph = agent.memory.decision_graph.create({
    "name": "loan_approval",
    "nodes": [
        {
            "id": "check_credit_score",
            "type": "condition",
            "evaluate": "credit_score >= 650",
            "true_next": "check_income",
            "false_next": "reject_low_credit"
        },
        {
            "id": "check_income",
            "type": "condition",
            "evaluate": "annual_income >= 50000",
            "true_next": "approve",
            "false_next": "manual_review"
        },
        {
            "id": "approve",
            "type": "action",
            "action": "approve_loan"
        },
        {
            "id": "reject_low_credit",
            "type": "action",
            "action": "reject_loan",
            "reason": "Credit score below minimum requirement"
        },
        {
            "id": "manual_review",
            "type": "action",
            "action": "flag_for_review"
        }
    ]
})

# Execute the decision graph
result = agent.memory.decision_graph.execute(
    graph_id="loan_approval",
    inputs={
        "credit_score": 720,
        "annual_income": 65000
    }
)

# Get full decision audit trail
audit_trail = result.get_audit_trail()
for step in audit_trail:
    print(f"{step.node_id}: {step.outcome} - {step.reasoning}")

Choosing the Right Memory Type

Most agents benefit from using multiple memory types together. Here's a guide to help you choose:

Use Case	Recommended Memory Types
Customer Support Bot	Semantic + Episodic + Procedural
Documentation Assistant	Semantic only
Personal Assistant	Episodic + Procedural
Approval Workflow	Decision Graph + Episodic
Data Analyst	All four types

Agents Workflows