v0.2.0 · MIT

know

software product development knowledge graph

Structured context for AI-driven software product development. Know turns product decisions into dependency graphs that LLMs can traverse — linking what you’re building and why to how it gets implemented.

install
$ npm install -g know-cli copy
agent evaluation
> Fetch AGENTS.md and follow the briefing — evaluate know-cli for this project and how I work with AI. copy

Why graphs over spec files?

Spec files are fine for humans. For AI agents, they’re token overhead — brittle snapshots that bloat, duplicate, and rot.

Spec files

Static, fragile, expensive

  • Information scattered across files
  • Relationships implicit in prose
  • Duplicated context burns tokens
  • Drift from reality over time
  • No queryable structure for agents
Spec graphs

Queryable, connected, current

  • Single source of truth per node
  • Relationships are first-class edges
  • Generate specs on demand from graph
  • Traverse from intent to implementation
  • Deterministic feature completion state

Dual graph system

Two graphs, one truth. The spec graph maps what users need. The code graph maps what exists. Cross-links connect intent to implementation. 

%%{init: {'theme': 'dark', 'themeVariables': {'primaryColor': '#171a28', 'primaryTextColor': '#cdd2e6', 'primaryBorderColor': '#2c3150', 'lineColor': '#4e5370', 'secondaryColor': '#0b0d14', 'tertiaryColor': '#10121c', 'edgeLabelBackground': '#10121c', 'clusterBkg': '#0b0d14', 'clusterBorder': '#222640', 'fontFamily': 'IBM Plex Mono, monospace', 'fontSize': '13px'}}}%%
flowchart TD
    subgraph spec ["spec-graph.json — product intent"]
        direction TD
        P["project"]:::project --> U["user"]:::user
        U --> O["objective"]:::objective
        O --> F["feature"]:::feature
    end

    subgraph code ["code-graph.json — codebase"]
        direction TD
        M["module"]:::cmod --> Pk["package"]:::cpkg
        M --> Cl["class"]:::ccls
        Cl --> Fn["function"]:::cfn
    end

    classDef project fill:#5c9eff18,stroke:#5c9eff60,color:#5c9eff
    classDef user fill:#66e0a018,stroke:#66e0a060,color:#66e0a0
    classDef objective fill:#ff8a5018,stroke:#ff8a5060,color:#ff8a50
    classDef feature fill:#40c8ff18,stroke:#40c8ff60,color:#40c8ff
    classDef cmod fill:#5c9eff18,stroke:#5c9eff60,color:#5c9eff
    classDef cpkg fill:#d580ff18,stroke:#d580ff60,color:#d580ff
    classDef ccls fill:#ffcc3318,stroke:#ffcc3360,color:#ffcc33
    classDef cfn fill:#5af5a018,stroke:#5af5a060,color:#5af5a0
      
// spec-graph.json
{
  "entities": {
    "feature": {
      "auth": {
        "name": "Authentication",
        "description": "User login system"
      }
    }
  },
  "graph": {
    "feature:auth": {
      "depends_on": [
        "action:login",
        "action:logout",
        "component:session"
      ]
    }
  },
  "references": {
    "implementation": {
      "auth": {
        "module": "module:auth",
        "graph": "code-graph.json"
      }
    }
  }
}

Heat memory

The spec graph knows what to build. The code graph knows what exists. Heat scores tell you what’s actually moving — five git-derived signals fused into a single composite score per file and method.

30
churn
Commits in last 90 days
25
recency
14-day half-life decay
15
complexity
Lines of code / span
15
centrality
Import fan-in + fan-out
15
ripple
Neighbor recency propagation
hot > 0.66 warm 0.33 – 0.66 cool < 0.33 know gen codemap src --heat
feature:auth ⟶ component:session ⟶ module:auth ⟶ ■ 0.82 hot

One traversal links intent to code with relevance.

heat output
{
  "path": "src/graph.py",
  "heat": {
    "score": 0.659,
    "label": "warm",
    "signals": {
      "churn": 0.520,  // 17 commits in 90d window
      "recency": 0.890,  // touched 2 days ago, 14d half-life
      "complexity": 0.740,  // 890 lines
      "centrality": 0.610,  // high fan-in from 8 importers
      "ripple": 0.380  // neighbors moderately active
    }
  },
  "functions": [
    { "name": "update_entity", "heat": { "score": 0.810, "label": "hot" } },
    { "name": "load_graph",    "heat": { "score": 0.210, "label": "cool" } }
  ]
}

