# Graphify Comparison & Analysis

## Overview

This document records our analysis of [Graphify](https://github.com/safishamsi/graphify) (**45,690 stars**, MIT license) against our schema discovery search service (`@coda/search` + `apps/search`). Graphify is an AI coding assistant skill that converts a folder of code, documentation, papers, images, and media into a queryable knowledge graph. It integrates as a `/graphify` slash command in Claude Code, Codex, OpenCode, Cursor, Gemini CLI, GitHub Copilot CLI, VS Code Copilot Chat, Aider, OpenClaw, Factory Droid, Trae, Hermes, Kimi Code, Kiro, Pi, Google Antigravity, and others.

We evaluated it to identify transferable techniques, as we did with [LightRAG](../search/lightrag-comparison.md), [RAG-Anything](../search/raganything-comparison.md), [ChromaFs](../search/chromafs-comparison.md), [LLM Wiki](llm-wiki-comparison.md), [RLMs](rlm-comparison.md), and [Stash](../memory/stash-comparison.md).

> **Update (2026-05-10):** Refreshed with live GitHub data. Stars at 45,690 (up from 45,601). v0.7.13 released May 9 fixing Ollama VRAM exhaustion by deriving `num_ctx` from actual chunk size. v0.7.12 also released May 9. v0.7.10-11 earlier that week added ALTER TABLE FK extraction + schema-qualified names and further stability fixes. 32 contributors (up from 30), 4,952 forks (up from 4,942), 235 open issues. v1.0.0 (Apr 5) remains the stable release milestone. Known issues #741 (non-determinism), #726 (cross-language false positives), #719 (sensitive-file filter) still open. New features since v0.7.9: callflow-html export, living architecture diagrams, Pascal/Delphi support, `graphify uninstall`, context-window retry with bisection, Windows fixes. Default branch changed to `v7`. Homepage: graphifylabs.ai. Active development continues on deterministic extraction, deduplication hardening, and cross-language bridge support (Tauri #767). Competitive landscape: code-review-graph (15,966 stars), SocratiCode (2,459 stars), codebase-memory-mcp (2,197 stars). @coda/search updated to post-PR-198 architecture. Conclusions unchanged: different problem domain, no techniques to adopt.

---

## How Graphify works

Graphify builds a knowledge graph from a mixed corpus (code + documentation + papers + images + video) through a linear pipeline:

```
detect() -> extract() -> build_graph() -> cluster() -> analyze() -> report() -> export()
```

Each stage is a single function in its own module. Stages communicate through plain Python dicts and NetworkX graphs with no shared state.

### Extraction (three-pass)

1. **Deterministic AST pass** (no LLM): tree-sitter parses code files across 29+ programming languages, extracting classes, functions, imports, call graphs, docstrings, and rationale comments (`# WHY:`, `# HACK:`, `# NOTE:`). SQL receives specialized handling for tables, views, foreign keys, ALTER TABLE FK extraction, and FROM/JOIN edges with schema-qualified name support (v0.7.10).
2. **Local transcription pass** (no LLM): faster-whisper transcribes video and audio locally. Cached per-file.
3. **LLM semantic pass**: Runs in parallel batches over docs, papers, images, PDFs, and transcripts. Outputs JSON fragments containing nodes, edges, and group relationships that merge into the unified graph.

Code files never touch the LLM -- only non-code content does. AST parsing is deterministic, fast, and free; LLM extraction is reserved for inherently ambiguous content.

### Graph construction

- NetworkX graph (undirected by default, directed with `--directed`)
- Three-layer node deduplication: within-file (AST `seen_ids` set), between-file (NetworkX idempotent `add_node`), and semantic merge (explicit `seen` set)
- Edges carry structured metadata: `relation`, `confidence` (EXTRACTED/INFERRED/AMBIGUOUS), `confidence_score` (float for INFERRED), `source_file`, `source_location`, `weight`
- **Hyperedges** (v0.5+): Group relationships stored in `G.graph["hyperedges"]` for N-ary relationships
- Cross-file call resolution with ambiguity filtering (>=2 matching callee names are skipped)

### Confidence system

| Level     | Confidence | Meaning                                          |
| --------- | ---------- | ------------------------------------------------ |
| EXTRACTED | 1.0        | Found directly in source (import, call, literal) |
| INFERRED  | 0.55-0.95  | Reasonable deduction (co-occurrence, call-graph) |
| AMBIGUOUS | N/A        | Uncertain, flagged for human review              |

### Community detection

- Leiden algorithm (via graspologic) preferred; falls back to Louvain (NetworkX built-in)
- Two-phase cohesion re-clustering (v0.6.9) prevents unrelated subsystems from merging
- Oversized communities (>25% of graph nodes, min 10) are automatically split
- No embeddings involved -- clustering is purely graph-topology-based

### Querying

- BFS traversal (broad context) or DFS traversal (trace specific paths)
- Keyword matching against node labels with diacritic-insensitive scoring and exact bonus
- Token-budgeted output (configurable, default 2000 tokens)
- Shortest path finding via NetworkX (max 8 hops)
- All queries operate on persisted `graph.json` -- no re-reading source files

### Outputs (v1.0.0+)

- `graph.html` -- interactive HTML visualization (click nodes, filter, search)
- `GRAPH_REPORT.md` -- god nodes, surprising connections, suggested questions
- `graph.json` -- full persistent graph for agent navigation
- Optional: Obsidian vault export with graph.canvas, wiki export, callflow-html diagrams

### Security model (v0.5.4+)

SSRF protection (URL scheme whitelisting, private IP blocking, DNS rebinding defense), size limits (50MB binary, 10MB text), path traversal prevention, and input sanitization.

---

## How our system differs

Our search service is a **schema discovery engine** -- it indexes structured GraphQL and Snowflake metadata so an AI agent can find relevant operations/tables from natural-language queries. Graphify is a **codebase comprehension tool** -- it builds a knowledge graph from code and documentation so an AI assistant has structured context about a project.

### Architecture (post-PR-198)

The engine has been decomposed into focused, interface-driven components:

- **SearchEngine** -- generic lifecycle orchestrator implementing `SchemaIndex`. State machine: CREATED -> READY -> DEGRADED -> DESTROYED.
- **SchemaFetcher** -- data source abstraction (`fetch()` for cold start, `diff()` for incremental)
- **DocumentTransformer** -- adapts raw items to searchable documents
- **GraphBuilder** -- builds and incrementally updates the relationship `LabeledGraph<string>`
- **GlossaryProvider** -- supplies domain glossary entries for term expansion
- **Filter** -- allowlist/blocklist predicate controlling which items are indexed
- **SnapshotPersistence** -- versioned blob store with three-dimensional key invalidation

### Feature comparison

| Aspect               | Graphify (v0.7.13, 45.7K stars)                                 | @coda/search (v0.1.0)                                                                           |
| -------------------- | --------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| **Purpose**          | Codebase comprehension for AI assistant context                 | Schema discovery for AI agent tool selection                                                    |
| **Corpus**           | Source code + docs + papers + images + video + SQL schemas      | Structured schema metadata (GraphQL types, Snowflake tables)                                    |
| **Architecture**     | Linear pipeline (7 stages, plain dicts, no shared state)        | Decomposed engine: SchemaFetcher + DocumentTransformer + GraphBuilder + HybridSearch + Pipeline |
| **Graph source**     | AST parsing (code) + LLM extraction (docs) + confidence tagging | Structurally derived (type->field edges, FK inference from `_ID` columns)                       |
| **Graph interface**  | NetworkX API (mutable, no read-only view)                       | `ReadonlyLabeledGraph<T>` interface for consumers; mutable `LabeledGraph<T>` for builders       |
| **Retrieval**        | BFS/DFS traversal + keyword matching on node labels             | BM25 keyword + HNSW vector + glossary boost + graph degree + proximity -> RRF fusion            |
| **Score fusion**     | None (traversal-based, no scoring)                              | `ScoreFusion` interface: `RrfFusion` (k=25) + `WeightedSumFusion`; N-signal, extensible         |
| **Embeddings**       | None -- explicitly avoided                                      | ONNX-quantized HNSW (uint8, ~55MB for 10K docs), zero LLM dependency                            |
| **Lexical matching** | Simple keyword match with diacritic normalization + exact bonus | BM25 with Porter stemming, camelCase splitting, and prefix fallback                             |
| **Indexing cost**    | Free for code (AST); LLM calls for docs/media                   | Zero LLM calls (tokenize + embed only)                                                          |
| **Query latency**    | ~50-500ms (graph traversal + keyword scan)                      | ~10-15ms (in-memory BM25 + HNSW)                                                                |
| **State management** | Stateless pipeline, persisted graph.json                        | State machine: CREATED->READY->DEGRADED->DESTROYED with AbortController propagation             |
| **Deployment**       | Local CLI tool + MCP stdio. No server.                          | ConnectRPC microservice (Fargate), admin UI                                                     |
| **Integrations**     | 18+ AI coding assistant platforms                               | ConnectRPC API consumed by internal AI agent                                                    |
| **Observability**    | Report file + `cost.json`                                       | Typed EventBus (28 event types), OTel-compatible envelopes, admin UI                            |
| **Benchmarks**       | None published                                                  | NDCG=0.887, MRR=0.943, Recall@10=0.994 (82 tables, 40 golden queries)                           |
| **Test count**       | 85 test files, unit tests only                                  | ~1,386 tests (~721 packages/search + ~665 apps/search)                                          |
| **Release cadence**  | Daily (v0.7.10-13 in past 3 days)                               | PR-based, CI-gated                                                                              |

---

## Why we are not adopting Graphify

### 1. Different problem domains -- codebase comprehension vs schema retrieval

Graphify builds understanding of how code is organized. Our system retrieves specific schema entries to inform an agent's next action. The knowledge graph Graphify produces is a development aid; the search results we produce are tool-selection inputs.

### 2. No vector retrieval -- graph traversal alone is insufficient for ranked search

Graphify explicitly avoids embeddings. Retrieval is BFS/DFS graph traversal from keyword-matched start nodes. BM25 + HNSW + RRF fusion consistently outperforms graph-traversal-only retrieval in our benchmarks (NDCG@10 improvement of 0.15-0.20 over keyword-only baselines).

### 3. No score fusion -- cannot combine heterogeneous signals

Our pipeline fuses 6+ signals through `RrfFusion`. Adding Graphify's traversal-based approach would either replace RRF (a regression) or duplicate our existing graph degree and proximity signals.

### 4. Local-only architecture does not fit our deployment model

Graphify runs entirely on the developer's machine. Our search service is a shared microservice serving multiple concurrent agents.

### 5. AST parsing is irrelevant for schema metadata

Our corpus is schema metadata from introspection queries and `INFORMATION_SCHEMA`, which is more precise than what AST parsing could provide.

### 6. LLM extraction dependency is architecturally unacceptable

For non-code content, Graphify delegates extraction to the user's AI assistant. Our system controls the full pipeline with zero LLM calls and deterministic behavior.

---

## What we could adopt (re-evaluated)

### Considered: Confidence-tagged edges

**Graphify pattern**: Every relationship tagged EXTRACTED/INFERRED/AMBIGUOUS with discrete confidence bands (0.55-0.95).

**Verdict**: Not adopting now. Our graph edges are all structurally derived and therefore certain. Revisit if we add inferred cross-datasource relationships.

### Considered: Graph-seeded retrieval as an additional RRF signal

**Verdict**: Not adopting. `ProximitySignal` already captures graph-local relevance with better anchor selection (vector candidates vs keyword matches).

### Considered: Community-level result grouping

**Verdict**: Not adopting. Graph augmentation already provides related-item grouping; community detection adds no value on our shallow (2-hop) graph.

### Considered: SQL AST extraction

**Graphify pattern** (v0.6.0+, enhanced in v0.7.10): tree-sitter-sql parses SQL files to extract tables, views, foreign keys, ALTER TABLE FK, and FROM/JOIN edges with schema-qualified name support.

**Verdict**: Not adopting now. `INFORMATION_SCHEMA` is authoritative and sufficient. Revisit if we need to index SQL files from version control.

### Worth monitoring: Content-hash incremental extraction (v0.7.5)

**Graphify pattern**: `graphify extract` auto-detects a prior `manifest.json` and re-extracts only changed/new files.

**Our analog**: Our snapshot system uses content-hash cache keys (`version + modelId + contentHash`) at the index layer. Conceptually equivalent, different layer.

**Verdict**: Not adopting -- we already have this at the index layer.

### Worth monitoring: Entity deduplication via MinHash/LSH (v0.7.5)

**Graphify pattern**: Entropy gate + MinHash/LSH blocking + Jaro-Winkler verification + same-community boost.

**Verdict**: Not adopting now. Revisit when automated glossary generation is on the roadmap.

### Worth monitoring: Cross-project graph composition (v0.7.7)

**Graphify pattern**: `graphify global add/remove/list/path` registers multiple project graphs with collision-preventing prefixed node IDs.

**Verdict**: Not adopting. Our multi-engine approach provides stronger isolation.

### Worth monitoring: Cross-language bridge support (issue #767)

**Graphify pattern**: Tauri `invoke()` to `#[tauri::command]` resolution across TypeScript and Rust files.

**Verdict**: Interesting for cross-datasource join discovery, but architecturally different from our FK-inference approach.

**Conclusion**: No techniques from Graphify are worth adopting at this time. The entity dedup, global graph, and cross-language bridge patterns are worth monitoring.

---

## Enterprise readiness comparison

| Dimension                     | Graphify (v0.7.13)                                        | @coda/search                                                                 |
| ----------------------------- | --------------------------------------------------------- | ---------------------------------------------------------------------------- |
| **Deployment model**          | Local CLI + MCP stdio. No server.                         | Fargate container, ConnectRPC service, health checks.                        |
| **Multi-tenancy**             | None. Single-user, single-repo at a time.                 | Multiple SchemaFetcher instances. Tenant isolation via SearchFilter.         |
| **High availability**         | Not applicable (local tool).                              | Fargate tasks with health probes. Circuit breaker.                           |
| **State management**          | Stateless pipeline. Graph persisted as JSON file.         | Explicit state machine (CREATED->READY->DEGRADED->DESTROYED).                |
| **Graceful degradation**      | None. If extraction fails, the pipeline stops.            | Two-phase init: keyword search immediate, vectors async. Per-stage fallback. |
| **Observability**             | `cost.json` + `GRAPH_REPORT.md`. No structured telemetry. | 28 typed event types, OTel-compatible envelopes, admin UI.                   |
| **Access control**            | None.                                                     | Build-time `Filter` allowlist/blocklist + query-time `SearchFilter`.         |
| **Cost predictability**       | Unbounded LLM cost for non-code content.                  | $0 per query, $0 per index build.                                            |
| **CI integration**            | Headless extraction (v0.7.3).                             | Jenkins pipeline with lint + typecheck + tests + audit.                      |
| **Benchmark / quality gates** | None published.                                           | NDCG=0.887, MRR=0.943. MRR regression guard in CI.                           |
| **Test coverage**             | 85 test files. Unit tests only.                           | ~1,386 tests. Unit + integration + benchmark.                                |
| **Known quality issues**      | #741 non-determinism, #726 false positives, #719 filter   | No known quality issues in retrieval accuracy.                               |

---

## Developer experience comparison

| Dimension                | Graphify                                                          | @coda/search                                                         |
| ------------------------ | ----------------------------------------------------------------- | -------------------------------------------------------------------- |
| **Getting started**      | `pip install graphifyy && graphify .` -- one command, zero config | Implement 4-5 interfaces, wire up SearchEngine. Higher barrier.      |
| **API surface**          | 7 MCP tools + 10+ CLI commands. Flat, imperative.                 | 9 sub-path exports, 50+ types/classes. Interface-driven, composable. |
| **Time to first result** | < 1 minute for a small repo (AST only)                            | Seconds (warm-start) to minutes (cold embed).                        |
| **Learning curve**       | Low -- CLI tool with ~15 commands.                                | Higher -- requires understanding IR concepts, signal system, DI.     |
| **Flexibility**          | Fixed pipeline. No hooks for custom stages.                       | Pluggable at every layer: SearchStage, Signal, Fusion, Expander.     |
| **Type safety**          | Python dict-based. Runtime errors.                                | Full TypeScript generics: `SearchEngine<TRaw, TDoc, TContext>`.      |
| **Platform breadth**     | 18+ AI coding assistant integrations                              | Single internal consumer (AI agent service)                          |

---

## Abstraction quality

### Graphify

Graphify's abstractions are **thin and imperative**. Each pipeline stage is a standalone function that takes plain dicts and returns plain dicts. No interfaces, no DI, no composition contracts. Strengths: low cognitive overhead, easy to fork, massive platform reach. Weaknesses: no compile-time contracts, monolithic NetworkX graph object, no extension points.

### @coda/search

Our abstractions are **interface-driven and composable**. Key patterns:

1. **ReadonlyLabeledGraph<T>** -- consumers receive read-only views, enforced at the type level
2. **StaticSignal<T> / QuerySignal** -- captures the static-vs-per-query distinction cleanly
3. **SearchStage** -- single `rank()` method, adding a signal requires one interface implementation
4. **SchemaFetcher<TRaw, TContext>** -- separates data source from indexing concerns
5. **ScoreFusion** -- `fuse(signals: NamedSignal[])`, swappable via constructor argument

---

## Documentation & examples

| Dimension             | Graphify                                          | @coda/search                                                       |
| --------------------- | ------------------------------------------------- | ------------------------------------------------------------------ |
| **README**            | Comprehensive, ~3000+ lines. Covers all commands. | Package-level TSDoc, links to architecture docs.                   |
| **Translations**      | 28 languages                                      | English only                                                       |
| **API reference**     | None. MCP tool schemas are the closest.           | TSDoc on every export, `@packageDocumentation` on barrels.         |
| **Architecture docs** | `GRAPH_REPORT.md` generated output.               | 6 doc pages + comparison series + style guide.                     |
| **Examples**          | Implicit through CLI usage in README.             | Progressive examples (01-04) + cookbook + golden query benchmarks. |
| **Inline docs**       | Python docstrings on public functions.            | TSDoc with design rationale (e.g., RRF k-value justification).     |

---

## Scope & limitations

### Graphify out of scope

- Ranked retrieval (no scoring, no relevance ordering)
- Vector/semantic search (no embeddings)
- Multi-tenant access control
- Concurrent query serving
- Service deployment (no API, no container)
- Quality benchmarks or regression testing
- Deterministic output (issue #741 -- ~11K-line diffs on unchanged source)

### @coda/search out of scope

- Source code parsing (AST, tree-sitter)
- Document/paper/PDF extraction
- Image or video analysis
- Community detection / clustering
- LLM-based extraction (by design)
- Cross-repository analysis
- AI coding assistant integration (18+ platforms)

---

## Competitive landscape -- codebase comprehension tools

| Project                 | Stars  | Status         | Notes                                                              |
| ----------------------- | ------ | -------------- | ------------------------------------------------------------------ |
| **Graphify**            | 45,601 | Active (daily) | Market leader. v1.0.0 stable + v0.7.13. 18+ platform integrations. |
| **code-review-graph**   | 15,966 | Active         | Local knowledge graph for Claude Code.                             |
| **SocratiCode**         | 2,459  | Active         | Enterprise-grade 40M+ LOC intelligence.                            |
| **codebase-memory-mcp** | 2,197  | Active         | MCP server for persistent knowledge graphs.                        |

---

## Verdict & recommendations

### If we started fresh, what would we adopt from Graphify?

Nothing for search retrieval. Graphify solves a fundamentally different problem (codebase comprehension vs schema discovery). Its BFS/DFS traversal retrieval without embeddings or score fusion is inadequate for ranked search. However, if we ever needed a codebase comprehension layer for our AI agent, Graphify's `/graphify` slash command integration pattern is the gold standard.

### What are we doing better?

- **Retrieval quality**: Multi-signal ranked search with formal evaluation (NDCG=0.887, MRR=0.943) vs traversal-based keyword matching with no benchmarks
- **Determinism**: Our indexing and retrieval pipeline is fully deterministic; Graphify produces ~11K-line diffs on unchanged source (issue #741)
- **Cost predictability**: $0 per query, $0 per index build vs unbounded LLM cost for non-code content
- **State management**: Explicit state machine with graceful degradation vs stateless pipeline that stops on failure
- **Test rigor**: ~1,386 tests with MRR regression guard vs 85 test files with known quality issues (#726 false positives, #719 filter issues)
- **Type safety**: Full TypeScript generics with compile-time contracts vs Python dict-based runtime errors

### What are we missing for enterprise-level production readiness?

- **Platform breadth**: Graphify integrates with 18+ AI coding assistants. Our search service has one internal consumer.
- **Community**: 45.6K stars, 30 contributors, 4.9K forks, rapid release cadence vs private internal project
- **Content variety**: Graphify handles code, docs, PDFs, images, video, YouTube, Office files, Google Workspace. We handle GraphQL and Snowflake metadata only.
- **Distributed indexing**: Neither system supports multi-node deployment
- **Rate limiting**: Handled at API gateway, not in the search layer

### Overall assessment

Graphify and @coda/search are complementary, not competitive. Graphify excels at turning diverse codebases into navigable knowledge graphs for AI assistants. @coda/search excels at precision-ranked retrieval of structured schema metadata for AI agent tool selection. The v1.0.0 milestone (Apr 2026) with Leiden community detection, edge provenance tagging, and interactive visualization makes Graphify the clear leader in codebase comprehension. But its lack of vector search, score fusion, evaluation metrics, and deterministic behavior makes it unsuitable for our retrieval use case.

---

## References

- Shamsi, S.: [Graphify](https://github.com/safishamsi/graphify) (MIT, 2026) -- 45,690 stars, v0.7.13
- LightRAG comparison: [lightrag-comparison.md](../search/lightrag-comparison.md)
- ChromaFs comparison: [chromafs-comparison.md](../search/chromafs-comparison.md)
- LLM Wiki comparison: [llm-wiki-comparison.md](llm-wiki-comparison.md)
- RLM comparison: [rlm-comparison.md](rlm-comparison.md)
- Stash comparison: [stash-comparison.md](../memory/stash-comparison.md)