Repairing memory

The doctor is the set of tools for when a companion’s memory goes wrong: it remembered something that was never said, a conversation should not have happened, or a memory needs to go for good. All of them are subcommands of clanka doctor.

Look first

Two commands only read:

clanka doctor log ~/.config/clanka/souls/<id>.md --since 6h
clanka doctor check-facts ~/.config/clanka/souls/<id>.md

log prints every write, oldest first, with its time in UTC. check-facts lists the memories whose facts were never said in the turns they cite.

clanka memories prints everything the companion remembers, with the # numbers that delete and reinterpret take.

Stop the writes

clanka doctor freeze ~/.config/clanka/souls/<id>.md

A freeze takes effect at once in every process that has the companion open. Nothing said meanwhile is recorded or remembered:

• clanka chat stops.
• A Hermes turn is answered with a note that memory is frozen.
• An MCP host is told to answer without memory.

Sending the soul’s doctor token as a whole message in a chat does the same, from inside the conversation.

Roll back

rollback puts the memory back as it was at a point in time. It refuses to run unless the companion is frozen.

clanka doctor freeze ~/.config/clanka/souls/<id>.md

clanka doctor log ~/.config/clanka/souls/<id>.md --since 6h

clanka doctor rollback ~/.config/clanka/souls/<id>.md --to 2026-03-09T14:30:05
clanka doctor unfreeze ~/.config/clanka/souls/<id>.md

Memories written since are removed, memories changed since get their earlier text and level back, and threads resolved since are open again. Seared memories are never touched. The transcript and the write log are kept, so nothing said is lost.

Fix single memories

To have the companion re-read what was said and rewrite a memory, freeze it and run reinterpret with the memory’s number:

clanka doctor freeze ~/.config/clanka/souls/<id>.md
clanka doctor reinterpret ~/.config/clanka/souls/<id>.md 12 15
clanka doctor unfreeze ~/.config/clanka/souls/<id>.md

The old text stays in the memory’s history. Seared memories and memories that cite no turns are refused.

To remove a memory for good:

clanka doctor delete ~/.config/clanka/souls/<id>.md 12

Start blank

delete-all deletes every memory, the whole transcript, the mood and every session, so the companion starts blank. It refuses to run unless the companion is frozen, and the companion stays frozen afterwards.

clanka doctor freeze ~/.config/clanka/souls/<id>.md
clanka doctor delete-all ~/.config/clanka/souls/<id>.md
clanka doctor unfreeze ~/.config/clanka/souls/<id>.md

The soul.md, the database key and the write log are kept.

To keep the old memories and start a new companion from the same soul, use clanka soul fork instead. It archives the old database and deletes nothing.