Skip to Content
ConfigurationKnowledge Graph

Knowledge Graph (knowledge_graph)

The Project Knowledge Graph gives Navigator one interface to query everything it knows — tasks, SOPs, system docs, and experiential memories — plus a way to persist patterns, pitfalls, decisions, and learnings across sessions. The graph lives in .agent/knowledge/graph.json and loads on query (~1–2k tokens).

Config block

In .agent/.nav-config.json:

{
  "knowledge_graph": {
    "enabled": true,
    "auto_capture_corrections": true,
    "auto_capture_decisions": true,
    "auto_surface_relevant": true,
    "max_session_memories": 5,
    "confidence_decay_rate": 0.01,
    "staleness_threshold_days": 90,
    "git_tracked": true
  }
}

Keys

  • enabled (default true) — master switch for the knowledge graph.
  • auto_capture_corrections (default true) — convert nav-profile corrections into memories.
  • auto_capture_decisions (default true) — capture task decisions as memories.
  • auto_surface_relevant (default true) — surface relevant memories at session start.
  • max_session_memories (default 5) — cap on memories surfaced per session (token budget).
  • confidence_decay_rate (default 0.01) — confidence drop per week, applied only by the manual --action decay command, not automatically on session start.
  • staleness_threshold_days (default 90) — age after which a memory is flagged stale; used only by the manual --action stale command.
  • git_tracked (default true) — commit the graph so the team shares the same knowledge.

confidence_decay_rate and staleness_threshold_days are not wired to any hook. Decaying a git-tracked file every session would create churn, so run decay and staleness checks manually when curating the graph.

Memory types

TypeMeaningExample
Pattern”We use X for Y""JWT tokens for stateless auth”
Pitfall”Watch out for X""Auth changes break session tests”
Decision”We chose X because Y""JWT over sessions for scaling”
Learning”X usually means Y""This error usually indicates Z”

Capturing memories

"Remember this pattern: we use X for Y"
"Remember this pitfall: watch out for X when..."
"Remember we decided to use X because..."

Explicit captures start at 0.9 confidence, correction-derived memories at 0.8. Each use boosts confidence (+5%, capped at +25%); the manual decay command lowers it over time. Memories above 0.7 are reliable; below 0.3 are pruning candidates.

Token budget

ComponentTokensWhen
graph.json (50 nodes)~1000On query
graph.json (200 nodes)~2000On query
Memory summaries (5)~500On session start
Full memory detail~500 eachOn request

Session overhead is roughly 1.3k tokens. Actual graph reads are instrumented with OpenTelemetry — run /nav:stats to see your own numbers.

Initialization

First time, build the graph from existing docs:

"Initialize knowledge graph"

This scans .agent/ (tasks, SOPs, system docs, markers), extracts concepts and relationships, and writes .agent/knowledge/graph.json.

Example

User: "What do we know about auth?"

Knowledge Graph: "auth"

TASKS (2)
  - TASK-29: Theory of Mind (completed)
  - TASK-12: V3 Skills-Only (completed)

MEMORIES (2)
  - PITFALL: "Auth changes break session tests" (90%)
  - DECISION: "JWT over sessions for scaling" (95%)

SOPs (1)
  - DEV-003: Autonomous Completion

Load details: "Read TASK-29" or "Show auth pitfalls"

(example output)

Reply ModesCode Simplification