diff --git a/docs/docs/specs/messages.md b/docs/docs/specs/messages.md
index d233916af..83a8fa063 100644
--- a/docs/docs/specs/messages.md
+++ b/docs/docs/specs/messages.md
@@ -10,23 +10,65 @@ This is currently under development.
 
 ## Overview
 
-`Messages` are in `threads` and capture additional metadata.
+`Messages` capture a conversation's content. This can include the content from LLM responses and other metadata from [chat completions](/specs/chats).
 
 - Users and assistants can send multimedia messages.
 - An [OpenAI Message API](https://platform.openai.com/docs/api-reference/messages) compatible endpoint at `localhost:3000/v1/messages`.
 
 ## Folder Structure
 
-- `Message` objects are stored in `thread.json` files under the `messages` property. See [threads](./threads.md).
+Messages are saved in the `/threads/{thread_id}` folder in `messages.jsonl` files
 
-## `message` object
+```sh
+jan/
+    threads/
+        assistant_name_unix_timestamp/
+            ...
+            messages.jsonl
+        jan_2341243134/
+            ...
+            messages.jsonl
+```
 
-### Example
+## `message.jsonl`
 
-Here's a standard example `message` json.
+Individual messages are saved in `jsonl` format for indexing purposes.
 
 ```json
-"id": "0",                            // Sequential or UUID?
+{...message_2}
+{...message_1}
+{...message_0}
+```
+
+### Examples
+
+Here's a standard example `message` sent from a user.
+
+```json
+"id": "0",                            // Sequential or UUID
+"object": "thread.message",           // Defaults to "thread.message"
+"created_at": 1698983503,
+"thread_id": "thread_asdf",           // Defaults to parent thread
+"assistant_id": "jan",                // Defaults to parent thread
+"role": "user",                  // From either "user" or "assistant"
+"content": [
+  {
+    "type": "text",
+    "text": {
+      "value": "Hi!?",
+      "annotations": []
+    }
+  }
+],
+"metadata": {},                       // Defaults to {}
+// "run_id": "...",                   // Rather than `run` id abstraction
+// "file_ids": [],
+```
+
+Here's an example `message` response from an assistant.
+
+```json
+"id": "0",                            // Sequential or UUID
 "object": "thread.message",           // Defaults to "thread.message"
 "created_at": 1698983503,
 "thread_id": "thread_asdf",           // Defaults to parent thread
@@ -42,14 +84,13 @@ Here's a standard example `message` json.
   }
 ],
 "metadata": {},                       // Defaults to {}
-"chat_completion_id": "",             // For now, we use `chat` completion id
-// "run_id": "...",                   // Rather than `run` id
-// "file_ids": [],
+// "run_id": "...",                   // KIV
+// "file_ids": [],                    // KIV
 ```
 
 ## API Reference
 
-Jan's Threads API is compatible with [OpenAI's Messages API](https://platform.openai.com/docs/api-reference/messages), with additional methods for managing messages locally.
+Jan's `messages` API is compatible with [OpenAI's Messages API](https://platform.openai.com/docs/api-reference/messages), with additional methods for managing messages locally.
 
 See [Jan Messages API](https://jan.ai/api-reference#tag/Messages)
 
diff --git a/docs/docs/specs/threads.md b/docs/docs/specs/threads.md
index eaec86ee8..3290b1574 100644
--- a/docs/docs/specs/threads.md
+++ b/docs/docs/specs/threads.md
@@ -21,12 +21,14 @@ This is currently under development.
 - Threads are saved in the `/threads` folder.
 - Threads are organized by folders, one for each thread, and can be easily zipped, exported, and cleared.
 - Thread folders follow the naming: `assistant_id` + `thread_created_at`.
+- Thread folders also contain `messages.jsonl` files. See [messages](/specs/messages).
 
 ```sh
 jan/
     threads/
         assistant_name_unix_timestamp/
             thread.json
+            messages.jsonl
         jan_2341243134/
             thread.json
 ```
@@ -34,7 +36,7 @@ jan/
 ## `thread.json`
 
 - Each `thread` folder contains a `thread.json` file, which is a representation of a thread.
-- `thread.json` contains metadata, model parameter overrides, and [message](https://jan.ai/specs/messages) history.
+- `thread.json` contains metadata and model parameter overrides.
 - There are no required fields.
 
 ### Example
@@ -43,15 +45,19 @@ Here's a standard example `thread.json` for a conversation between the user and
 
 ```json
 "id": "thread_....",                  // Defaults to foldername
-"object": "thread",                     // Defaults to "thread"
-"summary": "funny physics joke",      // Defaults to ""
-"assistants": ["jan"],                // Defaults to "jan"
+"object": "thread",                   // Defaults to "thread"
+"title": "funny physics joke",        // Defaults to ""
+"assistants": [
+  {
+    "assistant_id": "jan",            // Defaults to "jan"
+    "model": {                        // Defaults to 1 currently active model (can be changed before thread is begun)
+      "settings": {},                 // Defaults to and overrides assistant.json's "settings" (and if none, then model.json "settings")
+      "parameters": {},               // Defaults to and overrides assistant.json's "parameters" (and if none, then model.json "parameters")
+    }
+  },
+],
 "created": 1231231                    // Defaults to file creation time
 "metadata": {},                       // Defaults to {}
-"messages": [],
-"model_id": "...",                    // Defaults to assistant.model ???
-"settings": {},                       // Defaults to and overrides assistant.settings
-"parameters": {},                     // Defaults to and overrides assistant.settings
 ```
 
 ## API Reference