MagGraph

In-process Git-backed graph engine for AI semantic layers — powered by Rust

Why "MagGraph"? The name is short for Magpie — a Corvid. Corvids (ravens, crows, jays, and magpies) are renowned in animal cognition research for their remarkable intelligence, long-term memory, and sophisticated tool use. MagGraph is built to be the memory and knowledge layer for AI agents with those same qualities: a graph that thinks, remembers, and uses tools.

MagGraph stores knowledge as versioned Markdown nodes in your Git repository, with BFS/DFS traversal, Git-backed sync, external lakehouse content resolution, and a built-in MCP server scaffold — all from a zero-dependency pip install.

Install

pip install maggraph

Pre-built wheels are available for:

No Rust toolchain required — the Rust core is compiled into the wheel.

Quick start

import maggraph

# Load config + open the graph index
config = maggraph.load_config("maggraph.toml")
index  = config.open_index()

# List nodes
print(index.list_nodes())          # ['getting_started', 'welcome', ...]

# Read a node
node = index.read_node("welcome")
print(node.body)                   # full markdown body

# Search, backlinks, and recall
print(index.search("Welcome")[0]["id"])
print(index.backlinks("welcome"))
bundle = index.recall_bundle("welcome", reason="quick start")
print(bundle["markdown"])

# BFS traversal
result = index.traverse("welcome", depth=2, order="bfs")
print(result.to_markdown(index))   # formatted traversal report

# CRUD and memory helpers
index.create_memory_node("prefers_cli", "preference", "User prefers CLI-first UX.")
index.create_node("new_note", node_type="note", body="# Hi\n", links=["welcome"])
index.update_node("new_note", "# Updated\n")
index.suppress_node("new_note", reason="example")
index.unsuppress_node("new_note")
index.delete_node("new_note")

Async support

import asyncio, maggraph

async def main():
    index = maggraph.open_index("examples/basic/knowledge_graph")
    node  = await index.read_node_async("welcome")
    result = await index.traverse_async("welcome", depth=3, order="dfs")
    print(result.to_markdown(index))

asyncio.run(main())

Blocking Rust work runs on a Tokio thread pool — Python's event loop stays responsive.

Lakehouse content resolution

Resolve external data sources (S3, file://, HTTP) referenced from node frontmatter:

import maggraph

config = maggraph.load_config("maggraph.toml")  # mode = "lakehouse"
index  = config.open_index()
reader = config.open_lakehouse_reader()

# Resolve a node's external source (e.g. s3://bucket/data.parquet)
result = reader.read_node(index, "customer_churn_q2")
print(result.content.kind)          # "external_asset"
print(result.content.uri)           # "s3://corp-data/lake/churn.parquet"
print(result.content.format)        # "parquet"
print(result.content.to_markdown()) # agent-friendly summary

# Cache stats
print(reader.cache_len())    # 1
print(reader.cache_bytes())  # ~128

# Also callable directly on the index
result2 = index.read_node_with_content(reader, "customer_churn_q2")

maggraph.toml for lakehouse mode:

[storage]
mode = "lakehouse"
root_path = "./knowledge_graph"

[lakehouse]
remote_sources = [
  { uri = "s3://corp-data/lake", format = "parquet" }
]

MCP server scaffold

maggraph scaffold --mcp --output ./mcp_server

Generates a ready-to-run FastMCP server at ./mcp_server/server.py wired to your graph index — expose list_nodes, read_node, traverse, create_node, and delete_node as MCP tools with one command.

Git-backed sync

# Leader pushes a snapshot
maggraph sync push --message "Add Q2 analysis nodes"

# Follower (read-only) pulls
maggraph sync pull

API reference

Links

• GitHub
• Architecture & planning docs
• Examples
• CONTRIBUTING.md

License

MIT OR Apache-2.0