Skip to content

Open source file-system and knowledge based agent template. Build AI agents that stay up to date with your knowledge base

improve docs

Hugo Richardbac9ce9885a4
diff --git a/.agents/skills/.gitkeep b/.agents/skills/.gitkeep
deleted file mode 100644
index e69de29..0000000
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
index 586ee82..806483c 100644
--- a/.github/pull_request_template.md
+++ b/.github/pull_request_template.md
@@ -20,6 +20,8 @@ Here are the available types and scopes:
### Scopes
- chat (apps/chat - Main application)
- sdk (packages/sdk - @savoir/sdk)
+- agent (packages/agent - @savoir/agent)
+- cli (packages/cli - @savoir/cli)
- deps (dependencies updates)
- docs (documentation)
-->
diff --git a/.github/workflows/semantic-pull-request.yml b/.github/workflows/semantic-pull-request.yml
index 5a42a6c..914fe0e 100644
--- a/.github/workflows/semantic-pull-request.yml
+++ b/.github/workflows/semantic-pull-request.yml
@@ -24,9 +24,9 @@ jobs:
scopes: |
deps
chat
- bot
sdk
- logger
+ agent
+ cli
docs
types: |
breaking
diff --git a/README.md b/README.md
index 43156c4..c2eec4b 100644
--- a/README.md
+++ b/README.md
@@ -2,7 +2,7 @@
<br>
<b>Savoir</b>
<br>
- <i>Build AI agents with real-time knowledge access.</i>
+ <i>Build AI agents with up-to-date knowledge access.</i>
<br>
<br>
</p>
@@ -13,17 +13,17 @@
---
-Open-source infrastructure to build AI agents powered by real-time file-based knowledge. 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.
+Open-source infrastructure to build AI agents powered by up-to-date file-based knowledge. 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. Savoir agents use `grep`, `find`, and `cat` inside isolated sandboxes to search across all your sources. Results are deterministic, explainable, and instant. Zero infrastructure overhead.
+No vector database. No chunking pipeline. No embedding model. Savoir agents use `grep`, `find`, and `cat` inside [isolated sandboxes](./docs/ARCHITECTURE.md#3-sandbox-system) to search across all your [sources](./docs/SOURCES.md). 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](https://github.com/vercel-labs/chat). Adding a new platform is a single adapter file.
+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](https://github.com/vercel-labs/chat). Adding a new platform is [a single adapter file](./docs/CUSTOMIZATION.md#4-add-a-bot-adapter).
### Built-in Admin Panel
@@ -35,7 +35,7 @@ Ask your app about itself. "What errors happened in the last 24 hours?", "Show t
### 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.
+Every incoming question is classified by complexity (trivial → complex) and [routed to the right model](./docs/ARCHITECTURE.md#4-ai-agent-router--model-selection). 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
@@ -49,7 +49,7 @@ Share any conversation with a single click. Generates a public read-only link wi
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
+## [Architecture](./docs/ARCHITECTURE.md)
```
┌─────────────────────────────────────────────────────────────────┐
@@ -159,7 +159,7 @@ See [ENVIRONMENT.md](./docs/ENVIRONMENT.md) for the full list of environment var
Savoir is designed as a **reusable template**. See the [Customization Guide](./docs/CUSTOMIZATION.md) for how to:
- Rename your instance (name, icon, description)
-- Add documentation sources (GitHub repos, YouTube channels)
+- Add [content sources](./docs/SOURCES.md) (GitHub repos, YouTube channels, custom)
- Add custom AI tools
- Add bot adapters (Slack, Linear, etc.)
- Customize AI prompts
@@ -176,6 +176,8 @@ See [SOURCES.md](./docs/SOURCES.md) for detailed source configuration options.
## How It Works
+> For the full technical deep-dive, see [Architecture](./docs/ARCHITECTURE.md).
+
1. **Sources in Database**: Sources are stored in SQLite via [NuxtHub](https://hub.nuxt.com), 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](https://useworkflow.dev)
3. **Sandbox Creation**: When an agent needs to search, the API creates/recovers a [Vercel Sandbox](https://vercel.com/docs/vercel-sandbox) with the snapshot repo cloned
@@ -189,7 +191,7 @@ Savoir includes built-in bot integrations powered by the [Vercel Chat SDK](https
- **GitHub Bot**: Responds to mentions in GitHub issues and PRs. Uses a [GitHub App](https://docs.github.com/en/apps) for authentication and webhooks.
- **Discord Bot**: Responds to mentions and continues conversations in threads. Uses the [Discord API](https://discord.com/developers/docs).
-Both bots use the same AI agent and knowledge base as the chat interface.
+Both bots use the same AI agent and knowledge base as the chat interface. Want to add your own? See [Adding a Bot Adapter](./docs/CUSTOMIZATION.md#4-add-a-bot-adapter).
## Development
diff --git a/apps/chat/app/content/docs/admin-mode.md b/apps/chat/app/content/docs/admin-mode.md
index fd80005..4817680 100644
--- a/apps/chat/app/content/docs/admin-mode.md
+++ b/apps/chat/app/content/docs/admin-mode.md
@@ -77,3 +77,5 @@ Admin mode uses a completely separate AI pipeline from the regular chat:
4. The `chart` tool can render visual time-series charts inline in the conversation
Admin chats are stored like regular chats but tagged with `mode: 'admin'` in the database.
+
+For a deeper look at the architecture behind admin mode and other components, see the [Architecture documentation](https://github.com/vercel-labs/savoir/blob/main/docs/ARCHITECTURE.md) on GitHub.
diff --git a/apps/chat/app/content/docs/bot-setup.md b/apps/chat/app/content/docs/bot-setup.md
index 06527b7..33b97b7 100644
--- a/apps/chat/app/content/docs/bot-setup.md
+++ b/apps/chat/app/content/docs/bot-setup.md
@@ -80,4 +80,4 @@ When enabled, the bot will respond to every new issue opened in repositories whe
The bot is built on the [Vercel Chat SDK](https://github.com/vercel-labs/chat) with a custom GitHub adapter. It uses the [Octokit](https://github.com/octokit/rest.js) library with [GitHub App authentication](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/about-authentication-with-a-github-app) to interact with the GitHub API.
-Each response goes through the same AI agent pipeline as the chat interface, using [Vercel AI SDK](https://ai-sdk.dev) tools to search the knowledge base in a [Vercel Sandbox](https://vercel.com/docs/vercel-sandbox).
+Each response goes through the same AI agent pipeline as the chat interface, using [Vercel AI SDK](https://ai-sdk.dev) tools to search the knowledge base in a [Vercel Sandbox](https://vercel.com/docs/vercel-sandbox). For the full architecture, see the [Architecture documentation](https://github.com/vercel-labs/savoir/blob/main/docs/ARCHITECTURE.md) on GitHub. To build your own adapter, see the [Customization Guide](https://github.com/vercel-labs/savoir/blob/main/docs/CUSTOMIZATION.md#4-add-a-bot-adapter).
diff --git a/apps/chat/app/content/docs/discord-bot.md b/apps/chat/app/content/docs/discord-bot.md
index 4ae8b13..df54c6b 100644
--- a/apps/chat/app/content/docs/discord-bot.md
+++ b/apps/chat/app/content/docs/discord-bot.md
@@ -69,3 +69,5 @@ If `NUXT_DISCORD_MENTION_ROLE_IDS` is set, the bot will also respond when those
Bot conversation state is stored in:
- [**Redis**](https://upstash.com/docs/redis) if `REDIS_URL` is set (recommended for production -- state persists across restarts)
- **In-memory** as fallback (state is lost on restart)
+
+For the full architecture and how to build custom adapters, see the [Architecture](https://github.com/vercel-labs/savoir/blob/main/docs/ARCHITECTURE.md) and [Customization Guide](https://github.com/vercel-labs/savoir/blob/main/docs/CUSTOMIZATION.md#4-add-a-bot-adapter) on GitHub.
diff --git a/apps/chat/app/content/docs/sdk.md b/apps/chat/app/content/docs/sdk.md
index 744bfec..b4279fc 100644
--- a/apps/chat/app/content/docs/sdk.md
+++ b/apps/chat/app/content/docs/sdk.md
@@ -1,6 +1,6 @@
# Savoir SDK
-The [`@savoir/sdk`](https://github.com/vercel-labs/savoir/tree/main/packages/sdk) package provides a TypeScript client for interacting with Savoir programmatically. It exposes [AI SDK](https://ai-sdk.dev)-compatible tools that let any AI model search and read your knowledge base.
+The [`@savoir/sdk`](https://github.com/vercel-labs/savoir/tree/main/packages/sdk) package provides a TypeScript client for interacting with Savoir programmatically. It exposes [AI SDK](https://ai-sdk.dev)-compatible tools that let any AI model search and read your knowledge base. For the full API reference and error handling, see the [SDK README](https://github.com/vercel-labs/savoir/blob/main/packages/sdk/README.md) on GitHub.
## Installation
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index 9a7ee15..9b6edc3 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -1,6 +1,8 @@
# Savoir Architecture
-This document describes the technical architecture of Savoir, a platform for building AI agents with real-time knowledge access.
+> Back to [README](../README.md)
+
+This document describes the technical architecture of Savoir, a platform for building AI agents with up-to-date knowledge access.
## System Overview
@@ -110,7 +112,7 @@ savoir/
### 1. Sources (Database)
-Sources are stored in SQLite via [NuxtHub](https://hub.nuxt.com) and managed through the admin interface.
+Sources are stored in SQLite via [NuxtHub](https://hub.nuxt.com) and managed through the admin interface. See [Sources](./SOURCES.md) for configuration details.
#### Database Schema
@@ -251,7 +253,7 @@ Content synchronization uses [Vercel Workflow](https://useworkflow.dev) for dura
- Responds to mentions and continues conversations in threads
- Webhook: `POST /api/webhooks/discord`
-Both bots use the same AI agent pipeline (router + tools) as the chat interface but with internal sandbox access (no HTTP round-trip).
+Both bots use the same AI agent pipeline (router + tools) as the chat interface but with internal sandbox access (no HTTP round-trip). To add a new platform, see [Customization > Add a Bot Adapter](./CUSTOMIZATION.md#4-add-a-bot-adapter).
## API Endpoints
diff --git a/docs/CODING-GUIDELINES.md b/docs/CODING-GUIDELINES.md
index f7d2990..0c1285b 100644
--- a/docs/CODING-GUIDELINES.md
+++ b/docs/CODING-GUIDELINES.md
@@ -1,5 +1,7 @@
# Coding Guidelines
+> Back to [README](../README.md) | See also: [Contributing](../CONTRIBUTING.md), [Architecture](./ARCHITECTURE.md)
+
## Comments
Only add comments when the code is truly complex or non-obvious.
diff --git a/docs/CUSTOMIZATION.md b/docs/CUSTOMIZATION.md
index fe125d3..4614780 100644
--- a/docs/CUSTOMIZATION.md
+++ b/docs/CUSTOMIZATION.md
@@ -1,5 +1,7 @@
# Customization Guide
+> Back to [README](../README.md) | See also: [Sources](./SOURCES.md), [Environment](./ENVIRONMENT.md), [Architecture](./ARCHITECTURE.md)
+
Savoir is designed as a reusable template. This guide covers how to customize your instance.
## 1. Rename Your Instance
@@ -32,7 +34,7 @@ Sources define your knowledge base. Manage them through the **Admin UI**:
3. Configure a GitHub repository or YouTube channel
4. Click **Sync** to pull content
-See [SOURCES.md](./SOURCES.md) for all source options.
+See [Sources](./SOURCES.md) for all source options and how to add custom source types.
## 3. Add Custom AI Tools
@@ -135,7 +137,7 @@ export default defineAppConfig({
})
```
-See the [Nuxt UI documentation](https://ui.nuxt.com) for all theming options.
+See the [Nuxt UI documentation](https://ui.nuxt.com) for all theming options. For a deeper understanding of the app structure, see [Architecture](./ARCHITECTURE.md).
## 7. Deploy
diff --git a/docs/ENVIRONMENT.md b/docs/ENVIRONMENT.md
index 376ca63..fe19dd1 100644
--- a/docs/ENVIRONMENT.md
+++ b/docs/ENVIRONMENT.md
@@ -1,5 +1,7 @@
# Environment Variables
+> Back to [README](../README.md) | See also: [Architecture](./ARCHITECTURE.md), [Customization](./CUSTOMIZATION.md)
+
All environment variables for the Savoir project, organized by category.
## Core
diff --git a/docs/SOURCES.md b/docs/SOURCES.md
index e23f7d0..672fcb5 100644
--- a/docs/SOURCES.md
+++ b/docs/SOURCES.md
@@ -1,5 +1,7 @@
# Content Sources
+> Back to [README](../README.md) | See also: [Customization](./CUSTOMIZATION.md), [Architecture](./ARCHITECTURE.md)
+
Savoir aggregates content from multiple sources into a unified, searchable knowledge base. A source is anything that produces files — GitHub repos, YouTube transcripts, and any custom source you build. Everything ends up as files in a sandbox, and the AI agent searches across all of them.
The system is designed to be extensible. Built-in source types handle GitHub and YouTube, but the architecture supports any source that can output files: Reddit threads, Slack exports, RSS feeds, custom APIs, static markdown — anything.
@@ -91,12 +93,12 @@ await savoir.client.syncSource('my-docs')
### How Sync Works
-1. A Vercel Sandbox is created from the latest snapshot
+1. A [Vercel Sandbox](https://vercel.com/docs/vercel-sandbox) is created from the latest snapshot
2. All source repositories are cloned/updated
3. Changes are pushed to the snapshot repository
4. A new sandbox snapshot is taken for instant startup
-This runs as a durable Vercel Workflow with automatic retries.
+This runs as a durable [Vercel Workflow](https://useworkflow.dev) with automatic retries. See [Architecture > Sandbox System](./ARCHITECTURE.md#3-sandbox-system) for more details on how snapshots and sandboxes work.
### Sync Tracking
diff --git a/packages/agent/README.md b/packages/agent/README.md
index 012db94..3023d81 100644
--- a/packages/agent/README.md
+++ b/packages/agent/README.md
@@ -2,6 +2,8 @@
Framework-agnostic agent core for Savoir. Handles question routing, prompt management, agent creation, and AI tool definitions.
+> See also: [Main README](../../README.md), [Architecture](../../docs/ARCHITECTURE.md), [Customization](../../docs/CUSTOMIZATION.md)
+
## Overview
This package provides the AI agent infrastructure used by Savoir's chat interface and bots. It is designed to be consumed by `apps/chat` but can also be used independently.
diff --git a/packages/sdk/README.md b/packages/sdk/README.md
index 6caeb27..88c0053 100644
--- a/packages/sdk/README.md
+++ b/packages/sdk/README.md
@@ -1,8 +1,10 @@
# @savoir/sdk
-SDK for [Savoir](https://github.com/vercel-labs/savoir) - AI agents with real-time knowledge base access.
+SDK for [Savoir](https://github.com/vercel-labs/savoir) — AI agents with up-to-date knowledge base access.
-Provides [AI SDK](https://ai-sdk.dev) compatible tools to query documentation in a sandboxed environment.
+Provides [AI SDK](https://ai-sdk.dev) compatible tools to query content in a sandboxed environment.
+
+> See also: [Main README](../../README.md), [Architecture](../../docs/ARCHITECTURE.md), [Environment Variables](../../docs/ENVIRONMENT.md)
## Installation