# 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 list
goosedump show pi:context-id
goosedump grep pi:context-id '*database*'
goosedump search pi:context-id 'migration failure'
goosedump compact pi:context-id
```
Use `goosedump --help` or the
[manual page](https://github.com/jarkkojs/goosedump/blob/main/man/man1/goosedump.1)
for all commands and options.
## Features
- Lists and filters contexts across all supported providers.
- Renders provider-native output and converts conversations between provider
formats.
- Searches session history with BM25 ranking and glob matching.
- Imports contexts into another provider's store; pair with `delete` to move
them.
- Recalls durable memory harvested from compacted context ranges.
## Persistent memory
`compact` emits a summary without retaining the selected range by default. Pass
`--train` to harvest it into the platform state directory
(`~/.local/state/goosedump/goosedump.db` on Linux). Stored entries are classified
as decisions, facts, preferences, procedures, or episodes and include trust,
confidence, validity, scope, derivation, and concrete source provenance. Admission
screening quarantines instruction-like, generated, and malformed content before
retrieval. Indexing uses a durable pending/indexed/failed ledger, recovers interrupted
work, and stops automatic retries after three attempts. Use `recall --type TYPE` to
restrict a search, `stats` to inspect type, governance, and ingestion counts,
`govern review` to inspect quarantined entries, and `ingest review` to inspect
indexing failures.
Memory keeps historical provenance. Deleting or moving a source context does
not remove previously harvested content. `forget HASH` and `forget PROVIDER:ID`
remove memory and create durable tombstones that prevent re-ingestion. Use
`govern approve`, `quarantine`, `supersede`, `contradict`, and `expire` for explicit
lifecycle control. Pass `compact --train` only when the selected range may be
retained; screening is defensive and is not a substitute for secret filtering.
Reset one terminal failure for another bounded retry cycle with
`ingest retry HASH`.
`mutate` performs an optional local merge of two archived memories. It normally
waits for sufficient usage evidence; `mutate --force` is intended for testing.
The fixed `GPT-OSS-20B MXFP4` text model is downloaded on first use, or ahead of
time with `goosedump pull`.
## Inference performance
The custom GPT-OSS-20B CPU engine defaults to the physical CPU core count, capped by
the CPUs available to the process. Override the compute thread count:
```sh
GOOSEDUMP_INFERENCE_THREADS=6 \
goosedump compact pi:context-id
```
GPT-OSS-20B text generation uses the custom CPU engine. Measure a representative
context before changing the defaults. The `bench` feature builds a standalone harness
that shells out to `goosedump 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 tools, durable-memory recall, and 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.
## License
The Rust program is licensed under `LGPL-2.1-or-later`. The npm distribution
also contains Apache-2.0-licensed components.