Auryn
Turn any codebase into a queryable knowledge graph — so your AI agent answers from real structure instead of grepping and guessing.
Quickstart · Agent setup · Languages · Docs
Works with Claude Code · Cursor · Windsurf · any MCP client
Point it at a repo. It parses every file, builds a graph of functions, types, tables and
endpoints — plus the edges between them (CALLS, EXTENDS, READS/WRITES, DEPENDS_ON) —
and stores it in FalkorDB. Your coding agent then traverses that
graph through MCP and cites file and line for every claim.
Sixteen languages. Live SQL and Oracle schemas too. No server, no Docker to get started.
Quickstart
Two commands, zero infrastructure. You'll be looking at a real graph in about a second.
pip install falkordb-auryn
auryn quickstart
This boots FalkorDB embedded (in-process, no daemon), ingests a tiny payments API that ships inside the package, and opens the viewer at http://127.0.0.1:8080.
Your own project is the same command with a path:
auryn quickstart path/to/your/repo
The graph persists at <path>/.auryn/graph.db, so re-running reuses it. First pass parses
everything; after that, re-ingestion is a delta — unchanged files are a no-op.
Requirements — Python ≥ 3.12.
falkordb-aurynis batteries-included: every language plugin out of the box. The in-process database is fetched automatically on firstauryn quickstarton macOS / Linux (recent glibc); on native Windows or older-glibc Linux, point at a remote FalkorDB viaauryn install --backend remote. Add live-DB drivers with"falkordb-auryn[all]". For an isolated tool install, include the DB up front:uv tool install "falkordb-auryn[embedded]". From a clone?uv syncthenuv run auryn quickstart.
Give your agent the graph
The viewer is a one-shot look. The real payoff is your agent querying the graph itself. Install once:
auryn install
That prompts for a FalkorDB backend — local (bundled server, starts on demand) or
remote (host/port/creds) — then registers the auryn MCP server and skill with every
agent it detects. It writes only to ~/.auryn and the agent's own config. Never your repo.
From there it's just conversation:
You: What breaks if I change the signature of
charge_card?
● auryn_status() → no graph for this repo yet
● index_repository(path=".") → indexed: functions, calls, endpoints, inheritance
● locate(name="charge_card") → Function app/billing.py:9 id: python://…charge_card(...)
● impact_of(id="python://…charge_card(...)", edge_types=["CALLS"])
→ create_charge (app/api.py) ──EXPOSES_ENDPOINT──▶ POST /charges
Agent: A blast radius of one direct caller:
create_chargeinapp/api.py, which handles POST /charges — so the endpoint's contract changes with it.charge_carditself callsget_account,_guard_limitandConnection.execute; none are affected by a signature change. Updatecreate_chargeand the/chargesrequest shape together. (citesapp/api.py:15,app/billing.py:9)
No raw Cypher, no file dumps, no guessing. One hop, id-backed. Each repo gets its own graph.
Your code stays yours. Everything runs on your machine or your own FalkorDB — self-hosted,
no hosted service in the path, no telemetry, no phoning home. Read tools issue only
GRAPH.RO_QUERY, so an agent is structurally incapable of writing to your graph, and install
touches nothing but ~/.auryn and your agent's config.
The tools your agent gets
| Tool | What it does | |
|---|---|---|
auryn_status |
read | Is there a graph yet, and what's in it? Called first. |
index_repository / ingest_repository |
write | Build or update the graph for a local dir or git repo. |
locate |
read | Find symbols by name — the entry point; other tools take the id it returns. |
search_code |
read | Semantic (vector) search by meaning when you don't know the name — needs auryn embed first. |
get_context |
read | One node's properties, source, and 1-hop neighbours. |
who_calls / callees |
read | Inbound callers / outbound callees within N hops. |
find_path |
read | Shortest path between two nodes — "does X reach Y, and how." |
impact_of |
read | Blast radius over CALLS/DEPENDS_ON/READS/WRITES. |
trace_entrypoint |
read | Full call closure of an entry point, plus every table it touches. |
get_schema / run_cypher |
read | The meta-model; arbitrary read-only Cypher. |
list_graphs / use_graph switch between multiple graphs on one instance.
Why a graph
| Question | grep | Auryn |
|---|---|---|
| Who calls this? | every textual match, no callers of callers | exact inbound edges, N hops deep |
| What breaks if I change it? | you read and hope | traversal with file:line citations |
| Does this endpoint touch that table? | unanswerable | one path query |
| Is the answer current? | always re-read | delta re-ingest; unchanged code is free |
What it can read
Everything file-based is auto-detected by auryn ingest in a single pass. Live
databases are read via auryn run <name>. pip install falkordb-auryn includes every language by
default; for a lean, single-language install instead, pip install auryn-python (each plugin pulls
auryn-core).
All sources and engines
| Source | Extra | Engine |
|---|---|---|
| Python | [python] |
tree-sitter → Jedi (deep) |
| TypeScript / JavaScript | [typescript] |
tree-sitter |
| C# | [csharp] |
Roslyn (deep), tree-sitter fallback |
| Java · C · C++ · CUDA | [java] [c] [cpp] [cuda] |
tree-sitter |
| Go · Rust · PHP · Julia | [go] [rust] [php] [julia] |
tree-sitter |
| Ruby · Kotlin · Swift · Bash | [ruby] [kotlin] [swift] [bash] |
tree-sitter |
| PL/SQL files | [oracle] |
vendored ANTLR |
| Oracle (live DB) | [oracle-live] |
oracledb + ANTLR |
| SQL schema (live DB) | [sql] [sql-all] |
SQLAlchemy, any dialect |
The deep C# engine needs the .NET SDK on PATH; without it,
C# falls back to tree-sitter automatically.
CLI
auryn ingest dir /path/to/repo --project-name MyApp # auto-detect every language
auryn ingest repo https://github.com/you/repo.git --ref main
auryn view # open the viewer against the configured backend
auryn serve | stop # run/stop the local FalkorDB daemon explicitly
auryn uninstall [--purge] # reverse install
Omit --host/--port and it uses the backend from auryn install. Full reference:
docs/cli.md, or auryn <command> --help. Runnable walkthroughs live in
demo/.
Documentation
| Architecture | Plugin discovery, the ingest pipeline, delta-sync, backends. |
| Graph model | Labels, edges, ids, provenance — and what each ingestor extracts. |
| CLI reference | Every command and flag. |
| Adding a language | A worked, line-by-line new ingestor. |
| Docs index | Everything, including the ADRs. |
Contributing
uv sync --group dev
uv run pytest --cov=auryn --cov-report=term-missing
Tests run against embedded FalkorDB by default — no server, no Docker. Set
AURYN_TEST_BACKEND=server for a real one. New language ingestors are very welcome: start
at CONTRIBUTING.md.
Built by FalkorDB
Metadata
Release files for falkordb-auryn 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| falkordb_auryn-0.1.0.tar.gz | 3.9 MB | Without provenance | Details for falkordb_auryn-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| falkordb_auryn-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for falkordb_auryn-0.1.0-py3-none-any.whl |
Total release size: 4.0 MB
Release files / falkordb_auryn-0.1.0.tar.gz
| Download URL | falkordb_auryn-0.1.0.tar.gz |
|---|---|
| Size | 3.9 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
8dc72fe69f1a0fa1c46c0f753c7c2dad48dabca3d27088f6c075015f2cba0d0a
|
|
BLAKE2b-256 checksum How to use checksums |
78068046f0301ddbf57181471aec79847e2732dd0ad9bc07972383e5fe4c9392
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.8 {"installer":{"name":"uv","version":"0.13.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / falkordb_auryn-0.1.0-py3-none-any.whl
| Download URL | falkordb_auryn-0.1.0-py3-none-any.whl |
|---|---|
| Size | 16.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d9239ab92ee3f93c3cd6c543b9b4f2eac17a70b59100357c09a53e3176349305
|
|
BLAKE2b-256 checksum How to use checksums |
9c01633516f88470ba4d66e9c7c672bc536507c4d9574701ae6d1d14b4015999
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.8 {"installer":{"name":"uv","version":"0.13.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for falkordb-auryn 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.