Conversations

NimbleBrain automatically persists every conversation. Each conversation is stored as a JSONL file, and you can resume, fork, rename, delete, and search conversations through the CLI, API, or web UI.

Storage format

Conversations are stored as append-only JSONL (JSON Lines) files. In workspace mode, files live under the workspace directory:

~/.nimblebrain/workspaces/ws_engineering/conversations/conv_a1b2c3d4e5f67890.jsonl

The file format uses event sourcing:

Line 1 — immutable conversation metadata (created once, never rewritten)
Lines 2+ — append-only conversation events

Metadata (line 1)

{
  "id": "conv_a1b2c3d4e5f67890",
  "createdAt": "2026-03-25T10:30:00.000Z",
  "format": "events",
  "workspaceId": "ws_engineering",
  "ownerId": "user_abc123",
  "visibility": "private",
  "participants": ["user_abc123"]
}

Token totals, cost, and last model are not stored in line 1 — they are derived at read time by scanning llm.response events in the file.

Events (lines 2+)

Events are appended chronologically. Key event types:

Event	Description
`user.message`	A user sent a message (includes `userId` for multi-participant conversations)
`run.start`	Agent engine started processing
`llm.response`	LLM returned a response (contains token counts, model, content)
`tool.start`	A tool call began
`tool.done`	A tool call completed (contains result, latency)
`run.done`	Agent engine finished processing
`run.error`	Agent engine encountered an error

Example user message event:

{
  "ts": "2026-03-25T10:30:00.000Z",
  "type": "user.message",
  "content": [{"type": "text", "text": "Summarize my meetings from this week"}],
  "userId": "user_abc123"
}

Shared conversations

Conversations can be shared with other workspace members for multi-participant chat. When a conversation is shared, all participants can send messages and see each other’s messages and assistant responses in real time.

The agent can share a conversation and manage participants through the manage_conversation tool:

Share — changes visibility from private to shared
Add participant — adds a workspace member to the conversation
Remove participant — removes a participant (cannot remove the owner)
Unshare — reverts to private, removing all participants except the owner

Only the conversation owner or a workspace admin can manage sharing.

Access control

Role	Private conversations	Shared conversations
Owner	Full access	Full access
Workspace admin	Can view all	Can view all
Participant	No access	Can view and send messages
Other members	No access	No access

Multi-participant chat UI

When multiple participants are in a conversation, the chat UI shows who sent each message:

Your messages appear as normal (right-aligned, italic, no label)
Other participants’ messages get a colored dot and display name above the message, shown only when the speaker changes — keeping the interface clean
Each participant gets a unique accent color on their message border

Real-time streaming

When you’re viewing a shared conversation and another participant sends a message, you see the assistant’s response stream in real time — the same way you’d see your own messages stream. If your connection drops, the conversation reloads automatically on reconnect to catch anything you missed.

Participants who are removed from a conversation or whose conversation is unshared have their streaming connection closed immediately.

nb --resume conv_a1b2c3d4e5f67890

This loads the conversation history and continues from where you left off.

Listing conversations

The sidebar in the web UI shows recent conversations with titles and timestamps. Click any conversation to load it.

Conversations can also be listed and managed programmatically through the nb__status system tool with scope: "overview".

Auto-titling

NimbleBrain generates conversation titles automatically after the first assistant response. The title is stored in the metadata line of the JSONL file and displayed in the web UI sidebar and conversation list.

Storage configuration

By default, the CLI uses JSONL storage in ~/.nimblebrain/conversations/. You can change the storage backend in nimblebrain.json:

{
  "store": {
    "type": "jsonl",
    "dir": "/custom/path/to/conversations"
  }
}

For in-memory storage (no persistence):

{
  "store": {
    "type": "memory"
  }
}

What’s next

Chat — how conversations are created during chat
Multi-Agent Delegation — child agents run in their own conversations
Events API — real-time event streaming (workspace and per-conversation)