MdGraph | Vectorless OKF Context Engine for Agentic AI

Core Capabilities

Engineered for Complete Pluggability

Swap parsers, inference providers, and database indexes via clean configuration interfaces.

Universal Ingestion

Ingest local folders (PDFs, HTML, markdown, text), live website URLs, or YouTube video transcripts with timestamped captions into structured Markdown without losing structural layout or table integrity.

Docling • Unstructured • Web • YouTube

Pluggable LLM & Offline Compiler

Compile knowledge using any LLM—from local Llama models via Ollama to Claude 3.5, Gemini 1.5, or GPT-4o—powered by LiteLLM and strict Pydantic validation. Or compile offline without API keys via deterministic rule extraction.

LiteLLM • Ollama • GPT-4o • Claude • Offline

Git-Backed Absolute Truth

Markdown with YAML frontmatter is the single, auditable source of truth. Every concept modification is versioned, committed, and diffable in Git. The database index is completely disposable and rebuildable anytime.

Libgit2 • Commit Hashes • Audit Trail

Vectorless Relational Indexing

Ditches opaque embeddings and drift. Uses SQLite FTS5 (for edge/local) or PostgreSQL JSONB (for enterprise) to index YAML frontmatter, BM25 full-text keyword search, and explicit cross-links into graph edge tables.

SQLite FTS5 • PostgreSQL JSONB • BM25

Sub-Millisecond Recursive CTEs

Execute topological multi-hop queries via SQL Recursive Common Table Expressions (WITH RECURSIVE). Resolves incoming/outgoing links and shortest paths with cycle detection in sub-millisecond execution time.

WITH RECURSIVE • Cycle Detection • Multi-Hop

Native FastMCP Server

Expose your entire knowledge graph over Model Context Protocol over stdio and sse transports. External agents in Cursor, Claude Desktop, Google ADK, and LangGraph query context natively.

stdio • SSE Transport • FastMCP Standard

High-Performance REST API

Optional standalone FastAPI microservice for high-throughput ingestion, multipart document uploads, and one-shot compilation pipelines (/api/v1/pipeline) executing off-thread via asyncio.to_thread.

FastAPI • OpenAPI Swagger • Asynchronous

Multi-Tenant Workspace Scoping

Native workspace isolation via tenant_id. Isolate team subdirectories, composite primary keys (tenant_id, id), and strictly enforced CTE graph boundaries with zero cross-tenant leakage.

Composite PKs • CTE Boundary Enforcement • Isolation

Google OKF v0.2 Guardrails

Natively conforms to Google's Open Knowledge Format v0.2 specification. Includes trust signals, human attestations (verified), expiration timestamps (stale_after), and forward-compatible Pydantic schema extensibility.

Provenance • Trust Attestations • Forward Compatible

Pipeline & Storage Architecture

Physical Separation of Compiler & Cache

MdGraph enforces a strict separation between the heavy, state-mutating Compiler Layer and the lightweight, read-optimized Query Cache.

1. Ingest

PDF, HTML, Web, YouTube

→

2. Compile

LiteLLM / Offline OKF

→

3. Store Truth

Git + Markdown Repo

→

4. Index Cache

SQLite FTS5 / Postgres CTE

5a. FastMCP Serving port 8000

Autonomous agents in Google ADK, LangGraph, Cursor, and Claude Desktop call standardized graph tools over stdio or sse.

5b. FastAPI REST Service port 8080

Asynchronous microservices, CI/CD pipelines, and web frontends consume REST endpoints, upload multipart files, and inspect Swagger docs at /docs.

Relational Cache Mapping

How plain Markdown files and relative links map into lightning-fast relational structures.

Markdown OKF Source	Relational Cache Target	Query Optimization
YAML Frontmatter	JSON / JSONB Columns	Exact-match scalar filtering, tag intersections (`?&`)
Markdown Body	SQLite FTS5 / Postgres tsvector	BM25 full-text keyword search and relevance ranking
Explicit Links `[x](./y.md)`	Graph Edge Table (source, target, tenant_id)	Sub-millisecond Recursive Common Table Expressions (`WITH RECURSIVE`)
File Metadata	Git Commit Hashes	Incremental cache invalidation, freshness verification & time-travel

SQLite Backend

Default & Zero-Config

Single-file embedded cache with WAL mode. Ideal for local desktop agents, Cursor/Claude pipelines, single-container services, and CI/CD testing.

SQLite FTS5 with BM25 ranking
In-process Recursive CTE traversals
Ephemeral in-memory mode via :memory:

Config: db_type: "sqlite"

PostgreSQL Backend

Enterprise Multi-Tenant

Enterprise backend for distributed agent swarms, Google Cloud Run, Cloud SQL, and high-concurrency production deployments.

Native JSONB with GIN containment indexing
Native tsvector + ts_rank full-text search
Multi-tenant concurrent read/write isolation

Install: pip install "mdgraph-ai[postgres]"

Google OKF v0.2 Standard

Human-Readable Markdown.
Machine-Traversable Graphs.

Unlike black-box vector databases where data is trapped inside opaque float arrays, MdGraph keeps your core knowledge fully portable. Every document is regular Markdown readable by any text editor, versioned in Git, and instantly queryable.

Zero embedding generation costs, API rate limits, or vector drift
Deterministic multi-hop pathways with 100% cited source provenance
Built-in trust signals: human attestations (verified) & expiration guardrails (stale_after)
Forward-compatible: Pydantic extra="allow" preserves future OKF fields seamlessly

Disposable Cache Architecture: The Git repository is the single source of truth. If your database cache is deleted or upgraded, rebuild the entire graph in milliseconds:

mdgraph index --rebuild

concepts/remote_work_policy.md

---
okf_version: "0.2"
type: Policy
title: Remote Work Hardware Allowance
description: Home office equipment stipend rules
tags: [hr, hardware, remote]
status: stable
stale_after: "2027-12-31"
generated:
  by: "agent:gpt-4o"
  at: "2026-10-17T00:00:00Z"
verified:
  - by: "human:hr_director"
    at: "2026-10-17T00:00:00Z"
    notes: "Approved for FY27"
sources:
  - "./raw_docs/hr_handbook_2026.pdf"
resource: "https://internal.company.com/policies/hardware"
---

# Remote Work Hardware Allowance

Employees receive a yearly stipend managed by 
the [IT Department](./it_department.md).

## Approved Purchases
All equipment must be sourced via the 
[Vendor Portal](./vendor_portal.md).

OKF v0.2 Schema Field Reference

Field	Type	Description
okf_version	str	Specification version (`"0.2"`).
type	str	Semantic concept category: `Policy`, `System`, `Service`, `Entity`, `Tool`, `Article`.
title	str	Human-readable concept title.
description	str	High-level 1-line concept description.
tags	list[str]	Keyword tags for indexed categorical filtering and intersections.
status	str	Lifecycle state: `stable`, `draft`, `deprecated`, `expired`, `archived`.
stale_after	str	ISO expiration date triggering automated agent re-attestation warnings.
generated	dict	Provenance attribution dictionary: `{ "by": "agent:gpt-4o", "at": "..." }`.
verified	list[dict]	Trust attestation list: `[{ "by": "human:reviewer", "at": "...", "notes": "..." }]`.
sources	list[str]	Upstream raw document file paths or URLs from which concept was compiled.
tenant_id	str	Workspace isolation identifier (`"default"` or tenant slug).

Agent Connectivity Protocol

Native FastMCP Server for Autonomous Agents

MdGraph exposes deterministic tools over Model Context Protocol (stdio and sse) so any agent framework can discover, traverse, and read knowledge graphs natively.

$ mdgraph serve --port 8000 (SSE HTTP)

$ mdgraph serve --transport stdio (Cursor / Claude)

Exposed MCP Tools

MCP Tool	Signature	Description
get_concept	(node_id: str, tenant_id: str = None) -> dict	Retrieve metadata, tags, and direct cross-links for a concept.
read_concept_body	(node_id: str, tenant_id: str = None) -> str	Read the exact, unmodified OKF markdown body from Git.
search_knowledge	(query: str, tags: list = None, limit: int = 10, tenant_id: str = None) -> list[dict]	BM25 full-text keyword search across title, body, and tags.
traverse_graph	(node_id: str, max_depth: int = 2, direction: str = "out", tenant_id: str = None) -> dict	Execute Recursive CTE to return topological neighbors and multi-hop pathways.
find_path	(source_id: str, target_id: str, max_depth: int = 5, tenant_id: str = None) -> dict	Find the shortest topological path between two concepts.
list_concepts	(concept_type: str = None, tag: str = None, tenant_id: str = None) -> list[dict]	Filter concepts by exact semantic type or category tags.
get_graph_stats	(tenant_id: str = None) -> dict	Total concepts, edges, commit hash, and tag distribution.
reindex	(rebuild: bool = False, tenant_id: str = None) -> dict	Refresh or rebuild relational cache from Git truth.

Deterministic Multi-Hop Reasoning

How Agents Navigate Without Hallucinations

Vector similarity fails on multi-step questions spanning non-contiguous files. MdGraph allows agents to seed, traverse, and synthesize with complete accuracy:

User Question: "How do I buy an ergonomic keyboard, who approves it, and what are security guidelines?"

1. search_knowledge("ergonomic keyboard") ──> Seed concept: [remote_work_policy]

2. traverse_graph("remote_work_policy", depth=2)

├── Outgoing edge ──> [vendor_portal] (procurement workflow)

├── Outgoing edge ──> [it_department] (approval rules)

└── Outgoing edge ──> [security_guidelines] (device compliance)

3. read_concept_body("vendor_portal") & read_concept_body("security_guidelines")

✓ Agent synthesizes a 100% cited, hallucination-free response from exact Git Markdown nodes.

Client Integration Scenarios

Claude Desktop & Cursor

Add directly to claude_desktop_config.json or .cursor/mcp.json:

{
  "mcpServers": {
    "mdgraph": {
      "command": "mdgraph",
      "args": ["serve", "--transport", "stdio"]
    }
  }
}

Natural prompt queries trigger autonomous calls to search_knowledge and traverse_graph.

Programmatic Python SDK

Connect Python agent pipelines directly over MCP:

from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

params = StdioServerParameters(
    command="mdgraph", 
    args=["serve", "--transport", "stdio"]
)
async with stdio_client(params) as (r, w):
    async with ClientSession(r, w) as session:
        await session.initialize()
        res = await session.call_tool(
            "traverse_graph", 
            {"node_id": "payment_gateway", "max_depth": 2}
        )

Official Model Context Protocol SDK compatibility.

LangGraph & CrewAI

Wrap MdGraph tools via langchain_mcp_adapters:

from langchain_mcp_adapters.client import MultiServerMCPClient
from langgraph.prebuilt import create_react_agent
from langchain_openai import ChatOpenAI

client = MultiServerMCPClient()
await client.connect_to_server(
    "mdgraph", url="http://localhost:8000/sse"
)
tools = client.get_tools()
agent = create_react_agent(ChatOpenAI(model="gpt-4o"), tools)
ans = await agent.ainvoke({"messages": [...]})

Equip standard ReAct agents with deterministic graph reasoning.

High-Throughput Microservice

Standalone FastAPI REST Service

Dedicated asynchronous REST microservice for remote document ingestion, multipart file uploads, and one-shot compilation pipelines with zero overhead on core operations.

$ mdgraph api --port 8080 --host 0.0.0.0

Swagger UI at /docs

Method	Endpoint	Description
GET	/health	Health check, knowledge repository path, and total concept count.
POST	/api/v1/ingest	Polymorphic ingestion accepting URLs, YouTube links, local paths, or folders.
POST	/api/v1/ingest/url	Ingest a website URL or YouTube video link into normalized Markdown.
POST	/api/v1/ingest/file	Multipart file upload (`multipart/form-data`) supporting PDF, HTML, Markdown, and text.
POST	/api/v1/compile	Compile Markdown into OKF concepts (supports LLM or offline, optional Git commit).
POST	/api/v1/pipeline	One-shot pipeline: Ingest any source (URL, YouTube, text) AND compile into OKF concepts in Git in a single call.
GET	/api/v1/concepts	Search or list concepts from the relational query cache with tag/type filters.
GET	/api/v1/graph/traverse/{node_id}	Execute recursive CTE multi-hop traversal over HTTP with depth & direction parameters.
GET	/api/v1/tenants	List all active isolated tenant workspaces.

# Ingest URL via cURL

curl -X POST "http://localhost:8080/api/v1/ingest/url" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://docs.python.org/3/tutorial/"}'

# Multipart PDF Upload

curl -X POST "http://localhost:8080/api/v1/ingest/file" \
  -F "file=@./specs/architecture.pdf"

# One-Shot Pipeline (YouTube to OKF in Git)

curl -X POST "http://localhost:8080/api/v1/pipeline" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "offline": true,
    "save_to_repo": true
  }'

# Multi-Hop Traversal via HTTP

curl "http://localhost:8080/api/v1/graph/traverse/remote_work_policy?max_depth=3"
curl "http://localhost:8080/api/v1/graph/paths?source=payments&target=ledger"

Enterprise Security & Partitioning

Multi-Tenant Workspace Isolation

Different business units, projects, or client organizations can store, index, traverse, and query knowledge graphs within a shared repository and relational database with complete data isolation.

Git Workspace Directory Layout

knowledge/
├── index.md                       # Root index (default workspace)
├── concepts/                      # Default workspace concepts
│   ├── api_gateway.md
│   └── auth_service.md
└── tenants/                       # Multi-tenant workspaces
    ├── team_fintech/
    │   └── concepts/
    │       ├── payment_router.md  # fintech-isolated concept
    │       └── ledger.md
    └── team_security/
        └── concepts/
            └── payment_router.md  # Identical ID, zero clash

