Graph Memory

A personal knowledge graph for Claude that survives across sessions, devices, and tools. Built on Neo4j with semantic embeddings, OAuth-secured for use from Claude Code, Claude Desktop, and claude.ai web — all hitting the same graph.

https://github.com/user-attachments/assets/826e5f5a-5759-4b31-83dd-6bd7e0e044b8

Asked from my phone. Pulls a decision made days ago on my laptop, citing the commit hash.

No external API keys, no LLM provider integration, no per-token costs. Entity extraction runs inside your Claude sessions (Max plan). Embedding runs locally via bge-small-en. Everything stays on your hardware unless you choose to expose it.

Why a graph

Built-in memory in Claude Code is "append facts to markdown, grep later." That gets you 80% there but breaks at scale: no relationships, no confidence, no decay, no contradiction detection, no temporal awareness. Two memories that reinforce each other look identical to two memories that contradict each other.

This project replaces flat keyword matching with weighted, relationship-aware retrieval:

• Weighted edges with configurable decay — frequently-confirmed knowledge stays strong; stale information fades naturally on per-type half-lives (preferences ~693 days, events ~99 days)
• Bi-temporal validity — separate valid_at (when fact was true), invalid_at (when superseded), ingested_at (when learned). Old facts get marked invalid rather than deleted
• Semantic + structural search — vector embeddings find conceptually similar entities; graph traversal then expands through real relationships
• Project-context affinity — when you're working in a specific project, related entities surface first
• Contradiction detection — conflicting facts are flagged, not silently coexisting
• Full provenance — every edge traces back to the conversation, transcript, or document that sourced it
• Dream process — a scheduled Claude session reviews recent transcripts and ingest documents overnight, extracts new knowledge, applies decay, and writes a changelog

Architecture

                  Claude Code      Claude Desktop      claude.ai web
                       │                  │                  │
                       └────────── OAuth 2.1 Bearer ─────────┘
                                          │
                              https://your-host.example/mcp
                                          │
                                Cloudflare Tunnel
                                          │
                                  docker-compose
                            ┌────────────┴────────────┐
                            ▼                         ▼
                    graph-memory-mcp           graph-memory-neo4j
                    (Node 22 + jose)           (Neo4j 5.20 + APOC)
                    port 3847                  bolt://neo4j:7687
                            │                         │
                            └─── bolt-internal ───────┘

Two Docker services, talking over the compose network. The MCP server is the only thing that touches Neo4j directly — it implements OAuth 2.1 itself (RS256 JWTs, public clients with PKCE-S256, RFC 7591 dynamic client registration, RFC 7009 revocation), validates bearer tokens for /mcp calls, and exposes Cloudflare Access only on /oauth/authorize for the actual user login. The Neo4j instance has no external listeners.

The dream process is just another Claude session that runs on a schedule, reads transcripts, and calls the same MCP tools any client would call — there's no separate extraction pipeline.

Schema

Entity types (canonical): Person, Project, Preference, Concept, Decision, Fact, Event, Object, Reasoning — plus a few ad-hoc types (Organization, Technology, Artifact, Infrastructure, Feature, Resource) that have emerged organically through use. The schema is permissive on labels.

Relationship types (canonical, 22): WORKS_ON, WORKS_AT, REPORTS_TO, STAKEHOLDER_IN, PREFERS, KNOWS_ABOUT, DEPENDS_ON, USES_TECH, USES, DECIDED_FOR, SUPERSEDES, CONTRADICTS, RELATED_TO, ALIAS_OF, PARTICIPATED_IN, OCCURRED_DURING, PRODUCED, TRIGGERED_BY, HOSTED_ON, PRODUCED_BY, LED_TO, INVOLVED_IN. The catch-all RELATED_TO carries a relationship_type subtype property (similar_to, part_of, enables, impacts, etc.) for cases where the typed relationships don't fit.

Every node and edge carries:

• weight (0.0–1.0) — decays over time on per-type half-lives
• confidence — separate from weight, tracks the source's certainty
• tenant_id — multi-tenant isolation (single-user by default; multi-user-ready via OAuth email claim)
• embedding (nodes) — 384-dim vector for semantic search
• valid_at / invalid_at / ingested_at (edges) — bi-temporal tracking

