Deterministic AI Context for IDE AI agents.

When working with large enterprise codebases, sequential file exploration fundamentally breaks the AI context window. Naive tools like grep or basic AST tree-sitters retrieve raw files blindly. When an agent traces a single bug, it often pulls in 50+ files containing thousands of irrelevant lines of boilerplate, imports, and disconnected logic.

This rapid context bloat guarantees two failure modes. First, the LLM exceeds its context limit and crashes the session. Second, even if the prompt fits, the sheer volume of noise dilutes the attention mechanism. This leads to severe hallucinations where the model invents dependencies or confidently suggests calling methods that do not actually exist in your architecture.

Foldwork replaces black-box vector embeddings with a deterministic, graph-based ingestion pipeline. It uses an incremental AST parser to read your codebase, immediately mapping out two distinct structures: a Symbol Graph containing every interface, class, and function signature, and a Dependency Graph tracking outbound caller/callee relationships.

These graphs are durably stored in a local SQLite catalog. We chose SQLite because it offers robust ACID guarantees, requires zero external dependencies, and supports sub-millisecond querying via FTS5. This local-first catalog means indexing happens exactly once per file change, not on every AI prompt.

When an AI agent requests context, it communicates with the Foldwork Retriever via the Model Context Protocol (MCP). The transport layer securely bridges the gap to the LLM, enabling the agent to fetch precisely the right sub-graphs without the repository ever leaving your machine.

Trust in developer tools is earned through predictability. Foldwork is built around canonical determinism: by alphabetically sorting directory trees, stripping non-semantic metadata, and applying consistent formatters before cataloging, we ensure that the same repository state always produces the exact same byte-for-byte retrieval output.

This strict determinism is not just an architectural purity goal—it has massive financial implications. Because Anthropic's KV prompt cache requires identical prefix matching, Foldwork's predictable outputs guarantee that subsequent Claude sessions hit the cache 100% of the time, reducing API costs by up to 90% while dramatically accelerating response times. Furthermore, the local-first, air-gapped architecture ensures that your proprietary intellectual property never leaves your machine for indexing.

A tool that takes 5 minutes to index your codebase is useless for a developer in the middle of a debugging session. Foldwork is engineered for instantaneous feedback. By utilizing a highly optimized, single-pass AST parser combined with the zero-overhead FTS5 indexing of SQLite, we achieve indexing speeds that feel entirely synchronous.

Memory footprint is equally critical. Heavy IDE plugins and language servers often consume gigabytes of RAM, starving the host machine. Foldwork's daemon idles at approximately 45MB, ensuring your local environment remains snappy even when working inside massive legacy monorepos.

However, FTS5 tokenizers are notoriously bad at searching for hardcoded punctuation or exact regex patterns. Foldwork solves this with the injector_regex_search tool, which acts as a hybrid engine that gracefully bridges into native git grep -nE/-nF, giving the AI agent flawless literal and regex matching capabilities when semantic search isn't enough.

* Measured locally using the Foldwork benchmarking suite. Results are reproducible by running the benchmark tool against the same repository and environment.

Foldwork is not a weekend prototype; it is an enterprise-grade daemon designed to survive the chaos of real-world development environments. When you switch Git branches containing thousands of file changes, Foldwork gracefully handles the churn through a robust event-debouncing mechanism that prevents redundant re-indexing operations.

When indexing massive 100,000+ file monorepos, hitting Linux inotify file-watcher limits (ENOSPC) is guaranteed. Foldwork doesn't just crash; it safely pauses, opens a direct /dev/tty interactive bridge to prompt the developer to scale their OS limits (via sysctl), and dynamically resumes indexing without requiring a restart.

We've also implemented strict OOM (Out Of Memory) protections that abort operations on pathological files (e.g., a 5MB minified JSON file) rather than crashing the daemon. Automatic schema versioning ensures that when you upgrade the Foldwork binary, the local SQLite catalog is seamlessly migrated without requiring manual cache purges.