pragmagraph 0.0.1

Standalone observed-fact graph substrate for code and document structure

PragmaGraph

Standalone observed-fact graph substrate for code and document structure.

pragmagraph is the future native third-brain package for OpenMinion-style code and document graphs. The name comes from Greek pragma, meaning a deed, matter, or thing done. In this package, the name frames the third brain as the place for observed structure: files, symbols, documents, artifacts, references, commits, and other reproducible facts.

This 0.0.1 semantic alpha provides a small local source-graph MVP: deterministic DTOs, JSON snapshots, a local code/document indexer, lexical and structural query helpers, CLI commands, and fixture handoff artifacts for future OpenMinion adapter work.

Boundary

• Sophiagraph owns inferred, judged, lossy durable memory.
• PragmaGraph owns observed, indexer-extracted, reproducible facts and deeds.
• Graphify remains the first third-brain adapter. PragmaGraph is the future native package, not a relabeling of Graphify.

The boundary discussion lives in the host repository at docs/discussions/sophiagraph-pragmagraph-boundary-2026-05-27.md. The shortest future-agent reference is docs/reference/second-vs-third-brain-quick-reference.md.

Practical rule: if a parser, static analyzer, doc walker, git reader, or shell command can reproduce the fact without an LLM, it belongs in PragmaGraph. If it depends on a preference, operator pin, summary, design judgment, or memory consolidation decision, it belongs in Sophiagraph. Sophiagraph may cite PragmaGraph with pragma://... evidence references; PragmaGraph never stores Sophiagraph's judgments.

Trust and Brand Safety

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.

License and brand-use boundary

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

The software license grants rights to use, modify, and redistribute the code. It does not grant rights to use the PragmaGraph, Sophiagraph, or OpenMinion names, logos, branding, website identity, or social identity except for truthful attribution. Forks, clones, and derivative distributions must not present themselves as the official PragmaGraph project or imply affiliation, endorsement, or maintenance by PragmaGraph or OpenMinion contributors unless that is actually true.

What the package provides

The package currently provides:

• package metadata and Apache-2.0 release files
• stable alpha import roots:
  • pragmagraph
  • pragmagraph.contracts
  • pragmagraph.models
  • pragmagraph.query
  • pragmagraph.storage
  • pragmagraph.adapters
  • pragmagraph.portability
• immutable DTOs for source refs, graph nodes, graph edges, snapshots, query hits, omitted diagnostics, path results, and health summaries
• deterministic JSON snapshot load/save helpers
• a local indexer for directories, files, Markdown headings, Python AST definitions/imports, and lexical snippets
• query, neighborhood, path, and health helpers over loaded snapshots
• CLI commands for index, query, neighborhood, path, and health
• a semantic smoke entrypoint for install validation
• package-local tests, lint, and release-check workflow
• API compatibility and release docs

What the package does not provide yet

This package does not currently provide:

• SQLite, KuzuDB, Neo4j, hosted, vector, or typed-edge storage
• Graphify runtime API wrapping or Graphify replacement behavior
• file watchers, git hooks, daemons, or scheduled refresh
• OpenMinion runtime provider wiring
• prompt context merging
• semantic inference from prose or model output
• automatic Sophiagraph memory writes or promotion

Those features belong to follow-on releases or to OpenMinion's provider adapter layer.

Install

Editable install during local development:

python3.11 -m pip install -e .

Install with development tools:

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

Wheel build:

python3.11 -m build

Standalone Smoke

Source-root smoke:

PYTHONPATH=src python3.11 -m pragmagraph --json

Installed-console-script smoke:

pragmagraph-smoke --json

Expected output is deterministic JSON with the package name, version, status, stable import roots, and semantic_contract: true.

CLI Quickstart

Index a local code/docs root into a deterministic JSON snapshot:

pragmagraph index . --out .pragmagraph/snapshot.json --namespace my-project --json

Query the snapshot:

pragmagraph query .pragmagraph/snapshot.json "RuntimeGraph" --json

Inspect nearby graph facts:

pragmagraph neighborhood .pragmagraph/snapshot.json \
  "pragma://my-project/file/src/app.py" --json

Check health:

pragmagraph health .pragmagraph/snapshot.json --json

External Consumer Quickstart

Minimal standalone flow for another framework or service:

import pragmagraph

snapshot = pragmagraph.index_path(".", namespace="example")
pragmagraph.save_snapshot(snapshot, ".pragmagraph/snapshot.json")
print(pragmagraph.PACKAGE_STATUS)

The package can also be checked from a shell:

python3.11 -m pragmagraph --json

See API_COMPATIBILITY.md for the public import-root policy and RELEASING.md for package-local release checks.