PragmaGraph

Deterministic observed-fact graphs for code, docs, artifacts, and Git history.

GitHub · PyPI · Website · Docs · X

PragmaGraph v0.0.14 is a standalone public alpha package for facts that can be reproduced from source. It indexes local code, documents, artifacts, and Git history into deterministic graph snapshots without asking an LLM to decide what is true.

Read This First

1. Read At a Glance to confirm the observed-fact boundary.
2. Follow Install and Quick Start to index and query one local project.
3. Read How It Fits before mixing observed facts with durable memory or a graph viewer.
4. Use the Ten Minute Tour for the complete workspace, viewer, store, certification, and refresh path.
5. Read Development before changing the package.

Trust and Brand Safety

• Official GitHub: https://github.com/OpenMinion/pragmagraph
• Official website: https://www.openminion.com
• Official X account: https://x.com/OpenMinion

PragmaGraph has no official token, coin, NFT, airdrop, staking program, treasury product, or investment offering. Any claim otherwise is unauthorized and should be treated as a scam.

At a Glance

Practical rule: if a parser, static analyzer, document walker, Git reader, or explicit command can reproduce a fact without an LLM, it belongs in PragmaGraph.

Common Commands

python3.11 -m pip install pragmagraph
pragmagraph-smoke --json
pragmagraph quickstart . --serve --open --json
pragmagraph investigate --config .pragmagraph/workspace.toml "RuntimeGraph" --json
pragmagraph freshness --config .pragmagraph/workspace.toml --json

Install

Install the base package:

python3.11 -m pip install pragmagraph

Optional precise parser and native SCIP support:

python3.11 -m pip install "pragmagraph[precise]"
python3.11 -m pip install "pragmagraph[scip]"

For a source checkout:

python3.11 -m pip install -e ".[dev]"
python3.11 -m pip install -e ".[precise]"
python3.11 -m pip install -e ".[scip]"

Quick Start

External Consumer Quickstart

Start with the one-command local loop:

pragmagraph quickstart . --serve --open --json

quickstart writes .pragmagraph/workspace.toml when it does not already exist, refreshes the local snapshot, materializes the local store, and opens a visual investigation panel through GraphFakos. The generated config keeps the root, workspace, and store anchored to the repository where the command ran.

When you want the lower-level steps explicitly, run the same pieces yourself.

Index a local project:

pragmagraph index . \
  --out .pragmagraph/snapshot.json \
  --namespace demo \
  --git-identity-mode name_email_hash \
  --json

Query the snapshot:

pragmagraph query .pragmagraph/snapshot.json "RuntimeGraph" --json
pragmagraph investigate .pragmagraph/snapshot.json "RuntimeGraph" --json
pragmagraph investigate --config .pragmagraph/workspace.toml "RuntimeGraph" --json

Refresh it explicitly:

pragmagraph refresh . \
  --out .pragmagraph/snapshot.json \
  --manifest-out .pragmagraph/manifest.json \
  --namespace demo \
  --json

Run the self-contained package example:

python3.11 examples/quickstart_flow.py

For a reusable workspace and local visual graph, continue with docs/ten-minute-tour.md.

Command Map

The quickstart above is the shortest useful path. The grouped commands below are the advanced surfaces behind the same observed-fact workflow.

Connect an MCP client

Generate setup records for Claude Desktop, Cursor, Codex, Claude Code, and Hermes:

pragmagraph mcp-config --snapshot .pragmagraph/workspace/snapshot.json --json
pragmagraph mcp-config-smoke --snapshot .pragmagraph/workspace/snapshot.json --json

Supplied snapshot and root paths become machine-local absolute paths so the client can launch pragmagraph-server serve-stdio from another working directory. The command emits config objects for JSON/YAML-style clients and exact registration commands for Codex and Claude Code; it does not install or launch a client.

Inspect, export, and benchmark a snapshot when you need lower-level artifacts:

pragmagraph report .pragmagraph/snapshot.json --json
pragmagraph export .pragmagraph/snapshot.json --format mermaid
pragmagraph graphify-export .pragmagraph/snapshot.json > graphify.json
pragmagraph graph-pack-verify .pragmagraph/graph-pack --json
pragmagraph graph-pack-review .pragmagraph/graph-pack \
  --snapshot-out .pragmagraph/imported-snapshot.json \
  --store-out .pragmagraph/imported.sqlite \
  --json
pragmagraph ui-preview \
  --screen graph_pack_review \
  --graph-pack .pragmagraph/graph-pack \
  --snapshot-out .pragmagraph/imported-snapshot.json \
  --store-out .pragmagraph/imported.sqlite \
  --json
pragmagraph benchmark .

graph-pack-verify is the receiver-side trust check for a portable pack: it validates manifest counts, file checksums, optional store parity, and optional evidence JSON before import. graph-pack-review adds a receive-side summary and copyable import command without mutating files.

