AI Memory with Memgraph

Vector Memory Forgets. Graphs Don’t.

LLMs are stateless, so they need an external memory. Vector memory retrieves what sounds similar, not what is structurally relevant given the full history. On Memgraph (memgraph.com/ai-memory) memory is a graph of entities and typed relationships you traverse, so recall follows the actual connections between what the system knows, did, and knows how to do.

Memgraph models three kinds of long-term memory as one unified graph:

This example writes and reads all three through the actual Context Graph packages a live coding-assistant plugin uses (sessions-graph, actions-graph, skills-graph) instead of a hand-rolled schema. The (:User)/(:Session) nodes those three packages share are the join key, so the payoff is a genuine graph traversal, not three separate lookups glued together.

High-level Plan

1. Spin up the memory store (Memgraph).
2. Write the three memory types for a client the assistant has worked with, through sessions-graph/actions-graph/skills-graph.
3. Recall each type, then all three together to answer “Schedule a follow-up with the client like last time.”

What You Need

Two things to install once, yourself. The script checks for both before it touches anything and prints exactly how to get whichever is missing:

• Docker: https://docs.docker.com/get-docker/. On Windows, winget install --id Docker.DockerDesktop; Docker Desktop must be running.
• Python 3.10-3.13: https://www.python.org/downloads/. On Windows, winget install --id Python.Python.3.12 (tick Add python.exe to PATH).

Everything below that the script installs on its own: the Memgraph image, and the three Context Graph packages from PyPI into a throwaway virtualenv (.ai-memory-venv/) next to the script. No repository checkout needed.

No API keys: this example writes structured memory directly, the same way an application would call these packages. Automatic, LLM-backed extraction from raw conversation text is a separate, opt-in step; see Where to Go Next.

Run It

The scripts live in the memgraph/memgraph-platform repository.

macOS / Linux:

./ai-memory.sh          # bring everything up, seed memory, run recall
./ai-memory.sh clean    # stop and remove everything the script created

Windows (PowerShell 5.1 or 7+), same steps, same output:

.\ai-memory.ps1          # bring everything up, seed memory, run recall
.\ai-memory.ps1 clean    # stop and remove everything the script created

Or run it straight from the web, without downloading anything first:

curl -sSL https://install.memgraph.com/ai-memory | bash

iwr https://install.memgraph.com/ai-memory/windows -useb | iex

This does the same as the bare forms above: the script works in your current directory and fetches ai-memory.py into the virtualenv, so clean removes it along with everything else. clean itself needs the downloaded script file.

If Windows blocks the script, allow local scripts for the session first: Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass.

Step-by-step

1. Spin up Memgraph

Memgraph starts with schema info enabled, so the ontology is queryable once the Context Graph packages have written into it:

docker network create aimemory-net
 
docker run -d --name aimemory-memgraph --network aimemory-net \
  -p 7687:7687 -p 7444:7444 \
  memgraph/memgraph-mage:3.12.0 --schema-info-enabled=True

2. Install the Context Graph memory packages

python3 -m venv .ai-memory-venv
.ai-memory-venv/bin/pip install sessions-graph actions-graph skills-graph memgraph-toolbox

On Windows the interpreter lives in .ai-memory-venv\Scripts\ instead of .ai-memory-venv/bin/, so read .ai-memory-venv\Scripts\python.exe -m pip … for this and the next step.

3. Write the three memory types

The assistant has met a client before and knows how to schedule follow-ups. That knowledge is split across three packages, glued together by a shared (:User {user_id}) and two (:Session {session_id}) nodes (session-acme-kickoff, session-acme-followup); see ai-memory.py:

# Episodic: two real sessions, each with a ToolCall/ToolResult (actions-graph)
actions.create_session(Session(session_id="session-acme-kickoff", ...))
actions.create_session(Session(session_id="session-acme-followup", ...))
actions.record_tool_call(session_id=..., tool_name="schedule_meeting", tool_input={...})
actions.record_tool_result(session_id=..., tool_use_id=..., tool_name="schedule_meeting", ...)
 
