code-knowledge-graph

module

v0.0.0-...-85391f8 Latest Latest Go to latest Published: May 13, 2026 License: AGPL-3.0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/0xmhha/code-knowledge-graph

Links

Open Source Insights

README ¶

CKG — Code Knowledge Graph

Build a queryable knowledge graph from a code path. Point CKG at a directory and it parses the source (Go / TypeScript / Solidity) into a graph of files, symbols, and relationships you can query from the CLI, an MCP-enabled LLM, or a 3D web viewer.

Features

Multi-language parsing — Go, TypeScript, Solidity via tree-sitter
Persistent graph store — SQLite (default) or PostgreSQL
Multiple query surfaces — REST API, MCP server, 3D viewer
Incremental builds — file-level caching for fast re-indexing
Rich schema — 33 node kinds, dependency / call / git-history edges

Quick start

git clone https://github.com/0xmhha/code-knowledge-graph
cd code-knowledge-graph
make build

# 1. Build a graph from any code path
./bin/ckg build --src=/path/to/repo --out=/tmp/ckg

# 2. Query via HTTP + 3D viewer
./bin/ckg serve --graph=/tmp/ckg --open      # http://localhost:8080

# 3. Query from Claude Code via MCP
claude mcp add ckg --command ./bin/ckg --args "mcp,--graph=/tmp/ckg"

Commands

Command	Purpose
`ckg build`	Parse a code path into a graph database
`ckg serve`	HTTP API + embedded 3D viewer
`ckg mcp`	MCP server for LLM agents (Claude Code, etc.)
`ckg export-static`	Export viewer + chunked JSON for static hosting
`ckg export-postgres`	Migrate a SQLite graph to PostgreSQL
`ckg eval`	Compare graph-context vs raw-file context on benchmark tasks
`ckg audit`	Validate graph integrity

Run ckg <command> --help for flags.

Production deployment

ckg serve ships an embedded viewer for local use. For shared deployments, split the static viewer from the API:

./bin/ckg export-static --graph=/tmp/ckg --out=/srv/ckg/static
./bin/ckg serve --graph=/tmp/ckg --port=8080 --no-viewer

