Repository Structure

Repository Structure

This page explains where the main parts of BonsaiCore live and what each directory is responsible for. If you are trying to find the right place for a change, start here.

---

Top-Level Layout

Path	Purpose
src/mcp_server/	MCP server implementation, tool routing, and orchestration.
src/memory/	Memory logic, scoring, decay, consolidation, and storage adapters.
src/ui/	UI components and the Memory Bonsai visualization.
deploy/	Deployment configs, environment setup, and proof-of-deployment artifacts.
docs/ or wiki	Architecture notes, contributor guidance, and extended project documentation.

---

src/mcp_server/

This is the control plane layer.

It contains the MCP server and the tool definitions that let the agent interact with memory in a structured way. If a change affects how the agent stores, queries, consolidates, or decays memory, this is usually the first place to look.

Typical responsibilities

• Tool registration.
• Request routing.
• Payload validation.
• MCP interface behavior.
• Orchestration between agent and memory logic.

---

src/memory/

This is the core memory layer.

It holds the logic that makes BonsaiCore behave like a persistent system rather than a simple chat application. If a change affects memory relevance, decay, reinforcement, or consolidation, it belongs here.

Typical responsibilities

• Episodic and semantic memory logic.
• Vector and graph/relational storage adapters.
• Scoring and ranking.
• Decay and pruning behavior.
• Consolidation pipelines.

---

src/ui/

This is the presentation layer.

It contains the components that visualize memory growth, pruning, and consolidation. If you are working on the Memory Bonsai interface or any future capability dashboard, this is the right place.

Typical responsibilities

• Visualization components.
• Interaction surfaces.
• Status views and memory activity displays.
• Real-time feedback for demos.

---

deploy/

This folder holds deployment-related material.

It should contain the files that help someone reproduce, verify, or understand the live environment. If you are working on cloud setup, hosting, or evidence for submission, start here.

Typical responsibilities

• Cloud configuration.
• Environment and infrastructure notes.
• Deployment scripts.
• Proof-of-deployment artifacts.
• Operational documentation.

---

Documentation Areas

BonsaiCore uses the wiki for longer-form documentation and architecture notes. That is where the framework-level explanation lives, including the memory model, MCP tool surface, and contribution guidance.

Use the wiki for:

• system concepts,
• architecture explanation,
• contributor onboarding,
• and demo walkthroughs.

Use the repository for:

• code,
• configs,
• scripts,
• and deployable assets.

---

Where To Start

If you are new to the project:

1. Read the wiki pages first.
2. Look at src/mcp_server/ to understand the control plane.
3. Read src/memory/ to understand how memory behaves.
4. Inspect src/ui/ if you want to work on the demo experience.
5. Review deploy/ if you are touching cloud or release setup.

---

Related Pages

• Architecture & Core Concepts
• Memory Model
• MCP Tools
• Building New Capabilities
• Contributing