# Semantic: a durable fact about the client (sessions-graph)
memories.save_memory(
    user_id="acme-corp",
    content="Acme Corp's contact is Dana Lee (timezone America/New_York); they prefer 30-minute meetings.",
    session_id="session-acme-kickoff",
)
 
# Procedural: a reusable skill, used during the follow-up session (skills-graph)
skills.add_skill(Skill(name="schedule-follow-up", description="...", content="1. Book a calendar slot...\n2. Send a calendar invite."))
skills.record_skill_usage(session_id="session-acme-followup", skill_name="schedule-follow-up", action="used", timestamp=...)

Run it:

MEMGRAPH_URL=bolt://localhost:7687 .ai-memory-venv/bin/python ai-memory.py

4. Recall

Each memory type is a small, package-provided lookup:

memories.get_memories("acme-corp")               # semantic
actions.list_sessions(limit=1)                    # episodic: most recent session
actions.get_session_actions(session.session_id)   # ... and what happened in it
skills.get_skill("schedule-follow-up")            # procedural

The payoff is the interconnected recall: one Cypher traversal through the shared User/Session nodes joins all three to answer “schedule a follow-up with the client like last time”:

MATCH (u:User {user_id: "acme-corp"})-[: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
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

It returns Dana Lee’s Acme Corp facts, the session-acme-followup session, the schedule-follow-up skill and its steps, everything needed for the assistant to reply “Done. 30 min Tuesday slot booked, invite sent.”

5. Inspect the memory ontology

SHOW SCHEMA INFO returns the whole ontology (labels, relationship types, properties) in constant time, so an agent can learn the shape of memory before querying it. This is now the real User/Session/Memory/Action/Skill schema the Context Graph packages created, not a demo-only schema:

SHOW SCHEMA INFO;

6. Explore visually (optional)

docker run -d --name aimemory-lab --network aimemory-net -p 3000:3000 \
  -e QUICK_CONNECT_MG_HOST=aimemory-memgraph -e QUICK_CONNECT_MG_PORT=7687 \
  memgraph/lab:3.12.0
# open http://localhost:3000  ->  MATCH p=()-[]-() RETURN p;

Wire It Into a Real Harness

The seeding above did by hand what a real coding-assistant plugin does automatically. One script installs and wires the Context Graph plugin end to end for Claude Code or Codex, defaulting to this same Memgraph instance (bolt://localhost:7687, no auth, database memgraph):

curl -fsSL https://raw.githubusercontent.com/memgraph/ai-toolkit/main/context-graph/scripts/install.sh | bash
# Codex instead of Claude Code:
CONTEXT_GRAPH_RUNTIME=codex bash -c "$(curl -fsSL https://raw.githubusercontent.com/memgraph/ai-toolkit/main/context-graph/scripts/install.sh)"

It registers the runtime’s plugin marketplace and installs the plugin (the step a bare agent-context-graph bootstrap can’t do, since that’s what actually wires hooks into the runtime), installs the CLI with all three connectors, sets your identity, and verifies with doctor. It even starts Memgraph itself if nothing’s reachable, so on a clean machine it doubles as an alternative to steps 1–2 above. Override identity with AGENT_CONTEXT_GRAPH_USER_ID (defaults to git config user.name); see the Context Graph guide for the rest of the configurable env vars and defaults, reconciliation, and cross-component queries.

Every real session then writes Memory/Action/Skill nodes automatically, the same nodes ai-memory.py just wrote by hand, and the next session reads that memory back before it starts.

Clean Up

./ai-memory.sh clean          # .\ai-memory.ps1 clean  on Windows

That removes the container, the Lab container if you started one, the network, and the virtualenv.

If you ran the installer above, mind the order: the plugin keeps writing to whatever answers on bolt://localhost:7687, which is this demo’s container. Removing it leaves the hooks with nowhere to write. Either hold off until you’re done with the plugin, or re-run install.sh afterwards: with nothing reachable it starts a Memgraph of its own on the same port.