# 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 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.