Skip to main content

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)

Source distribution for sessions-graph 0.12.0
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)

Table of built distributions (wheels) for sessions-graph 0.12.0
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page