Skip to main content
In Cognee, a session defines the scope for a single conversation or agent run. It maintains a cache of short-term information, including recent queries, responses, and the context used to answer them.

​
What Is a Session?

A session is Cognee’s short-term memory for a specific user during search operations. It is identified by (user_id, session_id) and stores an ordered list of recent interactions created by calls to cognee.search(). When you omit session_id in a search call, Cognee uses the session ID default_session and still stores the turn when caching is enabled. Sessions are created and used only for these search types: GRAPH_COMPLETION, RAG_COMPLETION, TRIPLET_COMPLETION. Batch queries do not use the session cache, and other search types do not read or write session history. Cognee reads from this session memory at the start of a search to recover earlier turns. When the search finishes, it writes a new interaction to the session so the history grows over time. Using the same session_id across searches allows Cognee to include previous interactions as conversational history in the LLM prompt, enabling follow-up questions and contextual awareness.
Sessions require caching to be enabled. See the next sections and Configuration Details below. If caching is disabled or unavailable, searches still work but without access to previous interactions.

​
How Sessions Work

Sessions are used during search operations. When you call cognee.search() with a session_id:
  1. Retrieve context – Cognee finds relevant graph elements for your query
  2. Load conversation history – If caching is enabled, previous interactions for (user_id, session_id) are loaded
  3. Generate answer – The LLM receives the query, graph context, and retrieved history
  4. Save interaction – A new Q&A entry is stored in the session cache

​
Cache Adapters

Cognee supports two cache adapters for storing sessions. Redis is recommended for distributed or multi-process setups, while Filesystem can be used when you need a simple local cache without network dependencies. Both provide the same functionality; only the storage backend differs. Below are the configuration options for each adapter with additional details.
Add to your .env file:
CACHING=true
CACHE_BACKEND=redis
CACHE_HOST=localhost
CACHE_PORT=6379
Start Redis:
# Using Docker
docker run -d -p 6379:6379 redis:latest

# Or using local installation
redis-server
  • Fast in-memory storage
  • Supports shared locks for Kuzu (multi-process coordination)
  • Requires a running Redis instance and network connectivity
Sessions store interactions as JSON entries in a list. Each entry contains:
  • time: ISO 8601 timestamp (UTC)
  • question: The user’s query text
  • context: Context used for the answer; may be empty if summarization is not enabled
  • answer: The LLM’s response
  • qa_id: Unique identifier for the entry (used for feedback and updates)
  • feedback_text: Optional user feedback text
  • feedback_score: Optional feedback score, 1–5
Sessions are keyed by: agent_sessions:{user_id}:{session_id}Each user can have multiple sessions, each maintaining its own cache of short-term information.
Environment Variables:
  • CACHING (bool): Enable/disable caching (default: false)
  • CACHE_BACKEND (str): "redis" or "fs" (default: "fs" when CACHING=true)
  • CACHE_HOST (str): Redis hostname (default: "localhost")
  • CACHE_PORT (int): Redis port (default: 6379)
  • CACHE_USERNAME (str, optional): Redis username
  • CACHE_PASSWORD (str, optional): Redis password
Conversation history window:
  • Cognee includes up to the last 10 session entries when building LLM conversation history.
Sessions persist until the cache is cleared (e.g. via prune or by wiping the cache backend). There is no automatic expiration.
FeatureRedisFilesystem
StorageIn-memory (Redis)Local disk (diskcache)
PerformanceVery fastFast (local I/O)
Multi-process✅ Supported❌ Not supported
Shared locks✅ Yes❌ No
Network required✅ Yes❌ No
Setup complexityMediumLow
Best forProduction, distributedDevelopment, local

Search

Learn how sessions integrate with search

Sessions Guide

Practical examples with Redis and filesystem

Setup Configuration

Configure cache adapters