# Journal and History Guide

**Version**: 1.0.0-rc.4
**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, viewable but not resumable
- **Session timeline**: an event-by-event view within a single session
- **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
└── …
```

Simplified for the common case — a session can also hold document edits,
PDF operations, and proposal decisions alongside conversations, all
folded into the "Total events" count below.

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

Within a single session, its events are shown as a plain vertical list —
each one a dot and a connector line, with a type label and timestamp.
There is **no calendar or heatmap view across days or months**: no
hover-for-detail, no click-to-filter-by-day, no week/month/year zoom.
Browsing across sessions means picking a different session from the
session list, not navigating a timeline.

---

## Viewing a past conversation

You can open and read any past exchange from the Journal panel, but
**there is no "resume" feature** — no action reloads a past conversation's
context into an active chat session. Confirmed: `ChatHistoryView.tsx` is a
pure read-only renderer with no click handler or state mutation. It's a
record to consult, not a conversation you can pick back up.

---

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

> **Fixed in RC4.** Until then, both journals could record an event against
> the **wrong project** after a project switch: every write site re-fetched
> the *current* history manager rather than the one for the project the
> event belonged to, so an entry arriving after a switch landed in the new
> project's `brain.db` and `journal.db`. The context is now captured when
> the event is created, not when it is written.

### Approximate size

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

---

## Managing the history

**Since RC4 the research journal can be purged.** The action asks twice:
the first confirmation lists exactly what disappears (sessions, events, AI
operations, chat history), the second reminds you that it is irreversible
and that un-exported reports go with it. It reports how many sessions were
removed.

Deleting a *single* session is still not possible.

Do not confuse this with Settings → Actions → **"Purge database"**, which
despite the name wipes your **PDF vector index** — all embeddings, chunks,
HNSW and BM25 indexes — and would force you to reindex every PDF. That one
does not touch `journal.db` or your conversation history.

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