Kronos

Kronos

A memory for your AI assistant, kept on your machine.
Every conversation you've had, kept and searchable. The ones that matter now, brought up on their own.

[The Kronos calendar: a month of conversations and the ones on the chosen day]

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.

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

[The memory view: how many memories are hot, warm and cold, and the hottest ones]

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:

The app

Open Kronos from your app launcher.

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.

[Search results for 'lisbon']

[The reader showing a past conversation]

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 keptkronos config recall off      stop bringing memories up on its ownkronos config brief off       no note at the start of a conversationkronos 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 everythingkronos doctor --fix    and repair what it can

The command line

Everything in the app is also a command:

kronos                         open the appkronos 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 messagekronos forget IDkronos status [--json]         how much is remembered, and how warmkronos config [KEY VALUE]      show or change settingskronos doctor [--fix]          check, and repairkronos sync                    take in new conversations nowkronos setup                   choose assistants, memory folder, launcherkronos setup --remove          disconnect everythingkronos mcp                     the tool server, for assistantskronos hook prompt|start       run by Claude Code's hooks, not by hand

Days are YYYY-MM-DD, in local time.

Where it works

Kronos isn't tied to any one model or company. The memory, the search and the calendar are plain tools that any assistant can call, local models included. To add Kronos to an assistant that isn't listed, give it this MCP server:

{ "command": "kronos", "args": ["mcp"] }

Two pieces depend on the assistant: reading its conversation files, and hooking into each message so recall can happen on its own. Today Kronos does both for Claude Code, which also runs the Code tab of the Claude desktop app. Each other assistant is one reader and, where it allows, one hook.

It runs on Linux, macOS and Windows.

Install

Pick one. Each ends with kronos setup, which asks what to connect.

Ask your assistant. Give it skills/kronos/SKILL.md, the step-by-step guide for installing, connecting, repairing and updating Kronos on any system. In Claude Code you can add it as a plugin:

/plugin marketplace add dawestheperson/kronos/plugin install kronos@kronos

Download it. Get the file for your system from the latest release, check it against SHA256SUMS, put kronos somewhere on your PATH, and run kronos setup. Claude desktop users can also open kronos.mcpb from the release to add the tools with one click.

Build it. With Rust installed, on any system:

cargo install --git https://github.com/dawestheperson/kronoskronos setup

Restart the Claude desktop app afterwards. Before changing any file for the first time, setup saves a backup next to it (*.kronos-backup), and it only ever adds or removes its own entries.

Update

Install the new version the same way, then run kronos doctor --fix. Memory and settings carry over.

Remove

kronos setup --remove

Then delete the program. Your memory stays in its folder in case you come back; delete that too to remove everything. The original conversations are never touched.

Privacy and security

• Nothing leaves your machine. Kronos never connects to the internet.
• Only you can read it. Its folder is created readable by your user alone. See PRIVACY.md.
• Secrets are hidden before anything is indexed and again before anything is shown: private keys, API keys and tokens in their known formats, values written as password=… or token: …, and a message that is nothing but a password-like word. A password inside a normal sentence can't be told apart from other words; if you typed one, ask the assistant to forget that message.
• Forget is permanent for Kronos: the memory leaves the index and is never taken in again. The original conversation belongs to the app that wrote it and is not edited.
• Encryption at rest is left to full-disk encryption, which Omarchy sets up when it is installed. A key stored on the same unlocked computer would not stop anything running as you; it would only add complexity.
• Small enough to read. About 3,000 lines of Rust and four building blocks: rusqlite, serde_json, regex, ratatui.

Numbers

Measured on a real history of 34 conversations and 90 MB:

Design

Every decision, and the reason for it, is in DECISIONS.md.

License

MIT