Front both with a reverse proxy: /api/* → :8080, /* → /srv/ckg/static.

Documentation

docs/ARCHITECTURE.md — pipeline + subcommand overview
docs/SCHEMA.md — node and edge enumeration
docs/EVAL.md — eval harness and scoring
docs/STUDY-GUIDE.md — background on Leiden, MCP, tree-sitter, 3D layout

Contributing

Contributions are welcome. To get started:

Fork the repository and create a feature branch from main.
Run make test and make lint before submitting.
Use conventional commit prefixes (feat:, fix:, docs:, ...).
Open a pull request describing the change and its motivation.

For larger changes, please open an issue first to discuss the design. Report bugs and request features at https://github.com/0xmhha/code-knowledge-graph/issues.

License

CKG is licensed under the GNU Affero General Public License v3.0 — see LICENSE.

AGPL-3.0 requires that if you run a modified version of CKG as a network-accessible service, you must make the corresponding source available to its users.

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
cmd
ckg command cmd/ckg/bench_mcp.go — `ckg bench-mcp` measures p50/p95/p99 latency of every registered MCP tool against a real graph.db.	cmd/ckg/bench_mcp.go — `ckg bench-mcp` measures p50/p95/p99 latency of every registered MCP tool against a real graph.db.
internal
audit Package audit compares the authoritative Go build file set (go/packages.Load) against the file set recorded in the CKG database.	Package audit compares the authoritative Go build file set (go/packages.Load) against the file set recorded in the CKG database.
buildpipe Package buildpipe — cache.go implements the A3 file-level incremental cache (spec v0.2 § 4 Phase 1).	Package buildpipe — cache.go implements the A3 file-level incremental cache (spec v0.2 § 4 Phase 1).
cluster Package cluster — Leiden community detection (V0 implementation).	Package cluster — Leiden community detection (V0 implementation).
detect
eval Package eval is the LLM-based benchmark harness for CKG.	Package eval is the LLM-based benchmark harness for CKG.
filterlist Package filterlist implements the --files-from JSON include/exclude filter for ckg build.	Package filterlist implements the --files-from JSON include/exclude filter for ckg build.
graph
link Package link — http_match.go implements W2 of schema 1.9 (cross-language HTTP client → server matching).	Package link — http_match.go implements W2 of schema 1.9 (cross-language HTTP client → server matching).
mcp Package mcp — bench.go exposes the registered tool handlers for in-process latency measurement.	Package mcp — bench.go exposes the registered tool handlers for in-process latency measurement.
parse
parse/golang Package golang is the Go-language parser for CKG.	Package golang is the Go-language parser for CKG.
parse/proto Package proto implements the CKG parser for `.proto` files (schema 1.9 W3a).	Package proto implements the CKG parser for `.proto` files (schema 1.9 W3a).
parse/solidity Package solidity implements the CKG parser for .sol files (spec §4.6.3).	Package solidity implements the CKG parser for .sol files (spec §4.6.3).
parse/solidity/binding Package binding wraps the tree-sitter-solidity grammar (vendored from github.com/JoranHonig/tree-sitter-solidity v1.2.11, MIT-licensed) into a *sitter.Language usable by github.com/tree-sitter/go-tree-sitter.	Package binding wraps the tree-sitter-solidity grammar (vendored from github.com/JoranHonig/tree-sitter-solidity v1.2.11, MIT-licensed) into a *sitter.Language usable by github.com/tree-sitter/go-tree-sitter.
parse/typescript Package typescript — body_walk.go implements P3 of the TS parser: statement-level call extraction inside function/method bodies.	Package typescript — body_walk.go implements P3 of the TS parser: statement-level call extraction inside function/method bodies.
persist Package persist defines storage interfaces (StoreReader / StoreWriter / Store) and a SQLite implementation.	Package persist defines storage interfaces (StoreReader / StoreWriter / Store) and a SQLite implementation.
score Package score — centrality.go provides Brandes betweenness centrality with source sampling, used by the GRAPH_REPORT generator to surface "bridge nodes": symbols that connect otherwise-distant parts of the graph and therefore drive cross-cutting concerns.	Package score — centrality.go provides Brandes betweenness centrality with source sampling, used by the GRAPH_REPORT generator to surface "bridge nodes": symbols that connect otherwise-distant parts of the graph and therefore drive cross-cutting concerns.
server Package server implements the HTTP API and serves the embedded viewer.	Package server implements the HTTP API and serves the embedded viewer.
temporal Package temporal extracts git-history derived facts (commits + per-file touch lists) used to emit CKS G6 Temporal edges (`changed_in`, `blame`) in the build pipeline.	Package temporal extracts git-history derived facts (commits + per-file touch lists) used to emit CKS G6 Temporal edges (`changed_in`, `blame`) in the build pipeline.
validate Package validate provides post-build inspectors that audit a constructed graph for integrity issues.	Package validate provides post-build inspectors that audit a constructed graph for integrity issues.
pkg
bm25 Package bm25 implements Okapi BM25 ranking for code-aware corpora.	Package bm25 implements Okapi BM25 ranking for code-aware corpora.
evidence Package evidence — cache.go amortises the per-call corpus indexing across BuildPack invocations.	Package evidence — cache.go amortises the per-call corpus indexing across BuildPack invocations.
impact Package impact is the shared "impact_of_change" implementation used by both internal/mcp.impact_of_change and internal/server's HTTP /api/impact handler.	Package impact is the shared "impact_of_change" implementation used by both internal/mcp.impact_of_change and internal/server's HTTP /api/impact handler.
smartctx Package smartctx is the shared "smart 1-shot retrieval" implementation used by both internal/mcp.get_context_for_task and internal/eval's δ baseline.	Package smartctx is the shared "smart 1-shot retrieval" implementation used by both internal/mcp.get_context_for_task and internal/eval's δ baseline.
store Package store is the public, read-only graph access surface for external callers (eval harness, future sister repos).	Package store is the public, read-only graph access surface for external callers (eval harness, future sister repos).
types