pi-goosedump

Pi extension for goosedump-backed session search, durable memory, session management, and compaction. Tools use the goose_ prefix.

Install

pi install npm:pi-goosedump

Bundled native binaries: Linux x64 and arm64, macOS arm64, and Windows x64.

Unsupported platforms are rejected when the extension loads. The extension uses that packaged binary by default and does not fall back to a goosedump executable on PATH. Set the shared GOOSEDUMP_BINARY environment variable to an absolute executable path to override it. An invalid override or missing packaged binary is treated as a broken installation. Local models download on first use.

Tools

Prefer these tools whenever prior sessions or durable memory can answer a question. Expand ranked or grepped hits with goose_get before guessing.

| Tool | When to use | | --------------------- | ---------------------------------------------------------- | | goose_search | Ranked session-history search; returns entry IDs | | goose_grep | Exact glob/substring filter over session messages | | goose_get | Expand entry IDs from search/grep to full content | | goose_remember | Queue background learning from a session after a milestone | | goose_recall | Recall project-scoped durable memory with provenance | | goose_forget | Remove a stale memory or a session's retained sources | | goose_memory_status | Inspect storage health, type counts, and tombstones | | goose_compact | Compact the current Pi session asynchronously | | goose_sessions | List or delete sessions in the current working directory |

Defaults:

| Setting | Default | | ---------------- | ------------------------------ | | Session target | Current Pi session | | History scope | lineage (active branch) | | Recall limit | 5 | | Non-Pi providers | Require an explicit session ID |

Use each tool's schema for full options. Typical flow:

1. goose_search or goose_grep for candidate entry IDs
2. goose_get on the interesting IDs
3. goose_recall for durable facts, decisions, preferences, procedures, lessons
4. goose_remember after milestones worth retaining

Commands

| Command | Purpose | | --------------------------------- | ------------------------------------------------ | | /goose-search [query] | Search the current session | | /goose-compact [keep:N] | Compact now; keep the last N user turns verbatim | | /goose-sessions | List, resume, or delete project sessions | | /goose-forget [id\|provider:id] | Forget stored memory | | /goose-memory-status | Show memory storage and indexing status | | /goose-settings | Edit goosedump settings | | /goosedump-settings | Edit goosedump settings (alias) |

Resume is available only for Pi sessions.

Settings

• Global: ~/.pi/agent/settings.json
• Project: .pi/settings.json

{
  "goosedump": {
    "turnsBeforeCompact": 0,
    "summaryMaxTokens": 4096,
    "enableMemory": false
  }
}

| Key | Range | Default | Notes | | -------------------- | -------------- | ------: | -------------------------------------------------------------- | | turnsBeforeCompact | 0–255 | 0 | 0 disables; each completed model response counts as one turn | | summaryMaxTokens | 512–65536 | 4096 | Capped to 80% of compaction.reserveTokens when lower | | enableMemory | true/false | false | Controls whether durable memory tools/commands/learning are on |

The footer shows the remaining turn count in hexadecimal.

Compaction behavior

• Pi's compaction.enabled controls automatic compaction.
• The first enabled context or turn limit starts one compaction.
• Successful compaction resets the turn counter.
• Manual and automatic compaction preserve the previous summary and summarize only new entries.
• keep:N leaves the last N user turns verbatim.
• Manual requests wait until Pi is idle.
• Memory learning runs in the background after a successful compaction.
• If the turn limit expires during a tool loop, Pi saves the current batch, compacts at that turn boundary, and resumes automatically.
• Goosedump failures fall back to Pi's compactor.

Development

Install dependencies and run the test suite:

npm install
npm test
npm run check

To exercise the extension against the binary built in this repository:

cargo build
GOOSEDUMP_BINARY="$(cd ../.. && pwd)/target/debug/goosedump" \
  pi --no-extensions -e ./index.ts

The explicit override takes precedence over the packaged platform binary. It must be an absolute path to an executable regular file.

License

Apache-2.0. See LICENSE.