Query project knowledge graph. Search across tasks, SOPs, memories, and concepts. Use when user asks "what do we know about X?", "show everything related to X", or "remember this pattern/pitfall/decision".
Instrucciones de origen · Vista previa de solo lectura
name
nav-graph
description
Query project knowledge graph. Search across tasks, SOPs, memories, and concepts. Use when user asks "what do we know about X?", "show everything related to X", or "remember this pattern/pitfall/decision".
allowed-tools
Read, Write, Edit, Bash
version
1.0.0
Navigator Knowledge Graph Skill
Query and manage the unified project knowledge graph. Surfaces relevant knowledge from tasks, SOPs, system docs, and experiential memories.
Why This Exists
Navigator v6.0.0 introduces the Project Knowledge Graph:
Unified search: Query across all knowledge types with one interface
Write guarantees (v6.17.0+): the backing .md is written BEFORE the
graph node and failures fail loudly (no more path-points-at-nothing nodes);
a failed graph save rolls the file back. Concepts are validated against the
graph's concept vocabulary — an unknown concept rejects the write and lists
the valid vocabulary. Pass --allow-new-concept to register genuinely new
concepts instead. Graphs without a curated vocabulary skip validation.
Optionally create detailed memory file:
# Pitfall: Auth Changes Break Session Tests## Summary
Auth changes often break session tests due to...
## Context
Discovered during TASK-XX when...
## Recommended Approach
When modifying auth, always run...
## Related- TASK-12: V3 Skills-Only
- SOP: autonomous-completion
Confirm capture:
Memory captured: mem-001
Type: Pitfall
Summary: "auth changes often break session tests"
Concepts: auth, testing
Confidence: 90%
This will be surfaced when working on auth or testing topics.
Knowledge Graph Initialized
Scanned:
- Tasks: 35
- SOPs: 12
- System docs: 3
- Markers: 8
Extracted:
- Concepts: 15
- Relationships: 47
Graph saved to .agent/knowledge/graph.json
Query with: "What do we know about [topic]?"
Rebuild safety (v6.17.0+): re-running the builder over an existing graph
PRESERVES the memories and files buckets and their edges — memories carry
graph-only fields no scan can reconstruct, and rebuilds used to wipe them
silently. Pass --no-preserve-memories for an intentional from-scratch
rebuild.
The navigator-research agent emits a structured research_findings JSON block alongside its markdown summary. After the agent returns, ingest those findings as graph memories via research_to_graph.py:
PLUGIN_DIR="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/plugins/cache/navigator-marketplace/navigator}"
[ -d "$PLUGIN_DIR" ] || PLUGIN_DIR="$HOME/.claude/plugins/marketplaces/navigator-marketplace"# Save the JSON block from the agent output to a file (or pipe via stdin)
python3 "$PLUGIN_DIR/skills/nav-graph/functions/research_to_graph.py" findings.json
# Or from stdincat findings.json | python3 "$PLUGIN_DIR/skills/nav-graph/functions/research_to_graph.py" -
# Validate without writing
python3 "$PLUGIN_DIR/skills/nav-graph/functions/research_to_graph.py" findings.json --dry-run
Trigger phrases:
"Ingest research findings"
"Save these findings to the graph"
(Automatic, when a navigator-research invocation completes — orchestrator may auto-ingest)
Defaults:
Confidence: 0.7 (lower than corrections/explicit captures — research is inference)
Note: confidence_decay_rate and staleness_threshold_days are consumed
only by the manual graph_maintenance commands (--action decay /
--action stale). They are not applied automatically on session start —
decaying a git-tracked file every session would create constant churn. Run
decay/staleness manually when curating the graph.
Knowledge Graph Health Check
========================================
Total Nodes: 133
Total Edges: 706
Memories: 37 (37 high confidence)
Tasks: 38
Concepts: 16
Orphan Nodes: 0
Duplicate Edges: 0
Dangling Edges: 0
Confidence Out-of-Range: 0
Health Score: 100/100
No integrity issues detected!
Advisory (not scored):
- 8 potential memory conflicts (heuristic, advisory)
- 3 stale memories (not validated in 90+ days)
Duplicate Edges, Dangling Edges, and Confidence Out-of-Range are the
integrity gate — all three should read 0 on a healthy graph. If they don't,
run --action repair (below).
v6.17.0 adds disk-vs-graph checks: Broken File Links (node references a
file that doesn't exist) and Unindexed Memory Files (files on disk with no
node — the drift class a 2026-07 audit found at 52/84 in a consumer repo)
are score-affecting; concept-vocabulary drift and archived resolved/ files
without nodes are advisory. Pass --root <project-root> when running from
another directory.
Reconcile Disk vs Graph (v6.17.0+)
Report drift between memory files on disk and graph nodes; --execute
registers unindexed files (type from parent dir, resolved/ parent →
resolved: true, frontmatter/heading parsing with conservative fallbacks —
0.5 confidence when unknown). Broken-link nodes are never auto-deleted and
concept refs are never rewritten — those two are report-and-hint only:
When a memory stops being true (bug fixed, decision reversed, guidance
codified elsewhere), do NOT delete it — resolve it. The node gets
resolved: true (+ superseded_by and a supersedes edge when a newer
memory replaces it) and the backing file moves to the sibling resolved/
directory. Resolved memories are excluded from session-start surfacing and
task-doc recall, skipped by stale/decay sweeps, and flagged [resolved] in
query output:
Deterministic relevance ranking used by the SessionStart hook and nav-task
Step 2.5 — also useful standalone:
# Explicit concepts (markdown for task docs, compact for terse output)
python3 "$PLUGIN_DIR/skills/nav-graph/functions/memory_recall.py" \
--concepts "auth,testing" --format markdown --limit 5
# Auto mode: concepts from open task nodes + active context marker
python3 "$PLUGIN_DIR/skills/nav-graph/functions/memory_recall.py" \
--auto --agent-dir .agent --limit 5
Scoring: concept overlap (alias-resolved), then confidence; resolved
memories excluded; silent (exit 0, no output) when nothing matches.
Compatible with consumer graphs that use file: keys and lack a
concept_index.
Repair Integrity Defects
Idempotently dedupe (from, to, type) edge rows, drop edges that reference a
missing node id, and normalize out-of-range memory confidences (a value like
90.0 is treated as 90% → 0.9). Safe to re-run:
Find and optionally remove low-confidence memories:
PLUGIN_DIR="${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/plugins/cache/navigator-marketplace/navigator}"
[ -d "$PLUGIN_DIR" ] || PLUGIN_DIR="$HOME/.claude/plugins/marketplaces/navigator-marketplace"# Preview what would be removed
python3 "$PLUGIN_DIR/skills/nav-graph/functions/graph_maintenance.py" --action prune --threshold 0.3 --dry-run
# Actually remove (use with caution)
python3 "$PLUGIN_DIR/skills/nav-graph/functions/graph_maintenance.py" --action prune --threshold 0.3 --execute
Apply Decay (experimental, manual-only)
Reduce confidence based on time since each memory's last decay. Idempotent —
running it twice on the same day is a no-op (each memory tracks last_decayed).
The rate defaults to knowledge_graph.confidence_decay_rate when --decay-rate
is omitted. This is not wired to any hook; run it manually when curating:
