{
  "markdown": "# Knowledge\n\nknowledge indexes your code, cloud infrastructure, logs, and docs into\ncross-linked graphs and serves them over MCP: hybrid code search,\ncall-graph traversal, structural AST search and replace, and a\nreasoning graph where hypotheses carry their evidence. Runs as a local\nMCP server; any LLM that speaks MCP works from the graph instead of\nrediscovering your system every session.\n\nCollectors keep the index current. The LLM queries it and gets the\npieces it asked for, sized to the question: a whole-file read bloats\nthe context with text that is not the answer, and a fragment read\nleaves gaps. Indexed retrieval is how the graph raises accuracy and\nlowers token spend.\n\nSkills and agents run an engineering workflow (brainstorm → ticket →\nplan → implement) over the same graphs, with researchers, planners,\nreviewers, and implementers reading and writing shared state.\nThoughts, decisions, tickets, and plans persist across sessions,\nmachines, and teammates. The graph makes the agent's work auditable.\n\n## See it work\n\nIndex a repo, then ask questions grep can't answer. Against this\nrepository:\n\n```jsonc\nsearch({ \"queries\": [\"bisect embedding batch on token overflow\"],\n         \"repo\": \"knowledge-mcp\" })\n\n// internal/embed/voyage.go — Voyage embedder: batches texts under item\n//   and token budgets, classifies errors, bisects token-overflow batches\n// internal/embed/voyage.go:180 isBatchTokenOverflow — detects batch token\n//   overflow by unwrapping LLMError causes\n```\n\nEach result is a graph node. Walk the call graph from any hit:\n\n```jsonc\ntraverse({ \"start\": \"internal/embed/voyage.go:voyageEmbedder.EmbedBinaryBatch\",\n           \"graph\": \"code\", \"repo\": \"knowledge-mcp\",\n           \"edge_types\": [\"CALLS\"], \"direction\": \"in\" })\n\n// EmbedBinary                                     internal/embed/voyage.go\n// TestVoyageEmbedder_BisectsOnBatchTokenOverflow  internal/embed/voyage_test.go\n// TestVoyageEmbedder_PacksByTokenBudget           internal/embed/voyage_test.go\n// ...\n```\n\nShape questions get structural answers. This matches the parsed syntax\ntree, so whitespace, comments, and token order don't matter:\n\n```jsonc\nast({ \"operation\": \"match\", \"language\": \"go\", \"pattern\": \"defer $X.Close()\" })\n\n// 65 matches across 1,560 files in 185ms: every deferred Close,\n// through whitespace, comments, and receiver renames\n```\n\nThe same engine rewrites. Give `replace` a capture template\n(`\"defer safeClose($X)\"`) and it previews the unified diff without\ntouching disk (dry-run is the default), then applies atomically; a\nrewrite that no longer parses is rejected, never written. A mechanical\nmulti-file refactor is one tool call.\n\nThe retrieval economics from the intro are visible here. When the\nquestion is \"what is in this file,\" the index answers without the\nfile: `file_symbols` returns each symbol's name, signature, line\nrange, and summary.\n\n```jsonc\nfile_symbols({ \"file_path\": \"internal/embed/voyage.go\", \"repo\": \"knowledge-mcp\" })\n```\n\nThe file is 246 lines. The context gets the symbol list, and the\nagent can fetch just the symbol it needs.\n\nReasoning persists the same way. The hypothesis recorded while that\noverflow was being debugged comes back in a later session with its\nevidence attached:\n\n```jsonc\nthoughts({ \"operation\": \"recall\", \"query\": \"voyage batch overflow\" })\n\n// 1. Voyage rejects the whole batch on token overflow, not the one long\n//    text — bound batches by estimated tokens and bisect on overflow\n//    [validated] charges: +2 (bisection test green; overflow retries gone)\n```\n\nAnd from any node you can keep walking: to the decision that shaped\nthe code, the ticket that shipped it, or the log stream where it\nfailed.\n\n## What's in the graph\n\n**Code intelligence.** Hybrid BM25 + semantic search over 31\ntree-sitter-chunked languages, an indexed call graph, and structural\nAST search *and replace*: match the shapes regex can't express, then\nrewrite every site from a capture template, gated by a dry-run diff\nand a per-file re-parse. \"Is there code that *does* this\" gets a real\nanswer, so an agent can check what exists before writing it again.\n\n**Reasoning with evidence.** Hypotheses are first-class nodes; evidence\nattaches as weighted positive or negative charges, and propagation lets\ncontradictory beliefs find equilibrium. \"Why did we do it this way\" has\nan answer months later. The graph also reads back on itself: `query`\nreflection modes include `tensions`, which lists pairs of recorded\nthoughts whose evidence points in opposite directions, and\n`personality`, `blind_spots`, and `influence`, which read the same\nthought graph from other angles. See\n[Reasoning](./docs/guides/reasoning.md).\n\n**Workflow.** Brainstorm → ticket → plan → implement, with every\nartifact in the graph and tickets synced to Linear in real time. One\ncoordinator dispatches researchers, planners, reviewers, and\nimplementers against shared state, so no single context has to hold\neverything, and a compaction or restart loses nothing the graph\nalready holds. Jira, GitHub Issues, and Asana are on the roadmap. The\nfull process model, with its routing and re-entry paths, is in\n[Concepts](./docs/guides/concepts.md).\n\n**Infrastructure and runtime.** Collectors for cloud (AWS, GCP, Azure,\nKubernetes), CI/CD, logs (CloudWatch, Loki, Elasticsearch, Stackdriver,\nK8s Events), web pages, and PDFs — each a graph, all cross-linked to\ncode. An incident traces from log line to deploy to commit to the\ndesign decision behind it. The built-in families are not a closed set:\n`custom_collector` registers your own collector binary, and the graph\nit emits gets the same treatment as the rest: summarized, embedded,\nsearchable, syncable.\n\nPractice graphs hold best-practice patterns collected from books,\nreferences, and websites, and sit beside your code, so an agent can\nreach for the established idiom instead of the first thing that\ncompiles.\nThe full write-up for each pillar:\n[Capabilities](./docs/guides/capabilities.md).\n\n## Install\n\nOne line, macOS (Apple Silicon) or Linux (x86_64 / arm64):\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/fulminate-io/knowledge-mcp/main/install.sh | sh\n```\n\nThe script downloads the latest release of both binaries\n(checksum-verified) into `~/.knowledge/bin`, then hands off to\n`knowledge setup`. Setup writes your first-run config (auto-detecting\nan LLM provider), installs the agents and skills for Claude Code\nand/or Codex if those CLIs are present, and registers the MCP daemon\nwith them. It also installs user-level services (launchd on macOS,\n`systemd --user` on Linux) so the graph server (127.0.0.1:15022) and\nMCP daemon (127.0.0.1:15023) start at login. Everything runs as your\nuser; no `sudo` anywhere.\n\nRe-running the same line upgrades in place; your config is never\ntouched. To configure interactively (pick a provider, paste optional\nAPI keys), run `knowledge setup` in a terminal any time. Headless\nprovisioning: append flags after `sh -s --` (e.g. `--headless`,\n`--no-service`); credentials come from the environment\n(`ANTHROPIC_API_KEY`, `VOYAGE_API_KEY`, `LINEAR_API_KEY`, ...) or\n`~/.knowledge/config`, never from flags. On Windows, follow the\n[manual install guide](./docs/guides/install-windows.md).\n\n<details>\n<summary><b>Homebrew</b></summary>\n\n```bash\nbrew tap fulminate-io/knowledge\nbrew install knowledge\nbrew services start knowledge-server   # local graph server  (127.0.0.1:15022)\nbrew services start knowledge          # shared MCP daemon    (127.0.0.1:15023)\nknowledge install-claude-assets        # wire Claude Code (or: install-codex-assets)\n```\n\nRun the services as your user, never with `sudo`: a root\nLaunchDaemon can't read your login keychain.\n\n</details>\n\n<details>\n<summary><b>From source</b></summary>\n\nRequirements: Go 1.26+, CGO enabled (tree-sitter C bindings). Building\nfrom source produces the `knowledge` binary only; run `knowledge\ninstall` afterwards to fetch the matching prebuilt `knowledge-server`\nfrom GitHub releases (checksum-verified).\n\n```bash\ngit clone https://github.com/fulminate-io/knowledge-mcp.git\ncd knowledge-mcp\nCGO_ENABLED=1 go build -o bin/knowledge .\n```\n\nSource-built users (no `brew services`) run the processes by hand:\n\n```bash\nknowledge serve                    # MCP daemon on 127.0.0.1:15023\nknowledge start / status / stop    # knowledge-server lifecycle (15022)\n```\n\n</details>\n\n### First index\n\nRestart your editor so it picks up the new MCP server, then trigger the\nfirst index from inside the LLM:\n\n```jsonc\ncollect({ \"type\": \"code\", \"id\": \"/absolute/path/to/repo\" })\n```\n\nThe first pass takes 30s–2min for a typical repo: tree-sitter chunks\nthe files, the LLM summarizes each node. Subsequent indexes are\nincremental: only changed files re-summarize.\n\nNo credentials are required to get here. On first run the server\nauto-detects an LLM provider: it prefers a logged-in Claude or Codex\nCLI on `$PATH`, then falls back to `ANTHROPIC_API_KEY`,\n`OPENAI_API_KEY`, or `GEMINI_API_KEY` from the environment.\n\n> [!WARNING]\n> A large first index is thousands of LLM calls — one summary per node.\n> If your summarizer is a logged-in `claude` or `codex` CLI, every call\n> draws on that subscription's session quota. For a big repo, point the\n> summarizer at an API provider first: add a `[summarizer]` section to\n> `~/.knowledge/config` with `provider = \"anthropic\"`, `\"openai\"`, or\n> `\"gemini\"` and the matching key, then restart the daemon. See\n> [Configuration](./docs/guides/config.md). Subsequent indexes are\n> incremental and cheap either way.\n\nFull walkthroughs: **[Set up with Claude Code](./docs/guides/setup-claude.md)**\n· **[Set up with Codex](./docs/guides/setup-codex.md)**. `knowledge doctor`\ndiagnoses install and daemon/server health. To connect another MCP\nclient by hand, point it at the daemon's streamable-HTTP endpoint:\n`http://127.0.0.1:15023/mcp`.\n\n## Two keys worth setting\n\nBoth are optional; both change what you get.\n\n| Key | With it | Without it |\n| --- | --- | --- |\n| `VOYAGE_API_KEY` | Hybrid semantic + keyword search; the LLM finds code and knowledge by meaning | Keyword (BM25) search only |\n| `LINEAR_API_KEY` | Projects and tickets sync to Linear in real time; status flows both ways | Tickets stay local to the graph |\n\nGet a Voyage key at [voyageai.com](https://voyageai.com); the Linear\nkey is a personal API key from Linear's settings (Settings → API).\nBoth go in `~/.knowledge/config` (TOML, auto-created on first run;\nconfig wins over the environment):\n\n```toml\n[credentials]\nvoyage_api_key = \"...\"\nlinear_api_key = \"...\"\n```\n\nTo pin LLM providers and models explicitly, the same file takes\n`[default]` and per-consumer sections; see\n[Configuration](./docs/guides/config.md) for the full reference.\n\n## Documentation\n\nStep-by-step guides ship in [`docs/guides/`](./docs/guides/index.md):\nsetup ([Claude Code](./docs/guides/setup-claude.md),\n[Codex](./docs/guides/setup-codex.md),\n[Configuration](./docs/guides/config.md)), the mental model\n([Concepts](./docs/guides/concepts.md),\n[Capabilities](./docs/guides/capabilities.md),\n[Reasoning](./docs/guides/reasoning.md)), collection\n([Web](./docs/guides/web-collection.md) ·\n[PDF](./docs/guides/pdf-collection.md) ·\n[Recipes](./docs/guides/recipes.md)), and reference\n([Binaries & CLI](./docs/guides/binaries.md) ·\n[Agents](./docs/guides/agents.md) · [Skills](./docs/guides/skills.md)).\n\n## Tools\n\n23 MCP tools across ten graph families. The full reference is\n[KNOWLEDGE_TOOLS.md](./KNOWLEDGE_TOOLS.md). The ones you'll touch\ndaily: `search`, `ast`, `traverse`, `thoughts`, `record_decision`,\n`create_project` / `create_ticket` / `create_plan`, `assemble`,\n`collect`. Generic primitives (`query`, `mutate`, `delete`,\n`manage`) route by graph and operation.\n\n## Fulminate Cloud (optional)\n\nKnowledge OSS runs entirely local: bring your own LLM, zero\ncredentials, full feature set. [Fulminate Cloud](https://fulminate.io)\nruns the same graph as a shared team environment: cloud machines your\ncoding agents run in, one graph the whole team reads and writes,\nworkflows and routing that turn inbound events (webhooks, cron ticks,\nSlack) into runs, and dashboards assembled over a dev environment and\npublished as pages. The environment tracks every run and agent, keeps\nusage analytics and audit logs, gates what agents may run with hooks,\nand supports BYOC when everything must stay in your own cloud account.\nAll tiers are BYOK: bring your own LLM key; Fulminate never resells\ntokens.\n\nIf one machine and one developer is your whole setup, the local\nserver is the product, not a trial of the paid one.\n\n```bash\nknowledge login    # browser-PKCE OAuth flow; token stored in your keychain\nknowledge logout   # revoke + clear keychain\n```\n\nLogged in, the daemon serves tool calls from the hosted graph server;\nlogged out, it runs fully local. A subscription with\n`mcp:knowledge:write` permission unlocks the `sync` tool: push local\ngraph state to cloud, pull team-visible state down, promote a working\ncopy as the team head.\n\n## Status\n\nPre-1.0. Active development toward Apache 2.0 OSS launch.\n\n**Shipping today**: MCP server with ten-graph architecture, thought\nreasoning with DeGroot propagation, 30+ topology analyzers, branch\noverlays, auto-compaction recovery, tokenless OSS boot, browser-PKCE\nOAuth login with keychain-backed credentials.\n\n## Contributing\n\nContribution guide, build rules, test conventions, and architectural\nconstraints: [CLAUDE.md](./CLAUDE.md).\n\n## License\n\nApache 2.0 on OSS launch. See [LICENSE](./LICENSE).\nFulminate Cloud commercial use is separately licensed; see\n[fulminate.io/legal](https://fulminate.io/legal).\n",
  "bytes": 13591,
  "sha": "6618e03c89d3cccb176f614911db63a7720fceab58698254d04f846094cd2787",
  "repo_slug": "fulminate-io/knowledge-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_fulminate_io_knowledge_mcp_d12ba946/readme"
}