docs: session storage migration #5682

dianed-square · 2025-11-11T18:04:10Z

Summary

This PR documents the session storage migration from .jsonl files to SQLite database.

It also temporarily overwrites doc changes from PR #5516 and changes to lowercase "goose" in touched files.

Documentation updates:

documentation/docs/guides/goose-cli-commands.md:
- Update session IDs and add migration note
- Add missing remove options
documentation/docs/guides/logs.md:
- Update for db migration and add migration note
documentation/docs/guides/multi-model/creating-plans.md:
- Update for new session output with session ID
documentation/docs/guides/recipes/session-recipes.md:
- Temp revert of 5516 changes
documentation/docs/guides/sessions/session-management.md:
- Add "Search Across All Session Content" sections via Chatrecall extension
- Update session IDs and CLI output format

Type of Change

Testing

Manual testing

To see the specific tasks where the Asana app for GitHub is being used, see below:
- https://app.asana.com/0/0/1211895109768763

Copilot

Pull Request Overview

This PR documents the session storage migration from .jsonl files to SQLite database, and makes related documentation updates including session ID format changes and the addition of a new search feature using the Chatrecall extension.

Key changes:

Updates session storage documentation to reflect SQLite database migration (version 1.10.0+)
Changes session ID format documentation from timestamp-based to YYYYMMDD_<COUNT> format
Adds "Search Across All Session Content" sections documenting the Chatrecall extension feature
Updates CLI command examples with new session IDs and removes obsolete flags
Temporarily reverts capitalization to lowercase "goose" throughout touched files

Reviewed Changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
`documentation/docs/troubleshooting/diagnostics-and-reporting.md`	Updates `session diagnostics` command examples to use `--id` flag instead of `--session-id`
`documentation/docs/guides/sessions/session-management.md`	Updates session storage references from `.jsonl` files to SQLite database, changes session ID format, adds Chatrecall extension search documentation, and updates "goose" capitalization
`documentation/docs/guides/recipes/session-recipes.md`	Reverts "Goose" to lowercase "goose" throughout the file
`documentation/docs/guides/multi-model/creating-plans.md`	Updates session output format in examples and changes "Goose" to lowercase "goose"
`documentation/docs/guides/logs.md`	Updates session storage documentation from `.jsonl` files to SQLite database with migration notes
`documentation/docs/guides/goose-cli-commands.md`	Adds session storage migration note, updates session ID examples, removes `--verbose` option from `session list`, and adds new filtering options

documentation/docs/troubleshooting/diagnostics-and-reporting.md

github-actions · 2025-11-11T18:07:08Z

PR Preview Action v1.6.0
Preview removed because the pull request was closed.
2025-11-12 00:18 UTC

alexhancock

looks great, thanks for documenting!

alexhancock · 2025-11-11T19:54:15Z

documentation/docs/guides/goose-cli-commands.md


-## Flag Naming Conventions

-Goose CLI follows consistent patterns for flag naming to make commands intuitive and predictable:


some of these are still relevant right?

@alexhancock correct us if we're wrong, but we believe these changes havent been released yet. our docs shouldnt be ahead of any features, so we're temporarily removing them and will restore once released.

blackgirlbytes · 2025-11-11T20:02:24Z

documentation/docs/guides/goose-cli-commands.md


 # Save diagnostics to a custom location
-goose session diagnostics --session-id 20250305_113223 --output /path/to/my-diagnostics.zip
+goose session diagnostics --session-id 20251108_5 --output /path/to/my-diagnostics.zip


oh i didnt realize this part changes as well. thank you

blackgirlbytes · 2025-11-11T20:03:39Z

documentation/docs/guides/goose-cli-commands.md

 - **`-n, --name <name>`**: Name for this run session (e.g. `daily-tasks`)
 - **`-r, --resume`**: Resume from a previous run
- **`-p, --path <PATH>`**: Path for this run session (e.g. `./playground.jsonl`)
+- **`-p, --path <PATH>`**: Path for this run session (e.g. `./playground.jsonl` for legacy session storage)


wonder if this line could be confusing if you're not familiar with the legacy session storage. is it possible to run path for session for any other situation and do a diff example? or am i misunderstanding

Looks like it's just for that. goose run --help says "Legacy parameter for backward compatibility. Extracts session ID from
the file path (e.g., '/path/to/20250325_200615.jsonl' -> '20250325_200615')."

