Getting Started

Persisting and Retrieving Memory

Getting Started with Zep Memory

Understanding Zep’s different memory APIs

The Zep Memory API provides a high-level interface for persisting and retrieving memory artifacts such as Messages, Sessions, Facts, and Summaries. The Memory API is Session-specific, opinionated, and offers a number of different Memory Types designed for different memory retrieval use cases.

The Zep Search APIs provide fine-grained control over memory artifact retrieval and are significantly more flexible than the Memory API.

The Zep Session and Message APIs are lower-level APIs that offer Create, Read, Update, and Delete operations against individual Session and Message records and their associated memory artifacts.

APIUse CaseScopeArtifacts
MemoryHigh-level interface for persisting and retrieving memory artifactsSingle SessionMessages, Sessions, Facts, Summaries
SearchFine-grained control over memory artifact retrievalAll Users, All or Specific User Sessions, a Single SessionMessages, Sessions, Facts, Summaries
SessionLower-level CRUD interface for managing Session recordsSpecified SessionSessions
MessageLower-level CRUD interface for managing Message records and their associated memory artifactsSpecified MessageMessages

Persisting Memory

The Zep Memory API makes it simple to persist one or more Messages to a Session.

1result = await client.memory.add(session_id, messages=messages)
Read more in the Memory Guide and Memory API Reference

Retrieving Memory

Using the Memory API

The Zep Memory API makes it simple to retrieve memory artifacts from a Session. Depending on the Type of memory specific and available artifacts, a Memory object is returned with one or more of the following properties:

  • messages: An array of Message objects for the last N messages in the session.
  • summary: A Summary object, which is the most recent summary generated prior to the last N messages in the session.
  • relevant_facts: An array of Fact objects relevant to the last 4 messages in the session.
  • relevant_summaries: An array of Summary objects relevant to the last 4 messages in the session.
1memory = client.memory.get(session_id="session_id")
Read more in the Memory Guide and Memory API Reference

Using the Search API

The Memory Search API provides a fine-grained interface for retrieving memory artifacts from a single Session, multiple Sessions, all Sessions for a User, or all Services project-wide.

Zep uses semantic similarity search to find the most relevant memory artifacts for a given text query.

Key features of this API:

  • Supports searching over Messages, Facts, or Summaries.
  • Search queries may filtered by Message, Fact, or Summary metadata. (Support for custom Fact and Summary metadata is coming soon!)
  • Results may be reranked using Maximum Marginal Relevance (MMR), inceasing the diversity of relevant results.
1results = client.memory.search_sessions(
2 user_id="user_id",
3 text=query_text,
4 search_type="similarity",
5 search_scope="facts",
6 limit=10
7)
The Search API is particularly useful for finegrained control over which memory artifacts are populated into your prompts. Learn more in the Memory Guide and Memory API Reference

Using the Session and Message API

Messages and their content, role, and role_type are immutable. They may only be deleted when an entire Session is deleted. You may however update the metadata for a Message. Have a use case for updating a Message? Let us know via the in-app chat!

The Session and Message APIs provide a lower-level interface for managing Session and Message records and their associated memory artifacts. You may create, read, update, and delete Session and Message records.

More details in the Memory API Reference