Sessions

Sessions persist your conversation so you can resume later. Each session is identified by a UUID and stored in a SQLite database.

How Sessions Work

• A session is not created when meka starts. It is created lazily when you send the first message.
• When a session is created, its UUID is printed to stderr.
• When you exit meka (Ctrl+D), the session UUID is printed again so you can note it for later.
• Sessions include the full conversation: your inputs, the agent’s responses, and tool call results.

Resuming a Session

Continue Last Session

meka -c

This resumes the most recently updated session.

By UUID

meka -c 550e8400-e29b-41d4-a716-446655440000

The agent loads the previous conversation and continues from where you left off.

By UUID Prefix

If the value isn’t a valid UUID, meka treats it as a leading prefix and looks up sessions whose ID starts with it. This avoids having to copy the entire UUID:

meka -c 550e            # works if exactly one session starts with `550e`
meka -c 5               # likely ambiguous; meka lists matching IDs and exits

When a prefix matches multiple sessions, meka prints the matching IDs (most-recent first) so you can disambiguate. Type a few more characters until the prefix is unique.

Session Locking

Only one meka instance can be attached to a session at a time. This prevents race conditions from concurrent writes.

• If you try to resume a session that is locked by a running meka process, you will get an error.
• If the locking process has exited (crashed or was killed), meka detects this and allows you to take over the lock.

Storage Location

Sessions are stored in a SQLite database at a platform-specific location:

Database Schema

The database has three tables:

sessions – one row per session:

messages – one row per message in a session:

tool_outputs – scratchpad entries, one row per entry:

Scratchpad entries are scoped to a session. Two sessions can have entries with the same name. Entries are preserved across compaction but deleted when a session is deleted.

History Retention

meka automatically manages session storage on startup with sensible defaults:

• retention_days (default: 90) – deletes sessions whose updated_at is older than this many days.
• max_storage_bytes (default: 52428800 / 50 MB) – when total message content exceeds this limit, the oldest sessions are deleted until the total is under the limit.

You can override these defaults in the config file under [session]:

[session]
retention_days = 30          # delete sessions not used in 30 days
max_storage_bytes = 10485760 # cap total storage at ~10 MB

See Config File for details.

Context Window Limiting

Long sessions can exceed the LLM’s context window or become expensive. The context_messages setting (default: 200) limits how many recent messages are sent to the API:

[session]
context_messages = 100

The full history remains in SQLite for resumption. Only the API payload is truncated. The truncation preserves tool call chains (it never splits a tool use from its result).

Compacting a Session

If a session becomes too long, you can use the /compact command to have the LLM summarize the conversation and replace older messages with a structured summary. Recent messages are preserved verbatim. The summary includes key files, decisions, errors, and user preferences.

Compaction preserves scratchpad entries and the todo list, and re-injects environment context so the agent isn’t disoriented after compaction. Tools that the model loaded via load_tool before compaction stay loaded after — the deferred-tool active set is snapshotted into the compaction boundary, so resumed sessions don’t re-issue load_tool for tools they already used.

Internally, compaction does not delete pre-compaction rows from the database. It appends a compact_boundary row to the messages table; the materialized view is reconstructed from the event log, so the persisted log itself stays append-only.

Auto-Compact

When auto_compact is enabled (default: true), meka automatically compacts the conversation when the input token count exceeds 80% of the context window. This runs between turns, not during tool loops.

[session]
auto_compact = true
context_window = 200000  # optional override

Listing Sessions

To see past sessions:

meka list

This shows a table with each session’s ID, last update time, and a preview of the first message:

ID                                    Updated              Preview
550e8400-e29b-41d4-a716-446655440000  2026-03-14 12:00:00  How do I implement a binary search tree?
a1b2c3d4-e5f6-7890-abcd-ef1234567890  2026-03-13 09:30:00  Fix the login page CSS

By default the 20 most recent sessions are shown. Use -n to change:

meka list -n 50

Exporting a Session

You can export any session as a Markdown file:

meka export 550e8400-e29b-41d4-a716-446655440000

This writes session-550e8400-e29b-41d4-a716-446655440000.md in the current directory with the full conversation. User and assistant messages are rendered as Markdown sections, while tool calls and results are wrapped in collapsible <details> blocks.

To write to a specific file:

meka export 550e8400-e29b-41d4-a716-446655440000 -o conversation.md

To print to stdout (for piping):

meka export 550e8400-e29b-41d4-a716-446655440000 -o -

Deleting Sessions

Delete specific sessions by UUID:

meka delete 550e8400-e29b-41d4-a716-446655440000

Delete multiple sessions at once:

meka delete 550e8400-e29b-41d4-a716-446655440000 a1b2c3d4-e5f6-7890-abcd-ef1234567890

Delete all sessions:

meka delete --all

Managing Sessions via SQLite

You can also manage sessions directly through the SQLite database. For example, to list all sessions:

sqlite3 ~/.local/share/meka/sessions.db \
  "SELECT id, created_at, updated_at FROM sessions ORDER BY updated_at DESC;"