knowledge-mcp CLAUDE.md

Knowledge

A persistent memory and reasoning graph for LLMs. Runs as a local MCP server. Primitives: think / charge / recall for hypothesis + evidence, informed-by edges linking code → decision → plan, triple-graph architecture (code + cloud + knowledge). Free OSS; Fulminate Cloud hosts the paid tiers.

Build

CGO_ENABLED=1 go build -o bin/knowledge .   # MCP stdio client
CGO_ENABLED=1 go test -p 4 ./...                          # all tests

CGO is required for tree-sitter C bindings (31 language grammars).

Setup

The knowledge binary is the MCP stdio client. It needs a graph server to talk to. Two options:

Local server (free, file-backed):

knowledge install   # downloads the server binary for your platform
knowledge start     # spawns the server on 127.0.0.1:15022
knowledge status    # confirm running

Fulminate Cloud (paid, team-shared):

knowledge login     # browser-PKCE OAuth flow

Once a server is available, point your MCP host at the client:

{
  "mcpServers": {
    "knowledge": {
      "command": "knowledge",
      "args": ["--root", "."]
    }
  }
}

The stdio client auto-connects to 127.0.0.1:15022 when unauthenticated, or routes to Fulminate Cloud when logged in. Run knowledge login for paid cloud features (team sync, always-on agents). Browser-only by design — headless environments are not supported.

Code Exploration: knowledge tools FIRST, shell tools LAST

Default to search, file_symbols, and traverse for every code-exploration task. Grep / Glob / Read / Bash-tail are the fallback, not the starting point. The knowledge graph is indexed, semantically aware, and knows the call graph — shell tools aren't. Reaching for grep first is almost always slower and less accurate.

Want to...	Use this first	Not this
Find functions, types, patterns, implementations	search({ "queries": [...] }) (batch 3-5 terms)	Grep / rg
List symbols in a file before editing	file_symbols({ "file_path": "..." })	Read the whole file
Find callers of a function	traverse({ "start": "path/to/file.go:Func", "graph": "code", "repo": "...", "edge_types": ["CALLS"], "direction": "in" })	grep -rn 'FuncName('
Find callees of a function	traverse({ "start": "path/to/file.go:Func", "graph": "code", "repo": "...", "edge_types": ["CALLS"], "direction": "out" })	grep -rn 'FuncName('
Find structural patterns (every defer X.Close(), every sync.Once.Do, every error-returning func decl)	ast({ "operation": "match", "language": "go", "pattern": "defer $X.Close()" })	grep (misses through whitespace, comments, token reorder)
Apply a UNIFORM structural edit across many files (rename a call pattern, wrap/unwrap a call, swap a deprecated API)	ast({ "operation": "replace", "language": "go", "pattern": "defer $X.Close()", "replacement": "defer safeClose($X)" }) — dry-run previews the diff (default), dry_run:false applies	sed / perl -pi / grep+script (mangle multi-line + slice literals, can't scope by enclosing type, no re-parse safety)
Search knowledge (decisions, findings, rules, past thoughts)	search({ "queries": [...], "graph": "knowledge" }) or recall({ "text": "..." })	Reading docs manually
Inspect a node's full context (ancestry, edges, history)	query({ "mode": "examine", "id": "..." })	Multiple individual queries