# goosedump
`goosedump` browses, searches, converts, and compacts saved coding-agent
conversations, and keeps project-scoped durable memory. 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.
## Compaction
`session compact` creates a summary; it never changes durable memory. Summaries are
bounded to an estimated 4,096 tokens by default. Use `--summary-max-tokens` to
change the budget or `0` to disable it. The bound is best-effort when preserved
goals, blockers, decisions, and preferences already exceed it.
## Durable memory
Memory is explicit and separate from compaction:
1. **Remember:** [`gpt-oss-20b`](docs/models/gpt-oss-20b.md) extracts typed,
atomic statements with source provenance. [`bge-small-en-v1.5`](docs/models/bge-small-en-v1.5.md)
embeds each statement. SQLite stores statements and provenance, while the
bundled [`sqlite-vec`](https://github.com/asg017/sqlite-vec) extension indexes
vectors in the same database.
2. **Recall:** lexical and entity matches come first. SQLite KNN queries over
cosine-similar BGE vectors fill the remaining slots.
Memories are classified as decisions, facts, preferences, procedures, or lessons.
`memory remember` processes only new session entries, so remembering an unchanged
session is idempotent. A new version of a memory can supersede an older active
statement of the same type.
Recall searches active memories from the current project by default. Use
`--history` for superseded statements or `--all-projects` to search everywhere.
`memory show` displays provenance, and `memory forget` leaves a tombstone so
forgotten content is not learned again accidentally.
Session-index caches are rebuilt when their format changes. Durable-memory schema
16 intentionally breaks compatibility with earlier databases. Back up and remove
`memory.sqlite3` when upgrading from schema 15 or older.
## Local inference
Both models run locally. Download them with `goosedump model pull`, or use
`model pull text` or `model pull embedding`. Recall still uses lexical and entity
matching when the embedding model is not cached.
Text inference uses every logical CPU by default. Override it with
`GOOSEDUMP_INFERENCE_THREADS`:
```sh
GOOSEDUMP_INFERENCE_THREADS=6 goosedump session compact pi:context-id
```
The optional `bench` feature measures `session compact`. Keep the machine,
session range, and model cache unchanged when comparing runs:
```sh
# Point benches/bench.txt at a real session first.
cargo bench --features bench
```
## Pi extension
The bundled [pi-goosedump extension](packages/pi-goosedump/README.md) adds
session search, durable memory, session management, 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.
## Licensing
1. `pi-goosedump`: Apache 2.0
2. `goosedump`: LGPL 2.1+
### Third Party Attribution
1. GPT-OSS-20B: Apache 2.0
2. bge-small-en-v1.5: MIT
The models are downloaded at run time and are not distributed with goosedump.