v0.15.1

v0.15.1

P@10 = 0.330 (302 tasks, 17 repos, 8 languages). 3.79x codegraph, 6.00x GitNexus, 22.0x grep.

What's new

• GCF v2.0 Stable: gcf-go v1.0.0 with mandatory profile=graph header, edges=N count in header and section headers. Closes the final comprehension gap with TOON on edge counting.
• Cal.com corpus: 17th benchmark repo (TypeScript/Next.js scheduling). 9 scheduling equiv classes. Calcom P@10 = 0.409.
• E-commerce equiv classes: 5 domain classes for saleor. P@10: 0.264 -> 0.527 (+99.6%).
• Corpus DB packaging: corpus-setup.sh package/restore creates per-repo tarballs for release assets.
• Benchmark whitepaper: prepared for publication (all numbers current, dev notes removed).

Install

brew install blackwell-systems/tap/knowing
# or
go install github.com/blackwell-systems/knowing/cmd/knowing@v0.15.1
# or
npm install -g @blackwell-systems/knowing
# or
pip install knowing

Full changelog: CHANGELOG.md

v0.15.0: GCF Default + Eval Cleanup

See CHANGELOG.md for details.

Install

brew install blackwell-systems/tap/knowing
go install github.com/blackwell-systems/knowing/cmd/knowing@v0.15.0

v0.13.0: Framework Intelligence + In-Process Resolvers

P@10 = 0.278 (308 tasks, 16 repos, 8 languages, cold start)

3.20x codegraph (19K stars). 5.05x GitNexus. 5.35x Gortex. 18.5x grep. codebase-memory could not complete the benchmark (22/297 tasks in 60 min, P@10 = 0.137 on completed subset).

Benchmark methodology

308 hand-curated retrieval tasks across 16 open source repositories spanning Go, Python, TypeScript, Java, C#, Rust, Ruby, and SQL. Each task is a natural-language description paired with expert-verified ground truth symbols. Repos range from 14K nodes (Jekyll) to 200K+ nodes (VS Code). Corpus includes both framework source code (django/django, pallets/flask) and framework-using applications (saleor/saleor, a Django e-commerce platform).

All measurements are cold start: no task memory, no embedding vectors, no cached results. Task memory is cleared before every run. Test cache is cleared before every run. Binary is rebuilt from source before every run. The benchmark adapter disables persistent pack caching. Every number is reproducible from the public corpus with BENCH_ADAPTERS=knowing go test ./bench/cross-system/ -run TestCrossSystem -v -timeout 0.

Competitive benchmarks run the same tasks through the same harness. All competitors use their default configurations. Corpus, tasks, and harness are open source.

Recommended setup

For the best retrieval experience, enable LSP enrichment:

knowing index <repo>           # tree-sitter + in-process resolvers + LSP enrichment

LSP enrichment (gopls, pyright, tsserver, etc.) upgrades edge confidence from 0.5 to 0.9 and discovers cross-file relationships that static analysis misses. Go enrichment alone moved Kubernetes from 0.000 to 0.232 and Terraform from 0.095 to 0.275. Language servers are auto-detected from project markers (go.mod, pyproject.toml, tsconfig.json).

For environments without language servers, the in-process resolvers provide the middle quality tier automatically:

Tree-sitter (0.5) -> In-process resolver (0.9) -> External LSP (0.9)

Each layer is optional. The binary alone gives you the first two.

Framework equivalence classes

263 concept-to-symbol mappings across 20 frameworks and 8 languages. When a task says "form validation," the engine knows the answer is RegexValidator, EmailValidator, URLValidator, even with zero keyword overlap. High-confidence matches bypass the graph walk and inject directly into results.

Covers Django, Flask, FastAPI, Terraform, Kubernetes, Kafka, Rails, Spring, ASP.NET, Ocelot, Caddy, Cargo, VS Code, NestJS, Next.js, Angular, React, Jekyll + cross-cutting patterns (testing, ORM, auth, CLI, config, errors, web, containers, crypto).

Self-adapting retrieval

Eight mechanisms that observe the graph and adjust. No configuration.

• Density-adaptive seeding: >40K nodes automatically prefers type hierarchies and increases seed count
• Language-scoped equiv classes: detects repo language from node structure, activates only matching frameworks
• Framework forced injection: high-confidence concept matches bypass the graph walk entirely
• Proximity-weighted scoring: BFS hop distance from seeds penalizes distant noise (zero overhead, reuses walk adjacency maps)
• Adaptive retrieval fallback: >200K node repos with flat walk results fall back to direct FTS + contains-edge expansion
• Focused seed selection: clusters candidates by package path, concentrates the walk in the dominant neighborhood

A 14K-node Jekyll repo and a 200K-node VS Code repo get different retrieval strategies automatically.

In-process resolvers

