Structured project memory for serious AI-assisted software development.
Current release: v1.3.0
Bonsai is a repo-local memory system and workflow for using AI to design, build, and evolve software over many sessions without losing the thread.
It helps you:
- keep context small, structured, and high-signal
- start fresh AI sessions frequently without starting over
- keep the human in the loop through explicit approval and execution gates
- rebuild a project cleanly from its final intended form after early pivots and experimentation
- move cleanly from Web AI design to IDE / CLI implementation
- guide coding agents through large codebases using layered code maps
- preview risky execution with optional compact dry runs
- right-size AI effort instead of burning maximum reasoning on every step
- layer deep product requirements, subsystem architecture, detailed phase plans, and stage-specific implementation skills without bloating always-loaded context
- preserve and actively reconcile product intent, architecture, roadmap, current execution state, and useful out-of-scope observations separately
Bonsai is plain Markdown plus a small set of prompts.
No server. No database. No framework lock-in.
Just durable, structured memory that travels with the project.
This repository intentionally contains Bonsai under:
.bonsai/
because that is how Bonsai is meant to live inside a real software project.
bonsai-dev/
├── README.md
└── .bonsai/
├── README.md
├── design_session.md
├── implementation_prompt.md
├── developer_context.example.md
├── skills/
│ ├── phase_execution.md
│ ├── dry_run.md
│ ├── handoff.md
│ └── final_truth_update.md
├── maps/
│ └── ...
└── projects/
└── task-tracker/
└── ...
The repo root is the public project landing page.
The .bonsai/ directory is the actual framework you copy into another repository.
This repository also includes:
.bonsai/projects/task-tracker/
The Task Tracker example supports two starting paths:
- Design your own implementation: begin with the supplied Task Tracker design prompt and choose your preferred language and tools during the design session.
- Explore the included reference memory: use the completed Java command-line / Gradle project memory to see the implementation workflow operate against a ready-made Bonsai project.
See the Task Tracker Example README for both paths.
Starting from design is the best introduction when you want to evaluate Bonsai independently of any specific implementation stack. The included Java reference memory is useful when you want to inspect completed project artifacts or exercise the implementation workflow directly.
Copy:
.bonsai/
into the root of the repository where you want to use it.
Each software effort gets its own project memory directory under:
.bonsai/projects/<project>/
Then follow:
.bonsai/README.md
for the project workflow.
Use a Web UI AI to brainstorm the product, architecture, constraints, and tradeoffs.
When the design has matured, paste the full contents of:
.bonsai/design_session.md
into the conversation.
The AI will synthesize the conversation into durable project memory:
requirements.mdarchitecture.mdplan.mdstate.md
and, when warranted:
plan/plan_phase_<N>.mdrequirements/requirements_<AREA>.mdarchitecture/architecture_<SUBSYSTEM>.md
A new Bonsai project usually begins with only the four core project memory documents:
requirements.mdarchitecture.mdplan.mdstate.md
Layered requirements, subsystem architecture files, detailed phase plans, and code maps are added only when the project warrants them.
Open your AI coding tool and begin with:
Read .bonsai/implementation_prompt.md and follow its instructions. Active project: <project>.
The AI will load the relevant Bonsai memory, summarize the current execution state, identify whether the exact next step affects approved final truth, recommend the appropriate AI level, and then stop at a structured startup gate before execution begins.
implementation_prompt.md stays compact by loading specialized skills only when needed:
.bonsai/skills/phase_execution.mdwhen phase planning, execution-mode resolution, or contract gates are active.bonsai/skills/dry_run.mdwhen the human requests an execution preview.bonsai/skills/handoff.mdwhen approved work is being closed or handed off.bonsai/skills/final_truth_update.mdwhen final-truth clarification or revision handling is needed
This is the command you will use over and over. At completion, the agent reconciles the result against approved final truth and any approved dry-run baseline, updates operational project memory, reports the result, and recommends starting a clean session for the recorded next step.
For large or unfamiliar codebases, Bonsai also includes a dedicated mapping workflow.
Code maps help future implementation agents:
- orient quickly
- route to the right subsystem
- avoid repeatedly rediscovering the repository
- preserve non-obvious caller and extension mechanics
See:
.bonsai/maps/README.md
for the full mapping workflow.
AI coding tools are powerful, but serious software work exposes their weak spots quickly.
A single giant chat or coding session slowly becomes:
- expensive
- noisy
- hard to steer
- full of stale decisions and dead branches
- increasingly prone to drift
Bonsai is designed for the opposite approach:
Start clean sessions often. Keep the memory outside the session. Load only what matters.
Without persistent structure, every new session forces the human to restate:
- what the product is
- what architecture has already been chosen
- what work is in progress
- what decisions are settled
- where the relevant code lives
- what should happen next
Bonsai makes that context durable and reusable.
The project remembers itself.
Many AI workflows respond to forgetting by stuffing more text into the model. Bonsai takes a different approach:
- telegraphic, structured memory
- layered documents
- compact session handoff
- selective reading
- progressive drill-down only when needed
The goal is not to maximize context. The goal is to maximize useful context per token.
Early software development involves pivots:
- requirements sharpen
- bad ideas get discarded
- architectures improve
- APIs change shape
- the implementation path wanders
That exploration is healthy. But the final repository should not be forced to preserve every wrong turn.
Bonsai distinguishes between:
- the path you took
- the product you ultimately decided to build
Its durable project memory is intended to describe the final desired system, not merely chronicle the historical implementation journey.
That truth is not only established during design. During implementation, Bonsai classifies proposed or discovered impact on requirements and architecture as:
None: existing final truth already covers the workClarification: intended behavior is unchanged, but final truth should be stated more preciselyRevision: intended behavior, constraints, architecture, or system boundaries change
A revision does not silently slip through as code or planning detail. The affected final-truth documents must be updated and approved before substantive implementation proceeds.
That enables a powerful workflow:
Once the product and architecture have matured, Bonsai can guide an AI to rebuild the system cleanly from scratch as though the final design had been known from the beginning.
A prototype that survived five pivots may work, but still carry the scars. Bonsai gives you a path toward a coherent rebuild, not just endless patching.
Bonsai is not just a folder of AI instructions.
It is a development memory system built around a specific belief:
AI-assisted software work improves dramatically when the project carries its own durable, structured memory.
A single giant project prompt eventually becomes its own problem:
- too much stale detail
- too much history mixed with current truth
- too much irrelevant context loaded into every session
- too little distinction between product intent, architecture, roadmap, and active work
Bonsai uses layered, purpose-specific documents instead.
It does not try to put the whole project into one prompt. It gives the AI a structured way to load the right memory at the right time.
Repository instructions are useful. Bonsai is built for a different job.
A typical agent instruction file tells an AI:
- how to behave
- how to build or test
- which conventions to follow
Bonsai preserves:
- what the product is
- what architecture is intended
- what decisions have been made
- what phase of work is active
- what exactly should happen next
- what useful out-of-scope observations should be preserved without becoming active work
- how to find deeper codebase understanding when needed
Agent instructions shape behavior. Bonsai preserves project memory.
They are complementary, not interchangeable.
Agent orchestration can be valuable. Multiple agents can divide work, explore alternatives, or operate in parallel.
But adding agents does not automatically solve:
- weak project memory
- bloated or stale context
- architectural drift
- repeated rediscovery of the codebase
- lossy handoffs between design and implementation
Throwing more agents at a poorly remembered project is still throwing more bodies at the wrong problem.
Bonsai addresses a more fundamental layer: the quality and continuity of the memory each agent receives.
It is independent of orchestration.
- Use Bonsai with one AI assistant.
- Use Bonsai with a coding agent.
- Use Bonsai inside a larger multi-agent workflow.
The principle is the same:
Better agents help. Better project memory helps every agent.
Many AI workflows are good at helping you move forward from wherever you currently are.
Bonsai is also designed to preserve the final product shape that emerges after experimentation, reconsideration, and change.
Design pivots are expected. When a major product, architecture, or roadmap decision changes, bring the current Bonsai memory documents back into a Web AI design session, revise the affected files, approve them, and then restart implementation from the revised memory.
That means Bonsai can support a clean rebuild later:
Not a replay of every development detour, but a fresh implementation of the final system you now know you wanted.
Bonsai stores the important truths of a project in versioned Markdown files inside the repo.
It separates:
- product truth
- architecture truth
- execution roadmap
- active session state
- useful out-of-scope observations
- phase-level execution detail
- stable developer or local context
- shared codebase navigation knowledge
These are different kinds of memory, and mixing them together makes both humans and agents worse at their jobs.
Top-level project memory should stay orienting and authoritative.
But serious projects eventually accumulate detail that deserves preservation without being loaded into every session.
Bonsai supports optional layered documents for product depth, architecture depth, and execution depth:
requirements/requirements_<AREA>.md
architecture/architecture_<SUBSYSTEM>.md
plan/plan_phase_<N>.md
Use these when a product area, architectural subsystem, or active implementation phase has deep, isolated complexity that would otherwise bloat the top-level documents.
The top-level files retain the project-wide truth. The layered files preserve detailed truth that can be loaded only when relevant.
Bonsai is designed around the idea that fresh sessions are good.
Instead of stretching one AI conversation until it becomes a swamp, you:
- execute one bounded, authorized step
- let the agent update
state.mdand report completion - normally end the current session at that handoff
- start a new session
- reload only the meaningful project memory
- continue cleanly
The completion gate still lets you continue in the current session when that is more convenient, but the recommended path is a clean restart. This keeps reasoning sharper and conversations easier to manage.
Bonsai aggressively avoids bloated memory.
Its documents are intended to be:
- structured
- telegraphic
- skimmable
- updated intentionally
- read selectively
The implementation workflow reads the high-level project memory first, then drills into deeper documents only when the current task requires it.
The implementation instructions follow the same rule. The always-loaded prompt preserves startup, authority, final-truth, scope, and maintenance invariants. Stage-specific procedures for phase execution, dry runs, and step completion are loaded only when their trigger applies.
A large project should not require dumping the entire project history or every implementation procedure into every AI session.
Bonsai assumes two different kinds of AI work.
Best for:
- brainstorming
- product shaping
- requirements discovery
- architecture discussion
- tradeoff analysis
- turning a fuzzy idea into a coherent build plan
Best for:
- reading the repository
- editing code
- running tests
- executing a plan
- updating operational project memory
Bonsai connects those modes.
The Web AI helps produce the project memory. The coding AI consumes that memory and executes against it.
Not all Bonsai documents are equal.
Some represent durable decisions the human owns. Others represent operational state the agent maintains.
requirements.mdrequirements/requirements_<AREA>.mdarchitecture.mdarchitecture/architecture_<SUBSYSTEM>.md
These should describe what the product is and how it is intended to work. They are not disposable scratchpads. They are maintained final truth.
The coding agent does not silently modify them to match implementation drift. At implementation gates and completion, it identifies whether work has no final-truth impact, requires a clarification, or requires a revision. The human approves changes to final truth before revised behavior or architecture becomes the project direction.
plan.mdstate.mdicebox.mdplan/plan_phase_<N>.md
These evolve as implementation proceeds.
This split matters. It gives the agent enough authority to manage execution without casually rewriting the project’s underlying intent.
state.md is the current-session handoff document.
It captures:
- current phase
- current pass within the phase
- active detailed phase plan, if any
- current objective
- recent work
- active blockers
- exact next step
- recommended AI effort level
It should stay compact.
A new coding session should be able to read state.md and understand immediately:
“What is happening right now, and what exactly do I do next?”
Implementation sessions often surface useful work that is not part of the exact next step:
- adjacent bugs
- technical debt
- missing tests
- refactor opportunities
- documentation gaps
- follow-up concerns worth revisiting later
Bonsai gives those observations a place to live:
icebox.md
The coding agent can preserve them without expanding scope mid-session.
icebox.md is not an approved backlog and not an execution plan.
It is a triageable parking lot for potentially valuable discoveries.
A human can later promote selected items into requirements, architecture, or planning when they actually become intended work.
plan.md tracks the implementation roadmap:
- the build strategy
- major phases
- active phase
- completed work
- deferred work
- whether a phase uses single-pass or contract-first two-pass execution
For phases that need real execution detail, Bonsai uses:
plan/plan_phase_<N>.md
This keeps the roadmap readable while still allowing complex work to be planned carefully.
Coding agents waste enormous time rediscovering a repository.
Bonsai addresses that with layered code maps.
A top-level code map gives the agent a broad orientation:
- major areas of the codebase
- key architectural domains
- high-value routing guidance
- where to look for a given kind of work
Deeper maps can provide more specific guidance for:
- large architectural subsystems
- framework internals
- package families
- extension seams
- caller-facing mechanics
- implementation patterns worth preserving
The agent starts broad and drills down only when needed.
This keeps startup context lean while still giving the AI a durable understanding of the codebase.
Bonsai’s code maps are not meant to replace reading code. They are meant to help the agent read the right code.
See the Bonsai Maps guide.
For phases that introduce an important API, subsystem boundary, or abstraction, Bonsai supports a Two-Pass Contract-First workflow.
The coding AI drafts:
- the high-level API shape
- behavioral tests that show intended use
- minimal scaffolding needed to make the contract reviewable
Then it stops.
The human reviews:
- Is this the right abstraction?
- Is the API shaped correctly?
- Do the tests express the right behavior?
- Should implementation proceed directly or after a dry run?
The gate makes that transition explicit: approve and proceed, approve and preview implementation with a dry run, request revisions, or return to the phase plan.
When the proposed contract changes final truth, contract approval alone is not enough. The affected requirements or architecture must also be updated and approved before Pass B begins.
The detailed phase and contract-gate skill lives in:
.bonsai/skills/phase_execution.md
and is loaded only when that workflow is active.
Only after approval does the AI build the underlying implementation.
This keeps the human involved at the highest-leverage moment:
Before the wrong abstraction becomes a large amount of working code.
Bonsai does not treat “read the prompt” as permission to start editing immediately.
At the beginning of an implementation session, the coding AI:
- reads the relevant Bonsai memory
- identifies the active project state
- surfaces the exact next step
- classifies its anticipated final-truth impact
- recommends the appropriate AI level
- stops at a structured startup gate
The startup gate is an execution decision: proceed with the identified step, request a dry run first, correct the next step, or stop.
Other gates name what the human is deciding. A phase plan or API contract is approved. A named implementation step is authorized to proceed. If execution would materially change approved scope, contract boundaries, requirements, or architecture, the agent stops and requests a decision instead of quietly broadening the work or silently rewriting final truth.
That precision matters. It lets the human catch stale state, shift direction, or review a high-value boundary before the agent commits to the next block of work.
When a planned step is risky, unclear, or expensive to reverse, Bonsai can preview execution before the agent changes files.
A dry run is intentionally compact. It identifies:
- the approved basis for the work
- expected touch points
- intended result
- planned checks
- likely scope concerns
- anticipated final-truth impact and affected truth documents, when any
When the dry run is approved, the agent can compare actual results and actual final-truth impact against that execution baseline in its completion summary.
The skill lives in:
.bonsai/skills/dry_run.md
and is loaded only when a dry run is requested.
Not every task deserves the most expensive or capable model.
Bonsai’s implementation workflow asks the coding AI to recommend the appropriate AI level for the
exact next step during session startup, and to keep that recommendation current in state.md as
the work changes.
That makes model selection part of the operating discipline:
- use stronger reasoning when architecture, contracts, or ambiguous debugging warrant it
- use lighter or cheaper levels for bounded implementation, maintenance, or straightforward continuation
- avoid burning maximum AI effort merely because a session has started
This is another way Bonsai keeps AI-assisted development focused, economical, and intentional.
Bonsai is intentionally boring technology:
- Markdown files
- plain text prompts
- repo-local structure
- versionable in Git
- usable with many Web AI and coding-agent tools
It does not require you to commit to a proprietary memory backend or a specific editor ecosystem.
If your AI tool can read files and follow instructions, it can probably work with Bonsai.
The included Task Tracker example is a compact project scenario intended to demonstrate Bonsai's design and implementation workflows.
See the Task Tracker Example README for the two available paths: designing your own implementation in your preferred stack or exploring the included Java command-line reference memory package.
Copy:
.bonsai/
into the root of the repository where you want to use it.
Each software effort lives under:
.bonsai/projects/<project>/
For example:
.bonsai/projects/my-product/
Brainstorm the product, requirements, constraints, architecture, tradeoffs, and implementation approach in a Web UI AI conversation.
When the design has matured, paste the full contents of:
.bonsai/design_session.md
into that same conversation.
The AI will synthesize the discussion into Bonsai project memory.
A typical new project begins with:
requirements.md
architecture.md
plan.md
state.md
More detailed layered documents are created only when warranted.
Place the generated files under:
.bonsai/projects/<project>/
For example:
.bonsai/projects/my-product/
├── requirements.md
├── architecture.md
├── plan.md
└── state.md
Copy:
.bonsai/developer_context.example.md
to:
.bonsai/developer_context.md
Use it for stable developer preferences, local SDK paths, build/runtime quirks, and recurring AI session preferences.
Do not use it for product requirements, target architecture, roadmap, or current execution state.
Run:
Read .bonsai/implementation_prompt.md and follow its instructions. Active project: <project>.
The AI will summarize the next step, recommend an AI effort level, and stop at a structured startup gate before execution.
For large, mature, or unfamiliar repositories, build code maps using .bonsai/maps/README.md.
Code maps are optional. Add them when repository rediscovery starts costing real time.
Bonsai is for developers who use AI as a serious engineering collaborator, not just an autocomplete engine.
It is especially useful when:
- a project spans many AI sessions
- you regularly switch between product thinking and implementation
- your codebase is large enough that repository rediscovery is expensive
- you want AI help without surrendering architectural control
- you want to preserve decisions cleanly instead of letting them disappear into old chats
- you expect the product to evolve, pivot, and eventually benefit from a clean rebuild
- you want to manage AI context and AI effort with some discipline instead of treating every task the same
If you have ever thought:
“This AI is useful, but I keep having to teach it the project again,”
Bonsai is meant for that.
Bonsai is an evolving workflow extracted from real AI-assisted software development practice.
It is already useful for:
- shaping a project in Web AI and handing it cleanly to a coding agent
- maintaining durable project memory across many implementation sessions
- keeping agents aligned through structured gates, execution state, and focused next steps
- preserving final truth by surfacing clarifications and blocking unapproved revisions during implementation
- reducing always-loaded implementation instructions through triggered skills
- previewing risky execution with optional compact dry runs
- recommending clean-session continuation after completed work
- mapping large repositories so agents spend less time rediscovering structure
- preserving architectural intent while letting execution state evolve
The system is still being refined. Areas currently evolving include:
- smoother first-time onboarding
- example-driven documentation
- the code mapping workflow
- the balance between layered depth and operational simplicity
- real-project feedback on final-truth reconciliation and triggered implementation skills
- better conventions for preserving useful discoveries without expanding active scope
A bonsai is not wild growth. It is growth shaped deliberately over time.
That is the point of this system.
AI can generate enormous amounts of motion. Bonsai is about turning that motion into deliberate, maintainable software.