knowing

Intelligence versioning system. Content-addressed graph where every relationship is tracked, scored, snapshotted, and retrievable. Designed to make AI agents trust, diff, cache, and reuse structural context cheaply.

What knowing Is

Git versions files. knowing versions the understanding of code.

Files are the wrong unit for AI agents. An agent doesn't need to know "this file changed." It needs to know "this change breaks 14 callers, adds a new dependency path, and disagrees with what production traffic shows." That's intelligence, not source.

knowing is an intelligence versioning system: a content-addressed graph where every relationship between symbols is tracked, scored, and snapshotted. Each snapshot captures not just what the code looks like, but what it means: who calls what, how confident we are, what production observed, and what changed since last time.

The hard problems (staleness, history, integrity, incremental updates) are structural consequences of choosing content-addressing. knowing watches for changes, detects stale 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. Feedback from past queries compounds into the intelligence: the system learns which symbols matter for which tasks, and rankings improve with use.

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 intelligence is versioned, so you can ask "what did we understand about the service graph on Tuesday?" and get an answer, not "what did the files look like on Tuesday?"

knowing is the only code-intelligence tool where every node, edge, and snapshot is content-addressed (sha256). Other tools use auto-increment IDs, UUIDs, or ephemeral in-memory graphs that are regenerated from scratch each session. Content-addressing means staleness is structurally detectable (changed file = new hash = stale edges are known without scanning), snapshots are verifiable from a single Merkle root, and query results keyed to a snapshot hash are valid forever.

Snapshots are structured as hierarchical Merkle trees: repo root -> package roots -> edge-type roots -> edge leaves. This means "which packages changed?" is an O(packages) root comparison instead of an O(edges) full scan (benchmarked at 517x faster for 100K-edge graphs). "Did call edges change?" is a single root lookup. Subgraph cache keys are computed from package roots, so queries against unchanged code return cached results instantly. Intelligence diffs ("3 new cross-service calls appeared in internal/mcp, 2 routes went dead in cmd/, blast radius of AuthMiddleware grew 40%") are scoped to the packages that actually changed.

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

Register and index a repository:

# Register a repo in the roster and index it.
# Each repo gets its own database at ~/.knowing/repos/<safe-name>.db
# so community detection, RWR, HITS, and BM25 operate on isolated data.
knowing add ./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

# Explain why a symbol ranked where it did.
knowing why -task "refactor auth" -symbol "SessionHandler"

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

Watch for file changes (re-indexes on save):

# Lightweight file watcher. Re-indexes changed files on save, runs LSP enrichment.
knowing watch ./path/to/repo

Run continuously (full daemon with MCP server):

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

Manage the repo roster:

# List all registered repos
knowing list

# Remove a repo from the roster
knowing remove ./path/to/repo

Serve MCP over stdio for local agents:

knowing mcp

Check graph integrity:

knowing fsck

Agent Integration

Add knowing to .mcp.json:

{
  "mcpServers": {
    "knowing": {
      "command": "knowing",
      "args": ["mcp", "--watch"],
      "transport": "stdio"
    }
  }
}

The database is auto-resolved from the roster: defaultDB() looks up the current directory in the roster and returns the per-repo DB path (~/.knowing/repos/<safe-name>.db). No -db flag is needed. Override with -db /path/to/db or the KNOWING_DB environment variable if needed.

The --watch flag enables integrated file watching: the MCP server monitors the repository for changes and re-indexes automatically, so agents always query fresh graph data. Omit --watch if you manage indexing separately.

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          │
│              │                        │                          │
│ 25 extractors│ Content-addressed      │ 23 tools + 8 resources   │
│ tree-sitter  │ SQLite + Merkle tree   │ stdio / HTTP             │
│ LSP + SCIP   │ Hierarchical snapshots │ GCF / GCB / JSON         │
│ OTel traces  │ Subgraph cache (93x)   │ PackRoot dedup (99%)     │
│              │ Graph notes (metadata)  │                          │
│              │ Community detection     │                          │
└──────────────┴────────────────────────┴──────────────────────────┘

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/architecture/edge-types.md for exact semantics, producers, confidence tiers, and traversal behavior.

MCP Tools

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

MCP prompts: refactor_safely, review_pr, investigate_dead_code.

MCP Resources

8 read-only resources let agents orient to the graph without spending a tool call:

Full reference: docs/guide/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 and Caching

The identity model (described in the opening section) provides three layers of caching that build on each other:

Additional structural properties:

• Edge events: relationship changes are explicit (added/removed per edge per commit), not inferred from full graph scans.
• Incremental community detection: after re-index, only nodes in changed packages are allowed to move. Unchanged communities are frozen. 6.9x faster (Louvain) on single-package edits.
• knowing fsck: verifies edge referential integrity, hash recomputation, and snapshot chain continuity from a single Merkle root. 98ms on the live graph.

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

Current Boundaries

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

• Breaking hash change (v0.3.0): Hash domain prefixes (node\0, edge\0, snapshot\0, merkle\0) were added to all hash computations. Databases built before v0.3.0 must be re-indexed (knowing add <path> or knowing index <path>). Run knowing fsck after re-indexing to verify integrity.

• 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 supports Go (gopls), TypeScript (tsserver), Python (pyright), Rust (rust-analyzer), Java (jdtls), and C# (OmniSharp). Servers are auto-detected from project markers and PATH. Languages without a detected server fall back to tree-sitter extraction and SCIP where available.

• Phase 3 incremental recompute is partially shipped (community persistence, context pack persistence, incremental detection). Scoped FTS rebuild, semantic change classification, and federated graphs are planned.

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

Documentation

License

MIT