# 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] [--summary-max-tokens NUMBER] [--plain] [--as PROVIDER]
session copy PROVIDER:ID --to PROVIDER [--yes]
session remove PROVIDER:ID [--yes]
memory remember PROVIDER:ID [--all] [--json]
memory recall QUERY [--project PATH | --all-projects] [--type TYPE] [--limit NUMBER] [--max-tokens NUMBER] [--history] [--json]
memory list [--project PATH | --all-projects] [--type TYPE] [--limit NUMBER] [--history] [--json]
memory show MEM_ID [--json]
memory forget MEM_ID|PROVIDER:ID [--yes] [--json]
memory status [--json]
model pull [all|embedding|text]
```
`session copy`, `session remove`, and `memory forget` print their plan by default.
Pass `--yes` to carry out the change.
## Persistent memory
`session compact` only creates a bounded summary; it never changes durable memory.
Use `memory remember PROVIDER:ID` to retain unseen source events and extract atomic
facts, decisions, preferences, procedures, and lessons with exact provenance.
Remembering the same unchanged session is idempotent. When a new statement is close
to an existing active memory of the same type, the older memory is marked superseded
and linked to the successor. Human and JSON reports list each added statement
(with `mem_` IDs) and any memories it superseded.
`memory recall` searches the current project by default and fills an estimated token
budget with ranked active memories. It first preserves exact lexical and entity-anchor
matches (paths, crates, symbols, commands, concepts), expands through shared anchors,
then fills remaining slots with BGE semantic matches. Existing databases are embedded
in bounded batches; `memory status` reports indexed and pending counts. Pass `--history`
to include superseded statements. Use `memory list` to browse, `memory show` to inspect
provenance revision hashes, entities, and supersession links, and `memory forget` to preview
deletion. Forgetting a memory ID removes the
derived statement; forgetting `provider:session-id` removes that session's retained
source events. Applied forgetting leaves content-free tombstones so deleted memory is
not learned again accidentally.
Summary output is bounded to an estimated 4096 tokens by default. Set
`--summary-max-tokens NUMBER` to choose another budget, or use `0` for no limit.
The bound is best-effort when preserved goals, blockers, decisions, and preferences
alone exceed it.
Session-index caches are versioned clean-break formats and are rebuilt when
incompatible. Durable memory migrations preserve existing sources, statements, and
evidence links; an unsupported schema version is rejected and must be reinitialized
explicitly.
## Inference performance
The custom GPT-OSS-20B CPU engine uses every logical CPU available to the
process by default. Override the compute thread count:
```sh
GOOSEDUMP_INFERENCE_THREADS=6 \
goosedump session compact pi:context-id
```
Compaction directive selection and durable-memory extraction use goosedump's custom
GPT-OSS-20B CPU engine. Semantic recall uses the pinned 36.7 MB BGE-small-en-v1.5
`Q8_0` encoder. Download both ahead of time with `goosedump model pull`, or select one
with `goosedump model pull text` or `goosedump model pull embedding`. Recall falls back
to lexical and entity matching when the embedding model is not cached.
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.