Filesystem-based knowledge agents replace the usual chunk, embed, and vector-search pipeline with a file tree plus shell-like retrieval tools. Instead of precomputing embeddings for every document, the system syncs source material into readable files and lets the agent navigate with commands such as find, grep, cat, jq, and short pipelines. The agent retrieves only the files or spans it needs for the current task.
The pattern is useful when the corpus has strong natural structure: support histories, transcripts, product documents, repository files, CRM exports, runbooks, or generated Markdown. Dense retrieval is strong for semantic similarity, but it can be opaque when the question asks for an exact field, identifier, phrase, date, or prior decision. A filesystem makes retrieval inspectable: the trace shows which directories were explored, which command found the evidence, and which file was read.
Vercel’s knowledge-agent template demonstrates this architecture with a source database, scheduled content sync into a snapshot repository, sandboxed execution, and AI SDK-compatible bash and bash_batch tools. Their related bash-tool work frames the smaller primitive: keep large context local, preload a filesystem, and return compact command results instead of pasting the whole corpus into the prompt.
The memory substrate is a directory tree, not a vector index. Each source is normalized into files with stable paths, names, and formats. Metadata belongs near the content as JSON, YAML, front matter, or sibling files so the agent can inspect both the text and its provenance without a separate retrieval service.
The model receives tools for exploration and selective reading. It can list directories, search for exact phrases, count matches, inspect metadata, and read a focused file region. This gives the agent a procedural retrieval loop instead of a single opaque top-k call.
Search runs in a controlled environment containing the synced corpus. The sandbox can be a virtual shell implemented in TypeScript, an in-memory filesystem, or a full VM when real binaries are needed. The important boundary is that the agent explores a prepared corpus, not the production host filesystem.
A filesystem knowledge agent turns retrieval into a visible sequence of commands. When the answer is wrong, engineers can inspect whether the file tree, search command, path choice, or prompt policy caused the failure.
The ingestion layer pulls external sources into a canonical repository or object snapshot. Each sync should produce deterministic paths, stable filenames, and normalized text formats. For binary documents, the pipeline should extract readable text while preserving the original asset path and extraction status.
knowledge/
customers/
cust_12345/
profile.json
tickets/
ticket_001.md
ticket_002.md
conversations/
2026-03-15.txt
documents/
extracted/
contract_abc123.txt
analysis/
contract_abc123/
summary.md
key_terms.json
runbooks/
authentication.md
incident-response.mdThe agent does not need arbitrary host access. A narrow tool surface is enough: list files, search text, read files, inspect structured data, and run bounded batches. Batching matters because retrieval often needs several cheap commands before the model has enough evidence.
import { generateText } from "ai";
import { createSavoir } from "@savoir/sdk";
const savoir = createSavoir({
apiUrl: process.env.SAVOIR_API_URL!,
apiKey: process.env.SAVOIR_API_KEY,
});
const result = await generateText({
model,
tools: savoir.tools,
maxSteps: 10,
prompt: "Find the authentication runbook and summarize the rollback steps.",
});A good retrieval trace looks like ordinary command-line investigation. The agent lists available domains, searches for candidate terms, reads exact files, and only then writes an answer. Because each step is logged, humans can reproduce or improve the retrieval strategy.
# Explore available domains.
find knowledge -maxdepth 2 -type d | sort
# Search for exact evidence.
grep -Rni "rollback" knowledge/runbooks knowledge/documents/extracted | head -20
# Read the selected source.
sed -n "1,140p" knowledge/runbooks/authentication.mdSupport histories, account profiles, transcripts, and issue records often have identifiers, timestamps, statuses, and exact phrases. Filesystem search lets the agent locate those exact artifacts without relying on embedding similarity between short fields.
For contracts, invoices, research packets, or compliance packages, place extracted text, generated summaries, key-value metadata, and review artifacts in predictable directories. The agent can compare the raw extraction with prior analysis and avoid reprocessing the whole bundle.
Runbooks, deployment logs, incident timelines, and configuration exports are often easier to search lexically than semantically. A filesystem agent can grep for error codes, inspect recent files by path, and cite exact operational evidence in its response.
The tree shape is part of the model interface. Use stable nouns, predictable nesting, short filenames, and explicit metadata files. Avoid dumping every record into one huge file; split by the unit the agent is likely to retrieve, such as one ticket, one transcript, one account, one contract, or one runbook.
type SourceFile = {
path: string;
sourceId: string;
sourceType: "repo" | "ticket" | "transcript" | "document" | "runbook";
updatedAt: string;
contentHash: string;
};
function targetPath(file: SourceFile): string {
return `${file.sourceType}/${file.sourceId}/${file.contentHash.slice(0, 8)}.md`;
}Tool responses should be bounded by line count, byte count, timeout, and output type. A failed search should return the command, exit code, and a small stderr preview; it should not dump an entire directory or binary file into the model context.
Plain commands are a strong baseline, but larger corpora benefit from local full-text indexes, SQLite tables, ripgrep caches, or precomputed manifests. These are still file-first systems when the index routes the agent back to readable paths and exact evidence.
grep is precise but can miss paraphrases. Use aliases, normalized fields, tags, and optional semantic fallback when users ask conceptual questions.