Compass is a native, local-first knowledge graph engine for source code and project artifacts. It discovers the entities in a project, records how they relate, and gives people and tools a smaller, structured way to explore a large codebase.
Compass was inspired by Graphify, but the products now evolve independently. Compass has no Graphify runtime or test dependency. It includes Compass-native capabilities, such as CompassQL and versioned graph history, and its public contracts are defined by Compass documentation and native tests.
Start here if you want to understand the product before adopting it:
- Getting started — install Compass, build a graph, and answer a real question.
- How Compass works — understand the pipeline without needing graph-database experience.
- Graph model — learn what nodes, relationships, communities, and provenance mean.
- Operations — understand local execution, credentials, long-running processes, and recovery.
- Compatibility and performance — inspect the published evidence.
Start with Getting started, then choose the task closest to yours:
- Explore an unfamiliar codebase
- Compose task-oriented context
- Enhance a graph with an agent
- Integrate Compass with other tools
- Set up a coding assistant
- Use versioned graph history
- Process PDF and Office documents
- Review pull requests in GitHub
- Operate watch, serve, hooks, and providers
- Solve a concrete problem
- Look up commands and contracts
- Check framework-route support
| Document | What it answers |
|---|---|
| How Compass works | How does a directory become a queryable graph? |
| Graph model | What do the entities and relationships mean? |
| Community detection and quality | How are deterministic communities built, bounded, and evaluated? |
| Provenance | How can I judge where an edge came from? |
| Agent Graph Overlays | How can an agent add verified knowledge without rewriting the Base Graph? |
| CompassQL concepts | When should I use an exact structural query? |
| Guide | Outcome |
|---|---|
| Getting started | A working local graph and your first useful answers |
| Exploring a codebase | A repeatable architecture-reading workflow |
| Task context | A bounded, verified evidence packet for explain, modify, debug, or test work |
| Agent graph enhancement | A grounded, versioned, opt-in agent enhancement workflow |
| Integrating Compass | Stable, machine-readable data in another tool |
| Assistant setup | A native Compass skill installed at the right scope |
| Versioned history | Immutable graphs and diffs for exact Git commits |
| GitHub PR review | Evidence-qualified reports, safe comments, and deterministic gates |
| Operations | Safe operation of long-running and optional surfaces |
The cookbook index routes to:
| Reference | Contents |
|---|---|
| Commands | Command families, common inputs, output modes, and diagnostics |
| Configuration | Providers, environment, paths, and precedence |
| Outputs | compass-out/, graph JSON, query results, and history exports |
| Document formats | Markdown fields, limits, and discovery versus extraction |
| Framework routes | Recognized routing shapes, graph projection, and conservative boundaries |
| React frontend graph | React-family roles, render evidence, activation, and qualification boundaries |
| PR Intelligence | Canonical report, fingerprints, completeness, risk rubric, and gates |
| Compatibility | Compass contracts, hard cutovers, and portability |
| CompassQL | Canonical language and runtime contract |
| CompassQL support | Checked syntax and feature matrix |
Implementation documents describe architecture and planned engineering work. They are not evidence that an uncompleted design has shipped.
| Document | Purpose |
|---|---|
| Universal evidence implementation | Current universal evidence pipeline, resolution order, and failure classes |
| Document OCR qualification | Offline contract gate and opt-in pinned-model acceptance procedure |
| Evidence resolution framework technical design | Target ownership, components, interfaces, and invariants for rearchitecting the resolver |
| Evidence resolution framework execution plan | Phased, commit-oriented implementation and verification plan |
| Architecture graph hardening technical design | Project-specific architecture projection, quality contract, and phased delivery plan |
| Architecture graph hardening qualification | Real-repository metrics, screenshots, acceptance gates, and residual diagnostics |
| Community detection quality technical design | Versioned topology, shared quality evidence, native Leiden, bounded selection, and incremental rollout |
| Community detection quality qualification | Fixture results, performance decision, and remaining corpus evidence |
| Python call and impact qualification | Pinned Dify source-call capture and direct-connection audits |
| Concept search qualification | Pinned novice-style module retrieval, approximate provenance, and local semantic fixtures |
| Agent query evaluation | Five-repository Compass/Graphify question suite, graph-anchor results, token cost, and remaining gaps |
| Query recall and accuracy design | Phased query-quality architecture, evidence, and rollout boundaries |
| Query implementation plans | Ordered, independently executable query-quality work plans |
| Grounded Agent Graph Overlay design | Ownership, Grounding, CRUD, composition, security, and history contracts for agent-authored graph enhancement |
| Grounded Agent Graph Overlay execution plan | Phased implementation, verification, qualification, and release record for the overlay |
Compass documentation uses four document types:
Concept explains what something means and why it exists
Guide walks through a complete task
Cookbook solves one concrete scenario with a short recipe
Reference states an exact interface, option, format, or limit
This separation is deliberate. A guide should not force you through an exhaustive option table, and a reference should not hide a precise contract inside a long tutorial.
Substantial pages open directly with an overview and end with related pages and a recommended next step. Small diagrams are ASCII so they remain useful in any terminal. Larger architecture diagrams are checked-in SVG files with accessible titles and descriptions.
Some topics already have a single authoritative document. The learning guides summarize and link to these; they do not replace them:
- Compatibility ledger
- Migration guide
- Performance qualification
- Security policy
- Support guide
- Contribution guide
- Code of Conduct
- CompassQL language contract
If a summary and a canonical document ever disagree, follow the canonical document and open a documentation issue.
Compass is a Rust workspace that ships the compass executable. Structural
code and document extraction and graph queries run locally and do not require
Python, embeddings, a vector database, or runtime grammar downloads. OCR is
optional and local with Compass-managed verified models. Semantic provider
enrichment is separate and may contact the provider you explicitly configure.
The current release packaging and
platform guarantees are recorded in the
compatibility ledger, not inferred from what happens to
compile on one developer machine.
Next step: follow Getting started to build and query your first graph.