Built for AI agents

Know gives agents structured project context without token-wasting repeated analysis. Query the graph, traverse dependencies, generate specs on demand.

◆

Query, don’t parse

Traverse from user intent to implementation in a single CLI call. know graph uses feature:auth returns the full dependency tree — no file scanning required.

◊

Generate, don’t store

Specs are produced from the graph when needed, always current. know gen feature-spec auth outputs a complete spec document from live graph state.

□

Structured build workflow

The /know:build slash command drives 7-phase feature development with XML task specs, checkpoints, and progress tracking.

⊞

Cross-boundary tracing

know gen trace feature:auth follows links across spec and code graphs. See which modules implement which features without manual mapping.

△

Validation as guardrails

know check validate enforces DAG structure, dependency rules, and completeness. Agents get immediate feedback when graph modifications break constraints.

◎

Gap detection

know check gap-summary identifies missing implementations, orphaned references, and incomplete dependency chains. Agents know exactly what’s left to build.

agent integration
# Initialize — sets up your project in one command:
#   slash commands  → .claude/commands/know/
#   know-tool skill → .claude/skills/know-tool/
#   graph config    → .ai/know/config/
#   initial graphs  → .ai/know/{spec,code}-graph.json
#   project context → .ai/know/project.md
#   protection hook → prevents direct graph file edits
#   CLAUDE.md       → injects <know-instructions> block
know init .

# Agent reads project context
know -g .ai/know/spec-graph.json list --type feature
know graph uses feature:auth
know gen feature-spec auth --format xml

# Agent modifies the graph
know add feature payment '{"name":"Payments","description":"..."}'
know link feature:payment action:checkout component:stripe
know check validate

# Agent generates specs from graph state
know gen spec feature:payment --format xml
know gen trace feature:payment

Slash commands

Claude Code slash commands wrap the CLI with guided, multi-phase workflows. Agents get interactive discovery, planning, building, and review.

Command What it does Phase
/know:plan QA-driven product discovery — builds spec-graph from conversation Discovery
/know:add Add features with 5-step interactive workflow + graph linking Discovery
/know:prepare Bootstrap existing codebase into both graphs with parallel agents Setup
/know:prebuild Validate specs align with graph before building Validation
/know:build 7-phase structured development: discover → explore → design → implement → integrate → test → review Execution
/know:change Structured change requests with requirement tracking Execution
/know:review Interactive QA walkthrough for end-user acceptance testing Review
/know:done Archive completed feature, update horizon, clean up artifacts Completion
/know:bug Track issues against features with automatic todo tracking Maintenance
/know:list Show features grouped by horizon with task progress Query
CLI essentials
# Query
know list --type feature        # list entities by type
know graph uses feature:auth     # dependency tree (down)
know graph used-by component:x   # reverse dependency (up)
know search "auth"               # fuzzy search

# Modify
know add feature auth '{"name":"Auth"}'
know link feature:auth action:login action:logout
know unlink feature:auth action:old

# Validate
know check validate              # full graph validation
know check health                # comprehensive report
know check gap-summary           # what's missing

# Generate
know gen feature-spec auth       # markdown spec from graph
know gen spec auth --format xml  # XML task spec
know gen trace feature:auth      # cross spec↔code boundary
know gen trace-matrix            # full traceability matrix

# Visualize
know viz tree                    # ASCII tree
know viz mermaid                 # diagram export
know viz d3                      # interactive D3 viz

People shipping with know

“I had to generate user flows for my product manager. I didn’t want to sit there with Playwright and personas. Know read my code, asked a few questions, and made great step-by-steps for each requirement.”
— AI Architect @ Startup
“Now Know is the backstop for Playwright.”
— AI Architect @ Startup
“My agents stop guessing during implementation. They Know.”
— AI Engineer @ Big Company

Pricing

Know is open source. MIT licensed. No tricks.

Personal
Free
forever
  • Full CLI
  • Both graphs
  • All slash commands
  • Heat scoring
  • Validation & generation
Install
Team
Free
forever
  • Everything in Personal
  • Shared spec graphs
  • Multi-agent workflows
  • Custom schemas
  • Code graph generation
Install
Enterprise
Free
forever
  • Everything in Team
  • It’s MIT licensed
  • Read the source
  • Seriously, it’s free

Want commercial support?

Start building with context

Install know-cli, run know init . in your project, and give your agents structured context that actually works.

View on GitHub npm package