knowing

Content-addressed graph artifact for software systems. Identity is content, so incremental updates are structural.

What knowing Is

Git already solved the hard problems for files. Content-addressed blobs. Merkle trees. Incremental updates. History and integrity as structural consequences of the identity model, not features bolted on after the fact. It works because identity is content: change a file, get a new hash, only the changed path needs recomputation.

knowing applies the same model to code relationships:

The hard problems (staleness, history, integrity, incremental updates) are structural consequences of choosing content-addressing. knowing watches .git/HEAD and ref changes, detects changed files, invalidates their hashes, re-extracts only affected edges, and computes a new snapshot root. Staleness is structurally detectable and recovery is bounded to the changed files, not a full re-index.

On top of this foundation, knowing fuses static analysis, infrastructure declarations, SCIP indexes, and OpenTelemetry runtime traces into one graph. Every edge carries provenance and confidence. Agents can ask not just "where is this symbol?" but "what depends on it, how do we know, how confident are we, and what changed since the last snapshot?"

Use knowing when code search is too shallow, LSP is too workspace-local, and dependency graphs stop at package boundaries.

What It Answers

For coding agents:

• "I am changing this function signature. Which callers, tests, routes, and repos are in the blast radius?"
• "Give me the most relevant context for this task in 5,000 tokens instead of making me grep the repo."
• "Which tests should run for these changed files?"

For platform and runtime teams:

• "Is this route actually used in production, or only declared in code?"
• "What did the service graph look like at the snapshot we deployed on Tuesday?"
• "Which runtime-observed paths disagree with static analysis?"

For security and compliance:

• "Prove this graph was derived from these source commits."
• "Show every service that touches this symbol, route, table, queue, or proto message."
• "What relationships were added or removed between two audit points?"

Why It Is Different

Most code-intelligence tools answer one slice of the problem:

knowing's unit of record is the relationship itself: source -edge_type-> target, with confidence and provenance. The graph is versioned like source code, so relationship history is a first-class artifact instead of a regenerated report.

Proof Points

The repository includes benchmark harnesses that regenerate their own findings from the live codebase.

Run the suites:

GOWORK=off go test ./bench/... -timeout 5m

See bench/README.md for methodology, design principles, and caveats.

Quick Start

Install:

brew install blackwell-systems/tap/knowing

# Or:
go install github.com/blackwell-systems/knowing/cmd/knowing@latest
npm install -g @blackwell-systems/knowing
pip install knowing

Index and query a repository:

# Build the graph. The default path uses fast tree-sitter extraction plus LSP enrichment.
knowing index -url github.com/org/repo ./path/to/repo

# Search symbols by qualified-name prefix.
knowing query "MyService"

# Ask for graph-ranked context for an agent task.
knowing context -task "refactor auth middleware" -format gcf

# Find affected tests for changed files.
knowing test-scope -files internal/auth/session.go,internal/auth/middleware.go

# Compare two graph snapshots.
knowing diff <old-snapshot> <new-snapshot>

Run continuously:

# Watches git changes, re-indexes incrementally, and serves MCP over HTTP.
knowing serve -addr :8100 ./path/to/repo

Serve MCP over stdio for local agents:

knowing mcp -db knowing.db

Agent Integration

Add knowing to .mcp.json:

{
  "mcpServers": {
    "knowing": {
      "command": "knowing",
      "args": ["mcp", "-db", "/path/to/knowing.db"],
      "transport": "stdio"
    }
  }
}

For HTTP transport:

{
  "mcpServers": {
    "knowing": {
      "url": "http://localhost:8100",
      "transport": "streamable-http"
    }
  }
}

Claude Code hooks are included for automatic context injection on session start, edits, compaction, task stop, and subagent launch. Start with the low-risk hooks in hooks/README.md, then enable edit/subagent hooks if the benchmark profile matches your workflow.

How It Works

┌──────────────────────────────────────────────────────────┐
│                    knowing daemon                       │
├──────────────┬───────────────────┬───────────────────────┤
│   Indexer    │   Graph Store     │      MCP Server       │
│              │                   │                       │
│ 17 extractors│ Content-addressed │ 22 tools + 3 prompts  │
│ tree-sitter  │ SQLite + Merkle   │ stdio / HTTP          │
│ gopls + SCIP │ Snapshot chain    │ GCF / GCB / JSON      │
│ OTel traces  │ Edge events       │                       │
└──────────────┴───────────────────┴───────────────────────┘

The pipeline has two planes:

• Execution plane: indexes repos, extracts symbols and relationships, ingests traces, stores snapshots.
• Intelligence plane: computes blast radius, semantic diffs, context packs, runtime traffic, test scope, feedback, and graph communities from the stored artifact.

The artifact boundary matters: intelligence features read the graph and produce derived results, but they do not mutate source graph facts. A bad ranking can produce a bad recommendation; it cannot corrupt the graph.

Capabilities

Languages And Formats

All extractors run through multi-dispatch: every matching extractor fires per file, results are merged. Tree-sitter extractors produce edges at confidence 0.7 (ast_inferred); go/packages and SCIP produce edges at 0.95-1.0 (ast_resolved, scip_resolved).

Edge Types

knowing records static, infrastructure, and runtime relationships, including:

• calls, imports, implements, references, handles_route
• depends_on, deploys, exposes, configures
• publishes, subscribes, connects_to
• runtime_calls, runtime_rpc, runtime_produces, runtime_consumes

See docs/edge-types.md for exact semantics, producers, confidence tiers, and traversal behavior.

MCP Tools

The MCP server exposes 22 tools across indexing, graph queries, analysis, runtime, context, feedback, and discovery:

MCP prompts: refactor_safely, review_pr, investigate_dead_code.

Full reference: docs/MCP-TOOLS.md.

Wire Formats

knowing serves responses in three encodings, selected per request:

GCF replaces JSON's repeated keys (qualified_name, provenance, components) with a header line followed by |-separated positional fields. Edge references use local IDs ($1 -> $3) instead of repeating full qualified names. The result is parseable by LLMs (line-oriented, no ambiguous nesting) while fitting 5x more graph context into the same token budget.

knowing context -task "refactor auth" -format gcf   # LLM-optimized
knowing context -task "refactor auth" -format json  # human-readable

Session statefulness: when the same symbols appear across multiple MCP calls in a session, GCF deduplicates them (47% reduction on repeated symbols). The wire format is stateful per-session, stateless per-request.

Round-trip integrity is verified: encode -> decode -> re-encode produces identical output for all codecs.

Content Addressing

The identity model is described in the opening section. Two additional properties worth noting:

• Caching: query results keyed to a snapshot hash remain valid forever for that snapshot. The hash is the cache key.
• Edge events: relationship changes are explicit (added/removed per edge per commit), not inferred from full graph scans.

For the full storage model and hash construction, see docs/architecture.md.

Current Boundaries

knowing is implemented, benchmarked, and usable, but it is still explicit about where precision depends on available data:

• Static call-graph impact follows calls edges; other edge types are used for context and relationship awareness, not every blast-radius traversal.
• Runtime tools require OpenTelemetry trace ingestion and route-symbol mappings; without trace data they have no runtime observations to report.
• LSP enrichment currently centers on Go through gopls; other languages rely on tree-sitter/static extractors and SCIP where available.
• Some planned work remains: MCP resources, traversal caching, richer ownership routing, and federated graphs.

See docs/FEATURES.md for the implementation inventory and known gaps, and docs/roadmap.md for planned work.

Documentation

License

MIT