meta-knowledge-graph

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 that distills durable :Learning candidates (scoped project or user, covering durable facts and decisions alike) from what just happened, plus an append-only :Observation timeline entry per work window (episodic memory: what happened, recalled by recency at session start).

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 is frozen at runtime: it is read on start but never rewrites itself. The memory extraction prompt is a fixed code constant — there is no Neo4j-backed self-improvement loop. The only writers of the system prompt 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 can run in several ways:

• Claude Code — install the packaged plugin (below). This is the quickest path and the one most users want.
• Codex — install the packaged plugin for lifecycle hooks, the MCP server, and Codex skills, or run straight from a repo checkout with the committed .codex/ wiring.
• Other harnesses — any MCP-capable harness with lifecycle hooks can drive the same shared scripts.

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 MCP start after install, the plugin launcher falls back to uv run --project to create the plugin cache virtualenv (one-time; that start is slower). Later MCP starts execute the cached .venv/bin/python -m meta_knowledge_graph directly, with the venv on PATH so optional MCP subprocesses run from the 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 the Claude Code plugin

For an installed Claude Code plugin, the config path is:

~/.config/meta-knowledge-graph/.env

Credentials live in that one user-global file (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. Example ~/.config/meta-knowledge-graph/.env: