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, macOS arm64, Windows x64.

On unsupported platforms, Pi keeps its normal compaction behavior and goosedump tools report that they are unavailable. 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 global and project compaction settings

Resume is available only for Pi sessions.

Settings

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

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

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

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.

License

Apache-2.0. See LICENSE.