Memories

Memories are the core of the zkStash platform. They represent the knowledge that your agents accumulate over time. Unlike the ephemeral context window of an LLM, memories in zkStash are persistent, searchable, and structured.

Core Memory Operation

At its core, every memory operation follows a simple cycle:

Accept: The system receives conversation data and the current memory state.
Prompt: An LLM determines how to expand or consolidate the memory.
Update: The new memory state is saved.

Short-Term vs. Long-Term Memory

Short-Term Memory (Context)

Short-term memory typically refers to the context window of the LLM or the state of a specific conversation thread.

Scope: Limited to a single session or thread.
Persistence: Ephemeral. Lost when the session ends or the context window is exceeded.
Use Case: Remembering the user’s name in the current chat, or the last question asked.

Long-Term Memory (Persistence)

zkStash provides Long-term Memory. This is knowledge that persists across different threads, sessions, and time.

Scope: Global (per Agent). Accessible across all interactions.
Persistence: Indefinite. Stored until explicitly deleted or expired.
Use Case: Remembering a user’s dietary restrictions learned last month, or a fact discovered by another agent in the fleet.

Types of Long-Term Memory

Just as humans use different types of memory for different purposes, AI agents benefit from organizing knowledge into distinct categories:

Semantic Memory (Facts & Knowledge)

Semantic memory stores factual information about the world, users, or domain-specific knowledge. We support two primary patterns:

1. Profiles (Structured)

Profiles are ideal for entities where there should be one active version of the truth.

Schema Type: Single Record (e.g., UserProfile, CustomerSettings)
Behavior: Updates replace the previous state.
Example: “User prefers dark mode”

2. Collections (Unbounded)

Collections are for accumulating an unbounded amount of knowledge that is searched at runtime.

Schema Type: Multiple Records (e.g., ProductKnowledge, DomainFact)
Behavior: New facts are appended.
Example: “Redis is an in-memory database”

Episodic Memory (Experiences & Events)

Episodic memory stores specific events or interactions that happened at a particular time.

Schema Type: Always Multiple Records (e.g., InteractionLog, TaskHistory)
Use Case: Learning from past successes/failures.
Example: “Agent successfully resolved ticket #456 using strategy X”

Procedural Memory (Rules & Strategies)

Procedural memory stores instructions, strategies, or rules that guide behavior.

Schema Type: Single Record (e.g., AgentInstructions)
Use Case: Evolving agent behavior based on feedback.
Example: “For technical issues, escalate to human if confidence < 0.7”

Writing Memories

There are two primary patterns for when to write memories:

Conscious Formation (Hot Path)

The agent decides to save a memory as part of its normal response flow using MCP.

Mechanism: The MCP server exposes tools (e.g., create_user_profile) to your agent.
Pros: Memory is immediately available for the next turn.
Cons: Adds latency to the user-facing response.

Subconscious Formation (Background)

A separate process analyzes the conversation history and extracts memories after the fact using the zkStash REST API or SDK.

Mechanism: Background workers call POST /memories.
Pros: No latency impact; allows for deeper “reflection” and batch processing.
Cons: Memory is not immediately available.

Organizing Memories

Memories are organized by Agent ID and optionally by Thread ID.

Agent ID: The primary namespace. All memories for a specific agent (e.g., “customer-support-bot”) are grouped together.
Thread ID: Optional sub-namespace for session-specific context. Useful for scoping memories to a particular conversation (e.g., isolating memories from different user chats).

This hierarchical organization allows you to:

Retrieve all knowledge for an agent across all conversations
Filter memories to a specific conversation thread
Share knowledge between agents by querying across Agent IDs

NOTE: Ready to integrate zkStash into your application? Check out the Integrations page for detailed guides on using the REST API, SDK, or MCP.