---
title: "Sessions"
description: "How mikan separates platform chat history from the agent harness's structured sessions."
url: "https://geminixiang.github.io/sessions/"
---

# Sessions

`log.jsonl` keeps human-readable platform messages used to bootstrap thread or reply context.
    `sessions/*.jsonl` stores tool results and agent turns so the mikan agent harness can continue
    work.
    Threads, reply chains, and shared channels map to fixed session files so different conversations
    do not contaminate each other.

## Platform session model

| Platform | `sessionKey` rule                                                                 | Notes                                                                  |
| -------- | --------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| Slack    | top-level / DM: `conversationId`; thread: `conversationId:threadTs`               | thread sessions are fixed files bootstrapped from recent chat history  |
| Discord  | DM: `channelId`; shared top-level: `channelId:messageId`; reply/thread: rooted id | replies in shared channels continue the root message session           |
| Telegram | private: `chatId`; shared top-level: `chatId:messageId`; reply chain: root reply  | no native thread model; shared sessions are inferred from reply chains |

## Session identity safety

A session key always belongs to exactly one conversation. Platform adapters may supply a scoped key, but conversation intake and the runtime reject a key whose conversation prefix differs from the incoming conversation. Conversation identities and scoped suffixes also reject path separators, control characters, and the special `.` / `..` segments before they can influence session storage. Thread session files keep their existing names and persistence behavior; the sessions module additionally rejects symlink session targets and proves derived paths remain inside the conversation's `sessions/` directory.

## Files

- workspace/
  - **log.jsonl** platform message history
  - sessions/
    - **current** points to the active top-level session
    - **\*.jsonl** structured harness session context, including tool results
    - **scope-derived files** fixed session files for thread / reply scopes

## Bootstrap, rotation, and reset

A new scoped session is seeded from at most 200 applicable platform messages from the previous 14 days. Top-level sessions rotate on a biweekly boundary. Rotation changes the active structured context file; it does not delete older JSONL files.

  Use `new` / `/new` in chat to reset the current session. Unless you remove them manually, previous
  files stay on disk for inspection.