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).
Related
Recall
Session-aware retrieval
Improve
Bridge sessions into the graph
Runtime configuration
Session store settings