Skip to content

add: Context Graph user docs under AI memory #1847

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
antejavor wants to merge 9 commits into
base: update/ai-ecosystem-structure-v2
Choose a base branch
from
+2,391 −96
Draft

add: Context Graph user docs under AI memory #1847

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
76db34d
add: Context Graph user docs under AI memory
antejavor Oct 20, 2026
b3984a1
add: Context Graph capture privacy settings
antejavor Oct 20, 2026
e564ccc
add: Context Graph forget, uninstall and first-run setup changes
antejavor Oct 21, 2026
746f51e
update: Context Graph plugin updates, without release versions
antejavor Oct 21, 2026
160dea8
Update.
antejavor Oct 22, 2026
04169f0
Remove uncessary.
antejavor Oct 22, 2026
a160f15
update: Restructure the Context Graph docs, add a Privacy page and ap…
antejavor Oct 22, 2026
efa231b
add: Context Graph data flow diagram on AI memory, with a dark version
antejavor Oct 22, 2026
188b33f
update: Context Graph docs for ai-toolkit #598-#601: Agent SDK apps, …
antejavor Oct 22, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 1 addition & 2 deletions pages/ai-ecosystem.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -79,8 +79,7 @@ an API key.

- [AI memory](/ai-ecosystem/ai-memory): Sets up Context Graph, which records
your coding agents' sessions in Memgraph as semantic, episodic and
procedural memory. It asks before it changes anything. You need Docker. On
Windows, the command prints the setup command to run in WSL or Git Bash.
procedural memory. It asks before it changes anything. You need Docker.

<Tabs items={['Linux/macOS', 'Windows']}>
<Tabs.Tab>
Expand Down
220 changes: 127 additions & 93 deletions pages/ai-ecosystem/ai-memory.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,122 +1,156 @@
---
title: AI memory
description: Store what an AI system knows, did and knows how to do as one graph in Memgraph, and set it up for your coding agents with one command.
description: Give AI agents a long-term memory as a graph in Memgraph, with Context Graph for your coding agents or with a memory model you build yourself.
---

import { Tabs } from 'nextra/components'

# AI memory

AI memory lets an AI system remember across sessions. In Memgraph, memory is a
graph of entities and typed relationships, so recall follows the connections
between what the system knows, what it did and what it knows how to do, not
only what sounds similar to the question.
AI memory lets an AI system use what happened in earlier sessions. In
Memgraph, memory is a graph: what the system knows, what it did and what it
knows how to do (semantic, episodic and procedural memory) are nodes linked
to the user and the session they came from.

## How Memgraph stores memory
A query can follow those links, and combine them with
[vector search](/querying/vector-search) and
[text search](/querying/text-search).

Memgraph stores three types of long-term memory in one graph:
There are two ways to add this memory to an AI system:

| Memory type | What it holds | How it's stored |
| --- | --- | --- |
| **Semantic** | What the system knows, such as facts and preferences | `(:User)-[:HAS_MEMORY]->(:Memory)` |
| **Episodic** | What the system did, such as past interactions | `(:Session)-[:HAS_ACTION]->(:Action)`, in order by `FOLLOWED_BY` |
| **Procedural** | What the system knows how to do, such as workflows | `(:Session)-[:USED_SKILL]->(:Skill)` |
- [Use Context Graph](#use-context-graph) for coding agents such as Claude
Code and Codex. It records their sessions and serves them back to the
agents, with no code to write.
- [Build your own memory](#build-your-own-memory) for your own agent or
application. You write the memory graph from your code and query it with
Cypher.

The `User` and `Session` nodes are shared by all three types, so one traversal
can recall facts, past actions and skills together.
## Use Context Graph

## Set up memory for your coding agents
Context Graph records each session of a
[supported coding agent](/ai-ecosystem/ai-memory/agents#supported-agents),
such as Claude Code or Codex, in Memgraph: your prompts, the agent's replies,
the tools it called and their results, the skills it used and the memories it
saved. In later sessions, any of those agents can read it back.

[Context Graph](https://github.com/memgraph/ai-toolkit/tree/main/context-graph),
part of the Memgraph AI Toolkit, records the sessions of your coding agents in
Memgraph as these three types of memory, so the agents can recall them in
later sessions. It works with Claude Code, Codex, GitHub Copilot CLI, Cursor,
OpenCode, Antigravity CLI and Grok Build.
Every connected agent gets:

You need [Docker](https://docs.docker.com/get-docker/), unless you already run
Memgraph 3.6 or later, and a terminal. Start the setup:
- **Capture.** Hooks in the agent write each session to the graph as it
happens. You use the agent as before.
- **Recall.** A `recall` tool, served over the Model Context Protocol (MCP),
returns what your past sessions hold about a question. Each session also
starts with a short note on where you left off in the current project.
- **Memory**, if you turn it on. A `memory` tool replaces the agent's own
memory, so the notes the agent saves are stored in the graph and shared by
all your agents.

<Tabs items={['Linux/macOS', 'Windows']}>
<Tabs.Tab>
```bash
curl -sSL https://install.memgraph.com/ai-memory | bash
```
</Tabs.Tab>
<Tabs.Tab>
Run the setup from WSL or Git Bash. In PowerShell, this command prints the
command to run there:
The diagram shows the three phases. During a session, the hooks capture each
event and the connectors write it to Memgraph, and the MCP server reads from
Memgraph when the agent asks. After the session,
[reconciliation](/ai-ecosystem/ai-memory/knowledge-graph) adds the knowledge
graph. Only the optional schema learning sends session text off your machine.

<div className="light-only">

![Context Graph in three phases: during a session, the memgraph-context-graph hooks in the agent, a coding agent or an Agent SDK app, drop private text and redact secrets, and the actions-graph, skills-graph and sessions-graph connectors write the session to Memgraph, along with the optional resources-graph connector and context-graph-spaces for shared spaces on Memgraph Enterprise; in Memgraph, users, sessions, actions, skills and memories form one graph, which the MCP server reads to serve recall and memory to the agent; after a session, reconciliation filters the text through the HyGM ontology, extracts entities and facts with GLiNER2 and stores them in the knowledge graph with their embeddings; only optional schema learning sends session text to an Anthropic or OpenAI API](/pages/ai-ecosystem/ai-memory/context-graph-flow.svg)

</div>
<div className="dark-only">

![Context Graph in three phases: during a session, the memgraph-context-graph hooks in the agent, a coding agent or an Agent SDK app, drop private text and redact secrets, and the actions-graph, skills-graph and sessions-graph connectors write the session to Memgraph, along with the optional resources-graph connector and context-graph-spaces for shared spaces on Memgraph Enterprise; in Memgraph, users, sessions, actions, skills and memories form one graph, which the MCP server reads to serve recall and memory to the agent; after a session, reconciliation filters the text through the HyGM ontology, extracts entities and facts with GLiNER2 and stores them in the knowledge graph with their embeddings; only optional schema learning sends session text to an Anthropic or OpenAI API](/pages/ai-ecosystem/ai-memory/context-graph-flow-dark.svg)

```powershell
iwr https://install.memgraph.com/ai-memory/windows -useb | iex
</div>

Context Graph is open source, part of the
[Memgraph AI Toolkit](https://github.com/memgraph/ai-toolkit/tree/main/context-graph).
By default, it stores everything in a Memgraph on your machine, with no
account or cloud service. See [Privacy](/ai-ecosystem/ai-memory/privacy) for
what is stored and how to keep things out.

To install it, see [Get started](/ai-ecosystem/ai-memory/get-started).

### How Context Graph organizes the graph

Each session is a `Session` node, linked to its `User`. Everything recorded in
the session hangs off that node:

```plaintext copy=false
(:User)-[:HAD_SESSION]->(:Session)
├─[:HAS_ACTION]->(:Action) prompts, replies, tool calls and results
├─[:USED_SKILL]->(:Skill) agent skills the session used
└─[:PRODUCED_MEMORY]->(:Memory) memories the agent saved
(:User)-[:HAS_MEMORY]->(:Memory)
```
</Tabs.Tab>
</Tabs>

The setup shows its plan and changes nothing until you confirm. Then it:

1. **Finds or starts Memgraph.** It uses the Memgraph in its configuration,
then one on `localhost:7687`, and otherwise starts the
`memgraph/memgraph-mage` image in a container named
`context-graph-memgraph`, with a data volume. If port 7687 is taken, it
picks a free port.
2. **Saves its configuration:** the Memgraph URL and your user ID, which
defaults to your git `user.name`.
3. **Installs the packages:** `uv` if it's missing, the
`memgraph-context-graph` command-line tool and its connectors.
4. **Connects your agents.** Claude Code and Codex get the Context Graph
plugin for your user. The other agents get hooks in the current project
directory.
5. **Checks the setup** and prints the command to rerun for any step that
failed.

Without a terminal, for example in CI, the command only prints the setup
command to run. Set `AI_MEMORY_SKIP_SETUP=1` to get the same behavior.

After the setup, every session of a connected agent writes `Memory`, `Action`
and `Skill` nodes to the graph, and the next session reads its memory back.
To manage the setup:

- `memgraph-context-graph ui` shows what your agents record, in the terminal.
- `memgraph-context-graph setup` changes your choices and skips what's already
done.
- `memgraph-context-graph uninstall` disconnects the agents. The graph and the
configuration stay.

For the other options and how to look at the graph in Memgraph Lab, see the
[Context Graph guide](https://github.com/memgraph/ai-toolkit/blob/main/context-graph/README.md#getting-started).

## Query the memory graph

Because the three types share the `User` and `Session` nodes, one query can
answer a request such as "schedule a follow-up with the client like last
time". This query returns what the system knows about a user, their most
recent session in which a meeting was scheduled, and the skill used in it:

`Memory` nodes hold what the agent knows, `Action` nodes what it did, and
`Skill` nodes what it knows how to do.

Context Graph can also extract the people, organizations, projects and other
entities your sessions mention into a
[knowledge graph](/ai-ecosystem/ai-memory/knowledge-graph), linked back to the
messages they came from. Recall uses it to find facts spread over many
sessions.

### Context Graph guides

- [Get started](/ai-ecosystem/ai-memory/get-started): Install Context Graph,
connect your agents and check that sessions are recorded.
- [Recall and memory](/ai-ecosystem/ai-memory/recall-and-memory): How agents
read their past sessions, and how to make Context Graph their memory.
- [Explore the graph](/ai-ecosystem/ai-memory/explore-the-graph): Look at what
your agents recorded, in the terminal, in Memgraph Lab or with Cypher.
- [Privacy](/ai-ecosystem/ai-memory/privacy): What is recorded, how to keep
text out of the graph, and how to delete sessions.
- [Configuration](/ai-ecosystem/ai-memory/configuration): The configuration
file, your own Memgraph, updating and uninstalling.
- [Knowledge graph](/ai-ecosystem/ai-memory/knowledge-graph): Extract
entities and facts from your sessions.
- [Agents](/ai-ecosystem/ai-memory/agents): The files setup changes for each
agent, and how the agents differ.
- [Agent SDK apps](/ai-ecosystem/ai-memory/agent-sdk-apps): Use the same
memory in an app built on the Claude Agent SDK or the OpenAI Agents SDK.
- [Shared spaces](/ai-ecosystem/ai-memory/shared-spaces): Share memory between
the members of a team, on Memgraph Enterprise.

## Build your own memory

To give your own agent or application a memory, write it to Memgraph from
your code and read it back with Cypher. You can use the same model as Context
Graph, shown in
[How Context Graph organizes the graph](#how-context-graph-organizes-the-graph).

### Query the memory graph

Because memories, actions and skills share the `User` and `Session` nodes,
one query can read all three. For a request such as "schedule a follow-up with
the client like last time", this query returns the user's memories, the last
session in which a meeting was scheduled, and the skills used in it:

```cypher template
MATCH (u:User {user_id: "USER_ID"})-[:HAS_MEMORY]->(mem:Memory)
MATCH (u)-[:HAD_SESSION]->(s:Session)-[:HAS_ACTION]->(a:Action {tool_name: "schedule_meeting"})
WITH u, mem, s, a ORDER BY s.started_at DESC LIMIT 1
MATCH (u:User {user_id: "USER_ID"})-[:HAD_SESSION]->(s:Session)-[:HAS_ACTION]->(a:Action {tool_name: "schedule_meeting"})
WITH u, s, a ORDER BY a.timestamp DESC LIMIT 1
OPTIONAL MATCH (u)-[:HAS_MEMORY]->(mem:Memory)
OPTIONAL MATCH (s)-[:USED_SKILL]->(sk:Skill)
RETURN mem.content AS client_facts, s.session_id AS last_session,
a.timestamp AS last_meeting_at, sk.name AS skill, sk.content AS how_to
RETURN s.session_id AS last_session, a.timestamp AS last_meeting_at,
collect(DISTINCT mem.content) AS memories, collect(DISTINCT sk.name) AS skills
```

`USER_ID` is the user ID from the setup. To see all the labels, relationship
types and properties the memory graph uses, run:
`USER_ID` is the user whose memory you read. To see all the labels,
relationship types and properties in the graph, run:

```cypher
SHOW SCHEMA INFO;
```

The Memgraph that the setup starts has schema info enabled. If you use your
own instance, start it with `--schema-info-enabled=true`.
This needs Memgraph started with `--schema-info-enabled=true`.

## Use another memory framework
To search memory by meaning as well as by its links, add a
[vector index](/querying/vector-search) on the memory text, and a
[text index](/querying/text-search) to search it by words.

If you already use an agent memory framework, you can keep it and store its
memory in Memgraph:
### Use Context Graph's packages

- [Mem0](/ai-ecosystem/integrations/mem0): Use Memgraph as the backend for Mem0
graph memory, in Mem0 1.x.
- [Cognee](/ai-ecosystem/integrations/cognee): Use Memgraph as the graph
database for Cognee's knowledge graph.
The packages Context Graph is built from are Python libraries you can use in
your own application. `actions-graph`, `skills-graph` and `sessions-graph`
write and read memory with the model above, so your application and your
coding agents can share one memory graph. See the
[Context Graph repository](https://github.com/memgraph/ai-toolkit/tree/main/context-graph)
for each package's API.
11 changes: 11 additions & 0 deletions pages/ai-ecosystem/ai-memory/_meta.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
export default {
"get-started": "Get started",
"recall-and-memory": "Recall and memory",
"explore-the-graph": "Explore the graph",
"privacy": "Privacy",
"configuration": "Configuration",
"knowledge-graph": "Knowledge graph",
"agents": "Agents",
"agent-sdk-apps": "Agent SDK apps",
"shared-spaces": "Shared spaces"
}
124 changes: 124 additions & 0 deletions pages/ai-ecosystem/ai-memory/agent-sdk-apps.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,124 @@
---
title: Agent SDK apps
description: Use Context Graph as the memory of an app built on the Claude Agent SDK or the OpenAI Agents SDK.
---

import { Tabs } from 'nextra/components'

# Agent SDK apps

An app built on the Claude Agent SDK or the OpenAI Agents SDK can use Context
Graph as its memory. The app gets what hooks and the MCP server give a coding
agent, inside its own process:

- **Recording:** the app's sessions are recorded, then embedded and reconciled
like coding-agent sessions.
- **Context:** each session starts with the memory index and
[where the user left off](/ai-ecosystem/ai-memory/recall-and-memory#where-you-left-off)
in the project.
- **Tools:** the [`recall`](/ai-ecosystem/ai-memory/recall-and-memory#recall)
and [`memory`](/ai-ecosystem/ai-memory/recall-and-memory#how-the-agent-uses-memory)
tools.

It's the same memory that the user's coding agents use.

## Install

The app reads the Memgraph connection, what is recorded and the
[privacy](/ai-ecosystem/ai-memory/privacy) settings from the
[configuration file](/ai-ecosystem/ai-memory/configuration#configuration-file),
the same as the hooks do. Run [setup](/ai-ecosystem/ai-memory/get-started)
first, or write the file with `memgraph-context-graph config set`.

The `memory` tool is offered only when Context Graph is the memory:

```bash
memgraph-context-graph config set memory.backend context-graph
```

Then install the package with the extra for your SDK, and the packages that
record actions and sessions:

<Tabs items={['Claude Agent SDK', 'OpenAI Agents SDK']}>
<Tabs.Tab>
```bash
pip install "memgraph-context-graph[claude]" "sessions-graph[memgraph-context-graph]" "actions-graph[memgraph-context-graph]"
```
</Tabs.Tab>
<Tabs.Tab>
```bash
pip install "memgraph-context-graph[openai]" "sessions-graph[memgraph-context-graph]" "actions-graph[memgraph-context-graph]"
```
</Tabs.Tab>
</Tabs>

## Connect the app

Create a `ContextGraphMemory` for the user whose memory it is:

```python
from memgraph_context_graph.sdk import ContextGraphMemory

memory = ContextGraphMemory(user_id="alice")
```

The app sets only `user_id` and `cwd`, the project directory. Without them,
Context Graph uses `identity.user_id` from the configuration file and the
current directory. In an app with many users, pass each user's ID, so that
each one recalls only their own sessions.

<Tabs items={['Claude Agent SDK', 'OpenAI Agents SDK']}>
<Tabs.Tab>
```python
from claude_agent_sdk import ClaudeSDKClient
from memgraph_context_graph.sdk.claude import ClaudeAgentMemory

claude = ClaudeAgentMemory(memory)
async with ClaudeSDKClient(claude.options(model="claude-sonnet-5-5")) as client:
await client.query("Which package manager does this project use?")
async for message in client.receive_response():
print(message)
claude.end_session()
```

`options()` takes the same arguments as `ClaudeAgentOptions`. It adds the
hooks that record the session, adds the `recall` and `memory` tools and allows
them, and turns off Claude Code's own auto memory. Hooks, MCP servers and
tools you pass are kept.

Don't add `"user"` to `setting_sources`. It would also load the Context Graph
Claude Code plugin, and every event would be recorded twice.
</Tabs.Tab>
<Tabs.Tab>
```python
from agents import Agent, Runner
from memgraph_context_graph.sdk.openai import OpenAIAgentsMemory

wired = OpenAIAgentsMemory(memory, session_id="chat-42")
agent = Agent(
name="Assistant",
instructions=wired.instructions("Be concise."),
tools=wired.tools(),
)
result = await Runner.run(agent, "Which package manager does this project use?", hooks=wired.hooks())
wired.end_session()
```

Use one `session_id` per conversation. `instructions()` adds the memory
context to your instructions, `tools()` returns `recall` and `memory` as
function tools, and `hooks()` records the run: the user's message, the model's
replies, tool calls and handoffs.
</Tabs.Tab>
</Tabs>

## End the session

Neither SDK reports when a session ends, so call `end_session()` when a
conversation is over. Context Graph then embeds the session's messages, so
recall can find them. Use `aend_session()` from async code.

## When Memgraph is down

Recording never fails the app. If Context Graph can't reach Memgraph, it stops
recording for 30 seconds before it tries again, so each call doesn't wait for
a connection timeout. If a tool fails, the model gets the error as text.
Loading
Loading