poppy-memory 0.2.0__py3-none-any.whl

poppy/__init__.py

@@ -0,0 +1,27 @@
+"""Poppy package metadata.
+
+The version is single-sourced from pyproject.toml: installed distributions
+resolve it via importlib.metadata; bare source checkouts (no dist-info on
+sys.path) fall back to reading pyproject.toml next to the package.
+"""
+
+from importlib import metadata as _metadata
+
+
+def _resolve_version() -> str:
+    try:
+        return _metadata.version("poppy-memory")
+    except _metadata.PackageNotFoundError:
+        pass
+    try:
+        import tomllib
+        from pathlib import Path
+
+        pyproject = Path(__file__).resolve().parents[2] / "pyproject.toml"
+        with pyproject.open("rb") as f:
+            return tomllib.load(f)["project"]["version"]
+    except Exception:
+        return "0.0.0+unknown"
+
+
+__version__ = _resolve_version()

poppy/build_mcpb.py

@@ -0,0 +1,91 @@
+"""Build a `.mcpb` (MCP Bundle) from the Poppy source tree.
+
+The bundle is what Claude Desktop installs with a double-click.
+We assemble a minimal staging directory (manifest, server entry shim,
+pyproject.toml, src/poppy) and shell out to the `mcpb` CLI to pack it.
+"""
+
+from __future__ import annotations
+
+import json
+import shutil
+import subprocess
+from pathlib import Path
+
+# Files copied verbatim from the repo root into the staging dir.
+ROOT_FILES = ("pyproject.toml", "README.md", "LICENSE", "uv.lock")
+
+# Subdirectories to ignore when copying src/poppy.
+SRC_IGNORES = ("__pycache__", ".pytest_cache", ".ruff_cache")
+
+
+def _copy_source(repo_root: Path, stage: Path) -> None:
+    src_dst = stage / "src" / "poppy"
+    shutil.copytree(
+        repo_root / "src" / "poppy",
+        src_dst,
+        ignore=shutil.ignore_patterns(*SRC_IGNORES),
+    )
+
+    for name in ROOT_FILES:
+        f = repo_root / name
+        if f.exists():
+            shutil.copy2(f, stage / name)
+
+
+def _copy_mcpb_inputs(repo_root: Path, stage: Path) -> None:
+    mcpb_src = repo_root / "mcpb"
+    shutil.copy2(mcpb_src / "manifest.json", stage / "manifest.json")
+    shutil.copy2(mcpb_src / "icon.png", stage / "icon.png")
+    shutil.copytree(mcpb_src / "server", stage / "server")
+
+
+def _read_version(repo_root: Path) -> str:
+    pyproject = (repo_root / "pyproject.toml").read_text()
+    for line in pyproject.splitlines():
+        if line.startswith("version") and "=" in line:
+            return line.split("=", 1)[1].strip().strip('"').strip("'")
+    raise RuntimeError("version not found in pyproject.toml")
+
+
+def _sync_manifest_version(stage: Path, version: str) -> None:
+    manifest_path = stage / "manifest.json"
+    manifest = json.loads(manifest_path.read_text())
+    if manifest.get("version") != version:
+        manifest["version"] = version
+        manifest_path.write_text(json.dumps(manifest, indent=2) + "\n")
+
+
+def build_mcpb(repo_root: Path, output_dir: Path) -> Path:
+    """Build a .mcpb bundle and return the path to the produced file.
+
+    Raises RuntimeError if the `mcpb` CLI is missing or pack fails.
+    """
+    if shutil.which("mcpb") is None:
+        raise RuntimeError("`mcpb` CLI not found — install with `npm install -g @anthropic-ai/mcpb`")
+
+    version = _read_version(repo_root)
+    output_dir.mkdir(parents=True, exist_ok=True)
+    stage = output_dir / f"poppy-memory-{version}-stage"
+    if stage.exists():
+        shutil.rmtree(stage)
+    stage.mkdir(parents=True)
+
+    _copy_mcpb_inputs(repo_root, stage)
+    _copy_source(repo_root, stage)
+    _sync_manifest_version(stage, version)
+
+    output_path = output_dir / f"poppy-memory-{version}.mcpb"
+    if output_path.exists():
+        output_path.unlink()
+
+    result = subprocess.run(
+        ["mcpb", "pack", str(stage), str(output_path)],
+        capture_output=True,
+        text=True,
+    )
+    if result.returncode != 0:
+        raise RuntimeError(f"mcpb pack failed:\n{result.stderr}\n{result.stdout}")
+
+    shutil.rmtree(stage)
+    return output_path

