Knowledge Graph

The Knowledge Graph is the backbone of RaiSE's context system. It merges everything — memory patterns, governance documents, skills metadata, work tracking, and discovered components — into a single graph of connected concepts.

What It Is

A directed graph where: - Nodes are concepts — patterns, principles, requirements, skills, stories, components, modules - Edges are relationships — "learned from", "governed by", "depends on", "constrained by"

When you run rai graph build, the CLI traverses all project sources and assembles this graph. When you query with rai graph query or rai graph context, you're searching this graph.

Node Types

The type field on GraphNode is an open string — any value is valid. RaiSE defines 23 built-in types as subclasses:

Type	ID Pattern	Source	Example
pattern	PAT-*, BASE-*	Memory JSONL files	"Use fixtures for database tests"
calibration	CAL-*	Calibration records	Story S3.5: M size, 45 min actual
session	SES-*	Session history	"Implemented auth module"
principle	§N	Constitution	"Simple heuristics over complex ML"
requirement	RF-*	PRD	"Marketing website with craftsman tone"
guardrail	GR-*	Guardrails	"MUST: No vanity metrics as goals"
skill	/name	SKILL.md files	/rai-story-plan — decompose into tasks
story	S*.*	Work tracking	S8.6: Docs Getting Started
epic	E*	Epic scopes	E8: Website v1 + Docs
component	comp-*	Discovery scan	SessionManager class
module	mod-*	Discovery analysis	mod-memory — memory subsystem
decision	ADR-*	Architecture decisions	ADR-019: Unified context graph
outcome	OUT-*	Vision outcomes	"Deliver zero-config onboarding"
project	proj-*	Project registry	proj-raise-commons
term	term-*	Domain glossary	"Knowledge Cartridge"
architecture	arch-*	Architecture docs	"Port/adapter pattern"
bounded_context	bc-*	Domain boundaries	bc-core — core domain
layer	layer-*	Architecture layers	layer-domain
mission	mission-*	Mission tracking	"Framework Extensibility"
release	release-*	Release tracking	release-3.1.0
artifact	artifact-*	Governance artifacts	Design doc, ADR
document	doc-*	Documentation	Referenced documents
symbol	sym-*	Code symbols	Function, class, method

Custom types can be registered by subclassing GraphNode with a node_type parameter.

Edge Types

Edges express how concepts relate. RaiSE defines 12 core edge types:

Edge	Meaning	Example
learned_from	Pattern came from this session	PAT-042 → SES-015
governed_by	Requirement implements a principle	RF-01 → §2
implements	Story implements a requirement	S8.6 → RF-05
part_of	Story belongs to an epic	S8.6 → E8
depends_on	Module depends on another	mod-session → mod-memory
belongs_to	Module belongs to a domain	mod-memory → bc-core
constrained_by	Domain is constrained by a guardrail	bc-core → GR-015
applies_to	Pattern applies to a skill	PAT-001 → /rai-story-implement
needs_context	Node requires context from another	skill → pattern
related_to	General association between nodes	concept → concept
in_layer	Component belongs to architecture layer	mod-session → layer-domain
learned_during	Knowledge captured during work	term → story

The type field on GraphEdge is also an open string — custom edge types are valid.

Building the Graph

rai graph build

