# 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]
```
`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 and are downloaded automatically when an operation first
needs them. Recall still uses lexical and entity matching when the embedding model
is not cached.
Text generation uses every logical CPU by default. Sentence embedding caps a
single query at two threads and uses the configured maximum for token-batched
indexing. Override the maximum for both models 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.