poppy/capture/__init__.py

@@ -0,0 +1,13 @@
+"""Auto-capture deep modules (ADR-0001/0002/0003).
+
+Each module here is a small, independently testable unit that the capture
+orchestration composes:
+
+* ``reconciler``  — dedup-on-capture: ADD / SUPERSEDE / SKIP before ingest (ADR-0003).
+* ``window``      — incremental transcript window over ``(watermark, now]`` (ADR-0001).
+* ``watermark``   — per-session capture watermark + turn cadence (ADR-0001).
+
+The SessionEnd / PostCompact backstops and the mid-session loop all route their
+extracted candidates through ``reconciler.reconcile_and_ingest`` so the store
+stays clean no matter what triggered the capture.
+"""

poppy/capture/_state.py

@@ -0,0 +1,46 @@
+"""Per-session capture state file (ADR-0001).
+
+A single JSON file under the Poppy data directory holds the per-session capture
+state — the watermark and, later, the turn cadence counters.
+It is keyed by session id so concurrent sessions never corrupt each other's
+progress.
+
+Writes go through ``save`` which does an atomic ``os.replace`` so a crash mid-write
+can never leave a torn file. Cross-process races within one session are prevented
+by the mid-session single-flight lock; SessionStart / SessionEnd do not
+run concurrently with a mid-session worker in practice.
+
+This file is a per-device cache of capture progress — it is NOT synced (the sync
+boundary keeps the capture journal / state local).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+STATE_FILENAME = "capture_state.json"
+
+
+def state_path(poppy_dir: Path) -> Path:
+    return poppy_dir / STATE_FILENAME
+
+
+def load(poppy_dir: Path) -> dict:
+    path = state_path(poppy_dir)
+    if not path.exists():
+        return {}
+    try:
+        data = json.loads(path.read_text())
+    except (json.JSONDecodeError, OSError):
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def save(poppy_dir: Path, data: dict) -> None:
+    poppy_dir.mkdir(parents=True, exist_ok=True)
+    path = state_path(poppy_dir)
+    tmp = path.with_name(path.name + ".tmp")
+    tmp.write_text(json.dumps(data, indent=2))
+    os.replace(tmp, path)

poppy/capture/banner.py

@@ -0,0 +1,92 @@
+"""SessionStart status banner.
+
+A one-line banner prepended to the SessionStart context so the developer can see
+whether auto-capture is working. It reads the capture status (ConsolidationPolicy,
+ADR-0002), the project memory count (engine), and the last-session capture count
+(CaptureJournal) — the three signals that make silent background capture
+observable rather than invisible.
+
+The render is a pure function so the active / INACTIVE / consent-pending wording is
+testable without a live agent session. Three rules drive it:
+
+* **Active** (capture is running): a reassuring line with the memory count and how
+  many memories the last session captured — proof the loop runs.
+* **INACTIVE** (consented but broken — no backend, remote-only, or the engine
+  failed to load): a *loud* line, because this is the silent-breakage case the
+  banner exists to catch (a partially-installed Poppy that quietly captures
+  nothing for weeks).
+* **Consent pending**: a nudge pointing at ``poppy consent --enable`` — never a
+  misleading "0 captured", since nothing is captured until consent is recorded.
+
+A deliberate off-state (explicit opt-out or a ``POPPY_CONSOLIDATE=0`` override) is
+silent: the developer made that choice, so the banner does not nag every session.
+"""
+
+from __future__ import annotations
+
+from poppy.capture.policy import CaptureStatus
+
+# Statuses that mean "the developer turned this off on purpose" — no banner.
+_SILENT_STATUSES = frozenset({CaptureStatus.DISABLED_OPT_OUT, CaptureStatus.DISABLED_ENV})
+
+
+def _scope(project: str | None) -> str:
+    return "this project" if project else "all projects"
+
+
+def _memory_clause(memory_count: int, project: str | None) -> str:
+    noun = "memory" if memory_count == 1 else "memories"
+    return f"{memory_count} {noun} for {_scope(project)}"
+
+
+def render_banner(
+    status: CaptureStatus,
+    *,
+    project: str | None,
+    memory_count: int,
+    last_session_count: int | None,
+    engine_ok: bool = True,
+) -> str | None:
+    """Render the SessionStart banner line, or ``None`` when nothing should show.
+
+    ``last_session_count`` is the journal's total for the most recent session that
+    captured anything (``None`` when nothing has ever been captured).
+    """
+    # A broken engine means recall itself is down — the loudest INACTIVE case,
+    # independent of capture consent/backend.
+    if not engine_ok:
+        return (
+            "## Poppy: INACTIVE\n"
+            "Poppy could not load its memory engine, so recall and capture are both off. "
+            "Run `poppy doctor` to diagnose."
+        )
+
+    if status in _SILENT_STATUSES:
+        return None
+
+    if status is CaptureStatus.INERT_PENDING:
+        mem = _memory_clause(memory_count, project)
+        return (
+            "## Poppy\n"
+            f"Automatic capture is pending your consent; nothing is captured yet ({mem}). "
+            "Run `poppy consent --enable` to turn it on, or `poppy consent --disable` to dismiss."
+        )
+
+    if status in (CaptureStatus.WARN_REMOTE_ONLY, CaptureStatus.DISABLED_NO_BACKEND):
+        if status is CaptureStatus.WARN_REMOTE_ONLY:
+            why = "only a paid remote backend is configured, so capture will not auto-spend"
+        else:
+            why = "no extraction backend was found"
+        return (
+            "## Poppy: INACTIVE\n"
+            f"Auto-capture is on but {why}, so nothing is being captured. "
+            "Install a host CLI (claude / codex / gemini) for free local capture, then `poppy doctor` to verify."
+        )
+
+    # ACTIVE / FORCED_ENV — capture is running.
+    line = f"## Poppy: active\nRemembering as you work · {_memory_clause(memory_count, project)}"
+    if last_session_count is not None:
+        noun = "memory" if last_session_count == 1 else "memories"
+        line += f" · {last_session_count} {noun} captured last session"
+    line += "."
+    return line

poppy/capture/cadence.py

@@ -0,0 +1,71 @@
+"""TurnCadence — per-session turn counter + cadence gate (ADR-0001).
+
+The mid-session loop fires a capture every Nth user turn. This module owns the
+per-session turn counter and the cadence / soft-cap gates. State lives in the
+shared per-session file (``_state``); the counters reset at SessionStart via
+``watermark.reset_session`` so cadence and coverage are predictable per session
+and concurrent sessions never interfere.
+
+Defaults (N / K) are sane starting points; ADR-0003's autoresearch pass tunes
+them later.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from poppy.capture import _state
+
+# Fire a capture every Nth user turn.
+DEFAULT_CADENCE_N = 3
+
+# Per-session soft cap: after K mid-session captures, stop firing and let the
+# SessionEnd backstop flush the remainder (defers, never drops).
+DEFAULT_SOFT_CAP_K = 20
+
+
+def register_turn(poppy_dir: Path, session_id: str) -> int:
+    """Increment and return this session's turn count."""
+    data = _state.load(poppy_dir)
+    entry = data.setdefault(session_id, {})
+    try:
+        turns = int(entry.get("turns", 0))
+    except (TypeError, ValueError):
+        turns = 0
+    turns += 1
+    entry["turns"] = turns
+    _state.save(poppy_dir, data)
+    return turns
+
+
+def should_capture(count: int, *, n: int = DEFAULT_CADENCE_N) -> bool:
+    """True on every Nth turn (3, 6, 9, ... for n=3)."""
+    return count > 0 and n > 0 and count % n == 0
+
+
+def capture_count(poppy_dir: Path, session_id: str) -> int:
+    """How many mid-session captures have fired for this session."""
+    entry = _state.load(poppy_dir).get(session_id, {})
+    try:
+        return int(entry.get("captures", 0))
+    except (TypeError, ValueError):
+        return 0
+
+
+def soft_cap_reached(poppy_dir: Path, session_id: str, *, k: int = DEFAULT_SOFT_CAP_K) -> bool:
+    """True once the per-session soft cap of mid-session captures is hit."""
+    return capture_count(poppy_dir, session_id) >= k
+
+
+def record_capture(poppy_dir: Path, session_id: str) -> int:
+    """Count one completed mid-session capture; returns the new total."""
+    data = _state.load(poppy_dir)
+    entry = data.setdefault(session_id, {})
+    try:
+        captures = int(entry.get("captures", 0))
+    except (TypeError, ValueError):
+        captures = 0
+    captures += 1
+    entry["captures"] = captures
+    _state.save(poppy_dir, data)
+    return captures

