vercel-labs/knowledge-agent-template: a grep-based knowledge agent you fork, not install
Open source file-system and knowledge based agent template. Build AI agents that stay up to date with your knowledge base
At a glance
- What is it?
- Vercel Labs ships a TypeScript template that answers questions by running grep, find and cat inside pooled Vercel Sandboxes instead of a vector database. The trade-off is that you are adopting a Nuxt application to maintain, not a library to import.
- Who is it for?
- Fork this if you already run on Vercel, your knowledge lives in a Git repository or another source you can sync into a snapshot, and you want web chat plus a GitHub or Discord bot without building an admin panel. Do not fork it if you need to keep sandboxes inside your own VPC, if your corpus is large enough that grep latency matters, or if you want a dependency you can upgrade rather than an application you own.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 1 day ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem it targets: retrieval infrastructure nobody wants to operate
Most retrieval-augmented setups require four moving parts before an agent answers anything: a chunking pipeline, an embedding model, a vector store, and a reindexing job that has to run whenever the source changes. The README positions this template against exactly that stack, stating it uses grep, find and cat across your sources with no embeddings and no vector DB. The claim of deterministic, explainable results follows from the mechanism: a file match is either there or it is not, and the agent's transcript shows the command it ran.
The audience is narrower than the tagline suggests. This is a template, and the README says so twice: fork it, customize it, deploy your own file-system based AI agent. You are not adding a package to an existing service. You are taking over a Nuxt application that already contains a chat UI, an API layer, bot adapters, an admin panel and a content sync pipeline. Teams without someone willing to own a TypeScript monorepo should read the SDK section below and stop there.
How the agent actually retrieves: bash tools over a shared sandbox
The architecture diagram in the README shows three layers. Your bot or app calls @savoir/sdk, which exposes AI SDK compatible tools named bash and bash_batch. Those tools make API calls into apps/app, a unified Nuxt application that holds the Sandbox Manager, the Content Sync job and Vercel Workflows for scheduled sync. The Sandbox Manager talks to Vercel Sandbox; Content Sync talks to a GitHub snapshot repository.
So the retrieval loop is not a similarity search. The model decides to run a shell command, the SDK forwards it, the sandbox executes it against synced files, and the output returns as tool results. The README's own example passes savoir.tools to generateText with maxSteps: 10, which is the step budget for that loop. The sandbox pool detail matters for latency: the README states that a chat connects to an already-running sandbox when one is available, with startup under 100ms, and that a pre-built snapshot spins one up in 1 to 3 seconds otherwise. Sandboxes are described as read-only with dangerous commands blocked, and shared so multiple agents search the same content. That sharing is the design's main efficiency argument and also its main coupling: content freshness depends on the sync job, not on the sandbox.
Getting it running: bun, one env file, three secrets
The self-hosting path in the README is four commands. Clone the repository, run bun install, copy apps/app/.env.example to apps/app/.env, then run bun run dev from the repository root. Bun is the package manager the template expects; the README does not document an npm or pnpm path.
The deploy button encodes the required environment variables: BETTER_AUTH_SECRET, GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET. The README's own envDescription says to generate the auth secret with openssl rand -hex 32 and to create a GitHub App at github.com/settings/apps/new for the client pair. The README text is truncated at the line beginning with Required environment vari, so the full list of variables is not available here; docs/ENVIRONMENT.md is linked as the reference. The SDK path is separate and lighter: createSavoir takes apiUrl and apiKey, read from SAVOIR_API_URL and SAVOIR_API_KEY in the example, and returns tools you pass to any AI SDK compatible model. The README also notes Slack and Linear adapters are planned rather than shipped, so treat the multi-platform claim as web chat, GitHub Issues and Discord today.
Where the file-system approach breaks down
Grep is exact matching. A user who asks about a concept using different vocabulary than the source documents will not get a match, and there is no embedding layer to bridge that gap. The README does not describe a synonym expansion or query rewriting step, so the burden falls on the model to guess the right search terms and on the corpus to contain them. This is the opposite failure mode from vector search, which retrieves semantically related chunks but cannot tell you why.
The second constraint is operational. Sandboxes are pooled and shared across users and conversations, which the README frames as a resource win. It also means content changes only land when the sync runs; Vercel Workflows handle scheduled sync according to the diagram. If your sources update constantly and answers must reflect the last few minutes, the sync interval becomes the real freshness bound, not the agent. Third, the whole design assumes Vercel Sandbox and a GitHub snapshot repository. The README gives no self-hosted sandbox backend, so teams that cannot run agent code on Vercel infrastructure are outside the supported path. The README does not state a repository size limit for the snapshot, and I cannot confirm one from the material.
The real alternative: embeddings and a vector store
The honest comparison is not another agent framework. It is the stack this template deliberately omits: chunk your documents, embed them, store the vectors, and retrieve by nearest neighbour. That approach handles paraphrase and vague questions far better, because the query does not have to share tokens with the source. It also costs more to run and more to reason about: you need an embedding model, an index, and a reindexing path when documents change, and when retrieval returns the wrong chunk you get a similarity score rather than a command you can read.
The difference in approach shows up in the transcript. With this template, the chat UI displays which files the agent is reading and which commands it is running, per the README's real-time tool visualization section. With a vector store, the equivalent artifact is a list of chunks and distances. If your team's failure mode is "we cannot tell why the bot said that," the file-system approach gives you a better audit trail. If your failure mode is "the bot misses questions phrased differently," embeddings win and this template will frustrate you.
Admin surface, router, and what you inherit by forking
The template ships an admin panel with usage stats, error logs, user management, source configuration and content sync controls, plus an admin agent that answers operational questions through tools named query_stats, query_errors, run_sql and chart. A complexity router classifies each incoming question and routes it to a cheaper or stronger model. None of this is a library you call; it is application code inside apps/app, and it is yours to maintain once you fork.
That is the maintenance story in one sentence. Because there are no published releases in the material provided, there is no version you can pin and no changelog to read before upgrading. Upstream changes arrive as commits on main, and pulling them into a customized fork means resolving conflicts across the chat UI, the bot adapters and the sync pipeline. The README describes adding a platform as a single adapter file under docs/CUSTOMIZATION.md, which suggests the adapter boundary is intentional, but the rest of the application is not described as pluggable. Budget for a fork you own, not a dependency you track. The MIT licence permits commercial use and modification; it also means no warranty, and this is not legal advice.
Who should fork it, and what to check first
Fork it if three things are true. You deploy on Vercel and are comfortable with Vercel Sandbox as the execution environment. Your knowledge already lives somewhere you can sync into a snapshot repository, since the README names GitHub repos, YouTube transcripts and custom APIs as source types. And you want the surrounding product (chat UI, shareable conversations, GitHub and Discord bots, admin panel) rather than just the retrieval tool, because that surrounding product is most of what you are taking on.
Do not fork it if you need sandboxes inside your own network, if your corpus is large enough that grep latency becomes the bottleneck (the README does not publish a size threshold, so this is a measurement you would have to make), or if your users phrase questions in vocabulary your documents do not contain. In that last case the missing embedding layer is the whole problem, and no amount of prompt tuning inside this template fixes it.
Verify two files before you start: docs/ARCHITECTURE.md for the sandbox pool and router behaviour, and docs/SOURCES.md for whether your source type has a documented sync path. Then confirm the auth variables in docs/ENVIRONMENT.md, since the README text cuts off mid-list. If your source type is not in docs/SOURCES.md, you are writing the sync job yourself, and that is the first real cost of adopting this template.
Editorial conclusion
Fork this if you already run on Vercel, your knowledge lives in a Git repository or another source you can sync into a snapshot, and you want web chat plus a GitHub or Discord bot without building an admin panel. Do not fork it if you need to keep sandboxes inside your own VPC, if your corpus is large enough that grep latency matters, or if you want a dependency you can upgrade rather than an application you own. Before committing, check docs/ARCHITECTURE.md for the sandbox pool lifetime and docs/SOURCES.md for whether your source type has a sync path, and confirm that the BETTER_AUTH_SECRET plus GitHub OAuth trio is the only auth you need.
Community notes