astria

<div align="center">

# astria

**Knowledge graph builder for codebases**

[![CI](https://github.com/Nodesify/astria/actions/workflows/ci.yml/badge.svg)](https://github.com/Nodesify/astria/actions/workflows/ci.yml)
[![npm](https://img.shields.io/npm/v/@nodesify/astria)](https://www.npmjs.com/package/@nodesify/astria)
[![npm downloads](https://img.shields.io/npm/dm/@nodesify/astria)](https://www.npmjs.com/package/@nodesify/astria)
[![docs](https://img.shields.io/badge/docs-latest-blue)](https://nodesify.github.io/astria/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Node](https://img.shields.io/badge/node-22-339933?logo=nodedotjs&logoColor=white)](https://nodejs.org/)
[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/Nodesify/astria)

[Docs](https://nodesify.github.io/astria/) | [Getting started](https://nodesify.github.io/astria/docs/getting-started) | [CLI Reference](https://nodesify.github.io/astria/docs/reference/cli) | [Architecture](ARCHITECTURE.md) | [Worked examples](worked/) | [Changelog](CHANGELOG.md) | [Release notes](https://nodesify.github.io/astria/blog)

</div>

Understand a codebase before you touch it. `astria` turns any folder into a queryable knowledge graph — deterministic AST extraction in Rust, optional local-embedding semantics, zero API keys, everything on your machine.

astria is inspired by the Python [Graphify](https://github.com/safishamsi/graphify) project's core idea — turn a corpus into a queryable knowledge graph — but it is an independent, from-scratch implementation: a deterministic, offline-first Rust/tree-sitter pipeline, not a fork or a port. astria is not affiliated with, sponsored by, or endorsed by the Graphify project or Graphify Labs.

Find source-grounded code context before changing a repository. Astria retrieves symbols, file locations, and relationships from the latest committed graph snapshot through the same CLI and MCP query engine. Updates reuse cached AST extraction and reconcile references across the current corpus; inferred name matches remain distinct from declared facts.

Retrieval quality and delivered context cost are measured separately. The [paired benchmark methodology](scripts/bench/paired/README.md) records file recall, source-grounded symbol checks, exact response tokens and failures. The [latest results](website/docs/explanation/retrieval-validation.md) include improvements and regressions. Historical full-corpus/query token ratios are size diagnostics, not measured savings over targeted source search. A measured first-shot comparison against a deterministic question-derived rg-plus-reads baseline is checked in at [worked/external-baseline/](worked/external-baseline/): ~207 delivered tokens per question put the defining file first for 8/8 external questions, while the baseline's 4,000-token responses never ranked it first — quality per delivered token against a single-pass search floor, not a claim about expert iterative search.

Code definitions retain their scoped identities during deduplication. Extraction includes assigned JS/TS functions and Python implementations behind overload declarations. Query text uses exact `o200k_base` budgets shared by CLI and MCP. After upgrading, run `astria update .` to refresh extraction and restore previously merged definitions; start fresh pagination because cursors now count both node and edge records.

Three things a folder full of files can't give you:

1. **Structure that survives the session** — hub files, god nodes, communities, and the blast radius of any change, stored in SQLite and refreshed incrementally as code changes.
2. **An honest audit trail** — every edge is labeled EXTRACTED / INFERRED / SEMANTIC / AMBIGUOUS with a numeric confidence score. You always know what was found in the source versus deduced versus LLM-enriched, and `--detail high` filters to only declared facts ([graph model](https://nodesify.github.io/astria/docs/reference/graph-model)).
3. **Answers for agents and humans** — query it from the CLI, from any AI agent via MCP, or just read the exported markdown wiki with plain file links.

[Worked examples with honest reviews](worked/) — the tool run on itself, including what the graph got *wrong* — plus a [head-to-head benchmark](worked/head-to-head/) against the Python Graphify project that inspired it, run on the same corpus. The full measurement stack — shared-tokenizer token parity, a golden-QA retrieval-quality harness (recall@k / MRR), blind LLM judging, and a LoCoMo memory adapter — lives in [`scripts/bench/`](scripts/bench/).

## Quick start

```bash
npm install -g @nodesify/astria
```

Requires no Rust toolchain — ships prebuilt native binaries via napi-rs.

Just want the agent skill, no CLI? `npx skills add Nodesify/astria` installs the graph-first skill from [skills.sh](https://skills.sh) - it answers from an existing `.astria/` graph as plain files and, when graph commands are needed, offers the install above (never without asking).

On Claude Code? One plugin bundles the MCP server, the skill, `/astria` + `/astria-risk` commands, and the `astria-architect` subagent: `/plugin marketplace add Nodesify/astria` then `/plugin install astria@nodesify`.

macOS/Linux without npm? `brew install nodesify/tap/astria` ([tap](https://github.com/Nodesify/homebrew-tap)).

```bash
astria run .                                  # build the graph (creates .astria/)
astria query "how does authentication work"   # ask the graph a question
astria map                                    # PageRank-ranked repo map for orientation
astria affected <node>                        # what breaks if you change this
```

Exclude files with a `.astriaignore` file in the project root (gitignore syntax). Everything astria writes lives in plain files under `.astria/` — [the full layout](https://nodesify.github.io/astria/docs/reference/directory-layout).

> **Migrating from `@nodesify/graphify`?** 1.0 is a rebrand: the binary is `astria`, the npm package is `@nodesify/astria`, and graphs live in `.astria/` instead of `.graphify/`. Run once after installing:
>
> ```bash
> astria migrate          # renames .graphify/ -> .astria/ and the global store
> astria install          # refreshes AI-tool skills/hooks (also cleans the old graphify entries)
> ```
>
> Legacy configuration variables remain supported where documented. LLM activation requires `--backend` or `ASTRIA_LLM_BACKEND`; `GRAPHIFY_LLM_BACKEND` does not opt in.

## Documentation

Full docs live at [nodesify.github.io/astria](https://nodesify.github.io/astria/) — versioned per release, with a `Next` page tracking unreleased work.

| | |
|---|---|
| **Getting started** | [Install and first graph](https://nodesify.github.io/astria/docs/getting-started) |
| **Guides** | [Agent integration (MCP + install)](https://nodesify.github.io/astria/docs/guides/mcp-and-agents) · [Wiki and exports](https://nodesify.github.io/astria/docs/guides/wiki-and-exports) · [Semantic enrichment](https://nodesify.github.io/astria/docs/guides/semantic-enrichment) · [Global graph](https://nodesify.github.io/astria/docs/guides/global-graph) · [Memory and learning](https://nodesify.github.io/astria/docs/guides/memory-and-learning) |
| **Reference** | [CLI](https://nodesify.github.io/astria/docs/reference/cli) · [MCP tools](https://nodesify.github.io/astria/docs/reference/mcp-tools) · [Environment variables](https://nodesify.github.io/astria/docs/reference/env-vars) · [Graph model](https://nodesify.github.io/astria/docs/reference/graph-model) · [The .astria directory](https://nodesify.github.io/astria/docs/reference/directory-layout) · [Language support](https://nodesify.github.io/astria/docs/reference/language-support) · [Troubleshooting](https://nodesify.github.io/astria/docs/reference/troubleshooting) |
| **Explanation** | [Architecture](https://nodesify.github.io/astria/docs/explanation/architecture) · [Benchmarks and evidence](https://nodesify.github.io/astria/docs/explanation/benchmarks) · [Retrieval validation](https://nodesify.github.io/astria/docs/explanation/retrieval-validation) |

### Feature highlights

- **Query it three ways** — CLI (`query`, `explain`, `path`, `affected`, `map`), an MCP server for AI agents, or an exported [markdown wiki](https://nodesify.github.io/astria/docs/guides/wiki-and-exports) any agent (or human) can crawl
- **Local embeddings, no API key** — `run --embed` adds `similar_to` edges and semantic query recall ([semantic enrichment guide](https://nodesify.github.io/astria/docs/guides/semantic-enrichment))
- **Optional LLM enrichment, measured and cached** — Claude, any OpenAI-compatible endpoint, or Gemini, with an optional Jev judge layer on top of any of them (`--judge jev`): the judge re-judges relations and node types from the schema allowlists, gives every semantic edge a calibrated confidence score, and can batch-gate trivial files and re-rank suggested questions before they cost engine calls. Vision included for images; per-run with `--backend`/`--model`/`--judge` or env vars. Thematic community naming (`run --label-communities`, one call per *changed* community) and a `--deep` concept-linking tier (one call per changed file) are content-hash cached, so unchanged inputs and effective configuration can reuse cached output. Backend selection is explicit; credentials alone never activate enrichment. Every response's usage block is counted — the run summary prints API calls and input/output tokens, and `ASTRIA_LLM_BUDGET` caps the spend ([semantic enrichment guide](https://nodesify.github.io/astria/docs/guides/semantic-enrichment))
- **Cross-repo global graph** — merge many repos into one queryable store at `~/.astria/global.db` ([global graph guide](https://nodesify.github.io/astria/docs/guides/global-graph))
- **The graph compounds with use** — repeated queries become `learned` edges; curated Q/A memory via `save-result`/`reflect` ([memory and learning](https://nodesify.github.io/astria