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.
Who this page is for: evaluators, Compass users, integrators, and contributors.
You will learn: where to start, which documents answer which questions, and which material describes current behavior versus future direction.
Prerequisites: none.
Reading time: about 5 minutes.
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.
- Security and privacy — see what stays local and when a configured provider may be contacted.
- Compatibility and performance — inspect the published evidence.
Start with Getting started, then choose the task closest to yours:
- Explore an unfamiliar codebase
- Integrate Compass with other tools
- Set up a coding assistant
- Use versioned graph history
- Operate watch, serve, hooks, and providers
- Solve a concrete problem
- Look up commands and contracts
Read these in order when you need a durable mental model of the Rust workspace:
- Design principles
- System architecture
- Language architecture
- Workspace and crate tour
- Extraction pipeline
- Universal evidence implementation
- Query engine
- Semantic pipeline
- Extending Compass
- Contributing
| Document | What it answers |
|---|---|
| How Compass works | How does a directory become a queryable graph? |
| Graph model | What do the entities and relationships mean? |
| Provenance | How can I judge where an edge came from? |
| 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 |
| 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 |
| Operations | Safe operation of long-running and optional surfaces |
| Document | Focus |
|---|---|
| Design principles | Local-first, deterministic, bounded, inspectable behavior |
| Architecture | Major layers and the data that crosses them |
| Language architecture | Grammar, adapter, evidence, resolution, and transition boundaries |
| Storage and history | Incremental artifacts and immutable historical realizations |
| Security and privacy | Trust boundaries, credentials, and offline behavior |
| Document | Focus |
|---|---|
| Workspace tour | Which crate owns which responsibility |
| Extraction pipeline | Discovery through atomic output publication |
| Universal evidence | Language contracts, crate boundaries, resolution, and qualification |
| Query engine | Discovery queries, traversal, and CompassQL |
| Semantic pipeline | Optional provider-backed extraction |
| Extending Compass | Adding languages, relations, integrations, and commands |
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 |
| Compatibility | Compass contracts, hard cutovers, and portability |
| CompassQL 1 | Canonical language and runtime contract |
| CompassQL support | Checked syntax and feature matrix |
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 begin with their audience, outcomes, prerequisites, and estimated reading time. They 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.
Compass evolves quickly, so future-facing documentation uses explicit labels:
- Available now means the behavior is implemented and supported by current source, help text, tests, or release evidence.
- Planned means a committed design or implementation plan describes the work. A plan is evidence of intent, not evidence that the feature has shipped.
- Aspirational means the idea expresses a direction or problem worth exploring. It has no promised release, compatibility, or delivery date.
See the roadmap for the combined view.
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 extraction and graph queries run locally and do not require Python,
embeddings, a vector database, or runtime grammar downloads. Semantic
extraction for documents and other non-code sources is optional 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.