Composite Primary Keys

Both SQLite and PostgreSQL index tables utilize PRIMARY KEY (tenant_id, id). Different teams can name concepts identically without colliding.

Recursive CTE Boundary Enforcement

All edges store tenant_id. Recursive CTE traversals enforce edges.tenant_id = ? across anchor and recursive steps, ensuring multi-hop paths never jump between tenants.

Seamless Across All 3 Interfaces

Pass --tenant team_fintech in CLI, send X-Tenant-ID HTTP header in REST API, or supply tenant_id to any FastMCP agent tool.

Developer Guide

Get Started in Minutes

From zero to an autonomous, Git-versioned knowledge graph ready for agent swarms.

# Step 1: Install MdGraph Engine & Extras pip / uv

# Core engine (CLI, Git, FastMCP, SQLite FTS5)
$ pip install mdgraph-ai

# Or install complete suite (API, PostgreSQL, dev tools)
$ pip install "mdgraph-ai[all]"

# Step 2: Initialize an OKF Knowledge Base Git-Backed

$ mdgraph init ./knowledge

# Step 3: Universal Ingestion (Files, Web, YouTube) Any Source

# Ingest local folder of PDFs, HTML, markdown
$ mdgraph ingest ./raw_documents/ --dest ./normalized/

# Ingest website URL into structured Markdown
$ mdgraph ingest https://docs.python.org/3/tutorial/

# Ingest YouTube video transcript
$ mdgraph ingest https://www.youtube.com/watch?v=dQw4w9WgXcQ

# Step 4: Compile into OKF Concepts LLM or Offline

# Compile via LiteLLM (GPT-4o, Claude 3.5, Gemini 1.5, Ollama)
$ mdgraph compile ./normalized/handbook.md --model openai/gpt-4o-mini

# Or compile offline without API keys
$ mdgraph compile ./normalized/handbook.md --offline

# Step 5: Search & Multi-Hop Traversal BM25 & CTE

# Full-text BM25 search
$ mdgraph query "hardware allowance"

# Multi-hop topological graph traversal up to 3 hops
$ mdgraph traverse remote_work_policy --depth 3

# Step 6: Serve to Agents (FastMCP & REST) Production Ready

# FastMCP Server (Cursor, Claude, Google ADK, LangGraph)
$ mdgraph serve --port 8000

# Standalone FastAPI REST microservice
$ mdgraph api --port 8080

Cloud Native

Cloud Deployment: Google Cloud Run & Docker

Deploy containerized MdGraph microservices with automatic scaling to zero and long-lived SSE streaming.

1. Run with Docker

# Build Docker image
docker build -t mdgraph:latest .

# Run REST API service on port 8080
docker run -p 8080:8080 mdgraph:latest

# Or run FastMCP Server over SSE on port 8000
docker run -p 8000:8000 mdgraph:latest \
  mdgraph serve --transport sse --port 8000

2. Serverless Google Cloud Run

# Deploy FastMCP Server with SSE session affinity
gcloud run deploy mdgraph-mcp \
  --image=$IMAGE_URI \
  --command="mdgraph" \
  --args="serve,--transport,sse,--host,0.0.0.0,--port,8080" \
  --region=us-central1 \
  --allow-unauthenticated \
  --port=8080 \
  --timeout=3600 \
  --session-affinity \
  --use-http2

Hierarchical Configuration

Clean YAML & Environment Controls

Configure MdGraph via YAML (mdgraph.yaml), CLI flags, or environment variables. CLI flags take highest precedence, followed by MDGRAPH_* variables, YAML, and built-in defaults.

MDGRAPH_REPO_PATH: Git storage path (default: ./knowledge)
MDGRAPH_DB_TYPE: SQLite or PostgreSQL backend
MDGRAPH_LLM_MODEL: OpenAI, Claude, Gemini, Ollama
MDGRAPH_AUTO_COMMIT: Automatic Git audit trail commits

mdgraph.yaml Default Config

repo_path: "./knowledge"
cache_path: "./.mdgraph/cache.db"
db_type: "sqlite"

# FastMCP Server settings
mcp_host: "0.0.0.0"
mcp_port: 8000

# Standalone REST API settings
api_host: "0.0.0.0"
api_port: 8080

# Compiler LLM (OpenAI, Anthropic, Gemini, Ollama via LiteLLM)
llm_model: "openai/gpt-4o-mini"
llm_temperature: 0.1

# Automated Git commits
git_author_name: "MdGraph Compiler"
git_author_email: "compiler@mdgraph.dev"
auto_commit: true

Kill the Vector Chunks. Store Explicit Knowledge Graphs.