-
Notifications
You must be signed in to change notification settings - Fork 0
Memory Model
BonsaiCore uses a memo-based memory architecture to keep context structured, useful, and efficient across sessions. Instead of storing everything as a flat history, it separates memory into layers with different lifecycles and responsibilities.
The memory model is designed to behave like a living system.
- Leaves hold short-term context.
- Branches hold episodic memos.
- Roots hold durable semantic memory.
This separation gives BonsaiCore a way to retain important information without letting context become noisy or unbounded.
Leaves are the short-term layer of the system.
- The current conversation turn.
- Immediate system prompts.
- Transient session state.
- Any context that only needs to exist while the session is active.
Leaves live inside the active context window of the model. They are not stored as long-term memory, and they do not need reinforcement or consolidation. Once the session changes, they are replaced naturally by the next active context.
Leaves give the system immediate responsiveness without forcing the longer-term memory layers to do the work of short-term reasoning.
Branches are the episodic memory layer.
- Recent interactions.
- Structured memos.
- Time-sensitive user signals.
- Context that may matter again later, but is not yet stable enough for long-term storage.
Each branch memo can include:
timestamptags[]reinforcement_countdecay_score
These fields let BonsaiCore track recency, importance, and repeated use.
Branches are the main working memory for retrieval. When the agent needs relevant history, it queries this layer first because it preserves enough detail to be useful while still remaining manageable.
Branches can:
- gain reinforcement when they are retrieved again,
- decay when they stop being relevant,
- and be promoted into Roots when their signal becomes stable.
Branches are where memory stays flexible. They let BonsaiCore remember recent experiences without promoting every temporary detail into permanent knowledge.
Roots are the semantic memory layer.
- Long-term user preferences.
- Stable facts.
- Repeated constraints.
- Consolidated insights that should survive across many sessions.
Roots are built from repeated or reinforced Branches. When the same signal appears often enough, the system can distill it into a simpler, more durable semantic record.
This is where short-lived experience becomes long-lived knowledge.
Roots are what make BonsaiCore feel persistent. They let the system carry stable understanding forward without depending on raw conversation replay.
Reinforcement is the signal that tells the system a memo is still useful.
Each time a Branch is retrieved or reused, its reinforcement_count can increase. That makes the memory more likely to stay active and more likely to be consolidated later.
Reinforcement helps BonsaiCore distinguish between:
- a one-off detail,
- and a pattern that deserves to survive.
Decay prevents memory from becoming bloated.
A Branch’s decay_score changes over time based on:
- how long it has been since the memo was created or retrieved,
- how much reinforcement it has received.
If the score falls too low, the memory no longer stays in active use. It can be archived or deleted depending on the policy in effect.
This keeps the system lean and ensures stale context does not accumulate forever.
Consolidation is the process of turning repeated episodic memory into durable semantic memory.
A Branch becomes a candidate for consolidation when:
- it appears repeatedly across sessions,
- it receives high reinforcement,
- or it represents a stable fact or preference.
The control plane can trigger a synthesis step that:
- strips away conversational noise,
- keeps the stable meaning,
- and writes the distilled result into Roots.
Consolidation is what lets BonsaiCore improve over time instead of merely accumulating data.
Pruning is the explicit removal of memory that no longer deserves to stay active.
Pruning can:
- archive stale memos,
- delete low-value entries,
- and keep storage from becoming a junk drawer.
This is one of BonsaiCore’s key design choices. Memory is not just stored; it is actively managed.
Leaf activity
│
▼
Branch storage
│
┌───┴──────────────┐
▼ ▼
Reinforcement Decay threshold
▼ ▼
Consolidation Pruning
▼ ▼
Roots Archive / deletion
The lifecycle is intentionally cyclical. Information can begin in Leaves, move into Branches, and eventually become Roots if it proves durable enough.
When working with the memory model, keep these rules in mind:
- Do not treat every interaction as permanent.
- Use reinforcement to identify useful patterns.
- Let decay remove stale context.
- Consolidate only when the signal is stable.
- Preserve the distinction between episodic and semantic memory.
These rules keep the system efficient and maintain the integrity of the architecture.