From 76db34dcc75807a5030c2d3cf945965a0f2c4b7c Mon Sep 17 00:00:00 2001 From: antejavor Date: Tue, 20 Oct 2026 12:18:52 +0200 Subject: [PATCH 01/11] add: Context Graph user docs under AI memory --- pages/ai-ecosystem/ai-memory.mdx | 52 ++--- pages/ai-ecosystem/ai-memory/_meta.ts | 3 + .../ai-ecosystem/ai-memory/context-graph.mdx | 91 ++++++++ .../ai-memory/context-graph/_meta.ts | 9 + .../ai-memory/context-graph/agents.mdx | 131 +++++++++++ .../ai-memory/context-graph/configuration.mdx | 162 ++++++++++++++ .../context-graph/explore-the-graph.mdx | 134 +++++++++++ .../ai-memory/context-graph/get-started.mdx | 194 ++++++++++++++++ .../context-graph/knowledge-graph.mdx | 182 +++++++++++++++ .../context-graph/recall-and-memory.mdx | 210 ++++++++++++++++++ .../ai-memory/context-graph/shared-spaces.mdx | 139 ++++++++++++ .../enabling-memgraph-enterprise.mdx | 7 + 12 files changed, 1275 insertions(+), 39 deletions(-) create mode 100644 pages/ai-ecosystem/ai-memory/_meta.ts create mode 100644 pages/ai-ecosystem/ai-memory/context-graph.mdx create mode 100644 pages/ai-ecosystem/ai-memory/context-graph/_meta.ts create mode 100644 pages/ai-ecosystem/ai-memory/context-graph/agents.mdx create mode 100644 pages/ai-ecosystem/ai-memory/context-graph/configuration.mdx create mode 100644 pages/ai-ecosystem/ai-memory/context-graph/explore-the-graph.mdx create mode 100644 pages/ai-ecosystem/ai-memory/context-graph/get-started.mdx create mode 100644 pages/ai-ecosystem/ai-memory/context-graph/knowledge-graph.mdx create mode 100644 pages/ai-ecosystem/ai-memory/context-graph/recall-and-memory.mdx create mode 100644 pages/ai-ecosystem/ai-memory/context-graph/shared-spaces.mdx diff --git a/pages/ai-ecosystem/ai-memory.mdx b/pages/ai-ecosystem/ai-memory.mdx index d1db91f22..079899ede 100644 --- a/pages/ai-ecosystem/ai-memory.mdx +++ b/pages/ai-ecosystem/ai-memory.mdx @@ -27,11 +27,11 @@ can recall facts, past actions and skills together. ## Set up memory for your coding agents -[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. +[Context Graph](/ai-ecosystem/ai-memory/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. You need [Docker](https://docs.docker.com/get-docker/), unless you already run Memgraph 3.6 or later, and a terminal. Start the setup: @@ -43,8 +43,7 @@ curl -sSL https://install.memgraph.com/ai-memory | bash ``` -Run the setup from WSL or Git Bash. In PowerShell, this command prints the -command to run there: +In PowerShell 5.1 or 7: ```powershell iwr https://install.memgraph.com/ai-memory/windows -useb | iex @@ -52,38 +51,13 @@ iwr https://install.memgraph.com/ai-memory/windows -useb | iex -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). +The setup shows its plan and changes nothing until you confirm. It finds or +starts Memgraph, installs Context Graph and connects the agents it finds. +After that, every session of a connected agent is recorded in the graph, and +the next session can recall it. + +See [Get started with Context Graph](/ai-ecosystem/ai-memory/context-graph/get-started) +for what the setup does, how to check it and how to change your choices. ## Query the memory graph diff --git a/pages/ai-ecosystem/ai-memory/_meta.ts b/pages/ai-ecosystem/ai-memory/_meta.ts new file mode 100644 index 000000000..13671a243 --- /dev/null +++ b/pages/ai-ecosystem/ai-memory/_meta.ts @@ -0,0 +1,3 @@ +export default { + "context-graph": "Context Graph" +} diff --git a/pages/ai-ecosystem/ai-memory/context-graph.mdx b/pages/ai-ecosystem/ai-memory/context-graph.mdx new file mode 100644 index 000000000..3a03e860b --- /dev/null +++ b/pages/ai-ecosystem/ai-memory/context-graph.mdx @@ -0,0 +1,91 @@ +--- +title: Context Graph +description: Give your coding agents a shared, long-term memory by recording their sessions as one graph in Memgraph that every agent can recall from. +--- + +# Context Graph + +Context Graph gives your coding agents a memory that lasts across sessions and +is shared between agents. It records each session of Claude Code, Codex, GitHub +Copilot CLI, Cursor, OpenCode, Antigravity CLI or Grok Build as a graph in +Memgraph: your prompts, the agent's replies, the tools it called, the skills it +used and the memories it saved. In the next session, any of those agents can +recall it. + +Context Graph is open source and part of the +[Memgraph AI Toolkit](https://github.com/memgraph/ai-toolkit/tree/main/context-graph). +It runs on your machine by default, with no account or cloud service. + +## What your agents get + +After setup, every connected agent gets three things: + +- **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), + finds what your past sessions hold about a question. A session also starts + with a short note on where you left off in the current project, whichever + agent you used last. +- **Memory.** If you turn it on, a `memory` tool replaces the agent's own + memory. The memories the agent saves are stored in the graph and shared by + all your agents. + +See [Recall and memory](/ai-ecosystem/ai-memory/context-graph/recall-and-memory) +for how each one works. + +## How the graph is organized + +Each session is a `Session` node, linked to its `User`. Everything recorded in +the session hangs off that node, so one Cypher query can span all of it: + +```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) +``` + +These are the three types of [AI memory](/ai-ecosystem/ai-memory): `Memory` +nodes are semantic memory, `Action` nodes are episodic memory and `Skill` +nodes are procedural memory. + +Context Graph can also extract the people, projects, files and decisions your +sessions mention into a [knowledge graph](/ai-ecosystem/ai-memory/context-graph/knowledge-graph), +linked back to the sessions that mention them. Recall uses it to find facts +across sessions. + +## Components + +Context Graph is a set of Python packages. Setup installs the ones you need, +so you only need this list to change what is recorded or to use a package in +your own application. + +| Package | What it records or does | +| --- | --- | +| `memgraph-context-graph` | The `memgraph-context-graph` command: setup, the hooks, the MCP server and the configuration. | +| `actions-graph` | Prompts, replies, tool calls and tool results, as `Action` nodes. | +| `skills-graph` | The agent skills a session used, as `Skill` nodes. | +| `sessions-graph` | Users, sessions and memories, the knowledge graph extracted from them, and recall. | +| `context-graph-viewer` | A read-only terminal viewer of the graph, opened with `memgraph-context-graph ui`. | +| `resources-graph` | GitHub issues, pull requests and repositories your agents read, so they can read them again from the graph. Off by default. | +| `context-graph-spaces` | [Shared spaces](/ai-ecosystem/ai-memory/context-graph/shared-spaces) for teams on Memgraph Enterprise. | + +## Pages in this section + +- [Get started](/ai-ecosystem/ai-memory/context-graph/get-started): Install + Context Graph and connect your agents with one command. +- [Agents](/ai-ecosystem/ai-memory/context-graph/agents): What setup changes + for each supported agent. +- [Recall and memory](/ai-ecosystem/ai-memory/context-graph/recall-and-memory): + How agents read their past sessions, and how to make Context Graph their + memory. +- [Configuration](/ai-ecosystem/ai-memory/context-graph/configuration): The + configuration file, a remote Memgraph, updates and uninstalling. +- [Knowledge graph](/ai-ecosystem/ai-memory/context-graph/knowledge-graph): + Extract entities and facts from your sessions. +- [Explore the graph](/ai-ecosystem/ai-memory/context-graph/explore-the-graph): + Look at what your agents recorded, in the terminal, in Memgraph Lab or with + Cypher. +- [Shared spaces](/ai-ecosystem/ai-memory/context-graph/shared-spaces): Share + memory between the members of a team. diff --git a/pages/ai-ecosystem/ai-memory/context-graph/_meta.ts b/pages/ai-ecosystem/ai-memory/context-graph/_meta.ts new file mode 100644 index 000000000..a7eac9148 --- /dev/null +++ b/pages/ai-ecosystem/ai-memory/context-graph/_meta.ts @@ -0,0 +1,9 @@ +export default { + "get-started": "Get started", + "agents": "Agents", + "recall-and-memory": "Recall and memory", + "configuration": "Configuration", + "knowledge-graph": "Knowledge graph", + "explore-the-graph": "Explore the graph", + "shared-spaces": "Shared spaces" +} diff --git a/pages/ai-ecosystem/ai-memory/context-graph/agents.mdx b/pages/ai-ecosystem/ai-memory/context-graph/agents.mdx new file mode 100644 index 000000000..ae35081b3 --- /dev/null +++ b/pages/ai-ecosystem/ai-memory/context-graph/agents.mdx @@ -0,0 +1,131 @@ +--- +title: Agents +description: See what Context Graph setup changes for Claude Code, Codex, GitHub Copilot CLI, Cursor, OpenCode, Antigravity CLI and Grok Build. +--- + +import { Tabs } from 'nextra/components' + +# Agents + +Context Graph works with seven coding agents. For each one, setup installs +hooks that record sessions, registers the MCP server that serves the `recall` +and `memory` tools, and can turn off the agent's own memory. This page lists +what setup changes for each agent, so you know which files it edits. + +## Supported agents + +| Agent | Runtime name | How it's connected | Applies to | +| --- | --- | --- | --- | +| Claude Code | `claude-code` | Context Graph plugin | Your user | +| Codex | `codex` | Context Graph plugin | Your user | +| GitHub Copilot CLI | `copilot-cli` | `.github/hooks/memgraph-context-graph.json` | One project | +| Cursor | `cursor` | `.cursor/hooks.json` | One project | +| OpenCode | `opencode` | `.opencode/plugins/memgraph-context-graph/index.js` | One project | +| Antigravity CLI | `antigravity-cli` | `.agents/hooks.json` | One project | +| Grok Build | `grok` | `.grok/hooks/memgraph-context-graph.json` | One project | + +Use the runtime name to choose agents in `memgraph-context-graph setup`, +`update`, `uninstall` and `doctor`. + +- **Claude Code and Codex** get the Context Graph plugin, installed for your + user. Every session of the agent is recorded, in any directory. +- **The other agents** get hook files in the project directory, never in your + home directory. Only sessions started in a connected project are recorded. + Setup connects the current directory; connect more projects with + `--project-dir`. If a hook file already exists, setup keeps your own hooks + in it. + +## MCP server registration + +The `recall` and `memory` tools are served by `memgraph-context-graph mcp`, an +MCP server named `context-graph`. Memory belongs to you, not to one project, +so the server is registered in each agent's user-level configuration: + +| Agent | Where the server is registered | How its tools are allowed | +| --- | --- | --- | +| Claude Code | The plugin | The plugin | +| Codex | The plugin | The plugin | +| GitHub Copilot CLI | `~/.copilot/mcp-config.json` | Copilot CLI has no allow list: approve the tools once, or start it with `--allow-tool=context-graph` | +| Cursor | `~/.cursor/mcp.json` | `Mcp(context-graph:*)` in `~/.cursor/cli-config.json` | +| OpenCode | `mcp.servers` in `~/.config/opencode/opencode.json` | An allow rule in `permissions` | +| Antigravity CLI | `~/.gemini/config/mcp_config.json` | `mcp(context-graph/*)` in `~/.gemini/antigravity-cli/settings.json` | +| Grok Build | `~/.grok/config.toml` | `MCPTool(context-graph__*)` | + +Setup adds the tools to the agent's allow list because an agent that runs +without a person, for example in a script, refuses a tool that needs approval. +Each file setup edits keeps the rest of its content and is backed up once, to +`FILE_NAME.context-graph.bak` next to it. + +## Built-in memory + +When you make Context Graph the agents' memory, setup turns off the agent's +own memory, so the agent doesn't keep two. Some agents have no memory of their +own to turn off. + +| Agent | Built-in memory | What setup changes | +| --- | --- | --- | +| Claude Code | Auto memory | Sets `autoMemoryEnabled: false` in `~/.claude/settings.json` and imports the existing memory files | +| Codex | Memories | Turns off `features.memories`, `memories.use_memories` and `memories.generate_memories` in `~/.codex/config.toml` and imports the existing memory | +| GitHub Copilot CLI | Copilot Memory, stored on GitHub | Sets `"memory": false` in `~/.copilot/settings.json`; the memory stays on GitHub and isn't imported | +| Cursor | None | Nothing | +| OpenCode | None | Nothing | +| Antigravity CLI | None in the CLI | Nothing | +| Grok Build | Topic notes in `~/.grok/memory-v2/` | Sets `[memory_v2] enabled = false` and imports the notes to `/memories/grok/` | + +See [Use Context Graph as your agents' memory](/ai-ecosystem/ai-memory/context-graph/recall-and-memory#use-context-graph-as-your-agents-memory) +for how the import works and how to switch back. + +## Differences between agents + +The agents' hooks don't all expose the same events, so some features work +differently: + +- **Session-start note.** Every agent gets the note on where you left off at + the start of a session. Grok Build's start hooks can't add text for the + model, so it gets the note through the MCP server's instructions instead. + Codex limits hook text to about 2,500 tokens, so a long memory index is cut + from its end. +- **Note before a tool call.** Only Claude Code and Codex can show the agent a + note just before a tool runs, such as that a GitHub issue it's about to + fetch is already in the graph. The other agents' pre-tool hooks can only + allow, block or rewrite the call. +- **End of a session.** Codex, Antigravity CLI and `opencode run` don't report + when a session ends. Their sessions are processed at the end of each turn + instead, so nothing is lost. +- **Antigravity CLI** hooks don't carry the prompt or reply text. Context Graph + reads the turns from the session transcript the agent writes. +- **Cursor:** the session-start note reaches the Cursor CLI. The agent window + in the Cursor editor may not show it to the model. +- **Codex** also reloads the memory index after it compacts the context. + +## Connect an agent manually + +Setup is the recommended way to connect agents. To install the Claude Code or +Codex plugin yourself, for example on a machine where you manage plugins by +hand: + + + +```bash +claude plugin marketplace add memgraph/ai-toolkit --sparse .claude-plugin +claude plugin install context-graph@context-graph-plugins -y +``` + + +```bash +codex plugin marketplace add memgraph/ai-toolkit --sparse .agents/plugins +codex plugin add context-graph@context-graph-plugins +``` + + + +For the per-project agents, `memgraph-context-graph hook init RUNTIME` writes +the hook file in the current directory, where `RUNTIME` is `copilot-cli`, +`cursor`, `opencode`, `antigravity-cli` or `grok`: + +```bash +memgraph-context-graph hook init cursor +``` + +`hook init` writes only the hooks. Run `memgraph-context-graph setup` for the +MCP server registration and the memory switch. diff --git a/pages/ai-ecosystem/ai-memory/context-graph/configuration.mdx b/pages/ai-ecosystem/ai-memory/context-graph/configuration.mdx new file mode 100644 index 000000000..cf5f6d24f --- /dev/null +++ b/pages/ai-ecosystem/ai-memory/context-graph/configuration.mdx @@ -0,0 +1,162 @@ +--- +title: Configure Context Graph +description: Configure Context Graph's Memgraph connection, identity and recorded data, and update or uninstall it for your coding agents. +--- + +import { Callout } from 'nextra/components' + +# Configure Context Graph + +Context Graph keeps its settings in one configuration file. This page covers +the file, connecting to your own Memgraph, choosing what is recorded, and +updating or removing Context Graph. + +## Configuration file + +Setup writes the configuration to `~/.config/context-graph/config.toml`, +readable only by you. Set the `CONTEXT_GRAPH_CONFIG` environment variable to +use another path. + +The hooks read their settings only from this file, not from environment +variables, because agents run hooks without your shell's environment. Change +settings with the `config` command: + +```bash +memgraph-context-graph config show +memgraph-context-graph config get memgraph.url +memgraph-context-graph config set identity.user_id alice +``` + +`config set` takes these keys: + +| Key | Default | What it sets | +| --- | --- | --- | +| `identity.user_id` | Your git `user.name`, set by setup | Your user ID. Your sessions and memories are filed under it, and recall searches only its sessions. | +| `memgraph.url` | `bolt://localhost:7687` | The Memgraph Bolt URL | +| `memgraph.user` | Empty | The Memgraph user name | +| `memgraph.password` | Empty | The Memgraph password. `config set memgraph.password` without a value prompts for it. | +| `memgraph.database` | `memgraph` | The database, on a Memgraph with [multi-tenancy](/database-management/multi-tenancy) | +| `capture.connectors` | `skills-graph, actions-graph, sessions-graph` | What the hooks record. See [Choose what is recorded](#choose-what-is-recorded). | +| `memory.backend` | Unset | `context-graph` when Context Graph is the agents' [memory](/ai-ecosystem/ai-memory/context-graph/recall-and-memory#use-context-graph-as-your-agents-memory). Set it with setup's `--memory-backend`, which also changes the agents' settings. | +| `session_start.resume` | `true` | Whether a session starts with the [note on where you left off](/ai-ecosystem/ai-memory/context-graph/recall-and-memory#where-you-left-off) | +| `recall.embedding_model` | `BAAI/bge-small-en-v1.5` | The embedding model for recall | +| `reconcile.auto_reconcile` | `false` | Whether the [knowledge graph](/ai-ecosystem/ai-memory/context-graph/knowledge-graph) is built after each session | +| `ontology.path` | Unset | A schema file for the knowledge graph | +| `ontology.derive` | `extend` | Whether Context Graph adds types to your schema: `extend` or `off` | +| `llm.anthropic_api_key` | Empty | An Anthropic API key, used only to learn your schema | +| `llm.openai_api_key` | Empty | An OpenAI API key, used only to learn your schema | +| `llm.derive_model` | `claude-sonnet-5-5` with Anthropic, `gpt-5` with OpenAI | The model that learns your schema | +| `edition` | `community` | `enterprise` to use [shared spaces](/ai-ecosystem/ai-memory/context-graph/shared-spaces). Set it with `memgraph-context-graph join`. | +| `github.token` | Unset | A GitHub token for `resources-graph`, used instead of your `gh` login. Prompts for the value. | + +Recall's other settings and the `[extraction]` settings are edited in the file +directly. See [Tune recall](/ai-ecosystem/ai-memory/context-graph/recall-and-memory#tune-recall) +and [Tune extraction](/ai-ecosystem/ai-memory/context-graph/knowledge-graph#tune-extraction). + + +The file holds your Memgraph password and API keys in plain text. Setup +creates it with permissions `0600`; keep it that way. + + +## Use your own Memgraph + +By default, setup starts Memgraph in Docker on your machine. To use another +Memgraph, such as a shared server or a +[high availability cluster](/database-management/clustering/high-availability), +pass its URL to setup: + +```bash +memgraph-context-graph setup --memgraph-url bolt://memgraph.example.com:7687 +``` + +If the instance has authentication, set the user and password: + +```bash +memgraph-context-graph config set memgraph.user alice +memgraph-context-graph config set memgraph.password +``` + +For a high availability cluster, use the `neo4j://` scheme with a coordinator's +address, so the client routes writes to the MAIN instance: + +```bash +memgraph-context-graph config set memgraph.url neo4j://coordinator.example.com:7687 +``` + +The instance must run Memgraph 3.6 or later, with +[MAGE](/advanced-algorithms) for recall by meaning. To see all labels and +properties with `SHOW SCHEMA INFO`, start it with `--schema-info-enabled=true`. +The Memgraph that setup starts has it enabled. + +Each user on a shared Memgraph should have their own `identity.user_id`. On a +shared Memgraph with Memgraph Enterprise, [shared spaces](/ai-ecosystem/ai-memory/context-graph/shared-spaces) +give each user a database of their own. + +## Choose what is recorded + +`capture.connectors` lists the packages the hooks send events to. Each one +records one part of a session: + +| Connector | Records | +| --- | --- | +| `actions-graph` | Prompts, replies, tool calls and tool results | +| `skills-graph` | The agent skills a session used | +| `sessions-graph` | The session, its user and project, and memories. Recall needs it. | +| `resources-graph` | The GitHub resources a session read. Off by default. | + +For example, to also remember GitHub resources: + +```bash +memgraph-context-graph config set capture.connectors "skills-graph, actions-graph, sessions-graph, resources-graph" +memgraph-context-graph setup +``` + +Setup installs the connectors the setting names. An empty value records +nothing, without disconnecting the agents. + +## Update Context Graph + +`update` upgrades the packages, then refreshes everything setup installed: the +Claude Code and Codex plugins, the hook files and MCP registrations of the +per-project agents, and the indexes and constraints in Memgraph. + +```bash +memgraph-context-graph update +``` + +- **Choose agents** by naming them: `memgraph-context-graph update cursor`. +- **Choose projects** for the per-project agents with `--project-dir`. The + default is the current directory. +- **Skip the upgrade** with `--no-upgrade`, to only refresh what setup + installed. + +`update` doesn't change your own hooks, the configuration file or the data in +the graph, and running it twice changes nothing. Restart running agent +sessions afterwards, because they keep the hooks they started with. + +## Uninstall Context Graph + +`uninstall` disconnects your agents: it removes the plugins, hook files and MCP +registrations, and turns the agents' own memory back on. + +```bash +memgraph-context-graph uninstall +``` + +Name agents to disconnect only those, and pass `--project-dir` for projects +other than the current directory. + +The graph, the configuration file and the `memgraph-context-graph` command +stay, and `uninstall` prints how to remove each of them. To also remove the +Memgraph that setup started, together with its data, remove its container and +volume: + +```bash +docker rm -f context-graph-memgraph +docker volume rm context-graph-memgraph-data +``` + + +Removing the volume deletes everything your agents recorded, including your +memories. + diff --git a/pages/ai-ecosystem/ai-memory/context-graph/explore-the-graph.mdx b/pages/ai-ecosystem/ai-memory/context-graph/explore-the-graph.mdx new file mode 100644 index 000000000..663256717 --- /dev/null +++ b/pages/ai-ecosystem/ai-memory/context-graph/explore-the-graph.mdx @@ -0,0 +1,134 @@ +--- +title: Explore the graph +description: Look at what your coding agents recorded in Context Graph, with the terminal viewer, Memgraph Lab or Cypher queries. +--- + +# Explore the graph + +Everything Context Graph records is an ordinary graph in Memgraph, so you can +look at it three ways: in the terminal viewer, in +[Memgraph Lab](/memgraph-lab), or with your own Cypher queries. + +## Terminal viewer + +The terminal viewer shows what your agents recorded, whether recording is +failing, and what the knowledge graph learned, without writing a query: + +```bash +memgraph-context-graph ui +``` + +It reads the same configuration file as the hooks, refreshes every few +seconds, and never writes to the graph. Setup installs it unless you pass +`--no-viewer`. + +| View | How to open it | What it shows | +| --- | --- | --- | +| Dashboard | Opens first | Your sessions, failed recordings, pending extraction and embedding work, the schema version, and new entities per day | +| Session | `enter` on a session | The session's timeline, with subagents under the call that started them, each action's input, and the entities and memory files the session produced | +| Entities | `k` on the dashboard, `g` on a session | Entities by name, by how many sessions and memory files mention them, or by most recent | +| Neighborhood | `enter` on an entity | The entity's relationships by type, with the text each one was read from. `enter` on a neighbor moves to it; `esc` goes back | + +The most useful keys: + +| Key | What it does | +| --- | --- | +| `a` | Show more sessions: yours, then also sessions without a user, then everyone's | +| `p` | Show one project only | +| `/` | Filter the table | +| `r` | Refresh now | +| `?` | Show all keys | +| `esc`, `q` | Go back, quit | + +The viewer shows your own sessions by default. Sessions recorded before you +had a user ID belong to no user. If the dashboard is empty, press `a`. + +## Memgraph Lab + +To see the graph itself, connect [Memgraph Lab](/memgraph-lab) to the Memgraph +in your configuration. Print its URL with: + +```bash +memgraph-context-graph config get memgraph.url +``` + +Connect Lab to that host and port. If you run Lab in Docker, the Memgraph +on your machine isn't at `localhost` inside the Lab container: + +- **macOS and Windows:** start Lab with + `docker run -d --name memgraph-lab -p 3000:3000 memgraph/lab:latest`, open + `http://localhost:3000`, and connect to host `host.docker.internal`. +- **Linux:** start Lab with + `docker run -d --name memgraph-lab --network host memgraph/lab:latest`, open + `http://localhost:3000`, and connect to host `localhost`. + +## Query the graph + +The graph uses these labels and relationship types: + +| Node | What it is | +| --- | --- | +| `User` | You, by `user_id` | +| `Session` | One agent session, by `session_id`, with its `project_key` and `started_at` | +| `Action` | A prompt, reply, tool call or tool result | +| `Skill` | An agent skill | +| `Memory` | A memory file, by `path` | +| `Project` | A project the memory files are about, by `key` | +| `Chunk` | A piece of a message or memory file that entities were extracted from | +| Entity labels | An extracted entity, with its name in `text`, its type in `entity_type` and a label for the type, such as `Person` | + +To see every label, relationship type and property, run: + +```cypher +SHOW SCHEMA INFO; +``` + +This needs Memgraph started with `--schema-info-enabled=true`; the Memgraph +setup starts has it. + +The queries below are templates. Replace `USER_ID` with your user ID from +`memgraph-context-graph config get identity.user_id`. + +Your ten most recent sessions, with the number of actions in each: + +```cypher template +MATCH (:User {user_id: "USER_ID"})-[:HAD_SESSION]->(s:Session) +OPTIONAL MATCH (s)-[:HAS_ACTION]->(a:Action) +RETURN s.session_id, s.project_key, s.started_at, count(a) AS actions +ORDER BY s.started_at DESC +LIMIT 10; +``` + +The skills you used most: + +```cypher template +MATCH (:User {user_id: "USER_ID"})-[:HAD_SESSION]->(:Session)-[:USED_SKILL]->(sk:Skill) +RETURN sk.name, count(*) AS uses +ORDER BY uses DESC; +``` + +Your memory files: + +```cypher template +MATCH (:User {user_id: "USER_ID"})-[:HAS_MEMORY]->(m:Memory) +RETURN m.path, m.updated_at +ORDER BY m.path; +``` + +The sessions in which a tool was called: + +```cypher template +MATCH (:User {user_id: "USER_ID"})-[:HAD_SESSION]->(s:Session)-[:HAS_ACTION]->(a:Action {tool_name: "TOOL_NAME"}) +RETURN DISTINCT s.session_id; +``` + +The entities your sessions mention most, after you +[build the knowledge graph](/ai-ecosystem/ai-memory/context-graph/knowledge-graph): + +```cypher template +MATCH (:User {user_id: "USER_ID"})-[:HAD_SESSION]->(:Session)-[:HAS_ACTION]->(:Action) + -[:HAS_CHUNK]->(:Chunk)<-[:MENTIONED_IN]-(e) +RETURN e.text, e.entity_type, count(*) AS mentions +ORDER BY mentions DESC +LIMIT 20; +``` diff --git a/pages/ai-ecosystem/ai-memory/context-graph/get-started.mdx b/pages/ai-ecosystem/ai-memory/context-graph/get-started.mdx new file mode 100644 index 000000000..4089a5d52 --- /dev/null +++ b/pages/ai-ecosystem/ai-memory/context-graph/get-started.mdx @@ -0,0 +1,194 @@ +--- +title: Get started with Context Graph +description: Install Context Graph with one command, connect your coding agents to Memgraph, and check that their sessions are recorded and recalled. +--- + +import { Tabs } from 'nextra/components' + +# Get started with Context Graph + +One command installs Context Graph, finds or starts Memgraph, and connects +every coding agent it finds on your machine. Setup shows its plan and changes +nothing until you confirm. + +## Prerequisites + +- **A terminal.** Setup asks its questions there. +- **Docker**, unless you already run Memgraph. Setup starts Memgraph in a + container. See [Get Docker](https://docs.docker.com/get-docker/). +- **Your own Memgraph, if you don't use Docker:** Memgraph 3.6 or later. For + recall by meaning, use the [MAGE](/advanced-algorithms) image + (`memgraph/memgraph-mage`) with at least 2 GiB of memory; without MAGE, + recall falls back to text search. +- **At least one supported agent** on your `PATH`: Claude Code, Codex, GitHub + Copilot CLI, Cursor, OpenCode, Antigravity CLI or Grok Build. + +You don't need Python. Setup installs [uv](https://docs.astral.sh/uv/) if it's +missing, and uv installs the rest. + +## 1. Run setup + +Run setup from the project directory you work in. Claude Code and Codex are +connected for your user, but the other agents are connected one project at a +time, starting with the current directory. + + + +```bash +curl -sSL https://install.memgraph.com/ai-memory | bash +``` + + +In PowerShell 5.1 or 7: + +```powershell +iwr https://install.memgraph.com/ai-memory/windows -useb | iex +``` + +If Windows blocks the script, allow scripts for the current session first: + +```powershell +Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass +``` + + + +Setup lists what it found and what it will do: + +- **Agents:** the agents on your `PATH`, ticked. Untick any you don't want + connected. +- **Memgraph:** the one it will use or start. +- **Name:** your user ID in the graph. Your memories are filed under it. It + defaults to your git `user.name`, or your system user name. +- **Memory:** whether your agents use Context Graph as their memory instead of + their own. See [Use Context Graph as your agents' memory](/ai-ecosystem/ai-memory/context-graph/recall-and-memory#use-context-graph-as-your-agents-memory). + +The plan updates as you change your choices. Nothing changes until you press +**Install**. + +Without a terminal, for example in CI, the install command only prints the +setup command to run. Set `AI_MEMORY_SKIP_SETUP=1` to get the same behavior on +a terminal. + +## 2. What setup does + +Setup runs these steps in order. Each step checks first, so running setup +again only does what's missing. + +1. **Finds or starts Memgraph.** Setup uses the Memgraph in its configuration + file, then a Memgraph on `localhost:7687`. Otherwise, it starts the + `memgraph/memgraph-mage` image in a container named + `context-graph-memgraph`, with a data volume, listening on `127.0.0.1` + only. If port 7687 is taken, it picks a free port. +2. **Saves the configuration:** the Memgraph URL and your user ID, in + `~/.config/context-graph/config.toml`. +3. **Installs the packages:** the `memgraph-context-graph` command, the + packages that record actions, skills and sessions, and the terminal viewer. +4. **Connects your agents.** See [Agents](/ai-ecosystem/ai-memory/context-graph/agents) + for what changes for each one. +5. **Checks the setup,** the same way as + [`memgraph-context-graph doctor`](#3-check-the-setup). + +The report ends with the command to rerun for any step that failed. + +## 3. Check the setup + +Restart any agent sessions that were running during setup, because a running +session keeps the hooks it started with. Then check the setup: + +```bash +memgraph-context-graph doctor --runtime claude-code +``` + +Replace `claude-code` with the agent you want to check: `codex`, +`copilot-cli`, `cursor`, `opencode`, `antigravity-cli` or `grok`. Every line +starts with `OK` when the setup works: + +```plaintext copy=false +OK memgraph-context-graph executable: ... +OK memgraph-context-graph: ... +OK config: identity.user_id set +OK memgraph: reachable +OK connector:skills-graph: installed=...; memgraph=reachable +OK connector:actions-graph: installed=...; memgraph=reachable +OK connector:sessions-graph: installed=...; memgraph=reachable +OK embeddings: BAAI/bge-small-en-v1.5 (384 dimensions) inside Memgraph +OK mcp: serves recall +OK runtime:claude-code: strict hook smoke passed +``` + +A line that starts with `FAIL` says what failed. The `embeddings` check fails +on a Memgraph without MAGE; recall then uses text search only. + +## 4. Use your agents + +Work with your agents as before. Every session is recorded in the graph as it +happens. To see it, open the terminal viewer: + +```bash +memgraph-context-graph ui +``` + +In a new session, ask the agent about earlier work, for example "what did we +decide about the deploy window?". The agent calls the `recall` tool and +answers from your past sessions. You can run the same search yourself: + +```bash +memgraph-context-graph recall "what did we decide about the deploy window?" +``` + +## Choose agents and options + +Every choice in setup is also a flag of `memgraph-context-graph setup`. After +the first install, run setup again with flags to change your choices: + +```bash +memgraph-context-graph setup codex --memgraph-url bolt://memgraph.example.com:7687 +``` + +To pass flags on the first install, run Context Graph's install script and +add them after `bash -s --`: + +```bash +curl -fsSL https://raw.githubusercontent.com/memgraph/ai-toolkit/main/context-graph/scripts/install.sh | bash -s -- codex --memgraph-url bolt://memgraph.example.com:7687 +``` + +| Flag | What it sets | +| --- | --- | +| `RUNTIME ...` | The agents to connect: `claude-code`, `codex`, `copilot-cli`, `cursor`, `opencode`, `antigravity-cli` or `grok`. The default is every agent on your `PATH`. | +| `--project-dir DIR` | A project to connect the per-project agents in. Repeat it for more projects. The default is the current directory. | +| `--memgraph-url URL` | The Memgraph to use, instead of finding or starting one. | +| `--user-id NAME` | Your user ID in the graph. The default is the configured one, then your git `user.name`. | +| `--memory-backend context-graph` | Make Context Graph the agents' memory. `native` gives memory back to the agent. | +| `--memgraph-container NAME` | The container to find or start. The default is `context-graph-memgraph`. | +| `--no-viewer` | Don't install the terminal viewer. | +| `--plan` | Print what setup would do and change nothing. | +| `--no-tui` | Print plain output, even on a terminal. | + +On Windows, the piped command can't take arguments. Set them in +`CONTEXT_GRAPH_SETUP_ARGS` first: + +```powershell +$env:CONTEXT_GRAPH_SETUP_ARGS = 'codex --user-id alice' +iwr https://install.memgraph.com/ai-memory/windows -useb | iex +``` + +To connect another project for the per-project agents, run setup from that +project, or pass `--project-dir`: + +```bash +memgraph-context-graph setup cursor --project-dir ~/work/billing --project-dir ~/work/crawler +``` + +## Next steps + +- [Recall and memory](/ai-ecosystem/ai-memory/context-graph/recall-and-memory): + How your agents read their past sessions. +- [Configuration](/ai-ecosystem/ai-memory/context-graph/configuration): Use a + remote Memgraph, update Context Graph, or uninstall it. +- [Explore the graph](/ai-ecosystem/ai-memory/context-graph/explore-the-graph): + Look at what your agents recorded. + +If setup fails in a way the report doesn't explain, ask on +[Discord](https://discord.gg/memgraph) or open an issue on +[GitHub](https://github.com/memgraph/ai-toolkit/issues). diff --git a/pages/ai-ecosystem/ai-memory/context-graph/knowledge-graph.mdx b/pages/ai-ecosystem/ai-memory/context-graph/knowledge-graph.mdx new file mode 100644 index 000000000..911c08a10 --- /dev/null +++ b/pages/ai-ecosystem/ai-memory/context-graph/knowledge-graph.mdx @@ -0,0 +1,182 @@ +--- +title: Knowledge graph from sessions +description: Extract the people, projects and facts your agent sessions mention into a knowledge graph in Memgraph, and control its schema. +--- + +# Knowledge graph from sessions + +Context Graph can extract the entities your sessions mention, such as people, +organizations, projects and tools, and the facts that connect them, into a +knowledge graph. Each entity links back to the messages and memory files it +came from. Recall uses the knowledge graph to find facts that are spread over +many sessions. + +Extraction runs on your machine with [GLiNER2](https://github.com/fastino-ai/GLiNER2), +a local extraction model, and needs no LLM API key. This process is called +**reconciliation**. + +## Install the extraction packages + +Setup doesn't install the extraction model, because it's large. Add it to the +`memgraph-context-graph` tool, together with the `sessions-graph` command: + +```bash +uv tool install --force 'memgraph-context-graph[mcp]' \ + --with 'skills-graph[memgraph-context-graph]' \ + --with 'actions-graph[memgraph-context-graph]' \ + --with 'sessions-graph[memgraph-context-graph,reconciliation]' \ + --with context-graph-viewer \ + --with-executables-from sessions-graph +``` + +The first extraction downloads the model. + +## Build the knowledge graph + +When a session ends, Context Graph marks it as pending reconciliation. To +extract every pending session: + +```bash +sessions-graph reconcile --pending +``` + +To extract one session, pass its ID: + +```bash +sessions-graph reconcile --session SESSION_ID +``` + +`SESSION_ID` is the `session_id` property of the `Session` node. The terminal +viewer shows it for each session. + +Extraction takes longer than an agent allows a hook to run, so it never runs +inside a hook. Choose how it runs: + +- **After each session,** in a background process: + + ```bash + memgraph-context-graph config set reconcile.auto_reconcile true + ``` + + If the background process stops, the session stays pending, and the next + `reconcile --pending` extracts it. +- **On a schedule,** with `sessions-graph reconcile --pending --limit 50` in + cron or another scheduler. `--limit` caps how many sessions one run + extracts. + +Codex, Antigravity CLI and `opencode run` don't report when a session ends. +Their sessions are marked pending at the end of each turn, so +`reconcile --pending` extracts them too. + +Memory files are extracted on their own, because a file outlives the session +that wrote it. Each change to a file marks it pending, and +`reconcile --pending` extracts pending files before sessions. When a file +changes or is deleted, Context Graph first removes what its previous text +produced. + +## What reconciliation writes + +Reconciliation splits the text of a session's messages, tool calls and memory +files into `Chunk` nodes and extracts entities from them: + +```plaintext copy=false +(:Action)-[:HAS_CHUNK]->(:Chunk)<-[:MENTIONED_IN]-(:Entity) +(:Memory)-[:HAS_CHUNK]->(:Chunk) +``` + +Each entity gets a label for its type from your schema, such as `Person` or +`Organization`. An entity of a type outside the schema is kept, with the +property `ontology_conformant` set to `false`. Facts are relationships between +entities, typed by the schema, with the sentence they were read from. + +An entity mentioned in several sessions is one node, so its relationships +connect the sessions that mention it. Content seen before isn't extracted +again. + +Reconciliation also computes the embeddings recall uses for the new entities +and facts. Messages are embedded at the end of every turn, whether or not you +build the knowledge graph. + +## Schema + +Entities are extracted under a schema, called an **ontology**: the entity +types and relationship types to look for. Every user starts with a default +schema. It has people, organizations, locations and events, value types such +as dates and amounts, and two catch-all types, `Topic` and `Artifact`. + +### Use your own schema + +To extract the types that matter in your work, write a schema file and set it +in the configuration: + +```bash +memgraph-context-graph config set ontology.path ~/schemas/coding.yaml +``` + +The schema file uses the format of the +[HyGM manual strategy](https://github.com/memgraph/ai-toolkit/tree/main/hygm). +The next `sessions-graph reconcile` applies the file, and applies it again +whenever it changes. If the file isn't valid, reconcile reports it and keeps +the current schema. + +`ontology.derive` sets what may happen to your schema afterwards: + +- **`extend`** (the default): your types are kept as written, together with + the default core types, and Context Graph may add types next to them. +- **`off`:** the schema is used exactly as written, and no types are added. + +To see the schema in use: + +```bash +sessions-graph ontology show +``` + +### Learn the schema from your sessions + +With an LLM API key in the configuration, Context Graph learns new types from +your sessions: + +```bash +memgraph-context-graph config set llm.anthropic_api_key +``` + +`config set` prompts for the key. With `llm.openai_api_key` instead, the +default model is `gpt-5`; set another model with `llm.derive_model`. + +Learning starts on its own when you have 2, 4, 8 and so on up to 128 sessions +with enough of your own text (at least 2 of your messages and 1,000 +characters), and then every 128 sessions. Each run reads up to 64 recent +sessions, proposes new schemas, and keeps one only if it types more of your +messages without adding more catch-all entities. To run it now: + +```bash +sessions-graph derive --force +``` + +Each schema is stored as an `OntologyVersion` node, and `sessions-graph +ontology show` shows the one in use. Without an API key, the schema doesn't +change, and extraction still works. + +## Tune extraction + +The `[extraction]` section of the configuration file sets how sessions are +read. Edit it in the file; all keys are optional: + +| Key | Default | What it sets | +| --- | --- | --- | +| `model` | `fastino/gliner2.5-base-v1` | The GLiNER2 model | +| `entity_threshold` | GLiNER2's default | The lowest confidence, from 0 to 1, at which an entity is kept | +| `relation_threshold` | GLiNER2's default | The lowest confidence, from 0 to 1, at which a fact is kept | +| `chunk_size` | GLiNER2's default | Words per chunk | +| `chunk_overlap` | GLiNER2's default | Words shared by neighboring chunks | + +For example: + +```toml +[extraction] +model = "fastino/gliner2.5-base-v1" +entity_threshold = "0.3" +``` + +Reconciliation and schema learning use the same settings, so a session is +always read the same way. diff --git a/pages/ai-ecosystem/ai-memory/context-graph/recall-and-memory.mdx b/pages/ai-ecosystem/ai-memory/context-graph/recall-and-memory.mdx new file mode 100644 index 000000000..2a71a4c90 --- /dev/null +++ b/pages/ai-ecosystem/ai-memory/context-graph/recall-and-memory.mdx @@ -0,0 +1,210 @@ +--- +title: Recall and memory +description: Let coding agents recall their past sessions from Memgraph, and make Context Graph their long-term memory shared across agents. +--- + +import { Callout } from 'nextra/components' + +# Recall and memory + +Context Graph gives your agents two ways to use what earlier sessions left +behind. **Recall** searches everything your sessions recorded and returns what +matches a question. **Memory** is the set of notes the agent chooses to keep, +such as your preferences and project decisions, loaded at the start of every +session. + +Recall works as soon as setup finishes. Memory is opt-in, because it replaces +the agent's own memory. + +## Recall + +The `recall` tool takes one argument, a question, and returns the parts of +your past sessions that match it: dated messages, and facts extracted from +them. It doesn't answer the question; the agent's model answers from what +recall returns. The results come with a short header that tells the model how +to read them, for example that a later message about the same thing replaces +an earlier one. + +Recall searches only your own sessions. Your user ID comes from the +configuration file, never from the tool call, so an agent can't read another +user's sessions. + +Recall combines several searches over your history: + +| Search | What it finds | +| --- | --- | +| Memories | [Memory files](#use-context-graph-as-your-agents-memory) that match by meaning or by words, shown first | +| Messages by meaning | Messages closest to the question, by vector search | +| Messages by words | Messages that match the question's words, by text search | +| Entities | People, projects and other entities that match, with their facts | +| Facts | Extracted facts that match, with the messages they came from | +| Facts about you | All facts of the types that match, for questions that count or list things | + +Entities and facts come from the [knowledge graph](/ai-ecosystem/ai-memory/context-graph/knowledge-graph). +Before it's built, recall finds messages and memories only. + +The searches by meaning need [MAGE](/advanced-algorithms): Memgraph computes +the embeddings itself with the +[`embeddings` module](/advanced-algorithms/available-algorithms/embeddings), +so no model runs on your machine. On Memgraph without MAGE, recall uses text +search only and says so in its results. + +### Ask from the terminal + +The `recall` command runs the same search: + +```bash +memgraph-context-graph recall "which database did we pick for the cache?" +``` + +Add `--json` to get the messages and facts as JSON. + +### Where you left off + +At the start of each session, the agent gets a short note about the current +project: + +- that the `recall` tool exists; +- your last session in this project: its date, the agent, your first and last + request, and the agent's last reply; +- your first request in each of the two sessions before it. + +Sessions from every agent count, so a session in Grok Build can continue where +one in Codex stopped. The note quotes your sessions; it isn't a search, so the +agent still calls `recall` when it needs more. + +A project is identified by its git `origin` remote, so all clones of a +repository count as one project. Without a remote, the directory name is used. + +To turn the note off: + +```bash +memgraph-context-graph config set session_start.resume false +``` + +### Tune recall + +Recall's defaults are the settings it was evaluated with. To change how many +results each search returns, or to drop a search, edit the `[recall]` section +of the [configuration file](/ai-ecosystem/ai-memory/context-graph/configuration#configuration-file): + +| Key | Default | What it sets | +| --- | --- | --- | +| `embedding_model` | `BAAI/bge-small-en-v1.5` | The model Memgraph computes embeddings with | +| `lanes` | All six | The searches to run, as a comma-separated subset of `memories`, `turns`, `text`, `entities`, `facts` and `user_facts` | +| `memories_k` | `5` | Memory files returned | +| `turns_k` | `8` | Messages found by meaning | +| `text_k` | `8` | Messages found by words | +| `entities_k` | `15` | Entities matched | +| `edges_per_entity` | `6` | Facts read from each matched entity | +| `facts_k` | `15` | Facts matched | +| `fact_turns_k` | `8` | Messages added for the matched facts | +| `user_fact_types` | `2` | Fact types gathered in full, for questions that count or list things | +| `user_facts_k` | `30` | Facts returned for those types | +| `turn_chars` | `1500` | Characters shown per message | +| `query_instruction` | Depends on the model | Text added before the question when it's embedded. The English `bge` models get their retrieval instruction; other models get none | + +When you change `embedding_model`, Context Graph computes the embeddings again +with the new model. Embeddings from two models are never mixed. The default +model needs Memgraph with at least 2 GiB of memory, and Memgraph downloads it +on first use. + +## Use Context Graph as your agents' memory + +Agents such as Claude Code and Codex keep their own memory: notes they save +and read at the start of a session. You can make Context Graph that memory +instead. Your memories are then stored in Memgraph, shared by all your agents +and searched by recall. + +Turn it on for an agent with setup: + +```bash +memgraph-context-graph setup claude-code --memory-backend context-graph +``` + +The interactive setup offers the same switch as a checkbox. For each agent, +setup: + +1. **Imports the agent's existing memory,** once. Claude Code's user and + feedback memories go to `/memories/user/` and `/memories/feedback/`, and + project memories go to that project's folder. Codex's memory summary + becomes `/memories/user/codex-memory-summary.md`. A file already in the + graph is never overwritten. +2. **Turns off the agent's own memory,** as listed in + [Agents](/ai-ecosystem/ai-memory/context-graph/agents#built-in-memory). + Setup backs up each file it edits. +3. **Saves the choice** as `backend = "context-graph"` in the `[memory]` + section of the configuration file. + +If the import can't run, for example because Memgraph isn't reachable, setup +doesn't turn off the agent's memory. The change shows from the next session, +because agents list their tools when a session starts. + +### How the agent uses memory + +With the switch on, the MCP server also serves a `memory` tool. It has the +commands of the +[Claude memory tool](https://docs.claude.com/en/docs/agents-and-tools/tool-use/memory-tool): +`view`, `create`, `str_replace`, `insert`, `delete` and `rename`, on files +under `/memories`. The agent keeps two kinds of files: + +- **`/memories/`** for what applies everywhere, such as your preferences. +- **`/memories/projects/PROJECT/`** for one codebase, where `PROJECT` is the + project's key, such as `github.com_memgraph_ai-toolkit`. + +Each file is a `Memory` node in your graph. At the start of a session, the +agent gets: + +- an index of the files in `/memories/` and in the current project's folder, + one line per file, up to 200 lines; +- the full text of every file whose frontmatter has `pin: true`; +- the name of the current project's folder. + +The index is built from the graph each time, so it's never out of date. + +### Rules for memory files + +- A file can't be empty or larger than 100 KB. +- An edit applies only if the file still holds the text the edit was made + from. If another session changed the file in between, the edit fails + instead of overwriting that change. +- Context Graph keeps the last 20 versions of each file. Overwriting, editing + or deleting a file saves its previous text first, as a `MemoryVersion` node. + + +Without the switch, the `memory` tool isn't listed, and the agent keeps using +its own memory. Recall works either way. + + +### Switch back + +To give memory back to the agent: + +```bash +memgraph-context-graph setup claude-code --memory-backend native +``` + +The agent's own memory is turned on again. The memories in the graph stay +where they are, and recall still finds them. `memgraph-context-graph uninstall` +also turns the agent's own memory back on. + +## Remember GitHub resources + +The optional `resources-graph` package remembers the public GitHub issues, +pull requests and repositories your agents read, so they can read them from +the graph instead of fetching them again. Turn it on in +[Configuration](/ai-ecosystem/ai-memory/context-graph/configuration#choose-what-is-recorded). + +When it's on: + +1. The hooks record which GitHub addresses a session fetched or mentioned. + They never call GitHub. +2. `resources-graph sweep` fetches those addresses and stores them in the + graph. Run it after a session or on a schedule. It uses your `gh` login, or + a token set with `memgraph-context-graph config set github.token`. +3. The agent reads a stored issue or pull request with the `resource` tool, + which returns it with the time it was fetched. The agent decides whether + that's recent enough. + +Claude Code and Codex also get a note just before they fetch something that's +already in the graph. The fetch still runs. diff --git a/pages/ai-ecosystem/ai-memory/context-graph/shared-spaces.mdx b/pages/ai-ecosystem/ai-memory/context-graph/shared-spaces.mdx new file mode 100644 index 000000000..1289cf5ae --- /dev/null +++ b/pages/ai-ecosystem/ai-memory/context-graph/shared-spaces.mdx @@ -0,0 +1,139 @@ +--- +title: Shared spaces +description: Run Context Graph for a team on one Memgraph Enterprise instance, with a personal space for each user and shared spaces for team memory. +--- + +import { Callout } from 'nextra/components' + +# Shared spaces Enterprise + +Shared spaces let a team run Context Graph on one Memgraph. Each user gets a +**personal space**, a database only they can read, and teams get **shared +spaces**, databases whose members read and write the same memory files. An +agent can save a decision to a shared space, and every member's agents recall +it. + +Shared spaces need [Memgraph Enterprise](/database-management/enabling-memgraph-enterprise). +Memgraph enforces the isolation between spaces with +[multi-tenancy](/database-management/multi-tenancy), +[role-based access control](/database-management/authentication-and-authorization/role-based-access-control) +and [label-based access control](/database-management/authentication-and-authorization/role-based-access-control#label-based-access-control). +Context Graph itself doesn't filter what a user can read. + +Without shared spaces, Context Graph runs as the **Community** edition: one +user and one database. Nothing changes for Community users when the shared +spaces package is installed. + +## How spaces work + +- **Identity** is your Memgraph login. It replaces `identity.user_id`. +- **Your personal space** is the database `u_LOGIN`. It holds your sessions, + memories and knowledge graph, and only you can read it. +- **A shared space** is the database `space_NAME`. Members can read + everything in it, and write only memory files. +- **Shared memory files** appear to the agent under `/memories/spaces/NAME/`. + The agent writes there only when you want something shared. At the start of + a session, each shared space adds up to 20 files to the memory index. +- **Recall** searches your personal space and every shared space you can read, + in parallel. If a space doesn't answer within 10 seconds, recall returns the + other results and names the space it's missing. + +Your own sessions stay in your personal space. A shared space holds only the +memory files members put there, and the knowledge graph built from them. + +## Set up spaces as an admin + +Declare the members and spaces in a spec file, such as `spaces.toml`: + +```toml +members = ["alice", "bob"] +personal_memory_limit_mb = 2048 + +[spaces.payments] +members = ["alice", "bob"] +memory_limit_mb = 4096 +``` + +- **`members`** at the top lists every user who gets a personal space. +- **`personal_memory_limit_mb`** caps each personal space's memory, with a + [tenant profile](/database-management/tenant-profiles). +- **`[spaces.NAME]`** declares a shared space, its members and its memory cap. + `labels` and `edge_types` set what members may write; the default is memory + files only. + +Install the `context-graph-spaces` package and apply the spec as a Memgraph +admin user: + +```bash +pip install context-graph-spaces +export MEMGRAPH_URL=bolt://memgraph.example.com:7687 +export MEMGRAPH_USER=ADMIN_USER +export MEMGRAPH_PASSWORD=ADMIN_PASSWORD +context-graph-spaces plan spaces.toml +context-graph-spaces apply spaces.toml +``` + +`plan` prints what `apply` would change. `apply` creates what's missing and +prints one-time setup lines for new users, including the password of the +`cg_service` user. Running it again changes nothing. + +`apply` creates and maintains: + +| Object | Name | Access | +| --- | --- | --- | +| Personal database | `u_LOGIN` | Its owner only | +| Shared database | `space_NAME` | Members read everything and write the spec's labels | +| Roles | `cg_u_LOGIN_HASH`, `space_NAME_member_HASH`, `cg_worker_HASH` | Named after what they grant | +| Service user | `cg_service` | Writes the knowledge graph in shared spaces | +| Tenant profiles | `cg_MBmb` | The memory caps from the spec | + +Removing a user from the spec revokes their access, and removing a space +revokes access to it. `apply` drops users and databases only with `--prune`, +and only touches objects whose names start with `u_`, `space_` or `cg_`. + +### Run the shared space worker + +Members can only write memory files to a shared space. The `cg_service` user +builds the knowledge graph there, and the embeddings recall uses. Run the +worker next to `apply`, with the password `apply` printed: + +```bash +export CG_SERVICE_PASSWORD=SERVICE_PASSWORD +context-graph-spaces reconcile spaces.toml --watch +``` + +Every 30 seconds, for each shared space, the worker removes what deleted +files left behind and extracts the changed memory files. It uses no LLM. +Personal spaces are extracted on each user's machine, as in the Community +edition. + + +Without the worker, shared memory files are still stored and read, but recall +can't find them by meaning or through the knowledge graph. + + +## Join as a user + +Each user runs `join` with the Memgraph URL and their login: + +```bash +memgraph-context-graph join bolt://memgraph.example.com:7687 alice +``` + +`join` prompts for the password, installs the `context-graph-spaces` package +if it's missing, and sets `edition = "enterprise"`, the URL, the login and the +password in the [configuration file](/ai-ecosystem/ai-memory/context-graph/configuration#configuration-file). +It then checks the login and prints your personal space and the shared spaces +you can read: + +```plaintext copy=false +Wrote /home/alice/.config/context-graph/config.toml: edition = enterprise, login 'alice'. +Personal space: u_alice. Shared spaces: payments. +``` + +If this machine isn't set up yet, run +[setup](/ai-ecosystem/ai-memory/context-graph/get-started) next to connect +your agents. + +In the [terminal viewer](/ai-ecosystem/ai-memory/context-graph/explore-the-graph#terminal-viewer), +press `w` to switch to the next space you can read. diff --git a/pages/database-management/enabling-memgraph-enterprise.mdx b/pages/database-management/enabling-memgraph-enterprise.mdx index 25b9c5cf7..20ee0bd9f 100644 --- a/pages/database-management/enabling-memgraph-enterprise.mdx +++ b/pages/database-management/enabling-memgraph-enterprise.mdx @@ -279,6 +279,13 @@ deployment. You can create, alter, and drop profiles, and use `SHOW MEMORY INFO` and `SHOW STORAGE INFO ON DATABASE` to monitor per-database memory usage. +### Context Graph shared spaces + +[Shared spaces](/ai-ecosystem/ai-memory/context-graph/shared-spaces) run +Context Graph for a team on one Memgraph instance. Each user gets a personal +database for their coding agents' memory, and teams get shared databases, +isolated with multi-tenancy and role-based access control. + ### CRON snapshot scheduling Memgraph supports [periodic snapshot From b3984a15f28467d4532d2e6d2f7dac23ed151a2f Mon Sep 17 00:00:00 2001 From: antejavor Date: Tue, 20 Oct 2026 12:57:14 +0200 Subject: [PATCH 02/11] add: Context Graph capture privacy settings --- .../ai-ecosystem/ai-memory/context-graph.mdx | 7 +- .../ai-memory/context-graph/configuration.mdx | 119 +++++++++++++++++- .../ai-memory/context-graph/get-started.mdx | 4 +- 3 files changed, 122 insertions(+), 8 deletions(-) diff --git a/pages/ai-ecosystem/ai-memory/context-graph.mdx b/pages/ai-ecosystem/ai-memory/context-graph.mdx index 3a03e860b..e1048e15f 100644 --- a/pages/ai-ecosystem/ai-memory/context-graph.mdx +++ b/pages/ai-ecosystem/ai-memory/context-graph.mdx @@ -14,7 +14,9 @@ recall it. Context Graph is open source and part of the [Memgraph AI Toolkit](https://github.com/memgraph/ai-toolkit/tree/main/context-graph). -It runs on your machine by default, with no account or cloud service. +It runs on your machine by default, with no account or cloud service, and +[redacts secrets](/ai-ecosystem/ai-memory/context-graph/configuration#keep-secrets-out-of-the-graph) +before anything is stored. ## What your agents get @@ -81,7 +83,8 @@ your own application. How agents read their past sessions, and how to make Context Graph their memory. - [Configuration](/ai-ecosystem/ai-memory/context-graph/configuration): The - configuration file, a remote Memgraph, updates and uninstalling. + configuration file, a remote Memgraph, privacy settings, updates and + uninstalling. - [Knowledge graph](/ai-ecosystem/ai-memory/context-graph/knowledge-graph): Extract entities and facts from your sessions. - [Explore the graph](/ai-ecosystem/ai-memory/context-graph/explore-the-graph): diff --git a/pages/ai-ecosystem/ai-memory/context-graph/configuration.mdx b/pages/ai-ecosystem/ai-memory/context-graph/configuration.mdx index cf5f6d24f..388975dfd 100644 --- a/pages/ai-ecosystem/ai-memory/context-graph/configuration.mdx +++ b/pages/ai-ecosystem/ai-memory/context-graph/configuration.mdx @@ -1,6 +1,6 @@ --- title: Configure Context Graph -description: Configure Context Graph's Memgraph connection, identity and recorded data, and update or uninstall it for your coding agents. +description: Configure Context Graph's Memgraph connection, identity and what it records, keep secrets out of the graph, and update or uninstall it. --- import { Callout } from 'nextra/components' @@ -8,8 +8,8 @@ import { Callout } from 'nextra/components' # Configure Context Graph Context Graph keeps its settings in one configuration file. This page covers -the file, connecting to your own Memgraph, choosing what is recorded, and -updating or removing Context Graph. +the file, connecting to your own Memgraph, choosing what is recorded, keeping +secrets out of the graph, and updating or removing Context Graph. ## Configuration file @@ -37,6 +37,10 @@ memgraph-context-graph config set identity.user_id alice | `memgraph.password` | Empty | The Memgraph password. `config set memgraph.password` without a value prompts for it. | | `memgraph.database` | `memgraph` | The database, on a Memgraph with [multi-tenancy](/database-management/multi-tenancy) | | `capture.connectors` | `skills-graph, actions-graph, sessions-graph` | What the hooks record. See [Choose what is recorded](#choose-what-is-recorded). | +| `capture.redact` | `true` | Whether secrets are redacted before they're stored. See [Keep secrets out of the graph](#keep-secrets-out-of-the-graph). | +| `capture.max_chars` | `100000` | The most characters kept from one text field, such as a tool's output. `0` keeps everything. | +| `capture.exclude_tools` | None | Tools whose calls and results aren't recorded, by name or glob | +| `capture.exclude_projects` | None | Directories in which nothing is recorded, by path or glob | | `memory.backend` | Unset | `context-graph` when Context Graph is the agents' [memory](/ai-ecosystem/ai-memory/context-graph/recall-and-memory#use-context-graph-as-your-agents-memory). Set it with setup's `--memory-backend`, which also changes the agents' settings. | | `session_start.resume` | `true` | Whether a session starts with the [note on where you left off](/ai-ecosystem/ai-memory/context-graph/recall-and-memory#where-you-left-off) | | `recall.embedding_model` | `BAAI/bge-small-en-v1.5` | The embedding model for recall | @@ -49,8 +53,8 @@ memgraph-context-graph config set identity.user_id alice | `edition` | `community` | `enterprise` to use [shared spaces](/ai-ecosystem/ai-memory/context-graph/shared-spaces). Set it with `memgraph-context-graph join`. | | `github.token` | Unset | A GitHub token for `resources-graph`, used instead of your `gh` login. Prompts for the value. | -Recall's other settings and the `[extraction]` settings are edited in the file -directly. See [Tune recall](/ai-ecosystem/ai-memory/context-graph/recall-and-memory#tune-recall) +Recall's other settings, the `[extraction]` settings and `[redact]` patterns +are edited in the file directly. See [Tune recall](/ai-ecosystem/ai-memory/context-graph/recall-and-memory#tune-recall) and [Tune extraction](/ai-ecosystem/ai-memory/context-graph/knowledge-graph#tune-extraction). @@ -114,6 +118,111 @@ memgraph-context-graph setup Setup installs the connectors the setting names. An empty value records nothing, without disconnecting the agents. +## Keep secrets out of the graph + +The hooks record prompts, replies, and tool input and output in full, so a +session can contain an API key from a `.env` file or text you don't want +stored. Before anything reaches Memgraph, Context Graph removes what you mark +as private, redacts secrets, and shortens long text. What it removes is never +stored. + +These rules apply to everything the hooks record, for every agent. They don't +apply to memory files the agent writes with the +[`memory` tool](/ai-ecosystem/ai-memory/context-graph/recall-and-memory#how-the-agent-uses-memory), +which are stored as written. Sessions recorded before an update that added the +rules stay as they were. + +### Mark text as private + +Text between `` and `` is removed from prompts, replies and +tool input and output: + +```plaintext +Connect to the staging database. The password is in the team vault under "staging-db". +``` + +Context Graph stores only "Connect to the staging database.". The agent still +gets the whole prompt. If a prompt has nothing outside its private block, it +isn't stored at all. An unclosed `` hides the rest of the text. + +### Redact secrets + +Context Graph replaces known kinds of secrets with `[REDACTED:NAME]`, where +`NAME` says what was removed: + +| Name | What it matches | +| --- | --- | +| `private_key` | PEM private key blocks | +| `aws_access_key` | AWS access key IDs | +| `github_token` | GitHub tokens and fine-grained personal access tokens | +| `anthropic_key` | Anthropic API keys | +| `openai_key` | OpenAI API keys | +| `slack_token` | Slack tokens | +| `stripe_key` | Stripe secret and restricted keys | +| `google_api_key` | Google API keys | +| `jwt` | JSON Web Tokens | +| `url_password` | Passwords in URLs, such as `postgres://user:PASSWORD@host` | +| `config_secret` | The Memgraph password, API keys and GitHub token in the configuration file, if they're at least 6 characters long | + +To redact your own patterns, add a `[redact]` section to the configuration +file. Each key is the name in the replacement, and each value is a +[Python regular expression](https://docs.python.org/3/library/re.html#regular-expression-syntax) +in single quotes: + +```toml +[redact] +ticket = 'ACME-[0-9]+' +customer_email = '[A-Za-z0-9._%+-]+@acme\.com' +``` + +An invalid pattern is ignored and reported as a configuration warning, and +recording continues. + +Redaction matches known shapes of secrets, so it doesn't catch every secret. +Use `` or `capture.exclude_projects` for anything it might miss. + +To turn redaction off, so that only `` blocks are removed: + +```bash +memgraph-context-graph config set capture.redact false +``` + +### Shorten long text + +Each text field, such as a tool's output, is cut after `capture.max_chars` +characters, 100,000 by default, and ends with a note of how many characters +were removed. To change the limit, or to keep everything with `0`: + +```bash +memgraph-context-graph config set capture.max_chars 20000 +``` + +### Exclude tools and projects + +To stop recording some tools' calls and results, list their names. A name can +be a glob, such as `mcp__vault__*` for every tool of one MCP server: + +```bash +memgraph-context-graph config set capture.exclude_tools "TodoWrite, mcp__vault__*" +``` + +To record nothing from some projects, list their directories. A session that +starts in one of them, or in a directory inside one, isn't recorded. `~` stands +for your home directory, and a path can be a glob: + +```bash +memgraph-context-graph config set capture.exclude_projects "~/clients/*, ~/personal" +``` + +The agent works as usual in an excluded project, and recall still finds your +other sessions there. + +Setting a list replaces the previous one. To clear it, set an empty value: + +```bash +memgraph-context-graph config set capture.exclude_projects "" +``` + ## Update Context Graph `update` upgrades the packages, then refreshes everything setup installed: the diff --git a/pages/ai-ecosystem/ai-memory/context-graph/get-started.mdx b/pages/ai-ecosystem/ai-memory/context-graph/get-started.mdx index 4089a5d52..0c8b079ba 100644 --- a/pages/ai-ecosystem/ai-memory/context-graph/get-started.mdx +++ b/pages/ai-ecosystem/ai-memory/context-graph/get-started.mdx @@ -123,7 +123,9 @@ on a Memgraph without MAGE; recall then uses text search only. ## 4. Use your agents Work with your agents as before. Every session is recorded in the graph as it -happens. To see it, open the terminal viewer: +happens, with secrets redacted. To keep text out of the graph, wrap it in +`` tags, or exclude a project; see +[Keep secrets out of the graph](/ai-ecosystem/ai-memory/context-graph/configuration#keep-secrets-out-of-the-graph). To see it, open the terminal viewer: ```bash memgraph-context-graph ui From e564ccc0e85bc0ade27395ef08b3930efcf5e5ff Mon Sep 17 00:00:00 2001 From: antejavor Date: Wed, 21 Oct 2026 13:37:08 +0200 Subject: [PATCH 03/11] add: Context Graph forget, uninstall and first-run setup changes --- .../ai-ecosystem/ai-memory/context-graph.mdx | 4 +- .../ai-memory/context-graph/configuration.mdx | 82 ++++++++++++++++--- .../ai-memory/context-graph/get-started.mdx | 13 ++- 3 files changed, 83 insertions(+), 16 deletions(-) diff --git a/pages/ai-ecosystem/ai-memory/context-graph.mdx b/pages/ai-ecosystem/ai-memory/context-graph.mdx index e1048e15f..fa3b6fc33 100644 --- a/pages/ai-ecosystem/ai-memory/context-graph.mdx +++ b/pages/ai-ecosystem/ai-memory/context-graph.mdx @@ -83,8 +83,8 @@ your own application. How agents read their past sessions, and how to make Context Graph their memory. - [Configuration](/ai-ecosystem/ai-memory/context-graph/configuration): The - configuration file, a remote Memgraph, privacy settings, updates and - uninstalling. + configuration file, a remote Memgraph, privacy settings, forgetting + sessions, updates and uninstalling. - [Knowledge graph](/ai-ecosystem/ai-memory/context-graph/knowledge-graph): Extract entities and facts from your sessions. - [Explore the graph](/ai-ecosystem/ai-memory/context-graph/explore-the-graph): diff --git a/pages/ai-ecosystem/ai-memory/context-graph/configuration.mdx b/pages/ai-ecosystem/ai-memory/context-graph/configuration.mdx index 388975dfd..6c3b02ea1 100644 --- a/pages/ai-ecosystem/ai-memory/context-graph/configuration.mdx +++ b/pages/ai-ecosystem/ai-memory/context-graph/configuration.mdx @@ -9,7 +9,8 @@ import { Callout } from 'nextra/components' Context Graph keeps its settings in one configuration file. This page covers the file, connecting to your own Memgraph, choosing what is recorded, keeping -secrets out of the graph, and updating or removing Context Graph. +secrets out of the graph, forgetting sessions, and updating or removing +Context Graph. ## Configuration file @@ -223,6 +224,47 @@ Setting a list replaces the previous one. To clear it, set an empty value: memgraph-context-graph config set capture.exclude_projects "" ``` +## Forget sessions + +`forget` deletes sessions from your graph for good, with everything recorded in +them and everything extracted from them. Delete sessions by ID: + +```bash +memgraph-context-graph forget session SESSION_ID +``` + +`SESSION_ID` is the session's `session_id`, shown in the +[terminal viewer](/ai-ecosystem/ai-memory/context-graph/explore-the-graph#terminal-viewer). +Pass several IDs to delete several sessions. + +To delete every session that ran in a directory or inside it, pass the +directory: + +```bash +memgraph-context-graph forget project ~/work/client-repo +``` + +`forget` lists the matching sessions and asks before it deletes them. Add +`--dry-run` to only list them, and `--yes` to skip the question. Without a +terminal, `--yes` is required. + +For each session, `forget` deletes: + +- its prompts, replies, tool calls and results, its skill uses, and its + records of GitHub resources; +- what reconciliation extracted from it, and every entity no other session or + memory file mentions; +- its lines in the log of failed recordings. + +Entities that other sessions mention, skills, stored GitHub resources and your +memory files stay, including files the session wrote. A forgotten session +leaves only a `ForgottenSession` node with its ID, which stops a hook that is +still running, or a resumed session, from recording it again. + +Only the agent's user can forget sessions: the agent has no tool for it. With +[shared spaces](/ai-ecosystem/ai-memory/context-graph/shared-spaces), `forget` +deletes from your personal space only. + ## Update Context Graph `update` upgrades the packages, then refreshes everything setup installed: the @@ -252,20 +294,38 @@ registrations, and turns the agents' own memory back on. memgraph-context-graph uninstall ``` -Name agents to disconnect only those, and pass `--project-dir` for projects -other than the current directory. +On a terminal, it then asks about each of these, and keeps it unless you +answer yes: + +- **The graph:** the Memgraph container that setup started and its data + volume, with every recorded session and memory. +- **The configuration:** the configuration file and the log of failed + recordings. +- **The tool:** the `memgraph-context-graph` command and its packages. -The graph, the configuration file and the `memgraph-context-graph` command -stay, and `uninstall` prints how to remove each of them. To also remove the -Memgraph that setup started, together with its data, remove its container and -volume: +To remove everything without questions, for example in a script: ```bash -docker rm -f context-graph-memgraph -docker volume rm context-graph-memgraph-data +memgraph-context-graph uninstall --all ``` +| Flag | What it does | +| --- | --- | +| `RUNTIME ...` | Disconnect only these agents. The default is every connected agent. | +| `--project-dir DIR` | A project to disconnect the per-project agents from. Repeat it for more projects. The default is the current directory. | +| `--graph` | Also delete the graph: setup's Memgraph container and its volume | +| `--config` | Also delete the configuration file and the log of failed recordings | +| `--tool` | Also uninstall the `memgraph-context-graph` tool | +| `--all` | `--graph`, `--config` and `--tool` together | +| `--memgraph-container NAME` | The container setup started. The default is `context-graph-memgraph`. | +| `--no-tui` | Don't ask; remove the agent connections and what the flags name | + +Without a terminal, `uninstall` removes only the agent connections and what the +flags name. It deletes only the container setup started, by name, never a +Memgraph you run yourself. On Windows, the running tool can't remove itself, +so `uninstall` prints the `uv tool uninstall` command to run afterwards. + -Removing the volume deletes everything your agents recorded, including your -memories. +Deleting the graph deletes everything your agents recorded, including your +memories, and can't be undone. diff --git a/pages/ai-ecosystem/ai-memory/context-graph/get-started.mdx b/pages/ai-ecosystem/ai-memory/context-graph/get-started.mdx index 0c8b079ba..47a16bb84 100644 --- a/pages/ai-ecosystem/ai-memory/context-graph/get-started.mdx +++ b/pages/ai-ecosystem/ai-memory/context-graph/get-started.mdx @@ -55,8 +55,10 @@ Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass Setup lists what it found and what it will do: -- **Agents:** the agents on your `PATH`, ticked. Untick any you don't want - connected. +- **Agents:** the agents on your `PATH`. On a first run, Claude Code and + Codex are ticked, and the per-project agents aren't; tick the ones you want + connected in this project. On a later run, the agents already connected are + ticked. If no agent is ticked, setup fails instead of installing nothing. - **Memgraph:** the one it will use or start. - **Name:** your user ID in the graph. Your memories are filed under it. It defaults to your git `user.name`, or your system user name. @@ -114,9 +116,14 @@ OK connector:actions-graph: installed=...; memgraph=reachable OK connector:sessions-graph: installed=...; memgraph=reachable OK embeddings: BAAI/bge-small-en-v1.5 (384 dimensions) inside Memgraph OK mcp: serves recall -OK runtime:claude-code: strict hook smoke passed +OK runtime:claude-code: connectors accept its probe event +OK plugin:claude-code: context-graph@context-graph-plugins installed and enabled ``` +The `runtime:` check sends a test event to the connectors. For Claude Code and +Codex, the `plugin:` check confirms the agent will call the hooks: it fails if +the agent isn't on your `PATH`, or the plugin isn't installed or is disabled. + A line that starts with `FAIL` says what failed. The `embeddings` check fails on a Memgraph without MAGE; recall then uses text search only. From 746f51eeed854d27d0d3995df667a814e0ee8c9b Mon Sep 17 00:00:00 2001 From: antejavor Date: Wed, 21 Oct 2026 13:57:51 +0200 Subject: [PATCH 04/11] update: Context Graph plugin updates, without release versions --- .../ai-memory/context-graph/configuration.mdx | 57 +++++++++++++++---- 1 file changed, 45 insertions(+), 12 deletions(-) diff --git a/pages/ai-ecosystem/ai-memory/context-graph/configuration.mdx b/pages/ai-ecosystem/ai-memory/context-graph/configuration.mdx index 6c3b02ea1..8af76ca74 100644 --- a/pages/ai-ecosystem/ai-memory/context-graph/configuration.mdx +++ b/pages/ai-ecosystem/ai-memory/context-graph/configuration.mdx @@ -130,8 +130,7 @@ stored. These rules apply to everything the hooks record, for every agent. They don't apply to memory files the agent writes with the [`memory` tool](/ai-ecosystem/ai-memory/context-graph/recall-and-memory#how-the-agent-uses-memory), -which are stored as written. Sessions recorded before an update that added the -rules stay as they were. +which are stored as written. ### Mark text as private @@ -267,23 +266,57 @@ deletes from your personal space only. ## Update Context Graph -`update` upgrades the packages, then refreshes everything setup installed: the -Claude Code and Codex plugins, the hook files and MCP registrations of the -per-project agents, and the indexes and constraints in Memgraph. +Context Graph doesn't update itself. Upgrading the packages changes the code +the hooks run, but the plugins, hook files and MCP registrations that setup +wrote stay as they were. `update` upgrades both in one step: ```bash memgraph-context-graph update ``` -- **Choose agents** by naming them: `memgraph-context-graph update cursor`. -- **Choose projects** for the per-project agents with `--project-dir`. The - default is the current directory. -- **Skip the upgrade** with `--no-upgrade`, to only refresh what setup - installed. +It runs these steps in order: + +1. **Upgrades the packages:** `memgraph-context-graph` and its connectors. +2. **Updates the Claude Code and Codex plugins** from the Context Graph plugin + marketplace, if they're installed. +3. **Rewrites the hook files and MCP registrations** of the per-project agents, + in the current directory or the `--project-dir` directories. +4. **Creates the indexes and constraints** in Memgraph that are missing. +5. **Checks the setup,** the same way as `doctor`. + +Then restart running agent sessions, because a session keeps the hooks it +started with. + +| Flag | What it does | +| --- | --- | +| `RUNTIME ...` | Update only these agents. The default is every connected agent. | +| `--project-dir DIR` | A project whose per-project agents to update. Repeat it for more projects. The default is the current directory. | +| `--no-upgrade` | Skip the package upgrade, and only refresh the plugins, hook files, registrations and schema | `update` doesn't change your own hooks, the configuration file or the data in -the graph, and running it twice changes nothing. Restart running agent -sessions afterwards, because they keep the hooks they started with. +the graph, and running it twice changes nothing. + +### Update the plugins manually + +If you manage plugins yourself, update the Context Graph plugin with the +agent's own commands. Claude Code updates the plugin in place: + +```bash +claude plugin marketplace update context-graph-plugins +claude plugin update context-graph@context-graph-plugins +``` + +Codex has no update command, so refresh the marketplace and add the plugin +again: + +```bash +codex plugin marketplace upgrade context-graph-plugins +codex plugin add context-graph@context-graph-plugins +``` + +Updating only the plugin doesn't upgrade the packages its hooks run. Run +`memgraph-context-graph update` as well, or upgrade the tool with +`uv tool upgrade memgraph-context-graph`. ## Uninstall Context Graph From 160dea88f70500015912ce1231915cfbe7ce0b06 Mon Sep 17 00:00:00 2001 From: antejavor Date: Thu, 22 Oct 2026 11:01:47 +0200 Subject: [PATCH 05/11] Update. --- pages/ai-ecosystem/ai-memory.mdx | 160 ++++++++++++++---- pages/ai-ecosystem/ai-memory/_meta.ts | 8 +- .../ai-memory/{context-graph => }/agents.mdx | 2 +- .../{context-graph => }/configuration.mdx | 20 +-- .../ai-ecosystem/ai-memory/context-graph.mdx | 94 ---------- .../ai-memory/context-graph/_meta.ts | 9 - .../{context-graph => }/explore-the-graph.mdx | 2 +- .../{context-graph => }/get-started.mdx | 12 +- .../{context-graph => }/knowledge-graph.mdx | 0 .../{context-graph => }/recall-and-memory.mdx | 8 +- .../{context-graph => }/shared-spaces.mdx | 6 +- .../enabling-memgraph-enterprise.mdx | 2 +- 12 files changed, 156 insertions(+), 167 deletions(-) rename pages/ai-ecosystem/ai-memory/{context-graph => }/agents.mdx (98%) rename pages/ai-ecosystem/ai-memory/{context-graph => }/configuration.mdx (93%) delete mode 100644 pages/ai-ecosystem/ai-memory/context-graph.mdx delete mode 100644 pages/ai-ecosystem/ai-memory/context-graph/_meta.ts rename pages/ai-ecosystem/ai-memory/{context-graph => }/explore-the-graph.mdx (98%) rename pages/ai-ecosystem/ai-memory/{context-graph => }/get-started.mdx (94%) rename pages/ai-ecosystem/ai-memory/{context-graph => }/knowledge-graph.mdx (100%) rename pages/ai-ecosystem/ai-memory/{context-graph => }/recall-and-memory.mdx (96%) rename pages/ai-ecosystem/ai-memory/{context-graph => }/shared-spaces.mdx (96%) diff --git a/pages/ai-ecosystem/ai-memory.mdx b/pages/ai-ecosystem/ai-memory.mdx index 079899ede..2f093b5f4 100644 --- a/pages/ai-ecosystem/ai-memory.mdx +++ b/pages/ai-ecosystem/ai-memory.mdx @@ -1,6 +1,6 @@ --- 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' @@ -12,29 +12,36 @@ 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. -## How Memgraph stores memory +## Choose an approach -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)** to give your coding agents a + memory now. One command connects Claude Code, Codex and other coding agents + to Memgraph, and they record and recall their sessions with no code. +- **[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 gives your coding agents a memory that lasts across sessions and +is shared between agents. It records each session of Claude Code, Codex, GitHub +Copilot CLI, Cursor, OpenCode, Antigravity CLI or Grok Build in Memgraph: your +prompts, the agent's replies, the tools it called, the skills it used and the +memories it saved. In the next session, any of those agents can recall it. -[Context Graph](/ai-ecosystem/ai-memory/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. +Context Graph is open source and part of the +[Memgraph AI Toolkit](https://github.com/memgraph/ai-toolkit/tree/main/context-graph). +It runs on your machine by default, with no account or cloud service, and +[redacts secrets](/ai-ecosystem/ai-memory/configuration#keep-secrets-out-of-the-graph) +before anything is stored. + +### Set up Context Graph You need [Docker](https://docs.docker.com/get-docker/), unless you already run -Memgraph 3.6 or later, and a terminal. Start the setup: +Memgraph 3.6 or later, and a terminal. Run the setup from the project +directory you work in: @@ -52,16 +59,93 @@ iwr https://install.memgraph.com/ai-memory/windows -useb | iex The setup shows its plan and changes nothing until you confirm. It finds or -starts Memgraph, installs Context Graph and connects the agents it finds. -After that, every session of a connected agent is recorded in the graph, and -the next session can recall it. - -See [Get started with Context Graph](/ai-ecosystem/ai-memory/context-graph/get-started) -for what the setup does, how to check it and how to change your choices. - -## Query the memory graph +starts Memgraph, installs Context Graph and connects your agents. See +[Get started](/ai-ecosystem/ai-memory/get-started) for what the setup does, +how to check it and how to change your choices. + +### What your agents get + +After setup, every connected agent gets three things: + +- **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), + finds what your past sessions hold about a question. A session also starts + with a short note on where you left off in the current project, whichever + agent you used last. +- **Memory.** If you turn it on, a `memory` tool replaces the agent's own + memory. The memories the agent saves are stored in the graph and shared by + all your agents. + +See [Recall and memory](/ai-ecosystem/ai-memory/recall-and-memory) for how +each one works. + +### 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) +``` -Because the three types share the `User` and `Session` nodes, one query can +`Memory` nodes hold what the agent knows, `Action` nodes what it did, and +`Skill` nodes what it knows how to do. Because they share the `User` and +`Session` nodes, one traversal can recall all three together. + +Context Graph can also extract the people, projects, files and decisions your +sessions mention into a [knowledge graph](/ai-ecosystem/ai-memory/knowledge-graph), +linked back to the sessions that mention them. Recall uses it to find facts +across sessions. + +### Components + +Context Graph is a set of Python packages. Setup installs the ones you need, +so you only need this list to change what is recorded or to use a package in +your own application. + +| Package | What it records or does | +| --- | --- | +| `memgraph-context-graph` | The `memgraph-context-graph` command: setup, the hooks, the MCP server and the configuration. | +| `actions-graph` | Prompts, replies, tool calls and tool results, as `Action` nodes. | +| `skills-graph` | The agent skills a session used, as `Skill` nodes. | +| `sessions-graph` | Users, sessions and memories, the knowledge graph extracted from them, and recall. | +| `context-graph-viewer` | A read-only terminal viewer of the graph, opened with `memgraph-context-graph ui`. | +| `resources-graph` | GitHub issues, pull requests and repositories your agents read, so they can read them again from the graph. Off by default. | +| `context-graph-spaces` | [Shared spaces](/ai-ecosystem/ai-memory/shared-spaces) for teams on Memgraph Enterprise. | + +### Context Graph guides + +- [Get started](/ai-ecosystem/ai-memory/get-started): Install Context Graph + and connect your agents with one command. +- [Agents](/ai-ecosystem/ai-memory/agents): What setup changes for each + supported agent. +- [Recall and memory](/ai-ecosystem/ai-memory/recall-and-memory): How agents + read their past sessions, and how to make Context Graph their memory. +- [Configuration](/ai-ecosystem/ai-memory/configuration): The configuration + file, a remote Memgraph, privacy settings, forgetting sessions, updates and + uninstalling. +- [Knowledge graph](/ai-ecosystem/ai-memory/knowledge-graph): Extract + entities and facts from your sessions. +- [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. +- [Shared spaces](/ai-ecosystem/ai-memory/shared-spaces): Share memory between + the members of a team. + +## 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 facts, actions and skills 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: @@ -75,22 +159,24 @@ 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 ``` -`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 connections, add a +[vector index](/querying/vector-search) on the memory text, and a +[text index](/querying/text-search) for search 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. diff --git a/pages/ai-ecosystem/ai-memory/_meta.ts b/pages/ai-ecosystem/ai-memory/_meta.ts index 13671a243..a7eac9148 100644 --- a/pages/ai-ecosystem/ai-memory/_meta.ts +++ b/pages/ai-ecosystem/ai-memory/_meta.ts @@ -1,3 +1,9 @@ export default { - "context-graph": "Context Graph" + "get-started": "Get started", + "agents": "Agents", + "recall-and-memory": "Recall and memory", + "configuration": "Configuration", + "knowledge-graph": "Knowledge graph", + "explore-the-graph": "Explore the graph", + "shared-spaces": "Shared spaces" } diff --git a/pages/ai-ecosystem/ai-memory/context-graph/agents.mdx b/pages/ai-ecosystem/ai-memory/agents.mdx similarity index 98% rename from pages/ai-ecosystem/ai-memory/context-graph/agents.mdx rename to pages/ai-ecosystem/ai-memory/agents.mdx index ae35081b3..133d069e7 100644 --- a/pages/ai-ecosystem/ai-memory/context-graph/agents.mdx +++ b/pages/ai-ecosystem/ai-memory/agents.mdx @@ -72,7 +72,7 @@ own to turn off. | Antigravity CLI | None in the CLI | Nothing | | Grok Build | Topic notes in `~/.grok/memory-v2/` | Sets `[memory_v2] enabled = false` and imports the notes to `/memories/grok/` | -See [Use Context Graph as your agents' memory](/ai-ecosystem/ai-memory/context-graph/recall-and-memory#use-context-graph-as-your-agents-memory) +See [Use Context Graph as your agents' memory](/ai-ecosystem/ai-memory/recall-and-memory#use-context-graph-as-your-agents-memory) for how the import works and how to switch back. ## Differences between agents diff --git a/pages/ai-ecosystem/ai-memory/context-graph/configuration.mdx b/pages/ai-ecosystem/ai-memory/configuration.mdx similarity index 93% rename from pages/ai-ecosystem/ai-memory/context-graph/configuration.mdx rename to pages/ai-ecosystem/ai-memory/configuration.mdx index 8af76ca74..eeac3e996 100644 --- a/pages/ai-ecosystem/ai-memory/context-graph/configuration.mdx +++ b/pages/ai-ecosystem/ai-memory/configuration.mdx @@ -42,21 +42,21 @@ memgraph-context-graph config set identity.user_id alice | `capture.max_chars` | `100000` | The most characters kept from one text field, such as a tool's output. `0` keeps everything. | | `capture.exclude_tools` | None | Tools whose calls and results aren't recorded, by name or glob | | `capture.exclude_projects` | None | Directories in which nothing is recorded, by path or glob | -| `memory.backend` | Unset | `context-graph` when Context Graph is the agents' [memory](/ai-ecosystem/ai-memory/context-graph/recall-and-memory#use-context-graph-as-your-agents-memory). Set it with setup's `--memory-backend`, which also changes the agents' settings. | -| `session_start.resume` | `true` | Whether a session starts with the [note on where you left off](/ai-ecosystem/ai-memory/context-graph/recall-and-memory#where-you-left-off) | +| `memory.backend` | Unset | `context-graph` when Context Graph is the agents' [memory](/ai-ecosystem/ai-memory/recall-and-memory#use-context-graph-as-your-agents-memory). Set it with setup's `--memory-backend`, which also changes the agents' settings. | +| `session_start.resume` | `true` | Whether a session starts with the [note on where you left off](/ai-ecosystem/ai-memory/recall-and-memory#where-you-left-off) | | `recall.embedding_model` | `BAAI/bge-small-en-v1.5` | The embedding model for recall | -| `reconcile.auto_reconcile` | `false` | Whether the [knowledge graph](/ai-ecosystem/ai-memory/context-graph/knowledge-graph) is built after each session | +| `reconcile.auto_reconcile` | `false` | Whether the [knowledge graph](/ai-ecosystem/ai-memory/knowledge-graph) is built after each session | | `ontology.path` | Unset | A schema file for the knowledge graph | | `ontology.derive` | `extend` | Whether Context Graph adds types to your schema: `extend` or `off` | | `llm.anthropic_api_key` | Empty | An Anthropic API key, used only to learn your schema | | `llm.openai_api_key` | Empty | An OpenAI API key, used only to learn your schema | | `llm.derive_model` | `claude-sonnet-5-5` with Anthropic, `gpt-5` with OpenAI | The model that learns your schema | -| `edition` | `community` | `enterprise` to use [shared spaces](/ai-ecosystem/ai-memory/context-graph/shared-spaces). Set it with `memgraph-context-graph join`. | +| `edition` | `community` | `enterprise` to use [shared spaces](/ai-ecosystem/ai-memory/shared-spaces). Set it with `memgraph-context-graph join`. | | `github.token` | Unset | A GitHub token for `resources-graph`, used instead of your `gh` login. Prompts for the value. | Recall's other settings, the `[extraction]` settings and `[redact]` patterns -are edited in the file directly. See [Tune recall](/ai-ecosystem/ai-memory/context-graph/recall-and-memory#tune-recall) -and [Tune extraction](/ai-ecosystem/ai-memory/context-graph/knowledge-graph#tune-extraction). +are edited in the file directly. See [Tune recall](/ai-ecosystem/ai-memory/recall-and-memory#tune-recall) +and [Tune extraction](/ai-ecosystem/ai-memory/knowledge-graph#tune-extraction). The file holds your Memgraph password and API keys in plain text. Setup @@ -94,7 +94,7 @@ properties with `SHOW SCHEMA INFO`, start it with `--schema-info-enabled=true`. The Memgraph that setup starts has it enabled. Each user on a shared Memgraph should have their own `identity.user_id`. On a -shared Memgraph with Memgraph Enterprise, [shared spaces](/ai-ecosystem/ai-memory/context-graph/shared-spaces) +shared Memgraph with Memgraph Enterprise, [shared spaces](/ai-ecosystem/ai-memory/shared-spaces) give each user a database of their own. ## Choose what is recorded @@ -129,7 +129,7 @@ stored. These rules apply to everything the hooks record, for every agent. They don't apply to memory files the agent writes with the -[`memory` tool](/ai-ecosystem/ai-memory/context-graph/recall-and-memory#how-the-agent-uses-memory), +[`memory` tool](/ai-ecosystem/ai-memory/recall-and-memory#how-the-agent-uses-memory), which are stored as written. ### Mark text as private @@ -233,7 +233,7 @@ memgraph-context-graph forget session SESSION_ID ``` `SESSION_ID` is the session's `session_id`, shown in the -[terminal viewer](/ai-ecosystem/ai-memory/context-graph/explore-the-graph#terminal-viewer). +[terminal viewer](/ai-ecosystem/ai-memory/explore-the-graph#terminal-viewer). Pass several IDs to delete several sessions. To delete every session that ran in a directory or inside it, pass the @@ -261,7 +261,7 @@ leaves only a `ForgottenSession` node with its ID, which stops a hook that is still running, or a resumed session, from recording it again. Only the agent's user can forget sessions: the agent has no tool for it. With -[shared spaces](/ai-ecosystem/ai-memory/context-graph/shared-spaces), `forget` +[shared spaces](/ai-ecosystem/ai-memory/shared-spaces), `forget` deletes from your personal space only. ## Update Context Graph diff --git a/pages/ai-ecosystem/ai-memory/context-graph.mdx b/pages/ai-ecosystem/ai-memory/context-graph.mdx deleted file mode 100644 index fa3b6fc33..000000000 --- a/pages/ai-ecosystem/ai-memory/context-graph.mdx +++ /dev/null @@ -1,94 +0,0 @@ ---- -title: Context Graph -description: Give your coding agents a shared, long-term memory by recording their sessions as one graph in Memgraph that every agent can recall from. ---- - -# Context Graph - -Context Graph gives your coding agents a memory that lasts across sessions and -is shared between agents. It records each session of Claude Code, Codex, GitHub -Copilot CLI, Cursor, OpenCode, Antigravity CLI or Grok Build as a graph in -Memgraph: your prompts, the agent's replies, the tools it called, the skills it -used and the memories it saved. In the next session, any of those agents can -recall it. - -Context Graph is open source and part of the -[Memgraph AI Toolkit](https://github.com/memgraph/ai-toolkit/tree/main/context-graph). -It runs on your machine by default, with no account or cloud service, and -[redacts secrets](/ai-ecosystem/ai-memory/context-graph/configuration#keep-secrets-out-of-the-graph) -before anything is stored. - -## What your agents get - -After setup, every connected agent gets three things: - -- **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), - finds what your past sessions hold about a question. A session also starts - with a short note on where you left off in the current project, whichever - agent you used last. -- **Memory.** If you turn it on, a `memory` tool replaces the agent's own - memory. The memories the agent saves are stored in the graph and shared by - all your agents. - -See [Recall and memory](/ai-ecosystem/ai-memory/context-graph/recall-and-memory) -for how each one works. - -## How the graph is organized - -Each session is a `Session` node, linked to its `User`. Everything recorded in -the session hangs off that node, so one Cypher query can span all of it: - -```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) -``` - -These are the three types of [AI memory](/ai-ecosystem/ai-memory): `Memory` -nodes are semantic memory, `Action` nodes are episodic memory and `Skill` -nodes are procedural memory. - -Context Graph can also extract the people, projects, files and decisions your -sessions mention into a [knowledge graph](/ai-ecosystem/ai-memory/context-graph/knowledge-graph), -linked back to the sessions that mention them. Recall uses it to find facts -across sessions. - -## Components - -Context Graph is a set of Python packages. Setup installs the ones you need, -so you only need this list to change what is recorded or to use a package in -your own application. - -| Package | What it records or does | -| --- | --- | -| `memgraph-context-graph` | The `memgraph-context-graph` command: setup, the hooks, the MCP server and the configuration. | -| `actions-graph` | Prompts, replies, tool calls and tool results, as `Action` nodes. | -| `skills-graph` | The agent skills a session used, as `Skill` nodes. | -| `sessions-graph` | Users, sessions and memories, the knowledge graph extracted from them, and recall. | -| `context-graph-viewer` | A read-only terminal viewer of the graph, opened with `memgraph-context-graph ui`. | -| `resources-graph` | GitHub issues, pull requests and repositories your agents read, so they can read them again from the graph. Off by default. | -| `context-graph-spaces` | [Shared spaces](/ai-ecosystem/ai-memory/context-graph/shared-spaces) for teams on Memgraph Enterprise. | - -## Pages in this section - -- [Get started](/ai-ecosystem/ai-memory/context-graph/get-started): Install - Context Graph and connect your agents with one command. -- [Agents](/ai-ecosystem/ai-memory/context-graph/agents): What setup changes - for each supported agent. -- [Recall and memory](/ai-ecosystem/ai-memory/context-graph/recall-and-memory): - How agents read their past sessions, and how to make Context Graph their - memory. -- [Configuration](/ai-ecosystem/ai-memory/context-graph/configuration): The - configuration file, a remote Memgraph, privacy settings, forgetting - sessions, updates and uninstalling. -- [Knowledge graph](/ai-ecosystem/ai-memory/context-graph/knowledge-graph): - Extract entities and facts from your sessions. -- [Explore the graph](/ai-ecosystem/ai-memory/context-graph/explore-the-graph): - Look at what your agents recorded, in the terminal, in Memgraph Lab or with - Cypher. -- [Shared spaces](/ai-ecosystem/ai-memory/context-graph/shared-spaces): Share - memory between the members of a team. diff --git a/pages/ai-ecosystem/ai-memory/context-graph/_meta.ts b/pages/ai-ecosystem/ai-memory/context-graph/_meta.ts deleted file mode 100644 index a7eac9148..000000000 --- a/pages/ai-ecosystem/ai-memory/context-graph/_meta.ts +++ /dev/null @@ -1,9 +0,0 @@ -export default { - "get-started": "Get started", - "agents": "Agents", - "recall-and-memory": "Recall and memory", - "configuration": "Configuration", - "knowledge-graph": "Knowledge graph", - "explore-the-graph": "Explore the graph", - "shared-spaces": "Shared spaces" -} diff --git a/pages/ai-ecosystem/ai-memory/context-graph/explore-the-graph.mdx b/pages/ai-ecosystem/ai-memory/explore-the-graph.mdx similarity index 98% rename from pages/ai-ecosystem/ai-memory/context-graph/explore-the-graph.mdx rename to pages/ai-ecosystem/ai-memory/explore-the-graph.mdx index 663256717..e34cbd1e0 100644 --- a/pages/ai-ecosystem/ai-memory/context-graph/explore-the-graph.mdx +++ b/pages/ai-ecosystem/ai-memory/explore-the-graph.mdx @@ -123,7 +123,7 @@ RETURN DISTINCT s.session_id; ``` The entities your sessions mention most, after you -[build the knowledge graph](/ai-ecosystem/ai-memory/context-graph/knowledge-graph): +[build the knowledge graph](/ai-ecosystem/ai-memory/knowledge-graph): ```cypher template MATCH (:User {user_id: "USER_ID"})-[:HAD_SESSION]->(:Session)-[:HAS_ACTION]->(:Action) diff --git a/pages/ai-ecosystem/ai-memory/context-graph/get-started.mdx b/pages/ai-ecosystem/ai-memory/get-started.mdx similarity index 94% rename from pages/ai-ecosystem/ai-memory/context-graph/get-started.mdx rename to pages/ai-ecosystem/ai-memory/get-started.mdx index 47a16bb84..eb5417871 100644 --- a/pages/ai-ecosystem/ai-memory/context-graph/get-started.mdx +++ b/pages/ai-ecosystem/ai-memory/get-started.mdx @@ -63,7 +63,7 @@ Setup lists what it found and what it will do: - **Name:** your user ID in the graph. Your memories are filed under it. It defaults to your git `user.name`, or your system user name. - **Memory:** whether your agents use Context Graph as their memory instead of - their own. See [Use Context Graph as your agents' memory](/ai-ecosystem/ai-memory/context-graph/recall-and-memory#use-context-graph-as-your-agents-memory). + their own. See [Use Context Graph as your agents' memory](/ai-ecosystem/ai-memory/recall-and-memory#use-context-graph-as-your-agents-memory). The plan updates as you change your choices. Nothing changes until you press **Install**. @@ -86,7 +86,7 @@ again only does what's missing. `~/.config/context-graph/config.toml`. 3. **Installs the packages:** the `memgraph-context-graph` command, the packages that record actions, skills and sessions, and the terminal viewer. -4. **Connects your agents.** See [Agents](/ai-ecosystem/ai-memory/context-graph/agents) +4. **Connects your agents.** See [Agents](/ai-ecosystem/ai-memory/agents) for what changes for each one. 5. **Checks the setup,** the same way as [`memgraph-context-graph doctor`](#3-check-the-setup). @@ -132,7 +132,7 @@ on a Memgraph without MAGE; recall then uses text search only. Work with your agents as before. Every session is recorded in the graph as it happens, with secrets redacted. To keep text out of the graph, wrap it in `` tags, or exclude a project; see -[Keep secrets out of the graph](/ai-ecosystem/ai-memory/context-graph/configuration#keep-secrets-out-of-the-graph). To see it, open the terminal viewer: +[Keep secrets out of the graph](/ai-ecosystem/ai-memory/configuration#keep-secrets-out-of-the-graph). To see it, open the terminal viewer: ```bash memgraph-context-graph ui @@ -191,11 +191,11 @@ memgraph-context-graph setup cursor --project-dir ~/work/billing --project-dir ~ ## Next steps -- [Recall and memory](/ai-ecosystem/ai-memory/context-graph/recall-and-memory): +- [Recall and memory](/ai-ecosystem/ai-memory/recall-and-memory): How your agents read their past sessions. -- [Configuration](/ai-ecosystem/ai-memory/context-graph/configuration): Use a +- [Configuration](/ai-ecosystem/ai-memory/configuration): Use a remote Memgraph, update Context Graph, or uninstall it. -- [Explore the graph](/ai-ecosystem/ai-memory/context-graph/explore-the-graph): +- [Explore the graph](/ai-ecosystem/ai-memory/explore-the-graph): Look at what your agents recorded. If setup fails in a way the report doesn't explain, ask on diff --git a/pages/ai-ecosystem/ai-memory/context-graph/knowledge-graph.mdx b/pages/ai-ecosystem/ai-memory/knowledge-graph.mdx similarity index 100% rename from pages/ai-ecosystem/ai-memory/context-graph/knowledge-graph.mdx rename to pages/ai-ecosystem/ai-memory/knowledge-graph.mdx diff --git a/pages/ai-ecosystem/ai-memory/context-graph/recall-and-memory.mdx b/pages/ai-ecosystem/ai-memory/recall-and-memory.mdx similarity index 96% rename from pages/ai-ecosystem/ai-memory/context-graph/recall-and-memory.mdx rename to pages/ai-ecosystem/ai-memory/recall-and-memory.mdx index 2a71a4c90..938f05042 100644 --- a/pages/ai-ecosystem/ai-memory/context-graph/recall-and-memory.mdx +++ b/pages/ai-ecosystem/ai-memory/recall-and-memory.mdx @@ -40,7 +40,7 @@ Recall combines several searches over your history: | Facts | Extracted facts that match, with the messages they came from | | Facts about you | All facts of the types that match, for questions that count or list things | -Entities and facts come from the [knowledge graph](/ai-ecosystem/ai-memory/context-graph/knowledge-graph). +Entities and facts come from the [knowledge graph](/ai-ecosystem/ai-memory/knowledge-graph). Before it's built, recall finds messages and memories only. The searches by meaning need [MAGE](/advanced-algorithms): Memgraph computes @@ -86,7 +86,7 @@ memgraph-context-graph config set session_start.resume false Recall's defaults are the settings it was evaluated with. To change how many results each search returns, or to drop a search, edit the `[recall]` section -of the [configuration file](/ai-ecosystem/ai-memory/context-graph/configuration#configuration-file): +of the [configuration file](/ai-ecosystem/ai-memory/configuration#configuration-file): | Key | Default | What it sets | | --- | --- | --- | @@ -131,7 +131,7 @@ setup: becomes `/memories/user/codex-memory-summary.md`. A file already in the graph is never overwritten. 2. **Turns off the agent's own memory,** as listed in - [Agents](/ai-ecosystem/ai-memory/context-graph/agents#built-in-memory). + [Agents](/ai-ecosystem/ai-memory/agents#built-in-memory). Setup backs up each file it edits. 3. **Saves the choice** as `backend = "context-graph"` in the `[memory]` section of the configuration file. @@ -193,7 +193,7 @@ also turns the agent's own memory back on. The optional `resources-graph` package remembers the public GitHub issues, pull requests and repositories your agents read, so they can read them from the graph instead of fetching them again. Turn it on in -[Configuration](/ai-ecosystem/ai-memory/context-graph/configuration#choose-what-is-recorded). +[Configuration](/ai-ecosystem/ai-memory/configuration#choose-what-is-recorded). When it's on: diff --git a/pages/ai-ecosystem/ai-memory/context-graph/shared-spaces.mdx b/pages/ai-ecosystem/ai-memory/shared-spaces.mdx similarity index 96% rename from pages/ai-ecosystem/ai-memory/context-graph/shared-spaces.mdx rename to pages/ai-ecosystem/ai-memory/shared-spaces.mdx index 1289cf5ae..18e46fc00 100644 --- a/pages/ai-ecosystem/ai-memory/context-graph/shared-spaces.mdx +++ b/pages/ai-ecosystem/ai-memory/shared-spaces.mdx @@ -122,7 +122,7 @@ memgraph-context-graph join bolt://memgraph.example.com:7687 alice `join` prompts for the password, installs the `context-graph-spaces` package if it's missing, and sets `edition = "enterprise"`, the URL, the login and the -password in the [configuration file](/ai-ecosystem/ai-memory/context-graph/configuration#configuration-file). +password in the [configuration file](/ai-ecosystem/ai-memory/configuration#configuration-file). It then checks the login and prints your personal space and the shared spaces you can read: @@ -132,8 +132,8 @@ Personal space: u_alice. Shared spaces: payments. ``` If this machine isn't set up yet, run -[setup](/ai-ecosystem/ai-memory/context-graph/get-started) next to connect +[setup](/ai-ecosystem/ai-memory/get-started) next to connect your agents. -In the [terminal viewer](/ai-ecosystem/ai-memory/context-graph/explore-the-graph#terminal-viewer), +In the [terminal viewer](/ai-ecosystem/ai-memory/explore-the-graph#terminal-viewer), press `w` to switch to the next space you can read. diff --git a/pages/database-management/enabling-memgraph-enterprise.mdx b/pages/database-management/enabling-memgraph-enterprise.mdx index 20ee0bd9f..35a3efd8f 100644 --- a/pages/database-management/enabling-memgraph-enterprise.mdx +++ b/pages/database-management/enabling-memgraph-enterprise.mdx @@ -281,7 +281,7 @@ memory usage. ### Context Graph shared spaces -[Shared spaces](/ai-ecosystem/ai-memory/context-graph/shared-spaces) run +[Shared spaces](/ai-ecosystem/ai-memory/shared-spaces) run Context Graph for a team on one Memgraph instance. Each user gets a personal database for their coding agents' memory, and teams get shared databases, isolated with multi-tenancy and role-based access control. From 04169f04561fae57cbdd8472359c06ee53e2a7e5 Mon Sep 17 00:00:00 2001 From: antejavor Date: Thu, 22 Oct 2026 11:12:27 +0200 Subject: [PATCH 06/11] Remove uncessary. --- pages/ai-ecosystem/ai-memory/get-started.mdx | 3 --- 1 file changed, 3 deletions(-) diff --git a/pages/ai-ecosystem/ai-memory/get-started.mdx b/pages/ai-ecosystem/ai-memory/get-started.mdx index eb5417871..dd4375d8c 100644 --- a/pages/ai-ecosystem/ai-memory/get-started.mdx +++ b/pages/ai-ecosystem/ai-memory/get-started.mdx @@ -68,9 +68,6 @@ Setup lists what it found and what it will do: The plan updates as you change your choices. Nothing changes until you press **Install**. -Without a terminal, for example in CI, the install command only prints the -setup command to run. Set `AI_MEMORY_SKIP_SETUP=1` to get the same behavior on -a terminal. ## 2. What setup does From a160f15f8ae8fb6528f4f74944d3f80804704f32 Mon Sep 17 00:00:00 2001 From: antejavor Date: Thu, 22 Oct 2026 11:45:14 +0200 Subject: [PATCH 07/11] update: Restructure the Context Graph docs, add a Privacy page and apply the docs rules --- pages/ai-ecosystem.mdx | 3 +- pages/ai-ecosystem/ai-memory.mdx | 161 ++++++---------- pages/ai-ecosystem/ai-memory/_meta.ts | 5 +- pages/ai-ecosystem/ai-memory/agents.mdx | 26 +-- .../ai-ecosystem/ai-memory/configuration.mdx | 163 +--------------- .../ai-memory/explore-the-graph.mdx | 4 +- pages/ai-ecosystem/ai-memory/get-started.mdx | 67 +++---- .../ai-memory/knowledge-graph.mdx | 19 +- pages/ai-ecosystem/ai-memory/privacy.mdx | 175 ++++++++++++++++++ .../ai-memory/recall-and-memory.mdx | 20 +- .../ai-ecosystem/ai-memory/shared-spaces.mdx | 2 +- 11 files changed, 314 insertions(+), 331 deletions(-) create mode 100644 pages/ai-ecosystem/ai-memory/privacy.mdx diff --git a/pages/ai-ecosystem.mdx b/pages/ai-ecosystem.mdx index 7e91a9b31..4cd25834b 100644 --- a/pages/ai-ecosystem.mdx +++ b/pages/ai-ecosystem.mdx @@ -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. diff --git a/pages/ai-ecosystem/ai-memory.mdx b/pages/ai-ecosystem/ai-memory.mdx index 2f093b5f4..a709105af 100644 --- a/pages/ai-ecosystem/ai-memory.mdx +++ b/pages/ai-ecosystem/ai-memory.mdx @@ -3,82 +3,52 @@ title: AI memory 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. -## Choose an approach +A query can follow those links, and combine them with +[vector search](/querying/vector-search) and +[text search](/querying/text-search). There are two ways to add this memory to an AI system: -- **[Use Context Graph](#use-context-graph)** to give your coding agents a - memory now. One command connects Claude Code, Codex and other coding agents - to Memgraph, and they record and recall their sessions with no code. -- **[Build your own memory](#build-your-own-memory)** for your own agent or +- [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. ## Use Context Graph -Context Graph gives your coding agents a memory that lasts across sessions and -is shared between agents. It records each session of Claude Code, Codex, GitHub -Copilot CLI, Cursor, OpenCode, Antigravity CLI or Grok Build in Memgraph: your -prompts, the agent's replies, the tools it called, the skills it used and the -memories it saved. In the next session, any of those agents can recall it. - -Context Graph is open source and part of the -[Memgraph AI Toolkit](https://github.com/memgraph/ai-toolkit/tree/main/context-graph). -It runs on your machine by default, with no account or cloud service, and -[redacts secrets](/ai-ecosystem/ai-memory/configuration#keep-secrets-out-of-the-graph) -before anything is stored. - -### Set up Context Graph - -You need [Docker](https://docs.docker.com/get-docker/), unless you already run -Memgraph 3.6 or later, and a terminal. Run the setup from the project -directory you work in: - - - -```bash -curl -sSL https://install.memgraph.com/ai-memory | bash -``` - - -In PowerShell 5.1 or 7: - -```powershell -iwr https://install.memgraph.com/ai-memory/windows -useb | iex -``` - - - -The setup shows its plan and changes nothing until you confirm. It finds or -starts Memgraph, installs Context Graph and connects your agents. See -[Get started](/ai-ecosystem/ai-memory/get-started) for what the setup does, -how to check it and how to change your choices. - -### What your agents get +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. -After setup, every connected agent gets three things: +Every connected agent gets: - **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), - finds what your past sessions hold about a question. A session also starts - with a short note on where you left off in the current project, whichever - agent you used last. -- **Memory.** If you turn it on, a `memory` tool replaces the agent's own - memory. The memories the agent saves are stored in the graph and shared by + 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. -See [Recall and memory](/ai-ecosystem/ai-memory/recall-and-memory) for how -each one works. +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 @@ -94,47 +64,32 @@ the session hangs off that node: ``` `Memory` nodes hold what the agent knows, `Action` nodes what it did, and -`Skill` nodes what it knows how to do. Because they share the `User` and -`Session` nodes, one traversal can recall all three together. - -Context Graph can also extract the people, projects, files and decisions your -sessions mention into a [knowledge graph](/ai-ecosystem/ai-memory/knowledge-graph), -linked back to the sessions that mention them. Recall uses it to find facts -across sessions. - -### Components - -Context Graph is a set of Python packages. Setup installs the ones you need, -so you only need this list to change what is recorded or to use a package in -your own application. - -| Package | What it records or does | -| --- | --- | -| `memgraph-context-graph` | The `memgraph-context-graph` command: setup, the hooks, the MCP server and the configuration. | -| `actions-graph` | Prompts, replies, tool calls and tool results, as `Action` nodes. | -| `skills-graph` | The agent skills a session used, as `Skill` nodes. | -| `sessions-graph` | Users, sessions and memories, the knowledge graph extracted from them, and recall. | -| `context-graph-viewer` | A read-only terminal viewer of the graph, opened with `memgraph-context-graph ui`. | -| `resources-graph` | GitHub issues, pull requests and repositories your agents read, so they can read them again from the graph. Off by default. | -| `context-graph-spaces` | [Shared spaces](/ai-ecosystem/ai-memory/shared-spaces) for teams on Memgraph Enterprise. | +`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 - and connect your agents with one command. -- [Agents](/ai-ecosystem/ai-memory/agents): What setup changes for each - supported agent. +- [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, a remote Memgraph, privacy settings, forgetting sessions, updates and - uninstalling. + file, your own Memgraph, updating and uninstalling. - [Knowledge graph](/ai-ecosystem/ai-memory/knowledge-graph): Extract entities and facts from your sessions. -- [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. +- [Agents](/ai-ecosystem/ai-memory/agents): The files setup changes for each + agent, and how the agents differ. - [Shared spaces](/ai-ecosystem/ai-memory/shared-spaces): Share memory between - the members of a team. + the members of a team, on Memgraph Enterprise. ## Build your own memory @@ -145,18 +100,18 @@ Graph, shown in ### Query the memory graph -Because facts, actions and skills 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: +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 whose memory you read. To see all the labels, @@ -168,15 +123,15 @@ SHOW SCHEMA INFO; This needs Memgraph started with `--schema-info-enabled=true`. -To search memory by meaning as well as by connections, add a +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) for search by words. +[text index](/querying/text-search) to search it by words. ### Use Context Graph's packages 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 +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. diff --git a/pages/ai-ecosystem/ai-memory/_meta.ts b/pages/ai-ecosystem/ai-memory/_meta.ts index a7eac9148..9ccdf9cd0 100644 --- a/pages/ai-ecosystem/ai-memory/_meta.ts +++ b/pages/ai-ecosystem/ai-memory/_meta.ts @@ -1,9 +1,10 @@ export default { "get-started": "Get started", - "agents": "Agents", "recall-and-memory": "Recall and memory", + "explore-the-graph": "Explore the graph", + "privacy": "Privacy", "configuration": "Configuration", "knowledge-graph": "Knowledge graph", - "explore-the-graph": "Explore the graph", + "agents": "Agents", "shared-spaces": "Shared spaces" } diff --git a/pages/ai-ecosystem/ai-memory/agents.mdx b/pages/ai-ecosystem/ai-memory/agents.mdx index 133d069e7..e3ae8bdb3 100644 --- a/pages/ai-ecosystem/ai-memory/agents.mdx +++ b/pages/ai-ecosystem/ai-memory/agents.mdx @@ -8,9 +8,11 @@ import { Tabs } from 'nextra/components' # Agents Context Graph works with seven coding agents. For each one, setup installs -hooks that record sessions, registers the MCP server that serves the `recall` +hooks that record sessions, registers the Model Context Protocol (MCP) server +that serves the `recall` and `memory` tools, and can turn off the agent's own memory. This page lists -what setup changes for each agent, so you know which files it edits. +the files setup changes for each agent, and where the agents behave +differently. ## Supported agents @@ -27,13 +29,11 @@ what setup changes for each agent, so you know which files it edits. Use the runtime name to choose agents in `memgraph-context-graph setup`, `update`, `uninstall` and `doctor`. -- **Claude Code and Codex** get the Context Graph plugin, installed for your - user. Every session of the agent is recorded, in any directory. -- **The other agents** get hook files in the project directory, never in your - home directory. Only sessions started in a connected project are recorded. - Setup connects the current directory; connect more projects with - `--project-dir`. If a hook file already exists, setup keeps your own hooks - in it. +Claude Code and Codex sessions are recorded in any directory. For the other +agents, the hook file is in the project directory, never in your home +directory, so only sessions started in a connected project are recorded. +Connect more projects with `--project-dir`. If a hook file already exists, +setup keeps your own hooks in it. ## MCP server registration @@ -119,13 +119,13 @@ codex plugin add context-graph@context-graph-plugins -For the per-project agents, `memgraph-context-graph hook init RUNTIME` writes -the hook file in the current directory, where `RUNTIME` is `copilot-cli`, -`cursor`, `opencode`, `antigravity-cli` or `grok`: +For the per-project agents, the `memgraph-context-graph hook init RUNTIME` +command writes the hook file in the current directory, where `RUNTIME` is the +agent's runtime name: ```bash memgraph-context-graph hook init cursor ``` -`hook init` writes only the hooks. Run `memgraph-context-graph setup` for the +The `hook init` command writes only the hooks. Run `memgraph-context-graph setup` for the MCP server registration and the memory switch. diff --git a/pages/ai-ecosystem/ai-memory/configuration.mdx b/pages/ai-ecosystem/ai-memory/configuration.mdx index eeac3e996..4d8bcf423 100644 --- a/pages/ai-ecosystem/ai-memory/configuration.mdx +++ b/pages/ai-ecosystem/ai-memory/configuration.mdx @@ -1,16 +1,14 @@ --- title: Configure Context Graph -description: Configure Context Graph's Memgraph connection, identity and what it records, keep secrets out of the graph, and update or uninstall it. +description: Configure Context Graph's Memgraph connection, identity and what it records, and update or uninstall Context Graph. --- import { Callout } from 'nextra/components' # Configure Context Graph -Context Graph keeps its settings in one configuration file. This page covers -the file, connecting to your own Memgraph, choosing what is recorded, keeping -secrets out of the graph, forgetting sessions, and updating or removing -Context Graph. +Context Graph keeps its settings in one configuration file. Setup writes it, +and the `config` command changes it. ## Configuration file @@ -38,9 +36,9 @@ memgraph-context-graph config set identity.user_id alice | `memgraph.password` | Empty | The Memgraph password. `config set memgraph.password` without a value prompts for it. | | `memgraph.database` | `memgraph` | The database, on a Memgraph with [multi-tenancy](/database-management/multi-tenancy) | | `capture.connectors` | `skills-graph, actions-graph, sessions-graph` | What the hooks record. See [Choose what is recorded](#choose-what-is-recorded). | -| `capture.redact` | `true` | Whether secrets are redacted before they're stored. See [Keep secrets out of the graph](#keep-secrets-out-of-the-graph). | -| `capture.max_chars` | `100000` | The most characters kept from one text field, such as a tool's output. `0` keeps everything. | -| `capture.exclude_tools` | None | Tools whose calls and results aren't recorded, by name or glob | +| `capture.redact` | `true` | Whether secrets are redacted before they're stored. See [Redact secrets](/ai-ecosystem/ai-memory/privacy#redact-secrets). | +| `capture.max_chars` | `100000` | The most characters kept from one text field, such as a tool's output. `0` keeps everything. See [Shorten long text](/ai-ecosystem/ai-memory/privacy#shorten-long-text). | +| `capture.exclude_tools` | None | Tools whose calls and results aren't recorded, by name or glob. See [Exclude tools and projects](/ai-ecosystem/ai-memory/privacy#exclude-tools-and-projects). | | `capture.exclude_projects` | None | Directories in which nothing is recorded, by path or glob | | `memory.backend` | Unset | `context-graph` when Context Graph is the agents' [memory](/ai-ecosystem/ai-memory/recall-and-memory#use-context-graph-as-your-agents-memory). Set it with setup's `--memory-backend`, which also changes the agents' settings. | | `session_start.resume` | `true` | Whether a session starts with the [note on where you left off](/ai-ecosystem/ai-memory/recall-and-memory#where-you-left-off) | @@ -119,156 +117,11 @@ memgraph-context-graph setup Setup installs the connectors the setting names. An empty value records nothing, without disconnecting the agents. -## Keep secrets out of the graph - -The hooks record prompts, replies, and tool input and output in full, so a -session can contain an API key from a `.env` file or text you don't want -stored. Before anything reaches Memgraph, Context Graph removes what you mark -as private, redacts secrets, and shortens long text. What it removes is never -stored. - -These rules apply to everything the hooks record, for every agent. They don't -apply to memory files the agent writes with the -[`memory` tool](/ai-ecosystem/ai-memory/recall-and-memory#how-the-agent-uses-memory), -which are stored as written. - -### Mark text as private - -Text between `` and `` is removed from prompts, replies and -tool input and output: - -```plaintext -Connect to the staging database. The password is in the team vault under "staging-db". -``` - -Context Graph stores only "Connect to the staging database.". The agent still -gets the whole prompt. If a prompt has nothing outside its private block, it -isn't stored at all. An unclosed `` hides the rest of the text. - -### Redact secrets - -Context Graph replaces known kinds of secrets with `[REDACTED:NAME]`, where -`NAME` says what was removed: - -| Name | What it matches | -| --- | --- | -| `private_key` | PEM private key blocks | -| `aws_access_key` | AWS access key IDs | -| `github_token` | GitHub tokens and fine-grained personal access tokens | -| `anthropic_key` | Anthropic API keys | -| `openai_key` | OpenAI API keys | -| `slack_token` | Slack tokens | -| `stripe_key` | Stripe secret and restricted keys | -| `google_api_key` | Google API keys | -| `jwt` | JSON Web Tokens | -| `url_password` | Passwords in URLs, such as `postgres://user:PASSWORD@host` | -| `config_secret` | The Memgraph password, API keys and GitHub token in the configuration file, if they're at least 6 characters long | - -To redact your own patterns, add a `[redact]` section to the configuration -file. Each key is the name in the replacement, and each value is a -[Python regular expression](https://docs.python.org/3/library/re.html#regular-expression-syntax) -in single quotes: - -```toml -[redact] -ticket = 'ACME-[0-9]+' -customer_email = '[A-Za-z0-9._%+-]+@acme\.com' -``` - -An invalid pattern is ignored and reported as a configuration warning, and -recording continues. - -Redaction matches known shapes of secrets, so it doesn't catch every secret. -Use `` or `capture.exclude_projects` for anything it might miss. - -To turn redaction off, so that only `` blocks are removed: - -```bash -memgraph-context-graph config set capture.redact false -``` - -### Shorten long text - -Each text field, such as a tool's output, is cut after `capture.max_chars` -characters, 100,000 by default, and ends with a note of how many characters -were removed. To change the limit, or to keep everything with `0`: - -```bash -memgraph-context-graph config set capture.max_chars 20000 -``` - -### Exclude tools and projects - -To stop recording some tools' calls and results, list their names. A name can -be a glob, such as `mcp__vault__*` for every tool of one MCP server: - -```bash -memgraph-context-graph config set capture.exclude_tools "TodoWrite, mcp__vault__*" -``` - -To record nothing from some projects, list their directories. A session that -starts in one of them, or in a directory inside one, isn't recorded. `~` stands -for your home directory, and a path can be a glob: - -```bash -memgraph-context-graph config set capture.exclude_projects "~/clients/*, ~/personal" -``` - -The agent works as usual in an excluded project, and recall still finds your -other sessions there. - -Setting a list replaces the previous one. To clear it, set an empty value: - -```bash -memgraph-context-graph config set capture.exclude_projects "" -``` - -## Forget sessions - -`forget` deletes sessions from your graph for good, with everything recorded in -them and everything extracted from them. Delete sessions by ID: - -```bash -memgraph-context-graph forget session SESSION_ID -``` - -`SESSION_ID` is the session's `session_id`, shown in the -[terminal viewer](/ai-ecosystem/ai-memory/explore-the-graph#terminal-viewer). -Pass several IDs to delete several sessions. - -To delete every session that ran in a directory or inside it, pass the -directory: - -```bash -memgraph-context-graph forget project ~/work/client-repo -``` - -`forget` lists the matching sessions and asks before it deletes them. Add -`--dry-run` to only list them, and `--yes` to skip the question. Without a -terminal, `--yes` is required. - -For each session, `forget` deletes: - -- its prompts, replies, tool calls and results, its skill uses, and its - records of GitHub resources; -- what reconciliation extracted from it, and every entity no other session or - memory file mentions; -- its lines in the log of failed recordings. - -Entities that other sessions mention, skills, stored GitHub resources and your -memory files stay, including files the session wrote. A forgotten session -leaves only a `ForgottenSession` node with its ID, which stops a hook that is -still running, or a resumed session, from recording it again. - -Only the agent's user can forget sessions: the agent has no tool for it. With -[shared spaces](/ai-ecosystem/ai-memory/shared-spaces), `forget` -deletes from your personal space only. - ## Update Context Graph Context Graph doesn't update itself. Upgrading the packages changes the code the hooks run, but the plugins, hook files and MCP registrations that setup -wrote stay as they were. `update` upgrades both in one step: +wrote stay as they were. The `update` command upgrades both in one step: ```bash memgraph-context-graph update @@ -320,7 +173,7 @@ Updating only the plugin doesn't upgrade the packages its hooks run. Run ## Uninstall Context Graph -`uninstall` disconnects your agents: it removes the plugins, hook files and MCP +The `uninstall` command disconnects your agents: it removes the plugins, hook files and MCP registrations, and turns the agents' own memory back on. ```bash diff --git a/pages/ai-ecosystem/ai-memory/explore-the-graph.mdx b/pages/ai-ecosystem/ai-memory/explore-the-graph.mdx index e34cbd1e0..2236947fd 100644 --- a/pages/ai-ecosystem/ai-memory/explore-the-graph.mdx +++ b/pages/ai-ecosystem/ai-memory/explore-the-graph.mdx @@ -40,8 +40,8 @@ The most useful keys: | `?` | Show all keys | | `esc`, `q` | Go back, quit | -The viewer shows your own sessions by default. Sessions recorded before you -had a user ID belong to no user. If the dashboard is empty, press `a`. +The viewer shows your own sessions by default. If the dashboard is empty, +press `a`: sessions recorded while no user ID was set belong to no user. ## Memgraph Lab diff --git a/pages/ai-ecosystem/ai-memory/get-started.mdx b/pages/ai-ecosystem/ai-memory/get-started.mdx index dd4375d8c..62e6b6bac 100644 --- a/pages/ai-ecosystem/ai-memory/get-started.mdx +++ b/pages/ai-ecosystem/ai-memory/get-started.mdx @@ -8,29 +8,32 @@ import { Tabs } from 'nextra/components' # Get started with Context Graph One command installs Context Graph, finds or starts Memgraph, and connects -every coding agent it finds on your machine. Setup shows its plan and changes -nothing until you confirm. +the coding agents you choose. Setup shows its plan and changes nothing until +you confirm. + +From then on, Context Graph records your prompts, the agent's replies, and +every tool call with its input and output, in full. Known kinds of secrets are +redacted first. Read [Privacy](/ai-ecosystem/ai-memory/privacy) to keep other +text out of the graph. ## Prerequisites -- **A terminal.** Setup asks its questions there. -- **Docker**, unless you already run Memgraph. Setup starts Memgraph in a - container. See [Get Docker](https://docs.docker.com/get-docker/). -- **Your own Memgraph, if you don't use Docker:** Memgraph 3.6 or later. For - recall by meaning, use the [MAGE](/advanced-algorithms) image - (`memgraph/memgraph-mage`) with at least 2 GiB of memory; without MAGE, - recall falls back to text search. -- **At least one supported agent** on your `PATH`: Claude Code, Codex, GitHub - Copilot CLI, Cursor, OpenCode, Antigravity CLI or Grok Build. +- **Memgraph 3.6 or later, or Docker.** If setup doesn't find a Memgraph, it + starts one with [Docker](https://docs.docker.com/get-docker/). If you bring + your own Memgraph, use the [MAGE](/advanced-algorithms) image + (`memgraph/memgraph-mage`) with at least 2 GiB of memory for recall by + meaning; without MAGE, recall uses text search only. +- **At least one [supported agent](/ai-ecosystem/ai-memory/agents#supported-agents)** + on your `PATH`. You don't need Python. Setup installs [uv](https://docs.astral.sh/uv/) if it's missing, and uv installs the rest. ## 1. Run setup -Run setup from the project directory you work in. Claude Code and Codex are -connected for your user, but the other agents are connected one project at a -time, starting with the current directory. +Run setup in a terminal, from the project directory you work in. Claude Code +and Codex are connected for your user, in every directory. The other agents +are connected one project at a time, starting with the current directory. @@ -63,16 +66,16 @@ Setup lists what it found and what it will do: - **Name:** your user ID in the graph. Your memories are filed under it. It defaults to your git `user.name`, or your system user name. - **Memory:** whether your agents use Context Graph as their memory instead of - their own. See [Use Context Graph as your agents' memory](/ai-ecosystem/ai-memory/recall-and-memory#use-context-graph-as-your-agents-memory). + their own. Recall works either way, and you can change this later. See + [Use Context Graph as your agents' memory](/ai-ecosystem/ai-memory/recall-and-memory#use-context-graph-as-your-agents-memory). The plan updates as you change your choices. Nothing changes until you press **Install**. +### What setup does -## 2. What setup does - -Setup runs these steps in order. Each step checks first, so running setup -again only does what's missing. +After you press **Install**, setup runs these steps in order. Each step checks +first, so running setup again only does what's missing. 1. **Finds or starts Memgraph.** Setup uses the Memgraph in its configuration file, then a Memgraph on `localhost:7687`. Otherwise, it starts the @@ -86,11 +89,11 @@ again only does what's missing. 4. **Connects your agents.** See [Agents](/ai-ecosystem/ai-memory/agents) for what changes for each one. 5. **Checks the setup,** the same way as - [`memgraph-context-graph doctor`](#3-check-the-setup). + [`memgraph-context-graph doctor`](#2-check-the-setup). The report ends with the command to rerun for any step that failed. -## 3. Check the setup +## 2. Check the setup Restart any agent sessions that were running during setup, because a running session keeps the hooks it started with. Then check the setup: @@ -99,9 +102,9 @@ session keeps the hooks it started with. Then check the setup: memgraph-context-graph doctor --runtime claude-code ``` -Replace `claude-code` with the agent you want to check: `codex`, -`copilot-cli`, `cursor`, `opencode`, `antigravity-cli` or `grok`. Every line -starts with `OK` when the setup works: +Replace `claude-code` with the +[runtime name](/ai-ecosystem/ai-memory/agents#supported-agents) of the agent +you want to check. Every line starts with `OK` when the setup works: ```plaintext copy=false OK memgraph-context-graph executable: ... @@ -124,12 +127,10 @@ the agent isn't on your `PATH`, or the plugin isn't installed or is disabled. A line that starts with `FAIL` says what failed. The `embeddings` check fails on a Memgraph without MAGE; recall then uses text search only. -## 4. Use your agents +## 3. Use your agents -Work with your agents as before. Every session is recorded in the graph as it -happens, with secrets redacted. To keep text out of the graph, wrap it in -`` tags, or exclude a project; see -[Keep secrets out of the graph](/ai-ecosystem/ai-memory/configuration#keep-secrets-out-of-the-graph). To see it, open the terminal viewer: +Work with your agents as before. To see the sessions being recorded, open the +terminal viewer: ```bash memgraph-context-graph ui @@ -161,7 +162,7 @@ curl -fsSL https://raw.githubusercontent.com/memgraph/ai-toolkit/main/context-gr | Flag | What it sets | | --- | --- | -| `RUNTIME ...` | The agents to connect: `claude-code`, `codex`, `copilot-cli`, `cursor`, `opencode`, `antigravity-cli` or `grok`. The default is every agent on your `PATH`. | +| `RUNTIME ...` | The [runtime names](/ai-ecosystem/ai-memory/agents#supported-agents) of the agents to connect. The default is every agent on your `PATH`. | | `--project-dir DIR` | A project to connect the per-project agents in. Repeat it for more projects. The default is the current directory. | | `--memgraph-url URL` | The Memgraph to use, instead of finding or starting one. | | `--user-id NAME` | Your user ID in the graph. The default is the configured one, then your git `user.name`. | @@ -190,10 +191,12 @@ memgraph-context-graph setup cursor --project-dir ~/work/billing --project-dir ~ - [Recall and memory](/ai-ecosystem/ai-memory/recall-and-memory): How your agents read their past sessions. -- [Configuration](/ai-ecosystem/ai-memory/configuration): Use a - remote Memgraph, update Context Graph, or uninstall it. - [Explore the graph](/ai-ecosystem/ai-memory/explore-the-graph): Look at what your agents recorded. +- [Privacy](/ai-ecosystem/ai-memory/privacy): Keep text out of the graph and + delete sessions. +- [Configuration](/ai-ecosystem/ai-memory/configuration): Use a + remote Memgraph, update Context Graph, or uninstall it. If setup fails in a way the report doesn't explain, ask on [Discord](https://discord.gg/memgraph) or open an issue on diff --git a/pages/ai-ecosystem/ai-memory/knowledge-graph.mdx b/pages/ai-ecosystem/ai-memory/knowledge-graph.mdx index 911c08a10..a93129c33 100644 --- a/pages/ai-ecosystem/ai-memory/knowledge-graph.mdx +++ b/pages/ai-ecosystem/ai-memory/knowledge-graph.mdx @@ -46,8 +46,8 @@ To extract one session, pass its ID: sessions-graph reconcile --session SESSION_ID ``` -`SESSION_ID` is the `session_id` property of the `Session` node. The terminal -viewer shows it for each session. +`SESSION_ID` is the session's `session_id`, shown in the +[terminal viewer](/ai-ecosystem/ai-memory/explore-the-graph#terminal-viewer). Extraction takes longer than an agent allows a hook to run, so it never runs inside a hook. Choose how it runs: @@ -64,9 +64,8 @@ inside a hook. Choose how it runs: cron or another scheduler. `--limit` caps how many sessions one run extracts. -Codex, Antigravity CLI and `opencode run` don't report when a session ends. -Their sessions are marked pending at the end of each turn, so -`reconcile --pending` extracts them too. +Codex, Antigravity CLI and `opencode run` don't report when a session ends, +so their sessions are marked pending at the end of each turn instead. Memory files are extracted on their own, because a file outlives the session that wrote it. Each change to a file marks it pending, and @@ -144,10 +143,12 @@ memgraph-context-graph config set llm.anthropic_api_key default model is `gpt-5`; set another model with `llm.derive_model`. Learning starts on its own when you have 2, 4, 8 and so on up to 128 sessions -with enough of your own text (at least 2 of your messages and 1,000 -characters), and then every 128 sessions. Each run reads up to 64 recent -sessions, proposes new schemas, and keeps one only if it types more of your -messages without adding more catch-all entities. To run it now: +with enough of your own text, and then every 128 sessions. A session has +enough text with at least 2 of your messages and 1,000 characters. + +Each run reads up to 64 recent sessions and proposes new schemas. It keeps one +only if it types more of your messages without adding more catch-all +entities. To run it now: ```bash sessions-graph derive --force diff --git a/pages/ai-ecosystem/ai-memory/privacy.mdx b/pages/ai-ecosystem/ai-memory/privacy.mdx new file mode 100644 index 000000000..5ecc355f6 --- /dev/null +++ b/pages/ai-ecosystem/ai-memory/privacy.mdx @@ -0,0 +1,175 @@ +--- +title: Privacy +description: See what Context Graph records from your agent sessions and where it goes, keep secrets and private text out of the graph, and delete sessions. +--- + +# Privacy + +Context Graph stores your agent sessions in the Memgraph in your +[configuration](/ai-ecosystem/ai-memory/configuration#configuration-file). By +default, that is a Memgraph that setup started in Docker on your machine, +listening on `127.0.0.1` only. + +Recorded sessions are sent nowhere else, with one exception. With an +Anthropic or OpenAI API key, +[schema learning](/ai-ecosystem/ai-memory/knowledge-graph#learn-the-schema-from-your-sessions) +sends that provider the full text of up to 64 recent sessions per run, +including the agent's replies and tool input and output. Without a key, it +doesn't run. + +The hooks use only the keys in the configuration file. A `sessions-graph` +command you run from a shell also uses `ANTHROPIC_API_KEY` or +`OPENAI_API_KEY` from your environment. + +Extraction and embeddings run locally: Context Graph downloads the models, +not your text. The Memgraph that setup starts sends Memgraph's +[telemetry](/fundamentals/telemetry); start your own Memgraph with +`--telemetry-enabled=false` to turn it off. + +## Keep text out of the graph + +The hooks that setup installs in each agent record prompts, replies, and tool +input and output in full, so a +session can contain an API key from a `.env` file or text you don't want +stored. Before anything reaches Memgraph, Context Graph removes what you mark +as private, redacts secrets, and shortens long text. What it removes is never +stored. + +These rules apply to everything the hooks record, for every agent. They don't +apply to memory files the agent writes with the +[`memory` tool](/ai-ecosystem/ai-memory/recall-and-memory#how-the-agent-uses-memory), +which are stored as written. + +### Mark text as private + +Text between `` and `` is removed from prompts, replies and +tool input and output: + +```plaintext +Connect to the staging database. The password is in the team vault under "staging-db". +``` + +Context Graph stores only "Connect to the staging database.". The agent still +gets the whole prompt. If a prompt has nothing outside its private block, it +isn't stored at all. An unclosed `` hides the rest of the text. + +### Redact secrets + +Context Graph replaces known kinds of secrets with `[REDACTED:NAME]`, where +`NAME` says what was removed: + +| Name | What it matches | +| --- | --- | +| `private_key` | PEM private key blocks | +| `aws_access_key` | AWS access key IDs | +| `github_token` | GitHub tokens and fine-grained personal access tokens | +| `anthropic_key` | Anthropic API keys | +| `openai_key` | OpenAI API keys | +| `slack_token` | Slack tokens | +| `stripe_key` | Stripe secret and restricted keys | +| `google_api_key` | Google API keys | +| `jwt` | JSON Web Tokens | +| `url_password` | Passwords in URLs, such as `postgres://user:PASSWORD@host` | +| `config_secret` | The Memgraph password, API keys and GitHub token in the configuration file, if they're at least 6 characters long | + +To redact your own patterns, add a `[redact]` section to the configuration +file. Each key is the name in the replacement, and each value is a +[Python regular expression](https://docs.python.org/3/library/re.html#regular-expression-syntax) +in single quotes: + +```toml +[redact] +ticket = 'ACME-[0-9]+' +customer_email = '[A-Za-z0-9._%+-]+@acme\.com' +``` + +An invalid pattern is ignored and reported as a configuration warning, and +recording continues. + +Redaction matches known shapes of secrets, so it doesn't catch every secret. +Use `` or `capture.exclude_projects` for anything it might miss. + +To turn redaction off, so that only `` blocks are removed: + +```bash +memgraph-context-graph config set capture.redact false +``` + +### Shorten long text + +Each text field, such as a tool's output, is cut after `capture.max_chars` +characters, 100,000 by default, and ends with a note of how many characters +were removed. To change the limit, or to keep everything with `0`: + +```bash +memgraph-context-graph config set capture.max_chars 20000 +``` + +### Exclude tools and projects + +To stop recording some tools' calls and results, list their names. A name can +be a glob, such as `mcp__vault__*` for every tool of one MCP server: + +```bash +memgraph-context-graph config set capture.exclude_tools "TodoWrite, mcp__vault__*" +``` + +To record nothing from some projects, list their directories. A session that +starts in one of them, or in a directory inside one, isn't recorded. `~` stands +for your home directory, and a path can be a glob: + +```bash +memgraph-context-graph config set capture.exclude_projects "~/clients/*, ~/personal" +``` + +The agent works as usual in an excluded project, and recall still finds your +other sessions there. + +Setting a list replaces the previous one. To clear it, set an empty value: + +```bash +memgraph-context-graph config set capture.exclude_projects "" +``` + +## Forget sessions + +The `forget` command deletes sessions from your graph for good, with everything recorded in +them and everything extracted from them. Delete sessions by ID: + +```bash +memgraph-context-graph forget session SESSION_ID +``` + +`SESSION_ID` is the session's `session_id`, shown in the +[terminal viewer](/ai-ecosystem/ai-memory/explore-the-graph#terminal-viewer). +Pass several IDs to delete several sessions. + +To delete every session that ran in a directory or inside it, pass the +directory: + +```bash +memgraph-context-graph forget project ~/work/client-repo +``` + +`forget` lists the matching sessions and asks before it deletes them. Add +`--dry-run` to only list them, and `--yes` to skip the question. Without a +terminal, `--yes` is required. + +For each session, `forget` deletes: + +- its prompts, replies, tool calls and results, its skill uses, and its + records of GitHub resources; +- what reconciliation extracted from it, and every entity no other session or + memory file mentions; +- its lines in the log of failed recordings. + +Entities that other sessions mention, skills, stored GitHub resources and your +memory files stay, including files the session wrote. A forgotten session +leaves only a `ForgottenSession` node with its ID, which stops a hook that is +still running, or a resumed session, from recording it again. + +Only you can forget sessions, from the command line. The agents have no tool +for it. With +[shared spaces](/ai-ecosystem/ai-memory/shared-spaces), `forget` +deletes from your personal space only. + diff --git a/pages/ai-ecosystem/ai-memory/recall-and-memory.mdx b/pages/ai-ecosystem/ai-memory/recall-and-memory.mdx index 938f05042..a954268c7 100644 --- a/pages/ai-ecosystem/ai-memory/recall-and-memory.mdx +++ b/pages/ai-ecosystem/ai-memory/recall-and-memory.mdx @@ -3,8 +3,6 @@ title: Recall and memory description: Let coding agents recall their past sessions from Memgraph, and make Context Graph their long-term memory shared across agents. --- -import { Callout } from 'nextra/components' - # Recall and memory Context Graph gives your agents two ways to use what earlier sessions left @@ -21,9 +19,11 @@ the agent's own memory. The `recall` tool takes one argument, a question, and returns the parts of your past sessions that match it: dated messages, and facts extracted from them. It doesn't answer the question; the agent's model answers from what -recall returns. The results come with a short header that tells the model how -to read them, for example that a later message about the same thing replaces -an earlier one. +recall returns. + +The results start with a short header that tells the model how to read them, +for example that a later message about the same thing replaces an earlier +one. Recall searches only your own sessions. Your user ID comes from the configuration file, never from the tool call, so an agent can't read another @@ -84,7 +84,7 @@ memgraph-context-graph config set session_start.resume false ### Tune recall -Recall's defaults are the settings it was evaluated with. To change how many +To change how many results each search returns, or to drop a search, edit the `[recall]` section of the [configuration file](/ai-ecosystem/ai-memory/configuration#configuration-file): @@ -142,7 +142,8 @@ because agents list their tools when a session starts. ### How the agent uses memory -With the switch on, the MCP server also serves a `memory` tool. It has the +With the switch on, Context Graph's Model Context Protocol (MCP) server also +serves a `memory` tool. It has the commands of the [Claude memory tool](https://docs.claude.com/en/docs/agents-and-tools/tool-use/memory-tool): `view`, `create`, `str_replace`, `insert`, `delete` and `rename`, on files @@ -171,11 +172,6 @@ The index is built from the graph each time, so it's never out of date. - Context Graph keeps the last 20 versions of each file. Overwriting, editing or deleting a file saves its previous text first, as a `MemoryVersion` node. - -Without the switch, the `memory` tool isn't listed, and the agent keeps using -its own memory. Recall works either way. - - ### Switch back To give memory back to the agent: diff --git a/pages/ai-ecosystem/ai-memory/shared-spaces.mdx b/pages/ai-ecosystem/ai-memory/shared-spaces.mdx index 18e46fc00..49457b560 100644 --- a/pages/ai-ecosystem/ai-memory/shared-spaces.mdx +++ b/pages/ai-ecosystem/ai-memory/shared-spaces.mdx @@ -114,7 +114,7 @@ can't find them by meaning or through the knowledge graph. ## Join as a user -Each user runs `join` with the Memgraph URL and their login: +Each user runs the `join` command with the Memgraph URL and their login: ```bash memgraph-context-graph join bolt://memgraph.example.com:7687 alice From efa231bbd2f5148bf62bac1c6f4ea0b97ec802d0 Mon Sep 17 00:00:00 2001 From: antejavor Date: Thu, 22 Oct 2026 12:38:59 +0200 Subject: [PATCH 08/11] add: Context Graph data flow diagram on AI memory, with a dark version --- pages/ai-ecosystem/ai-memory.mdx | 17 ++ .../ai-memory/context-graph-flow-dark.svg | 209 ++++++++++++++++++ .../ai-memory/context-graph-flow.svg | 209 ++++++++++++++++++ styles/globals.css | 7 +- 4 files changed, 441 insertions(+), 1 deletion(-) create mode 100644 public/pages/ai-ecosystem/ai-memory/context-graph-flow-dark.svg create mode 100644 public/pages/ai-ecosystem/ai-memory/context-graph-flow.svg diff --git a/pages/ai-ecosystem/ai-memory.mdx b/pages/ai-ecosystem/ai-memory.mdx index a709105af..641d6af42 100644 --- a/pages/ai-ecosystem/ai-memory.mdx +++ b/pages/ai-ecosystem/ai-memory.mdx @@ -42,6 +42,23 @@ Every connected agent gets: memory, so the notes the agent saves are stored in the graph and shared by all your agents. +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. + +
+ +![Context Graph in three phases: during a session, the memgraph-context-graph hooks in the coding agent 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) + +
+
+ +![Context Graph in three phases: during a session, the memgraph-context-graph hooks in the coding agent 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) + +
+ 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 diff --git a/public/pages/ai-ecosystem/ai-memory/context-graph-flow-dark.svg b/public/pages/ai-ecosystem/ai-memory/context-graph-flow-dark.svg new file mode 100644 index 000000000..b464c4e82 --- /dev/null +++ b/public/pages/ai-ecosystem/ai-memory/context-graph-flow-dark.svg @@ -0,0 +1,209 @@ + + How Context Graph records and recalls agent sessions + During a session, the memgraph-context-graph hooks in the coding agent drop private text and redact secrets, and the actions-graph, skills-graph and sessions-graph connectors write the session to Memgraph as a graph of users, sessions, actions, skills and memories. The optional resources-graph connector records GitHub resources, and context-graph-spaces adds shared spaces on Memgraph Enterprise. The MCP server reads Memgraph and serves the recall and memory tools to the agent. After a session, reconciliation filters the text through the HyGM ontology, extracts entities and facts with GLiNER2 and stores them in Memgraph with their embeddings. Only optional schema learning sends session text to an Anthropic or OpenAI API. + + + + + + + + + + + + + + + + YOUR MACHINE + + + + DURING A SESSION + + IN MEMGRAPH + + AFTER A SESSION + + + + Coding agent + Claude Code, Codex, Cursor and others + + MCP server + recall and memory tools + + + + + Capture + Hooks drop <private> text and redact secrets + + memgraph-context-graph + hooks, MCP server and setup + + + + actions-graph + + skills-graph + + sessions-graph + + + resources-graph + GitHub, off by default + + context-graph-spaces + + ENTERPRISE + + + write + + + + Memgraph + + + + + + + + + + + User + + Memory + + + Session + + + + + Action + + Skill + + + + + + + + + + + + + + + + + + + Knowledge graph + + + + + read + + + pending sessions + + + Reconciliation + Runs locally + + ONTOLOGY + HyGM: entity and fact types + + + Extract entities and facts with GLiNER2 + + + Store them with their embeddings + + + + Schema learning + + + session text, only with an API key + + Anthropic or OpenAI API + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/public/pages/ai-ecosystem/ai-memory/context-graph-flow.svg b/public/pages/ai-ecosystem/ai-memory/context-graph-flow.svg new file mode 100644 index 000000000..5cca5cda1 --- /dev/null +++ b/public/pages/ai-ecosystem/ai-memory/context-graph-flow.svg @@ -0,0 +1,209 @@ + + How Context Graph records and recalls agent sessions + During a session, the memgraph-context-graph hooks in the coding agent drop private text and redact secrets, and the actions-graph, skills-graph and sessions-graph connectors write the session to Memgraph as a graph of users, sessions, actions, skills and memories. The optional resources-graph connector records GitHub resources, and context-graph-spaces adds shared spaces on Memgraph Enterprise. The MCP server reads Memgraph and serves the recall and memory tools to the agent. After a session, reconciliation filters the text through the HyGM ontology, extracts entities and facts with GLiNER2 and stores them in Memgraph with their embeddings. Only optional schema learning sends session text to an Anthropic or OpenAI API. + + + + + + + + + + + + + + + + YOUR MACHINE + + + + DURING A SESSION + + IN MEMGRAPH + + AFTER A SESSION + + + + Coding agent + Claude Code, Codex, Cursor and others + + MCP server + recall and memory tools + + + + + Capture + Hooks drop <private> text and redact secrets + + memgraph-context-graph + hooks, MCP server and setup + + + + actions-graph + + skills-graph + + sessions-graph + + + resources-graph + GitHub, off by default + + context-graph-spaces + + ENTERPRISE + + + write + + + + Memgraph + + + + + + + + + + + User + + Memory + + + Session + + + + + Action + + Skill + + + + + + + + + + + + + + + + + + + Knowledge graph + + + + + read + + + pending sessions + + + Reconciliation + Runs locally + + ONTOLOGY + HyGM: entity and fact types + + + Extract entities and facts with GLiNER2 + + + Store them with their embeddings + + + + Schema learning + + + session text, only with an API key + + Anthropic or OpenAI API + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/styles/globals.css b/styles/globals.css index 705470a25..fbb7c8605 100644 --- a/styles/globals.css +++ b/styles/globals.css @@ -303,4 +303,9 @@ html.dark div.nextra-nav-container { .dark .custom-header::before { color: var(--ash-gray) !important; -} \ No newline at end of file +} +/* Show an image only in the light or only in the dark theme */ +.dark .light-only, +html:not(.dark) .dark-only { + display: none; +} From 188b33f9da0fe850bf33262f272f3bdab0d64958 Mon Sep 17 00:00:00 2001 From: antejavor Date: Thu, 22 Oct 2026 14:25:53 +0200 Subject: [PATCH 09/11] update: Context Graph docs for ai-toolkit #598-#601: Agent SDK apps, config set for all keys, memory hand-back, setup's own Memgraph --- pages/ai-ecosystem/ai-memory.mdx | 6 +- pages/ai-ecosystem/ai-memory/_meta.ts | 1 + .../ai-ecosystem/ai-memory/agent-sdk-apps.mdx | 124 ++++++++ pages/ai-ecosystem/ai-memory/agents.mdx | 3 +- .../ai-ecosystem/ai-memory/configuration.mdx | 26 +- pages/ai-ecosystem/ai-memory/get-started.mdx | 34 ++- .../ai-memory/knowledge-graph.mdx | 11 +- pages/ai-ecosystem/ai-memory/privacy.mdx | 10 +- .../ai-memory/recall-and-memory.mdx | 47 +++- .../ai-memory/context-graph-flow-dark.svg | 8 +- .../ai-memory/context-graph-flow.svg | 8 +- scripts/generate-context-graph-flow.py | 264 ++++++++++++++++++ 12 files changed, 489 insertions(+), 53 deletions(-) create mode 100644 pages/ai-ecosystem/ai-memory/agent-sdk-apps.mdx create mode 100644 scripts/generate-context-graph-flow.py diff --git a/pages/ai-ecosystem/ai-memory.mdx b/pages/ai-ecosystem/ai-memory.mdx index 641d6af42..b0a40c7ae 100644 --- a/pages/ai-ecosystem/ai-memory.mdx +++ b/pages/ai-ecosystem/ai-memory.mdx @@ -50,12 +50,12 @@ graph. Only the optional schema learning sends session text off your machine.
-![Context Graph in three phases: during a session, the memgraph-context-graph hooks in the coding agent 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) +![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)
-![Context Graph in three phases: during a session, the memgraph-context-graph hooks in the coding agent 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) +![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)
@@ -105,6 +105,8 @@ sessions. 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. diff --git a/pages/ai-ecosystem/ai-memory/_meta.ts b/pages/ai-ecosystem/ai-memory/_meta.ts index 9ccdf9cd0..324fdc4c4 100644 --- a/pages/ai-ecosystem/ai-memory/_meta.ts +++ b/pages/ai-ecosystem/ai-memory/_meta.ts @@ -6,5 +6,6 @@ export default { "configuration": "Configuration", "knowledge-graph": "Knowledge graph", "agents": "Agents", + "agent-sdk-apps": "Agent SDK apps", "shared-spaces": "Shared spaces" } diff --git a/pages/ai-ecosystem/ai-memory/agent-sdk-apps.mdx b/pages/ai-ecosystem/ai-memory/agent-sdk-apps.mdx new file mode 100644 index 000000000..e065754a9 --- /dev/null +++ b/pages/ai-ecosystem/ai-memory/agent-sdk-apps.mdx @@ -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: + + + +```bash +pip install "memgraph-context-graph[claude]" "sessions-graph[memgraph-context-graph]" "actions-graph[memgraph-context-graph]" +``` + + +```bash +pip install "memgraph-context-graph[openai]" "sessions-graph[memgraph-context-graph]" "actions-graph[memgraph-context-graph]" +``` + + + +## 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. + + + +```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. + + +```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. + + + +## 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. diff --git a/pages/ai-ecosystem/ai-memory/agents.mdx b/pages/ai-ecosystem/ai-memory/agents.mdx index e3ae8bdb3..cd6506eef 100644 --- a/pages/ai-ecosystem/ai-memory/agents.mdx +++ b/pages/ai-ecosystem/ai-memory/agents.mdx @@ -12,7 +12,8 @@ hooks that record sessions, registers the Model Context Protocol (MCP) server that serves the `recall` and `memory` tools, and can turn off the agent's own memory. This page lists the files setup changes for each agent, and where the agents behave -differently. +differently. For an app you build on an agent SDK, see +[Agent SDK apps](/ai-ecosystem/ai-memory/agent-sdk-apps). ## Supported agents diff --git a/pages/ai-ecosystem/ai-memory/configuration.mdx b/pages/ai-ecosystem/ai-memory/configuration.mdx index 4d8bcf423..0b988e06f 100644 --- a/pages/ai-ecosystem/ai-memory/configuration.mdx +++ b/pages/ai-ecosystem/ai-memory/configuration.mdx @@ -16,6 +16,11 @@ Setup writes the configuration to `~/.config/context-graph/config.toml`, readable only by you. Set the `CONTEXT_GRAPH_CONFIG` environment variable to use another path. +The file lists every key under a comment that says what it does. A key you +haven't set is commented out, with its default, so you can see all settings +in one place. Setup and `config set` rewrite the file: they keep your values +and `[redact]` patterns, but not comments you add. + The hooks read their settings only from this file, not from environment variables, because agents run hooks without your shell's environment. Change settings with the `config` command: @@ -24,9 +29,12 @@ settings with the `config` command: memgraph-context-graph config show memgraph-context-graph config get memgraph.url memgraph-context-graph config set identity.user_id alice +memgraph-context-graph config set recall.turns_k "" ``` -`config set` takes these keys: +An empty value, as in the last command, sets a key back to its default. +`config set` checks each value and refuses one that Context Graph can't use, +so a typo doesn't break recording later. It takes these keys: | Key | Default | What it sets | | --- | --- | --- | @@ -42,19 +50,19 @@ memgraph-context-graph config set identity.user_id alice | `capture.exclude_projects` | None | Directories in which nothing is recorded, by path or glob | | `memory.backend` | Unset | `context-graph` when Context Graph is the agents' [memory](/ai-ecosystem/ai-memory/recall-and-memory#use-context-graph-as-your-agents-memory). Set it with setup's `--memory-backend`, which also changes the agents' settings. | | `session_start.resume` | `true` | Whether a session starts with the [note on where you left off](/ai-ecosystem/ai-memory/recall-and-memory#where-you-left-off) | -| `recall.embedding_model` | `BAAI/bge-small-en-v1.5` | The embedding model for recall | +| `recall.*` | See [Tune recall](/ai-ecosystem/ai-memory/recall-and-memory#tune-recall) | The embedding model for recall, which searches run, and how many results each returns | | `reconcile.auto_reconcile` | `false` | Whether the [knowledge graph](/ai-ecosystem/ai-memory/knowledge-graph) is built after each session | | `ontology.path` | Unset | A schema file for the knowledge graph | | `ontology.derive` | `extend` | Whether Context Graph adds types to your schema: `extend` or `off` | +| `extraction.*` | See [Tune extraction](/ai-ecosystem/ai-memory/knowledge-graph#tune-extraction) | How sessions are read into the knowledge graph | | `llm.anthropic_api_key` | Empty | An Anthropic API key, used only to learn your schema | | `llm.openai_api_key` | Empty | An OpenAI API key, used only to learn your schema | | `llm.derive_model` | `claude-sonnet-5-5` with Anthropic, `gpt-5` with OpenAI | The model that learns your schema | | `edition` | `community` | `enterprise` to use [shared spaces](/ai-ecosystem/ai-memory/shared-spaces). Set it with `memgraph-context-graph join`. | | `github.token` | Unset | A GitHub token for `resources-graph`, used instead of your `gh` login. Prompts for the value. | -Recall's other settings, the `[extraction]` settings and `[redact]` patterns -are edited in the file directly. See [Tune recall](/ai-ecosystem/ai-memory/recall-and-memory#tune-recall) -and [Tune extraction](/ai-ecosystem/ai-memory/knowledge-graph#tune-extraction). +Only `[redact]` patterns are edited in the file directly, because you name +them yourself. See [Redact secrets](/ai-ecosystem/ai-memory/privacy#redact-secrets). The file holds your Memgraph password and API keys in plain text. Setup @@ -87,8 +95,10 @@ memgraph-context-graph config set memgraph.url neo4j://coordinator.example.com:7 ``` The instance must run Memgraph 3.6 or later, with -[MAGE](/advanced-algorithms) for recall by meaning. To see all labels and -properties with `SHOW SCHEMA INFO`, start it with `--schema-info-enabled=true`. +[MAGE](/advanced-algorithms) for +[recall by meaning](/ai-ecosystem/ai-memory/recall-and-memory#recall). To see +all labels and properties with `SHOW SCHEMA INFO`, start it with +`--schema-info-enabled=true`. The Memgraph that setup starts has it enabled. Each user on a shared Memgraph should have their own `identity.user_id`. On a @@ -174,7 +184,7 @@ Updating only the plugin doesn't upgrade the packages its hooks run. Run ## Uninstall Context Graph The `uninstall` command disconnects your agents: it removes the plugins, hook files and MCP -registrations, and turns the agents' own memory back on. +registrations, and [gives the agents' memory back](/ai-ecosystem/ai-memory/recall-and-memory#switch-back). ```bash memgraph-context-graph uninstall diff --git a/pages/ai-ecosystem/ai-memory/get-started.mdx b/pages/ai-ecosystem/ai-memory/get-started.mdx index 62e6b6bac..c263e1a7c 100644 --- a/pages/ai-ecosystem/ai-memory/get-started.mdx +++ b/pages/ai-ecosystem/ai-memory/get-started.mdx @@ -18,11 +18,13 @@ text out of the graph. ## Prerequisites -- **Memgraph 3.6 or later, or Docker.** If setup doesn't find a Memgraph, it - starts one with [Docker](https://docs.docker.com/get-docker/). If you bring - your own Memgraph, use the [MAGE](/advanced-algorithms) image - (`memgraph/memgraph-mage`) with at least 2 GiB of memory for recall by - meaning; without MAGE, recall uses text search only. +- **Docker, or Memgraph 3.6 or later.** By default, setup starts Memgraph with + [Docker](https://docs.docker.com/get-docker/). To use your own Memgraph + instead, pass its URL with `--memgraph-url`, and use the + [MAGE](/advanced-algorithms) image + (`memgraph/memgraph-mage`) with at least 2 GiB of memory, so that + [recall](/ai-ecosystem/ai-memory/recall-and-memory#recall) can search by + meaning. - **At least one [supported agent](/ai-ecosystem/ai-memory/agents#supported-agents)** on your `PATH`. @@ -77,11 +79,14 @@ The plan updates as you change your choices. Nothing changes until you press After you press **Install**, setup runs these steps in order. Each step checks first, so running setup again only does what's missing. -1. **Finds or starts Memgraph.** Setup uses the Memgraph in its configuration - file, then a Memgraph on `localhost:7687`. Otherwise, it starts the - `memgraph/memgraph-mage` image in a container named - `context-graph-memgraph`, with a data volume, listening on `127.0.0.1` - only. If port 7687 is taken, it picks a free port. +1. **Finds or starts Memgraph.** Setup uses the Memgraph you passed with + `--memgraph-url` or set in its configuration file. Otherwise, it uses its + own container, `context-graph-memgraph`, and starts it if it's stopped. If + there's no such container, it starts the `memgraph/memgraph-mage` image + under that name, with a data volume, listening on `127.0.0.1` only. If + port 7687 is taken, it picks a free port. Setup never writes to another + Memgraph that happens to run on `localhost:7687`; to use one, pass + `--memgraph-url bolt://localhost:7687`. 2. **Saves the configuration:** the Memgraph URL and your user ID, in `~/.config/context-graph/config.toml`. 3. **Installs the packages:** the `memgraph-context-graph` command, the @@ -124,8 +129,9 @@ The `runtime:` check sends a test event to the connectors. For Claude Code and Codex, the `plugin:` check confirms the agent will call the hooks: it fails if the agent isn't on your `PATH`, or the plugin isn't installed or is disabled. -A line that starts with `FAIL` says what failed. The `embeddings` check fails -on a Memgraph without MAGE; recall then uses text search only. +A line that starts with `FAIL` says what failed. On a Memgraph without MAGE, +the `embeddings` check is expected to fail; see +[Recall](/ai-ecosystem/ai-memory/recall-and-memory#recall). ## 3. Use your agents @@ -164,10 +170,10 @@ curl -fsSL https://raw.githubusercontent.com/memgraph/ai-toolkit/main/context-gr | --- | --- | | `RUNTIME ...` | The [runtime names](/ai-ecosystem/ai-memory/agents#supported-agents) of the agents to connect. The default is every agent on your `PATH`. | | `--project-dir DIR` | A project to connect the per-project agents in. Repeat it for more projects. The default is the current directory. | -| `--memgraph-url URL` | The Memgraph to use, instead of finding or starting one. | +| `--memgraph-url URL` | The Memgraph to use, instead of setup's own container. | | `--user-id NAME` | Your user ID in the graph. The default is the configured one, then your git `user.name`. | | `--memory-backend context-graph` | Make Context Graph the agents' memory. `native` gives memory back to the agent. | -| `--memgraph-container NAME` | The container to find or start. The default is `context-graph-memgraph`. | +| `--memgraph-container NAME` | Setup's own container, which it finds or starts. The default is `context-graph-memgraph`. | | `--no-viewer` | Don't install the terminal viewer. | | `--plan` | Print what setup would do and change nothing. | | `--no-tui` | Print plain output, even on a terminal. | diff --git a/pages/ai-ecosystem/ai-memory/knowledge-graph.mdx b/pages/ai-ecosystem/ai-memory/knowledge-graph.mdx index a93129c33..69d39e8fa 100644 --- a/pages/ai-ecosystem/ai-memory/knowledge-graph.mdx +++ b/pages/ai-ecosystem/ai-memory/knowledge-graph.mdx @@ -160,8 +160,9 @@ change, and extraction still works. ## Tune extraction -The `[extraction]` section of the configuration file sets how sessions are -read. Edit it in the file; all keys are optional: +The `extraction.*` keys set how sessions are read. All of them are optional, +and `config set` refuses a value that extraction can't use, such as a +threshold above 1: | Key | Default | What it sets | | --- | --- | --- | @@ -173,10 +174,8 @@ read. Edit it in the file; all keys are optional: For example: -```toml -[extraction] -model = "fastino/gliner2.5-base-v1" -entity_threshold = "0.3" +```bash +memgraph-context-graph config set extraction.entity_threshold 0.3 ``` Reconciliation and schema learning use the same settings, so a session is diff --git a/pages/ai-ecosystem/ai-memory/privacy.mdx b/pages/ai-ecosystem/ai-memory/privacy.mdx index 5ecc355f6..5cb2e9915 100644 --- a/pages/ai-ecosystem/ai-memory/privacy.mdx +++ b/pages/ai-ecosystem/ai-memory/privacy.mdx @@ -21,17 +21,11 @@ The hooks use only the keys in the configuration file. A `sessions-graph` command you run from a shell also uses `ANTHROPIC_API_KEY` or `OPENAI_API_KEY` from your environment. -Extraction and embeddings run locally: Context Graph downloads the models, -not your text. The Memgraph that setup starts sends Memgraph's -[telemetry](/fundamentals/telemetry); start your own Memgraph with -`--telemetry-enabled=false` to turn it off. - ## Keep text out of the graph The hooks that setup installs in each agent record prompts, replies, and tool -input and output in full, so a -session can contain an API key from a `.env` file or text you don't want -stored. Before anything reaches Memgraph, Context Graph removes what you mark +input and output in full, so a session can contain an API key from a `.env` +file or text you don't want stored. Before anything reaches Memgraph, Context Graph removes what you mark as private, redacts secrets, and shortens long text. What it removes is never stored. diff --git a/pages/ai-ecosystem/ai-memory/recall-and-memory.mdx b/pages/ai-ecosystem/ai-memory/recall-and-memory.mdx index a954268c7..ce9ac4312 100644 --- a/pages/ai-ecosystem/ai-memory/recall-and-memory.mdx +++ b/pages/ai-ecosystem/ai-memory/recall-and-memory.mdx @@ -84,9 +84,16 @@ memgraph-context-graph config set session_start.resume false ### Tune recall -To change how many -results each search returns, or to drop a search, edit the `[recall]` section -of the [configuration file](/ai-ecosystem/ai-memory/configuration#configuration-file): +To change how many results each search returns, or to drop a search, set a +`recall.*` key with +[`config set`](/ai-ecosystem/ai-memory/configuration#configuration-file): + +```bash +memgraph-context-graph config set recall.turns_k 12 +memgraph-context-graph config set recall.lanes "memories, turns, text" +``` + +The keys are: | Key | Default | What it sets | | --- | --- | --- | @@ -180,9 +187,37 @@ To give memory back to the agent: memgraph-context-graph setup claude-code --memory-backend native ``` -The agent's own memory is turned on again. The memories in the graph stay -where they are, and recall still finds them. `memgraph-context-graph uninstall` -also turns the agent's own memory back on. +For Claude Code, setup first copies the graph's memories back into Claude +Code's auto memory, so it continues from what the graph learned: + +- A project's files go to each Claude Code project folder for that project, + and `/memories/user/` and `/memories/feedback/` files go to every folder. +- The graph's copy replaces an older copy there, and each folder's + `MEMORY.md` index is rebuilt. +- Files that Claude Code has no folder for, such as a project it never opened + or another agent's files, stay in the graph only. Setup lists them. + +Then it turns the agent's own memory on again. The memories in the graph stay +where they are, and recall still finds them. If Memgraph isn't reachable, +setup changes nothing. + +Codex, GitHub Copilot CLI and Grok Build get nothing copied back, because +their memory is generated or hosted by the agent itself. + +`memgraph-context-graph uninstall` also gives memory back the same way. If +Memgraph isn't reachable, it turns the agent's memory back on with what it +held before the switch, and warns you. + +### Check for a second memory + +A project's `.claude/settings.json` or `.claude/settings.local.json` overrides +your user settings. If one of them sets `autoMemoryEnabled: true`, Claude Code +keeps its own memory in that project next to Context Graph's. +`memgraph-context-graph doctor` fails in that case. Run it from the project: + +```bash +memgraph-context-graph doctor --runtime claude-code +``` ## Remember GitHub resources diff --git a/public/pages/ai-ecosystem/ai-memory/context-graph-flow-dark.svg b/public/pages/ai-ecosystem/ai-memory/context-graph-flow-dark.svg index b464c4e82..3781437d4 100644 --- a/public/pages/ai-ecosystem/ai-memory/context-graph-flow-dark.svg +++ b/public/pages/ai-ecosystem/ai-memory/context-graph-flow-dark.svg @@ -1,6 +1,6 @@ How Context Graph records and recalls agent sessions - During a session, the memgraph-context-graph hooks in the coding agent drop private text and redact secrets, and the actions-graph, skills-graph and sessions-graph connectors write the session to Memgraph as a graph of users, sessions, actions, skills and memories. The optional resources-graph connector records GitHub resources, and context-graph-spaces adds shared spaces on Memgraph Enterprise. The MCP server reads Memgraph and serves the recall and memory tools to the agent. After a session, reconciliation filters the text through the HyGM ontology, extracts entities and facts with GLiNER2 and stores them in Memgraph with their embeddings. Only optional schema learning sends session text to an Anthropic or OpenAI API. + 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 as a graph of users, sessions, actions, skills and memories. The optional resources-graph connector records GitHub resources, and context-graph-spaces adds shared spaces on Memgraph Enterprise. The MCP server reads Memgraph and serves the recall and memory tools to the agent. After a session, reconciliation filters the text through the HyGM ontology, extracts entities and facts with GLiNER2 and stores them in Memgraph with their embeddings. Only optional schema learning sends session text to an Anthropic or OpenAI API. ```python diff --git a/pages/ai-ecosystem/ai-memory/configuration.mdx b/pages/ai-ecosystem/ai-memory/configuration.mdx index 0b988e06f..b983ac87e 100644 --- a/pages/ai-ecosystem/ai-memory/configuration.mdx +++ b/pages/ai-ecosystem/ai-memory/configuration.mdx @@ -32,7 +32,8 @@ memgraph-context-graph config set identity.user_id alice memgraph-context-graph config set recall.turns_k "" ``` -An empty value, as in the last command, sets a key back to its default. +An empty value, as in the last command, sets a key back to its default. The +exception is `capture.connectors`, where an empty value records nothing. `config set` checks each value and refuses one that Context Graph can't use, so a typo doesn't break recording later. It takes these keys: diff --git a/pages/ai-ecosystem/ai-memory/explore-the-graph.mdx b/pages/ai-ecosystem/ai-memory/explore-the-graph.mdx index 2236947fd..faeb2ef0f 100644 --- a/pages/ai-ecosystem/ai-memory/explore-the-graph.mdx +++ b/pages/ai-ecosystem/ai-memory/explore-the-graph.mdx @@ -94,8 +94,8 @@ Your ten most recent sessions, with the number of actions in each: ```cypher template MATCH (:User {user_id: "USER_ID"})-[:HAD_SESSION]->(s:Session) OPTIONAL MATCH (s)-[:HAS_ACTION]->(a:Action) -RETURN s.session_id, s.project_key, s.started_at, count(a) AS actions -ORDER BY s.started_at DESC +RETURN s.session_id, s.project_key, s.started_at AS started_at, count(a) AS actions +ORDER BY started_at DESC LIMIT 10; ``` @@ -127,8 +127,8 @@ The entities your sessions mention most, after you ```cypher template MATCH (:User {user_id: "USER_ID"})-[:HAD_SESSION]->(:Session)-[:HAS_ACTION]->(:Action) - -[:HAS_CHUNK]->(:Chunk)<-[:MENTIONED_IN]-(e) -RETURN e.text, e.entity_type, count(*) AS mentions + -[:HAS_CHUNK]->(c:Chunk)<-[:MENTIONED_IN]-(e) +RETURN e.text, e.entity_type, count(DISTINCT c) AS mentions ORDER BY mentions DESC LIMIT 20; ``` diff --git a/pages/ai-ecosystem/ai-memory/get-started.mdx b/pages/ai-ecosystem/ai-memory/get-started.mdx index c263e1a7c..cf618bba4 100644 --- a/pages/ai-ecosystem/ai-memory/get-started.mdx +++ b/pages/ai-ecosystem/ai-memory/get-started.mdx @@ -101,7 +101,10 @@ The report ends with the command to rerun for any step that failed. ## 2. Check the setup Restart any agent sessions that were running during setup, because a running -session keeps the hooks it started with. Then check the setup: +session keeps the hooks it started with. Codex and Grok Build record nothing +until you trust the new hooks: in Codex, run `/hooks` once and accept them; in +Grok Build, run `/hooks-trust` once in each connected project. Then check the +setup: ```bash memgraph-context-graph doctor --runtime claude-code @@ -109,7 +112,7 @@ memgraph-context-graph doctor --runtime claude-code Replace `claude-code` with the [runtime name](/ai-ecosystem/ai-memory/agents#supported-agents) of the agent -you want to check. Every line starts with `OK` when the setup works: +you want to check. Every check starts with `OK` when the setup works: ```plaintext copy=false OK memgraph-context-graph executable: ... @@ -122,9 +125,13 @@ OK connector:sessions-graph: installed=...; memgraph=reachable OK embeddings: BAAI/bge-small-en-v1.5 (384 dimensions) inside Memgraph OK mcp: serves recall OK runtime:claude-code: connectors accept its probe event +OK memory: claude-code's built-in memory (memory.backend native) OK plugin:claude-code: context-graph@context-graph-plugins installed and enabled +INFO capture-failures: none in the last 24h (...) ``` +The last line counts the recordings that failed in the last day. + The `runtime:` check sends a test event to the connectors. For Claude Code and Codex, the `plugin:` check confirms the agent will call the hooks: it fails if the agent isn't on your `PATH`, or the plugin isn't installed or is disabled. diff --git a/pages/ai-ecosystem/ai-memory/knowledge-graph.mdx b/pages/ai-ecosystem/ai-memory/knowledge-graph.mdx index 69d39e8fa..31094d6dd 100644 --- a/pages/ai-ecosystem/ai-memory/knowledge-graph.mdx +++ b/pages/ai-ecosystem/ai-memory/knowledge-graph.mdx @@ -29,7 +29,10 @@ uv tool install --force 'memgraph-context-graph[mcp]' \ --with-executables-from sessions-graph ``` -The first extraction downloads the model. +This command replaces the packages installed with the tool. If you turned on +`resources-graph`, add `--with 'resources-graph[memgraph-context-graph]'` and +`--with-executables-from resources-graph`. The first extraction downloads the +model. ## Build the knowledge graph @@ -88,8 +91,10 @@ Each entity gets a label for its type from your schema, such as `Person` or property `ontology_conformant` set to `false`. Facts are relationships between entities, typed by the schema, with the sentence they were read from. -An entity mentioned in several sessions is one node, so its relationships -connect the sessions that mention it. Content seen before isn't extracted +A person, organization, place or thing mentioned in several sessions is one +node, so its relationships connect the sessions that mention it. Dates, +amounts, events and topics are kept per passage, because the same words can +mean different things in two sessions. Content seen before isn't extracted again. Reconciliation also computes the embeddings recall uses for the new entities diff --git a/pages/ai-ecosystem/ai-memory/recall-and-memory.mdx b/pages/ai-ecosystem/ai-memory/recall-and-memory.mdx index ce9ac4312..e1e2f52f1 100644 --- a/pages/ai-ecosystem/ai-memory/recall-and-memory.mdx +++ b/pages/ai-ecosystem/ai-memory/recall-and-memory.mdx @@ -194,8 +194,9 @@ Code's auto memory, so it continues from what the graph learned: and `/memories/user/` and `/memories/feedback/` files go to every folder. - The graph's copy replaces an older copy there, and each folder's `MEMORY.md` index is rebuilt. -- Files that Claude Code has no folder for, such as a project it never opened - or another agent's files, stay in the graph only. Setup lists them. +- Files that Claude Code has no folder for stay in the graph only, such as a + project it never opened, another agent's files, or files directly in + `/memories/`. Setup lists them. Then it turns the agent's own memory on again. The memories in the graph stay where they are, and recall still finds them. If Memgraph isn't reachable, From 43c266f6bbcde935d9ff6fc76e976fabff56cc8e Mon Sep 17 00:00:00 2001 From: antejavor Date: Thu, 22 Oct 2026 21:01:43 +0200 Subject: [PATCH 11/11] update: AI memory overview is about Context Graph and how it works; ontology learning in the diagram; runnable SDK examples, credentials before setup, review fixes --- pages/ai-ecosystem.mdx | 10 +- pages/ai-ecosystem/ai-memory.mdx | 190 ++++++++---------- .../ai-ecosystem/ai-memory/agent-sdk-apps.mdx | 72 ++++--- .../ai-ecosystem/ai-memory/configuration.mdx | 10 +- .../ai-memory/explore-the-graph.mdx | 14 ++ pages/ai-ecosystem/ai-memory/get-started.mdx | 7 +- .../ai-memory/recall-and-memory.mdx | 4 +- .../ai-memory/context-graph-flow-dark.svg | 4 +- .../ai-memory/context-graph-flow.svg | 4 +- scripts/generate-context-graph-flow.py | 6 +- 10 files changed, 165 insertions(+), 156 deletions(-) diff --git a/pages/ai-ecosystem.mdx b/pages/ai-ecosystem.mdx index 4cd25834b..ab86f7dfa 100644 --- a/pages/ai-ecosystem.mdx +++ b/pages/ai-ecosystem.mdx @@ -36,9 +36,9 @@ This section covers: ranking and prompt assembly as one Cypher query, and [Agentic GraphRAG](/ai-ecosystem/graph-rag/agentic-graphrag) lets an agent choose the retrieval pipeline for each question. -- [AI memory](/ai-ecosystem/ai-memory): Store semantic, episodic and procedural - memory (what a system knows, what it did and what it knows how to do) as - one graph that any AI system can query across sessions. +- [AI memory](/ai-ecosystem/ai-memory): Give coding agents a long-term memory + with Context Graph, which records their sessions in Memgraph and serves them + back to every connected agent in later sessions. - [Agentic AI](/ai-ecosystem/agentic-ai): Store an agent's states and actions as a reasoning graph, so the agent plans by traversing scored paths instead of by prompting, and every decision leaves a trace you can inspect. @@ -78,8 +78,8 @@ 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. + your coding agents' sessions in Memgraph and serves them back as memory. It + asks before it changes anything. You need Docker. diff --git a/pages/ai-ecosystem/ai-memory.mdx b/pages/ai-ecosystem/ai-memory.mdx index b0a40c7ae..b168ecccc 100644 --- a/pages/ai-ecosystem/ai-memory.mdx +++ b/pages/ai-ecosystem/ai-memory.mdx @@ -1,35 +1,22 @@ --- title: AI memory -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. +description: Give coding agents and Agent SDK apps a long-term memory in Memgraph with Context Graph, which records their sessions and serves them back in later sessions. --- -# AI memory - -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. - -A query can follow those links, and combine them with -[vector search](/querying/vector-search) and -[text search](/querying/text-search). +import { Tabs } from 'nextra/components' -There are two ways to add this memory to an AI system: - -- [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. +# AI memory -## Use Context Graph +AI memory lets an AI agent use what happened in earlier sessions: what you +decided, what it did and what it learned about your work. Context Graph is +Memgraph's AI memory. It records the sessions of your coding agents, such as +Claude Code and Codex, as a graph in Memgraph, and serves them back to every +connected agent in later sessions. -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 works with seven +[coding agents](/ai-ecosystem/ai-memory/agents#supported-agents), with no code +to write. Apps built on the Claude Agent SDK or the OpenAI Agents SDK can use +the same memory; see [Agent SDK apps](/ai-ecosystem/ai-memory/agent-sdk-apps). Every connected agent gets: @@ -42,54 +29,90 @@ Every connected agent gets: memory, so the notes the agent saves are stored in the graph and shared by all your agents. -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. +Context Graph is open source, part of the +[Memgraph AI Toolkit](https://github.com/memgraph/ai-toolkit/tree/main/context-graph). -
+## Get started -![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) +One command installs Context Graph, finds or starts Memgraph and connects the +agents you choose. It shows its plan and changes nothing until you confirm. -
-
- -![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) + + +```bash +curl -sSL https://install.memgraph.com/ai-memory | bash +``` + + +```powershell +iwr https://install.memgraph.com/ai-memory/windows -useb | iex +``` + + -
+See [Get started](/ai-ecosystem/ai-memory/get-started) for the prerequisites, +the choices setup offers and how to check that sessions are recorded. -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. +## How it works -To install it, see [Get started](/ai-ecosystem/ai-memory/get-started). +Context Graph works in three phases, shown in the diagram: during a session, +it records each event and serves recall from Memgraph; after the session, +reconciliation builds a knowledge graph from what was recorded. -### 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: +![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 ontology learning sends session text to an Anthropic or OpenAI API](/pages/ai-ecosystem/ai-memory/context-graph-flow.svg) -```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) -``` +
+
-`Memory` nodes hold what the agent knows, `Action` nodes what it did, and -`Skill` nodes what it knows how to do. +![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 ontology learning sends session text to an Anthropic or OpenAI API](/pages/ai-ecosystem/ai-memory/context-graph-flow-dark.svg) -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 +### During a session + +- **Hooks.** The `memgraph-context-graph` hooks run in the agent, whether a + coding agent or an Agent SDK app, on each event: a prompt, a reply, a tool + call or its result. They drop text marked as private and redact secrets + before anything is stored. +- **Connectors.** The hooks pass each event to the connectors, which write it + to Memgraph. `actions-graph` records prompts, replies, tool calls and their + results, `skills-graph` the agent skills a session used, and `sessions-graph` + the session, its user and project, and the memories the agent saved. The + optional `resources-graph` records the GitHub resources a session read. On + Memgraph Enterprise, `context-graph-spaces` adds + [shared spaces](/ai-ecosystem/ai-memory/shared-spaces) for a team. +- **Memgraph.** Users, sessions, actions, skills and memories form one graph, + and the knowledge graph links to them. See + [Explore the graph](/ai-ecosystem/ai-memory/explore-the-graph). +- **MCP server.** The MCP server reads Memgraph and serves the `recall` and + `memory` tools to the agent. See + [Recall and memory](/ai-ecosystem/ai-memory/recall-and-memory). + +### After a session + +When a session ends, [reconciliation](/ai-ecosystem/ai-memory/knowledge-graph) +extracts the people, organizations, projects and other entities it mentions, +and the facts that connect them, into a knowledge graph. It runs on your +machine: + +1. **Ontology.** The ontology is the schema of the knowledge graph: the entity + types and fact types to look for, such as a person who works for an + organization. It's a model in HyGM, the AI Toolkit's graph schema package. + Every user starts with a default ontology, and you can write your own. +2. **Extract.** GLiNER2, a local extraction model, finds the entities and + facts of those types in the session's text. It needs no LLM API key. +3. **Store.** The entities and facts are stored in Memgraph with their + embeddings, linked to the messages they came from. Recall uses them to find + facts spread over many sessions. + +**Ontology learning** is optional. With an Anthropic or OpenAI API key in the +configuration, Context Graph learns new entity and fact types from your +sessions. It's the only part of Context Graph that sends session text off +your machine. + +## Guides - [Get started](/ai-ecosystem/ai-memory/get-started): Install Context Graph, connect your agents and check that sessions are recorded. @@ -109,48 +132,3 @@ sessions. 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"})-[: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 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 whose memory you read. To see all the labels, -relationship types and properties in the graph, run: - -```cypher -SHOW SCHEMA INFO; -``` - -This needs Memgraph started with `--schema-info-enabled=true`. - -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. - -### Use Context Graph's packages - -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. diff --git a/pages/ai-ecosystem/ai-memory/agent-sdk-apps.mdx b/pages/ai-ecosystem/ai-memory/agent-sdk-apps.mdx index fcb2fe6a9..feb10591a 100644 --- a/pages/ai-ecosystem/ai-memory/agent-sdk-apps.mdx +++ b/pages/ai-ecosystem/ai-memory/agent-sdk-apps.mdx @@ -30,14 +30,8 @@ The app reads the Memgraph connection, what is recorded and the 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: +Install the package with the extra for your SDK, and the packages that record +actions and sessions: @@ -67,18 +61,32 @@ 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. +The app gets the `memory` tool whatever `memory.backend` your coding agents +use, because an app has no memory of its own to replace. To leave it out, pass +`memory_tool=False`. + +Both SDKs are async. Each example below is a whole script. + ```python +import asyncio + from claude_agent_sdk import ClaudeSDKClient +from memgraph_context_graph.sdk import ContextGraphMemory 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() + +async def main(): + claude = ClaudeAgentMemory(ContextGraphMemory(user_id="alice")) + 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) + await claude.aend_session() + + +asyncio.run(main()) ``` `options()` takes the same arguments as `ClaudeAgentOptions`. It adds the @@ -92,17 +100,26 @@ so its hooks don't record every event a second time. ```python +import asyncio + from agents import Agent, Runner +from memgraph_context_graph.sdk import ContextGraphMemory 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() + +async def main(): + wired = OpenAIAgentsMemory(ContextGraphMemory(user_id="alice"), 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()) + print(result.final_output) + await wired.aend_session() + + +asyncio.run(main()) ``` Use one `session_id` per conversation. `instructions()` adds the memory @@ -114,9 +131,14 @@ replies, tool calls and handoffs. ## 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. +Neither SDK reports when a session ends, so call `aend_session()`, or +`end_session()` from code that isn't async, when a conversation is over. + +Recall can find each message as soon as its turn ends, because Context Graph +embeds a session's messages at the end of every turn. Ending the session +embeds anything left and marks the session for +[reconciliation](/ai-ecosystem/ai-memory/knowledge-graph#build-the-knowledge-graph), +which starts at once if `reconcile.auto_reconcile` is on. ## When Memgraph is down diff --git a/pages/ai-ecosystem/ai-memory/configuration.mdx b/pages/ai-ecosystem/ai-memory/configuration.mdx index b983ac87e..bcc19d189 100644 --- a/pages/ai-ecosystem/ai-memory/configuration.mdx +++ b/pages/ai-ecosystem/ai-memory/configuration.mdx @@ -75,17 +75,13 @@ creates it with permissions `0600`; keep it that way. By default, setup starts Memgraph in Docker on your machine. To use another Memgraph, such as a shared server or a [high availability cluster](/database-management/clustering/high-availability), -pass its URL to setup: - -```bash -memgraph-context-graph setup --memgraph-url bolt://memgraph.example.com:7687 -``` - -If the instance has authentication, set the user and password: +pass its URL to setup. If the instance has authentication, set the user and +password first, because setup connects with them: ```bash memgraph-context-graph config set memgraph.user alice memgraph-context-graph config set memgraph.password +memgraph-context-graph setup --memgraph-url bolt://memgraph.example.com:7687 ``` For a high availability cluster, use the `neo4j://` scheme with a coordinator's diff --git a/pages/ai-ecosystem/ai-memory/explore-the-graph.mdx b/pages/ai-ecosystem/ai-memory/explore-the-graph.mdx index faeb2ef0f..ecdf41ef8 100644 --- a/pages/ai-ecosystem/ai-memory/explore-the-graph.mdx +++ b/pages/ai-ecosystem/ai-memory/explore-the-graph.mdx @@ -64,6 +64,20 @@ on your machine isn't at `localhost` inside the Lab container: ## Query 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) +``` + +The [knowledge graph](/ai-ecosystem/ai-memory/knowledge-graph#what-reconciliation-writes) +links to the actions and memory files its entities came from. + The graph uses these labels and relationship types: | Node | What it is | diff --git a/pages/ai-ecosystem/ai-memory/get-started.mdx b/pages/ai-ecosystem/ai-memory/get-started.mdx index cf618bba4..7800e4f50 100644 --- a/pages/ai-ecosystem/ai-memory/get-started.mdx +++ b/pages/ai-ecosystem/ai-memory/get-started.mdx @@ -12,9 +12,7 @@ the coding agents you choose. Setup shows its plan and changes nothing until you confirm. From then on, Context Graph records your prompts, the agent's replies, and -every tool call with its input and output, in full. Known kinds of secrets are -redacted first. Read [Privacy](/ai-ecosystem/ai-memory/privacy) to keep other -text out of the graph. +every tool call with its input and output. ## Prerequisites @@ -80,7 +78,8 @@ After you press **Install**, setup runs these steps in order. Each step checks first, so running setup again only does what's missing. 1. **Finds or starts Memgraph.** Setup uses the Memgraph you passed with - `--memgraph-url` or set in its configuration file. Otherwise, it uses its + `--memgraph-url`, or the one set in its configuration file unless that is + the default `bolt://localhost:7687`. Otherwise, it uses its own container, `context-graph-memgraph`, and starts it if it's stopped. If there's no such container, it starts the `memgraph/memgraph-mage` image under that name, with a data volume, listening on `127.0.0.1` only. If diff --git a/pages/ai-ecosystem/ai-memory/recall-and-memory.mdx b/pages/ai-ecosystem/ai-memory/recall-and-memory.mdx index e1e2f52f1..02c1782f9 100644 --- a/pages/ai-ecosystem/ai-memory/recall-and-memory.mdx +++ b/pages/ai-ecosystem/ai-memory/recall-and-memory.mdx @@ -46,8 +46,8 @@ Before it's built, recall finds messages and memories only. The searches by meaning need [MAGE](/advanced-algorithms): Memgraph computes the embeddings itself with the [`embeddings` module](/advanced-algorithms/available-algorithms/embeddings), -so no model runs on your machine. On Memgraph without MAGE, recall uses text -search only and says so in its results. +so neither the agent nor the hooks run an embedding model. On Memgraph without +MAGE, recall uses text search only and says so in its results. ### Ask from the terminal diff --git a/public/pages/ai-ecosystem/ai-memory/context-graph-flow-dark.svg b/public/pages/ai-ecosystem/ai-memory/context-graph-flow-dark.svg index 3781437d4..376d27eb2 100644 --- a/public/pages/ai-ecosystem/ai-memory/context-graph-flow-dark.svg +++ b/public/pages/ai-ecosystem/ai-memory/context-graph-flow-dark.svg @@ -1,6 +1,6 @@ How Context Graph records and recalls agent sessions - 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 as a graph of users, sessions, actions, skills and memories. The optional resources-graph connector records GitHub resources, and context-graph-spaces adds shared spaces on Memgraph Enterprise. The MCP server reads Memgraph and serves the recall and memory tools to the agent. After a session, reconciliation filters the text through the HyGM ontology, extracts entities and facts with GLiNER2 and stores them in Memgraph with their embeddings. Only optional schema learning sends session text to an Anthropic or OpenAI API. + 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 as a graph of users, sessions, actions, skills and memories. The optional resources-graph connector records GitHub resources, and context-graph-spaces adds shared spaces on Memgraph Enterprise. The MCP server reads Memgraph and serves the recall and memory tools to the agent. After a session, reconciliation filters the text through the HyGM ontology, extracts entities and facts with GLiNER2 and stores them in Memgraph with their embeddings. Only optional ontology learning sends session text to an Anthropic or OpenAI API.