{"id":50708100,"url":"https://github.com/marlburrow/hivekeep","last_synced_at":"2026-06-17T01:01:21.010Z","repository":{"id":363320710,"uuid":"1262267135","full_name":"MarlBurroW/hivekeep","owner":"MarlBurroW","description":"Hivekeep is a self-hosted platform of autonomous, persistent personal AI agents. Your AI team. At home.","archived":false,"fork":false,"pushed_at":"2026-06-16T19:07:32.000Z","size":182727,"stargazers_count":17,"open_issues_count":18,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-06-16T19:14:16.542Z","etag":null,"topics":["agents","ai-agents","ai-assistant","automation","bun","chatbot","docker","llm","multi-agent-systems","personal-assistant","self-hosted","telegram-bot"],"latest_commit_sha":null,"homepage":"https://hivekeep.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/MarlBurroW.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"MarlBurroW"}},"created_at":"2026-06-07T19:32:15.000Z","updated_at":"2026-06-16T19:10:12.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/MarlBurroW/hivekeep","commit_stats":null,"previous_names":["marlburrow/hivekeep"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/MarlBurroW/hivekeep","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MarlBurroW%2Fhivekeep","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MarlBurroW%2Fhivekeep/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MarlBurroW%2Fhivekeep/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MarlBurroW%2Fhivekeep/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MarlBurroW","download_url":"https://codeload.github.com/MarlBurroW/hivekeep/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MarlBurroW%2Fhivekeep/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34429493,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-16T02:00:06.860Z","response_time":126,"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-agents","ai-assistant","automation","bun","chatbot","docker","llm","multi-agent-systems","personal-assistant","self-hosted","telegram-bot"],"created_at":"2026-06-09T13:02:04.195Z","updated_at":"2026-06-17T01:01:20.991Z","avatar_url":"https://github.com/MarlBurroW.png","language":"TypeScript","funding_links":["https://github.com/sponsors/MarlBurroW"],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\u003cimg src=\"docs/assets/logo.svg\" width=\"120\" alt=\"Hivekeep\" /\u003e\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eHivekeep\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eYour AI team. At home.\u003c/strong\u003e\u003cbr /\u003e\n  The simplicity of a consumer assistant, the sovereignty of your own server.\u003cbr /\u003e\n  A self-hosted platform of persistent AI agents that remember, collaborate, and answer you everywhere, in a single container.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003csub\u003e100% open-source (MIT) · self-hosted · zero external infra\u003c/sub\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-MIT-AE5AF9?style=flat-square\" alt=\"License MIT\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/MarlBurroW/hivekeep/releases\"\u003e\u003cimg src=\"https://img.shields.io/github/v/release/MarlBurroW/hivekeep?style=flat-square\u0026color=a855f7\" alt=\"Latest release\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/MarlBurroW/hivekeep/actions/workflows/ci.yml\"\u003e\u003cimg src=\"https://github.com/MarlBurroW/hivekeep/actions/workflows/ci.yml/badge.svg\" alt=\"CI\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/MarlBurroW/hivekeep/pkgs/container/hivekeep\"\u003e\u003cimg src=\"https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square\u0026logo=docker\u0026logoColor=white\" alt=\"Docker image\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/MarlBurroW/hivekeep\"\u003e\u003cimg src=\"https://img.shields.io/github/stars/MarlBurroW/hivekeep?style=flat-square\u0026color=ec4899\" alt=\"GitHub stars\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://bun.sh\"\u003e\u003cimg src=\"https://img.shields.io/badge/made%20with-Bun-000000?style=flat-square\u0026logo=bun\u0026logoColor=white\" alt=\"Made with Bun\" /\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://marlburrow.github.io/hivekeep/\"\u003eWebsite\u003c/a\u003e ·\n  \u003ca href=\"https://marlburrow.github.io/hivekeep/docs/\"\u003eDocs\u003c/a\u003e ·\n  \u003ca href=\"#get-started\"\u003eInstall\u003c/a\u003e ·\n  \u003ca href=\"#self-improving\"\u003ePlugins\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://hivekeep.app/#demo\"\u003e\n    \u003cimg src=\"docs/assets/demo-video.jpg\" alt=\"Watch the Hivekeep walkthrough — from a blank install to your own AI team in six minutes\" width=\"720\" /\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n  \u003csub\u003e\u003cstrong\u003e▶ Watch the 6-minute walkthrough\u003c/strong\u003e — onboarding, Queenie setting everything up, agents building a mini-app and a custom tool live, and a full tour.\u003c/sub\u003e\n\u003c/p\u003e\n\n---\n\n## The 30-second pitch\n\nMost AI tools treat every conversation as disposable. You explain yourself on Monday, they have forgotten by Tuesday. Hivekeep takes the opposite path: a team of persistent **Agents** that live on your server, keep their memory, and work together. Not a chatbot. A household of specialists that works like a hive.\n\n- **They never forget you.** One continuous session per Agent (no \"new conversation\"), backed by a hybrid long-term memory that accumulates months of context. No reset, ever.\n- **A team, not a chatbot.** Agents collaborate (`request` / `reply`), delegate to ephemeral sub-Agents, and run scheduled work, so several things move at once.\n- **Self-improving.** Your Agents build their own tools, mini-apps, and plugins. The platform grows with you instead of staying frozen.\n- **Everywhere.** Telegram, WhatsApp, Slack, Discord, Signal, Matrix, plus a polished PWA. An Agent can hand a channel to a specialist in real time.\n- **One container.** Zero Postgres, Redis, Mongo, or queue broker. One process, one SQLite file. Run it and Queenie sets up the rest by conversation.\n- **Your secrets stay yours.** An AES-256-GCM vault that is never exposed to the LLM, connected accounts that never leave your infrastructure, and token transparency so you stay in control of costs.\n\n---\n\n## A peek inside\n\n\u003ctable align=\"center\"\u003e\n  \u003ctr\u003e\n    \u003ctd width=\"50%\" align=\"center\" valign=\"top\"\u003e\n      \u003cimg src=\"docs/assets/screenshots/chat-briefing.webp\" alt=\"An agent answering with its calendar, backup check and reminders, every tool call shown inline\" /\u003e\u003cbr /\u003e\n      \u003csub\u003e\u003cb\u003eOne continuous conversation\u003c/b\u003e\u003cbr /\u003eEvery tool call rendered inline, never a black box.\u003c/sub\u003e\n    \u003c/td\u003e\n    \u003ctd width=\"50%\" align=\"center\" valign=\"top\"\u003e\n      \u003cimg src=\"docs/assets/screenshots/secret-popup.webp\" alt=\"An agent requesting a credential through a secure popup that stores it in the vault\" /\u003e\u003cbr /\u003e\n      \u003csub\u003e\u003cb\u003eAgents ask, never see\u003c/b\u003e\u003cbr /\u003eSecrets go straight to the encrypted vault. The model never sees the value.\u003c/sub\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd width=\"50%\" align=\"center\" valign=\"top\"\u003e\n      \u003cimg src=\"docs/assets/screenshots/miniapp-timer.webp\" alt=\"A focus-timer mini-app an agent built, running in the workspace next to the chat\" /\u003e\u003cbr /\u003e\n      \u003csub\u003e\u003cb\u003eYour agents build apps\u003c/b\u003e\u003cbr /\u003eReal mini-apps, hosted right inside Hivekeep.\u003c/sub\u003e\n    \u003c/td\u003e\n    \u003ctd width=\"50%\" align=\"center\" valign=\"top\"\u003e\n      \u003cimg src=\"docs/assets/screenshots/kanban.webp\" alt=\"A shared kanban board with tickets across backlog, to do and in progress\" /\u003e\u003cbr /\u003e\n      \u003csub\u003e\u003cb\u003eA shared kanban\u003c/b\u003e\u003cbr /\u003eProjects and tickets your agents work alongside you.\u003c/sub\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd width=\"50%\" align=\"center\" valign=\"top\"\u003e\n      \u003cimg src=\"docs/assets/screenshots/files.webp\" alt=\"A file browser and code editor for an agent's workspace\" /\u003e\u003cbr /\u003e\n      \u003csub\u003e\u003cb\u003eA real workspace\u003c/b\u003e\u003cbr /\u003eBrowse and edit every agent's files, with a proper editor.\u003c/sub\u003e\n    \u003c/td\u003e\n    \u003ctd width=\"50%\" align=\"center\" valign=\"top\"\u003e\n      \u003cimg src=\"docs/assets/screenshots/token-usage.webp\" alt=\"A token-usage dashboard with cost per agent, model and day\" /\u003e\u003cbr /\u003e\n      \u003csub\u003e\u003cb\u003eEvery token on record\u003c/b\u003e\u003cbr /\u003eCost per agent, per model, per day. No surprises.\u003c/sub\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n\u003cp align=\"center\"\u003e\u003ca href=\"https://hivekeep.app/tour/\"\u003e\u003cb\u003eTake the full tour →\u003c/b\u003e\u003c/a\u003e \u0026nbsp;·\u0026nbsp; 30+ screenshots from a running hive\u003c/p\u003e\n\n---\n\n## They never forget you\n\nEvery Agent has a persistent identity (name, role, character, expertise, model, avatar) shared across everyone on your instance, and **one continuous session** that never resets. Underneath sits a dual-channel long-term memory: automatic extraction during compaction, plus explicit tools (`recall`, `memorize`, `update_memory`, `forget`). Recall is hybrid, sqlite-vec KNN fused with FTS5 keyword search via Reciprocal Rank Fusion, then re-ranked by importance, temporal decay, and category intent. Compaction summarizes old context to stay within token limits and **never deletes the originals**, so anything can be recovered later with `search_history`.\n\n## One container. Nothing leaves your server\n\nA single process, a single SQLite file, a single Docker container. No Postgres, Redis, Mongo, SearxNG, or queue broker to provision. You bring one LLM key, and the whole platform runs on your infrastructure. Upgrading is re-pulling the image (or `git pull` for the native install). Your conversations, memories, and secrets stay on your server.\n\n## Your agents extend the platform themselves\n\nThis is the surprising part. Hivekeep is not a fixed feature set, it is a base your Agents grow:\n\n- **Custom tools, any language** (Python, Node, Bun, TypeScript, Bash, Deno) with native dependency management, and **rich React renderers** so a tool result shows up as a themed UI card, not raw JSON.\n- **Mini Apps** built by your Agents: real web apps in a sandboxed iframe, with a JS SDK, 29 React hooks, 50+ themed components (DataGrid, charts, Kanban, Calendar), an optional Hono backend, KV storage with snapshots and rollback, a public gallery with clone, 14 templates, and an \"Improve this\" natural-language edit loop.\n- **Plugins** over npm with a typed TypeScript SDK (`@hivekeep/sdk`): a built-in marketplace (any package keyworded `hivekeep-plugin`, live npm search) plus Git install, native provider interfaces, channel adapters, lifecycle hooks, granular runtime-enforced permissions, and a scaffolder (`create-hivekeep-plugin`). Fully self-hosted, no proprietary cloud.\n- **Dynamic MCP servers** the Agents can add and manage, and **toolboxes** (composable named allow-lists) to scope capabilities precisely per role.\n\n## One inbox for your whole team\n\nSix native channels: **Telegram, Discord, Slack, WhatsApp, Signal, Matrix**, plus the PWA as a seventh surface. The standout is **real-time channel handoff**: `transfer_channel` reassigns a channel from one Agent to another mid-conversation. The address does not change, the Agent does. The new Agent receives handoff context and the causal chain, with async delivery statuses throughout.\n\n\u003cp align=\"center\"\u003e\u003cimg src=\"docs/assets/screenshots/chat-channel.webp\" width=\"760\" alt=\"A smart-home request sent from Telegram: the agent runs the actions and reports back\" /\u003e\u003c/p\u003e\n\n## No black box. No cost surprises\n\nTransparency is a first-class feature, framed as \"you control your costs,\" never \"here is the bill.\" A **Context Viewer** breaks the prompt into a stacked, color-coded bar by section. Cache observability shows hit rate and TTL. Per-Agent EMA calibration compares estimated to actual token counts, and every call is tracked. The vault is AES-256-GCM, never printed in prompts or logs. Connected accounts (mail, calendar, contacts) use OAuth or encrypted credentials, and their tokens are never seen by Agents.\n\n\u003cp align=\"center\"\u003e\u003cimg src=\"docs/assets/screenshots/context-viewer.webp\" width=\"760\" alt=\"The Context Viewer breaking a prompt into a color-coded, per-section breakdown with cache hit rates\" /\u003e\u003c/p\u003e\n\n## Setup is a conversation, not a YAML file\n\nOnboarding is three quick screens (identity, language, one LLM key). Then **Queenie**, a permanent configurator Agent with 45+ tools, takes over **by conversation**: she connects providers, secures secrets in the vault, and creates your first Agents. No YAML, no CLI. Secure input means secrets go UI to vault and **never to the LLM** (only a non-sensitive confirmation comes back). One OpenAI key becomes several auto-detected capabilities. Queenie stays accessible for life.\n\n\u003cp align=\"center\"\u003e\u003cimg src=\"docs/assets/screenshots/chat-onboarding.webp\" width=\"760\" alt=\"Queenie connecting an AI provider through a secure popup during onboarding\" /\u003e\u003c/p\u003e\n\n## Build a household for your life\n\nOnly **Queenie** ships built in. Everyone else is yours to create, each with an auto-generated avatar. A few examples of what people build (names from the sample roster):\n\n| Agent | Role |\n|---|---|\n| **Atlas** | DevOps and infrastructure: CI/CD, observability, incident response |\n| **Forge** | Code assistant: full-stack development, review, refactoring, debugging |\n| **Sentinel** | Security: pentesting, threat modeling, secure code review |\n| **Prism** | Data and BI: SQL, dashboards, reporting, business intelligence |\n| **Nest** | Home automation: Home Assistant, smart devices, energy management |\n| **Sage** | Research: literature review, synthesis, fact-checking |\n| **Inbox** | Email and calendar: triage, scheduling, reminders, follow-ups |\n| **Cuisine** | Cooking: recipes, meal planning, grocery lists |\n| **Ledger** | Personal finance: budgeting, expense tracking, planning |\n| **Lexicon** | Translation and localization across languages |\n\nThe same building blocks cover a DevOps copilot, a home brain, a personal knowledge base, a multi-agent dispatcher team, a business monitor, or a shared family assistant.\n\n## Providers and plugins\n\nBring one config per provider and Hivekeep auto-detects its capabilities (`llm`, `embedding`, `image`, `search`, `stt`, `tts`). **Built in today:** Anthropic (API key and Claude Max OAuth), OpenAI (API key and Codex CLI), Google Gemini, OpenRouter, xAI, DeepSeek, MiniMax, Kimi (Moonshot), and a generic **OpenAI-compatible** connector (your own base URL, for NewAPI / LiteLLM / llama.cpp / LM Studio / vLLM / Ollama) for LLMs; OpenAI and Gemini for images; OpenAI and the OpenAI-compatible connector (local models via Ollama, llama.cpp, etc.) for embeddings; OpenAI and ElevenLabs for speech-to-text and text-to-speech; Brave Search, SerpAPI, Tavily, and Perplexity Sonar for web search. Need more? Add any provider as a **plugin** through the typed SDK, no fork required.\n\n---\n\n## Why Hivekeep\n\nSelf-hosted AI assistants like **OpenClaw** and **Hermes** are excellent: they win or tie on memory, omnichannel reach, and self-hosting too. Where Hivekeep pulls ahead is the **team**, the **polished product UI**, and **transparency**. Marks below are best-effort from public docs (June 2026); peers genuinely win or tie on several rows.\n\n| Dimension | Hivekeep | OpenClaw | Hermes |\n|---|:---:|:---:|:---:|\n| Self-hosted, your data | yes | yes | yes |\n| Persistent memory | yes | yes | yes |\n| Native omnichannel | yes | yes | yes |\n| Connected accounts (mail, calendar) | yes | no | partial |\n| Agents build their own tools / skills | yes | partial | yes |\n| Scheduled tasks (cron) | yes | yes | yes |\n| A team of agents that collaborate | yes | no | no |\n| Polished web app (PWA) | yes | partial | partial |\n| Rendered tool calls (UI, not JSON) | yes | no | no |\n| Mini-apps and projects (Kanban) | yes | no | no |\n| Conversational setup (no CLI) | yes | no | no |\n| Secrets never sent to the LLM | yes | partial | partial |\n| Token and context transparency | yes | no | no |\n\n\u003e Hivekeep is production-ready for individual and small-group use, with solid foundations and UX polish that keeps advancing. We are honest about the maturity (~80%) rather than overselling it. See the [roadmap](https://marlburrow.github.io/hivekeep/) for the known rough edges.\n\n---\n\n## Get started\n\nOne command. No `docker-compose`, no YAML, no database to provision.\n\n### Native install (recommended)\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/MarlBurroW/hivekeep/main/install.sh | bash\n```\n\nThe script installs [Bun](https://bun.sh) if needed, clones the repo, builds the frontend, runs migrations, creates a system service (systemd or launchd), and starts Hivekeep on port **3000**. It preflights disk, RAM, ports, and connectivity, and rolls back cleanly on failure.\n\nThen open `http://localhost:3000` and **Queenie takes it from there**: three quick screens, then she configures everything by conversation.\n\n### Docker (alternative)\n\n```bash\ndocker run -d \\\n  --name hivekeep \\\n  -p 3000:3000 \\\n  -v hivekeep-data:/app/data \\\n  ghcr.io/marlburrow/hivekeep:latest\n```\n\n\u003e This path requires the published container image. If the pull fails with `manifest unknown` or a `403`, the image is not public yet, use the native installer above (it builds locally and needs no registry image), or build from source. See the [install docs](https://marlburrow.github.io/hivekeep/docs/) for the Docker Compose path and reverse-proxy setup. The installer also offers a hardened Docker mode: `bash \u003c(curl -fsSL .../install.sh) --docker`.\n\n### Recovery one-liners\n\n```bash\n# Port 3000 already taken? Map another host port (Docker):\ndocker run -d -p 3001:3000 -v hivekeep-data:/app/data ghcr.io/marlburrow/hivekeep:latest\n\n# Inspect why the daemon will not start:\ndocker logs hivekeep            # Docker\njournalctl -u hivekeep -e       # native (systemd)\n\n# Generate a diagnostic report for bug reports (no local clone needed):\nbash \u003c(curl -fsSL https://raw.githubusercontent.com/MarlBurroW/hivekeep/main/install.sh) --doctor\n# Or, if you used the native installer, the wrapper it installs also works:\n#   \"$HIVEKEEP_DIR\"/hivekeep doctor   (HIVEKEEP_DIR defaults to /opt/hivekeep or ~/hivekeep)\n```\n\n\u003e **Back up your encryption key.** On first boot Hivekeep generates and persists an AES-256-GCM key at `data/.encryption-key` and encrypts all vault secrets with it. If you instead set `ENCRYPTION_KEY` yourself, you must provide the same value on every restart. Keep this key (or the `data/` directory) backed up, or you lose access to encrypted secrets.\n\nTo expose Hivekeep on your network or behind a reverse proxy, add `-e HOST=0.0.0.0` and `-e PUBLIC_URL=https://your-domain`. See the [configuration reference](config.md) for every environment variable.\n\n---\n\n## Features\n\nAll capabilities are detailed on the [website](https://marlburrow.github.io/hivekeep/) and in the [docs](https://marlburrow.github.io/hivekeep/docs/). The short version:\n\n**Persistent agents that remember and collaborate**\n- Persistent identity, expertise, and long-term memory per Agent, shared across instance users\n- One continuous session, never resets\n- Hybrid memory: sqlite-vec KNN + FTS5 fused by Reciprocal Rank Fusion, automatic extraction plus explicit tools\n- Progressive compaction that summarizes without ever deleting originals\n- Sub-Agents (`await` / `async`), inter-Agent messaging (`request` / `reply`), unified contacts registry, stateful browser\n\n**Self-hosted and self-improving platform**\n- One process, one SQLite file, one container, zero external infra\n- Custom tools in any language with rich React renderers\n- Mini Apps built by Agents (SDK, 29 hooks, 50+ themed components, optional backend, gallery)\n- Plugins over npm via a typed SDK plus a built-in marketplace, dynamic MCP, composable toolboxes\n\n**A nice agent UI (PWA)**\n- Installable PWA, responsive and mobile-first\n- 18 OKLch palettes (aurora, ocean, forest, sunset, monochrome, sakura, neon, lavender, midnight, copper, jade, crimson, galaxy, amber, slate, rose, mint, citrus) x light/dark/system x adaptive contrast\n- Glass/gradient design system, WCAG AA, i18n (10 UI languages; Agents speak 40+)\n- Rich tool renders inline, @mentions with autocomplete, real-time SSE streaming, auto-generated per-Agent avatars\n- Files: a built-in workspace browser/editor — browse, edit, upload, and share any file your Agents produce, with clickable file paths in chat\n\n**Conversational onboarding (Queenie)**\n- Minimal 3-screen onboarding, then full guided configuration by chat\n- Secure input: secrets go UI to vault, never to the LLM\n- One key becomes many auto-detected capabilities, avatars are auto-generated and customizable\n\n**Everywhere**\n- Six native channels: Telegram, Discord, Slack, WhatsApp, Signal, Matrix\n- Real-time channel handoff between Agents with handoff context and causal chain\n\n**Trust, security, and transparency**\n- AES-256-GCM vault, never exposed to the LLM\n- Connected accounts (mail, calendar, contacts) whose tokens are never seen by Agents\n- Token and context transparency: Context Viewer, cache observability, per-Agent EMA calibration\n- Multi-user isolation, quick private sessions, Better Auth with admin and member roles\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eFull feature list\u003c/strong\u003e\u003c/summary\u003e\n\n#### 1. Agent architecture and runtime\nPersistent identity and expertise per Agent (shared across users, sender-tagged messages, replies in the last speaker's language). One continuous session, never reset. Hybrid long-term memory (sqlite-vec KNN + FTS5, RRF fusion, importance/decay/category re-ranking, multi-query + HyDE + optional LLM rerank). Progressive compaction (token-aware keep-window + telescoping multi-summary, originals never deleted, triggers around 75% of the context window). FIFO queue per Agent with user-message priority. Sub-Agents (`await` / `async`, max depth 3). Inter-Agent messaging (`request` / `reply`, correlation IDs, rate-limited, chain-depth guarded). Unified contacts registry. Stateful browser (18 `browser_*` tools, Playwright + stealth + accessibility-snapshot refs). Native Anthropic prompt caching.\n\n#### 2. UI/UX, PWA, design system, theming\nInstallable PWA (hand-coded service worker, offline app shell). 18 OKLch palettes x light/dark/system x adaptive contrast (normal/soft, DB-synced cross-device). Glass/gradient design system, WCAG AA, 21 micro-interaction keyframes. i18n (10 UI languages: en, fr, es, de, pt-BR, zh-CN, ja, ru, it, pl; Agents answer in 40+ languages, independent of the UI). Rich tool renders inline. @mentions with autocomplete. Real-time SSE streaming on a single multiplexed connection. Auto-generated per-Agent avatars (3 independent axes: art style, subject, character).\n\n#### 3. Custom tools + rich renderers\nMulti-language authoring (Python, Node, Bun, TS, Bash, Deno) with native dependency management. Each tool can bundle a `renderer.tsx`, server-bundled and SSR-validated before deploy, delivered as a content-addressed ESM module. Two-phase (build + SSR) validation. Themed UI kit, native renderers for 20+ built-in tools, per-toolbox scoping.\n\n#### 4. Mini Apps\nAgents build real web apps in a sandboxed iframe. Vanilla JS SDK (theme, storage, API/HTTP proxy, memory, conversation, SSE). 29 React hooks. 50+ themed components (DataGrid, charts, Kanban, Calendar). Optional Hono backend. KV storage (snapshots, rollback). Public gallery with clone, 14 templates, an \"Improve this\" natural-language edit loop, console ring buffer.\n\n#### 5. Conversational onboarding (Queenie)\nMinimal 3-screen onboarding, then a permanent configurator Agent (`kind=configurator`) with a dedicated 45+ tool toolbox. Secure input for secrets (`request_provider_setup`, `request_channel_setup`, `prompt_secret`): UI to vault, never to the LLM. Provider connection with key reuse (one key, N capabilities), defaults, global rules, Agent creation, avatars, channels, all by chat. Admin-first-run only.\n\n#### 6. Auto-generated avatars\nEnd-to-end image generation: an LLM prompt-writer rewrites each prompt from the global style, subject type, and Agent identity. Text-to-image or image-to-image with a neutral base for cross-Agent consistency. Three UI modes (upload + crop, auto, manual).\n\n#### 7. Projects, Kanban, tickets, GitHub\nProjects with injectable context, 5-column Kanban (drag-and-drop, optimistic, SSE), tickets (tags, comments, attachments, history, mentions), per-project tags. Ticket sub-tasks in mandatory `await` with project + ticket context. Automated enrichment. GitHub integration (background clone, isolated worktree per sub-task, PAT in vault via credential helper).\n\n#### 8. Connected accounts (mail, calendar, contacts)\nGeneric multi-provider OAuth2 (Google, Microsoft 365, Apple). Mail (Gmail, Outlook/365, IMAP/SMTP). Calendar events (Google, M365, iCloud CalDAV, generic CalDAV). Read-only contact search (iCloud, Google People, MS Graph, CardDAV). Tokens cached server-side, never seen by Agents. Optional send-approval mode, per-Agent allow-list, encryption at rest. **Email triggers**: per-account condition trees (sender, domain, subject, body, attachment…, nested AND/OR) that automatically prompt a target Agent — injected into its conversation or spawned as an isolated task — when matching mail arrives (polled, with cold-start and anti-flood guards; Agents can set them up via tools).\n\n#### 9. Plugins, SDK, marketplace\nNPM-based plugins, typed TypeScript SDK (`@hivekeep/sdk`). Built-in marketplace (keyword `hivekeep-plugin`, live npm search) + Git install. Strict declarative manifest with granular permissions. Native AI tools, native provider families (LLM, embedding, image, search, TTS, STT + email/contacts/calendar), channel adapters, lifecycle hooks, interactive cards, per-plugin storage, permission-controlled HTTP, namespaced vault, scaffold CLI (`create-hivekeep-plugin`), auto-disable on error.\n\n#### 10. Toolboxes and tool scoping\nDynamic composition of `CORE_TOOLS` plus toolboxes, resolved each turn (hot reload). Nine built-in toolboxes (code, research, ops, scout, all, email, calendar, address-book, configurator). Smart wildcard (`all`/`*` covers natives + enabled custom, never MCP/plugin). Flexible assignment (Agent, task, cron, webhook), sub-Agent hard floor, scout delegation to a cheap read-only model.\n\n#### 11. Context and token transparency\nContext Viewer (stacked multicolor bar by section + detailed table). Granular per-section estimation. Provider-agnostic cache observability (read/write/fresh tokens, hit rate, residual TTL). Per-Agent EMA calibration. Exhaustive per-call usage tracking (`llm_usage`). Sensitive tool-result masking before summarization. Budget-based history trimming.\n\n#### 12. Channels and multi-Agent binding\nSix platforms (Telegram, Discord, Slack, WhatsApp, Signal, Matrix). Real-time channel transfer (`transfer_channel`, atomic mutation, audit messages, SSE, sideband hint). Mutable Agent-channel binding, inter-Agent sending with auto prefix, transfer context injected into `\u003cchannel-context\u003e`, causal chain (`channelOriginId`), async delivery statuses, attachments + vision.\n\n#### 13. Vault and secret security\nAES-256-GCM (random 12-byte IV + auth tag, auto-generated 256-bit key, `chmod 0600`). Secure UI-to-vault input (create + test + store atomically, no return to the LLM). Deterministic config references (`$vault:`). Message redaction that blocks compacting leakage. Typed vault entries (credential, card, note, identity, custom), metadata-only search, encrypted attachments.\n\n#### 14. Memory system\nDual-channel capture (automatic with KNN dedup + explicit with category/importance/subject/scope). Hybrid search (KNN cosine + FTS5, RRF, multi-query + optional HyDE). Post-fusion ranking (decay, importance, retrieval boost, subject boost, category intent). Optional LLM rerank + adaptive-K trimming, auto consolidation of near-duplicates, importance recalibration, conservative stale pruning, pluggable embeddings with FTS-only graceful degradation, scoped memories.\n\n#### 15. Automation\nCrons (POSIX/ISO8601, one-shot, croner in-process; Agent-created crons need user approval; cron learnings auto-saved). Webhooks (SHA256 token, simple/regex filters, templates, rate-limited). Human-in-the-loop (`prompt_human`: confirm/select/text). Scout (read-only delegation to a cheap model). Wakeups (`wake_me_in` / `wake_me_every`). Persistent task queue with concurrency groups and frozen snapshots.\n\n#### 16. Platform and power-user\nDynamic MCP servers (Agents manage their own). Real-time system logs (ring buffer, filterable, SSE). Direct SQL (opt-in, bound params, row cap). Platform config with secret redaction. Centralized contacts with scoped notes. Shareable files (public/password/expiring/burn). Quick private sessions per user. Multi-channel notifications. Pluggable provider resolver (one config, auto-detected capabilities).\n\n#### Built-in tools (120+)\nA rich set of native tools out of the box across Memory/Knowledge, Web/Browsing, Contacts, Vault, Multi-Agent, Automation, Mini Apps, Channels, Custom Tools, Filesystem, Files/Images, System, MCP, HTTP, and Human-in-the-Loop. Examples: `recall`, `memorize`, `search_history`, `web_search`, `browse_url`, `spawn_agent`, `send_message`, `reply`, `create_cron`, `transfer_channel`, `create_mini_app`, `register_tool`, `run_shell`, `add_mcp_server`, `http_request`, `prompt_human`.\n\n\u003c/details\u003e\n\n---\n\n## Architecture\n\nOne process, one SQLite file, one container. Everything is here, nothing external to wire up.\n\n- **Native LLM primitives.** AI providers are implemented natively, organized by capability in `src/server/llm/{llm,embedding,image,search,stt,tts,core}/`. There is no external agent-orchestration SDK in the loop. Plugins consume the same surface through `@hivekeep/sdk`.\n- **Queue per Agent.** A serialized FIFO per Agent with user-message priority, so there are no race conditions on shared context.\n- **Global SSE.** One real-time connection per client, multiplexed by `agentId`. No per-Agent connections.\n- **No message deletion.** Compaction compresses older messages into dated summaries that merge telescopically. Originals are always preserved and recoverable.\n- **Secrets stay in the vault.** Vault secrets are never placed in prompts. Redaction prevents leaks into summaries.\n- **Pluggable providers.** One config per provider, capabilities (`llm`, `embedding`, `image`, `search`, `stt`, `tts`) auto-detected.\n\nFull details in the [technical docs](https://marlburrow.github.io/hivekeep/docs/).\n\n---\n\n## Tech stack\n\n| Layer | Technology |\n|---|---|\n| **Runtime** | [Bun](https://bun.sh) |\n| **Backend** | [Hono](https://hono.dev), [Drizzle ORM](https://orm.drizzle.team), bun:sqlite, [sqlite-vec](https://github.com/asg017/sqlite-vec), native LLM primitives (`src/server/llm/*`), [Better Auth](https://www.better-auth.com), [croner](https://github.com/Hexagon/croner) |\n| **Frontend** | [React](https://react.dev), [Vite](https://vite.dev), [Tailwind CSS](https://tailwindcss.com), [shadcn/ui](https://ui.shadcn.com), [i18next](https://www.i18next.com) |\n| **LLM providers** | Anthropic, OpenAI, Google Gemini, OpenRouter, xAI, DeepSeek, MiniMax, Kimi, OpenAI-compatible (any custom base URL) (plus image, embedding, search, and speech providers; more via plugins) |\n| **Database** | SQLite (single file) + FTS5 + sqlite-vec |\n\n---\n\n## Configuration\n\nAll values have sensible defaults, you can start with an empty `.env`. The most common ones:\n\n| Variable | Default | Description |\n|---|---|---|\n| `PORT` | `3000` | HTTP server port |\n| `HOST` | `127.0.0.1` | Bind address (`0.0.0.0` to expose on all interfaces) |\n| `HIVEKEEP_DATA_DIR` | `./data` | Persistent data directory (DB, uploads, workspaces) |\n| `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. Keep it backed up. |\n| `LOG_LEVEL` | `info` | `debug` / `info` / `warn` / `error` |\n| `PUBLIC_URL` | `http://localhost:3000` | Public-facing URL (webhooks, invitation links) |\n\nSee [`config.md`](config.md) and [`.env.example`](.env.example) for the complete reference (compaction thresholds, memory tuning, queue settings, cron limits, web browsing, and more).\n\n---\n\n## Development\n\n### Prerequisites\n\n- [Bun](https://bun.sh) 1.3+\n- Git\n\n### Setup\n\n```bash\ngit clone https://github.com/MarlBurroW/hivekeep.git\ncd hivekeep\nbun install\nbun run dev    # Vite dev server (5173) + Hono backend (3000)\n```\n\n### Commands\n\n| Command | Description |\n|---|---|\n| `bun run dev` | Start dev servers (Vite + Hono with hot reload) |\n| `bun run typecheck` | `tsc --noEmit` (also run by the pre-commit hook) |\n| `bun run test` | Unit tests (`bun test`) |\n| `bun run build` | Production build (Vite to `dist/client/`) |\n| `bun run start` | Start the production server |\n| `bun run db:generate` | Generate a Drizzle migration from schema changes |\n| `bun run db:migrate` | Apply pending migrations |\n\n### Project structure\n\n```\nsrc/\n  server/    # Bun + Hono backend (routes, services, llm/, tools, db, auth, sse)\n  client/    # React + Vite frontend (pages, components, hooks, locales, styles)\n  shared/    # Types and constants shared by client and server\ndata/        # Created at runtime: SQLite DB, uploads, workspaces\nsite/        # Marketing site (Astro)\ndocs-site/   # Documentation (Astro + Starlight)\n```\n\n### Design system\n\nThe UI follows a custom design system with 18 palettes and full dark/light support. Before building any UI:\n- Consult `src/client/pages/design-system/DesignSystemPage.tsx` (the live showcase, source of truth)\n- Use semantic CSS variables (`var(--color-*)`) or Tailwind tokens, never hardcode colors\n- Reuse components from `src/client/components/ui/`\n\n---\n\n## Community and support\n\n- **Issues** - [report bugs or request features](https://github.com/MarlBurroW/hivekeep/issues)\n- **Discussions** - [questions, ideas, show and tell](https://github.com/MarlBurroW/hivekeep/discussions)\n- **Troubleshooting** - [TROUBLESHOOTING.md](TROUBLESHOOTING.md)\n- **Security** - see [SECURITY.md](SECURITY.md) to report a vulnerability\n\nIf Hivekeep is useful to you, consider [starring the repo](https://github.com/MarlBurroW/hivekeep). It helps others find the project.\n\n## Contributing\n\nContributions are welcome: code, plugins, mini-apps, translations, docs, feedback. Read [CONTRIBUTING.md](CONTRIBUTING.md) and the [code of conduct](CODE_OF_CONDUCT.md) to get started. Before pushing, run `bun run typecheck` and `bun run test` (both are also run by the pre-commit hook). Publish a plugin to npm with the `hivekeep-plugin` keyword to surface it in the marketplace.\n\n---\n\n## License\n\nHivekeep is licensed under the [MIT License](LICENSE). You are free to use, modify, and distribute it, including in commercial and closed-source projects. Your data, your keys, your server, no lock-in.\n\n\u003cp align=\"center\"\u003e\n  \u003csub\u003eBuilt with care and \u003ca href=\"https://bun.sh\"\u003eBun\u003c/a\u003e · \u003ca href=\"https://marlburrow.github.io/hivekeep/\"\u003eWebsite\u003c/a\u003e · \u003ca href=\"https://marlburrow.github.io/hivekeep/docs/\"\u003eDocs\u003c/a\u003e\u003c/sub\u003e\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarlburrow%2Fhivekeep","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarlburrow%2Fhivekeep","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarlburrow%2Fhivekeep/lists"}