> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bumbleagi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Knowledge and journal

> Durable facts and private reflections for your entity.

## 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

```bash theme={null}
bumblebee knowledge canary
```

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

### Structure

```markdown theme={null}
## [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](/architecture/cognition#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:

```yaml theme={null}
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

```bash theme={null}
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.