Meta Knowledge Graph: Self-Learning Memory for AI Agents
The Meta Knowledge Graph (MKG) is a self-improving, graph-structured memory
layer for AI agents, backed by Neo4j. It is harness-agnostic: the Neo4j
store and the MCP server plug into any MCP-capable harness, and the
capture/injection scripts ride on whatever lifecycle hooks the harness exposes.
This repo ships ready-made wiring for Claude Code
(.claude/settings.json) and Codex
(.codex/config.toml plus
.codex/hooks.json); plugging a custom harness in means
pointing its lifecycle events at the same scripts.
It ships as two halves that form a closed capture-and-recall loop:
- MCP server (
meta-knowledge-graph) — surfaces project memory, the underlying
graph, the persisted system prompt, and (optionally) a data catalog and
warehouse to the agent as tools.
- Lifecycle hooks — plain Python scripts that log every session event,
inject scoped project context on prompt submit, and run an LLM memory extraction processor at Stop
(and SessionEnd when the harness exposes it)
that distills durable
:Learning (scoped project or user) and
:Decision candidates from what just happened.
The hooks write to the same graph the MCP tools read from, so each new session
starts with the most relevant prior learnings already injected — both
project-scoped memory and durable facts about the user. The persisted system
prompt and memory extraction prompt are frozen at runtime: they are read
on start but never rewrite themselves. The only writers besides the seed scripts
are the deliberate consolidation services — a rate-limited Stop/SessionEnd hook
that folds accumulated user-profile memory into the system prompt once enough of
it has piled up unreviewed, keeping every superseded prompt as version history.
A complete end-to-end demo — a B2B sales / customer-success assistant for an
enterprise car-rental provider — ships in the repo; see
Sales agent use case for setup.
Running MKG
MKG is harness-agnostic, and there are two ways to run it:
- Claude Code — install the packaged plugin (below). This is the quickest
path and the one most users want.
- Codex and other harnesses — they run today straight from a repo
checkout: the
.codex/ wiring is committed, so opening this repo Just Works,
and any harness with lifecycle hooks can drive the same scripts. Dedicated
plugins for Codex and other harnesses are on the roadmap.
Either way MKG is two halves — lifecycle hooks (capture + recall) and an
MCP server (Neo4j / BigQuery / neocarta tools) — and the only host
prerequisites are uv and a reachable Neo4j
instance; both halves execute through uv.
Claude Code (plugin)
claude plugin marketplace add neo4j-labs/meta-knowledge-graph
claude plugin install meta-knowledge-graph@mkg
- The marketplace is named
mkg; the qualified plugin id is meta-knowledge-graph@mkg.
- On the first session after install, the
SessionStart hooks bootstrap a
uv virtualenv for the plugin cache (one-time; that session is slower).
Later sessions reuse it, and optional MCP subprocesses run from that same
environment instead of doing their own uvx startup install.
- Verify:
claude plugin list shows meta-knowledge-graph@mkg enabled; inside
a session the MKG system prompt is injected and mcp__meta-knowledge-graph__*
tools are available.
claude plugin disable meta-knowledge-graph@mkg
claude plugin enable meta-knowledge-graph@mkg
claude plugin details meta-knowledge-graph@mkg # component inventory + token cost
Configuring
Credentials live in one user-global file, ~/.config/meta-knowledge-graph/.env
(mode 600), read by both the hooks and the MCP server. It survives plugin
updates and is never written into the ephemeral plugin cache.
MKG deliberately does not use /plugin configure — there is no
userConfig/keychain schema, so credentials stay file-based and portable
across harnesses (Codex, etc.).
Run the wizard in your own terminal (it prompts for secrets):
uv run --project ~/.claude/plugins/marketplaces/mkg meta-knowledge-graph setup
…or write the file by hand:
mkdir -p ~/.config/meta-knowledge-graph
cat > ~/.config/meta-knowledge-graph/.env <<'EOF'
NEO4J_URI=neo4j+s://xxxx.databases.neo4j.io
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=change-me
NEO4J_DATABASE=neo4j
OPENAI_API_KEY=sk-... # optional: memory extraction + embeddings
# ANTHROPIC_API_KEY / GEMINI_API_KEY / OPENROUTER_API_KEY / DIFFBOT_TOKEN also honored
EOF
chmod 600 ~/.config/meta-knowledge-graph/.env
