Skip to content

1.9 Journal and History

Jump to bottom
Frédéric Clavert edited this page Jul 23, 2026 · 11 revisions

Journal and History Guide

Version: 1.0.0-rc.3 Last updated: 2026-07-20

Overview

ClioDeck keeps a full record of your work with the AI assistant, so you can find your way back to past enquiries and follow your own progress.

What is recorded

  • Research journal: your work sessions
  • Conversation history: past exchanges with the assistant
  • Session timeline: a chronological view
  • Context recovery: pick up an earlier conversation
  • AI proposals (RC3): every accept, reject or edit is recorded, along with the chapter it happened in

Two journals, two purposes

ClioDeck keeps two journals, deliberately separated:

Journal Contents What it is for
Research journal (brain.db) Full exchanges: questions, answers, sources, proposal texts Finding and citing your own method
AI usage journal (journal.db) Facts without content: which model, when, how many tokens, which decisions Accounting for your use of AI — without ever exposing your text

The usage journal contains no prompt, no excerpt and no file path. That is a design guarantee, not a setting. Open it with Ctrl/Cmd+J.

Research journal

Opening it

  1. Open your project
  2. Click the Journal icon in the sidebar (book icon)

Structure

The journal is organised by work sessions:

Session (2026-07-20 14:30)
├── Conversation 1
│   ├── Your question
│   └── Assistant's answer (with sources)
├── Conversation 2
└── …

What is shown

Item Description
Date and time When the session took place
Duration Time spent in the session
Total events A generic event count — AI operations, document edits, proposal decisions, and PDF operations all increment it, not just question/answer exchanges

Filtering

  • Empty sessions: hide sessions without activity

That's the only filter currently wired up — there is no date-range filter, and a keyword search field exists in the store but isn't connected to any component yet.

Conversation history

This isn't a separate feature from the research journal above — it's the same data, viewed at the level of individual exchanges rather than sessions. There is no separate "History" icon in the chat panel; browse exchanges from inside the Journal panel itself.

Navigating

  • Conversation list: newest first
  • Preview: the opening words of each exchange
  • Selection: click to see the detail

What each exchange keeps

Item Description
Question Your original message
Answer The assistant's reply
Sources Documents used for retrieval
Timestamp Exact date and time

Session timeline

A chronological view of your research activity.

Jul 2026
│
├── 20 ████████ (8 sessions)
├── 19 ████ (4 sessions)
├── 18 ██ (2 sessions)
│
Jun 2026
│
├── 30 █ (1 session)
└── …
  • Hover: see the detail of a day
  • Click: filter that day's sessions
  • Zoom: week, month, year

Resuming a conversation

  1. Open the history
  2. Select a past conversation
  3. The context is reloaded

Limits

  • The retrieval context may differ if your index has changed since
  • Answers are not recomputed
  • The sources shown are the ones used at the time

Where the data lives

Everything is stored inside the project folder:

{project}/.cliodeck/
├── brain.db      # research journal, history and vector stores
└── journal.db    # AI usage journal (separate by design)

Both are SQLite databases. The two files are separate on purpose: the usage journal must be shareable — for a report, a funder, an ethics statement — without carrying any of your text with it.

Approximate size

Volume Space
100 conversations ~1 MB
1 000 conversations ~10 MB
10 000 conversations ~100 MB

Managing the history

There is currently no way to delete a single session, or to purge journal history specifically. Settings → Actions does have a "Purge database" button, but — despite the name — it wipes your PDF vector index (all embeddings, text chunks, HNSW and BM25 indexes; you'd need to reindex every PDF afterwards). It does not touch journal.db or your conversation history at all. If you're looking to prune old sessions, there isn't a built-in action for that yet — see issue #16.

Export

The AI usage journal can be exported (Markdown, JSONL, CSV) with the cliodeck-journal export --format md|jsonl|csv command. Ctrl/Cmd+J opens the usage journal window for viewing, but that window has no export button today — exporting is CLI-only.

Good practice

  • Thematic sessions: group your enquiries by subject
  • Revisit: the history is where forgotten leads come back

Troubleshooting

The history does not appear

  • The database may be missing or corrupted — check .cliodeck/brain.db
  • Or no session has been recorded yet: start a conversation

Conversations seem lost

  • Conversations are saved automatically; an abrupt shutdown may lose the last exchange
  • Check the application logs

Degraded performance

  • A very large history can slow the journal panel down — there is no built-in way to trim it yet (see the note in Managing the history above)

Access

  • The Journal icon (book) in the sidebar — both sessions and individual exchanges live here, there's no separate history view
  • Ctrl/Cmd+J for the AI usage journal

Clone this wiki locally