Bonsai: branching-conversation toolkit for AI chat apps

Bonsai is an open-source toolkit designed to let developers embed branching-conversation logic into chat-based applications. The problem it solves is structural: conventional AI chat apps force every exchange into a single, linear thread of messages. If a user wants to explore a tangent—say, "what if we tried a different approach?"—they either disrupt the main conversation or start over and lose the context they have already built up. Bonsai removes that false choice by allowing conversations to branch.

The toolkit introduces four core concepts. Tree Model makes every project start as one main branch; from any message, a user can branch off to explore an idea independently without touching the main thread. ContextPacket is a crucial transparency feature: before sending a prompt to the model, developers can inspect the exact set of messages, merged summaries, and wiki pages that will be included in the request—with no hidden retrieval step. This makes the model's input fully auditable. Merge is an explicit, user-reviewed action that lands a branch's summary back onto its parent branch. Distill converts a branch or merge transcript into durable Markdown wiki pages that future conversations can retrieve, building a reusable knowledge base instead of requiring re-explanation. The Wiki itself is a plaintext Markdown knowledge base with frontmatter, designed to be human-readable, greppable, and easily backed up outside Bonsai entirely. Retrieval provides a pluggable search interface over that wiki, with full-text search built in and support for embeddings-based search in later phases.

Bonsai is not a finished chat app but a library for developers. It is aimed at teams building chat-based products—support tools, research assistants, internal copilots—who want branching, mergeable context, and durable memory as foundational features. The toolkit provides the tree/branch/merge/distill logic and swappable adapters for data storage, LLM calls, and knowledge search, so teams do not have to build that infrastructure themselves. Crucially, branching, merging, and distilling are never automatic; all three are explicit, user-approved actions, ensuring that what the model sees is always predictable and transparent.

The codebase is organized into several packages. @bonsai/core is the framework-agnostic domain layer, defining interfaces for Storage, LLMProvider, WikiStore, and Retriever. Adapters include @bonsai/storage-postgres (Postgres storage with full-text-search retrieval), @bonsai/provider-openai (OpenAI-compatible chat and streaming), and @bonsai/wiki-fs (Markdown files on disk). An optional @bonsai/server provides a thin HTTP layer. The project enforces strict architectural boundaries: ESLint rules ban framework-specific imports (React, Next.js, Tailwind, Node filesystem/network modules, and provider SDKs) from core, and dependency-cruiser forbids core from importing adapter code. A boundary-verification test suite in CI ensures these rules hold on every push and pull request. The project is currently in Phase 1 scaffold with no packages published yet. Prerequisites are Node ≥20.11.0 and pnpm 9.15.4. Documentation is built with Astro Starlight and auto-generates API references from TypeScript source via TypeDoc. The codebase is released under the MIT license.

Bonsai addresses a fundamental friction in how people use AI chat applications: the enforced linearity of conversation history. Existing chat tools present a simple model—messages accumulate in order, and exploring a tangent either hijacks the thread or requires starting fresh—which mirrors single-threaded conversation with a human but poorly matches how people actually explore ideas collaboratively. By making branching, merging, and knowledge distillation explicit user actions rather than automatic behind-the-scenes operations, Bonsai gives developers a foundation for chat-based tools (support systems, research assistants, internal copilots) that match the exploratory, nonlinear nature of real problem-solving.

The toolkit is designed with developer ergonomics and transparency in mind. The ContextPacket feature—which lets developers inspect exactly what messages, summaries, and wiki pages will be sent to the model before a reply is generated—directly addresses a key user pain point: "why did the AI say that?" By making that answer concrete and traceable, Bonsai reduces the opacity that often frustrates users of complex AI systems. The codebase itself enforces strict architectural boundaries, banning framework-specific imports and provider dependencies from the core logic, ensuring the toolkit remains adapter-agnostic and portable across different storage backends, LLM providers, and deployment contexts.

At present, Bonsai is in early-stage development (Phase 1 scaffold) with no published packages, so adoption remains ahead. However, the modular architecture—separating core domain logic, storage adapters (Postgres), provider adapters (OpenAI-compatible), and wiki storage (filesystem)—signals an intent to support multiple deployment patterns and lower the barrier for teams building internal or customer-facing AI chat systems.

No comments yet. Be the first to share your thoughts!