Build knowledge agents without embeddings

Filesystems over vector databases

Most knowledge agents are built on a familiar architecture: pick a vector database, design a chunking pipeline, choose an embedding model, and tune retrieval parameters. This stack works well for semantic similarity but breaks down when the question calls for a specific value inside structured data. The failure is often silent — the agent confidently returns the wrong chunk, and there is no clear path from question to answer.

Vercel took a different route with its open-source Knowledge Agent Template. Instead of embeddings, the agent gets a filesystem and bash. For the company’s sales call summarization agent, this shift cut costs from roughly $1.00 to $0.25 per call while improving output reliability.

How the file-based agent works

The template eliminates the vector database, chunking pipeline, and embedding model entirely. All search happens inside isolated Vercel Sandboxes using standard Unix commands: grep, find, and cat.

The request flow is straightforward:

1. Sources are added through the admin interface and stored in Postgres.
2. Content syncs to a snapshot repository via Vercel Workflow.
3. A Vercel Sandbox loads the snapshot when the agent needs to search.
4. The agent’s bash and bash_batch tools run filesystem commands.
5. The agent returns an answer with optional references.

This approach makes results deterministic, explainable, and fast. When the agent returns a bad answer, you inspect the trace: it ran grep -r "pricing" docs/, opened docs/plans/enterprise.md, and read the wrong section. Fixing the problem means editing the file or adjusting the search strategy — a debugging loop that takes minutes. With vectors, you would have to identify which chunk was retrieved, understand why it scored 0.82 while the correct chunk scored 0.79, and then guess whether the issue was chunk boundaries, the embedding model, or the similarity threshold.

LLMs already understand filesystems. They have been trained on vast amounts of code, which means they know how to navigate directories, run grep, and manage state across codebases. If agents perform well on filesystem operations for code retrieval, the same skill applies to any other data store. No embedding pipeline to maintain, no vector database to scale — just add a source, sync, and search.

Deploying one agent across platforms

A single agent can serve one knowledge base and one codebase, but users and engineers live in different places: Slack, Discord, GitHub, Microsoft Teams. Chat SDK connects the same agent pipeline to every platform your users are on through adapters.

Each adapter abstracts platform-specific concerns like authentication, event formats, and messaging. The agent logic itself never changes. An onNewMention handler fires whenever the bot is mentioned, regardless of platform, and the agent streams its response back to the thread via the same filesystem-backed pipeline.

import { Chat } from "chat";
import { createSlackAdapter } from "@chat-adapter/slack";
import { createDiscordAdapter } from "@chat-adapter/discord";
import { createRedisState } from "@chat-adapter/state-redis";
const bot = new Chat({
  userName: "knowledge-agent",
  adapters: {
    slack: createSlackAdapter(),
    discord: createDiscordAdapter(),
  },
  state: createRedisState(),
});
bot.onNewMention(async (thread, message) => {
  await thread.subscribe();
  const result = await agent.stream({ prompt: message.text });
  await thread.post(result);
});

GitHub and Discord adapters ship with the template, and Chat SDK also supports Slack, Microsoft Teams, Google Chat, and others via its adapter directory. Teams that need custom integrations can build their own adapters.

AI SDK tools and model routing

The @savoir/sdk package provides tools that connect any AI SDK-powered agent to a knowledge base. Import the tools, point the client at your instance URL, and pass them into the agent. If you plan to extend and publish the SDK, customize the package name from @savoir/sdk to your own.

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 { text } = await generateText({
  model: yourModel, // any AI SDK compatible model
  tools: savoir.tools, // bash and bash_batch tools
  maxSteps: 10,
  prompt: 'How do I configure authentication?',
})
console.log(text)

The template also includes a complexity-based router that classifies each incoming question and directs it to an appropriate model. Simple questions land on fast, inexpensive models; harder questions go to more powerful ones. Cost optimization happens without manual rules. Any AI SDK model provider works through Vercel AI Gateway.

Administration and observability

A built-in admin interface covers usage statistics, error logs, user management, source configuration, and content sync controls — no external observability tooling required.

An AI-powered admin agent answers operational questions directly, such as "what errors occurred in the last 24 hours" or "what are the common questions users ask." It relies on internal tools including query_stats, query_errors, run_sql, and chart to produce answers.

Getting started

A working knowledge agent does not require a vector database, an embedding model, or a chunking pipeline. A filesystem, bash, and a Chat SDK adapter to reach your users are enough. The Knowledge Agent Template wires these primitives together, letting you focus on what the agent knows instead of how it retrieves information.