knowledge-agent-template

Open source file-system and knowledge based agent template. Build AI agents that stay up to date with your knowledge base — grep, find, and cat across your sources, no embeddings, no vector DB. Plug any source (GitHub repos, YouTube transcripts, custom APIs) and deploy as a chat app, a GitHub bot, a Discord bot, or all at once.

Features

File-Based Search — No Embeddings Needed

No vector database. No chunking pipeline. No embedding model. Agents use grep, find, and cat inside isolated sandboxes to search across all your sources. Results are deterministic, explainable, and instant. Zero infrastructure overhead.

Multi-Platform Bots — One Agent, Everywhere

Write your agent once, deploy it on the web chat, GitHub Issues, Discord - and soon Slack, Linear, and more. Powered by pluggable adapters via the Chat SDK. Adding a new platform is a single adapter file.

Built-in Admin Panel

Full admin interface out of the box: usage stats, error logs, user management, source configuration, and content sync controls. No need for external dashboards or third-party monitoring.

AI-Powered Admin Agent

Ask your app about itself. "What errors happened in the last 24 hours?", "Show token usage by model", "Which endpoints are slowest?" — the admin agent has access to internal tools like query_stats, query_errors, run_sql, and chart to answer operational questions in natural language.

Smart Complexity Router

Every incoming question is classified by complexity (trivial → complex) and routed to the right model. Simple questions go to fast, cheap models. Hard questions go to powerful ones. Cost optimization happens automatically, no manual rules to maintain.

Real-Time Tool Visualization

The chat UI shows what the agent is doing in real time: which files it's reading, which commands it's running, and how long each step takes. No black box.

Shareable Conversations

Share any conversation with a single click. Generates a public read-only link with full metadata — author, title, and the complete exchange.

Shared Sandbox Pool

Sandboxes are pooled across users and conversations. When a chat starts, it connects to an already-running sandbox instead of creating a new one — startup in under 100ms. If none is available, a pre-built snapshot spins one up in 1–3s. Sandboxes are read-only with blocked dangerous commands, and automatically shared so multiple agents search the same up-to-date content without duplicating resources.

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        Your AI Application                      │
│                     (Discord bot, GitHub bot, etc.)             │
└─────────────────────────────────┬───────────────────────────────┘
                                  │
                                  ▼
┌─────────────────────────────────────────────────────────────────┐
│                          @savoir/sdk                            │
│              AI SDK compatible tools (bash, bash_batch)         │
└─────────────────────────────────┬───────────────────────────────┘
                                  │ API calls
                                  ▼
┌─────────────────────────────────────────────────────────────────┐
│                         apps/app                                │
│                    (Unified Nuxt Application)                   │
│  ┌─────────────┐  ┌──────────────┐  ┌────────────────────────┐  │
│  │   Sandbox   │  │   Content    │  │   Vercel Workflows     │  │
│  │   Manager   │  │     Sync     │  │   (scheduled sync)     │  │
│  └──────┬──────┘  └──────┬───────┘  └────────────────────────┘  │
└─────────┼────────────────┼──────────────────────────────────────┘
          │                │
          ▼                ▼
   ┌────────────┐   ┌─────────────┐
   │   Vercel   │   │   GitHub    │
   │   Sandbox  │   │  Snapshot   │
   │            │   │    Repo     │
   └────────────┘   └─────────────┘

Packages

| Package | Description | |---------|-------------| | @savoir/sdk | AI SDK compatible tools for agents | | @savoir/agent | Agent core: router, prompts, tools, types | | apps/app | Unified Nuxt app (chat UI + API + bots) |

Quick Start

Using the SDK

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)

Deploy to Vercel

Self-hosting

# Clone the repository
git clone https://github.com/vercel-labs/knowledge-agent-template.git
cd knowledge-agent-template

# Install dependencies
bun install

# Configure environment variables
cp apps/app/.env.example apps/app/.env
# Edit .env with your configuration

# Start the app
bun run dev

Required environment variables:

# Authentication
BETTER_AUTH_SECRET=your-secret        # Secret for signing sessions/tokens
GITHUB_CLIENT_ID=...                  # GitHub OAuth app client ID
GITHUB_CLIENT_SECRET=...              # GitHub OAuth app client secret

# AI (optional — only needed for local dev, Vercel uses OIDC automatically)
# AI_GATEWAY_API_KEY=...              # Vercel AI Gateway API key

# Sandbox
# NUXT_GITHUB_SNAPSHOT_REPO=org/repo  # Optional default (can be set from admin sandbox UI)
# NUXT_GITHUB_TOKEN=ghp_...           # Optional fallback override (GitHub App is the default path)

See ENVIRONMENT.md for the full list of environment variables.

Customization

Knowledge Agent Template is designed as a reusable template. See the Customization Guide for how to:

• Rename your instance (name, icon, description)
• Add content sources (GitHub repos, YouTube channels, custom)
• Add custom AI tools
• Add bot adapters (Slack, Linear, etc.)
• Customize AI prompts
• Theme the UI
• Deploy to production

AI-assisted customization: The project includes local skills in .agents/skills/ (add-tool, add-source, add-bot-adapter, rename-project). You can delegate these tasks to an AI agent — e.g. "Follow the rename-project skill to rename this to MyDocs" — instead of doing them manually.

Configuration

Sources are managed through the admin interface at /admin. You can add GitHub repositories and YouTube channels as knowledge sources, then trigger a sync from the UI.

Sources can also be listed programmatically via the SDK (savoir.client.getSources()).

See SOURCES.md for detailed source configuration options.

How It Works

For the full technical deep-dive, see Architecture.

1. Sources in Database: Sources are stored in SQLite via NuxtHub, managed through the admin interface
2. Content Aggregation: Sources (GitHub repos, YouTube transcripts, custom APIs, etc.) are synced to a snapshot repository via Vercel Workflow
3. Sandbox Creation: When an agent needs to search, the API creates/recovers a Vercel Sandbox with the snapshot repo cloned
4. File-based Search: The SDK bash and bash_batch tools execute grep/find/cat commands in the sandbox to search and read content
5. AI Integration: Tools are compatible with the Vercel AI SDK for seamless integration with any LLM

Bots

Knowledge Agent Template includes built-in bot integrations powered by the Vercel Chat SDK:

• GitHub Bot: Responds to mentions in GitHub issues and PRs. Uses a GitHub App for authentication and webhooks.
• Discord Bot: Responds to mentions and continues conversations in threads. Uses the [Discord API]