This merges all sources: 1. Governance: principles, requirements, guardrails from governance/ 2. Memory: patterns, calibration, sessions from .raise/rai/memory/ 3. Work: epic and story scopes from work/epics/ 4. Skills: metadata from .claude/skills/*/SKILL.md 5. Components: discovered code from work/discovery/ 6. Documents: freeform markdown you point it at — see below

The default Community output is stored in SQLite (~/.rai/raise.db), isolated by project ID.

Indexing Documents

Sources 1–5 are discovered by convention. Your prose is not: SOPs, ADRs, RFCs, research notes and work scopes live wherever your team put them, so the graph indexes only the globs you declare in graph.document_sources.

This is opt-in and empty by default. A project that never sets it gets zero document nodes — rai graph query will find your code and your patterns, but nothing you wrote in markdown. rai graph build prints a hint when that happens:

hint: No documents indexed: 'graph.document_sources' is unset in .raise/manifest.yaml.

Configuration

Add a graph section to .raise/manifest.yaml. Patterns are globs relative to the project root; ** recurses.

graph:
  document_sources:
  - dev/sops/*.md            # standard operating procedures
  - dev/decisions/**/*.md    # ADRs
  - dev/rfcs/**/*.md
  - work/epics/*/scope.md    # what each epic set out to do
  - work/epics/*/design.md   # and how it was designed
  - docs/concepts/*.md

Then rebuild:

rai graph build

Start narrow. Every matched file is split into one node per ## section, so a broad pattern like work/**/*.md over a mature repo can add tens of thousands of nodes — slower builds and noisier retrieval. Point at the documents you would actually want an agent to quote back at you.

What you get

Behavior	Detail
Node type	document, id doc-<slugified-path>-<n> where n is the 0-based section ordinal — ids are opaque, do not construct them from a heading
Granularity	One node per ## section, so retrieval lands on the relevant part of a long document, not the whole file
Title	YAML frontmatter title, else the first # H1, else the filename
doc_type	Frontmatter doc_type, else inferred from the path (sops/ → sop, rfcs/ → rfc, research/ → research, proposals/ → proposal)
Tags	Frontmatter tags (list or comma-separated string)

Query them like any other node:

rai graph query "rollback procedure" --types document

If a pattern matches nothing, rai graph build says so rather than quietly indexing less than you asked for — a typo'd glob is not a silent zero.

Graph Staleness

The graph is a snapshot, not a live view. Once built, it does not know about commits that land afterward — rai session open runs an advisory freshness check every session to surface when that snapshot has drifted too far from the checkout it describes.

Freshness is evaluated on two independent signals, each with a warn and a critical tier:

Signal	warn (default)	critical (default)
Age since last build	7 days	14 days
Commits landed since last build	50 commits	100 commits

Either signal crossing its threshold is enough to trigger that tier — the graph does not need to be both old and far behind. The check never blocks rai session open: both tiers surface as an advisory warn, with the tier name and a rebuild hint carried in the check's data so the developer can decide whether to run rai graph build before relying on graph-backed reviews or patterns this session.

Configuration

Tune the thresholds per project under graph.staleness in .raise/manifest.yaml. Any key you omit falls back to its default — partial overrides are safe:

graph:
  staleness:
    warn_days: 5
    warn_commits: 20
    critical_days: 10
    critical_commits: 50

A high-velocity team tightens these to catch drift sooner; a slower-moving project can loosen them to reduce noise. The same thresholds also drive rai doctor's project-graph-age / project-graph-commits checks — one configuration, both surfaces.

Querying the Graph

Keyword Search

Find concepts by content:

rai graph query "testing patterns"

Concept Lookup

Find a specific concept by ID:

rai graph query "PAT-001" --strategy concept_lookup

Module Context

Get the full architectural context for a module — its domain, layer, constraints, and dependencies:

rai graph context mod-memory

This returns: - Bounded context: which domain the module belongs to - Layer: its position in the architecture (leaf, domain, integration, orchestration) - Constraints: applicable guardrails (MUST and SHOULD) - Dependencies: what it depends on and what depends on it

Validation

Check the graph for structural issues:

rai graph validate

This detects cycles in dependency relationships, invalid edge types, and dangling references.

Why a Graph

The graph structure enables contextual queries — not just "find this keyword" but "show me everything related to this module, including the rules that constrain it and the patterns learned while building it."

When your AI partner runs rai session start --context, the CLI assembles a context bundle by traversing this graph. The result is a compressed view of everything relevant to your current work — not a dump of all files, but a curated selection of the most important nodes and their relationships.

Further Reading

• Memory — how patterns, calibration, and sessions feed into the graph
• Knowledge Cartridges — distributable knowledge packages that load into the graph
• Governance — how governance rules flow into the graph
• Graph CLI — build, query, and validate the graph