Skip to Content
ConceptsKnowledge Graph

Knowledge Graph

One interface to query everything Navigator knows about a project, plus experiential memory that persists across sessions.

The Problem: Siloed Knowledge

Before v6.0.0, project knowledge was scattered with no way to ask a single question across it:

  • Tasks lived in .agent/tasks/
  • SOPs lived in .agent/sops/
  • System docs lived in .agent/system/
  • Markers captured session state separately

Each store was useful on its own, but there was no way to ask “what do we know about auth?” and get an answer that spanned all of them. Knowledge also evaporated between sessions — a pitfall you hit on Tuesday was forgotten by Thursday.

The Solution: Unified Search + Memory

The Knowledge Graph adds two things:

  1. Unified search — one query interface across tasks, SOPs, system docs, and markers.
  2. Experiential memory — durable observations that survive across sessions and surface when relevant.

The graph lives in .agent/knowledge/graph.json and is loaded only on query, keeping it out of the way until you ask.

The Four Memory Types

What separates the types is the kind of claim each one makes:

  • Pattern — a reusable approach. “We use JWT tokens for stateless auth.”
  • Pitfall — a gotcha or failure mode. “Auth changes often break session tests.”
  • Decision — a choice plus its rationale. “We chose JWT over sessions because it scales statelessly.” Since v7.1.0 a decision may also carry the contradiction it resolved.
  • Learning — a project-specific interpretation. “This timeout error usually means the migration didn’t run.”

A pattern tells you what to do; a pitfall tells you what to avoid; a decision records why something is the way it is; a learning translates a signal into its likely cause.

Capturing and Surfacing

Capture happens two ways:

  • Explicitly — “Remember this pattern: …”, “Remember this pitfall: …”, “Remember we decided … because …”
  • Automatically — when enabled, corrections from nav-profile and task decisions are converted into memories without a prompt. As of v7.0.0, task graph sync runs as dispatcher ops on the TaskCreated/TaskCompleted events.

Surfacing happens at session start: relevant memories for the current context are loaded automatically (capped so they stay within a small token budget), so prior insight reaches you before you repeat a mistake.

Contradictions

TRIZ — the inventive-problem method built from ~200,000 patents — starts from one observation: real design problems have a contradiction at the center. Improving A worsens B. Compromises split the difference; inventions resolve it, usually by separating the two demands in time, in space, by condition, or by level.

Since v7.1.0 a Decision memory can record exactly that:

**Contradiction**: clean codebase vs rollback safety
**Separation**: time
**Principle**: temporary re-export shims for one major, delete in v8

The fields are optional; untagged memories are unchanged. What they buy you is a new question the graph can answer — how did we resolve this shape of problem before? — via graph_manager.py --action contradictions --filter "rollback". Your project’s decisions become the patent base.

Two places consume it. The intent brief asks for a contradiction (usually none) and looks up prior resolutions before filling Approach. On substantial tasks, nav-triz (v7.2.0) turns the prior resolutions plus three principle prompts into three competing candidates with named downsides, then recommends one.

Web research feeds the same graph: after a nav-deep-research (v7.3.0) run passes its ship gate, every typed Key findings bullet of the report becomes a memory whose evidence is the cited source URL. Since v7.5.1 each URL carries the fetch date and a content-hash prefix, so the memory records not just where a claim came from but which version of the page supported it. The fetched page bodies stay out of the repository as third-party text; the provenance travels with the memory.

Concepts and Relationships

When tasks, SOPs, and memories enter the graph, Navigator auto-extracts concepts (e.g. auth, testing, architecture) and links every item that touches them. That indexing is what makes cross-cutting queries possible — and it powers relationship traversal: from any node you can walk outward to find what else is related (“What’s related to TASK-29?”).

Confidence and Staleness

Memories are not permanent truths — they carry a confidence score and an age:

  • Explicit captures start higher than inferred ones; repeated use boosts confidence, while time without validation lets it decay.
  • Memories that go long enough without revalidation become stale and are candidates to age out, so the graph reflects what’s still true rather than accumulating cruft.

Treat this as a mental model: the graph self-curates toward reliable, current knowledge. The exact decay rate, staleness window, and pruning thresholds are knobs — see the configuration page for the values and the manual maintenance commands that apply them.

Example Query

You: What do we know about testing?

Knowledge Graph: "testing"

TASKS (3)
  - TASK-30: Task Verification Enhancement (completed)
  - TASK-17: Visual Regression Integration (completed)
  - TASK-11: Project Skills Generation (completed)

MEMORIES (2)
  - PITFALL: "Auth changes break session tests" (90%)
  - PATTERN: "Always run unit tests before integration" (85%)

SOPs (1)
  - visual-regression-setup

Load details: "Read TASK-30" or "Show testing memories"

Results group by knowledge type so you can scan and then load only the item you need. Token figures elsewhere in the docs are illustrative, not guarantees — the point is that one query reaches everything, and you pull detail on demand.

Loop ModeCodebase Research