Skip to main content

What is a session

A session holds short-term memory for one conversation: its questions and answers, agent trace steps, feedback and guidance. improve turns it into permanent graph memory.

How sessions work in Rust

A Session is a temporary memory context — search/answer history and feedback for a single conversational thread — distinct from permanent, graph-backed storage. Passing a --session-id to remember / recall scopes a turn to that session and lets retrieval reuse prior context; omitting it on remember persists input as permanent graph memory (see the memory API in operations). A completion search / recall (a retriever that prepares session turns; not chunks, summaries, lexical, Cypher, …) that omits it now uses the default session when the caller is known and session memory is on (session.caching); before, such a search was stateless. The id is default_session_<dataset_id> when one distinct dataset is searched, so separate single-dataset searches never share a session, else default_session. A search over several datasets, or naming none (unless per-dataset storage leaves the caller exactly one readable dataset, which scopes it), is one logical turn in the unscoped default session. Such a search reads the session’s history and, while AUTO_FEEDBACK is on, its stored guidance entries, analyzes the turn (also only while AUTO_FEEDBACK is on) and saves its Q&A; pass your own session id to keep it out of the default session, or turn session.caching off to keep it stateless. The store backend is pluggable. Rust: SessionStore trait in cognee-session, with FsSessionStore (crate feature fs), RedisSessionStore (crate feature redis), and RelationalSessionStore backends. Setting session.store = "fs" or "redis" requires a cognee built with its session-fs / session-redis feature. Those features register the store factory and its session.fs / session.redis config section; enabling cognee-session/fs or cognee-session/redis alone does neither. Next to its Q&A entries and agent trace steps, a session keeps a list of session-context rows: JSON objects with a "kind" field. "context" rows are active guidance entries (SessionContextEntry: goals, rules, preferences, lessons); other kinds are feedback records or internal state rows, such as the StateRowWatermark rows the improve stages use to remember how far they got. Only "context" rows are ever rendered (coerce_active_context_entries). SessionManager::{get,create,update}_session_context_entry read and write them on every store (session_context_entries table, {session_id}.context.json file, session_context:{user}:{session} Redis list); deleting or pruning a session removes them. The table holds one row per (user_id, session_id, entry_id) (unique index uq_session_context_entry), so on the relational store a create of an existing entry id replaces it in place (the file and Redis stores append); a session without a user is the "default" user’s, as on the file and Redis stores. apply_candidate_updates is the one writer of guidance entries (confidence ≥ 0.75, at most 280 characters, an exact duplicate links its new source instead of a second entry); improve’s extract_agent_context stage feeds it the agent-profile lessons it draws from the session’s trace steps, and so does every stored trace step while AUTO_FEEDBACK is on (see AUTO_FEEDBACK). The session graph-context snapshot is removed: SessionStore / SessionManager::{get,set}_graph_context, cognee::session::{get,set}_graph_context and the bindings’ graph-context ops are gone, a migration drops the session_graph_context table, and session history no longer starts with a “Background knowledge from the knowledge graph” prefix. The recall scope "graph_context" is a deprecated alias of "graph" (it logs a warning), and "all" means graph, session, trace and session context (see recall). With personalization on (personalization_enabled), improve’s update_user_preferences stage keeps one internal UserPreference node per user and dataset, with weighted prefers edges to the graph nodes the user’s rated answers used and the user’s stated preferences as text; graph, RAG, and hybrid searches by that user rank by those weights and carry that text (see Configuration: feedback & personalization).

Recall

Session-aware retrieval

Improve

Bridge sessions into the graph

Runtime configuration

Session store settings