Sessions

Represent a conversation in Zep's Memory Store

You are viewing the Zep Open Source v0.x documentation. This version is no longer supported, and documentation is provided as a reference only.

The current documentation for Zep Community Edition is available here.

Sessions represent a conversation. Sessions can be associated with Users in a 1:M relationship.

Chat messages are added to sessions in the form of Memories. Each session can have many messages associated with it.

The SessionID is a string key that accepts arbitrary identifiers. Related data you’d like to store can be persisted as metadata.

Adding a Session

SessionIDs are arbitrary identifiers that you can map to relevant business objects in your app, such as users or a conversation a user might have with your app

Note: Sessions don’t need to be explicitly created. Sessions are created automatically when adding Memories. If the SessionID already exists, then the Memory is upserted into the Session. Manually creating a session can be useful if you want to associate it with a user or add metadata.

Python

1 async with ZepClient(base_url, api_key) as client:
2     session_id = uuid.uuid4().hex # A new session identifier
3     session = Session(
4                 session_id=session_id,
5                 user_id=user_id,  # Optionally associate this session with a user
6                 metadata={"foo" : "bar"}
7             )
8     await client.memory.aadd_session(session)

TypeScript

1 const sessionData: ISession = {
2   session_id: sessionID,
3   user_id: userID, // Optionally associate this session with a user
4   metadata: { foo: "bar" },
5 };
6 const session = new Session(sessionData);
7 await client.memory.addSession(session);

Looking to associate a Session with a User? Check out our User Management docs.

Updating Session Metadata

You can update a session’s metadata by providing a Session object with new metadata. Note that metadata is merged, so any existing metadata will be preserved.

Python

1 session = Session(session_id=session_id, metadata={"qax" : "baz"})
2 await client.memory.aupdate_session(session)

TypeScript

1 const sessionData: ISession = {
2   session_id: sessionID,
3   metadata: { qax: "baz" },
4 };
5 const session = new Session(sessionData);
6 await client.memory.updateSession(session);

Getting a Session

Python

1 session = await client.memory.aget_session(session_id)
2 print(session.dict())

TypeScript

1 const session = await client.memory.getSession(sessionID);
2 console.debug("Retrieved session ", session.toDict());

Deleting a Session

Deleting a Session soft-deletes the Session and all associated Memories. The Session and Memories are still available in the database, but are marked as deleted and will not be returned in search results.

They will be purged on the next run of the Zep Purge Process.

If you persist memory to a deleted Session, it will be undeleted. Deleted Memories will, however, remain deleted.

Python

1 await client.memory.adelete_memory(session_id)

TypeScript

1 await client.memory.deleteMemory(sessionID);

Listing Sessions

You can list all Sessions in the Zep Memory Store with optional limit and cursor parameters for pagination. We also provide a helper generator function making it simple to iterate over all Sessions.

Python

1 # List the first 10 Sessions
2 sessions = client.memory.list_sessions(limit=10, cursor=0)
3 for session in sessions:
4     print(session)
5 
6 # List All Sessions using a generator
7 all_sessions = client.memory.list_all_sessions(chunk_size=100)
8 for session_chunk in all_sessions:
9     for session in session_chunk:
10         print(session)

TypeScript

1 // List the first 10 Sessions
2 const sessions = await client.memory.listSessions(10, 0);
3 
4 // List All Sessions using a generator
5 for await (const sessionChunk of client.memory.listSessionsChunked(100)) {
6   for (const session of sessionChunk) {
7     console.debug("Retrieved session ", session.toDict());
8   }
9 }

1	async with ZepClient(base_url, api_key) as client:
2	session_id = uuid.uuid4().hex # A new session identifier
3	session = Session(
4	session_id=session_id,
5	user_id=user_id, # Optionally associate this session with a user
6	metadata={"foo" : "bar"}
7	)
8	await client.memory.aadd_session(session)

1	const sessionData: ISession = {
2	session_id: sessionID,
3	user_id: userID, // Optionally associate this session with a user
4	metadata: { foo: "bar" },
5	};
6	const session = new Session(sessionData);
7	await client.memory.addSession(session);

1	session = Session(session_id=session_id, metadata={"qax" : "baz"})
2	await client.memory.aupdate_session(session)

1	const sessionData: ISession = {
2	session_id: sessionID,
3	metadata: { qax: "baz" },
4	};
5	const session = new Session(sessionData);
6	await client.memory.updateSession(session);

1	session = await client.memory.aget_session(session_id)
2	print(session.dict())

1	const session = await client.memory.getSession(sessionID);
2	console.debug("Retrieved session ", session.toDict());

1	# List the first 10 Sessions
2	sessions = client.memory.list_sessions(limit=10, cursor=0)
3	for session in sessions:
4	print(session)
5
6	# List All Sessions using a generator
7	all_sessions = client.memory.list_all_sessions(chunk_size=100)
8	for session_chunk in all_sessions:
9	for session in session_chunk:
10	print(session)

1	// List the first 10 Sessions
2	const sessions = await client.memory.listSessions(10, 0);
3
4	// List All Sessions using a generator
5	for await (const sessionChunk of client.memory.listSessionsChunked(100)) {
6	for (const session of sessionChunk) {
7	console.debug("Retrieved session ", session.toDict());
8	}
9	}