snowpack 0.1.1

Local-first agent memory for Claude Code: episodic + semantic memory in one SQLite file.

snowpack

The snowpack is the season's memory — every storm recorded as a layer.

Local-first agent memory for Claude Code. Snowpack ingests Claude Code session transcripts into episodic memory (what happened across sessions) and semantic memory (durable facts, entities, relationships), all in a single SQLite file with vector + keyword search. The agent reaches it through an ordinary CLI — no MCP server, no daemon, no infrastructure.

Status

Core pipeline implemented (episodic + semantic memory, hybrid retrieval, telemetry, distillation). See docs/adr/ADR-001-memory-architecture.md for the architecture and decision record, docs/hooks.md for ingestion hook setup, and docs/claude-md-snippet.md for the agent-facing usage docs.

Quick start

# 1. Install
pip install snowpack       # or: uv tool install snowpack

# 2. Wire everything up (idempotent, re-runnable, prompts before writing)
snowpack setup

snowpack setup checks Ollama (printing install/pull commands if it's down — it's a soft requirement, see "Embeddings" below), creates ~/.snowpack/snowpack.db, merges the ingestion + compaction-survival hooks into ~/.claude/settings.json (timestamped backup first), installs the memory snippet into ~/.claude/CLAUDE.md between managed markers, and adds the snowpack permission allowlist. --dry-run shows the diffs first, --check is a doctor that audits every integration point, and --uninstall removes exactly what setup added.

# 3. Use it
snowpack probe "auth decisions"   # hybrid retrieval (vector + keyword + recency)

(Ingestion runs out-of-band via the installed hooks; snowpack obs ingest also works manually.)

Embeddings: Ollama setup and choosing a model

Vector search needs a local embedding model served by Ollama. It is a soft requirement: without it snowpack still works — ingest stores episodes un-embedded, probe degrades to keyword + recency search, and the next ingest after Ollama comes up backfills the missing vectors automatically.

Install and run Ollama

# macOS
brew install ollama        # or download the app from https://ollama.com

# Linux
curl -fsSL https://ollama.com/install.sh | sh

# start the server (the desktop app does this automatically)
ollama serve

# fetch the default embedding model (~270 MB)
ollama pull nomic-embed-text

Prefer it sandboxed? A hardened Docker setup (localhost-only API, dropped capabilities, isolated model storage) ships in docker/docker-compose.yml:

docker compose -f docker/docker-compose.yml up -d
docker compose -f docker/docker-compose.yml exec ollama ollama pull nomic-embed-text

See docs/ollama-docker.md for GPU setup and the macOS caveat (containers can't use Apple Silicon's GPU — native Ollama is faster there).

Verify it's answering:

curl -s http://localhost:11434/api/embed \
  -d '{"model": "nomic-embed-text", "input": ["hello"]}' | head -c 120

If Ollama runs somewhere other than localhost:11434 (a container, another machine), point snowpack at it with SNOWPACK_OLLAMA_URL:

export SNOWPACK_OLLAMA_URL=http://gpu-box:11434

Choosing the embedding model

The model is fixed per database at snowpack init, because the vector tables are created with that model's output dimension (vec0 columns are fixed-width):

snowpack init                                  # nomic-embed-text (768-d)
snowpack init --model mxbai-embed-large       # higher quality, 1024-d
snowpack init --model all-minilm              # smaller/faster, 384-d

You normally don't pass --dim: init asks the running Ollama what dimension the model actually produces (and refuses a --dim that contradicts it). If Ollama isn't running, init falls back to a built-in table for common models (nomic-embed-text, mxbai-embed-large, all-minilm, snowflake-arctic-embed, bge-m3) — for anything else, either start Ollama first or pass --dim explicitly.

The configured model, dimension, and task prefixes are recorded in the database (meta table) and used for every subsequent embed, so you never specify the model again after init — obs ingest and probe read it from the database. To see what a database was initialized with:

sqlite3 ~/.snowpack/snowpack.db "SELECT * FROM meta"

Changing models later means re-embedding everything: until snowpack reindex ships, that is rm ~/.snowpack/snowpack.db, snowpack init --model <new>, snowpack obs ingest (episodes re-ingest from the transcripts, but extracted facts and telemetry are lost — export first if you care).

CLI surface

