kronos

<h1 align="center">Kronos</h1>

<p align="center">
  A memory for your AI assistant, kept on your machine.<br>
  Every conversation you've had, kept and searchable. The ones that matter now, brought up on their own.
</p>

<p align="center">
  <img src="docs/calendar.svg" alt="The Kronos calendar: a month of conversations and the ones on the chosen day" width="760">
</p>

---

## Why

AI assistants forget. Every conversation starts from nothing: the trip you
planned last week, the budget you set, the injury you mentioned, the job you
applied for, the problem you already solved. Unless you say it again, it's gone.

That's the difference between a chat box and an assistant. An assistant
remembers what you've told it, notices when something you say connects to
something from before, and doesn't make you repeat yourself.

Kronos gives an assistant that memory. It keeps every conversation you have,
indexes it, and gives each memory a **temperature**. Recent and often-used
memories are hot. When something you say connects to one of them, Kronos quietly
hands the assistant a short note about it before it answers. Old memories cool
down and stop interrupting, but nothing is ever deleted: anything can be found
again by searching, or by opening the calendar to the day it happened.

It runs entirely on your machine. Nothing is uploaded, and it works with any
assistant that can use tools.

## What it's like

You mention your knee is sore after a workout. You told your assistant two weeks
ago that lunges hurt it, and it suggested step-ups instead. Without Kronos, that
conversation is gone. With Kronos, the assistant sees this next to your message:

```
kronos: possibly relevant past conversations (kronos read ID for more)
#2 2026-09-27 health · Knee hurts on lunges, what should I swap Swap lunges for step-ups to a low box…
```

So it answers knowing the history: *"Still the left knee from lunges? Did the
step-ups help?"*

Say *"thanks, that's perfect"* and Kronos adds nothing. Most messages get nothing.
It only speaks up when something actually connects.

And you can ask it directly:

- *"Where did we decide to stay in Lisbon?"*
- *"What was I working on on the 24th?"*
- *"What did we set the grocery budget to?"*
- *"Forget that last message, it had my password in it."*

## What it does

- **Keeps everything.** Every conversation is kept in a private vault on your
  machine, even after the app that created it cleans up its own history.
- **Brings up what matters, unasked.** On every message, Kronos looks for past
  conversations on the same topic. If one clears the bar, the assistant gets up to
  three one-line notes. If nothing does, it gets nothing.
- **Picks up where you left off.** Starting a conversation brings a short note of
  what you were last doing in the same place, if it was recent.
- **Lets memories cool.** Each memory's temperature halves every two weeks unless
  it is used. Hot memories come up on their own, warm ones on a strong match, cold
  ones only when searched for. Nothing is deleted.
- **Has a calendar.** Every conversation, by day. Open any day and see what you
  talked about.
- **Gives the assistant tools** to search, read, browse the calendar and forget,
  through MCP, the standard way assistants use tools.
- **Gives you a window.** A small app with the calendar, search, your memory's
  temperature, and a reader. It takes on your system's theme.
- **Costs almost nothing.** No AI model of its own, no GPU, nothing running in the
  background, no internet. One 4.6 MB program.

## How it works

```
 conversations ──▶ vault ──▶ exchanges ──▶ search index
                                               │
                 your message ──▶ recall ◀─────┤ temperature
                                    │          │
                     three notes or nothing    └──▶ search · read · calendar
```

### The vault

Conversations are kept in `~/.local/share/kronos/vault`, readable only by you.
Kronos uses hard links where it can: a second name for the same file, so nothing
is copied and no extra space is used. When the original app deletes its copy,
the vault's name keeps the conversation alive.

### The index

Each conversation is split into **exchanges**: one message from you and
everything the assistant said back. Each exchange is indexed together with the
conversation's opening request, so a later *"where should we stay?"* still
belongs to the Lisbon trip. Tool output and the assistant's private reasoning are
left out: they are large, noisy, and the likeliest place for secrets.

The index stores what is needed to find text, not the text itself. Results point
to exact lines in the original conversation, which Kronos reads when needed.
90 MB of conversations make a 1 MB index.

### Temperature

Every memory carries a heat and the time it was last set. Its temperature right
now is

```
temperature = heat × 2^(−days since set / 14)
```

worked out whenever it's needed, so nothing has to run in the background. A new
memory starts at 1. Reading it adds 0.4, being brought up adds 0.1, up to 1.

