Knowledge

knowledge indexes your code, cloud infrastructure, logs, and docs into cross-linked graphs and serves them over MCP: hybrid code search, call-graph traversal, structural AST search and replace, and a reasoning graph where hypotheses carry their evidence. Runs as a local MCP server; any LLM that speaks MCP works from the graph instead of rediscovering your system every session.

Collectors keep the index current. The LLM queries it and gets the pieces it asked for, sized to the question: a whole-file read bloats the context with text that is not the answer, and a fragment read leaves gaps. Indexed retrieval is how the graph raises accuracy and lowers token spend.

Skills and agents run an engineering workflow (brainstorm → ticket → plan → implement) over the same graphs, with researchers, planners, reviewers, and implementers reading and writing shared state. Thoughts, decisions, tickets, and plans persist across sessions, machines, and teammates. The graph makes the agent's work auditable.

See it work

Index a repo, then ask questions grep can't answer. Against this repository:

search({ "queries": ["bisect embedding batch on token overflow"],
         "repo": "knowledge-mcp" })

// internal/embed/voyage.go — Voyage embedder: batches texts under item
//   and token budgets, classifies errors, bisects token-overflow batches
// internal/embed/voyage.go:180 isBatchTokenOverflow — detects batch token
//   overflow by unwrapping LLMError causes

Each result is a graph node. Walk the call graph from any hit:

traverse({ "start": "internal/embed/voyage.go:voyageEmbedder.EmbedBinaryBatch",
           "graph": "code", "repo": "knowledge-mcp",
           "edge_types": ["CALLS"], "direction": "in" })

// EmbedBinary                                     internal/embed/voyage.go
// TestVoyageEmbedder_BisectsOnBatchTokenOverflow  internal/embed/voyage_test.go
// TestVoyageEmbedder_PacksByTokenBudget           internal/embed/voyage_test.go
// ...

Shape questions get structural answers. This matches the parsed syntax tree, so whitespace, comments, and token order don't matter:

ast({ "operation": "match", "language": "go", "pattern": "defer $X.Close()" })

// 65 matches across 1,560 files in 185ms: every deferred Close,
// through whitespace, comments, and receiver renames

The same engine rewrites. Give replace a capture template ("defer safeClose($X)") and it previews the unified diff without touching disk (dry-run is the default), then applies atomically; a rewrite that no longer parses is rejected, never written. A mechanical multi-file refactor is one tool call.

The retrieval economics from the intro are visible here. When the question is "what is in this file," the index answers without the file: file_symbols returns each symbol's name, signature, line range, and summary.

file_symbols({ "file_path": "internal/embed/voyage.go", "repo": "knowledge-mcp" })

The file is 246 lines. The context gets the symbol list, and the agent can fetch just the symbol it needs.

Reasoning persists the same way. The hypothesis recorded while that overflow was being debugged comes back in a later session with its evidence attached:

thoughts({ "operation": "recall", "query": "voyage batch overflow" })

// 1. Voyage rejects the whole batch on token overflow, not the one long
//    text — bound batches by estimated tokens and bisect on overflow
//    [validated] charges: +2 (bisection test green; overflow retries gone)

And from any node you can keep walking: to the decision that shaped the code, the ticket that shipped it, or the log stream where it failed.

What's in the graph

Code intelligence. Hybrid BM25 + semantic search over 31 tree-sitter-chunked languages, an indexed call graph, and structural AST search and replace: match the shapes regex can't express, then rewrite every site from a capture template, gated by a dry-run diff and a per-file re-parse. "Is there code that does this" gets a real answer, so an agent can check what exists before writing it again.

Reasoning with evidence. Hypotheses are first-class nodes; evidence attaches as weighted positive or negative charges, and propagation lets contradictory beliefs find equilibrium. "Why did we do it this way" has an answer months later. The graph also reads back on itself: query reflection modes include tensions, which lists pairs of recorded thoughts whose evidence points in opposite directions, and personality, blind_spots, and influence, which read the same thought graph from other angles. See Reasoning.

