Memory and compaction

1. Session history
2. Context window
3. Compaction
4. Long-term notes

Seshat has three kinds of memory, each with its own job.

1. Session history

Every conversation is saved in a local SQLite database: messages, tool results, token usage and metadata. Sessions survive restarts and can be resumed.

seshat chat --continue          # the most recent session
seshat chat --resume <id>       # a specific one
seshat sessions list

2. The context window and compaction

A model can only read so much at once. Seshat tracks how much of the window a session uses. When it passes a threshold, it compacts: older messages are summarised into a shorter form so the session can go on.

When it starts

The window Seshat works with is the model’s window minus a reserve for the summary (2,000 tokens). Two marks matter:

• The threshold: 85% of that window, but never closer than 13,000 tokens to its end. Above it, auto-compaction runs before the next model call.
• The target: about 50% of the window. Compaction aims to land there.

In the Go SDK, turn automatic compaction on with AutoCompact in ClientConfig.

What it does

Compaction is checked before every model call, with two ways of freeing room: first a cheap one that needs no model, then a summary.

1. Threshold. Below it, nothing happens.
2. Micro-compaction. Large tool results are trimmed. If that brings the session under the target, there is no model call at all.
3. Summary. Otherwise the session’s own model writes a summary of the conversation, told to preserve the active requests, the decisions made, the tool outcomes that still matter and the unresolved work.
4. Recent messages are kept. Starting from the newest message, Seshat keeps messages until it reaches the target. The cut is then moved back if needed, so a tool result is never kept without the tool call it answers.
5. Rebuild. The new history is the summary, a marker saying the context was compacted, and the kept messages.

If the summary call fails, that turn ends with an error. By default the summary is written by the model of the session, so compaction works with any provider. In Go, ClientConfig.CompactSummaryModel picks another model for it.

When compaction keeps failing

The runtime counts failed compactions from one turn to the next. After 3 in a row it stops trying to summarise for the rest of the session, instead of paying for a call that keeps failing. The request is still checked against the hard limit of the window: if it does not fit, it fails on your machine with the compact_full error, before it reaches the provider.

What the history looks like afterwards

3. Notes that last

The agent can keep notes across sessions with the memory tools. They form a small knowledge graph of named entities and observations:

Tool	Use
memory_create_entities	Create entities (a person, a project, a decision)
memory_add_observations	Add facts to an entity
memory_search_nodes	Search what is stored
memory_open_nodes	Read specific entities

You can also read and edit memory yourself from the command line:

seshat memory                                          # show user memory
seshat memory --scope project                          # this project's memory
seshat memory --action set --key style --value "short answers, no preamble"
seshat memory --action clear --scope user
seshat memory --action context                         # what would be given to the agent

--scope is user, project or cross (shared across sessions).

Documents and knowledge

Memory is about the conversation and what the agent learns. For large bodies of documents, Seshat has a retrieval layer (chunking, embeddings, hybrid search) in the SDK. It is covered in Retrieval and knowledge.