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: text-embedding-3-small by default, configurable via AgentConfig.embedding_model
• Retrieval Method: Cosine similarity search
• Best For: FAQs, documentation, product catalogs, knowledge bases

Usage Example

Call these from inside run() (as self.pipeline.semantic) or externally via agent.pipeline.semantic once the agent is initialized:

# Add knowledge to semantic memory (one entry per call)
await agent.pipeline.semantic.store(
    "Our premium plan costs $149/month and includes up to 100 agents.",
    metadata={"category": "pricing", "product": "premium"},
)
await agent.pipeline.semantic.store(
    "Password reset can be done from Settings > Security > Reset Password.",
    metadata={"category": "account", "topic": "password"},
)

# Query semantic memory
results = await agent.pipeline.semantic.search("How much does the premium plan cost?", top_k=5)

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 recorded on every process() call --
# no separate step needed.
session = agent.start_session()
response = await agent.process(
    Message(content="I'd like to upgrade my subscription"), session_id=session,
)

# Access recent history for this agent
history = await agent.pipeline.episodic.get_recent("agent-123", session_id=session, limit=20)

# Search past interactions
relevant = await agent.pipeline.episodic.search("subscription upgrade", limit=10)

# context.episodic_context (passed into run()) already carries this
# automatically -- the agent recalls prior turns without extra code.
response = await agent.process(Message(content="What did we discuss last time?"), session_id=session)
# 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

from vouchstone_sdk import Skill

# Register a procedure the agent should follow
skill = Skill(
    id="handle_refund_request",
    name="handle_refund_request",
    description="Handle a customer refund request",
    steps=[
        "Acknowledge the request empathetically",
        "Ask for order number and reason",
        "Check refund eligibility in system",
        "Process refund if eligible or explain policy",
    ],
)
await agent.pipeline.procedural.register_skill("agent-123", skill)

# Record whether an execution succeeded -- feeds success_rate, which
# find_skill() uses to rank which learned procedure to apply
await agent.pipeline.procedural.record_execution(
    "agent-123", skill_name="handle_refund_request", success=True, latency_ms=850,
)

# Agent automatically retrieves relevant skills into context.procedural_skills
response = await agent.process(Message(content="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: