poppy-memory 0.2.0__tar.gz

poppy_memory-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,69 @@
+name: CI
+
+# push is restricted to main so PR branches run once (via pull_request),
+# not twice (push + pull_request) — PR #3 review follow-up.
+# pull_request filters on the BASE branch, so stacked PRs (base reveal-prep/*)
+# must be listed too or they would get zero CI runs.
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches:
+      - main
+      - "reveal-prep/**"
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Lint
+        run: |
+          uv run ruff check src/ tests/
+          uv run ruff format --check src/ tests/
+
+      - name: Test
+        run: uv run pytest -v
+
+  # Build-only release rehearsal on every push. Publishing to PyPI happens
+  # exclusively in publish.yml, which triggers only on v* tags.
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install build tooling
+        run: python -m pip install --upgrade pip build twine
+
+      - name: Build wheel + sdist
+        run: python -m build
+
+      - name: Verify build metadata
+        run: python -m twine check dist/*
+
+      - name: Upload dist artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          retention-days: 7

poppy_memory-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,36 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: read
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install build tooling
+        run: python -m pip install --upgrade pip build twine
+
+      - name: Build sdist + wheel
+        run: python -m build
+
+      - name: Verify build metadata
+        run: python -m twine check dist/*
+
+      - name: Publish to PyPI
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+        run: python -m twine upload dist/*

poppy_memory-0.2.0/.gitignore

@@ -0,0 +1,29 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+.uv-cache/
+uv.lock
+
+# Editor / IDE
+.vscode/
+.idea/
+*.swp
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Pytest / coverage
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# Built .mcpb bundles (the mcpb/ source dir with manifest.json + shim is checked in)
+*.mcpb
+mcpb-build/

poppy_memory-0.2.0/CHANGELOG.md

@@ -0,0 +1,87 @@
+# Changelog
+
+All notable changes to Poppy are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] - 2026-06-14
+
+First public release of `poppy-memory`.
+
+### Added
+
+- Core memory CLI: `remember`, `recall`, `list`, `edit`, `forget`, `expire`,
+  `stats`, with types (fact, decision, preference, lesson), projects, TTLs,
+  supersede chains, and LLM conflict detection (`--check-conflicts`,
+  `--auto-supersede`).
+- Three retrieval engines with a floating default tier: `bloom` (hybrid FTS5 +
+  bge-small embeddings + cross-encoder rerank), `sprout` (lighter bi-encoder),
+  `seed` (FTS5 only, zero ML deps). Switch with `poppy engines use`, re-embed
+  with `poppy migrate-engine`.
+- MCP server (`poppy serve`) plus one-command setup for Claude Code (MCP,
+  lifecycle hooks, CLAUDE.md primer), Claude Desktop, Cursor, Windsurf, Codex,
+  Copilot CLI, Pi, Goose, and Hermes Agent. `poppy doctor` verifies the whole
+  installation.
+- Claude Desktop Extension bundle builder (`poppy build mcpb`); the build
+  stamps the pyproject version into the bundle manifest.
+- Optional Trags cloud sync: device-code onboarding (`poppy setup trags`),
+  `poppy sync push|pull|run|status`, and auto-sync after local writes.
+- Imports from existing stores: `poppy import claude-memories` and
+  `poppy import hermes-memories`.
+- Local web UI (`poppy ui`) for browsing, editing, and restoring memories.
+- `--since` filter on `recall`/`list` accepting ISO dates or durations such as
+  `7d` and `1w3d`.
+- Telemetry disclosure and first-class opt-out: `poppy telemetry
+  status|on|off` persisting to `~/.poppy/config.json`, a one-time first-run
+  notice on stderr, and a README section listing every event and property
+  sent. `POPPY_TELEMETRY_OFF=1` always wins.
+- `poppy --version`, single-sourced from `pyproject.toml`.
+- Zero-touch capture: consent-gated automatic memory extraction from coding
+  sessions. Mid-session captures fire every Nth prompt under a single-flight
+  lock with a per-session soft cap; a SessionEnd backstop and PostCompact
+  re-extraction cover whatever the cadence missed. An incremental transcript
+  window (watermark-based, compaction-safe) feeds extraction, and a
+  dedup-on-capture reconciler decides ADD / SUPERSEDE / SKIP before anything
+  is written. Extraction runs locally through the user's own host CLI
+  (claude/codex/gemini); a remote-only backend is never auto-spent.
+- `poppy consent --enable/--disable/--status` plus a one-time consent prompt
+  in `poppy setup claude-code` (and a `--yes` flag): nothing is captured
+  until consent is granted, and an opt-out persists.
+- SessionStart status banner (active / inactive / consent pending) and
+  expanded `poppy doctor` capture reporting: granular consent and backend
+  status, last-capture freshness, journal count, and watermark/lock state.
+- Source-app provenance on MCP writes: memories record the real client app
+  (for example `claude-code` or `cursor`) from `poppy serve --source` or the
+  connecting client's `clientInfo`, never the bare transport string `mcp`.
+- Legacy engine names in an existing `config.json` keep working:
+  `speaker_closet` and `best` map silently to `bloom`, `baseline` to `seed`.
+- `since` filter on the MCP `recall` tool, accepting the same values as the
+  CLI `--since` (ISO date or a duration such as `7d`).
+- Offline-safe retrieval model loading: already-downloaded models load with
+  `local_files_only`, so recall keeps working with the network down; a cold
+  cache with no network exits with a one-line actionable error instead of a
+  HuggingFace traceback; a one-time stderr notice announces the first-run
+  model download.
+
+### Fixed
+
+- `--since` on `recall`/`list` was accepted but silently ignored; it now
+  filters and rejects invalid values with a usage error.
+- `recall`/`list` no longer print the misleading "No memories found." when
+  memories exist but active `--since`/`--project`/`--type` filters excluded
+  them; they say the filters matched nothing instead.
+- Recall telemetry reported a stale hardcoded engine name instead of the
+  engine that actually served the query.
+- The `memory_write` telemetry event sent the raw project name; it now sends
+  only a `has_project` boolean.
+
+### Security
+
+- License set to AGPL-3.0-or-later.
+- `~/.poppy/config.json` (holds API keys) is written 0600 inside a 0700
+  directory, atomically, so secrets never land world-readable.
+- The `poppy setup trags` device-code flow encrypts the returned API key to an
+  ephemeral RSA keypair, so the key never crosses the wire in plaintext.
+- Runtime SQLite connections enable WAL and a busy timeout, preventing
+  lock-related corruption under concurrent hook/CLI access.

poppy_memory-0.2.0/CLAUDE.md

@@ -0,0 +1,99 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+**Poppy** is a developer memory CLI and MCP server. "Remember what matters."
+
+Agents store and recall memories via MCP tools; humans browse via the CLI and the
+local web UI. Data lives locally at `~/.poppy/` (SQLite + FTS5 + embeddings).
+This is the publish repo for the `poppy-memory` package; experimental engine work
+lives elsewhere and is promoted here when it wins.
+
+## Tech Stack
+
+- **Language**: Python 3.11+
+- **Package manager**: uv
+- **CLI**: click
+- **MCP server**: mcp SDK (FastMCP)
+- **Storage**: SQLite + FTS5; embedding engines use sentence-transformers
+- **Testing**: pytest + pytest-asyncio
+
+## Development
+
+```bash
+uv sync                  # install dependencies
+uv run pytest -v         # run tests
+uv run ruff check src/ tests/
+uv run ruff format src/ tests/
+uv run poppy --help      # CLI help
+```
+
+Use the `POPPY_DIR` env var to avoid touching `~/.poppy/` during development.
+The test suite isolates this automatically (see `tests/conftest.py`).
+
+## Architecture
+
+```
+src/poppy/
+├── models.py          # Memory, Source, Filters dataclasses
+├── config.py          # Config load/save, consent tri-state, legacy migration
+├── sources.py         # Source-app provenance vocabulary
+├── engine/
+│   ├── interface.py   # RetrievalEngine ABC (the stable boundary)
+│   ├── registry.py    # Engine catalog + legacy-name fallback mapping
+│   ├── bloom.py       # Default: hybrid FTS5+embeddings, cross-encoder rerank
+│   ├── sprout.py      # Mid tier: lighter bi-encoder, same architecture
+│   └── seed.py        # FTS5 only, no ML deps (universal fallback)
+├── capture/           # Zero-touch capture stack (see below)
+├── consolidation.py   # LLM extraction: backstop, mid-session, post-compact
+├── cli/
+│   ├── main.py        # click CLI commands (incl. consent, doctor)
+│   └── hooks.py       # Claude Code hook entrypoints + detached workers
+├── mcp_server/        # FastMCP server + tool handlers
+├── setup/             # Per-client install (claude-code, cursor, goose, ...)
+├── sync/              # Optional Trags cloud sync
+└── ui/                # Local web UI
+```
+
+### Zero-touch capture (`src/poppy/capture/`)
+
+Automatic memory extraction from coding sessions. Consent-gated: enabled by
+default but inert until `poppy consent --enable` (ADR-0002).
+
+| Module | Role |
+|---|---|
+| `policy.py` | ConsolidationPolicy: consent tri-state + backend detection. Single source of truth for "is capture on, and if not, why". |
+| `_state.py` / `watermark.py` | Per-session JSON state; the watermark marks the last captured turn so no turn is extracted twice. Reset at SessionStart. |
+| `cadence.py` | Fire every Nth user turn; per-session soft cap defers the rest to the SessionEnd backstop. |
+| `lock.py` | Single-flight per-session lock; stale locks (crashed workers) are stolen after 5 minutes. |
+| `window.py` | Incremental transcript reader for `(watermark, now]`; survives compaction by clamping. |
+| `reconciler.py` | Dedup-on-capture before ingest: ADD / SUPERSEDE / SKIP, three tiers (lexical prefilter, LLM verdict, bias to ADD). |
+| `journal.py` | Local JSONL record of what each capture stored. Never synced. |
+| `banner.py` | SessionStart status banner (active / INACTIVE / consent pending). |
+
+Flow: `UserPromptSubmit` hook counts turns and, on cadence, spawns a detached
+`poppy hook _capture-worker` which runs `consolidation.consolidate_capture_event`
+(lock, window, gates, LLM extract, reconcile, watermark advance, journal).
+`SessionEnd` and `PostCompact` run the same extraction as backstops. Extraction
+uses the host CLI (`claude` / `codex` / `gemini`) so it is free and local; a
+remote-only backend is never auto-spent.
+
+Capture state files (`capture_state.json`, `capture_journal.jsonl`,
+`capture-*.lock`) are per-device by design and excluded from sync.
+
+### Key boundary: RetrievalEngine ABC
+
+Everything above `RetrievalEngine` is stable. New engines implement the ABC and
+register in `engine/registry.py`. `interface.py` does not change without
+discussion.
+
+## Conventions
+
+- Python 3.11+, formatted with ruff (line-length 120)
+- Tests with pytest; async tests with pytest-asyncio
+- Commits: conventional commits (`feat:`, `fix:`, `docs:`, `chore:`, `ci:`, `style:`)
+- User-facing copy: no em dashes
+- Releases are tag-driven (`v*` runs publish.yml); CI builds the wheel on every
+  push but never publishes

poppy_memory-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,12 @@
+# Contributing
+
+Poppy's source is published openly under the GNU Affero General Public License v3
+(see [LICENSE](LICENSE)). You are free to read, run, self-host, fork, and modify
+it under those terms.
+
+We do not accept external pull requests. Poppy is developed in-house, and keeping
+a single copyright holder lets us relicense or dual-license cleanly as the project
+evolves. Bug reports are welcome via issues; code contributions will be politely
+declined.
+
+If you build something on top of Poppy, we would love to hear about it.