axiom-graph 2.0.0

Project knowledge indexer for AI agents — scans code, tracks documentation staleness, and serves a knowledge graph to AI agents via MCP

Cortex

A project knowledge indexer that scans your codebase, builds a structured graph of modules, functions, classes, and documentation, and tracks when docs drift from the code they describe. Designed for AI-assisted development -- cortex gives agents structured access to your project through the Model Context Protocol (MCP).

Quick Start

pip install axiom-graph[viz]

axiom-graph init /path/to/your/project    # scan and build the index
axiom-graph check /path/to/your/project   # see what's stale
axiom-graph viz /path/to/your/project     # launch the dashboard

Features

• Knowledge graph -- indexes Python (and JS/TS via tree-sitter) into nodes and edges: functions, modules, classes, docs, tests, and their relationships
• Staleness detection -- two-dimensional tracking (own content changes + linked dependency changes) with transitive propagation through doc chains
• MCP server -- 29 tools for AI agents to search, read, navigate, and modify the index over the Model Context Protocol
• Viz dashboard -- interactive browser UI with graph view, list view, doc manager, workflow explorer, and detail panels
• DocJSON -- structured documentation format that links sections to code nodes, enabling automated drift detection
• dFlow integration -- optional workflow/task decorators with step markers, indexed alongside code
• CI gate -- axiom-graph check --fail-on any in GitHub Actions prevents stale docs from merging

MCP Server Setup

The MCP server is how AI agents interact with cortex. It uses stdio transport.

Claude Code

Create .mcp.json in your project root:

{
  "mcpServers": {
    "axiom-graph": {
      "type": "stdio",
      "command": "/path/to/your/venv/bin/python",
      "args": ["-m", "axiom_graph.mcp_server"],
      "env": {
        "AXIOM_GRAPH_LOG_LEVEL": "INFO"
      }
    }
  }
}

VS Code (Copilot / Continue)

Add to .vscode/settings.json:

{
  "mcp.servers": {
    "axiom-graph": {
      "command": "/path/to/your/venv/bin/python",
      "args": ["-m", "axiom_graph.mcp_server"],
      "env": {
        "AXIOM_GRAPH_LOG_LEVEL": "INFO"
      }
    }
  }
}

Any MCP client

The entry point is axiom-graph-mcp (installed as a console script) or python -m axiom_graph.mcp_server. Both use stdio transport -- JSON-RPC on stdin/stdout, logs on stderr.

Logging

Variable	Default	Description
AXIOM_GRAPH_LOG_LEVEL	INFO	DEBUG, INFO, WARNING, ERROR
AXIOM_GRAPH_LOG_FILE	(none)	Path to a rotating log file (5 MB max, 2 backups)

Set AXIOM_GRAPH_LOG_LEVEL=DEBUG to see tool entry/exit timing, SQL queries, and build details. Logs always go to stderr; AXIOM_GRAPH_LOG_FILE adds a file copy.

Documentation

Full documentation is available as a consumer docs site:

pip install axiom-graph[viz]              # includes mkdocs-material
axiom-graph render-site /path/to/project  # generates site/ directory
axiom-graph render-site /path/to/project --serve  # live preview at localhost:8000

Or read the DocJSON source files directly in docs/consumer/:

• Getting Started
• Core Concepts
• Staleness Engine
• Documentation System
• dFlow Integration
• MCP Server
• MCP Setup & Observability
• Viz Dashboard
• Configuration

License

MIT