# goosedump
`goosedump` browses, searches, converts, and compacts saved coding-agent
conversations. It supports 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 are available for Linux x64 and arm64, macOS arm64, and Windows x64:
```sh
npm install --global @jarkkojs/goosedump
```
To build from source:
```sh
cargo build --release
```
Source builds require a C compiler for the bundled SQLite library.
## Quick start
```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
```
Every command that operates on a saved session takes an explicit
`provider:session-id` target. Use `goosedump --help` or the
[manual page](https://github.com/jarkkojs/goosedump/blob/main/man/man1/goosedump.1)
for complete usage.
## Commands
The command tree mirrors the things it manages:
```text
session list [--query QUERY] [--json]
session show PROVIDER:ID [--entry ID] [--all] [--from ID] [--before ID] [--as PROVIDER]
session find PROVIDER:ID GLOB [range options] [--as PROVIDER]
session search PROVIDER:ID QUERY [range options] [--page NUMBER] [--as PROVIDER]
session compact PROVIDER:ID [range options] [--previous-summary SUMMARY] [--plain] [--remember] [--as PROVIDER]
session copy PROVIDER:ID --to PROVIDER [--yes]
session remove PROVIDER:ID [--yes]
memory search QUERY [--provider PROVIDER] [--path PATH] [--type TYPE] [--limit NUMBER]
memory status
model pull
```
`session copy` and `session remove` print their plan by default. Pass `--yes`
to carry out the change. This makes destructive and cross-provider operations
safe to inspect without a separate dry-run mode.
## Persistent memory
`session compact` emits a summary without retaining the selected range. Add
`--remember` only when the selected content may become durable memory.
Use `memory search` to retrieve learned decisions, facts, preferences,
procedures, and episodes; `memory status` to inspect the store; and
`memory forget` with a hash printed by `memory search` or a `provider:session-id`
to remove it. Forgetting creates durable tombstones so the same content is not
learned again accidentally.
Persistent formats are versioned and never migrated. An incompatible cache is
rebuilt, while an incompatible memory database is rejected and must be
reinitialized explicitly. A prior schema is never transformed in place.
## Inference performance
The custom GPT-OSS-20B CPU engine uses physical CPU cores, capped by the CPUs
available to the process, by default. Override the compute thread count:
```sh
GOOSEDUMP_INFERENCE_THREADS=6 \
goosedump session compact pi:context-id
```
GPT-OSS-20B text generation continues to use goosedump's custom CPU engine.
Download its weights ahead of time with `goosedump model pull`.
The `bench` feature builds a standalone harness that shells out to
`goosedump session compact` with `GOOSEDUMP_PROFILE_COMPACT=1` and reports
end-to-end and per-stage timings:
```sh
# Edit benches/bench.txt to point at a real context, then:
cargo bench --features bench
```
Each case emits JSON with per-run timing (including model loading), median and
p95 latency, and per-stage medians and p95s. Keep the machine, context range,
and model cache unchanged when comparing configurations.
## Pi extension
The bundled [pi-goosedump extension](packages/pi-goosedump/README.md) adds
session-history search, entry expansion, durable-memory recall, CWD-scoped session management,
memory forget/status maintenance, and turn-driven goosedump compaction to Pi:
```sh
pi install npm:pi-goosedump
```
## Development
```sh
cargo test --all-targets
cargo clippy --all-targets -- -D warnings
cargo fmt --check
```
The published Linux x64 and arm64 binaries are static glibc PIEs.
## Licensing
1. `pi-goosedump`: Apache 2.0
2. `goosedump`: LGPL 2.1+
### Third Party Attribution
1. GPT-OSS-20B: Apache 2.0
- Downloaded on first use at run-time. The model is not distributed together
with goosedump.