poppy/capture/journal.py

@@ -0,0 +1,126 @@
+"""CaptureJournal — local record of what each capture stored.
+
+One local source of truth for the SessionStart banner, ``poppy doctor``, and the
+dashboard: each capture appends a record with the session, project, count, and a
+short preview of each stored item. It is a per-device cache of already-synced
+data, so it stays local (it is NOT synced — see the sync boundary).
+
+Banner/doctor surfaces that read this are out of scope for the capture slices;
+this module exists so the capture worker has one place to record provenance the
+later surfaces will read.
+"""
+
+from __future__ import annotations
+
+import datetime
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+JOURNAL_FILENAME = "capture_journal.jsonl"
+PREVIEW_CHARS = 80
+MAX_ENTRIES = 200
+
+
+@dataclass
+class CaptureRecord:
+    ts: str
+    session_id: str
+    project: str | None
+    count: int
+    items: list[dict[str, str]] = field(default_factory=list)
+
+
+def _journal_path(poppy_dir: Path) -> Path:
+    return poppy_dir / JOURNAL_FILENAME
+
+
+def _preview(text: str) -> str:
+    text = " ".join((text or "").split())
+    return text[:PREVIEW_CHARS]
+
+
+def record(
+    poppy_dir: Path,
+    *,
+    session_id: str,
+    project: str | None,
+    count: int,
+    items: list[Any],
+    max_entries: int = MAX_ENTRIES,
+) -> CaptureRecord:
+    """Append a capture record. ``items`` are objects with ``.memory_type`` and
+    ``.content`` (Memory) — only the type and a short preview are stored."""
+    rec = CaptureRecord(
+        ts=datetime.datetime.now(datetime.UTC).isoformat(),
+        session_id=session_id,
+        project=project,
+        count=count,
+        items=[
+            {"type": getattr(it, "memory_type", "fact"), "preview": _preview(getattr(it, "content", ""))}
+            for it in items
+        ],
+    )
+
+    poppy_dir.mkdir(parents=True, exist_ok=True)
+    path = _journal_path(poppy_dir)
+    existing: list[str] = []
+    if path.exists():
+        existing = [ln for ln in path.read_text().splitlines() if ln.strip()]
+    existing.append(json.dumps(rec.__dict__))
+    existing = existing[-max_entries:]
+    path.write_text("\n".join(existing) + "\n")
+    return rec
+
+
+def read_all(poppy_dir: Path) -> list[dict[str, Any]]:
+    """Every journal record as raw dicts, oldest first. Skips unparseable lines.
+
+    Public accessor for surfaces that need the whole journal (e.g. the doctor's
+    journal-count line); most callers want :func:`read_last` instead.
+    """
+    path = _journal_path(poppy_dir)
+    if not path.exists():
+        return []
+    out: list[dict[str, Any]] = []
+    for ln in path.read_text().splitlines():
+        ln = ln.strip()
+        if not ln:
+            continue
+        try:
+            out.append(json.loads(ln))
+        except json.JSONDecodeError:
+            continue
+    return out
+
+
+def read_last(poppy_dir: Path) -> CaptureRecord | None:
+    """The most recent capture record, or None if nothing captured yet."""
+    rows = read_all(poppy_dir)
+    if not rows:
+        return None
+    data = rows[-1]
+    return CaptureRecord(
+        ts=data.get("ts", ""),
+        session_id=data.get("session_id", ""),
+        project=data.get("project"),
+        count=int(data.get("count", 0)),
+        items=data.get("items", []),
+    )
+
+
+def last_session_count(poppy_dir: Path) -> int | None:
+    """Total memories captured in the most recent session that captured anything.
+
+    A session can produce several capture records (each mid-session fire plus the
+    SessionEnd backstop), so the banner's "M captured last session" sums the counts
+    of every record sharing the latest record's ``session_id``. Returns ``None``
+    when nothing has been captured yet, so the banner can omit the clause rather
+    than print a misleading "0 captured".
+    """
+    rows = read_all(poppy_dir)
+    if not rows:
+        return None
+    last_session = rows[-1].get("session_id")
+    return sum(int(r.get("count", 0)) for r in rows if r.get("session_id") == last_session)

