Memory Types

Vouchstone provides a biologically-inspired 5-layer memory stack, each layer analogous to a region of the human brain. Understanding these memory layers is essential for building effective AI agents.

Working Memory

Working memory provides in-context state for the current agent turn. It holds the active conversation context, tool results, and intermediate reasoning — bounded by the LLM context window and reset at session end.

Key Characteristics

• Storage Backend: Redis
• Lifecycle: Per-session, resets when session ends
• Brain Analogy: Prefrontal cortex
• Best For: Active conversation context, tool call results, scratch state

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: Voyage AI voyage-3-large, 1024-dim (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 $149/month and includes up to 100 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}")

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

Meta-Memory

Meta-memory is the governance layer that manages all other memory layers. It handles retention policies, decay schedules, compression, deduplication, and forgetting — running on scheduled or threshold-triggered cycles.

Key Characteristics

• Storage Backend: Control plane (PostgreSQL)
• Execution: Scheduled and threshold-triggered
• Brain Analogy: Anterior prefrontal cortex (metacognition)
• Best For: Memory lifecycle management, compliance, storage optimization

Capabilities

• Retention Policies: Define how long each memory type is kept
• Decay: Gradually reduce relevance scores of aging memories
• Compression: Summarize old episodic traces into semantic knowledge
• Deduplication: Merge duplicate entities in semantic memory
• Forgetting: Remove deprecated or low-value memories on schedule

Choosing the Right Memory Type

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