Use investigate when you want a compact navigation bundle for one static question. It returns matched nodes, structural match reasons, direct neighborhood facts, path facts when two matches exist, freshness facts, and copyable next commands. Presets include file_map, symbol_map, doc_links, changed_recently, orphans, and high_degree; all remain lexical or structural, with no LLM ranking or intent inference.

Open the same investigation as a local visual panel:

pragmagraph ui-preview \
  --screen investigation \
  --snapshot .pragmagraph/snapshot.json \
  --query RuntimeGraph \
  --preset symbol_map \
  --serve \
  --open

Follow observed Git provenance:

pragmagraph git-commits-for-path .pragmagraph/snapshot.json src/app.py --json
pragmagraph git-files-for-commit .pragmagraph/snapshot.json abc123def456 --json
pragmagraph git-commits-for-symbol \
  .pragmagraph/snapshot.json RuntimeGraph --json

Import precise SCIP facts explicitly:

pragmagraph precise-import index.scip \
  --root . --namespace demo --out precise-snapshot.json --json

Operate a workspace or materialized store:

pragmagraph workspace-init . \
  --workspace .pragmagraph/workspace --json
pragmagraph workspace-query .pragmagraph/workspace RuntimeGraph --json
pragmagraph store-search-explain \
  .pragmagraph/graph.sqlite RuntimeGraph --json
pragmagraph store-backends --probe-optional --json
pragmagraph certify .pragmagraph/snapshot.json --json
pragmagraph serve --snapshot .pragmagraph/snapshot.json
pragmagraph mcp-smoke --snapshot .pragmagraph/snapshot.json --json

What PragmaGraph Provides

• immutable graph DTOs for nodes, edges, source references, queries, and snapshots
• deterministic indexing for code, Markdown, selected configuration, schemas, manifests, CI workflows, and Git history
• explicit refresh manifests, structural deltas, and CI comparisons
• neighborhood, path, reverse-edge, impact, explanation, and query-plan helpers
• JSON and SQLite-backed storage interchange
• reports plus JSON, Markdown, DOT, Mermaid, Graphify, and SCIP-oriented interchange
• multi-root composition and exact cross-repository symbol resolution
• workspace, local service, read-only MCP, benchmark, certification, and privacy surfaces
• a provider adapter for GraphFakos and package-owned visual preview commands

What PragmaGraph Does Not Provide

• LLM-based fact extraction or semantic judgment
• durable agent memory, memory promotion, or preference storage
• implicit background watchers, Git hooks, cron jobs, or daemons
• hosted HTTP, WebSocket, indexing, or collaboration infrastructure
• OpenMinion orchestration or prompt-context merging
• ownership of GraphFakos viewer behavior
• automatic execution of external indexers

Refresh, ingestion, and precise-fact import are explicit. The package does not silently install tools, start background workers, or perform network discovery.

How It Fits

SophiaGraph may cite a PragmaGraph fact as evidence. PragmaGraph does not store SophiaGraph’s summaries, preferences, judgments, or memory decisions. GraphFakos may render a PragmaGraph projection but does not become the owner of the source facts.

Workspaces, Interchange, and Viewing

Create a reusable workspace configuration:

pragmagraph workspace-config-init . \
  --out .pragmagraph/workspace.toml \
  --workspace .pragmagraph/workspace \
  --label demo \
  --namespace demo \
  --ui-screen project_health \
  --json

Open the visual graph:

pragmagraph demo-ui \
  --config .pragmagraph/workspace.toml \
  --serve --open --json

PragmaGraph owns observed-fact semantics and the adapter payload. GraphFakos owns the reusable viewer shell. See docs/viewer-contract.md and docs/storage-interchange.md before integrating either boundary.

Stable consumer owners are exposed under pragmagraph.workspace and pragmagraph.ui; use those package surfaces rather than reaching into CLI implementation modules.

Development

make dev-install
make hooks-install
make check

Use make release-check before publishing or changing the documented public surface.

Docs and Release

• docs/README.md: package documentation map
• docs/ten-minute-tour.md: shortest complete tour
• docs/standalone-product-cycle.md: end-to-end local product cycle
• docs/refresh-operations.md: refresh and status contracts
• docs/service-mode.md: local service boundary
• docs/workspace-mode.md: persistent workspace contract
• docs/source-tree-owner-map.md: code owners and package layout
• API_COMPATIBILITY.md: supported import roots
• RELEASING.md: release and publish flow

License and Brand-use Boundary

• Source code license: Apache-2.0
• Brand/trademark grant: none

The license grants rights to use, modify, and redistribute the code. It does not grant rights to present a fork, clone, token, website, or social account as the official PragmaGraph or OpenMinion project or imply affiliation or endorsement.