Sessions Graph
Store durable memories and retrieve context from a user's past agent sessions in Memgraph.
Sessions Graph is the memory component of Context Graph. It links users to sessions, stores memory files, extracts entities and relationships, and retrieves dated evidence for the agent's next answer.
Using a coding agent? The Context Graph installer wires this package automatically. The examples below are for direct Python use.
Installation
Requires Memgraph 3.6 or newer. Use the MAGE image for vector recall.
pip install sessions-graph
Optional features:
pip install 'sessions-graph[memgraph-context-graph]' # runtime connector
pip install 'sessions-graph[reconciliation]' # local entity extraction
Capture, extraction, embeddings, and recall need no LLM API key. An optional key enables ontology derivation.
Quick start
from sessions_graph import SessionsGraph
graph = SessionsGraph() # connects via MEMGRAPH_URL / MEMGRAPH_USER / MEMGRAPH_PASSWORD env vars
graph.setup() # creates constraints and the text index (run once)
# Write a memory
mem = graph.save_memory(
user_id="alice",
content="Prefers Python over TypeScript",
session_id="s-abc123", # optional — links memory to a session for provenance
)
# Retrieve all memories for a user
memories = graph.get_memories("alice")
# Search memories by content (full-text, powered by Tantivy)
results = graph.search_memories("alice", "Python")
# Update or delete
graph.update_memory(mem.memory_id, "Prefers Python, especially for data tooling")
graph.delete_memory(mem.memory_id)
Memory files
Agents can organize curated memory as files under /memories, shared across sessions. The file API supports viewing, creating, editing, deleting, and renaming, with version history and checks against stale edits.
store = graph.memory_store("alice", session_id="s-abc123")
store.create("/memories/feedback/testing.md", "Prefer real Memgraph in tests.")
print(store.view("/memories/feedback/testing.md"))
See memory files and the Python API for path rules, version history, text search, and method signatures. Coding agents use the same store through the MCP memory tool.
Recall
recall(user_id, question) returns what one user's own past sessions hold
about a question: the evidence, not an answer. The caller's model answers
from it.
recalled = graph.recall("alice", "Which database did we pick for the cache?")
print(recalled.render(today="2026-10-05")) # header with reading rules, then the rows
recalled.to_json() # source rows and exchange groups as data
Recall combines six searches over the user's history:
| Lane | Finds |
|---|---|
memories |
Curated memory files, by vector and full-text search |
turns |
Conversation messages nearest the question by vector |
text |
Messages matching the question by full-text search |
entities |
Relevant entities and their facts |
facts |
Extracted facts nearest the question by vector |
user_facts |
Facts grouped by relevant relation types, for questions that need a complete set |
Saved memory files come first. By default, recall then groups the related source messages into exchanges that fit a 6,000-token row budget per space, and uses extracted facts to rank them rather than showing them as separate claims. Supplemental search adds complementary problem-resolution exchanges. Set packing="turns" to restore separate turn and fact rows, or supplemental_search=False to turn off supplemental discovery. Without MAGE, recall falls back to text search and reports that in its output.
Exchange dependencies are included in the standard install; offline deployments must first populate the tokenizer cache, as described in exchange recall. On the matched 400-question retrieval comparison, exchanges used 38.1% fewer context tokens than historical recall but took 0.859 s versus 0.744 s for optimized turns. A general quality improvement has not been established; the report records question-type regressions and the remaining validation.
Tune search widths and packing with RecallConfig.from_mapping(...) or the config file's [recall] section; existing config files that omit the new keys adopt the defaults. Coding agents call the same read path through the MCP recall tool; see recall settings and the benchmark results.
Session reconciliation
Reconciliation turns session messages and tool activity into entities and relationships with local GLiNER2. It processes memory files separately so edits can replace what an earlier version produced.
sessions-graph reconcile --pending
sessions-graph reconcile --session s-abc123
Extraction runs outside hooks. Turn and session ends queue work; optional automatic processing starts on session end. See the reconciliation guide for scheduling, configuration, and programmatic use.
Ontology versions
Each user has an adopted ontology describing the entity and relation types extraction should produce. You can load a YAML schema or optionally let an LLM propose extensions, which are checked against the existing model before adoption.
sessions-graph ontology load --file coding.yaml
sessions-graph ontology show
See ontology versions for the default model, pinned types, derivation, and adoption checks.
Embeddings for recall
MAGE computes vectors inside Memgraph. Turn ends schedule message embedding; reconciliation embeds the entities and facts it creates. Catch up pending work with:
sessions-graph embed --pending
The default model is BAAI/bge-small-en-v1.5 (384 dimensions). It downloads inside Memgraph on first use and needs at least 2 GiB of memory. See embeddings for recall for model changes and failure handling.
Integration with Memgraph Context Graph
SDK applications get capture, the memory index, and tools through the SDK integration.
For custom event wiring, register SessionsGraphConnector with an AgentLink; see the Python API guide. Hook integrations read configuration from the Context Graph config file; direct SessionsGraph() use reads the connection environment variables shown above.
Graph schema
(:User)-[:HAD_SESSION]->(:Session)
(:User)-[:HAS_MEMORY]->(:Memory)
(:Session)-[:PRODUCED_MEMORY]->(:Memory)
(:Memory)-[:ABOUT]->(:Project)
(:Session)-[:HAS_ACTION]->(:Action)-[:HAS_CHUNK]->(:Chunk)
(:Memory)-[:HAS_CHUNK]->(:Chunk)<-[:MENTIONED_IN]-(:Entity)
Sessions Graph owns users, memories, and session provenance. Other components share the Session node. Actions belong to Actions Graph; chunks and extracted entities come from unstructured2graph.
API reference
The Python API guide lists memory, session, and reconciler methods.
Development
From the repository root:
./scripts/dev-memgraph.sh test sessions-graph
Metadata
Release files for sessions-graph 0.12.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| sessions_graph-0.12.0.tar.gz | 144.4 kB | Without provenance | Details for sessions_graph-0.12.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| sessions_graph-0.12.0-py3-none-any.whl | Python 3 | none | any | Details for sessions_graph-0.12.0-py3-none-any.whl |
Total release size: 234.6 kB
Release files / sessions_graph-0.12.0.tar.gz
| Download URL | sessions_graph-0.12.0.tar.gz |
|---|---|
| Size | 144.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
3742d52c5417ab3fe85f2a21057d265d56877c9bb444ecbca492519bdf729dab
|
|
BLAKE2b-256 checksum How to use checksums |
8315aaed39501525d043c8a002dd70d267455596ec836693c3addd23a937a1cc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.6 {"installer":{"name":"uv","version":"0.13.6","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / sessions_graph-0.12.0-py3-none-any.whl
| Download URL | sessions_graph-0.12.0-py3-none-any.whl |
|---|---|
| Size | 90.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
ad4bdc925a83622503970c8332809cc208eaf28db4d394d68469712afc294696
|
|
BLAKE2b-256 checksum How to use checksums |
211ddb7ab1554b5d5ede51e2c304f3b111e16b9fd234792b143360aeb7f886d5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.6 {"installer":{"name":"uv","version":"0.13.6","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for sessions-graph 0.12.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.