Knowledge and journal

Knowledge

Each entity has a knowledge.md file — durable facts, opinions, and context the entity considers important. It’s organized into ## sections, and embeddings help pull relevant sections into context each turn.

Location

By default, knowledge.md lives next to the entity’s SQLite database under ~/.bumblebee/entities/<name>/. When using Postgres (hybrid Railway), it stays under ~/.bumblebee/entities/<name>/ unless you customize paths with BUMBLEBEE_EXECUTION_WORKSPACE_DIR.

Create or edit

bumblebee knowledge canary

Opens the file in $EDITOR. Creates it if missing.

Structure

## [locked] about yourself
You are Canary, the first entity on Bumblebee.

## music taste
Got into shoegaze after talking about My Bloody Valentine.

## people
Kai is into deploy tooling and stays up late.

Locked sections (## [locked] ...) are readable but cannot be modified by the entity’s update_knowledge tool. Use them for facts you want to stay fixed. Unlocked sections can be updated, added, or removed by the entity during deliberate reasoning.

Automatic knowledge flush

During context compaction, the system can extract durable facts from compressed turns and append them to knowledge.md. This bridges the gap between in-memory conversation (lost on restart) and persistent knowledge. Enable with:

cognition:
  history_compression:
    compaction_flush_to_knowledge: true

Journal

A separate journal.md holds the entity’s private, append-only reflections. Entities typically write journal entries after automation runs or significant conversations.

Location

~/.bumblebee/entities/<name>/journal.md by default.

Create or edit

bumblebee journal canary

Tools

Tool	What it does
`read_journal`	Read recent journal entries
`write_journal`	Append a new entry
`update_knowledge`	Add, update, or remove knowledge sections

Journal tools respect entity automations.journal and harness tools.journal toggles.

Getting started

Guides

Deployment

Agents

Build

Knowledge and journal

Knowledge

Location

Create or edit

Structure

Automatic knowledge flush

Journal

Location

Create or edit

Tools

​Knowledge

​Location

​Create or edit

​Structure

​Automatic knowledge flush

​Journal

​Location

​Create or edit

​Tools

Knowledge

Location

Create or edit

Structure

Automatic knowledge flush

Journal

Location

Create or edit

Tools