FastAST

AST graph memory that keeps agents fast and context-cheap

Comment

Inspiration

AI coding agents are powerful, but they still struggle with large repositories. They either paste whole files into the prompt and burn tokens, or guess from partial context and break structure. Watching agents fail on real multi-file codebases—missing callers, dropping imports, and losing the shape of a module—made the problem clear.

The inspiration was simple: agents should not read the whole repo every time. They should query a local memory of the codebase—symbols, calls, imports, communities—and receive only the evidence they need. FastAST was built to make that practical: parse once, store facts, retrieve tightly, and stay fully local.

What it does

FastAST is a local codebase memory engine for AI coding agents.

It walks a repository, parses source with Tree-sitter across multiple languages, extracts symbols and relationships, and stores them in a SQLite-backed code graph. Agents connect through MCP or CLI and can:

  • index a repository into a persistent local graph
  • search symbols with hybrid ranking (heuristic + BM25 + semantic)
  • expand bounded call/import neighborhoods
  • retrieve token-aware evidence bundles instead of full files
  • explore communities, similar symbols, and file outlines
  • inspect the graph through a local web UI

Supported languages include Python, JavaScript/JSX, TypeScript/TSX, Java, Rust, HTML, CSS, JSON, and TOML. The system is offline-first: no cloud index, no forced remote model, and no requirement to dump entire files into the prompt.

How we built it

FastAST is layered as a cascade of relevance filters, not a single “prune button.”

  1. Discovery — walk the repo, respect ignore rules, classify files, hash content, and admit only useful source/config/docs
  2. Parsing and fact extraction — Tree-sitter multi-language AST visitors extract symbols, imports, calls, and structural edges
  3. Graph storage — SQLite stores files, symbols, edges, FTS5 lexical indexes, embeddings, communities, and similarity links
  4. Retrieval — ranked candidate search, bounded neighborhood expansion, and compact evidence selection under token budgets
  5. Agent surface — FastMCP tools and a CLI (fastast index, query, graph, evidence, communities, serve)
  6. UI — a Vite + React graph lens for connected-symbol exploration, inspectors, and evidence views

The compute-heavy path stays native where it matters (Rust / Tree-sitter / PyO3). Python owns orchestration, SQLite, MCP, and packaging so the project can ship as a normal pip / uv package.

Challenges we ran into

The hardest problems were not “can we parse code,” but “can we keep the graph useful without drowning the agent.”

  • Multi-language AST edge cases — decorators, abstract methods, JSX/TSX, nested scopes, and language-specific stubs all needed correct extraction
  • Graph noise — raw call graphs over-connect; confidence thresholds, relation filters, and neighborhood caps were required
  • Token discipline — returning whole files is easy; returning minimal high-signal evidence is not
  • Incremental indexing — re-indexing everything is too slow; hash/mtime skip logic and cascade deletes had to stay correct
  • Visualization truthfulness — early UI versions looked sparse or globe-like; matching a real connected-graph feel forced redesign of layout and draw budgets

Accomplishments that we're proud of

  • A complete local pipeline: discovery → AST facts → graph → hybrid retrieval → evidence bundles
  • Multi-language support with real symbol and edge extraction, not just file listing
  • MCP tools that coding agents can call at runtime without sending the whole repo
  • Hybrid search (structural + BM25 + semantic) with compact ranked output
  • Community detection and similarity links that expose structure beyond single-file views
  • A working CLI + API + UI stack on top of the same SQLite memory

What we learned

Codebase intelligence is less about one clever algorithm and more about layered pruning:

  • prune files before parsing
  • prune syntax into facts
  • prune weak edges
  • prune candidates by rank
  • prune neighborhoods by depth and fan-out
  • prune output by token budget

We also learned that agents need structured memory, not just faster prompt compression. A call graph and evidence bundle change agent behavior more than shaving a few lines from a single file.

What's next for FastAST

  • Stronger production packaging (cross-platform wheels, simpler install)
  • Deeper language fidelity and better type-aware call resolution
  • Faster incremental updates and watch mode for live repos
  • Tighter agent workflows: change-impact, related tests, and task-scoped evidence packs
  • UI polish toward a true connected-graph explorer
  • Optional stronger local embedding backends while staying offline by default

FastAST’s direction is unchanged: make local repository memory the default interface between coding agents and large codebases.

Built With

Share this project:

Updates

Submission history