poppy/capture/lock.py

@@ -0,0 +1,79 @@
+"""Single-flight capture lock.
+
+Never two capture workers for the same session at once: a fast typer can stack
+UserPromptSubmit fires, and overlapping extractions would double-read turns and
+race on the host CLI's auth/lock state (a known cause of silent 0-memory
+extractions). Each capture worker acquires a per-session lock for its whole run;
+a worker that cannot acquire it skips the fire — the watermark catches up next
+time.
+
+The lock is an ``O_CREAT | O_EXCL`` lock file under the Poppy directory. A lock
+older than ``LOCK_TTL_S`` is treated as stale (a crashed worker) and stolen, so a
+crash can never wedge capture permanently.
+"""
+
+from __future__ import annotations
+
+import errno
+import os
+import re
+import time
+from collections.abc import Iterator
+from contextlib import contextmanager
+from pathlib import Path
+
+# A held lock older than this (seconds) is assumed to belong to a crashed worker
+# and is stolen. Comfortably longer than a capture's host-CLI timeout (120s).
+LOCK_TTL_S = 300
+
+
+def _lock_path(poppy_dir: Path, session_id: str) -> Path:
+    safe = re.sub(r"[^A-Za-z0-9_.-]", "_", session_id) or "session"
+    return poppy_dir / f"capture-{safe}.lock"
+
+
+def _try_open(path: Path) -> int | None:
+    try:
+        return os.open(str(path), os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600)
+    except OSError as exc:
+        if exc.errno != errno.EEXIST:
+            return None
+    # Lock exists — steal it only if it is stale (crashed worker).
+    try:
+        age = time.time() - path.stat().st_mtime
+    except OSError:
+        return None
+    if age <= LOCK_TTL_S:
+        return None
+    try:
+        path.unlink()
+    except OSError:
+        return None
+    try:
+        return os.open(str(path), os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600)
+    except OSError:
+        return None
+
+
+@contextmanager
+def single_flight(poppy_dir: Path, session_id: str) -> Iterator[bool]:
+    """Hold the per-session capture lock for the duration of the block.
+
+    Yields ``True`` if the lock was acquired (caller should do the capture) or
+    ``False`` if another worker holds it (caller should skip). Always releases a
+    lock it acquired, even on error.
+    """
+    poppy_dir.mkdir(parents=True, exist_ok=True)
+    path = _lock_path(poppy_dir, session_id)
+    fd = _try_open(path)
+    acquired = fd is not None
+    if fd is not None:
+        os.close(fd)
+    try:
+        yield acquired
+    finally:
+        if acquired:
+            try:
+                path.unlink()
+            except OSError:
+                pass