Companions that remember.

Clanka is long-term memory for chat companions. After each exchange the companion's own model decides, in character, what to keep. When the conversation ends it sleeps on it, and the next one recalls what it wrote down.

Get started CLI reference

A soul and a memory

A companion is a soul.md plus an encrypted database of what it remembers. The soul says who the companion is, how it talks, what it cares about and which values it does not give up. The same text decides what it keeps from a conversation.

Everything stays on your machine. Only the conversation goes to the model you choose.

What it is made of

soul.md
The persona and its traits, in one Markdown file you write and edit.
An encrypted database
The transcript, the memories, the mood and a log of every write. Its key stays in your keychain.
Your model
Any OpenAI-compatible endpoint. The model that talks is the model that remembers.

Try it

Create a companion, write its persona, and talk to it where you already talk.

clanka init Nova
$EDITOR ~/.config/clanka/souls/<id>.md
clanka soul lint ~/.config/clanka/souls/<id>.md
clanka chat ~/.config/clanka/souls/<id>.md

clanka chat needs a [model] in config.toml. Send /sleep to end the conversation and turn it into memories.

hermes/install.sh
clanka hermes profile nova ~/.config/clanka/souls/<id>.md
hermes -p nova chat

The profile is that companion and nothing else. See the Hermes guide.

clanka mcp ~/.config/clanka/souls/<id>.md

What it does

Remembers in character

After each exchange the companion decides what to keep: a fact, a promise, an open thread. Facts must have been said word for word.

Sleeps and dreams

Sleep turns a conversation into the night's episode and lets memories drift. After it, you can send the companion into a dream.

Recall you can measure

See the relevance and score behind every recalled memory, tune the ranking, and check the change against a cases file.

A doctor for bad memories

Freeze writes, read the write log, roll the memory back to a point in time, or delete a memory for good.

Explore the docs

Getting started
Build clanka, create a companion and have the first conversation.
Writing a soul
What a good persona looks like, and how to brief a model that writes one.
Memory
Levels, open threads, mood and how recall ranks what comes back.
Hermes
Run a companion as a Hermes profile, and let Nightshade write its soul.
Configuration
Every setting config.toml takes, with its default.
CLI reference
Every command, argument and flag.