{"id":48123677,"url":"https://github.com/vercel-labs/knowledge-agent-template","last_synced_at":"2026-07-31T11:03:49.295Z","repository":{"id":340407933,"uuid":"1138349022","full_name":"vercel-labs/knowledge-agent-template","owner":"vercel-labs","description":"Open source file-system and knowledge based agent template. Build AI agents that stay up to date with your knowledge base","archived":false,"fork":false,"pushed_at":"2026-05-21T12:07:47.000Z","size":1981,"stargazers_count":820,"open_issues_count":3,"forks_count":112,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-06-08T03:27:54.118Z","etag":null,"topics":["agents","ai-agent","chatbot","file-system","knowledge-base","nuxt","sandbox","typescript","vue"],"latest_commit_sha":null,"homepage":"https://chatsdk-knowledge-agent.vercel.app","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vercel-labs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/funding.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null},"funding":{"github":["vercel-labs"]}},"created_at":"2026-01-20T15:02:20.000Z","updated_at":"2026-06-07T22:04:01.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/vercel-labs/knowledge-agent-template","commit_stats":null,"previous_names":["vercel-labs/chatsdk-knowledge-agent-template","vercel-labs/knowledge-agent-template"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/vercel-labs/knowledge-agent-template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vercel-labs%2Fknowledge-agent-template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vercel-labs%2Fknowledge-agent-template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vercel-labs%2Fknowledge-agent-template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vercel-labs%2Fknowledge-agent-template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vercel-labs","download_url":"https://codeload.github.com/vercel-labs/knowledge-agent-template/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vercel-labs%2Fknowledge-agent-template/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":36115842,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-07-20T02:08:10.276Z","status":"online","status_checked_at":"2026-07-31T02:00:06.731Z","response_time":112,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agents","ai-agent","chatbot","file-system","knowledge-base","nuxt","sandbox","typescript","vue"],"created_at":"2026-04-04T16:22:44.560Z","updated_at":"2026-07-31T11:03:49.275Z","avatar_url":"https://github.com/vercel-labs.png","language":"TypeScript","funding_links":["https://github.com/sponsors/vercel-labs"],"categories":["TypeScript"],"sub_categories":[],"readme":"\u003cimg src=\"./assets/banner.jpg\" width=\"100%\" alt=\"Knowledge Agent Template banner\" /\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cbr\u003e\n  \u003cb\u003eKnowledge Agent Template\u003c/b\u003e\n  \u003cbr\u003e\n  \u003ci\u003eOpen source file-system and knowledge based agent template.\u003c/i\u003e\n  \u003cbr\u003e\n  \u003cbr\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cb\u003eTemplate.\u003c/b\u003e Fork it, customize it, and deploy your own file-system based AI agent.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fvercel-labs%2Fknowledge-agent-template\u0026env=BETTER_AUTH_SECRET,GITHUB_CLIENT_ID,GITHUB_CLIENT_SECRET\u0026envDescription=BETTER_AUTH_SECRET%3A%20run%20openssl%20rand%20-hex%2032%20%7C%20GITHUB_CLIENT_ID%20%2B%20SECRET%3A%20create%20a%20GitHub%20App%20at%20github.com%2Fsettings%2Fapps%2Fnew\u0026envLink=https%3A%2F%2Fgithub.com%2Fvercel-labs%2Fknowledge-agent-template%2Fblob%2Fmain%2Fdocs%2FENVIRONMENT.md\u0026project-name=knowledge-agent\u0026repository-name=knowledge-agent\"\u003e\u003cimg src=\"https://vercel.com/button\" alt=\"Deploy with Vercel\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\nOpen 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.\n\n## Features\n\n### File-Based Search — No Embeddings Needed\n\nNo vector database. No chunking pipeline. No embedding model. 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.\n\n### Multi-Platform Bots — One Agent, Everywhere\n\nWrite 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).\n\n### Built-in Admin Panel\n\nFull 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.\n\n### AI-Powered Admin Agent\n\nAsk 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.\n\n### Smart Complexity Router\n\nEvery 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.\n\n### Real-Time Tool Visualization\n\nThe 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.\n\n### Shareable Conversations\n\nShare any conversation with a single click. Generates a public read-only link with full metadata — author, title, and the complete exchange.\n\n### Shared Sandbox Pool\n\nSandboxes 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.\n\n## [Architecture](./docs/ARCHITECTURE.md)\n\n```\n┌─────────────────────────────────────────────────────────────────┐\n│                        Your AI Application                      │\n│                     (Discord bot, GitHub bot, etc.)             │\n└─────────────────────────────────┬───────────────────────────────┘\n                                  │\n                                  ▼\n┌─────────────────────────────────────────────────────────────────┐\n│                          @savoir/sdk                            │\n│              AI SDK compatible tools (bash, bash_batch)         │\n└─────────────────────────────────┬───────────────────────────────┘\n                                  │ API calls\n                                  ▼\n┌─────────────────────────────────────────────────────────────────┐\n│                         apps/app                                │\n│                    (Unified Nuxt Application)                   │\n│  ┌─────────────┐  ┌──────────────┐  ┌────────────────────────┐  │\n│  │   Sandbox   │  │   Content    │  │   Vercel Workflows     │  │\n│  │   Manager   │  │     Sync     │  │   (scheduled sync)     │  │\n│  └──────┬──────┘  └──────┬───────┘  └────────────────────────┘  │\n└─────────┼────────────────┼──────────────────────────────────────┘\n          │                │\n          ▼                ▼\n   ┌────────────┐   ┌─────────────┐\n   │   Vercel   │   │   GitHub    │\n   │   Sandbox  │   │  Snapshot   │\n   │            │   │    Repo     │\n   └────────────┘   └─────────────┘\n```\n\n## Packages\n\n| Package | Description |\n|---------|-------------|\n| [`@savoir/sdk`](./packages/sdk) | [AI SDK](https://ai-sdk.dev) compatible tools for agents |\n| [`@savoir/agent`](./packages/agent) | Agent core: router, prompts, tools, types |\n| [`apps/app`](./apps/app) | Unified [Nuxt](https://nuxt.com) app (chat UI + API + bots) |\n\n## Quick Start\n\n### Using the SDK\n\n```typescript\nimport { generateText } from 'ai'\nimport { createSavoir } from '@savoir/sdk'\n\nconst savoir = createSavoir({\n  apiUrl: process.env.SAVOIR_API_URL!,\n  apiKey: process.env.SAVOIR_API_KEY,\n})\n\nconst { text } = await generateText({\n  model: yourModel, // any AI SDK compatible model\n  tools: savoir.tools, // bash and bash_batch tools\n  maxSteps: 10,\n  prompt: 'How do I configure authentication?',\n})\n\nconsole.log(text)\n```\n\n### Deploy to Vercel\n\n[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fvercel-labs%2Fknowledge-agent-template\u0026env=BETTER_AUTH_SECRET,GITHUB_CLIENT_ID,GITHUB_CLIENT_SECRET\u0026envDescription=BETTER_AUTH_SECRET%3A%20run%20openssl%20rand%20-hex%2032%20%7C%20GITHUB_CLIENT_ID%20%2B%20SECRET%3A%20create%20a%20GitHub%20App%20at%20github.com%2Fsettings%2Fapps%2Fnew\u0026envLink=https%3A%2F%2Fgithub.com%2Fvercel-labs%2Fknowledge-agent-template%2Fblob%2Fmain%2Fdocs%2FENVIRONMENT.md\u0026project-name=knowledge-agent\u0026repository-name=knowledge-agent)\n\n### Self-hosting\n\n```bash\n# Clone the repository\ngit clone https://github.com/vercel-labs/knowledge-agent-template.git\ncd knowledge-agent-template\n\n# Install dependencies\nbun install\n\n# Configure environment variables\ncp apps/app/.env.example apps/app/.env\n# Edit .env with your configuration\n\n# Start the app\nbun run dev\n```\n\n**Required environment variables:**\n\n```bash\n# Authentication\nBETTER_AUTH_SECRET=your-secret        # Secret for signing sessions/tokens\nGITHUB_CLIENT_ID=...                  # GitHub OAuth app client ID\nGITHUB_CLIENT_SECRET=...              # GitHub OAuth app client secret\n\n# AI (optional — only needed for local dev, Vercel uses OIDC automatically)\n# AI_GATEWAY_API_KEY=...              # Vercel AI Gateway API key\n\n# Sandbox\n# NUXT_GITHUB_SNAPSHOT_REPO=org/repo  # Optional default (can be set from admin sandbox UI)\n# NUXT_GITHUB_TOKEN=ghp_...           # Optional fallback override (GitHub App is the default path)\n\n```\n\nSee [ENVIRONMENT.md](./docs/ENVIRONMENT.md) for the full list of environment variables.\n\n## Customization\n\nKnowledge Agent Template is designed as a **reusable template**. See the [Customization Guide](./docs/CUSTOMIZATION.md) for how to:\n\n- Rename your instance (name, icon, description)\n- Add [content sources](./docs/SOURCES.md) (GitHub repos, YouTube channels, custom)\n- Add custom AI tools\n- Add bot adapters (Slack, Linear, etc.)\n- Customize AI prompts\n- Theme the UI\n- Deploy to production\n\n**AI-assisted customization:** The project includes local skills in [`.agents/skills/`](./.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.\n\n## Configuration\n\nSources 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.\n\nSources can also be listed programmatically via the SDK (`savoir.client.getSources()`).\n\nSee [SOURCES.md](./docs/SOURCES.md) for detailed source configuration options.\n\n## How It Works\n\n\u003e For the full technical deep-dive, see [Architecture](./docs/ARCHITECTURE.md).\n\n1. **Sources in Database**: Sources are stored in SQLite via [NuxtHub](https://hub.nuxt.com), managed through the admin interface\n2. **Content Aggregation**: Sources (GitHub repos, YouTube transcripts, custom APIs, etc.) are synced to a snapshot repository via [Vercel Workflow](https://useworkflow.dev)\n3. **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\n4. **File-based Search**: The SDK `bash` and `bash_batch` tools execute grep/find/cat commands in the sandbox to search and read content\n5. **AI Integration**: Tools are compatible with the [Vercel AI SDK](https://ai-sdk.dev) for seamless integration with any LLM\n\n## Bots\n\nKnowledge Agent Template includes built-in bot integrations powered by the [Vercel Chat SDK](https://github.com/vercel-labs/chat):\n\n- **GitHub Bot**: Responds to mentions in GitHub issues and PRs. Uses a [GitHub App](https://docs.github.com/en/apps) for authentication and webhooks.\n- **Discord Bot**: Responds to mentions and continues conversations in threads. Uses the [Discord API](https://discord.com/developers/docs).\n\nBoth 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).\n\n## Development\n\n```bash\n# Install dependencies\nbun install\n\n# Start the app in dev mode\nbun run dev\n\n# Build all packages\nbun run build\n\n# Run tests\nbun run test\n\n# Lint and fix\nbun run lint:fix\n```\n\n## Built With\n\n- [Nuxt](https://nuxt.com) - Full-stack Vue framework\n- [Nuxt UI](https://ui.nuxt.com) - UI component library\n- [NuxtHub](https://hub.nuxt.com) - Database, KV, and blob storage\n- [Vercel AI SDK](https://ai-sdk.dev) - AI model integration and tool system\n- [Vercel Sandbox](https://vercel.com/docs/vercel-sandbox) - Isolated execution environment\n- [Vercel Workflow](https://useworkflow.dev) - Durable workflow execution\n- [Better Auth](https://www.better-auth.com) - Authentication framework\n- [Drizzle ORM](https://orm.drizzle.team) - Type-safe database queries\n- [Vercel Chat SDK](https://github.com/vercel-labs/chat) - Bot framework for GitHub and Discord\n\n## Contributing\n\nSee [CONTRIBUTING.md](./CONTRIBUTING.md) for how to get involved.\n\n## License\n\n[MIT](./LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvercel-labs%2Fknowledge-agent-template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvercel-labs%2Fknowledge-agent-template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvercel-labs%2Fknowledge-agent-template/lists"}