Command	Purpose
snowpack setup	One-command onboarding: hooks, CLAUDE.md, permissions, db (--check doctor, --dry-run, --uninstall)
snowpack init	Create and configure the database
snowpack obs ingest	Ingest new transcript exchanges (incremental, idempotent)
snowpack obs extract	Extract durable facts from episodes (API-assisted)
snowpack obs list	List recent episodes
snowpack probe "query"	Hybrid retrieval (vector + keyword + graph + recency) with telemetry
snowpack feedback	Mark retrieved memories as used — trains ranking
snowpack stash	Working-memory checkpoint per project
snowpack resume	Re-injection payload for SessionStart hooks (compaction survival)
snowpack stats	Telemetry overview; --refresh recomputes usefulness
snowpack sinter	Mine repeated corrections into CLAUDE.md candidates
snowpack entity merge	Point a duplicate entity at its canonical form
snowpack pit	Local web UI: entity graph + telemetry dashboard

The pit (web UI)

snowpack pit            # serves http://127.0.0.1:8617 and opens the browser

A read-only, single-page UI over the same SQLite file (no extra dependencies, no build step; the graph library is vendored so it works offline):

• Graph tab — entities as nodes, facts as edges. Visual weights are real telemetry, not decoration: node size = usage, edge width = retrieval frequency, color = staleness, and dead gray = never retrieved — your pruning candidates at a glance. Click through node → fact → provenance episode; toggle superseded facts; search to highlight.
• Stats tab — totals, retrieval latency, channel win-rate (vector vs keyword vs graph — how to rebalance fusion weights), zero-result queries (gap detection), most/least-used facts, persistent weak layers, and recent retrievals expandable to per-result channels/scores/used flags.

The server binds 127.0.0.1 only and never mutates user data (the one write is recomputing derived usefulness scores on demand). Full guide — including how to read the visual encoding and troubleshooting — in docs/pit.md; stack decisions in docs/adr/ADR-002-pit-ui.md.

Documentation map

• docs/adr/ — architecture decision records (ADR-001 core, ADR-002 pit UI, ADR-003 pre-Phase-2 hardening program)
• docs/plans/ — point-in-time implementation plans approved before each build round, with outcomes
• docs/pit.md — running and reading the pit UI
• docs/hooks.md — out-of-band ingestion hooks
• docs/ollama-docker.md — sandboxed Ollama
• docs/claude-md-snippet.md — agent-facing usage docs for CLAUDE.md
• docs/releasing.md — publishing wheels to PyPI (trusted publishing)

Roadmap

The agent-memory market is crowded with cloud-first offerings (Mem0, Zep, Letta). Snowpack takes the opposite entry: a local-first core that syncs up when you want it to — local-first is the foundation later phases build on, not a stage to discard.

1. Phase 1 — local dev tool (now). Everything in this repo: single SQLite file, CLI + hooks integration, telemetry from day one. Goal: prove retrieval quality and accumulate the usage data later tuning depends on.
2. Phase 2 — local-first + sync. The SQLite file stays the on-device source of truth; optional sync to a hosted backend adds multi-device use, backup, and selective team sharing. The integration surface broadens beyond Claude Code: MCP server plus a language-agnostic SDK/HTTP API.
3. Phase 3 — hosted platform. A managed, multi-tenant memory service covering all four memory types (episodic, semantic, working, procedural). Self-hosting stays a first-class path.

Full reasoning, the fixed-vs-provisional decision table, and migration risks live in docs/adr/ADR-001-memory-architecture.md ("Phasing & evolution").

Fact extraction needs an API key (ANTHROPIC_API_KEY, OPENAI_API_KEY, or SNOWPACK_EXTRACTION_API_KEY) and defaults to Anthropic's OpenAI-compatible endpoint; override with SNOWPACK_EXTRACTION_BASE_URL / _MODEL. Keys are read from the environment only and never stored.

Development

uv sync
uv run pytest
uv run ruff check

Demo data

To try the full surface without real transcripts (and without touching ~/.snowpack), seed a sandboxed demo — synthetic transcripts for two fake projects, pre-extracted facts (including a superseded pair), and probe telemetry:

uv run python scripts/seed_demo.py        # creates ~/.snowpack-demo
export SNOWPACK_DB=~/.snowpack-demo/snowpack.db
export SNOWPACK_CLAUDE_PROJECTS=~/.snowpack-demo/projects
snowpack probe "what did we decide about auth" --all-projects
snowpack stats
snowpack pit

It works without Ollama (probe degrades to keyword+recency, exactly as in real use); with Ollama running the same script embeds everything.