From 830f301889bbcc590cbb17021d12a048f42c08aa Mon Sep 17 00:00:00 2001
From: Alex Clarke <alex.j.tusa@gmail.com>
Date: Fri, 8 May 2026 12:47:16 -0600
Subject: [PATCH] docs: Updated session documentation to mention auto-saved
 sessions

---
 Sessions.md | 71 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 71 insertions(+)

diff --git a/Sessions.md b/Sessions.md
index f6d1376..dfbee01 100644
--- a/Sessions.md
+++ b/Sessions.md
@@ -25,6 +25,77 @@ Sessions you persist and then load again later will inherit the same configurati
 that session. That is to say, if you had certain tools or MCP servers enabled when you were last in that session, they 
 will be available again when you continue that session.
 
+# Auto-Saved Sessions
+
+When `save_session` is set to `true` and you don't provide an explicit session name (i.e., you're in a temporary 
+session), Loki will automatically save your session when you exit. These auto-saved sessions behave differently from 
+manually saved sessions in a few important ways.
+
+## How Auto-Save Works
+
+When you exit a temporary session with `save_session: true`, Loki:
+
+1. Saves the session to a `_/` subdirectory inside the sessions directory (e.g., 
+   `~/.config/loki/sessions/_/`).
+2. Generates a timestamped filename in the format `YYYYMMDDTHHmmSS` (e.g., `20260508T120838`).
+3. If an auto-generated name is available (see [Auto-Naming](#auto-naming) below), it is appended to the timestamp
+   (e.g., `20260508T120838-discuss-rust-error-handling.yaml`).
+
+For agent sessions, auto-saved sessions are stored in the agent's own session directory under `_/` (e.g., 
+`~/.config/loki/agents/<agent-name>/sessions/_/`).
+
+## Auto-Naming
+
+When `save_session: true` is set and you send your first message in a temporary session, Loki will use the LLM to 
+automatically generate a short descriptive name for the session based on the initial exchange. This name is appended to 
+the timestamp in the filename, making it easier to identify sessions later.
+
+You can view the auto-generated name for the current session with `.info session` under the `autoname` field.
+
+## Finding Auto-Saved Sessions
+
+Auto-saved sessions are stored separately from manually named sessions. This means they won't appear in the default 
+session list:
+
+- **`--list-sessions` (CLI)**: Does **not** include auto-saved sessions.
+- **`.session` + <kbd>Tab</kbd> (REPL)**: Does **not** show auto-saved sessions in completions.
+
+To access auto-saved sessions, prefix your query with `_/`:
+
+- **`.session _/` + <kbd>Tab</kbd> (REPL)**: **Will** show auto-saved sessions in completions, since Loki looks in the 
+  `_/` subdirectory when it sees this prefix.
+- **`.session _/<name>` (REPL)**: Loads a specific auto-saved session. For example: 
+  `.session _/20260508T120838-discuss-rust-error-handling`.
+
+When you load an auto-saved session this way, it is treated as a temporary session again, meaning the session name resets to 
+`temp` internally. If auto-naming had previously generated a name, it will be restored so that subsequent saves continue 
+to use it.
+
+## One-Time Save Override
+
+You can force a single session to be saved regardless of the global `save_session` setting by using the `--save-session`
+CLI flag:
+
+```shell
+loki --session --save-session "What is Rust?"
+```
+
+This overrides the configured `save_session` value for that one invocation only, and the session will auto-save to the 
+`_/` subdirectory just like it would with `save_session: true`.
+
+## Save Behavior Summary
+
+The following table summarizes what happens when you exit a session, depending on the `save_session` setting and the 
+session type:
+
+| `save_session` | Session Type       | Mode | Behavior                                                                                 |
+|----------------|--------------------|------|------------------------------------------------------------------------------------------|
+| `true`         | Named session      | Any  | Auto-saves to `<sessions_dir>/<name>.yaml`                                               |
+| `true`         | Temporary (`temp`) | Any  | Auto-saves to `<sessions_dir>/_/<timestamp>[-autoname].yaml`                             |
+| `false`        | Any                | Any  | Never saves                                                                              |
+| `null`         | Any                | REPL | Prompts "Save session?" (if you say yes with a temp session, you'll be asked for a name) |
+| `null`         | Any                | CLI  | Does not save                                                                            |
+
 # Configuration
 Session behavior can be configured from the global Loki configuration file. The location of this file varies between 
 systems so you can use the following command to locate it on your system: