@opengsd/gsd-graph

Graph Engineering toolkit — build a local knowledge graph of relationships (subject–predicate–object triples with provenance), then answer multi-hop questions with citations.

| | | |--|--| | CLI | gsd-graph | | MCP | gsd-graph-mcp | | Store | .gsd-graph/graph.v1.json (source of truth) | | Runtime | Node.js ≥ 22 · offline by default | | npm | @opengsd/gsd-graph |

OpenGSD is the publisher namespace only. This package has no runtime dependency on gsd-core, GSD workflows, or Python graphify.

Why this exists

Regular RAG finds text fragments. Graph Engineering finds relationships — causation chains, “how A connects to B,” corpus-level themes.

extract → normalize → store → query → ground → maintain

Quick start

Global CLI (recommended)

npm install -g @opengsd/gsd-graph

# one shot: skill + hooks + config + full brownfield graph (+ MCP)
gsd-graph enable --mcp

# multi-hop Q&A with citations
gsd-graph ask "why is phase 4 blocked by phase 3?"

MCP for Claude / Codex / Cursor (if you skipped --mcp):

gsd-graph mcp install
gsd-graph mcp doctor   # after restarting the host

The global install keeps this CLI separate from a project's dependency tree. To upgrade later, rerun the install command with @latest.

Zero-install via npx (scoped package)

Because the package is scoped (@opengsd/…), use the package name (or -p) so npx resolves the bin:

# run the gsd-graph binary from the published package
npx -y @opengsd/gsd-graph enable
npx -y @opengsd/gsd-graph ask "why is X blocked by Y?"
npx -y @opengsd/gsd-graph status

# equivalent explicit form
npx -y -p @opengsd/gsd-graph gsd-graph enable

For reproducible automation, replace the unversioned package with an exact release, for example @opengsd/[email protected].

Local library dependency

Install locally only when application code imports the Node.js API:

npm install @opengsd/gsd-graph

After a local install, npx gsd-graph … also works via node_modules/.bin.

| Command | When | |---------|------| | gsd-graph enable --mcp | First time in a repo (+ register MCP hosts) | | gsd-graph sync | After docs / planning change (incremental) | | gsd-graph sync --llm | Also extract relationships from prose via your agent (or --llm http) | | gsd-graph ask "…" | Grounded multi-hop answer (overview questions get community themes) | | gsd-graph ask "…" --semantic | Retry no-seed abstains via the opt-in embedding sidecar | | gsd-graph why <a> <b> [--k 3] | How A connects to B — cited prose (+ alternative routes) | | gsd-graph top | Most central nodes (PageRank / degree) | | gsd-graph assert <s> <p> <o> | Record a learned fact (episode-logged; survives rebuilds) | | gsd-graph retract <tripleId> | Remove a wrong fact (episode-logged) | | gsd-graph supersede <winner> <loser> | Record a decision reversal | | gsd-graph export --format html --open | Interactive graph viewer (also mermaid / graphml / cypher) | | gsd-graph status | Counts / freshness / next steps | | gsd-graph query <term> | Seed-expand search | | gsd-graph watch | Debounced incremental sync on file changes (any editor) | | gsd-graph hook install-git | Plain .git/hooks/post-commit sync hook | | gsd-graph eval | Answer-quality QA set (seed recall, citation validity) | | gsd-graph review summary | Review-queue triage (counts by kind + hints) | | gsd-graph review accept --all --kind predicate_unknown | Batch-resolve review queue | | gsd-graph ontology eject | Materialize active pack + accepted extensions as a local pack | | gsd-graph embeddings build | Opt-in embedding sidecar for semantic seed fallback | | gsd-graph mcp install | Wire Claude / Codex / Cursor + project .mcp.json | | gsd-graph mcp doctor | Check store + MCP registration |

Agent skill (installed by enable): /skill:gsd-graph

Documentation

| Guide | Audience | |-------|----------| | Quick Guide | Install, 3 commands, continuous update, AI in 5 minutes | | Day in the life | Agent workflow: enable → hooks → ask vs query vs Memtrace | | Full Guide | Corpus, maintain, MCP, ontology, LLM, CLI reference, troubleshooting | | Publishing | GitHub Release → npm trusted-publishing runbook | | Design | Architecture, store contracts, pipeline decisions | | Changelog | Release history | | Skill | Agent skill source |

Continuous update

enable writes .gsd-graph/config.json with enabled + auto_update. Wire PostToolUse (Bash) to:

.gsd-graph/hooks/gsd-graph-update.sh

After commits on the default branch, a detached incremental gsd-graph sync runs (never blocks). Status: .gsd-graph/.last-sync-status.json.

No .planning/ required. If .planning/config.json exists, flags are mirrored under gsd_graph for GSD hosts.

Details: Full Guide → Continuous update.

What gets indexed

Auto corpus (when present): .planning/, docs/, README.md, CHANGELOG.md, AGENTS.md, …

Does not scan all of src/ by default.

gsd-graph sync --corpus ./specs --full
# or zero-install:
npx -y @opengsd/gsd-graph sync --corpus ./specs --full

Deterministic extraction reads explicit structure only: A --predicate--> B edge lines, [[wiki]] links, headings, Term: definition lines, #tags. Free prose never becomes a typed edge on its own (honesty by design).

LLM-assisted extraction (opt-in) is how prose becomes relationships:

gsd-graph sync --llm            # writes .gsd-graph/.prompt-extract.json for your agent
gsd-graph prompt apply extract  # merges the agent's result (INFERRED + review-gated)

gsd-graph sync --llm http       # or call an endpoint directly (OpenAI- or Anthropic-compatible)

config.json → llm.http: { "provider": "anthropic" | "openai", "base_url", "model", "api_key_env" }. LLM candidates are always INFERRED, carry llm/* provenance, and pass the same ontology gate + review queue as everything else.

How AI uses the graph

1. Sync keeps triples current from corpus files
2. Pack retrieves a small subgraph for the question (seeds → hops → paths → budget)
3. Ask / MCP graph_answer grounds the reply on that pack only — or abstains if empty

Default answer path is deterministic (no API key). Optional --llm must still cite pack triple ids only.

→ Full Guide → How AI leverages the graph

Store (source of truth)

| Path | Role | |------|------| | .gsd-graph/graph.v1.json | Canonical SoT | | .gsd-graph/graph.json | Disposable projection | | .gsd-graph/communities/ | Disposable theme reports | | .gsd-graph/GRAPH_REPORT.md | Human summary |

Native query/answer APIs never treat projections as authority.

Advanced surfaces

gsd-graph init --ontology engineering   # persisted; build/sync honor it
gsd-graph build --corpus ./docs
gsd-graph pack "question"
gsd-graph path Concept:a Concept:b
gsd-graph why "payments module" "postgres"
gsd-graph export --format mermaid       # or graphml | cypher | html
gsd-graph communities detect
gsd-graph review list
gsd-graph review accept --all --kind predicate_unknown --extend-ontology
gsd-graph snapshot save pre-refactor
gsd-graph mcp install
# or: npx -y -p @opengsd/[email protected] gsd-graph-mcp

Machine contract: JSON on stdout (K22). Library: require('@opengsd/gsd-graph').

Ontology packs: general (default), engineering, research.

Develop

npm install
npm run build
npm test
npm publish --access public   # maintainers; requires npm login to @opengsd

License

MIT — see LICENSE.