# goosedump
`goosedump` browses, searches, converts, and compacts saved coding-agent
sessions. It also provides project-scoped durable memory.
Supported agents: Claude Code, Codex, Crush, Gemini CLI, Goose, OpenCode, and Pi.
It builds on ideas from [`lllyasviel/VCC`](https://github.com/lllyasviel/VCC).
## Install
Prebuilt binaries support Linux x64/arm64, macOS arm64, and Windows x64:
```sh
npm install --global @jarkkojs/goosedump
```
Build from source (Rust 1.95+, C compiler, Node.js 18+):
```sh
cargo build --release
```
## Quick start
Session targets use `provider:session-id`. Bare IDs are not accepted.
```sh
goosedump session list --query '.provider == "pi"'
goosedump session show pi:context-id
goosedump session find pi:context-id '*database*'
goosedump session search pi:context-id 'database failure'
goosedump session compact pi:context-id
goosedump memory learn pi:context-id
goosedump memory recall 'database failure'
```
Full options: `goosedump --help` and the [manual page](man/man1/goosedump.1).
## Commands
| `session` | `list`, `show`, `find`, `search`, `compact`, `copy`, `remove` |
| `memory` | `learn`, `recall`, `list`, `show`, `forget`, `status` |
### Session
| `list` | Discover sessions as `provider:id` targets |
| `show` | Print a transcript (optionally re-render with `--as`) |
| `find` | Glob-match message text |
| `search` | Rank messages by relevance (5 results per page) |
| `compact` | Create a summary; does not write durable memory |
| `copy` | Preview or write a cross-provider copy |
| `remove` | Preview or remove a session and its descendants |
Range filters (`--entry`, `--from`, `--before`, `--all`) apply to `show`,
`find`, `search`, and `compact`.
### Memory
Compaction and memory are separate. `memory learn` stores evidence first, then
derives cited atomic claims. Recall searches the current project by default.
| `learn` | Learn from new entries in a session's active lineage |
| `recall` | Search claims (lexical, entity, relation, then semantic) |
| `list` | List recent claims |
| `show` | Show one claim with cited evidence |
| `forget` | Tombstone a claim or a session's retained evidence |
| `status` | Storage, indexing, embedding, and type counts |
Memory types: `decision`, `fact`, `preference`, `procedure`, `lesson`.
Defaults:
| Compact summary budget | 4096 |
| Recall result limit | 10 |
| Recall token budget | 2048 |
Pass `--summary-max-tokens 0` to disable the compact limit. Use `--history` for
superseded claims and `--all-projects` to search every project. Recall JSON
includes `match_reasons` and cited evidence with stable `citation_id` values.
Text and embedding models run locally and download on first use. Evidence,
claims, entities, relations, and vectors live together in SQLite.
## Pi extension
The [pi-goosedump](packages/pi-goosedump/README.md) extension adds session
search, memory, session management, and compaction to Pi:
```sh
pi install npm:pi-goosedump
```
## Local models
| [gpt-oss-20b](docs/models/gpt-oss-20b.md) | Claim extraction; compact candidate filter |
| [bge-small-en-v1.5](docs/models/bge-small-en-v1.5.md) | Semantic claim retrieval |
Benchmarks for the text model:
[gpt-oss-20b-benchmarks](docs/models/gpt-oss-20b-benchmarks.md).
## Development
```sh
cargo test --all-targets
cargo clippy --all-targets -- -D warnings
cargo fmt --check
```
## License
| goosedump | LGPL-2.1-or-later |
| pi-goosedump | Apache-2.0 |
| GPT-OSS-20B | Apache-2.0 |
| bge-small-en-v1.5 | MIT |
Models download at run time and are not distributed with goosedump.