Atlas: Engineering Memory Engine

Atlas answers what no dev tool does: why does this code exist? It reconstructs engineering intent from your repo's real history: the incident, the ADR, the PR, without leaving VS Code.

Comment

Inspiration

Every engineer has hit the same wall: you open an unfamiliar function and it looks wrong. Too defensive. A retry loop that shouldn't be there. A cache that seems redundant. So you "simplify" it and take down production, because that code was the fix for an outage two years before you joined.

The knowledge that explains code exists. It's in the incident write-up, the ADR, the PR discussion, the Slack thread where three people argued about it. But it's scattered across five systems, and none of them are where you're actually working.

Copilot and Cursor answer how do I write this. GitHub answers what changed. Nothing answers why does this exist, the question that decides whether you should touch it. That gap is where outages come from, and where onboarding time goes.

What it does

Highlight a function in VS Code, hit Ask Atlas, and get an answer grounded in your repository's real history:

  • a one-sentence explanation with a calibrated confidence score
  • key reasons tied to actual artifacts
  • typed citations including the commit, the PR, the incident, the ADR, the Slack thread

Then three more views:

  • 🎬 Decision Replay is a narrated timeline of why the code evolved. On the demo repo: basic auth (2022) → OAuth for enterprise SSO (2023) → INC-284, an OAuth outage that force-logged-out enterprise users → the post-mortem → ADR-012 → PR #842 adding the retry and Redis session fallback.
  • 💥 Impact Analysis is "what breaks if I remove Redis?" Risk level, blast radius across services, likely failures, and a migration path.
  • 🕸️ Knowledge Graph is the developer → decision → commit → code → incident subgraph the reasoning actually ran over.

The confidence is real, not decoration. Ask about rotateRefresh and Atlas returns 0.97, correctly tying it to the post-INC-284 session model. Ask about charge and it returns 0.46 and volunteers "the evidence does not contain a clear…". It tells you when it doesn't know, which is the only thing that makes the 0.97 worth trusting.

How I built it

Not plain RAG. A single similarity search cannot explain why code exists, because the answer usually lives one or two hops away, the PR that changed the function, the incident that motivated the PR. So Atlas builds an engineering-memory knowledge graph first, then reasons over it.

Repository ─▶ Indexer ─▶ Knowledge Graph ─▶ Embeddings ─▶ Reasoning ─▶ API ─▶ VS Code

Indexer. GitPython for commit history, tree-sitter for language-agnostic symbol extraction, and parsers for ADRs, incident write-ups, PR bodies and Slack exports. Reference extraction turns "fixes #284" and "see ADR-012" into real graph edges that regex is what converts prose into a traversable causal chain.

Retrieval fuses three signals, not one:

$$\text{score} = w_{sem}\cdot\text{similarity} + w_{graph}\cdot\text{proximity} + w_{rec}\cdot\text{recency}$$

The graph-proximity term is the whole idea. It's the difference between returning the nearest document and explaining the decision.

Reasoning is an explicit LangGraph StateGraph — collect → traverse → reason → synthesise so every stage is inspectable, with GPT-5.6 at the reason step under a strict JSON contract. The prompts forbid inventing artifacts and require confidence to track evidence strength, so the model reasons rather than embellishes.

Frontend is a React webview (Vite, Tailwind, Framer Motion) that inherits the VS Code theme, talking to a FastAPI backend through a typed client. Storage sits behind an interface: in-memory by default so the demo runs with zero dependencies, Postgres + pgvector for the production path.

Distribution was treated as part of the product. A hosted backend on Render has the demo repository baked into the image and pre-indexed on boot, so the extension ships pointing at it. setup.sh builds everything in about a minute, and a prebuilt .vsix is attached to the GitHub release. A judge installs one file, opens the sample repo, and sees a populated answer, no API key, no database, no local backend.

Codex accelerated the mechanical layers, the FastAPI surface, the TypeScript ⇄ Python type mirroring, the tree-sitter walker, the reference regexes, and translating the mockup into theme-aware components which kept human effort on architecture. Those decisions are recorded as ADRs in the repo.

Challenges I ran into

The citations were starving. The Ask card kept showing only two sources and the Timeline was nearly empty, even though the graph plainly contained the incident and the ADR. The cause was subtle: retrieval returned a top-8 evidence set, but code symbols outrank narrative artifacts on graph proximity and code symbols are never citeable. They ate the entire budget. It got worse as the graph got better: adding real commit history densified the graph and pushed the PR and ADR out completely. The fix was separating the two budgets — retrieve well past what you cite, and let the citation cap do the trimming. Sources went 2 → 6, timeline 2 → 6.

A second bug hid behind the first. "Learn More" showed no related discussions, ever. The Slack thread was being filtered out of an already-truncated six-item list, so it could never appear no matter how well it ranked. Keeping the full ranked list and capping only the display fixed it.

A hosted backend can't see the user's filesystem. The extension sends a local path to index meaningless to a container. Solved by baking the demo repo into the Docker image, building its git history at image-build time, pre-indexing on boot, and making the repo-identity derivation agree on both sides so the client skips indexing entirely.

Features nobody could find. Replay and Impact were reachable only from the command palette, so both tabs opened empty with a line of text telling you to run a command you had no way to discover. Watching someone conclude the feature was broken, when the backend was returning perfect data was the sharpest lesson of the build. Both empty states are now buttons.

Offline determinism. A demo that needs a network and an API key is a demo that fails on stage. Mock mode synthesises the same shape of answer from the same real retrieved evidence, so all four tabs populate identically with no key at all.

Accomplishments that I'm proud of

  • It reasons over real history, not keywords. The NOTE: comment in the demo says "see ADR-012 and incident INC-284". Atlas reconstructs that causal chain — the citations, timeline and graph are all derived by retrieval and graph traversal, none of it hardcoded. (The summary sentence for this one flagship function is a curated trace in seed/traces.json so the demo reads identically every run; ask about rotateRefresh or charge to watch the pipeline reason from scratch.)
  • Calibrated confidence. 0.97 where evidence is strong, 0.46 where it's thin, with the model saying so. Uncertainty you can act on.
  • Three minutes to a populated answer. Install one .vsix, open the sample repo. No key, no database, no backend.
  • It degrades gracefully at every layer. No Postgres falls back to in-memory, no API key falls back to grounded mock, an unavailable model falls back down a chain. Nothing about the demo is fragile.

What I learned

Retrieval budget and citation budget are different problems. Conflating them is what starved the sources, and the failure got worse as the underlying data got richer, the most misleading kind of bug, because real progress looked like regression.

Graph proximity is the whole ballgame for "why" questions. Semantic similarity finds documents about authentication. Graph proximity finds the incident that caused this authentication code. Only one of those answers the question.

Honest uncertainty is a feature. A tool that always claims 96% confidence is one engineers stop trusting the first time it's confidently wrong.

A feature nobody can find does not exist. Two of the four tabs were fully working and read as broken, purely because discovery was a command-palette entry. Shipping means shipping the path to the feature.

What's next for Atlas

  • More memory sources: Jira and Linear tickets, design docs, code review comments. Every system holding a piece of the "why".
  • Incremental indexing: so large monorepos stay current without full re-scans.
  • Team deployment: The hosted demo is deliberately a single instance with one key; the real shape is the Postgres + pgvector path deployed per-org, with per-workspace indexes and auth, so institutional memory outlives the people who created it.
  • Beyond VS Code: JetBrains, and a CLI for pre-merge checks: block the PR that "simplifies" away an incident fix.

Built With

Share this project:

Updates