All 7 language resolvers (Go, Python, TypeScript, Java, C#, Rust, Ruby) run in-process during indexing. No external language servers required. Produces resolver_resolved edges at 0.9 confidence.

Repo	Language	Resolver Edges
Kafka	Java	595,973
Django	Python	57,843
Cargo	Rust	26,989
VS Code	TypeScript	18,541
Ocelot	C#	1,285

Per-repo P@10

Repo	Lang	P@10	Change
Caddy	Go	0.440	+63%
Jekyll	Ruby	0.430	stable
Kafka	Java	0.421	+81%
Terraform	Go	0.405	+238%
Rails	Ruby	0.340	+70%
Flask	Python	0.321	+33%
Ocelot	C#	0.285	+90%
FastAPI	Python	0.275	+41%
Saleor	Python	0.236	new
Spark-Java	Java	0.235	+40%
Ripgrep	Rust	0.195	stable
Cargo	Rust	0.186	+11%
Django	Python	0.183	+126%
Kubernetes	Go	0.168	+68%
VS Code	TS	0.168	+354%

Saleor is the first framework-USING repo (Django e-commerce app). Proves equiv classes generalize to application code.

Other changes

• Embeddings OFF by default (confirmed neutral on cold start, no 30MB download)
• Phantom Python extends edges eliminated (5,581 dangling edges removed)
• Equivalence classes refactored into 30 per-framework files
• 3 new debug tools: debug-fts, debug-walk, bench-task
• mcp-assert lint made non-blocking (known false positives documented)

Full changelog: https://github.com/blackwell-systems/knowing/blob/main/CHANGELOG.md

v0.12.0

See CHANGELOG.md for details.

Install

brew install blackwell-systems/tap/knowing
go install github.com/blackwell-systems/knowing/cmd/knowing@v0.12.0

v0.10.1: Correct defaults, CLI flags, module-level detection

See CHANGELOG.md for details.

Install

brew install blackwell-systems/tap/knowing
go install github.com/blackwell-systems/knowing/cmd/knowing@v0.10.1

v0.10.0: Embedding Re-ranker (+15% P@10), Supply Chain Detection, 38 Edge Types

See CHANGELOG.md for details.

Install

brew install blackwell-systems/tap/knowing
go install github.com/blackwell-systems/knowing/cmd/knowing@v0.10.0

v0.9.0: 36 Edge Types, Self-Adapting Retrieval, Field Access Graphs

See CHANGELOG.md for details.

Install

brew install blackwell-systems/tap/knowing
go install github.com/blackwell-systems/knowing/cmd/knowing@v0.9.0

v0.8.1: Fix feedback compounding regression

See CHANGELOG.md for details.

Install

brew install blackwell-systems/tap/knowing
go install github.com/blackwell-systems/knowing/cmd/knowing@v0.8.1

v0.8.0: Docstring Retrieval, 32 Edge Types, 6-Language Coverage

See CHANGELOG.md for details.

Install

brew install blackwell-systems/tap/knowing
go install github.com/blackwell-systems/knowing/cmd/knowing@v0.8.0

v0.7.1

Fixed

Equivalence Channel Noise (P@10 regression fix)

Root cause of a significant retrieval quality regression traced and fixed. The equivalence class matching channel returned unbounded results (66 on small repos) that dominated RRF fusion, causing flat RWR scores across all seeds.

Mechanism: Universal seed classes with single-word phrases (e.g., "request") triggered generic targets ("Get", "Post", "Do") matching every method with that name in the codebase. These noisy results overwhelmed the correct tiered + BM25 results during Reciprocal Rank Fusion.

Fix:

• Generic target filter: skip resolving equiv targets <=3 chars or common method names (get, set, do, new, run, put, post, call, add, pop)
• Equiv cap: limit equiv results to 2x(tiered+BM25) count, preventing channel domination
• buildFTSQuery: removed redundant unquoted compound that searched all FTS columns
• Cleaned universal seed phrases: removed single-word triggers ("request", "fetch") and generic targets from HTTP_CLIENT class

Results:

• Flask P@10: 0.20 → 0.336 (+68%, new record)
• Full corpus (117 tasks, 7 repos): 0.101 → 0.226 (+124%)

Other Fixes

• Exclude phantom external nodes from RWR walk BFS expansion
• Restore extractKeywordSet (accidentally reverted during debug)
• Aider adapter: suppress stdout progress bars polluting JSON output
• Gortex adapter: handle log lines before JSON response

Benchmark

Cross-system benchmark Run 22 results (fresh indexes, no LSP enrichment):

System	P@10	R@10	NDCG@10	MRR
knowing	0.226	0.396	0.369	0.423
Aider	0.050	-	-	-
grep	0.020	0.035	-	-

knowing is 4.5x more precise than Aider and 11.3x more precise than grep.