https://github.com/MarlBurroW/kinbot
Self-hosted AI agents with persistent memory, real identity, and collaboration. One process, one SQLite file, zero cloud.
https://github.com/MarlBurroW/kinbot
agent-framework ai ai-agents artificial-intelligence automation bun chatbot docker llm mcp memory multi-agent ollama open-source react self-hosted selfhosted sqlite typescript vector-search
Last synced: 17 days ago
JSON representation
Self-hosted AI agents with persistent memory, real identity, and collaboration. One process, one SQLite file, zero cloud.
- Host: GitHub
- URL: https://github.com/MarlBurroW/kinbot
- Owner: MarlBurroW
- License: agpl-3.0
- Created: 2026-02-19T16:16:44.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2026-03-24T10:04:54.000Z (24 days ago)
- Last Synced: 2026-03-24T19:03:06.727Z (23 days ago)
- Topics: agent-framework, ai, ai-agents, artificial-intelligence, automation, bun, chatbot, docker, llm, mcp, memory, multi-agent, ollama, open-source, react, self-hosted, selfhosted, sqlite, typescript, vector-search
- Language: TypeScript
- Homepage: https://marlburrow.github.io/kinbot/
- Size: 29.8 MB
- Stars: 25
- Watchers: 1
- Forks: 4
- Open Issues: 11
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
- Security: SECURITY.md
Awesome Lists containing this project
- awesome-ai-agents-2026 - KinBot - hosted AI agent platform. Persistent memory (hybrid search + LLM re-ranking), 23+ providers (including Ollama), plugin store, mini-apps SDK, cron scheduling, 6 messaging channels. SQLite, runs on a Pi. | (🏠 Local and Self-Hosted AI / Self-Hosted Agents and UIs)
- Awesome-AI-Agents - KinBot - Self-hosted AI agent platform with persistent memory, 23+ LLM providers, plugin store, mini-apps SDK, cron scheduling, and 6 messaging channels (Telegram, Discord, Slack, WhatsApp, Signal, Matrix). Runs on SQLite, no cloud required.  (Platforms/API / Tools)
README
# KinBot
**AI agents that actually remember you.**
Self-hosted. Persistent memory. Real collaboration.
[](https://github.com/MarlBurroW/kinbot/actions/workflows/ci.yml)
[](https://github.com/MarlBurroW/kinbot/actions/workflows/e2e.yml)
[](https://github.com/MarlBurroW/kinbot/actions/workflows/codeql.yml)
[](https://github.com/MarlBurroW/kinbot/releases)
[](https://github.com/MarlBurroW/kinbot)
[](LICENSE)
[](https://github.com/MarlBurroW/kinbot/pkgs/container/kinbot)
[](https://github.com/MarlBurroW/kinbot/pulls)
[Website](https://marlburrow.github.io/kinbot/) · [Documentation](https://marlburrow.github.io/kinbot/docs/) · [Quick Start](#-quick-start) · [Features](#-features) · [Compare](#-how-does-kinbot-compare) · [Architecture](#-architecture) · [E2E Report](https://marlburrow.github.io/kinbot/e2e-report/) · [Discussions](https://github.com/MarlBurroW/kinbot/discussions) · [Troubleshooting](TROUBLESHOOTING.md) · [Changelog](https://marlburrow.github.io/kinbot/changelog) · [Contributing](#contributing)
## Why KinBot?
Most AI tools treat every conversation as **disposable**. You explain yourself Monday, they forget by Tuesday.
KinBot is different. You create **Kins** — AI agents with:
| | |
|---|---|
| 🧠 **Persistent memory** | They remember every conversation. Forever. Vector search + full-text across months of interactions. |
| 🎭 **Real identity** | Name, role, personality, avatar. They know who they are and who you are. |
| 🤝 **Collaboration** | Kins talk to each other, delegate tasks, spawn workers. A team, not a chatbot. |
| ⚡ **Autonomy** | Cron jobs, webhooks, Telegram. They work while you sleep. |
| 🏠 **Self-hosted** | One process. One SQLite file. Your data never leaves your server. |
> *"Like having your own team of AI specialists that live on your server and never forget a thing."*
---
## ✨ Features
### 🧠 Intelligence
Persistent memory (vector + full-text) · Knowledge base / RAG · Session compacting · Sub-agents · Inter-Kin communication · Continuous sessions that never reset
### 🔧 Automation & Extensibility
Cron jobs · Webhooks · HTTP requests · 6 channels (Telegram, Discord, Slack, WhatsApp, Signal, Matrix) · MCP servers · Custom tools · Mini Apps · **Plugin system** · Contacts · Notifications · Human-in-the-loop prompts · 23 AI providers (incl. Ollama) · Multi-provider auto-detection
### 🔒 Security & Privacy
AES-256-GCM vault · Auth with roles · Invitation system · 100% self-hosted · Your data never leaves your server
### 🎨 Experience
8 color palettes · Dark/Light/System themes · English & French · @mentions with autocomplete · File uploads · Image generation · Real-time SSE streaming
Full feature list
#### Kins
- **Persistent identity** — each Kin has a name, description, character, expertise domain, model, and avatar
- **Continuous sessions** — one session per Kin, never resets
- **Shared Kins** — all users on the instance interact with the same Kins; messages are tagged with sender identity
#### Intelligence
- **Long-term memory** — dual-channel: automatic extraction pipeline on every LLM turn + explicit `remember()` tool; hybrid search (vector similarity + full-text); query intent detection with category-aware score boosting; token-budgeted memory block in prompt
- **Knowledge base / RAG** — upload documents and texts as reference material; hybrid search (vector + full-text) retrieves relevant chunks at query time
- **Session compacting** — token-aware compaction with multi-summary accumulation and telescopic merge; original messages are always preserved
- **Sub-Kins (tasks)** — Kins can delegate work to ephemeral sub-agents; `await` mode re-enters the parent queue with the result, `async` mode deposits it as informational
- **Inter-Kin communication** — request/reply pattern with correlation IDs; rate-limited; replies are always informational (no ping-pong)
#### Automation
- **Cron jobs** — in-process scheduler (croner); Kins can create their own crons (with user approval); searchable/filterable cron list; cron results appear in the main session
- **Webhooks** — inbound webhooks to trigger Kins from external systems; configurable per-Kin
- **Channels** — 6 platforms: Telegram, Discord, Slack, WhatsApp, Signal, Matrix
- **Notifications** — Kins can send push notifications to users via the `notify` tool
- **Human-in-the-loop** — Kins can prompt users for approval before sensitive actions (cron creation, MCP server management, etc.)
#### Security & Privacy
- **Vault** — AES-256-GCM encrypted secrets; never exposed in prompts or logs; message redaction prevents leaking into compacted summaries
- **Authentication** — Better Auth with HTTP-only cookie sessions; admin + member roles; invitation system
- **Self-hosted** — your data never leaves your server
#### Extensibility
- **MCP servers** — connect any Model Context Protocol server to extend Kins with external tools; Kins can manage their own MCP connections
- **Plugin system** — extend KinBot with community or custom plugins; plugins can register tools, hooks, AI providers, and channels; install from Git repos or npm packages; hot reload during development; community registry with a built-in marketplace UI for discovering and installing plugins; managed via the UI with per-plugin configuration, encrypted secret storage, and enable/disable toggles; health monitoring with circuit breaker auto-disable; dependency management between plugins; version compatibility checking
- **Custom tools** — Kins can create, register, and run their own scripts from their workspace
- **Mini Apps** — Kins can build and deploy interactive web apps (HTML/CSS/JS) that live in the sidebar; auto-injected design system + JavaScript SDK with theme sync, toasts, inter-app navigation (`openApp`), dialogs (`confirm`/`prompt`), window title & badge control, persistent key-value storage (`get`/`set`/`delete`/`list`/`clear`), starter templates, parent-child event communication, and an App Gallery to browse and clone community apps
- **Contacts** — manage contacts that Kins can reference and interact with
- **Multi-provider** — 23 providers: Anthropic, Anthropic OAuth, OpenAI, Gemini, Mistral, DeepSeek, Groq, Together AI, Fireworks AI, Ollama, OpenRouter, Cohere, xAI, Voyage AI, Jina AI, Nomic, Tavily, Serper, Perplexity, Replicate, Stability AI, FAL AI, Brave Search
#### Experience
- **8 color palettes** — Aurora, Ocean, Forest, Sunset, Monochrome, Sakura, Neon, Lavender
- **Dark / Light / System** theme modes
- **Internationalization** — English and French
- **File uploads** — share files with Kins; image generation supported
- **Real-time streaming** — SSE-based, multiplexed across all Kins on a single connection
- **@mentions** — mention Kins and users in messages with autocomplete and styled pills; mentioned Kins receive notifications
- **Responsive UI** — mobile-friendly settings, contextual info tips, suggestion chips in empty chat states
- **System info** — version, uptime, and stats visible in settings
#### Built-in Tools (120+)
Kins have access to a rich set of native tools out of the box, no configuration needed:
**Memory & Knowledge** — `recall`, `memorize`, `update_memory`, `forget`, `list_memories`, `review_memories`, `search_history`, `search_knowledge`, `list_knowledge_sources`
**Web & Browsing** — `web_search`, `browse_url`, `extract_links`, `screenshot_url`
**Contacts** — `get_contact`, `search_contacts`, `create_contact`, `update_contact`, `delete_contact`, `find_contact_by_identifier`, `set_contact_note`
**Vault & Secrets** — `get_secret`, `create_secret`, `update_secret`, `delete_secret`, `search_secrets`, `redact_message`, vault entries & attachments
**Multi-Agent** — `spawn_self`, `spawn_kin`, `send_message`, `reply`, `list_kins`, `report_to_parent`, `request_input`, task management, `create_kin`, `update_kin`, `delete_kin`, `get_kin_details`
**Automation** — `create_cron`, `update_cron`, `delete_cron`, `list_crons`, `trigger_cron`, `get_cron_journal`, `wake_me_in`, `wake_me_every`, `cancel_wakeup`, `list_wakeups`, webhooks (CRUD)
**Mini Apps** — create, update, delete, read/write files, snapshots, rollback, persistent key-value storage, browse & clone from the App Gallery, templates, docs, icon generation
**Channels** — `list_channels`, `list_channel_conversations`, `send_channel_message`
**Plugins** — `list_installed_plugins`, `browse_plugin_store`, `install_plugin`, `uninstall_plugin`, `enable_plugin`, `disable_plugin`, `configure_plugin`, `get_plugin_details`, `check_plugin_updates`, `update_plugin`
**Custom Tools** — `register_tool`, `run_custom_tool`, `list_custom_tools` (Kins write and run their own scripts)
**Filesystem** — `read_file`, `write_file`, `edit_file`, `list_directory` (read, create, edit, and browse files in the workspace)
**Files & Images** — `store_file`, `get_stored_file`, `list_stored_files`, `search_stored_files`, `update_stored_file`, `delete_stored_file`, `attach_file`, `generate_image`, `list_image_models`
**System** — `run_shell`, `execute_sql`, `get_platform_logs`, `get_system_info`, user management
**MCP** — `add_mcp_server`, `update_mcp_server`, `remove_mcp_server`, `list_mcp_servers`
**HTTP** — `http_request` (make HTTP requests to external APIs with full method/header/body control)
**Human-in-the-Loop** — `prompt_human` (ask user for approval before sensitive actions), `notify` (push notifications)
## 🔍 How does KinBot compare?
| Feature | KinBot | ChatGPT | Open WebUI | LobeChat | AnythingLLM | OpenClaw | CrewAI |
|---|:---:|:---:|:---:|:---:|:---:|:---:|:---:|
| Self-hosted / your data | ✅ | ❌ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Persistent agent identity | ✅ | ⚠️ | ❌ | ⚠️ | ⚠️ | ⚠️ | ❌ |
| Long-term memory | ✅ | ⚠️ | ❌ | ❌ | ⚠️ | ⚠️ | ❌ |
| Session compacting | ✅ | ❌ | ❌ | ❌ | ❌ | ⚠️ | ❌ |
| Multi-agent collaboration | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ |
| Sub-agent delegation | ✅ | ❌ | ❌ | ❌ | ❌ | ⚠️ | ✅ |
| Cron jobs / autonomy | ✅ | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ |
| Encrypted secrets vault | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
| MCP tool servers | ✅ | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ |
| Multi-provider (23+) | ✅ | ❌ | ✅ | ✅ | ✅ | ✅ | ⚠️ |
| Webhooks | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
| Chat integrations (6 platforms) | ✅ | ❌ | ❌ | ❌ | ⚠️ | ✅ | ❌ |
| Custom tools (agent-created) | ✅ | ❌ | ❌ | ❌ | ❌ | ⚠️ | ⚠️ |
| Mini Apps (agent-built UIs) | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ |
| Plugin system (hot-reload) | ✅ | ❌ | ⚠️ | ✅ | ⚠️ | ⚠️ | ❌ |
| RAG / document embedding | ✅ | ⚠️ | ✅ | ⚠️ | ✅ | ❌ | ⚠️ |
| Multi-user with roles | ✅ | ✅ | ✅ | ⚠️ | ✅ | ❌ | ❌ |
| Web UI | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ |
| Zero-infra (no Postgres/Redis) | ✅ | ❌ | ❌ | ⚠️ | ❌ | ✅ | ✅ |
| Free & open source | ✅ | ❌ | ✅ | ✅ | ✅ | ✅ | ✅ |
✅ Full support · ⚠️ Partial · ❌ Not available · *Based on default capabilities as of March 2026*
**vs ChatGPT:** Great for quick questions, but ephemeral sessions, cloud-only, no self-hosting.
**vs OpenClaw:** Powerful single-agent personal assistant, CLI-first. KinBot is multi-agent, multi-user, web UI, with inter-agent collaboration.
**vs CrewAI / AutoGPT:** Task orchestration frameworks where agents execute a workflow and disappear. No persistence, no memory between runs. KinBot agents live permanently, accumulate knowledge, and work autonomously on schedules. Contractors vs. a team.
👉 [Full comparison with positioning details](https://marlburrow.github.io/kinbot/#comparison)
---
## 🚀 Quick Start
```bash
docker run -d --name kinbot -p 3000:3000 -v kinbot-data:/app/data ghcr.io/marlburrow/kinbot:latest
```
Open `http://localhost:3000` — done. The onboarding wizard handles the rest.
Other install methods (one-liner script, Docker Compose, manual)
### One-liner install (Linux / macOS)
```bash
curl -fsSL https://raw.githubusercontent.com/MarlBurroW/kinbot/main/install.sh | bash
```
This script will:
1. Install [Bun](https://bun.sh) if not already present
2. Clone the repository to `/opt/kinbot`
3. Install dependencies and build the frontend
4. Run database migrations
5. Create a system service (systemd on Linux, launchd on macOS)
6. Start KinBot on port **3000**
**Customizable via env vars:**
```bash
KINBOT_DIR=/home/me/kinbot \
KINBOT_DATA_DIR=/home/me/kinbot-data \
KINBOT_PORT=8080 \
bash <(curl -fsSL https://raw.githubusercontent.com/MarlBurroW/kinbot/main/install.sh)
```
### Docker Compose
```bash
git clone https://github.com/MarlBurroW/kinbot.git
cd kinbot/docker
ENCRYPTION_KEY=$(openssl rand -hex 32) docker compose up -d
```
See [`docker/docker-compose.yml`](docker/docker-compose.yml) for full options.
### Manual
```bash
git clone https://github.com/MarlBurroW/kinbot.git
cd kinbot
bun install
bun run build
bun run db:migrate
NODE_ENV=production bun run start
```
---
## Architecture
```
┌──────────────────────────────┐
│ Channels │
│ Telegram · Discord · Slack │
│ WhatsApp · Signal · Matrix │
└──────────────┬───────────────┘
│
┌───────────────────────────────────┼───────────────────────────┐
│ KinBot (single process) │
│ │ │
│ ┌──────────────────┐ ┌───────▼───────────────────────┐ │
│ │ React + Vite │ │ Hono REST API │ │
│ │ Tailwind 4 │◀────▶│ + SSE stream │ │
│ │ shadcn/ui │ └───────┬───────────────────────┘ │
│ └──────────────────┘ │ │
│ │ │
│ ┌───────────┬───────────┬───────────┬───────────┐ │
│ │ │ │ │ │ │
│ ┌─▼────────┐┌─▼────────┐┌─▼────────┐┌─▼────────┐┌─▼──────┐ │
│ │ Vercel ││ Queue ││ Croner ││ Mini ││Plugins │ │
│ │ AI SDK ││ (FIFO) ││(Cron ││ Apps ││ │ │
│ │ Kin ││ per Kin ││ jobs) ││ + Tools ││ tools │ │
│ │ Engine │└──────────┘└──────────┘└──────────┘│ hooks │ │
│ └────┬─────┘ │providers│ │
│ │ │channels│ │
│ │ └────────┘ │
│ ┌────▼────────────────────────────────────────────────────┐ │
│ │ SQLite (bun:sqlite + Drizzle ORM) │ │
│ │ + FTS5 (full-text search) │ │
│ │ + sqlite-vec (vector similarity) │ │
│ └─────────────────────────────────────────────────────────┘ │
└──────────┬───────────────────────────────────┬───────────────┘
│ │
AI Providers (23) Integrations
Anthropic · OpenAI · Gemini MCP servers
Mistral · DeepSeek · Groq Webhooks
Ollama · OpenRouter · xAI Custom tools
Cohere · Together · Fireworks Web browsing
+ embedding, image, search Plugins (community)
```
**Key design principles:**
- **Queue per Kin** — one message processed at a time per Kin; user messages have priority over automated ones
- **Global SSE** — one SSE connection per browser tab, multiplexed by `kinId`; no per-Kin polling
- **No message deletion** — compacting compresses older messages into dated summaries that merge telescopically; original messages always preserved
- **Secrets stay in the vault** — vault secrets are never exposed in prompts; redaction prevents leaking into summaries
---
## Tech Stack
| Layer | Technology |
|---|---|
| **Runtime** | [Bun](https://bun.sh) |
| **Backend** | [Hono](https://hono.dev), [Drizzle ORM](https://orm.drizzle.team), bun:sqlite, [sqlite-vec](https://github.com/asg017/sqlite-vec), [Vercel AI SDK](https://sdk.vercel.ai), [Better Auth](https://www.better-auth.com), [croner](https://github.com/Hexagon/croner) |
| **Frontend** | [React 19](https://react.dev), [Vite](https://vite.dev), [Tailwind CSS 4](https://tailwindcss.com), [shadcn/ui](https://ui.shadcn.com), [i18next](https://www.i18next.com) |
| **AI Providers** | Anthropic, OpenAI, Gemini, Mistral, DeepSeek, Groq, Together AI, Fireworks AI, Ollama, OpenRouter, Cohere, xAI, Voyage AI, Jina AI, Nomic, Tavily, Serper, Perplexity, Replicate, Stability AI, FAL AI, Brave Search |
| **Database** | SQLite (single file) + FTS5 + sqlite-vec |
---
## Configuration
Copy `.env.example` to `.env` and adjust as needed. All values have sensible defaults — you can start with an empty `.env`.
| Variable | Default | Description |
|---|---|---|
| `PORT` | `3333` | HTTP server port |
| `HOST` | `127.0.0.1` | Bind address (`0.0.0.0` to expose on all interfaces) |
| `KINBOT_DATA_DIR` | `./data` | Persistent data directory (DB, uploads, workspaces) |
| `ENCRYPTION_KEY` | *(auto-generated)* | 64-char hex key for AES-256-GCM vault encryption. Auto-generated and persisted to `data/.encryption-key` on first run. |
| `LOG_LEVEL` | `info` | `debug` \| `info` \| `warn` \| `error` |
| `PUBLIC_URL` | `http://localhost:3333` | Public-facing URL (used in webhooks, invitation links) |
See [`.env.example`](.env.example) for the complete list of all options (compacting thresholds, memory tuning, queue settings, cron limits, web browsing, etc.).
---
## Development
### Prerequisites
- [Bun](https://bun.sh) >= 1.0
- Git
### Setup
```bash
git clone https://github.com/MarlBurroW/kinbot.git
cd kinbot
bun install
bun run dev # Starts Vite dev server (port 5173) + Hono backend (port 3333)
```
The dev server proxies API requests from port 5173 to 3333 automatically.
### Commands
| Command | Description |
|---|---|
| `bun run dev` | Start dev servers (Vite + Hono with hot reload) |
| `bun run build` | Production build (Vite → `dist/client/`) |
| `bun run start` | Start production server |
| `bun run db:generate` | Generate a new Drizzle migration from schema changes |
| `bun run db:migrate` | Apply pending migrations to the SQLite database |
### Project structure
```
src/
server/ # Bun + Hono backend
routes/ # REST API routes (one file per resource)
services/ # Business logic
providers/ # AI provider implementations
tools/ # Native tools exposed to Kins
db/ # SQLite connection, Drizzle schema, migrations
auth/ # Better Auth config + middleware
sse/ # SSE manager
config.ts # Centralized configuration
client/ # React + Vite frontend
pages/ # Page components
components/ # UI components (shadcn/ui + custom)
hooks/ # Custom React hooks
locales/ # i18n translation files (en.json, fr.json)
styles/ # Design tokens + Tailwind config
shared/ # Types and constants shared by client and server
types.ts
constants.ts
data/ # Created at runtime — SQLite DB, uploads, workspaces
plugins/ # Community & custom plugins (each with manifest.json + main entry)
docker/ # Dockerfile + docker-compose.yml
site/ # GitHub Pages landing site
```
### Adding a new language
1. Copy `src/client/locales/en.json` to `src/client/locales/.json`
2. Translate all values (keys must remain identical)
3. Register the language in `src/client/lib/i18n.ts`
---
## ⚙️ Environment Variables
All settings have sensible defaults. Override only what you need.
Full configuration reference
#### Core
| Variable | Default | Description |
|----------|---------|-------------|
| `PORT` | `3333` | HTTP server port |
| `HOST` | `127.0.0.1` | Bind address (`0.0.0.0` to expose externally) |
| `NODE_ENV` | `development` | Set to `production` for optimized builds |
| `PUBLIC_URL` | `http://localhost:{PORT}` | Public-facing URL (for OAuth callbacks, webhooks) |
| `KINBOT_DATA_DIR` | `./data` | Data directory (DB, uploads, workspaces) |
| `ENCRYPTION_KEY` | Auto-generated | AES-256 key for vault encryption. Auto-generated and persisted on first run. Must be preserved across restarts. |
| `LOG_LEVEL` | `info` | Log verbosity: `debug`, `info`, `warn`, `error` |
| `DB_PATH` | `{dataDir}/kinbot.db` | SQLite database file path |
#### Memory & Compacting
| Variable | Default | Description |
|----------|---------|-------------|
| `COMPACTING_THRESHOLD_PERCENT` | `75` | Context usage % before compaction triggers |
| `COMPACTING_KEEP_PERCENT` | `40` | % of context window preserved as raw messages |
| `COMPACTING_SUMMARY_BUDGET_PERCENT` | `20` | Max % of context for summaries before telescopic merge |
| `COMPACTING_MAX_SUMMARIES` | `10` | Max active summaries before telescopic merge |
| `COMPACTING_MAX_SUMMARIES_PER_KIN` | `50` | Total summary retention per Kin (active + archived) |
| `COMPACTING_MODEL` | Provider default | Override the model used for session compacting |
| `MEMORY_EXTRACTION_MODEL` | Provider default | Override the model used for memory extraction |
| `MEMORY_MAX_RELEVANT` | `10` | Max relevant memories injected into context |
| `MEMORY_SIMILARITY_THRESHOLD` | `0.7` | Minimum cosine similarity for memory retrieval |
| `MEMORY_EMBEDDING_MODEL` | `text-embedding-3-small` | Embedding model for memory vectors |
| `MEMORY_EMBEDDING_DIMENSION` | `1536` | Vector dimension for embeddings |
| `MEMORY_TOKEN_BUDGET` | `0` | Max tokens for memory block in prompt (`0` = unlimited) |
| `MEMORY_RERANK_MODEL` | Provider default | Cross-encoder rerank model (Cohere, Jina) for memory retrieval |
| `MEMORY_CONSOLIDATION_MODEL` | Provider default | Model used for memory consolidation |
| `MEMORY_CONSOLIDATION_SIMILARITY` | `0.85` | Cosine similarity threshold for merging duplicate memories |
| `MEMORY_CONSOLIDATION_MAX_GEN` | `5` | Max consolidation generations per run |
| `MEMORY_MULTI_QUERY_MODEL` | Provider default | Model for multi-query expansion during recall |
| `MEMORY_HYDE_MODEL` | Provider default | Model for HyDE (hypothetical document embedding) queries |
| `MEMORY_CONTEXTUAL_REWRITE_MODEL` | Provider default | Model for contextual memory rewriting |
| `MEMORY_CONTEXTUAL_REWRITE_THRESHOLD` | `80` | Token threshold to trigger contextual rewrite |
| `MEMORY_ADAPTIVE_K` | `true` | Enable adaptive K (dynamic result count based on score distribution) |
| `MEMORY_ADAPTIVE_K_MIN_SCORE_RATIO` | `0.3` | Minimum score ratio for adaptive K cutoff |
| `MEMORY_RRF_K` | `60` | Reciprocal Rank Fusion K parameter for hybrid search |
| `MEMORY_FTS_BOOST` | `0.5` | Full-text search score boost factor |
| `MEMORY_SUBJECT_BOOST` | `1.3` | Score boost for subject-matching memories |
| `MEMORY_CATEGORY_BOOST` | `1.25` | Score boost for category-matching memories |
| `MEMORY_TEMPORAL_DECAY_LAMBDA` | `0.01` | Temporal decay rate (higher = faster decay) |
| `MEMORY_TEMPORAL_DECAY_FLOOR` | `0.7` | Minimum score multiplier from temporal decay |
| `HISTORY_TOKEN_BUDGET` | `40000` | Max tokens for conversation history in context |
#### Tasks & Queues
| Variable | Default | Description |
|----------|---------|-------------|
| `QUEUE_POLL_INTERVAL` | `500` | Queue polling interval in ms |
| `TASKS_MAX_DEPTH` | `3` | Maximum sub-task nesting depth |
| `TASKS_MAX_REQUEST_INPUT` | `3` | Max concurrent task requests per input |
| `TASKS_MAX_CONCURRENT` | `10` | Max concurrent tasks globally |
| `TOOLS_MAX_STEPS` | `10` | Max tool call steps per LLM turn |
#### Cron & Automation
| Variable | Default | Description |
|----------|---------|-------------|
| `CRONS_MAX_ACTIVE` | `50` | Max active cron jobs |
| `CRONS_MAX_CONCURRENT_EXEC` | `5` | Max concurrent cron executions |
#### Inter-Kin Communication
| Variable | Default | Description |
|----------|---------|-------------|
| `INTER_KIN_MAX_CHAIN_DEPTH` | `5` | Max chain depth for Kin-to-Kin messages |
| `INTER_KIN_RATE_LIMIT` | `20` | Max inter-Kin messages per minute |
#### Channels & Webhooks
| Variable | Default | Description |
|----------|---------|-------------|
| `CHANNELS_MAX_PER_KIN` | `5` | Max channel connections per Kin |
| `WEBHOOKS_MAX_PER_KIN` | `20` | Max webhooks per Kin |
| `WEBHOOKS_MAX_PAYLOAD_BYTES` | `1048576` | Max webhook payload size (1 MB) |
| `WEBHOOKS_LOG_RETENTION_DAYS` | `30` | Webhook execution log retention period |
| `WEBHOOKS_MAX_LOGS_PER_WEBHOOK` | `500` | Max stored execution logs per webhook |
| `WEBHOOKS_RATE_LIMIT_PER_MINUTE` | `60` | Max webhook executions per minute |
#### File Storage & Uploads
| Variable | Default | Description |
|----------|---------|-------------|
| `UPLOAD_DIR` | `{dataDir}/uploads` | Upload directory |
| `UPLOAD_MAX_FILE_SIZE` | `50` | Max upload size in MB |
| `UPLOAD_CHANNEL_RETENTION_DAYS` | `30` | Channel file retention period in days |
| `UPLOAD_CHANNEL_CLEANUP_INTERVAL` | `60` | Channel file cleanup interval in minutes |
| `FILE_STORAGE_DIR` | `{dataDir}/storage` | Kin file storage directory |
| `FILE_STORAGE_MAX_SIZE` | `100` | Max file size in MB |
| `FILE_STORAGE_CLEANUP_INTERVAL` | `60` | Cleanup interval in minutes |
#### Vault
| Variable | Default | Description |
|----------|---------|-------------|
| `VAULT_ATTACHMENT_DIR` | `{dataDir}/vault` | Vault attachment directory |
| `VAULT_MAX_ATTACHMENT_SIZE` | `50` | Max attachment size in MB |
| `VAULT_MAX_ATTACHMENTS_PER_ENTRY` | `10` | Max attachments per vault entry |
#### Workspaces & Mini Apps
| Variable | Default | Description |
|----------|---------|-------------|
| `WORKSPACE_BASE_DIR` | `{dataDir}/workspaces` | Kin workspace base directory |
| `MINI_APPS_DIR` | `{dataDir}/mini-apps` | Mini apps storage directory |
| `MINI_APPS_MAX_PER_KIN` | `20` | Max mini apps per Kin |
| `MINI_APPS_MAX_FILE_SIZE` | `5` | Max single file size in MB |
| `MINI_APPS_MAX_TOTAL_SIZE` | `50` | Max total size per app in MB |
| `MINI_APPS_BACKEND_ENABLED` | `true` | Enable mini app backend execution |
#### Web Browsing
| Variable | Default | Description |
|----------|---------|-------------|
| `WEB_BROWSING_PAGE_TIMEOUT` | `30000` | Page load timeout in ms |
| `WEB_BROWSING_MAX_CONTENT_LENGTH` | `100000` | Max extracted content length |
| `WEB_BROWSING_MAX_CONCURRENT` | `5` | Max concurrent fetches |
| `WEB_BROWSING_USER_AGENT` | KinBot default | Custom User-Agent string |
| `WEB_BROWSING_BLOCKED_DOMAINS` | *(empty)* | Comma-separated blocked domains |
| `WEB_BROWSING_PROXY` | *(none)* | HTTP proxy for web requests |
| `WEB_BROWSING_HEADLESS_ENABLED` | `false` | Enable headless browser (Puppeteer) |
| `PUPPETEER_EXECUTABLE_PATH` | Auto-detected | Chrome/Chromium path for headless mode |
| `WEB_BROWSING_MAX_BROWSERS` | `2` | Max concurrent browser instances |
| `WEB_BROWSING_BROWSER_IDLE_TIMEOUT` | `60000` | Browser idle timeout in ms |
#### MCP & Human-in-the-Loop
| Variable | Default | Description |
|----------|---------|-------------|
| `MCP_REQUIRE_APPROVAL` | `true` | Require user approval for MCP server management |
| `HUMAN_PROMPTS_MAX_PENDING` | `5` | Max pending human-in-the-loop prompts per Kin |
#### Sessions & Invitations
| Variable | Default | Description |
|----------|---------|-------------|
| `QUICK_SESSION_EXPIRATION_HOURS` | `24` | Quick session expiration time |
| `QUICK_SESSION_MAX_PER_USER_KIN` | `1` | Max active quick sessions per user per Kin |
| `QUICK_SESSION_RETENTION_DAYS` | `7` | Quick session data retention |
| `QUICK_SESSION_CLEANUP_INTERVAL` | `60` | Cleanup interval in minutes |
| `INVITATION_DEFAULT_EXPIRY_DAYS` | `7` | Default invitation link expiry |
| `INVITATION_MAX_ACTIVE` | `50` | Max active invitations |
#### Notifications
| Variable | Default | Description |
|----------|---------|-------------|
| `NOTIFICATIONS_RETENTION_DAYS` | `30` | Notification retention period |
| `NOTIFICATIONS_MAX_PER_USER` | `500` | Max stored notifications per user |
| `NOTIFICATIONS_EXT_MAX_PER_USER` | `5` | Max external notification endpoints per user |
| `NOTIFICATIONS_EXT_RATE_LIMIT` | `5` | External notification rate limit per minute |
| `NOTIFICATIONS_EXT_MAX_ERRORS` | `5` | Max consecutive errors before disabling endpoint |
#### Wakeups
| Variable | Default | Description |
|----------|---------|-------------|
| `WAKEUPS_MAX_PENDING_PER_KIN` | `20` | Max pending wakeups per Kin |
#### Version Check
| Variable | Default | Description |
|----------|---------|-------------|
| `VERSION_CHECK_ENABLED` | `false` | Enable automatic version checking |
| `VERSION_CHECK_REPO` | `MarlBurroW/kinbot` | GitHub repo to check for new releases |
| `VERSION_CHECK_INTERVAL_HOURS` | `12` | Hours between version checks |
---
## 🔧 Troubleshooting
Common issues and solutions
#### Port already in use
```
Error: listen EADDRINUSE :::3000
```
Another process is using port 3000. Either stop it or change KinBot's port:
```bash
PORT=3001 bun src/server/index.ts
# or with Docker:
docker run -d -p 3001:3000 ghcr.io/marlburrow/kinbot:latest
```
#### Database migration errors after update
If you see migration errors after updating KinBot:
```bash
# Backup first
cp data/kinbot.db data/kinbot.db.bak
# Re-run migrations
bun run db:migrate
```
#### Docker container won't start
Check logs for details:
```bash
docker logs kinbot
```
Common causes:
- **Permission issues on volume:** Ensure the data directory is writable (`chmod 777 ./data` or match UID)
- **Missing encryption key:** If you previously set `ENCRYPTION_KEY`, you must provide it on every restart (vault data is encrypted with it)
#### Provider connection fails
- Verify your API key is correct and has sufficient credits
- For self-hosted providers (Ollama), ensure the base URL is reachable from the KinBot container (use `host.docker.internal` or the host's LAN IP, not `localhost`)
- Check provider status pages for outages
#### Memory search returns no results
Memory extraction runs asynchronously after each LLM turn. If you just started a conversation:
- Wait a few seconds for the extraction pipeline to complete
- Check that you have an embedding provider configured in Settings > Providers
#### Blank page / frontend not loading
```bash
# Rebuild the frontend
bun run build
# Then restart
bun src/server/index.ts
```
For Docker, pull the latest image which includes pre-built frontend assets.
#### Generate a diagnostic report
If you're stuck, generate a report to include in bug reports:
```bash
bash install.sh --doctor
```
---
## 💬 Community & Support
- **Issues** — [Report bugs or request features](https://github.com/MarlBurroW/kinbot/issues)
- **Discussions** — [Questions, ideas, and show & tell](https://github.com/MarlBurroW/kinbot/discussions)
- **Contributing** — [Read the guide](CONTRIBUTING.md) to get started
- **Security** — [Report vulnerabilities responsibly](SECURITY.md)
- **Changelog** — [See what's new](https://marlburrow.github.io/kinbot/changelog)
If KinBot is useful to you, consider [starring the repo](https://github.com/MarlBurroW/kinbot) — it helps others discover the project.
## Contributing
Contributions are welcome! See **[CONTRIBUTING.md](CONTRIBUTING.md)** for the full guide: setup, adding providers/channels, code style, and commit conventions.
Quick version:
1. Fork the repository
2. Create a feature branch: `git checkout -b feat/my-feature`
3. Follow existing code conventions:
- Files: `kebab-case.ts` / Components: `PascalCase.tsx`
- Shared types in `src/shared/types.ts`; shared constants in `src/shared/constants.ts`
- API errors: `{ "error": { "code": "ERROR_CODE", "message": "..." } }`
- Never hardcode user-facing text — always use `useTranslation()` and add keys to both `en.json` and `fr.json`
4. Open a Pull Request with a clear description
### Design system
The UI is built on a custom design system with 8 palettes and full dark/light mode support. Before building any new UI:
- Consult `src/client/pages/design-system/DesignSystemPage.tsx` (live showcase, source of truth)
- Use semantic CSS variables (`var(--color-*)`) or Tailwind tokens — never hardcode colors
- Reuse components from `src/client/components/ui/`
---
## License
KinBot is licensed under the [GNU Affero General Public License v3.0](LICENSE) (AGPL-3.0).
You are free to use, modify, and distribute KinBot. However, if you deploy a modified version as a network service, you must also make your source code available under the same license. This protects against cloud-washing while keeping the project fully open.
For commercial use cases where the AGPL obligations are not compatible with your business, a commercial license is available — open an issue to discuss.
---