Workflow. Brainstorm → ticket → plan → implement, with every artifact in the graph and tickets synced to Linear in real time. One coordinator dispatches researchers, planners, reviewers, and implementers against shared state, so no single context has to hold everything, and a compaction or restart loses nothing the graph already holds. Jira, GitHub Issues, and Asana are on the roadmap. The full process model, with its routing and re-entry paths, is in Concepts.

Infrastructure and runtime. Collectors for cloud (AWS, GCP, Azure, Kubernetes), CI/CD, logs (CloudWatch, Loki, Elasticsearch, Stackdriver, K8s Events), web pages, and PDFs — each a graph, all cross-linked to code. An incident traces from log line to deploy to commit to the design decision behind it. The built-in families are not a closed set: custom_collector registers your own collector binary, and the graph it emits gets the same treatment as the rest: summarized, embedded, searchable, syncable.

Practice graphs hold best-practice patterns collected from books, references, and websites, and sit beside your code, so an agent can reach for the established idiom instead of the first thing that compiles. The full write-up for each pillar: Capabilities.

Install

One line, macOS (Apple Silicon) or Linux (x86_64 / arm64):

curl -fsSL https://raw.githubusercontent.com/fulminate-io/knowledge-mcp/main/install.sh | sh

The script downloads the latest release of both binaries (checksum-verified) into ~/.knowledge/bin, then hands off to knowledge setup. Setup writes your first-run config (auto-detecting an LLM provider), installs the agents and skills for Claude Code and/or Codex if those CLIs are present, and registers the MCP daemon with them. It also installs user-level services (launchd on macOS, systemd --user on Linux) so the graph server (127.0.0.1:15022) and MCP daemon (127.0.0.1:15023) start at login. Everything runs as your user; no sudo anywhere.

Re-running the same line upgrades in place; your config is never touched. To configure interactively (pick a provider, paste optional API keys), run knowledge setup in a terminal any time. Headless provisioning: append flags after sh -s -- (e.g. --headless, --no-service); credentials come from the environment (ANTHROPIC_API_KEY, VOYAGE_API_KEY, LINEAR_API_KEY, ...) or ~/.knowledge/config, never from flags. On Windows, follow the manual install guide.

brew tap fulminate-io/knowledge
brew install knowledge
brew services start knowledge-server   # local graph server  (127.0.0.1:15022)
brew services start knowledge          # shared MCP daemon    (127.0.0.1:15023)
knowledge install-claude-assets        # wire Claude Code (or: install-codex-assets)

git clone https://github.com/fulminate-io/knowledge-mcp.git
cd knowledge-mcp
CGO_ENABLED=1 go build -o bin/knowledge .

knowledge serve                    # MCP daemon on 127.0.0.1:15023
knowledge start / status / stop    # knowledge-server lifecycle (15022)

First index

Restart your editor so it picks up the new MCP server, then trigger the first index from inside the LLM:

collect({ "type": "code", "id": "/absolute/path/to/repo" })

The first pass takes 30s–2min for a typical repo: tree-sitter chunks the files, the LLM summarizes each node. Subsequent indexes are incremental: only changed files re-summarize.

No credentials are required to get here. On first run the server auto-detects an LLM provider: it prefers a logged-in Claude or Codex CLI on $PATH, then falls back to ANTHROPIC_API_KEY, OPENAI_API_KEY, or GEMINI_API_KEY from the environment.

[!WARNING] A large first index is thousands of LLM calls — one summary per node. If your summarizer is a logged-in claude or codex CLI, every call draws on that subscription's session quota. For a big repo, point the summarizer at an API provider first: add a [summarizer] section to ~/.knowledge/config with provider = "anthropic", "openai", or "gemini" and the matching key, then restart the daemon. See Configuration. Subsequent indexes are incremental and cheap either way.

Full walkthroughs: Set up with Claude Code · Set up with Codex. knowledge doctor diagnoses install and daemon/server health. To connect another MCP client by hand, point it at the daemon's streamable-HTTP endpoint: http://127.0.0.1:15023/mcp.

Two keys worth setting

Both are optional; both change what you get.