shumengya/sproutclaw
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update README.md compaction and branching sections

Browse Source 
- Simplify compaction section, link to docs/compaction.md for details
- Clarify that branch summaries are optional (user is prompted)
- Change /branch to /tree in compaction note
This commit is contained in:
Mario Zechner
2025-12-31 14:44:51 +01:00
parent dc5466becc
commit 0fa558154c
1 changed files with 5 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files

16
packages/coding-agent/README.md
View File

@@ -293,7 +293,7 @@ Toggle inline images via `/settings` or set `terminal.showImages: false` in sett
## Sessions ## Sessions
Sessions are stored as JSONL files with a **tree structure**. Each entry has an `id` and `parentId`, enabling in-place branching: navigate to any previous point with `/tree`, continue from there, and switch between branches while preserving all history in a single file. Old linear sessions are auto-migrated on load. Sessions are stored as JSONL files with a **tree structure**. Each entry has an `id` and `parentId`, enabling in-place branching: navigate to any previous point with `/tree`, continue from there, and switch between branches while preserving all history in a single file.
See [docs/session.md](docs/session.md) for the file format and programmatic API. See [docs/session.md](docs/session.md) for the file format and programmatic API.
@@ -325,14 +325,6 @@ Long sessions can exhaust context windows. Compaction summarizes older messages
When disabled, neither case triggers automatic compaction (use `/compact` manually if needed). When disabled, neither case triggers automatic compaction (use `/compact` manually if needed).
**How it works:**
1. Cut point calculated to keep ~20k tokens of recent messages
2. Messages before cut point are summarized
3. Summary replaces old messages as "context handoff"
4. Previous compaction summaries chain into new ones
Compaction does not create a new session, but continues the existing one, with a marker in the `.jsonl` file that encodes the compaction point.
**Configuration** (`~/.pi/agent/settings.json`): **Configuration** (`~/.pi/agent/settings.json`):
```json ```json
@@ -345,7 +337,9 @@ Compaction does not create a new session, but continues the existing one, with a
} }
``` ```
> **Note:** Compaction is lossy. The agent loses full conversation access afterward. Size tasks to avoid context limits when possible. For critical context, ask the agent to write a summary to a file, iterate on it until it covers everything, then start a new session with that file. The full session history is preserved in the JSONL file; use `/branch` to revisit any previous point. > **Note:** Compaction is lossy. The agent loses full conversation access afterward. Size tasks to avoid context limits when possible. For critical context, ask the agent to write a summary to a file, iterate on it until it covers everything, then start a new session with that file. The full session history is preserved in the JSONL file; use `/tree` to revisit any previous point.
See [docs/compaction.md](docs/compaction.md) for how compaction works internally and how to customize it via hooks.
### Branching ### Branching
@@ -354,7 +348,7 @@ Compaction does not create a new session, but continues the existing one, with a
- Search by typing, page with ←/→ - Search by typing, page with ←/→
- Filter modes (Ctrl+O): default → no-tools → user-only → labeled-only → all - Filter modes (Ctrl+O): default → no-tools → user-only → labeled-only → all
- Press `l` to label entries as bookmarks - Press `l` to label entries as bookmarks
- Selecting a branch generates a summary and switches context - When switching branches, you're prompted whether to generate a summary of the abandoned branch (messages up to the common ancestor)
**Create new session (`/branch`):** Branch to a new session file: **Create new session (`/branch`):** Branch to a new session file: