Historical — February 2026. The architecture described below was removed from Atlarix in v14.9.0 (10 July 2026) and no longer exists.
Blueprint, the parser, the graph, the file watcher and the whole index were deleted — about 5,246 lines — after the watcher was found to hold one open file descriptor per watched file, reaching roughly 12,365 of them on a large repository and breaking every child process the app tried to spawn.
Atlarix today has no index of any kind. Retrieval is purely lexical: bundled ripgrep (
grepandglob) over the open workspace, with no embeddings, no vector store, no structural graph and nothing running in the background. Project memory survives, but as plain notes on disk rather than a parsed graph.The problem this post opens with is real and I still think it is the right problem. The solution in it is not the one that shipped. Current architecture: atlarix.dev/docs.
There's a specific frustration every developer using AI coding tools knows.
You open a project you've been on for months. You ask the AI something reasonable — "how does our auth flow connect to the user service?" — and it either makes something up, asks you to paste files, or tells you it doesn't have access to your codebase.
So you paste the files. You explain the structure. You give it context. It helps. You close the laptop.
Next session: same thing. From scratch. Every time.
That's what pushed me to build Atlarix. Not to make another AI chat interface, but to fix this specific problem — the AI having no real, persistent understanding of your project.
The Root Issue: Code Isn't a List of Files
Every tool that tries to "understand your codebase" by dumping raw files into context is solving the wrong problem.
Your codebase isn't a flat list of files. It's a graph. Functions call functions. API routes hit services. Services write to databases. Webhooks trigger workers. A class inherits from a base that three other classes also inherit from.
When a senior engineer who's been on a project for a year answers a question, they're not re-reading files. They're querying a mental graph they've built up. The question I kept asking myself was: what if the AI had that graph too?
What I Built: Parse Once, Query Forever (removed in v14.9.0)
Here's what Atlarix actually does when you open a project.
(This described Atlarix v3.x. None of it ships today.) It ran a parser across your codebase — TypeScript and Python right now, more coming — and extracts every meaningful node: API endpoints, functions, classes, database operations, webhooks, scheduled jobs, third-party calls. Each node gets typed and tagged. Then it builds a graph from those nodes and their relationships, and caches it as a Blueprint at ~/.atlarix/blueprints/{projectHash}/.
Full parse on most projects: under 30 seconds.
After that, when you asked the AI something, it didn't scan files. It queried the graph. Finds the relevant nodes. Injects only those into context. We're talking ~5K tokens instead of 100K. A file watcher updates affected nodes on save, so the graph stays current without you doing anything.
The practical difference:
Before: Ask question → AI scans everything → 100K tokens → slow, expensive, confused
After: Ask question → Query graph → inject relevant nodes → 5K tokens → fast, accurate
This was the core of what we called RTE + RAG — Round-Trip Engineering to build the graph, Retrieval-Augmented Generation to query it. Both were removed in v14.9.0. If you have read that Atlarix uses Round-Trip Engineering or a visual Blueprint, this post is where that came from, and it is out of date.
The Part I'm Most Proud Of: Project Memory That Actually Persists
The RAG system solves the "understanding" problem. But there's a second problem — remembering decisions.
Why did you choose this database? Why is that service structured that way? What's the rule about how auth tokens are handled?
Atlarix writes to .atlarix/memory.md automatically during context compaction (when a conversation gets long). When you start a new session, the AI reads it first. It's just a markdown file — you can edit it manually, version control it, whatever you want.
There's also .atlarix/spec.md — a model-created task breakdown the AI generates for complex features. Both are inspired by how Claude Code handles project memory. Simple idea, makes a huge quality-of-life difference in practice.
Building Visually: The Blueprint Canvas (removed)
The graph wasn't just for the AI to query. It was also the foundation of a visual architecture designer. (The canvas, the graph and the generated plan file are all gone.)
In Blueprint mode, you get a React Flow canvas. You can design your system visually — drag in containers (Auth API, Worker Service, DB Layer), add beacons inside them (specific routes, functions, handlers), draw edges between them. It looks like an actual system diagram because it's meant to be one.
The workflow I use for new features:
- Design the architecture in Blueprint
- Click "Generate Plan" — the AI compares Blueprint (desired) to Live (actual code), generates
ATLARIX_PLAN.md - AI implements one task per message, waits for review before the next
- Approve, iterate, ship
It's architecture-first development. Design before you code. The AI implements what you designed, not what it guesses you want.
The Agent System (and Why I Separated Permissions from Modes)
One decision I made early that I think was right: separate agent mode from permission mode.
Modes are about delegation:
- Direct — just you and the model, no agents
- Guided — orchestrator delegates flat to specialists (Research, Architect, Builder, Reviewer)
- Autonomous — agents can spawn sub-agents for complex multi-step work
Permissions are about what the AI can touch:
- Ask — read-only tools only
- Build — can write files and run commands
These are independent. You can run Autonomous mode in Ask permission (agents can plan and research but can't write anything) or Direct mode in Build permission (full write access, no delegation). Mixing them any way you want.
The reason this matters: a Reviewer shouldn't be writing code. A Research agent shouldn't be executing commands. The separation of concerns in the tool sets prevents the agents from stepping on each other's work.
What v3.0 Changed
The big v3.0 changes were less glamorous than the earlier features but genuinely important for daily use:
- Workspace storage and path resolution were reworked and now just work correctly
- The
.atlarix/folder system is solid —memory.mdandspec.mdreliably persist across sessions - Relative paths in
create_directoryand file tools resolve correctly to the workspace root
Sometimes the most important release is the one that makes the existing stuff reliable.
What I'd Do Differently
A few honest things I'd change if I were starting over:
Start with SQLite sooner. The Blueprint was JSON-cached, and full ANTLR4 parsing with SQLite persistence was on the roadmap. Neither shipped — the whole index was deleted first, and in hindsight that was the right call rather than a missed one.
Fewer providers at launch. Supporting 8 cloud providers + AWS Bedrock + Ollama + LM Studio sounds like a feature. In practice, it's a lot of surface area to maintain. I'd have launched with 3 and expanded.
The permission UI took longer than expected. Getting the approve/reject flow right — where the AI proposes every file change and you see a diff before anything runs — was worth it, but it was the part I most underestimated.
Website: https://atlarix.dev
If you've hit the same wall with AI coding tools — re-explaining your project every session, blowing token budgets on raw context, wishing the AI actually understood your architecture — I'd love to hear if this solves it for you.
And if you've built something similar or tackled the codebase-as-graph problem differently, genuinely curious how you approached it. Drop it in the comments.
Where this ended up
Five months after this post, I deleted all of it. The file watcher was holding one
open file descriptor per watched file and hit roughly 12,365 on a large repository,
which broke process spawning outright; the index rebuilds also kept a laptop warm
for no measurable gain over plain search. Atlarix now uses bundled ripgrep and
nothing else — no index, no embeddings, no watcher, constant memory at any repo size.
I wrote up what that cost and what it taught here: atlarix.dev/blogs.
Top comments (0)