| Tier | Temperature | What happens |
| --- | --- | --- |
| **Hot** | 0.5 and up | Brought up automatically when it connects. |
| **Warm** | 0.15 to 0.5 | Brought up only on a strong connection. |
| **Cold** | below 0.15 | Never brought up on its own. Found by searching. |

Left alone, a memory is hot for two weeks, warm for about five more, then cold.
Using it heats it up again.

<p align="center">
  <img src="docs/memory.svg" alt="The memory view: how many memories are hot, warm and cold, and the hottest ones" width="760">
</p>

### Recall

On each message, Kronos picks out the topic words. Filler like *ok*, *thanks*,
*sounds good*, *uh* and *go ahead* doesn't count, and neither do words so common
they appear in a fifth of everything. It finds hot and warm memories containing
them and scores each on three things, from 0 to 1:

- **relevance**: how well the words match, compared with the other candidates;
- **temperature**: how recent and how used the memory is;
- **coverage**: how many of your topic words the memory contains.

The score is the average. Coverage is also a gate: at least two topic words, and
at least half of them, must appear. Without that, the best of a bad set would
always win. Hot memories need a score of 0.6, warm ones 0.75. At most one memory
per past conversation, three in all, and never from the conversation you're in.

Each note costs about 40 tokens. It takes around 35 milliseconds.

## Use

### Talking to your assistant

There's nothing to do. Talk as usual. Recall and the starting note happen on
their own, and the assistant has these tools when it wants more:

| Tool | What it does |
| --- | --- |
| `search` | Find past conversations by words. Filters: place, from, to. |
| `read` | Read a past exchange, optionally with what came before and after. |
| `calendar` | Recent days; one day's conversations; or a date range. |
| `forget` | Remove a memory from Kronos for good. |
| `doctor` | Check Kronos and repair what it can. The assistant calls it if a tool fails. |

### The app

Open **Kronos** from your app launcher.

| View | Keys |
| --- | --- |
| **1 calendar** | arrows move the day · `[` `]` change month · `t` today · `enter` the day's conversations, `enter` again to read one |
| **2 search** | `/` type · `enter` search · `j` `k` move · `enter` read |
| **3 memory** | how warm everything is, and the hottest memories · `enter` read |
| **reader** | `j` `k` scroll · `space` page · `g` `G` top and end · `esc` back |

`f` forgets the selected memory (after asking). `tab` cycles the views, `q` quits.

The app uses your terminal's colours, so it matches your theme, including every
Omarchy theme, and changes when you change it. The calendar and the memory list
share one heat scale: blue is cold, yellow is warm, red is hot.

<p align="center">
  <img src="docs/search.svg" alt="Search results for 'lisbon'" width="760">
</p>

<p align="center">
  <img src="docs/reader.svg" alt="The reader showing a past conversation" width="760">
</p>

### Your choices

`kronos setup` asks, and remembers the answers:

- **Which assistants to connect.** It lists the ones installed on your computer.
- **Where to keep your memory.** Any folder. Change it later and Kronos moves
  everything there.
- **Whether to add Kronos to your app launcher.**

The rest are settings you can change at any time:

```
kronos config                 show your settings and where they are kept
kronos config recall off      stop bringing memories up on its own
kronos config brief off       no note at the start of a conversation
kronos config notes 2         at most two memories per message
```

### It repairs itself

Updates happen: the program moves, an app rewrites its settings, a file gets
damaged. Kronos checks for this and puts things back on its own:

- At the start of every conversation, it reconnects any assistant you chose that
  has lost its connection.
- If its index is ever damaged, it sets it aside and rebuilds it from the vault
  the next time it opens. Your conversations are never lost; only how warm each
  memory was.
- Your assistant has a `doctor` tool and is told to call it when something
  fails. You can run it yourself too:

```
kronos doctor          check everything
kronos doctor --fix    and repair what it can
```

### The command line

Everything in the app is also a command:

```
kronos                         open the app
kronos search WORDS [--limit N] [--project P] [--from DAY] [--to DAY]
kronos read ID [--around N]
kronos calendar [DAY | FROM TO]
kronos recall WORDS            what would be brought up for this message
kronos forget ID
kronos status [--json]         how much is remembered, and how warm
kronos config [KEY VALUE]      show or change settings
kronos doctor [--fix]          check, and repair
kronos sync                    take in new conversations now
kronos setup                   choose assistants, memory