I separated out the "Used for legacy file-based session storage" to hopefully make it easier to parse. The note in the Session Management section gives a bit more context.

blackgirlbytes

approving with a small comment for improvement

Copilot

Pull Request Overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 7 comments.

Copilot · 2025-11-12T00:11:36Z

documentation/docs/guides/sessions/session-management.md

+    goose will search your session history and show relevant conversations with context from matching sessions. 
+
+    :::info
+    This functionality requires the built-in `Chatrecall` extension to be enabled (it's enabled by default).


The Chat Recall extension is not enabled by default. According to the code in crates/goose/src/agents/extension.rs, the chatrecall extension has default_enabled: false. This documentation should either say "if enabled" or remove the claim about being enabled by default.

Suggested change

This functionality requires the built-in `Chatrecall` extension to be enabled (it's enabled by default).

This functionality requires the built-in `Chatrecall` extension to be enabled (it is not enabled by default).

Copilot · 2025-11-12T00:11:36Z

documentation/docs/guides/sessions/session-management.md

+    goose will search your session history and show relevant conversations with context from matching sessions.
+
+    :::info
+    This functionality requires the built-in `Chatrecall` extension to be enabled (it's enabled by default).


The Chat Recall extension is not enabled by default. According to the code in crates/goose/src/agents/extension.rs, the chatrecall extension has default_enabled: false. This documentation should either say "if enabled" or remove the claim about being enabled by default.

Suggested change

This functionality requires the built-in `Chatrecall` extension to be enabled (it's enabled by default).

This functionality requires the built-in `Chatrecall` extension to be enabled (it is not enabled by default).

Copilot · 2025-11-12T00:11:37Z

documentation/docs/guides/goose-cli-commands.md


 **Options:**
- **`--session-id <session_id>`**: Export a specific session by session ID
+- **`-i, --id <ID>`**: Export a specific session by ID


Incorrect short flag. According to the code in crates/goose-cli/src/cli.rs, the session_id argument has long = "session-id" with alias = "id", but no short form. This should be documented as --id <ID> or --session-id <ID> (without the -i short option).

Suggested change

- **`-i, --id <ID>`**: Export a specific session by ID

- **`--id <ID>`**: Export a specific session by ID

Copilot · 2025-11-12T00:11:37Z

documentation/docs/getting-started/using-extensions.md

 In addition, these platform extensions provide core goose functionality. They are also always available and enabled by default:

+- Chat Recall: Search conversation content across all your session history
 - Extension Manager: Discover, enable, and disable extensions dynamically during sessions
 - [Todo](/docs/mcp/todo-mcp): Manage task lists and track progress across sessions



The Chat Recall extension is listed under platform extensions that are "always available and enabled by default", but according to the code in crates/goose/src/agents/extension.rs, Chat Recall has default_enabled: false. Either move this to a separate section for "available but not enabled by default" extensions, or update the introductory text to clarify that not all listed platform extensions are enabled by default.

Suggested change

In addition, these platform extensions provide core goose functionality. They are also always available and enabled by default:

- Chat Recall: Search conversation content across all your session history

- Extension Manager: Discover, enable, and disable extensions dynamically during sessions

- [Todo](/docs/mcp/todo-mcp): Manage task lists and track progress across sessions

In addition, these platform extensions provide core goose functionality. They are always available, but not all are enabled by default:

**Enabled by default:**

- Extension Manager: Discover, enable, and disable extensions dynamically during sessions

- [Todo](/docs/mcp/todo-mcp): Manage task lists and track progress across sessions

**Available but not enabled by default:**

- Chat Recall: Search conversation content across all your session history

Copilot · 2025-11-12T00:11:37Z

documentation/docs/guides/goose-cli-commands.md

- **`-v, --verbose`**: Include session file paths in the output
 - **`-f, --format <format>`**: Specify output format (`text` or `json`). Default is `text`
 - **`--ascending`**: Sort sessions by date in ascending order (oldest first)
+- **`-p, --working-dir <path>`**: Filter sessions by working directory


Incorrect short flag ordering. According to the code in crates/goose-cli/src/cli.rs, the working_dir parameter has short = 'w' with short_alias = 'p'. The documentation should show the primary short form first: -w, --working-dir <path> (with -p as an alias if mentioned).

Suggested change

- **`-p, --working-dir <path>`**: Filter sessions by working directory

- **`-w, --working-dir <path>`**: Filter sessions by working directory

The -w change isn't released yet, per --help
-p, --working_dir <WORKING_DIR>
Filter sessions by working directory

Copilot · 2025-11-12T00:11:37Z

documentation/docs/guides/goose-cli-commands.md

- **`--session-id <session_id>`**: Remove a specific session by its session ID
- **`-n, --name <name>`**: Remove a specific session by its name
- **`-r, --regex <pattern>`**: Remove sessions matching a regex pattern
+- **`-i, --id <ID>`**: Remove a specific session by its session ID


Incorrect short flag. According to the code in crates/goose-cli/src/cli.rs, the session_id argument has long = "session-id" with alias = "id", but no short form. This should be documented as --id <ID> or --session-id <ID> (without the -i short option).

Copilot · 2025-11-12T00:11:38Z

documentation/docs/guides/goose-cli-commands.md

 - **`-n, --name <name>`**: Name for this run session (e.g. `daily-tasks`)
 - **`-r, --resume`**: Resume from a previous run
- **`-p, --path <PATH>`**: Path for this run session (e.g. `./playground.jsonl`)
+- **`-p, --path <PATH>`**: Path for this run session (e.g. `./playground.jsonl`). Used for legacy file-based session storage.


Typo: "file- based" should be "file-based" (remove the space before the hyphen).

* origin/main: (29 commits) chore: Update governance to include Discord (#5690) Ollama improvements (#5609) feat: add Supabase MCP server to registry (#5629) Unlist VS Code extension tutorials from MCP and experimental sections (#5677) fix: make image processing work in github copilot provider (#5687) fix: do not take into account gitignore in developer mcp (#5688) docs: session storage migration (#5682) New maintainers (#5685) chore: Update governance (#5660) chore(release): release version 1.14.0 (minor) (#5676) fix : action icons overlap session title in chat history (#5684) Document recent goose PRs (#5683) docs: add GOOSE_PATH_ROOT environment variable documentation (#5678) feat: SessionManager integration for acp sessions (#5657) teach copilot our CI (#5672) bump openapi version directly (#5674) governance: update MAINTAINERS.md to reflect new maintainers (#5675) chore: upgrade rmcp to 0.8.5 (#5673) Update release instructions (#5662) Swapped out to_string_lossy with display for user facing text (#5666) ...

* 'main' of github.com:block/goose: Fix: Always show autocompact threshold ui (#5701) chore: Update governance to include Discord (#5690) Ollama improvements (#5609) feat: add Supabase MCP server to registry (#5629) Unlist VS Code extension tutorials from MCP and experimental sections (#5677) fix: make image processing work in github copilot provider (#5687) fix: do not take into account gitignore in developer mcp (#5688) docs: session storage migration (#5682) New maintainers (#5685) chore: Update governance (#5660) chore(release): release version 1.14.0 (minor) (#5676)

* main: (27 commits) hackathon banner (#5710) Fix documentation-only change detection for push events (#5712) Added transaction commits to multi sql functions in session_manager (#5693) fix: improve and simplify tool call chain rendering (#5704) Fix: Always show autocompact threshold ui (#5701) chore: Update governance to include Discord (#5690) Ollama improvements (#5609) feat: add Supabase MCP server to registry (#5629) Unlist VS Code extension tutorials from MCP and experimental sections (#5677) fix: make image processing work in github copilot provider (#5687) fix: do not take into account gitignore in developer mcp (#5688) docs: session storage migration (#5682) New maintainers (#5685) chore: Update governance (#5660) chore(release): release version 1.14.0 (minor) (#5676) fix : action icons overlap session title in chat history (#5684) Document recent goose PRs (#5683) docs: add GOOSE_PATH_ROOT environment variable documentation (#5678) feat: SessionManager integration for acp sessions (#5657) teach copilot our CI (#5672) ...

…eanup * 'main' of github.com:block/goose: (46 commits) Fix context progress bar not resetting after /clear command (#5652) docs: removing double announcements (#5714) docs: mcp sampling support (#5708) hackathon banner (#5710) Fix documentation-only change detection for push events (#5712) Added transaction commits to multi sql functions in session_manager (#5693) fix: improve and simplify tool call chain rendering (#5704) Fix: Always show autocompact threshold ui (#5701) chore: Update governance to include Discord (#5690) Ollama improvements (#5609) feat: add Supabase MCP server to registry (#5629) Unlist VS Code extension tutorials from MCP and experimental sections (#5677) fix: make image processing work in github copilot provider (#5687) fix: do not take into account gitignore in developer mcp (#5688) docs: session storage migration (#5682) New maintainers (#5685) chore: Update governance (#5660) chore(release): release version 1.14.0 (minor) (#5676) fix : action icons overlap session title in chat history (#5684) Document recent goose PRs (#5683) ...

Signed-off-by: Blair Allan <[email protected]>

dianed-square added 2 commits November 11, 2025 09:26

session storage migration

63112d6

restore

423233c

Copilot AI review requested due to automatic review settings November 11, 2025 18:04

dianed-square requested a review from a team as a code owner November 11, 2025 18:04

Copilot started reviewing on behalf of dianed-square November 11, 2025 18:04 View session

Copilot finished reviewing on behalf of dianed-square November 11, 2025 18:06

Copilot AI reviewed Nov 11, 2025

View reviewed changes

documentation/docs/troubleshooting/diagnostics-and-reporting.md Outdated Show resolved Hide resolved

dianed-square changed the title ~~session storage migration~~ docs: session storage migration Nov 11, 2025

undo revert

6474497

alexhancock reviewed Nov 11, 2025

View reviewed changes

blackgirlbytes reviewed Nov 11, 2025

View reviewed changes

blackgirlbytes approved these changes Nov 11, 2025

View reviewed changes

mention chatrecall; clarify use case

130e68c

Copilot AI review requested due to automatic review settings November 12, 2025 00:06

Copilot started reviewing on behalf of dianed-square November 12, 2025 00:07 View session

typo

cecbdd7

Copilot finished reviewing on behalf of dianed-square November 12, 2025 00:10

Copilot AI reviewed Nov 12, 2025

View reviewed changes

dianed-square merged commit 5648799 into main Nov 12, 2025
16 checks passed

Surendhar-N-D pushed a commit to Surendhar-N-D/goose that referenced this pull request Nov 17, 2025

docs: session storage migration (block#5682)

0216233

arul-cc pushed a commit to arul-cc/goose that referenced this pull request Nov 17, 2025

docs: session storage migration (block#5682)

3d27126

github-actions bot mentioned this pull request Nov 18, 2025

chore(release): release version 1.15.0 (minor) #5780

Merged

BlairAllan pushed a commit to BlairAllan/goose that referenced this pull request Nov 29, 2025

docs: session storage migration (block#5682)

94c0c42

Signed-off-by: Blair Allan <[email protected]>


		## Flag Naming Conventions

		Goose CLI follows consistent patterns for flag naming to make commands intuitive and predictable:

	This functionality requires the built-in `Chatrecall` extension to be enabled (it's enabled by default).
	This functionality requires the built-in `Chatrecall` extension to be enabled (it is not enabled by default).

	- `-i, --id <ID>`: Export a specific session by ID
	- `--id <ID>`: Export a specific session by ID

	- `-p, --working-dir <path>`: Filter sessions by working directory
	- `-w, --working-dir <path>`: Filter sessions by working directory

docs: session storage migration #5682

docs: session storage migration #5682

Uh oh!

Conversation

dianed-square commented Nov 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Type of Change

Testing

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

github-actions bot commented Nov 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

alexhancock left a comment

Choose a reason for hiding this comment

Uh oh!

alexhancock Nov 11, 2025

Choose a reason for hiding this comment

Uh oh!

blackgirlbytes Nov 11, 2025

Choose a reason for hiding this comment

Uh oh!

blackgirlbytes Nov 11, 2025

Choose a reason for hiding this comment

Uh oh!

blackgirlbytes Nov 11, 2025

Choose a reason for hiding this comment

Uh oh!

dianed-square Nov 12, 2025

Choose a reason for hiding this comment

Uh oh!

blackgirlbytes left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Uh oh!

Copilot AI Nov 12, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 12, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 12, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 12, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 12, 2025

Choose a reason for hiding this comment

Uh oh!

dianed-square Nov 12, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 12, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Nov 12, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

dianed-square commented Nov 11, 2025 •

edited

Loading

github-actions bot commented Nov 11, 2025 •

edited

Loading