Document Knowledge Graph

Document knowledge graph

Language: English · 简体中文

The document knowledge graph—also called the memory graph—connects current Wiki Pages and immutable Sources. It answers structural questions that lexical search cannot answer directly: what cites this evidence, which Pages are linked, whether one concept reaches another, and what may be affected by a dependency change.

Authority and projection

SQLite remains the canonical store. The graph is a rebuildable projection of current documents and relationships; it is never a second source of truth.

LWC projects:

• one node for every current Page (page:<slug>);
• one node for every current Source (source:<id>);
• LINKS_TO edges extracted from [[wiki-links]];
• CITES edges from Page citations;
• explicit, audited semantic relations.

Old Source revisions remain immutable in SQLite. The graph follows the current tracked-path head and current Page bodies.

When to use it

Use the document graph for:

• unknown topology or relationship discovery;
• immediate incoming or outgoing neighbors;
• a shortest typed path between two nodes;
• reverse dependency impact;
• structurally related Page ranking;
• support, contradiction, refinement, supersession, causality, or dependency claims that require an explicit audit trail.

Use search, page show, or source show for a direct lookup. Graph traversal adds no value when one known document already answers the question.

Enable one engine

Graph storage is disabled by default. Enabling or switching an engine changes project configuration and projection state, so an Agent must obtain consent first.

Grafeo is the embedded default recommendation:

lwc --scope project config set --graph grafeo
lwc --scope project work watch <work-id>
lwc --scope project graph status
lwc --scope project graph verify

Use surrealdb only when project policy has selected it:

lwc --scope project config set --graph surrealdb

The configuration response may return a Work. Completion means that Work reached succeeded and graph verify returned ok=true; queued or running is not completion.

Never switch or disable engines while graph Work is active. Do not copy, edit, or delete LWC-owned graph sidecars.

Bounded traversal

Start with the smallest operation that answers the question:

lwc graph overview --limit 10
lwc graph node page:projection-policy
lwc graph neighbors page:projection-policy --direction outgoing --limit 100
lwc graph path page:implementation page:policy --max-depth 6 --limit 200
lwc graph explore page:policy --direction both --depth 2 --limit 100

• overview summarizes counts and hubs.
• node resolves one identifier and reports bounded degree metadata.
• neighbors returns immediate typed neighbors.
• path explains a shortest typed route.
• explore traverses a bounded neighborhood; omit the identifier only for a representative macro view.

Use repeatable --edge-type filters when only specific relationships matter. Keep limits and depth explicit for automation.

Related Pages

lwc graph related customer-membership --limit 20

related ranks Pages only when structural evidence exists. It combines bidirectional Wiki links, shared Source citations, and Adamic–Adar common-neighbor evidence; Page-kind affinity only refines those candidates. The response exposes each signal so an Agent can explain the ranking.

This is structural relevance, not semantic truth. Open the returned Page and inspect its evidence before relying on a claim.

Impact analysis

lwc graph impact page:policy --max-depth 4 --limit 100

impact walks reverse dependencies and classifies affected nodes for hard action or review. Treat it as a bounded change-review aid, not proof that every returned node must change.

Explicit semantic relations

Automatic edges represent only citations and Wiki links. Strong claims must be written explicitly using one supported type:

• SUPPORTS
• CONTRADICTS
• REFINES
• SUPERSEDES
• CAUSES
• DEPENDS_ON

Create or replace one relation:

lwc graph relation set page:implementation DEPENDS_ON page:policy \
  --provenance source-grounded \
  --source 12 \
  --reason "Source 12 states the required policy" \
  --confidence 0.95

Inspect and retract it:

lwc graph relation list --from page:implementation --limit 100
lwc graph relation retract page:implementation DEPENDS_ON page:policy \
  --reason "The dependency was superseded"

Every explicit relation requires concise provenance, a reason, and confidence. A source-grounded relation must cite every supporting Source ID. Reasons are durable content: never place secrets or private reasoning in them.

Projection lifecycle

Page and Source mutations queue document-granular Work when the graph is enabled. Follow the returned Work rather than assuming the write command completed projection:

lwc work status <work-id>
lwc work watch <work-id>

Canonical search and reads remain available while projection is pending or failed. If verification reports missing, mismatched, or stale documents, repair through supported configuration, Work, checkpoint, or changeset recovery flows; never modify the sidecar directly.

Changesets use isolated draft Work and graph state. A committed changeset projects live documents, while discard removes only that draft's derived state.

Completion evidence

The document graph is ready when:

• configuration reports the intended engine and scope;
• every relevant Work reached succeeded;
• graph status reports the expected current documents;
• graph verify returns ok=true with no missing, mismatched, or stale entries;
• explicit relations have supported types and complete audit metadata;
• traversal used bounded depth, limits, and filters appropriate to the question.

Next: Code graph