snowpack 0.1.0__tar.gz

snowpack-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,16 @@
+name: ci
+
+on:
+  push:
+    branches: ["**"]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync
+      - run: uv run ruff check
+      - run: uv run pytest -q

snowpack-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,66 @@
+name: publish
+
+# Publishes to PyPI via trusted publishing (OIDC, no tokens) on version tags.
+# One-time setup on pypi.org is documented in docs/releasing.md.
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync
+      - run: uv run ruff check
+      - run: uv run pytest -q
+
+  build:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - name: Check tag matches project version
+        run: |
+          version=$(python3 -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          if [ "v$version" != "$GITHUB_REF_NAME" ]; then
+            echo "tag $GITHUB_REF_NAME does not match pyproject version $version" >&2
+            exit 1
+          fi
+      - run: uv build
+      - name: Smoke-test the wheel
+        # A bad build that drops data files (schema.sql, pit_static/) would
+        # still pass unit tests; install the artifact and exercise it.
+        run: |
+          python3 -m venv /tmp/smoke
+          /tmp/smoke/bin/pip install --quiet dist/*.whl
+          /tmp/smoke/bin/snowpack --help >/dev/null
+          SNOWPACK_DB=/tmp/smoke/test.db /tmp/smoke/bin/snowpack init --model nomic-embed-text
+          SNOWPACK_DB=/tmp/smoke/test.db SNOWPACK_CLAUDE_PROJECTS=/tmp/empty \
+            /tmp/smoke/bin/snowpack probe "smoke" --all-projects --no-log
+          /tmp/smoke/bin/python - <<'EOF'
+          from importlib.resources import files
+          pkg = files('snowpack')
+          assert (pkg / 'schema.sql').is_file(), 'schema.sql missing from wheel'
+          assert (pkg / 'pit_static' / 'index.html').is_file(), 'pit_static missing from wheel'
+          EOF
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

snowpack-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+dist/
+.pytest_cache/
+.ruff_cache/

snowpack-0.1.0/PKG-INFO

@@ -0,0 +1,240 @@
+Metadata-Version: 2.4
+Name: snowpack
+Version: 0.1.0
+Summary: Local-first agent memory for Claude Code: episodic + semantic memory in one SQLite file.
+Author: David Kelly
+Keywords: agent,claude-code,llm,local-first,memory,sqlite
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: Other/Proprietary License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: sqlite-vec>=0.1.6
+Requires-Dist: typer>=0.12
+Description-Content-Type: text/markdown
+
+# 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
+
+```bash
+# 1. Get Ollama running with the embedding model (see "Embeddings" below)
+ollama pull nomic-embed-text
+
+# 2. Install and initialize snowpack
+uv tool install .          # or: uv sync && uv run snowpack ...
+snowpack init              # create ~/.snowpack/snowpack.db
+
+# 3. Use it
+snowpack obs ingest        # ingest Claude Code transcripts (~/.claude/projects)
+snowpack probe "auth decisions"   # hybrid retrieval (vector + keyword + recency)
+```
+
+## Embeddings: Ollama setup and choosing a model
+
+Vector search needs a local embedding model served by
+[Ollama](https://ollama.com). 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
+
+```bash
+# 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`:
+
+```bash
+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:
+
+```bash
+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`:
+
+```bash
+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):
+
+```bash
+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:
+
+```bash
+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 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 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)
+
+```bash
+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)
+- `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
+
+```bash
+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:
+
+```bash
+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.

snowpack-0.1.0/README.md

@@ -0,0 +1,219 @@
+# 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
+
+```bash
+# 1. Get Ollama running with the embedding model (see "Embeddings" below)
+ollama pull nomic-embed-text
+
+# 2. Install and initialize snowpack
+uv tool install .          # or: uv sync && uv run snowpack ...
+snowpack init              # create ~/.snowpack/snowpack.db
+
+# 3. Use it
+snowpack obs ingest        # ingest Claude Code transcripts (~/.claude/projects)
+snowpack probe "auth decisions"   # hybrid retrieval (vector + keyword + recency)
+```
+
+## Embeddings: Ollama setup and choosing a model
+
+Vector search needs a local embedding model served by
+[Ollama](https://ollama.com). 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
+
+```bash
+# 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`:
+
+```bash
+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:
+
+```bash
+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`:
+
+```bash
+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):
+
+```bash
+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:
+
+```bash
+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 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 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)
+
+```bash
+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)
+- `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
+
+```bash
+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:
+
+```bash
+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.

snowpack-0.1.0/docker/docker-compose.yml

@@ -0,0 +1,39 @@
+# Ollama for snowpack, sandboxed.
+#
+#   docker compose -f docker/docker-compose.yml up -d
+#   docker compose -f docker/docker-compose.yml exec ollama ollama pull nomic-embed-text
+#
+# The API is published on 127.0.0.1 only — snowpack's default
+# (http://localhost:11434) works unchanged, and nothing on the network can
+# reach the model server. See docs/ollama-docker.md for GPU setup & caveats.
+
+services:
+  ollama:
+    image: ollama/ollama:latest
+    container_name: snowpack-ollama
+    restart: unless-stopped
+    ports:
+      - "127.0.0.1:11434:11434"
+    volumes:
+      - ollama-models:/root/.ollama   # pulled models persist across restarts
+    cap_drop:
+      - ALL
+    security_opt:
+      - no-new-privileges:true
+    healthcheck:
+      test: ["CMD", "ollama", "list"]
+      interval: 30s
+      timeout: 5s
+      retries: 3
+      start_period: 10s
+    # Optional memory cap. Embedding models are small (nomic-embed-text fits
+    # comfortably in 2g); raise it if you also serve generation models here.
+    # mem_limit: 4g
+
+    # NVIDIA GPU (requires nvidia-container-toolkit); CPU-only works fine
+    # for embedding models. macOS: containers cannot use the GPU at all —
+    # prefer native Ollama on Apple Silicon.
+    # gpus: all
+
+volumes:
+  ollama-models: