From 6ababd919d01f8238e227cc75057ae48f01f0cf6 Mon Sep 17 00:00:00 2001
From: Alex Clarke <alex.j.tusa@gmail.com>
Date: Fri, 7 Nov 2025 13:44:32 -0700
Subject: [PATCH] docs: documentation on how sessions work in Loki

---
 docs/SESSIONS.md | 44 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 44 insertions(+)
 create mode 100644 docs/SESSIONS.md

diff --git a/docs/SESSIONS.md b/docs/SESSIONS.md
new file mode 100644
index 0000000..7f683ec
--- /dev/null
+++ b/docs/SESSIONS.md
@@ -0,0 +1,44 @@
+# Sessions
+By default, Loki does not send back all previous messages in a conversation to the model. This means that each time you 
+query a model, it's essentially a one-off. However, Loki does support chat-like conversations with LLMs via its 
+`sessions` mechanism.
+
+Sessions in Loki enable the familiar conversational interactions with LLMs. This means you can reference previous 
+answers and ask follow-up questions and the model will know what you're referring to.
+
+Sessions can be temporary, or can be saved so you can continue conversations at a later time.
+
+Saved sessions are stored in the `sessions` subdirectory of the Loki configuration directory. The location of the 
+`sessions` directory varies by system, so you can use the following command to find the `sessions` directory if you need 
+it:
+
+```shell
+loki --info | grep 'sessions_dir' | awk '{print $2}'
+```
+
+## Usage
+When you use a session in Loki, you can either persist it or discard it once you're done. Sessions you discard are then
+just considered 'temporary' sessions.
+
+![Persistent Session Example](./images/sessions/sessions-example.gif)
+
+Sessions you persist and then load again later will inherit the same configuration as was used during the last usage of 
+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.
+
+## 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:
+
+```shell
+loki --info | grep 'config_file' | awk '{print $2}'
+```
+
+The following settings are available to customize the default behavior of sessions globally:
+
+| Setting                  | Description                                                                                                                                                                                                                                                                                                                                                            |
+|--------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `save_session`           | Controls the persistence of the session. <br><ul><li>If `true`, then any time you're in a session, changes will auto-save unless explicitly defined otherwise.</li> <li>If `false`, then any time you're in a session, changes will not auto-save unless explicitly specified otherwise.</li><li>If `null`, Loki will always prompt the user for what to do.</li></ul> |
+| `compression_threshold`  | Defines the token count threshold at which Loki will compress the session to save on the context length                                                                                                                                                                                                                                                                |
+| `summarization_prompt`   | This is the prompt that is used to compress the session up to a given point when compression is triggered                                                                                                                                                                                                                                                              |
+| `summary_context_prompt` | This is the prompt that's used to add the summarized conversation generated by the `summarization_prompt` as context to the model                                                                                                                                                                                                                                      |