Concise vocabulary in GRAPH_SCHEMA.md. Full reference (weights, decay, validity windows, init Cypher) in docs/GRAPH_SCHEMA_REFERENCE.md.

Tools

The MCP server exposes 23 tools across these categories:

Slash-command wrappers (/graph, /graph-ask, /graph-search, /graph-stats, /graph-dream, /graph-briefing, /graph-find, /graph-backup, /graph-capture, /ingest, etc.) install into ~/.claude/skills/. Full reference: docs/SKILLS.md.

/graph-capture is the manual companion to the nightly dream: the dream extracts knowledge from Claude Code transcripts in ~/.claude/projects/, but cannot see claude.ai web conversations or Claude Desktop chats (those live server-side or in Electron app data). Run /graph-capture at the end of a substantive claude.ai or Desktop conversation to commit any new entities, decisions, or facts to the graph.

Prerequisites

Required:

• Node.js 22+ and npm
• Docker (Desktop on Windows/macOS, or Docker Engine on Linux) with Docker Compose v2
• Claude Code and/or Claude Desktop with a Claude plan that covers Claude Code access — Pro, Max, Team, Enterprise, or Console all work (the free Claude.ai plan does not include Claude Code). Pro is fine for light/exploratory use; Max is recommended for daily-use deployments because the nightly dream process can be transcript-heavy on a busy day, and an unattended run that exhausts Pro's 5-hour window will abort mid-extraction and skip that night.
• A few hundred MB of disk for Neo4j + embeddings model

Optional:

• MarkItDown (pip install "markitdown[pdf,docx,xlsx,pptx]") — enables ingesting binary documents (.pdf, .docx, .xlsx, .pptx, .epub, .msg, .csv, .xml, .png, .jpg). Without it, ingest is limited to .md, .txt, .json, .html, .srt, .vtt.
• yt-dlp — convenient way to grab YouTube/web video subtitle files for ingestion. yt-dlp --write-auto-sub --sub-lang en --skip-download <url> writes a .vtt you can drop into ingest/pending/. Not a runtime dependency; just a tool that produces files graph-memory can already eat.
• cloudflared + a Cloudflare account — only needed for the multi-device / claude.ai web setup described in docs/REMOTE.md. Local-only deployments don't need it.
• Python 3.10+ — required only by MarkItDown and by scripts/sync-dream-skill.py.

Install

graph-memory has exactly one "primary device" — the machine that runs the two Docker containers (Neo4j + the MCP server) and runs the nightly dream + weekly maintenance scheduled tasks. Every other device is a "secondary device" that talks to the primary over HTTPS + OAuth — secondaries don't run their own containers and don't run their own dream process. Pick the install path that matches the role of the device you're sitting at right now.

Install — Primary Device (this device runs the containers)

Use this on the machine that will host Neo4j + the MCP server. This is also where the nightly dream and weekly maintenance scheduled tasks run, so the Claude Code transcripts you want extracted should live on this device.

Linux / macOS / Windows with Git Bash or WSL:

curl -fsSL https://raw.githubusercontent.com/stevepridemore/graph-memory/v0.3.0/scripts/install-primary.sh \
  | bash -s v0.3.0
# edit ~/graph-memory/.env (NEO4J_PASSWORD, GRAPH_MEMORY_HOME, CLAUDE_PROJECTS_DIR)
cd ~/graph-memory && docker compose up -d

Windows PowerShell (no bash needed):

$v = 'v0.3.0'
iwr "https://raw.githubusercontent.com/stevepridemore/graph-memory/$v/scripts/install-primary.ps1" -UseBasicParsing -OutFile $env:TEMP\gm-install.ps1
& $env:TEMP\gm-install.ps1 -Version $v
# edit $HOME\graph-memory\.env
cd $HOME\graph-memory; docker compose up -d

Verify with /graph-stats in any Claude Code session.

Optional: see docs/REMOTE.md for the Cloudflare Tunnel + Access setup that lets secondary devices and claude.ai web reach this graph remotely.

Install — Secondary Device (this device just talks to the primary)