procedural-graphs 🧭

Python implementation of Procedural Graphs (arXiv:2609.09153): an explicit, attributed graph of tools, skills, and statuses; locate–extract–generate situational guidance; and offline evolution with rejection memory.

Includes an optional FastMCP overlay for Cursor, Claude Code, and other MCP clients.

(Currently in pre-release testing — install directly from source).

The Problem It Solves

Standard LLM agents rely on an ever-growing linear conversation history. Over long-horizon tasks, agents suffer from planning drift, out-of-order tool calls, and repetitive action loops.

Procedural Graphs replace flat context histories with an explicit, evolving state machine:

1. At runtime (Inference): The agent only receives situational guidance for its current step and immediate valid transitions, cutting prompt bloat.

2. Playbook evolution (agent-in-the-loop): Failed steps are recorded in session memory; the host agent proposes a recovery and applies it with apply_graph_mutation. No API keys.

Quick Setup (From Source)

Requires Python 3.11+.

git clone https://github.com/<YOUR-USERNAME-OR-ORG>/procedural-graphs.git
cd procedural-graphs

# Create & activate a virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .\.venv\Scripts\Activate.ps1

# Install with MCP dependencies
pip install "mcp[cli]" -e .

Python SDK Usage

from procedural_graphs import (
    ProceduralGraph,
    ProcedureNode,
    TransitionEdge,
    GuidedAgent,
)

# 1. Build an attributed procedural graph
graph = ProceduralGraph()
graph.add_procedure(ProcedureNode(id="Start", name="Start", description="Entrypoint"))
graph.add_procedure(ProcedureNode(id="migrate", name="migrate", kind="tool"))
graph.add_transition(
    TransitionEdge(
        source="Start",
        target="migrate",
        condition="Schema change approved",
        guidance="Run the migration playbook.",
        pitfalls="Do not skip the backup.",
    )
)

# 2. Run agent with situational guidance
def agent_fn(query, history, guidance):
    print(f"Advisory Guidance: {guidance.text}")
    return {"action": "migrate", "output": "Migration complete"}

agent = GuidedAgent(agent_fn, graph, evolve=False)
result = agent.run("Deploy schema update")

Editor Setup (Cursor & Claude Code)

Serve the central playbook hub via MCP. Playbooks live in ~/.procedural-graphs/playbooks/ (not in each git repo). On first run, bundled templates are copied there only if a file of that name is missing — user edits and apply_graph_mutation results are never overwritten. Session cursors are stored under ~/.procedural-graphs/sessions/, keyed by repository, task_id, and playbook.

Do not copy YAML into project trees. Cursor mcp.json does not need --graph.

Cursor

In your .cursor/mcp.json (or cursor-settings.json):

{
  "mcpServers": {
    "procedural-graphs": {
      "command": "<PATH_TO_VENV>/bin/python",
      "args": ["-m", "procedural_graphs.cli", "serve"]
    }
  }
}

(On Windows, use: "C:\\path\\to\\.venv\\Scripts\\python.exe").

Optional: --graph path/to/playbook.yaml overrides the default playbook file for power users and tests. Named playbooks (e.g. bugfix) still resolve from the hub.

Claude Code (Terminal)

claude mcp add procedural-graphs -- <PATH_TO_VENV>/bin/python -m procedural_graphs.cli serve

Call list_available_playbooks to see hub stems, then get_procedural_guidance(playbook="feature-dev", task_id="..."). Mutations written by apply_graph_mutation update the central file, so learning in one repository is visible in another.

Ready-Made Playbooks

Bundled templates ship inside the Python package (procedural_graphs/default_playbooks/) and seed the user hub. examples/ in this repo is a browseable copy of the same schemas — it is not a per-project install path.

Testing

Run the test suite using pytest:

pip install pytest
pytest -v

The test suite in tests/ verifies:

• Graph Topology: Cycle handling, attribute validation, and serialization (test_graph.py).

• Inference Guidance: Node localization from trajectories and prompt compilation (test_guidance.py).

• Self-Evolution: Offline LLM refiner loops, mutation validation, and rejection memory deduplication (test_evolver.py).

• MCP session helpers: Agent-in-the-loop mutation apply/persist and anomaly recording without a live server (test_mcp_session.py).

• Central hub: Copy-missing-only seed, playbook path fallback, task-scoped sessions, hub mutations, and serve without --graph (test_storage.py, test_hub_sessions.py, test_cli.py).

Citation

@article{lu2026procedural,
  title={Procedural Graphs: Self-Evolving Execution Structures for LLM Agents},
  author={Lu, Yuxing and Chen, Yicheng and Wu, Shanchan and Ar{\i}k, Sercan {\"O}},
  journal={arXiv preprint arXiv:2609.09153},
  year={2026}
}

License

MIT