Initial release: Sibyl Memory Plugin family v0.1.0

Five-package monorepo for the official Sibyl Memory Plugin:

- sibyl-memory-client 0.4.1: local-first SDK, SQLite + FTS5, five-tier
hierarchical schema, multi-tenant, self-learning skill detection
- sibyl-memory-cli 0.3.2: sibyl init / upgrade / status / whoami / devices
- sibyl-memory-hermes 0.3.4: Hermes Agent v0.13+ memory provider
- sibyl-memory-mcp 0.1.2: MCP server for Claude Code / Codex / Cursor
- sibyl-plugin-schema: SQL migrations (internal, not on PyPI)

All packages MIT licensed, all live on PyPI.

Built by SIBYL at Sibyl Labs LLC.

.gitignore

@@ -0,0 +1,44 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+dist/
+*.egg-info/
+*.egg
+.eggs/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.tox/
+
+# Environments
+.venv/
+venv/
+env/
+.env
+.env.*
+!.env.example
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Vercel
+.vercel/
+
+# Local databases / state
+*.db
+*.sqlite
+*.sqlite3
+~/.sibyl-memory/

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sibyl Labs LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,90 @@
+# Sibyl Labs
+
+Agentic memory infrastructure. Local-first, SQLite-backed, structured-tier memory for AI agents — plus the CLI, MCP server, and Hermes plugin that ship on top of it.
+
+This is the official source repository for the Sibyl Memory Plugin family. All packages are published to PyPI under the MIT license.
+
+---
+
+## Packages
+
+| Package | PyPI | Description |
+|---|---|---|
+| [`sibyl-memory-client`](./sibyl-memory-client) | [![PyPI](https://img.shields.io/pypi/v/sibyl-memory-client)](https://pypi.org/project/sibyl-memory-client/) | Local-first agentic memory SDK. SQLite-backed five-tier hierarchical schema, FTS5 search, multi-tenant, with self-learning skill detection and local memory linter. Foundation of the plugin family. |
+| [`sibyl-memory-cli`](./sibyl-memory-cli) | [![PyPI](https://img.shields.io/pypi/v/sibyl-memory-cli)](https://pypi.org/project/sibyl-memory-cli/) | Command-line interface. `sibyl init` activates, `sibyl upgrade` runs the staker / subscription flow, `sibyl status` shows current tier and DB stats, `sibyl whoami`, `sibyl devices`. |
+| [`sibyl-memory-hermes`](./sibyl-memory-hermes) | [![PyPI](https://img.shields.io/pypi/v/sibyl-memory-hermes)](https://pypi.org/project/sibyl-memory-hermes/) | Bundled memory payload for Hermes Agent v0.13+ (and any other Python orchestration that wants direct SDK access). |
+| [`sibyl-memory-mcp`](./sibyl-memory-mcp) | [![PyPI](https://img.shields.io/pypi/v/sibyl-memory-mcp)](https://pypi.org/project/sibyl-memory-mcp/) | MCP server. Wraps the local SQLite + FTS5 memory engine and exposes it to MCP-compatible agents (Claude Code, Codex, Cursor, Continue, anything that speaks MCP). |
+| [`sibyl-plugin-schema`](./sibyl-plugin-schema) | (internal) | SQL migrations for the activation / account / subscription database. Not on PyPI — kept here as immutable record. |
+
+---
+
+## Install
+
+```bash
+pip install sibyl-memory-cli
+sibyl init
+```
+
+`sibyl init` opens a browser to activate your account at https://sibyllabs.org/plugin/activate, binds your wallet (SIWE) or email, and writes credentials to `~/.sibyl-memory/credentials.json`. Free tier is the default; staker and subscription tiers unlock additional capacity.
+
+For direct SDK use:
+
+```bash
+pip install sibyl-memory-client
+```
+
+For Hermes integration:
+
+```bash
+pip install sibyl-memory-hermes
+```
+
+For MCP:
+
+```bash
+pip install sibyl-memory-mcp
+# Then point your MCP client at the server entry point.
+```
+
+---
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  sibyl-memory-cli       sibyl-memory-mcp                │
+│  ┌──────────────┐       ┌──────────────┐                │
+│  │ sibyl init   │       │ MCP server   │                │
+│  │ sibyl status │       │ (stdio)      │                │
+│  │ sibyl whoami │       └──────┬───────┘                │
+│  └──────┬───────┘              │                        │
+│         │     sibyl-memory-hermes                       │
+│         │     ┌──────────────┐                          │
+│         │     │ Hermes hook  │                          │
+│         │     └──────┬───────┘                          │
+│         │            │                                  │
+│         └──────┬─────┘                                  │
+│                ▼                                        │
+│         sibyl-memory-client (SDK)                       │
+│         ┌────────────────────────┐                      │
+│         │ SQLite + FTS5          │                      │
+│         │ 5-tier schema          │                      │
+│         │ self-learning skills   │                      │
+│         │ multi-tenant           │                      │
+│         └────────────────────────┘                      │
+└─────────────────────────────────────────────────────────┘
+```
+
+Each package has its own `README.md` and `CHANGELOG.md` for details.
+
+---
+
+## License
+
+MIT. See [LICENSE](./LICENSE).
+
+## About
+
+Built by SIBYL, the autonomous agent operating at Sibyl Labs LLC. Follow the work on X at [@sibylcap](https://x.com/sibylcap), or at [sibyllabs.org](https://sibyllabs.org).
+
+Copyright (c) 2026 Sibyl Labs LLC.

sibyl-memory-cli/.gitignore

@@ -0,0 +1 @@
+.vercel

sibyl-memory-cli/CHANGELOG.md

@@ -0,0 +1,330 @@
+# Changelog
+
+All notable changes to `sibyl-memory-cli` are recorded here. Format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Versioning follows
+[SemVer](https://semver.org/).
+
+## [0.3.2] — 2026-05-20
+
+Branding pass on the banner. Operator directive: "beneath the large
+SIBYL title it needs to say underneath the memory you can hold in
+your hand tagline, 'a Sibyl Labs LLC Product. Agentic Infrastructure
+and Memory Products' or something similar."
+
+### Changed
+
+- `_banner.py` now emits a third line under the wordmark + tagline:
+  `a Sibyl Labs LLC Product. Agentic Infrastructure and Memory Products`.
+  Rendered in the same deepest-gold (`_GRADIENT[-1]` = `(106, 79, 31)`)
+  as the tagline but with ANSI dim (`\033[2m`) applied so the visual
+  hierarchy reads SIBYL > tagline > attribution at a glance. Plain-text
+  fallback also includes the line for non-color terminals.
+
+Preview captures at https://sibylcap.com/hud-2026-05-20 (scene 09
+isolates the banner; scenes 01 + 05 show it inline with the rest of
+the activation and install ceremonies).
+
+## [0.3.1] — 2026-05-20
+
+Operator-directed tuning: "typical app patterns — heavy menus on
+install window and initial setup, light on dashboards etc." v0.3.0
+applied the full section_header treatment uniformly across every
+subcommand. v0.3.1 lightens the daily-use dashboards and keeps the
+ceremony reserved for activation moments.
+
+### Changed
+
+- `sibyl status`, `sibyl whoami`, `sibyl devices`, `sibyl logout`,
+  `sibyl health` — dropped the section_header opener. Same convention
+  as `git status`, `ls -la`, `gh auth status`, `pg_isready`,
+  `redis-cli ping`: utilitarian dashboards present data, not chrome.
+  Eyebrow labels + kv rows + status lines remain.
+
+### Unchanged
+
+- `sibyl init` — keeps the full SIBYL gradient banner + section
+  headers + numbered next-steps. This IS the install moment; it earns
+  the ceremony.
+- `sibyl upgrade` — keeps section header + KV. Mid-weight: tier-flip
+  moment is install-ish but not first-run.
+- `_aesthetic.py` library — unchanged. Applied differently across
+  commands per the heavy/light convention.
+
+## [0.3.0] — 2026-05-20
+
+Visual identity pass across every subcommand. The `sibyl init` brand
+moment (the SIBYL ASCII wordmark with pale-gold → deep-ochre vertical
+gradient) was the only command with serious typography; every other
+subcommand was plain text + ANSI 16-color. v0.3.0 brings the lab face
+to the whole surface.
+
+### Added
+
+- New `_aesthetic.py` module — shared visual library for the entire CLI.
+  Brand palette derived from the rule 46 creme paper face (PAPER, INK,
+  ACCENT, JADE, PULSE, RULE, etc.). 24-bit truecolor → 256-color → plain
+  text degradation cascade. Letter-spaced eyebrows, gradient titles,
+  ASCII rule dividers, key/value rows, status chips with success/warn/
+  error glyphs, multi-stop char-by-char gradient interpolation.
+- `SIBYL_FORCE_COLOR=1` env override for non-tty rendering (CI logs,
+  doc captures, harness inspection). Honors `NO_COLOR` as the wider
+  precedence override per the standard.
+
+### Changed
+
+- `sibyl init`, `sibyl upgrade`, `sibyl status`, `sibyl whoami`,
+  `sibyl devices`, `sibyl logout`, `sibyl health` all now open with a
+  styled section header (gradient command-name + creme rule lines +
+  dim subtitle), use eyebrow labels for sub-sections (uppercase
+  letter-spaced ochre), and render key/value rows + status lines with
+  the brand palette. Success states (Activated, Upgraded, Logged out)
+  flow with a pulse → jade gradient. Cap warnings and errors use the
+  measured warm-ochre / red palette tokens, not generic ANSI 31/33.
+- `sibyl init` waiting spinner now reads "watching the network for your
+  bind" in pulse-jade, aligned with the wallet-bind-watcher service
+  language users see in their browser.
+- `sibyl devices` list rendering: current device marked with `▶` in
+  pulse + the device label flows in gold gradient; other devices show
+  in calm ink with dim metadata. Index chips in pulse for "this device"
+  or muted gray for the rest.
+
+### Compatibility
+
+- Backward compat preserved: existing `dim/bold/green/yellow/red/cyan`
+  helpers stay in `cli.py` (used by the legacy `print_status` path
+  which is now superseded but not removed). New `_aesthetic.a.*`
+  helpers layer on top.
+- All visual choices honor `NO_COLOR`. Plain text fallback is
+  visually clean (no garbage escapes leak).
+- Terminal capability detection identical to `_banner.py` for
+  consistency (COLORTERM=truecolor, TERM_PROGRAM whitelist, TERM
+  pattern match for kitty/alacritty/256color).
+
+## [0.2.0] — 2026-05-19
+
+Auth-redesign wave 2 — account-surface CLI commands. Adds `sibyl whoami`
+for a one-line account summary (masked by default, `--full` opt-in) and
+`sibyl devices` for listing active bearer tokens with per-device revoke.
+
+### Added
+
+- `sibyl whoami` — one-line summary: short account_id, tier, masked email
+  (`a***@e***.tld`), masked wallet (`0xabcd…1234`), this device label.
+  `--full` flag shows unmasked email + wallet for ops scenarios.
+- `sibyl devices` — list active (non-revoked) bearer tokens for the
+  account in issued_at DESC order. Marks current device with `▶` and
+  shows revoke command for each other device.
+- `sibyl devices revoke <index>` — POST `/api/plugin/devices` with the
+  bearer_id at that index. Refuses to revoke the calling device.
+
+### Server companion (deployed)
+
+- `GET  /api/plugin/devices?account_id=<uuid>` — lists bearer_tokens.
+- `POST /api/plugin/devices { bearer_id }` — revokes the bearer.
+- Both auth via `Authorization: Bearer <session_token>`; caller must
+  own the account.
+
+## [0.1.4] — 2026-05-18
+
+Maximum-efficiency onboarding release. New `sibyl setup` command auto-detects
+agent frameworks on the user's machine and wires SIBYL as the memory provider
+in one command. Replaces the prior three-step Hermes flow (`pip install
+sibyl-memory-hermes` + `sibyl-memory-hermes install-plugin` + manual
+`config.yaml` edit) with `sibyl setup`. Also handles Claude Code MCP wiring.
+
+### Added
+
+- **`sibyl setup`** — new subcommand. Auto-detects Hermes (`$HERMES_HOME` or
+  `~/.hermes/` or `hermes` on PATH) and Claude Code (`~/.claude/settings.json`
+  or `claude` on PATH). Prompts per stack with explicit confirmation:
+  - Fresh add: `Set SIBYL as default memory provider in Hermes? [Y/n]` (default Y)
+  - Overwrite existing: `Hermes currently uses 'mem0' as memory provider. Overwrite with SIBYL? [y/N]` (default N, never destroys user state without explicit y)
+  - Already wired: noop with green status
+  - Multi-framework: `Wire which? [h]ermes, [c]laude, [a]ll, [n]one (default: all)`
+- **`sibyl setup hermes`** / **`sibyl setup claude-code`** — explicit targeting
+  for power users (skips detection, wires only the named stack).
+- **Flags**: `--yes` (accept all defaults, still respects destructive-default-N
+  unless `--force` is also passed), `--force` (overwrite existing non-SIBYL
+  configs), `--dry-run` (print intent without writing), `--hermes-home`,
+  `--claude-settings` (override autodetect).
+- **Atomic writes + backups**: every config edit creates a `.bak` sibling
+  (`config.yaml.bak`, `settings.json.bak`) before atomic rename via tmpfile.
+  Defensive against partial writes + user mistake recovery.
+- **`HermesWirer`, `ClaudeCodeWirer`** classes in new `sibyl_memory_cli.setup`
+  module. Composable wirer protocol (`is_present()` / `current_state()` /
+  `wire()` / `WireOutcome`) ready for v0.1.5 addition of Codex / Cursor /
+  Continue wirers.
+- **33 new tests** in `tests/test_setup.py` covering: detection logic, prompt
+  helpers, Hermes fresh / existing-sibyl / existing-other / force-overwrite /
+  dry-run / config-preservation, Claude Code fresh / existing-other-mcps /
+  existing-sibyl / mismatched-sibyl / force / dry-run.
+
+### Changed
+
+- **Dependencies**: added `pyyaml>=6.0` for Hermes `config.yaml` editing.
+  Already a transitive dep for any Hermes user; small (~250 KB) for
+  Claude-Code-only users.
+
+### Notes
+
+- Replaces the prior canonical three-step Hermes flow. Docs `install.html`
+  Step 4 collapses from three commands to two: `pip install sibyl-memory-cli`
+  + `sibyl setup`. The old `sibyl-memory-hermes install-plugin` path stays
+  documented as a manual fallback for advanced users who want fine-grained
+  control over each step.
+- Codex / Cursor / Continue MCP wirers are scoped for v0.1.5. The wirer
+  protocol in `setup.py` is ready to take them as drop-in classes.
+- The shell installer (`curl ... | sh`) remains on the roadmap; combined with
+  `sibyl setup` it collapses the full onboarding to a single curl line.
+
+
+
+## [0.1.3] — 2026-05-18
+
+KAPPA external-tester remediation release. Family-wide alignment with the
+v0.4.0 client + v0.3.2 hermes (KAPPA-attributed fixes: exception export
+path, db file perms, identifier validation, FTS5 error surfacing). No CLI
+code changes in this release.
+
+### Changed
+
+- `sibyl-memory-client` pin: `>=0.3.3` → `>=0.4.0`.
+- `sibyl-memory-hermes` pin: `>=0.3.1` → `>=0.3.2`.
+
+### Notes
+
+- `sibyl init / upgrade / status / health` surface is unchanged from
+  v0.1.2. KAPPA's fixes flow through transparently via the dependency
+  bump.
+
+---
+
+## [0.1.2] — 2026-05-18
+
+Audit-remediation release. v0.3.0 plugin-family pre-ship audit (2026-05-18T05:05Z)
+surfaced 10 critical findings; this release lands the CLI-side fixes.
+Companion releases: `sibyl-memory-client` v0.3.3 (engine + schema v3 +
+cross-tier search), `sibyl-memory-hermes` v0.3.1, `sibyl-memory-mcp` v0.1.1.
+
+### Fixed
+
+- **C3** — `__version__` no longer hardcoded. Now sourced from
+  `importlib.metadata.version("sibyl-memory-cli")` with `+source` fallback.
+  Same pattern as sibyl-memory-hermes v0.3.0+. Wheel and `__init__.py`
+  can't drift.
+- **C3** — HTTP User-Agent header now built from the runtime
+  `_client_version()` helper instead of the hardcoded `"sibyl-memory-cli/0.1.0"`.
+  Server telemetry will see real versions, not the stale literal.
+- **C3** — `/api/plugin/session-init` payload's `client_version` field
+  similarly switched from `__import__("sibyl_memory_cli").__version__` to
+  the helper. Telemetry will accurately reflect 0.1.2+.
+- **C4** — post-activation message rewritten. Removed the fictional
+  `from hermes_agent import Agent; agent = Agent(memory=SibylMemoryProvider())`
+  quickstart (the API never existed in any Hermes release). Replaced with:
+  the real Hermes install flow (`sibyl-memory-hermes install-plugin` +
+  config.yaml edit), the MCP install hint for Claude Code / Codex / Cursor /
+  Continue users, and the direct-SDK path for any Python orchestration.
+
+### Security
+
+- **SEC-2** — `write_credentials_atomic` now creates files at mode 0o600
+  set by the kernel at file-creation time via `os.open(O_WRONLY|O_CREAT|
+  O_EXCL|O_NOFOLLOW, 0o600)`. Previously used `write_text()` then
+  `os.chmod(0o600)`, leaving a world-readable window between syscalls every
+  credential save. No race.
+- **SEC-1** (CLI-side mitigation) — the URL parameter handed to the
+  browser is now treated as an opaque pairing-session identifier, not as
+  the long-lived bearer. After activation completes, the CLI prefers a
+  server-issued `bearer_token` field from `/check` (post-fix server flow);
+  if absent, falls back to the legacy session-echo flow. Full fix requires
+  the api-sibyllabs server-side change to issue a separate bearer; this
+  release prepares the CLI to consume it when the server-side lands.
+  Internal variable renamed `session_token` → `session_id` in `cmd_init`
+  to reflect the corrected meaning.
+- **SEC-11** — `read_credentials` refuses to follow symlinks.
+
+### Dependencies
+
+- `sibyl-memory-client>=0.3.3` (was `>=0.3.0`)
+- `sibyl-memory-hermes>=0.3.1` (was `>=0.2.0`) — picks up the fictional-API
+  removal in the hermes package; earlier versions are structurally broken.
+
+## [0.1.1] — 2026-05-17
+
+### Added
+
+- **SIBYL wordmark banner** at the top of `sibyl init`. ANSI Shadow boxchars,
+  24-bit truecolor vertical gradient flowing cream/white at the top through
+  warm gold to deep ochre at the bottom — aligned with the lab visual identity
+  per the operator's brand-discipline rule (creme palette, `--accent #8a6a2a`).
+  Plus a tagline: "memory you can hold in your hand".
+
+### Implementation notes
+
+- New module `sibyl_memory_cli._banner` with `render_banner()` and
+  `print_banner()` helpers. Truecolor support is detected via `COLORTERM`,
+  `TERM_PROGRAM`, and `TERM` — modern terminals (iTerm2, Alacritty, Kitty,
+  wezterm, Ghostty, Windows Terminal, VS Code, Tabby) light up automatically.
+- Gracefully degrades to plain text (still readable, no escape junk) when
+  `NO_COLOR` is set, when stdout is not a TTY, or when `TERM=dumb`.
+- Wired into `cmd_init` only — `status` / `health` / `upgrade` stay banner-free
+  so they don't add noise to scripted invocations.
+- Banner palette is encoded as 6 RGB tuples (one per row) in the module
+  rather than computed at runtime — easier to tune and audit.
+
+## [0.1.0] — 2026-05-16
+
+### Changed (same-day revision before publish): terminal pairing code
+
+`sibyl init` now generates a 6-digit pairing code locally (via
+`secrets.randbelow`), prints it in the terminal, and POSTs only its
+sha256 hash to `/api/plugin/session-init` BEFORE opening the browser.
+The code itself never leaves the user's machine until they type it
+into the browser's email panel. Replaces the earlier Resend-backed
+email magic-code flow, removing the external dependency entirely.
+
+The wallet (SIWE) path is unchanged — the pairing code only matters
+for the email panel.
+
+
+
+Initial release. Operator directive 2026-05-16: build the user-facing
+CLI + upgrade page so the SDK + payment-auth machinery has a front door.
+
+### Added
+
+- **`sibyl init`** — browser activation. Generates a session UUID,
+  opens `sibyllabs.org/plugin/activate?session=...` in the user's
+  browser, polls `api.sibyllabs.org/api/plugin/check` every 3s with a
+  10-min timeout. On bind, writes `~/.sibyl-memory/credentials.json`
+  atomically at mode 0600.
+- **`sibyl upgrade`** — opens `sibyllabs.org/plugin/upgrade?session=...`
+  with the existing session token. Polls `/api/plugin/access` every 3s
+  with a 15-min timeout until `tier` changes from the local value.
+  On change: rewrites credentials.json, clears `tier_cache.json` so
+  the next write picks up the new entitlement immediately.
+- **`sibyl status`** — shows local credentials, DB size, tier cache
+  state, plus the server's view of tier (subscription / staker /
+  free). Flags local↔server tier drift.
+- **`sibyl health`** — wraps `SibylMemoryProvider.health()`. Prints
+  the JSON diagnostic dict.
+
+### Design
+
+- Pure stdlib HTTP via `urllib`. No `requests`, no `httpx`. The wheel
+  installs in seconds.
+- `session_token` printed only as short slice (`first8…last4`). Never
+  full-length to stdout.
+- Polling has explicit timeouts. No infinite loops. Ctrl-C exits 130.
+- All endpoint URLs configurable via env (`SIBYL_API_BASE`,
+  `SIBYL_ACTIVATE_BASE`, `SIBYL_UPGRADE_BASE`) for staging tests.
+
+### Depends on
+
+- `sibyl-memory-client>=0.3.0` (cap gate)
+- `sibyl-memory-hermes>=0.2.0` (provider + credentials loader)
+
+### Entry point
+
+`pip install sibyl-memory-cli` installs the `sibyl` binary via the
+`[project.scripts]` block in pyproject.

sibyl-memory-cli/README.md

@@ -0,0 +1,103 @@
+# sibyl-memory-cli
+
+Command-line interface for the **Sibyl Memory Plugin**.
+
+```bash
+pip install sibyl-memory-cli
+```
+
+This pulls in `sibyl-memory-client` (the local SDK) and `sibyl-memory-hermes` (the Hermes provider) automatically.
+
+## Commands
+
+```
+sibyl init                  Open the browser activation page. Writes ~/.sibyl-memory/credentials.json.
+sibyl upgrade               Open the upgrade page. Stake $SIBYL or subscribe in USDC.
+sibyl status                Show local credentials, DB size, and the server's view of your tier.
+sibyl health                Run the SibylMemoryProvider self-check (schema version, DB path, tenant).
+```
+
+## Activation
+
+```bash
+$ sibyl init
+
+  Sibyl Memory Plugin · activation
+
+  Session:     a1b2c3d4…e5f6
+  Opening:     https://sibyllabs.org/plugin/activate?session=a1b2c3d4-…
+
+  Sign in with your wallet in the browser. This terminal will pick up automatically.
+
+  ⠹ waiting for browser activation … 9:42 left
+```
+
+The browser opens. Sign a SIWE message with your wallet. The terminal picks up the moment the binding lands. Credentials are written to `~/.sibyl-memory/credentials.json` at mode 0600.
+
+## Upgrade
+
+```bash
+$ sibyl upgrade
+
+  Sibyl Memory Plugin · upgrade
+
+  Account            a1b2c3d4…e5f6
+  Current tier       FREE
+  Opening            https://sibyllabs.org/plugin/upgrade?session=…
+
+  Two paths in your browser:
+    1. Stake $SIBYL on Base (free unlimited if you qualify)
+    2. Subscribe in USDC (monthly / quarterly / annual)
+```
+
+In the browser:
+- **Stake** — connect your wallet (browser or Coinbase Smart Wallet), sign to bind, and the page checks your `$SIBYL` balance on Base. If you hold the threshold (default 100,000 $SIBYL liquid+staked, configurable), the local cap lifts.
+- **Subscribe** — pick monthly ($29) / quarterly ($79) / annual ($290) USDC, sign the transfer, the server records the subscription. Tier flips immediately.
+
+On either path, the CLI sees the tier change, rewrites `credentials.json`, and clears `tier_cache.json` so your next write picks up the new entitlement without delay.
+
+## Status
+
+```bash
+$ sibyl status
+
+  Sibyl Memory Plugin · status
+
+  LOCAL
+    Credentials       ~/.sibyl-memory/credentials.json
+    Account           a1b2c3d4…e5f6
+    Tier              FREE
+    DB size           1,247,300 bytes (1.19 MB)
+    Tier cache        free (checked 2026-05-16T18:12:03)
+
+  SERVER
+    Tier              FREE
+    Source            free
+    Cap bytes         2,097,152
+    $SIBYL held       0
+    Threshold         100,000
+    Qualified         no
+```
+
+If `LOCAL` and `SERVER` tiers diverge, run `sibyl upgrade`.
+
+## Environment overrides
+
+For internal testing only:
+
+```bash
+SIBYL_API_BASE=https://staging.api.sibyllabs.org sibyl init
+SIBYL_ACTIVATE_BASE=https://staging.sibyllabs.org/plugin/activate sibyl init
+SIBYL_UPGRADE_BASE=https://staging.sibyllabs.org/plugin/upgrade sibyl upgrade
+```
+
+## Security
+
+- `credentials.json` is written atomically at mode 0600.
+- `session_token` is never printed in full — only a short slice.
+- No memory content ever transits these endpoints. The CLI never reads `memory.db` content; it only checks file size.
+- Wallet operations happen in the browser. The CLI sees only the resulting tier change.
+
+## License
+
+MIT.

sibyl-memory-cli/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sibyl-memory-cli"
+version = "0.3.2"
+description = "Command-line interface for the Sibyl Memory Plugin. `sibyl init` activates, `sibyl upgrade` runs the staker / subscription flow, `sibyl status` shows current tier and DB stats, `sibyl whoami` gives a one-line account summary, `sibyl devices` lists active devices and supports per-device revoke."
+authors = [{ name = "SIBYL, Sibyl Labs LLC", email = "sibyl@sibyllabs.org" }]
+license = { text = "MIT" }
+readme = "README.md"
+requires-python = ">=3.10"
+keywords = ["sibyl", "memory", "cli", "agent", "hermes"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Environment :: Console",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+  "sibyl-memory-client>=0.4.0",
+  "sibyl-memory-hermes>=0.3.2",
+  "pyyaml>=6.0",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=7.0",
+]
+
+[project.scripts]
+sibyl = "sibyl_memory_cli.cli:main"
+
+[project.urls]
+Homepage = "https://sibyllabs.org/plugin"
+Documentation = "https://docs.sibyllabs.org/memory/"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["sibyl_memory_cli*"]

sibyl-memory-cli/src/sibyl_memory_cli/__init__.py

@@ -0,0 +1,24 @@
+"""sibyl-memory-cli — Command-line interface for the Sibyl Memory Plugin.
+
+Entry point: `sibyl` (installed via [project.scripts] in pyproject).
+
+Commands:
+    sibyl init          activate the plugin — opens browser SIWE flow, writes ~/.sibyl-memory/credentials.json
+    sibyl upgrade       open the upgrade flow — stake $SIBYL or subscribe in USDC
+    sibyl status        show current tier, DB size, expiry, account
+    sibyl health        provider self-check (mirrors SibylMemoryProvider.health())
+
+Browser pages live at sibyllabs.org/plugin/{activate,upgrade}.
+All HTTP calls target https://api.sibyllabs.org/api/plugin/*.
+"""
+from .cli import main
+
+# Single-sourced from installed metadata so wheel + code can't drift
+# (C3 audit fix v0.1.2). Same pattern as sibyl-memory-hermes v0.3.0+.
+from importlib.metadata import PackageNotFoundError, version as _pkg_version
+try:
+    __version__ = _pkg_version("sibyl-memory-cli")
+except PackageNotFoundError:  # pragma: no cover - source-tree dev only
+    __version__ = "0.0.0+source"
+
+__all__ = ["main", "__version__"]

sibyl-memory-cli/src/sibyl_memory_cli/_aesthetic.py

@@ -0,0 +1,279 @@
+"""Shared visual identity for the sibyl CLI surface.
+
+Sister module to `_banner.py`. Where the banner is the identity-reveal
+moment for `sibyl init`, this module supplies the granular building
+blocks every subcommand uses to share one coherent look:
+
+  - 24-bit-truecolor → 256-color → plain-text degradation cascade
+  - Brand palette derived from the lab creme paper face (rule 46)
+  - Letter-spaced eyebrow labels, gradient titles, ASCII rule dividers
+  - Key/value rows, status chips, success/warn/error glyphs
+  - Pulsing accents for live states (activation, upgrade, watching)
+
+Voice constraint: precise, editorial, restrained. Gradients flow over
+2–3 stops max. No rainbow. The terminal is paper.
+"""
+from __future__ import annotations
+
+import os
+import sys
+from typing import Iterable
+
+# ─── Palette (RGB · derived from rule 46 creme-paper tokens) ─────────
+# Names map 1:1 to CSS custom properties on lab artifacts.
+
+PAPER       = (245, 241, 230)   # --paper        — foreground accent on dark
+PAPER_DEEP  = (237, 230, 211)   # --paper-deep   — depth on creme
+CARD        = (253, 251, 245)   # --card         — slightly lifted creme
+INK         = (21,  17,  10)    # --ink          — main text on creme
+INK_SOFT    = (44,  39,  29)    # --ink-soft     — body text
+INK_MUTE    = (106, 99,  86)    # --ink-mute     — secondary text
+INK_FAINT   = (152, 145, 127)   # --ink-faint    — tertiary text
+RULE        = (216, 208, 187)   # --rule         — hairline
+RULE_STRONG = (184, 174, 147)   # --rule-strong  — emphasised hairline
+ACCENT      = (138, 106, 42)    # --accent       — ochre highlight
+ACCENT_WARM = (160, 132, 56)    # --accent-warm  — softer ochre
+ACCENT_GOLD = (224, 194, 119)   # mid gold       — gradient bridge
+ACCENT_PALE = (244, 229, 184)   # pale gold      — gradient top
+JADE        = (45,  110, 106)   # --jade         — cool counterpoint
+PULSE       = (29,  138, 130)   # --pulse        — brighter jade (live signal)
+ERROR       = (162, 58,  42)    # --error        — measured red
+
+# Status glyphs (Unicode, terminal-safe in modern fonts)
+GLYPH_OK    = "✓"
+GLYPH_WARN  = "⚠"
+GLYPH_ERR   = "✗"
+GLYPH_DOT   = "·"
+GLYPH_ARROW = "→"
+GLYPH_BULLET = "▸"
+
+
+# ─── Terminal capability detection ────────────────────────────────────
+
+def supports_truecolor() -> bool:
+    """24-bit RGB ANSI. Same heuristic as _banner.py."""
+    if os.environ.get("NO_COLOR"):
+        return False
+    if os.environ.get("TERM", "").lower() == "dumb":
+        return False
+    # SIBYL_FORCE_COLOR=1 — explicit override for non-tty rendering
+    # (CI logs, doc captures, dev inspection in non-tty environments).
+    if os.environ.get("SIBYL_FORCE_COLOR") == "1":
+        return True
+    if not sys.stdout.isatty():
+        return False
+    colorterm = os.environ.get("COLORTERM", "").lower()
+    if "truecolor" in colorterm or "24bit" in colorterm:
+        return True
+    term_program = os.environ.get("TERM_PROGRAM", "").lower()
+    if term_program in {"iterm.app", "wezterm", "ghostty", "vscode", "tabby"}:
+        return True
+    term = os.environ.get("TERM", "").lower()
+    if any(k in term for k in ("256color", "kitty", "alacritty", "xterm-direct")):
+        return True
+    return False
+
+
+def supports_color() -> bool:
+    """Any color at all (3/4-bit fallback)."""
+    if os.environ.get("NO_COLOR"):
+        return False
+    if os.environ.get("TERM", "").lower() == "dumb":
+        return False
+    if os.environ.get("SIBYL_FORCE_COLOR") == "1":
+        return True
+    return sys.stdout.isatty()
+
+
+_TC = supports_truecolor()
+_C  = supports_color()
+RESET = "\033[0m" if _C else ""
+
+
+def rgb(r: int, g: int, b: int) -> str:
+    """24-bit foreground escape (no-op if color disabled)."""
+    if not _TC:
+        return ""
+    return f"\033[38;2;{r};{g};{b}m"
+
+
+def rgb_bg(r: int, g: int, b: int) -> str:
+    if not _TC:
+        return ""
+    return f"\033[48;2;{r};{g};{b}m"
+
+
+def color(text: str, c: tuple[int, int, int]) -> str:
+    if not _TC:
+        return text
+    return f"{rgb(*c)}{text}{RESET}"
+
+
+# ─── Gradient · char-by-char RGB interpolation ────────────────────────
+
+def _interp(a: int, b: int, t: float) -> int:
+    return round(a + (b - a) * t)
+
+
+def gradient(text: str, *stops: tuple[int, int, int]) -> str:
+    """Color a string with a gradient across N stops, one char at a time.
+
+    Plain-text fallback: returns the input unchanged when color is off.
+    Whitespace is preserved (uncolored to keep terminals consistent).
+    """
+    if not _TC or len(stops) < 2 or not text:
+        return text
+    out = []
+    chars = list(text)
+    # Distribute char index across stop segments
+    n = max(1, len(chars) - 1)
+    segs = len(stops) - 1
+    for i, ch in enumerate(chars):
+        if ch == " ":
+            out.append(ch)
+            continue
+        seg_f = (i / n) * segs
+        seg_i = min(int(seg_f), segs - 1)
+        t = seg_f - seg_i
+        a = stops[seg_i]
+        b = stops[seg_i + 1]
+        r = _interp(a[0], b[0], t)
+        g = _interp(a[1], b[1], t)
+        bb = _interp(a[2], b[2], t)
+        out.append(f"\033[38;2;{r};{g};{bb}m{ch}")
+    return "".join(out) + RESET
+
+
+def gradient_gold(text: str) -> str:
+    """Pale-gold → deep-ochre flow. The brand's headline gradient."""
+    return gradient(text, ACCENT_PALE, ACCENT_GOLD, ACCENT)
+
+
+def gradient_jade(text: str) -> str:
+    """Pulse → jade. Used for success states + live indicators."""
+    return gradient(text, PULSE, JADE)
+
+
+# ─── Style primitives ─────────────────────────────────────────────────
+
+def dim(s: str) -> str:
+    return color(s, INK_FAINT)
+
+
+def muted(s: str) -> str:
+    return color(s, INK_MUTE)
+
+
+def soft(s: str) -> str:
+    return color(s, INK_SOFT)
+
+
+def ink(s: str) -> str:
+    return color(s, INK)
+
+
+def ok(s: str) -> str:
+    return color(s, PULSE)
+
+
+def warn(s: str) -> str:
+    return color(s, ACCENT_WARM)
+
+
+def err(s: str) -> str:
+    return color(s, ERROR)
+
+
+def accent(s: str) -> str:
+    return color(s, ACCENT)
+
+
+def bold(s: str) -> str:
+    if not _C:
+        return s
+    return f"\033[1m{s}{RESET}"
+
+
+# ─── Composite primitives ─────────────────────────────────────────────
+
+def eyebrow(label: str) -> str:
+    """Uppercase letter-spaced ochre label. Editorial section marker."""
+    spaced = " ".join(label.upper())
+    return color(spaced, ACCENT)
+
+
+def divider(width: int = 60, *, glyph: str = "─") -> str:
+    """Creme-paper rule line."""
+    return color(glyph * width, RULE)
+
+
+def section_header(name: str, *, subtitle: str | None = None, width: int = 60) -> str:
+    """The standard subcommand opener.
+
+       ─ <name> ────────────────────────────────────────
+       <subtitle, dim>
+    """
+    name_part = f" {gradient_gold(name)} "
+    # Stripped-color length for visible width calc
+    visible_name_len = len(f" {name} ")
+    rule_left = "─"
+    rule_right = "─" * max(3, width - 1 - visible_name_len)
+    head = color(rule_left, RULE) + name_part + color(rule_right, RULE)
+    if subtitle:
+        return head + "\n" + dim(subtitle)
+    return head
+
+
+def chip(text: str, *, palette: str = "accent") -> str:
+    """Compact inline label · [text]."""
+    palettes = {
+        "accent": ACCENT,
+        "jade":   PULSE,
+        "warn":   ACCENT_WARM,
+        "error":  ERROR,
+        "mute":   INK_MUTE,
+    }
+    c = palettes.get(palette, ACCENT)
+    return color(f"[{text}]", c)
+
+
+def kv(label: str, value: str, *, label_width: int = 16, value_color: str = "ink") -> str:
+    """One left-aligned label / value row.
+
+    Used across status / whoami / devices for the LOCAL / SERVER blocks.
+    """
+    palettes = {
+        "ink": INK, "soft": INK_SOFT, "mute": INK_MUTE, "faint": INK_FAINT,
+        "accent": ACCENT, "ok": PULSE, "warn": ACCENT_WARM, "err": ERROR,
+    }
+    val_color = palettes.get(value_color, INK_SOFT)
+    return f"  {color(label.ljust(label_width), INK_FAINT)} {color(value, val_color)}"
+
+
+def block_title(text: str) -> str:
+    """Sub-section title within a command output. Like 'LOCAL' or 'SERVER'."""
+    return "\n" + eyebrow(text)
+
+
+def success_line(text: str) -> str:
+    """Single-line success marker with gradient + glyph."""
+    return f"  {ok(GLYPH_OK)} {gradient_jade(text)}"
+
+
+def warn_line(text: str) -> str:
+    return f"  {warn(GLYPH_WARN)} {warn(text)}"
+
+
+def err_line(text: str) -> str:
+    return f"  {err(GLYPH_ERR)} {err(text)}"
+
+
+def hr_caption(caption: str, *, width: int = 60) -> str:
+    """Caption line under a divider — small, muted, centered."""
+    pad = max(0, (width - len(caption)) // 2)
+    return " " * pad + dim(caption)
+
+
+def footer_credits(*, width: int = 60) -> str:
+    """Bottom-of-output line. Used at end of long outputs."""
+    return color("─" * width, RULE) + "\n" + dim("  sibyl labs · memory you can hold in your hand")

sibyl-memory-cli/src/sibyl_memory_cli/_banner.py

@@ -0,0 +1,123 @@
+"""ASCII banner for sibyl-memory-cli.
+
+Prints the SIBYL wordmark in ANSI Shadow boxchars with a 24-bit truecolor
+vertical gradient flowing from cream/white at the top through warm gold
+to deep ochre at the bottom — aligned with the lab visual identity per
+the operator's brand-discipline rule (creme palette, deep-ochre accent).
+
+Gracefully degrades:
+  - NO_COLOR env var set       → plain text fallback
+  - stdout is not a TTY        → plain text fallback (or skip entirely)
+  - TERM=dumb                  → plain text fallback
+
+Truecolor support is detected via $COLORTERM (truecolor / 24bit) — most
+modern terminals (iTerm2, Alacritty, Kitty, wezterm, Windows Terminal,
+modern xterm builds, Ghostty) advertise it. Falls back to 256-color
+gradient when not available.
+"""
+from __future__ import annotations
+
+import os
+import sys
+
+# ANSI Shadow rendering of "SIBYL" — 6 rows, 41 cols. Each row gets its
+# own gradient color (top = pale cream/white, bottom = deep ochre).
+_LINES = (
+    "███████╗██╗██████╗ ██╗   ██╗██╗     ",
+    "██╔════╝██║██╔══██╗╚██╗ ██╔╝██║     ",
+    "███████╗██║██████╔╝ ╚████╔╝ ██║     ",
+    "╚════██║██║██╔══██╗  ╚██╔╝  ██║     ",
+    "███████║██║██████╔╝   ██║   ███████╗",
+    "╚══════╝╚═╝╚═════╝    ╚═╝   ╚══════╝",
+)
+
+# Vertical gradient · cream → gold → deep ochre. One RGB tuple per row.
+# Tuned against the SIBYL palette: --paper #f5f1e6 (top blend),
+# --accent #8a6a2a (mid-bottom), with extra highlight + shadow stops
+# to give the wordmark visible dimension.
+_GRADIENT = (
+    (253, 251, 245),   # almost white, slight cream      (top highlight)
+    (244, 229, 184),   # pale gold                       (upper)
+    (224, 194, 119),   # mid gold                        (upper-mid)
+    (184, 146,  73),   # rich ochre gold                 (mid)
+    (138, 106,  42),   # deep ochre · brand --accent     (lower)
+    (106,  79,  31),   # deepest                         (bottom shadow)
+)
+
+_TAGLINE = "memory you can hold in your hand"
+_ATTRIBUTION = "a Sibyl Labs LLC Product. Agentic Infrastructure and Memory Products"
+
+
+def _supports_truecolor() -> bool:
+    """Detect 24-bit color support. Conservative — fall back gracefully."""
+    if os.environ.get("NO_COLOR"):
+        return False
+    if os.environ.get("TERM", "").lower() == "dumb":
+        return False
+    if not sys.stdout.isatty():
+        return False
+    colorterm = os.environ.get("COLORTERM", "").lower()
+    if "truecolor" in colorterm or "24bit" in colorterm:
+        return True
+    # Many modern terminals don't set COLORTERM but do support truecolor.
+    # Recognize the well-behaved emitters.
+    term_program = os.environ.get("TERM_PROGRAM", "").lower()
+    if term_program in {"iterm.app", "wezterm", "ghostty", "vscode", "tabby"}:
+        return True
+    term = os.environ.get("TERM", "").lower()
+    if any(k in term for k in ("256color", "kitty", "alacritty", "xterm-direct")):
+        return True
+    return False
+
+
+def _color_supported() -> bool:
+    """Plain ANSI color (3/4-bit). Stricter than truecolor."""
+    if os.environ.get("NO_COLOR"):
+        return False
+    if os.environ.get("TERM", "").lower() == "dumb":
+        return False
+    return sys.stdout.isatty()
+
+
+def _rgb(r: int, g: int, b: int) -> str:
+    return f"\033[38;2;{r};{g};{b}m"
+
+
+_RESET = "\033[0m"
+
+
+def render_banner(*, force_color: bool | None = None) -> str:
+    """Return the banner as a string ready to print.
+
+    Args:
+        force_color: Override auto-detection. None = auto, True = force
+            truecolor, False = force plain text. Useful for testing.
+    """
+    use_truecolor = force_color if force_color is not None else _supports_truecolor()
+
+    if not use_truecolor:
+        # Plain text — still visually clean, just no color.
+        body = "\n".join("  " + line for line in _LINES)
+        tagline = f"\n  {_TAGLINE}"
+        attribution = f"\n  {_ATTRIBUTION}\n"
+        return body + tagline + attribution
+
+    # Colored — apply per-row gradient.
+    colored_lines = []
+    for line, (r, g, b) in zip(_LINES, _GRADIENT):
+        colored_lines.append(f"  {_rgb(r, g, b)}{line}{_RESET}")
+
+    body = "\n".join(colored_lines)
+    # Tagline in the deepest gold — present, but not competing with the wordmark.
+    r, g, b = _GRADIENT[-1]
+    tagline = f"\n  {_rgb(r, g, b)}{_TAGLINE}{_RESET}"
+    # Attribution dimmer still — a half-step below the tagline so the hierarchy
+    # reads SIBYL > tagline > attribution at a glance. ANSI dim (\033[2m) gives
+    # ~55% perceived opacity across the supported terminals.
+    attribution = f"\n  \033[2m{_rgb(r, g, b)}{_ATTRIBUTION}{_RESET}\n"
+    return body + tagline + attribution
+
+
+def print_banner(*, force_color: bool | None = None) -> None:
+    """Print the banner. Safe to call unconditionally; honors NO_COLOR + TTY checks."""
+    print(render_banner(force_color=force_color))

sibyl-memory-cli/src/sibyl_memory_cli/cli.py

@@ -0,0 +1,880 @@
+"""`sibyl` command-line interface.
+
+Stdlib only. The CLI is a thin wrapper around HTTP calls to
+https://api.sibyllabs.org/api/plugin/* and the local SibylMemoryProvider.
+
+Design pillars:
+  - Zero non-stdlib deps in this file. urllib is enough.
+  - Credentials are written atomically at mode 0600, set at file-creation
+    time via O_CREAT|O_EXCL|O_NOFOLLOW (no chmod-after-write race).
+  - The URL parameter handed to the browser is an opaque session identifier,
+    not the long-lived bearer (audit SEC-1 — server-side pairing handoff
+    issues a separate bearer at activation completion if available).
+  - session_token is never printed in full — display short slice only.
+  - Polling has explicit timeouts; no infinite loops.
+  - Every command exits with a clear status code (0 ok, 1 user error, 2 server error).
+"""
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+import secrets
+import sys
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+import uuid
+import webbrowser
+from pathlib import Path
+from typing import Any
+
+
+def _client_version() -> str:
+    """Return the installed package version from metadata, never hardcoded."""
+    try:
+        from importlib.metadata import PackageNotFoundError, version as _v
+        try:
+            return _v("sibyl-memory-cli")
+        except PackageNotFoundError:
+            return "0.0.0+source"
+    except Exception:
+        return "0.0.0+source"
+
+# ---- Defaults ----------------------------------------------------------
+
+API_BASE = os.environ.get("SIBYL_API_BASE", "https://api.sibyllabs.org")
+ACTIVATE_BASE = os.environ.get("SIBYL_ACTIVATE_BASE", "https://sibyllabs.org/plugin/activate")
+UPGRADE_BASE = os.environ.get("SIBYL_UPGRADE_BASE", "https://sibyllabs.org/plugin/upgrade")
+
+DEFAULT_CRED_PATH = Path("~/.sibyl-memory/credentials.json").expanduser()
+DEFAULT_DB_PATH = Path("~/.sibyl-memory/memory.db").expanduser()
+DEFAULT_TIER_CACHE_PATH = Path("~/.sibyl-memory/tier_cache.json").expanduser()
+
+POLL_INTERVAL_SEC = 3
+INIT_TIMEOUT_SEC = 10 * 60      # 10 minutes for /init activation
+UPGRADE_TIMEOUT_SEC = 15 * 60   # 15 minutes for upgrade — wallet ux can be slow
+
+# ---- Color / output ----------------------------------------------------
+
+from . import _aesthetic as a
+
+_NO_COLOR = bool(os.environ.get("NO_COLOR")) or not sys.stdout.isatty()
+
+
+def c(code: str, s: str) -> str:
+    if _NO_COLOR:
+        return s
+    return f"\033[{code}m{s}\033[0m"
+
+
+def dim(s: str) -> str: return c("2", s)
+def bold(s: str) -> str: return c("1", s)
+def green(s: str) -> str: return c("32", s)
+def yellow(s: str) -> str: return c("33", s)
+def red(s: str) -> str: return c("31", s)
+def cyan(s: str) -> str: return c("36", s)
+
+
+def _detect_os_family() -> str | None:
+    p = sys.platform
+    if p == "darwin": return "macos"
+    if p.startswith("linux"): return "linux"
+    if p.startswith("win"): return "windows"
+    return None
+
+
+def short(token: str | None) -> str:
+    if not token:
+        return "—"
+    if len(token) <= 12:
+        return token
+    return f"{token[:8]}…{token[-4:]}"
+
+
+def print_status(label: str, value: str) -> None:
+    print(f"  {dim(label.ljust(18))} {value}")
+
+
+# ---- HTTP --------------------------------------------------------------
+
+class HttpError(Exception):
+    def __init__(self, status: int, body: Any, url: str) -> None:
+        super().__init__(f"HTTP {status} for {url}: {body}")
+        self.status = status
+        self.body = body
+        self.url = url
+
+
+def http_request(  # noqa: D401
+    method: str,
+    path: str,
+    *,
+    body: dict | None = None,
+    timeout: float = 15.0,
+    headers: dict | None = None,
+) -> dict:
+    """Single source of truth for HTTP calls. Returns parsed JSON or raises HttpError."""
+    url = f"{API_BASE}{path}"
+    data = None
+    full_headers = {"Accept": "application/json", "User-Agent": f"sibyl-memory-cli/{_client_version()}"}
+    if body is not None:
+        data = json.dumps(body).encode("utf-8")
+        full_headers["Content-Type"] = "application/json"
+    if headers:
+        full_headers.update(headers)
+    req = urllib.request.Request(url, data=data, method=method, headers=full_headers)
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            return json.loads(resp.read().decode("utf-8"))
+    except urllib.error.HTTPError as e:
+        try:
+            err_body = json.loads(e.read().decode("utf-8"))
+        except Exception:
+            err_body = {"error": "unparseable response body"}
+        raise HttpError(e.code, err_body, url) from None
+    except urllib.error.URLError as e:
+        raise HttpError(0, {"error": str(e.reason)}, url) from None
+
+
+# ---- Credentials I/O ---------------------------------------------------
+
+def write_credentials_atomic(creds: dict, path: Path = DEFAULT_CRED_PATH) -> Path:
+    """Write credentials.json atomically at mode 0600.
+
+    v0.1.2 hardening (audit SEC-2): mode 0600 is set by the kernel at
+    file-creation time via O_CREAT|O_EXCL|O_NOFOLLOW. Previously used
+    write_text() followed by os.chmod(), leaving a world-readable window
+    between syscalls every credential save.
+    """
+    path = path.expanduser()
+    path.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
+    data = json.dumps(creds, indent=2).encode("utf-8")
+    tmp = path.with_suffix(path.suffix + ".tmp")
+    # Clean any leftover .tmp from a crashed prior write so O_EXCL can succeed.
+    try:
+        os.unlink(tmp)
+    except FileNotFoundError:
+        pass
+    flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL
+    if hasattr(os, "O_NOFOLLOW"):
+        flags |= os.O_NOFOLLOW
+    fd = os.open(str(tmp), flags, 0o600)
+    try:
+        os.write(fd, data)
+        os.fsync(fd)
+    finally:
+        os.close(fd)
+    os.replace(str(tmp), str(path))
+    return path
+
+
+def read_credentials(path: Path = DEFAULT_CRED_PATH) -> dict | None:
+    """Read credentials.json.
+
+    v0.1.2 hardening (audit SEC-11): refuses to follow symlinks.
+    Returns None if the file is a symlink or doesn't exist."""
+    path = path.expanduser()
+    if not path.exists():
+        return None
+    if path.is_symlink():
+        return None
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def invalidate_tier_cache(path: Path = DEFAULT_TIER_CACHE_PATH) -> None:
+    """Drop the local tier cache so the next write refreshes against the server."""
+    path = path.expanduser()
+    if path.exists():
+        path.unlink()
+
+
+# ---- `sibyl init` ------------------------------------------------------
+
+def _gen_pairing_code() -> str:
+    """6-digit cryptographic pairing code. Uniform across 000000-999999."""
+    return f"{secrets.randbelow(1_000_000):06d}"
+
+
+def _hash_pairing_code(code: str, session: str) -> str:
+    return hashlib.sha256(f"{code}:{session}".encode("utf-8")).hexdigest()
+
+
+def cmd_init(args: argparse.Namespace) -> int:
+    """Activation flow. Generate session UUID + pairing code, register with
+    server, open activation page in browser, poll /check until bound.
+
+    The pairing code is printed in the terminal. If the user picks the
+    email path in the browser, they type both their email and this code.
+    No external email service is required."""
+    # Brand moment — gold/white gradient SIBYL wordmark.
+    # Honors NO_COLOR + TTY detection automatically; safe to always call.
+    from ._banner import print_banner
+    print_banner()
+
+    cred_path = Path(args.credentials).expanduser()
+    if cred_path.exists() and not args.force:
+        existing = read_credentials(cred_path) or {}
+        print(a.section_header("already activated", subtitle="use --force to re-activate"))
+        print()
+        print(a.kv("Account", short(existing.get("account_id"))))
+        print(a.kv("Tier", (existing.get("tier") or "free").upper(), value_color="accent"))
+        print(a.kv("Credentials", str(cred_path)))
+        print()
+        return 0
+
+    # SEC-1 mitigation (v0.1.2): the URL parameter is an opaque pairing
+    # session identifier, NOT the long-lived bearer used by /access and
+    # /check-write. The CLI generates it locally and the server treats
+    # it as the activation rendezvous key only. The persistent bearer
+    # is issued by the server in the /check response (`bearer_token`
+    # field) after activation completes. Servers running pre-SEC-1
+    # firmware that echo the URL identifier as the bearer still work —
+    # we use whichever the server returns in the bound credentials.
+    session_id = str(uuid.uuid4())
+    pairing_code = _gen_pairing_code()
+    code_hash = _hash_pairing_code(pairing_code, session_id)
+    activate_url = f"{ACTIVATE_BASE}?session={session_id}"
+
+    # Pre-register the session + pairing code hash with the server.
+    # The code itself never leaves the user's machine until they type it
+    # into the browser.
+    try:
+        http_request(
+            "POST",
+            "/api/plugin/session-init",
+            body={
+                "session": session_id,
+                "pairing_code_hash": code_hash,
+                "env": {
+                    "os_family": _detect_os_family(),
+                    "install_method": "cli",
+                    "client_version": _client_version(),
+                },
+            },
+            timeout=10.0,
+        )
+    except HttpError as e:
+        # Non-fatal: SIWE path doesn't need the pairing code. If session-init
+        # fails the user can still complete SIWE. Surface the warning.
+        print(yellow(f"Warning: session-init failed ({e.status}). Wallet path still works; email path may not."))
+
+    print()
+    print(a.section_header("activation", subtitle="three paths · pick whichever fits your device"))
+    print()
+    print(a.kv("Session", short(session_id)))
+    formatted_code = pairing_code[:3] + " " + pairing_code[3:]
+    print(a.kv("Code", a.gradient_gold(formatted_code), value_color="accent")
+          + "  " + a.dim("(use this in the email panel)"))
+    print(a.kv("Opening", activate_url))
+    print()
+    print(a.dim("  desktop wallet · email + code · or send USDC from any mobile wallet"))
+    print(a.dim("  this terminal will pick up automatically when you bind."))
+    print()
+
+    try:
+        webbrowser.open(activate_url, new=2)
+    except Exception:
+        pass
+
+    # Poll /api/plugin/check
+    deadline = time.time() + INIT_TIMEOUT_SEC
+    last_status = ""
+    spinner = "⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏"
+    spin_i = 0
+
+    while time.time() < deadline:
+        try:
+            resp = http_request("GET", f"/api/plugin/check?session={urllib.parse.quote(session_id)}", timeout=10.0)
+        except HttpError as e:
+            if e.status in (404, 503, 0):
+                # Session not yet created server-side, or transient — keep polling
+                pass
+            else:
+                print(red(f"\nUnexpected error: {e.body}"))
+                return 2
+            resp = {"bound": False}
+
+        if resp.get("bound") and resp.get("credentials"):
+            creds = resp["credentials"]
+            # SEC-1: prefer the server-issued bearer_token (post-fix) over
+            # echoing the URL pairing-session id. Servers running pre-SEC-1
+            # firmware echo `session_token` back as the bearer — we use
+            # whichever the server returns. The CLI's session_id (URL
+            # identifier) is the rendezvous key, not the persistent bearer.
+            bearer = creds.get("bearer_token") or creds.get("session_token")
+            if not bearer:
+                # Fallback: pre-SEC-1 server flow where neither field is
+                # echoed back — inject the pairing session id so subsequent
+                # /access and /check-write calls have something to send.
+                bearer = session_id
+            # Sanity check on echoed session_token (pre-SEC-1 flow only)
+            if creds.get("session_token") and creds["session_token"] != session_id \
+                    and not creds.get("bearer_token"):
+                print(red("\nSession token mismatch — refusing to write credentials."))
+                return 2
+            creds["session_token"] = bearer
+            path = write_credentials_atomic(creds, cred_path)
+            print(f"\r{' ' * 80}\r", end="")  # clear spinner line
+            print()
+            print(a.success_line("Activated."))
+            print()
+            print(a.kv("Account", short(creds.get("account_id"))))
+            print(a.kv("Tier", (creds.get("tier") or "free").upper(), value_color="accent"))
+            print(a.kv("Wallet", creds.get("wallet") or "—"))
+            print(a.kv("Email", creds.get("email") or "—"))
+            print(a.kv("Credentials", str(path)))
+            print()
+            print(a.section_header("wire it into your agent"))
+            print()
+            print(a.dim("  hermes:"))
+            print(a.dim("    sibyl-memory-hermes install-plugin"))
+            print(a.dim("    # then edit ~/.hermes/config.yaml:"))
+            print(a.dim("    #   memory:"))
+            print(a.dim("    #     provider: sibyl"))
+            print()
+            print(a.dim("  claude code / codex / cursor / continue (MCP):"))
+            print(a.dim("    pip install sibyl-memory-mcp"))
+            print()
+            print(a.dim("  python orchestration (langchain / llamaindex / custom):"))
+            print(a.dim("    from sibyl_memory_hermes import SibylMemoryProvider"))
+            print(a.dim("    provider = SibylMemoryProvider()"))
+            print()
+            return 0
+
+        # Spinner tick
+        spin_i = (spin_i + 1) % len(spinner)
+        remaining = int(deadline - time.time())
+        spin_glyph = a.color(spinner[spin_i], a.PULSE)
+        status = f"\r  {spin_glyph} {a.dim('watching the network for your bind')} … {a.dim(f'{remaining // 60}:{remaining % 60:02d} left')}"
+        if status != last_status:
+            sys.stdout.write(status)
+            sys.stdout.flush()
+            last_status = status
+        time.sleep(POLL_INTERVAL_SEC)
+
+    print()
+    print(a.err_line("Activation timed out."))
+    print(a.dim("  Re-run `sibyl init` to try again."))
+    return 1
+
+
+# ---- `sibyl upgrade` ---------------------------------------------------
+
+def cmd_upgrade(args: argparse.Namespace) -> int:
+    """Upgrade flow. Read existing creds → open upgrade page → poll /access until tier flips."""
+    creds = read_credentials(Path(args.credentials).expanduser())
+    if not creds:
+        print(a.err_line("Not activated."))
+        print(a.dim("  Run `sibyl init` first."))
+        return 1
+
+    account_id = creds.get("account_id")
+    session_token = creds.get("session_token")
+    current_tier = (creds.get("tier") or "free").lower()
+
+    if not account_id or not session_token:
+        print(a.err_line("credentials.json is missing account_id or session_token."))
+        print(a.dim("  Re-run `sibyl init`."))
+        return 1
+
+    upgrade_url = f"{UPGRADE_BASE}?session={session_token}"
+
+    print()
+    print(a.section_header("upgrade", subtitle="lift the 2 MB free-tier cap"))
+    print()
+    print(a.kv("Account", short(account_id)))
+    print(a.kv("Current tier", current_tier.upper(), value_color="accent"))
+    print(a.kv("Opening", upgrade_url))
+    print()
+    print(a.dim("  two paths in the browser:"))
+    print(a.dim("    1. stake $SIBYL on Base (free unlimited if you qualify)"))
+    print(a.dim("    2. subscribe in USDC (monthly / quarterly / annual)"))
+    print()
+
+    try:
+        webbrowser.open(upgrade_url, new=2)
+    except Exception:
+        pass
+
+    # Poll /api/plugin/access until tier changes
+    deadline = time.time() + UPGRADE_TIMEOUT_SEC
+    last_status = ""
+    spinner = "⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏"
+    spin_i = 0
+
+    while time.time() < deadline:
+        try:
+            resp = http_request(
+                "POST",
+                "/api/plugin/access",
+                body={"account_id": account_id, "session_token": session_token},
+                timeout=10.0,
+            )
+        except HttpError as e:
+            if e.status == 401:
+                print(red("\nSession expired. Re-run `sibyl init`."))
+                return 1
+            # Transient — keep polling
+            resp = {}
+
+        new_tier = (resp.get("tier") or current_tier).lower()
+        source = resp.get("source")
+
+        if new_tier != current_tier and source in ("subscription", "staker"):
+            # Tier changed. Refresh credentials.
+            creds["tier"] = new_tier
+            if resp.get("staker") and resp["staker"].get("wallet"):
+                creds["wallet"] = resp["staker"]["wallet"]
+            write_credentials_atomic(creds, Path(args.credentials).expanduser())
+            invalidate_tier_cache()
+
+            print(f"\r{' ' * 80}\r", end="")
+            print()
+            print(a.success_line(f"Upgraded to {new_tier.upper()} via {source}."))
+            print()
+            print(a.kv("Source", source))
+            if resp.get("expires_at"):
+                print(a.kv("Expires", resp["expires_at"]))
+            if resp.get("cap_bytes") is None:
+                print(a.kv("Storage cap", "unlimited", value_color="ok"))
+            else:
+                print(a.kv("Storage cap", f"{resp['cap_bytes']:,} bytes"))
+            if resp.get("staker"):
+                s = resp["staker"]
+                print(a.kv("Wallet", s.get("wallet", "—")))
+                print(a.kv("$SIBYL held", str(s.get("total_sibyl", "—"))))
+            print()
+            print(a.dim("  local tier cache cleared. your next write will sync the new tier."))
+            return 0
+
+        spin_i = (spin_i + 1) % len(spinner)
+        remaining = int(deadline - time.time())
+        spin_glyph = a.color(spinner[spin_i], a.PULSE)
+        tier_glyph = a.color(current_tier.upper(), a.ACCENT)
+        status = f"\r  {spin_glyph} {a.dim('waiting for browser upgrade')} · current: {tier_glyph}  {a.dim(f'{remaining // 60}:{remaining % 60:02d} left')}"
+        if status != last_status:
+            sys.stdout.write(status)
+            sys.stdout.flush()
+            last_status = status
+        time.sleep(POLL_INTERVAL_SEC)
+
+    print()
+    print(a.err_line("Upgrade timed out. Tier unchanged."))
+    print(a.dim("  Re-run `sibyl upgrade` to retry."))
+    return 1
+
+
+# ---- `sibyl status` ----------------------------------------------------
+
+def cmd_status(args: argparse.Namespace) -> int:
+    """Show local + server-side state without modifying anything.
+
+    LIGHT treatment: utilitarian dashboard. No banner, no section header,
+    no chrome. Eyebrow labels + kv rows + ↓ status drift surfaces. Same
+    convention as `git status`, `ls -la`, `btop` panel bodies."""
+    cred_path = Path(args.credentials).expanduser()
+    creds = read_credentials(cred_path)
+
+    print()
+
+    if not creds:
+        print(a.warn_line("Not activated."))
+        print(a.dim("  Run `sibyl init`."))
+        return 0
+
+    # Local view
+    print(a.eyebrow("local"))
+    print(a.kv("Credentials", str(cred_path)))
+    print(a.kv("Account", short(creds.get("account_id"))))
+    print(a.kv("Tier", (creds.get("tier") or "free").upper(), value_color="accent"))
+    print(a.kv("Wallet", creds.get("wallet") or "—"))
+    print(a.kv("Email", creds.get("email") or "—"))
+    print(a.kv("Issued", creds.get("issued_at") or "—"))
+
+    db_path = Path(args.db).expanduser()
+    if db_path.exists():
+        size = db_path.stat().st_size
+        pct = size / 2_097_152 * 100
+        size_label = f"{size:,} bytes ({size / (1024 * 1024):.2f} MB · {pct:.1f}% of free cap)"
+        size_color = "warn" if pct > 80 else "soft"
+        print(a.kv("DB path", str(db_path)))
+        print(a.kv("DB size", size_label, value_color=size_color))
+    else:
+        print(a.kv("DB path", f"{db_path} (not created)"))
+
+    tier_cache = Path(args.tier_cache).expanduser()
+    if tier_cache.exists():
+        cache = json.loads(tier_cache.read_text(encoding="utf-8"))
+        print(a.kv("Tier cache", f"{cache.get('tier','?')} (checked {cache.get('checked_at','?')[:19]})"))
+    else:
+        print(a.kv("Tier cache", "—"))
+
+    # Server view (only if account_id + session_token are present)
+    if creds.get("account_id") and creds.get("session_token"):
+        print()
+        print(a.eyebrow("server"))
+        try:
+            resp = http_request(
+                "POST",
+                "/api/plugin/access",
+                body={"account_id": creds["account_id"], "session_token": creds["session_token"]},
+                timeout=10.0,
+            )
+            print(a.kv("Tier", (resp.get("tier") or "free").upper(), value_color="accent"))
+            print(a.kv("Source", resp.get("source") or "—"))
+            print(a.kv("Cap bytes", "unlimited" if resp.get("cap_bytes") is None else f"{resp['cap_bytes']:,}"))
+            if resp.get("expires_at"):
+                print(a.kv("Expires", resp["expires_at"]))
+            if resp.get("staker"):
+                s = resp["staker"]
+                print(a.kv("$SIBYL held", str(s.get("total_sibyl", "—"))))
+                print(a.kv("Threshold", str(s.get("threshold_sibyl", "—"))))
+                print(a.kv("Qualified", "yes" if s.get("qualified") else "no",
+                           value_color="ok" if s.get("qualified") else "soft"))
+            # Detect server/local drift
+            srv_tier = (resp.get("tier") or "free").lower()
+            loc_tier = (creds.get("tier") or "free").lower()
+            if srv_tier != loc_tier:
+                print()
+                print(a.warn_line(f"Local tier ({loc_tier}) differs from server tier ({srv_tier})."))
+                print(a.dim("  Run `sibyl upgrade` to refresh, or `sibyl init --force` to re-activate."))
+        except HttpError as e:
+            print(a.kv("Tier", f"server error: {e.status}", value_color="err"))
+
+    print()
+    return 0
+
+
+# ---- `sibyl dashboard` (placeholder, today routes to status) -----------
+
+def cmd_dashboard(args: argparse.Namespace) -> int:
+    """Open the web account dashboard. In v0.1.0, the dashboard at
+    account.sibyllabs.org is not yet live (queued post-V1-ship per the
+    operator design memo). Until then, `sibyl dashboard` delegates to
+    `sibyl status` so the command surface exists from day one and users
+    who muscle-memory it get a real result.
+
+    When account.sibyllabs.org ships, this will flip to
+    `webbrowser.open(...)` with no UX disruption — same command, real
+    web dashboard."""
+    DASHBOARD_BASE = os.environ.get("SIBYL_DASHBOARD_BASE")
+    if DASHBOARD_BASE:
+        # If env var is set, open the web dashboard with the session token.
+        creds = read_credentials(Path(args.credentials).expanduser())
+        if creds and creds.get("session_token"):
+            url = f"{DASHBOARD_BASE}?session={creds['session_token']}"
+            print()
+            print(bold("Sibyl Memory Plugin · dashboard"))
+            print(f"  {dim('Opening:')}     {url}")
+            print()
+            try:
+                webbrowser.open(url, new=2)
+            except Exception:
+                pass
+            return 0
+    # Fall through: account.sibyllabs.org isn't live yet, run status instead.
+    return cmd_status(args)
+
+
+# ---- `sibyl whoami` ----------------------------------------------------
+
+def _mask_email(e: str | None) -> str:
+    if not e or "@" not in e:
+        return "—"
+    user, _, domain = e.partition("@")
+    if "." not in domain:
+        return f"{user[0]}***@{domain[0]}***"
+    name, _, tld = domain.rpartition(".")
+    return f"{user[0]}***@{name[0]}***.{tld}"
+
+
+def _mask_wallet(w: str | None) -> str:
+    if not w or not w.startswith("0x") or len(w) < 12:
+        return w or "—"
+    return f"{w[:6]}…{w[-4:]}"
+
+
+def cmd_whoami(args: argparse.Namespace) -> int:
+    """One-line account summary. Shows account_id + tier + linked email/wallet + this device.
+
+    LIGHT treatment: 4-line glance. No banner, no section header. Same shape
+    as `whoami` on unix, `gh auth status`, `aws sts get-caller-identity`."""
+    creds = read_credentials(Path(args.credentials).expanduser())
+    if not creds:
+        print(a.warn_line("Not activated."))
+        print(a.dim("  Run `sibyl init`."))
+        return 1
+
+    full = bool(getattr(args, "full", False))
+    acct = creds.get("account_id") or ""
+    tier = (creds.get("tier") or "free").upper()
+    email = creds.get("email") if full else _mask_email(creds.get("email"))
+    wallet = creds.get("wallet") if full else _mask_wallet(creds.get("wallet"))
+
+    print()
+    print(f"  {a.color('account', a.INK_FAINT)}  {a.bold(short(acct))}  {a.dim(a.GLYPH_DOT)}  {a.gradient_gold(tier)}")
+    print(f"  {a.color('wallet ', a.INK_FAINT)}  {a.color(wallet or '—', a.INK)}")
+    print(f"  {a.color('email  ', a.INK_FAINT)}  {a.color(email or '—', a.INK)}")
+    os_label = _detect_os_family() or "unknown"
+    device_line = f"sibyl-memory-cli/{_client_version()} {os_label}"
+    print(f"  {a.color('device ', a.INK_FAINT)}  {a.dim(device_line)}")
+    print()
+    return 0
+
+
+# ---- `sibyl devices` ---------------------------------------------------
+
+def cmd_devices(args: argparse.Namespace) -> int:
+    """List active bearer tokens (devices) for the account. Optional: revoke by index."""
+    creds = read_credentials(Path(args.credentials).expanduser())
+    if not creds:
+        print(a.err_line("Not activated."))
+        print(a.dim("  Run `sibyl init`."))
+        return 1
+    account_id = creds.get("account_id")
+    session_token = creds.get("session_token")
+    if not account_id or not session_token:
+        print(a.err_line("credentials.json missing account_id or session_token."))
+        print(a.dim("  Run `sibyl init`."))
+        return 1
+
+    sub = getattr(args, "sub", None)
+
+    # `sibyl devices revoke <index>` path
+    if sub == "revoke":
+        idx = getattr(args, "index", None)
+        if idx is None:
+            print(red("usage: sibyl devices revoke <index>"))
+            return 1
+        # List first to map index → bearer_id
+        try:
+            resp = http_request(
+                "GET",
+                f"/api/plugin/devices?account_id={urllib.parse.quote(account_id)}",
+                headers={"Authorization": f"Bearer {session_token}"},
+                timeout=10.0,
+            )
+        except HttpError as e:
+            print(red(f"server error: {e.status} {e.body}"))
+            return 2
+        devices = resp.get("devices", [])
+        try:
+            target = devices[idx]
+        except (IndexError, TypeError):
+            print(red(f"no device at index {idx}. Run `sibyl devices` to see indexes."))
+            return 1
+        if target.get("is_this_device"):
+            print(red("refusing to revoke your own device — that would lock you out. Run `sibyl logout` instead, then `sibyl init` on a fresh activation."))
+            return 1
+        try:
+            revoke_resp = http_request(
+                "POST",
+                "/api/plugin/devices",
+                body={"bearer_id": target["bearer_id"]},
+                headers={"Authorization": f"Bearer {session_token}"},
+                timeout=10.0,
+            )
+        except HttpError as e:
+            print(red(f"revoke failed: {e.status} {e.body}"))
+            return 2
+        print(green(f"✓ Revoked device {target.get('device_label') or target['bearer_id']}"))
+        return 0 if revoke_resp.get("revoked") else 1
+
+    # Default: list devices
+    try:
+        resp = http_request(
+            "GET",
+            f"/api/plugin/devices?account_id={urllib.parse.quote(account_id)}",
+            headers={"Authorization": f"Bearer {session_token}"},
+            timeout=10.0,
+        )
+    except HttpError as e:
+        if e.status == 401:
+            print(a.err_line("Session expired."))
+            print(a.dim("  Re-run `sibyl init`."))
+        else:
+            print(a.err_line(f"server error: {e.status} {e.body}"))
+        return 2
+
+    devices = resp.get("devices", [])
+    # LIGHT treatment: table-like dashboard. Eyebrow line with count + the rows. No banner.
+    print()
+    print(f"  {a.eyebrow('devices')}  {a.dim(f'· {len(devices)} active')}")
+    print()
+    if not devices:
+        print(a.dim("  no active devices"))
+        print()
+        return 0
+
+    for i, d in enumerate(devices):
+        is_this = d.get("is_this_device")
+        marker = a.ok("▶") if is_this else " "
+        label = d.get("device_label") or "(unlabeled)"
+        installed = d.get("install_method") or "—"
+        last_seen = d.get("last_seen_at", "")[:19].replace("T", " ")
+        idx_chip = a.chip(str(i), palette="jade" if is_this else "mute")
+        label_color = a.gradient_gold(label) if is_this else a.color(label, a.INK)
+        meta = f"{a.dim(installed)} {a.dim(a.GLYPH_DOT)} {a.dim('last seen ' + last_seen)}"
+        note = a.color("(this device)", a.PULSE) if is_this else a.dim(f"revoke: sibyl devices revoke {i}")
+        print(f"  {marker} {idx_chip} {label_color}  {meta}  {note}")
+    print()
+    return 0
+
+
+# ---- `sibyl logout` ----------------------------------------------------
+
+def cmd_logout(args: argparse.Namespace) -> int:
+    """Delete credentials.json + tier_cache.json. memory.db stays — that's your data."""
+    cred_path = Path(args.credentials).expanduser()
+    tier_cache = Path(args.tier_cache).expanduser()
+
+    deleted = []
+    if cred_path.exists():
+        cred_path.unlink()
+        deleted.append(str(cred_path))
+    if tier_cache.exists():
+        tier_cache.unlink()
+        deleted.append(str(tier_cache))
+
+    # LIGHT treatment: quick confirmation. No banner, no section header.
+    print()
+    if not deleted:
+        print(a.warn_line("Nothing to remove."))
+        print(a.dim("  Already logged out."))
+    else:
+        print(a.success_line("Logged out."))
+        for path in deleted:
+            print(f"  {a.dim('removed')} {a.color(path, a.INK)}")
+        print()
+        print(a.dim("  memory.db untouched. run `sibyl init` to activate a fresh account."))
+    print()
+    return 0
+
+
+# ---- `sibyl health` ----------------------------------------------------
+
+def cmd_health(args: argparse.Namespace) -> int:
+    """SibylMemoryProvider.health() — minimal self-check."""
+    try:
+        from sibyl_memory_hermes import SibylMemoryProvider
+    except ImportError:
+        print(a.err_line("sibyl-memory-hermes not installed."))
+        print(a.dim("  pip install sibyl-memory-hermes"))
+        return 1
+
+    # LIGHT treatment: verdict + details. No banner, no section header.
+    # Pattern: `pg_isready` / `redis-cli ping` / `gh auth status`.
+    print()
+    provider = SibylMemoryProvider(db_path=args.db)
+    h = provider.health()
+    ok_state = bool(h.get("ok"))
+    if ok_state:
+        print(a.success_line("All green."))
+    else:
+        print(a.err_line("Health check reports issues."))
+    print()
+    for k, v in h.items():
+        if k == "ok":
+            continue
+        val = str(v)
+        print(a.kv(k, val, value_color="ok" if v is True else ("soft" if v else "warn")))
+    print()
+    return 0 if ok_state else 1
+
+
+# ---- Dispatch ----------------------------------------------------------
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="sibyl",
+        description="Command-line interface for the Sibyl Memory Plugin.",
+    )
+    p.add_argument("--credentials", default=str(DEFAULT_CRED_PATH),
+                   help="Path to credentials.json (default: ~/.sibyl-memory/credentials.json)")
+    p.add_argument("--db", default=str(DEFAULT_DB_PATH),
+                   help="Path to memory.db (default: ~/.sibyl-memory/memory.db)")
+    p.add_argument("--tier-cache", default=str(DEFAULT_TIER_CACHE_PATH),
+                   help="Path to tier_cache.json (default: ~/.sibyl-memory/tier_cache.json)")
+
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    p_init = sub.add_parser("init", help="Activate the plugin in your browser")
+    p_init.add_argument("--force", action="store_true", help="Re-activate even if credentials.json exists")
+    p_init.set_defaults(func=cmd_init)
+
+    p_up = sub.add_parser("upgrade", help="Open the upgrade flow (stake or subscribe)")
+    p_up.set_defaults(func=cmd_upgrade)
+
+    p_st = sub.add_parser("status", help="Show local + server tier / DB stats")
+    p_st.set_defaults(func=cmd_status)
+
+    p_who = sub.add_parser("whoami", help="One-line account summary (masked by default)")
+    p_who.add_argument("--full", action="store_true", help="Show full email + wallet (no masking)")
+    p_who.set_defaults(func=cmd_whoami)
+
+    p_dev = sub.add_parser("devices", help="List devices (active bearer tokens) for the account")
+    dev_sub = p_dev.add_subparsers(dest="sub")
+    p_rev = dev_sub.add_parser("revoke", help="Revoke a device by index (run `sibyl devices` for indexes)")
+    p_rev.add_argument("index", type=int, help="Index from `sibyl devices` output")
+    p_dev.set_defaults(func=cmd_devices)
+    p_rev.set_defaults(func=cmd_devices)
+
+    p_dash = sub.add_parser("dashboard", help="Open the account dashboard (delegates to status until account.sibyllabs.org ships)")
+    p_dash.set_defaults(func=cmd_dashboard)
+
+    p_lo = sub.add_parser("logout", help="Remove local credentials (memory.db stays)")
+    p_lo.set_defaults(func=cmd_logout)
+
+    p_h = sub.add_parser("health", help="Run the provider self-check")
+    p_h.set_defaults(func=cmd_health)
+
+    # v0.1.4: one-command auto-detect-and-wire setup for any agent stack
+    from .setup import cmd_setup
+    p_setup = sub.add_parser(
+        "setup",
+        help="Auto-detect Hermes / Claude Code and wire SIBYL as the memory provider",
+    )
+    p_setup.add_argument(
+        "target", nargs="?", choices=list(["hermes", "claude-code"]),
+        help="Wire just this framework (default: detect all)",
+    )
+    p_setup.add_argument(
+        "--yes", "-y", action="store_true",
+        help="Skip prompts, accept defaults (still respects destructive-default-NO unless --force)",
+    )
+    p_setup.add_argument(
+        "--force", action="store_true",
+        help="Overwrite existing non-SIBYL memory provider configs",
+    )
+    p_setup.add_argument(
+        "--dry-run", action="store_true",
+        help="Print what would change without writing",
+    )
+    p_setup.add_argument(
+        "--hermes-home", default=None,
+        help="Override HERMES_HOME autodetection",
+    )
+    p_setup.add_argument(
+        "--claude-settings", default=None,
+        help="Override ~/.claude/settings.json autodetection",
+    )
+    p_setup.set_defaults(func=cmd_setup)
+
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        return args.func(args)
+    except KeyboardInterrupt:
+        print(red("\nInterrupted."))
+        return 130
+
+
+if __name__ == "__main__":
+    sys.exit(main())

sibyl-memory-cli/src/sibyl_memory_cli/setup.py

@@ -0,0 +1,493 @@
+"""`sibyl setup`: auto-detect agent frameworks and wire SIBYL as memory provider.
+
+Maximum-efficiency onboarding command. Single-command path for the user:
+
+    pip install sibyl-memory-cli
+    sibyl setup          # auto-detects Hermes + Claude Code, prompts per stack, wires
+
+Two wirers in v0.1.4:
+  - HermesWirer:     install-plugin + edit $HERMES_HOME/config.yaml (memory.provider)
+  - ClaudeCodeWirer: edit ~/.claude/settings.json (mcpServers.sibyl-memory)
+
+Each wirer follows the same protocol:
+  is_present()       -> bool          (filesystem + PATH detect)
+  current_state()    -> dict          (configured? wired-with-sibyl? current-value?)
+  wire(force, dry_run, prompt_fn) -> WireOutcome
+
+Destructive operations (overwriting an existing non-SIBYL config) default to NO
+on the prompt. Fresh adds default to YES. --force overrides destructive guards.
+--yes accepts all defaults (still respects the destructive-default-NO unless
+--force is also passed). --dry-run prints intent without writing.
+
+All config edits are atomic: backup to <file>.bak, write to <file>.tmp, rename.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import shutil
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Callable, Optional, Union
+
+# Color helpers re-imported from cli module via late binding to avoid circular dep.
+# When called via `sibyl setup` they resolve through the cli module's tty detection.
+def _color_fns():
+    from .cli import bold, cyan, dim, green, red, yellow
+    return bold, cyan, dim, green, red, yellow
+
+
+# ----------------------------------------------------------------------
+# WireOutcome
+# ----------------------------------------------------------------------
+
+@dataclass
+class WireOutcome:
+    """Result of a wirer.wire() call. Composable across multiple wirers."""
+    name: str
+    status: str          # 'wired' / 'already' / 'skipped' / 'dry-run' / 'error'
+    message: str
+    backup_path: Optional[Path] = None
+
+
+# ----------------------------------------------------------------------
+# Lazy YAML import. Hermes wirer needs it; Claude-only users do not.
+# ----------------------------------------------------------------------
+
+def _import_yaml():
+    try:
+        import yaml
+        return yaml
+    except ImportError:
+        return None
+
+
+# ----------------------------------------------------------------------
+# HermesWirer
+# ----------------------------------------------------------------------
+
+class HermesWirer:
+    name = "hermes"
+    display_name = "Hermes"
+    initial = "h"
+
+    def __init__(self, *, hermes_home: Optional[Union[str, Path]] = None):
+        self.hermes_home = (
+            Path(hermes_home).expanduser() if hermes_home
+            else self._auto_hermes_home()
+        )
+        self.config_path = self.hermes_home / "config.yaml"
+        self.plugin_dir = self.hermes_home / "plugins" / "sibyl"
+
+    @staticmethod
+    def _auto_hermes_home() -> Path:
+        env = os.environ.get("HERMES_HOME")
+        if env:
+            return Path(env).expanduser()
+        return Path.home() / ".hermes"
+
+    def is_present(self) -> bool:
+        # Present if HERMES_HOME exists OR `hermes` binary on PATH
+        if self.hermes_home.exists():
+            return True
+        if shutil.which("hermes"):
+            return True
+        return False
+
+    def current_state(self) -> dict:
+        config_exists = self.config_path.exists()
+        plugin_installed = (self.plugin_dir / "__init__.py").exists()
+        memory_provider: Optional[str] = None
+        if config_exists:
+            yaml = _import_yaml()
+            if yaml is not None:
+                try:
+                    raw = self.config_path.read_text(encoding="utf-8")
+                    cfg = yaml.safe_load(raw) or {}
+                    if isinstance(cfg, dict):
+                        mem = cfg.get("memory")
+                        if isinstance(mem, dict):
+                            memory_provider = mem.get("provider")
+                except Exception:
+                    pass
+        return {
+            "hermes_home": str(self.hermes_home),
+            "config_path": str(self.config_path),
+            "config_exists": config_exists,
+            "plugin_installed": plugin_installed,
+            "memory_provider": memory_provider,
+            "wired_with_sibyl": memory_provider == "sibyl",
+        }
+
+    def wire(self, *, force: bool = False, dry_run: bool = False,
+             prompt_fn: Optional[Callable[..., str]] = None) -> WireOutcome:
+        state = self.current_state()
+        yaml = _import_yaml()
+        if yaml is None:
+            return WireOutcome(
+                self.name, "error",
+                "PyYAML not installed. Run `pip install pyyaml` and retry.",
+            )
+
+        # 1. Install plugin if missing
+        if not state["plugin_installed"]:
+            if dry_run:
+                pass  # report at the end
+            else:
+                try:
+                    self._install_plugin()
+                except Exception as e:
+                    return WireOutcome(
+                        self.name, "error",
+                        f"install-plugin failed: {type(e).__name__}: {e}",
+                    )
+
+        # 2. Already wired? no-op
+        if state["wired_with_sibyl"] and state["plugin_installed"]:
+            return WireOutcome(
+                self.name, "already",
+                f"Hermes already has SIBYL as memory provider in {self.config_path}",
+            )
+
+        # 3. Existing non-SIBYL provider? confirm or refuse
+        if state["memory_provider"] and state["memory_provider"] != "sibyl" and not force:
+            if prompt_fn is None:
+                return WireOutcome(
+                    self.name, "skipped",
+                    f"Existing memory.provider '{state['memory_provider']}'. Use --force to overwrite.",
+                )
+            ans = prompt_fn(
+                f"Hermes currently uses '{state['memory_provider']}' as memory provider. Overwrite with SIBYL?",
+                default="N",
+            )
+            if ans != "y":
+                return WireOutcome(self.name, "skipped", "Memory provider overwrite declined.")
+
+        # 4. Dry-run report
+        if dry_run:
+            actions = []
+            if not state["plugin_installed"]:
+                actions.append(f"install plugin at {self.plugin_dir}")
+            actions.append(f"set memory.provider=sibyl in {self.config_path}")
+            return WireOutcome(self.name, "dry-run", "Would: " + "; ".join(actions))
+
+        # 5. Real write. Backup, then atomic rename.
+        backup = self._backup_config()
+        try:
+            self._write_config_with_sibyl(yaml)
+        except Exception as e:
+            return WireOutcome(
+                self.name, "error",
+                f"config write failed: {type(e).__name__}: {e}",
+                backup_path=backup,
+            )
+        return WireOutcome(
+            self.name, "wired",
+            f"Wired memory.provider=sibyl in {self.config_path}",
+            backup_path=backup,
+        )
+
+    def _install_plugin(self) -> None:
+        from sibyl_memory_hermes.install_plugin import install
+        install(hermes_home=str(self.hermes_home))
+
+    def _backup_config(self) -> Optional[Path]:
+        if not self.config_path.exists():
+            return None
+        backup = self.config_path.with_suffix(".yaml.bak")
+        shutil.copy2(self.config_path, backup)
+        return backup
+
+    def _write_config_with_sibyl(self, yaml) -> None:
+        cfg: dict = {}
+        if self.config_path.exists():
+            raw = self.config_path.read_text(encoding="utf-8")
+            loaded = yaml.safe_load(raw)
+            if isinstance(loaded, dict):
+                cfg = loaded
+        if not isinstance(cfg.get("memory"), dict):
+            cfg["memory"] = {}
+        cfg["memory"]["provider"] = "sibyl"
+        self.config_path.parent.mkdir(parents=True, exist_ok=True)
+        tmp = self.config_path.with_suffix(".yaml.tmp")
+        with open(tmp, "w", encoding="utf-8") as f:
+            yaml.safe_dump(cfg, f, sort_keys=False, default_flow_style=False)
+        os.replace(tmp, self.config_path)
+
+
+# ----------------------------------------------------------------------
+# ClaudeCodeWirer
+# ----------------------------------------------------------------------
+
+class ClaudeCodeWirer:
+    name = "claude-code"
+    display_name = "Claude Code"
+    initial = "c"
+
+    SIBYL_MCP_BLOCK = {"command": "sibyl-memory-mcp"}
+
+    def __init__(self, *, settings_path: Optional[Union[str, Path]] = None):
+        self.settings_path = (
+            Path(settings_path).expanduser() if settings_path
+            else Path.home() / ".claude" / "settings.json"
+        )
+
+    def is_present(self) -> bool:
+        if self.settings_path.exists():
+            return True
+        if shutil.which("claude"):
+            return True
+        return False
+
+    def current_state(self) -> dict:
+        settings_exists = self.settings_path.exists()
+        mcp_servers: dict = {}
+        sibyl_block: Optional[dict] = None
+        if settings_exists:
+            try:
+                cfg = json.loads(self.settings_path.read_text(encoding="utf-8"))
+                if isinstance(cfg, dict):
+                    raw_servers = cfg.get("mcpServers", {})
+                    if isinstance(raw_servers, dict):
+                        mcp_servers = raw_servers
+                        sibyl_block = mcp_servers.get("sibyl-memory")
+            except Exception:
+                pass
+        return {
+            "settings_path": str(self.settings_path),
+            "settings_exists": settings_exists,
+            "mcp_servers_count": len(mcp_servers),
+            "sibyl_mcp": sibyl_block,
+            "wired_with_sibyl": sibyl_block == self.SIBYL_MCP_BLOCK,
+        }
+
+    def wire(self, *, force: bool = False, dry_run: bool = False,
+             prompt_fn: Optional[Callable[..., str]] = None) -> WireOutcome:
+        state = self.current_state()
+
+        if state["wired_with_sibyl"]:
+            return WireOutcome(
+                self.name, "already",
+                f"Claude Code already has SIBYL Memory MCP server in {self.settings_path}",
+            )
+
+        if state["sibyl_mcp"] and not force:
+            if prompt_fn is None:
+                return WireOutcome(
+                    self.name, "skipped",
+                    "Existing sibyl-memory MCP entry differs. Use --force to overwrite.",
+                )
+            ans = prompt_fn(
+                "Claude Code has 'sibyl-memory' MCP entry but pointing elsewhere. Update?",
+                default="N",
+            )
+            if ans != "y":
+                return WireOutcome(self.name, "skipped", "MCP entry update declined.")
+
+        if dry_run:
+            verb = "update" if state["sibyl_mcp"] else "add"
+            return WireOutcome(
+                self.name, "dry-run",
+                f"Would {verb} mcpServers.sibyl-memory in {self.settings_path}",
+            )
+
+        backup = self._backup_settings()
+        try:
+            self._write_settings_with_sibyl()
+        except Exception as e:
+            return WireOutcome(
+                self.name, "error",
+                f"settings write failed: {type(e).__name__}: {e}",
+                backup_path=backup,
+            )
+        return WireOutcome(
+            self.name, "wired",
+            f"Added SIBYL Memory MCP server to {self.settings_path}",
+            backup_path=backup,
+        )
+
+    def _backup_settings(self) -> Optional[Path]:
+        if not self.settings_path.exists():
+            return None
+        backup = self.settings_path.with_suffix(".json.bak")
+        shutil.copy2(self.settings_path, backup)
+        return backup
+
+    def _write_settings_with_sibyl(self) -> None:
+        cfg: dict = {}
+        if self.settings_path.exists():
+            try:
+                loaded = json.loads(self.settings_path.read_text(encoding="utf-8"))
+                if isinstance(loaded, dict):
+                    cfg = loaded
+            except Exception:
+                cfg = {}
+        if not isinstance(cfg.get("mcpServers"), dict):
+            cfg["mcpServers"] = {}
+        cfg["mcpServers"]["sibyl-memory"] = self.SIBYL_MCP_BLOCK
+        self.settings_path.parent.mkdir(parents=True, exist_ok=True)
+        tmp = self.settings_path.with_suffix(".json.tmp")
+        tmp.write_text(json.dumps(cfg, indent=2) + "\n", encoding="utf-8")
+        os.replace(tmp, self.settings_path)
+
+
+# ----------------------------------------------------------------------
+# Registry + dispatch
+# ----------------------------------------------------------------------
+
+ALL_WIRERS: dict = {
+    "hermes": HermesWirer,
+    "claude-code": ClaudeCodeWirer,
+}
+
+
+def _interactive_prompt(question: str, *, default: str = "Y") -> str:
+    """Yes/no prompt. default 'Y' or 'N'. Returns 'y' or 'n'."""
+    default_label = "[Y/n]" if default.upper() == "Y" else "[y/N]"
+    try:
+        ans = input(f"{question} {default_label}: ").strip()
+    except EOFError:
+        return default.lower()
+    if not ans:
+        return default.lower()
+    return "y" if ans[:1].lower() == "y" else "n"
+
+
+def _accept_defaults_prompt(question: str, *, default: str = "Y") -> str:
+    """Non-interactive prompt. Returns the default. Used with --yes."""
+    return default.lower()
+
+
+def _wirer_kwargs(args: argparse.Namespace, name: str) -> dict:
+    kw: dict = {}
+    if name == "hermes" and getattr(args, "hermes_home", None):
+        kw["hermes_home"] = args.hermes_home
+    if name == "claude-code" and getattr(args, "claude_settings", None):
+        kw["settings_path"] = args.claude_settings
+    return kw
+
+
+def cmd_setup(args: argparse.Namespace) -> int:
+    """`sibyl setup` entry point. Auto-detect, then wire."""
+    bold, cyan, dim, green, red, yellow = _color_fns()
+
+    # Resolve target wirers
+    target = getattr(args, "target", None)
+    if target:
+        if target not in ALL_WIRERS:
+            print(red(f"Unknown setup target: {target}"))
+            print(f"Available: {', '.join(ALL_WIRERS)}")
+            return 1
+        wirers: dict = {target: ALL_WIRERS[target](**_wirer_kwargs(args, target))}
+        skip_present_check = True   # explicit target = wire it even if not detected on PATH
+    else:
+        wirers = {name: cls(**_wirer_kwargs(args, name)) for name, cls in ALL_WIRERS.items()}
+        skip_present_check = False
+
+    print()
+    print(bold("Sibyl Memory Plugin setup"))
+    print()
+
+    # Detection
+    if skip_present_check:
+        detected = wirers
+    else:
+        detected = {n: w for n, w in wirers.items() if w.is_present()}
+
+    if not detected:
+        print(yellow("No agent frameworks detected on this machine."))
+        print()
+        print(dim("Looked for:"))
+        for name, w in wirers.items():
+            st = w.current_state()
+            loc = st.get("hermes_home") or st.get("settings_path")
+            print(f"  {w.display_name}: {loc}")
+        print()
+        print(dim("To override detection, point setup at a custom path:"))
+        print(f"  {cyan('sibyl setup --hermes-home /custom/path')}")
+        print(f"  {cyan('sibyl setup --claude-settings /custom/settings.json')}")
+        print()
+        return 0
+
+    # Detection summary
+    print(dim("Detected:"))
+    for name, w in detected.items():
+        st = w.current_state()
+        loc = st.get("hermes_home") or st.get("settings_path")
+        print(f"  {w.display_name} at {loc}")
+    print()
+
+    # Multi-framework picker
+    selected = list(detected.keys())
+    if len(detected) > 1 and not args.yes:
+        choices = ", ".join(f"[{w.initial}]{w.display_name}" for w in detected.values())
+        ans = input(
+            f"Wire which? {choices}, [a]ll, [n]one (default: all): "
+        ).strip().lower()
+        if ans in ("n", "none"):
+            print(dim("Skipping all."))
+            print()
+            return 0
+        elif ans in ("", "a", "all"):
+            pass
+        else:
+            picked = [n for n, w in detected.items() if w.initial == ans[:1]]
+            if not picked:
+                print(red(f"No match for '{ans}'. Aborting."))
+                return 1
+            selected = picked
+
+    # Per-stack execution
+    outcomes: list = []
+    prompt_fn = _accept_defaults_prompt if args.yes else _interactive_prompt
+
+    for name in selected:
+        wirer = detected[name]
+        st = wirer.current_state()
+
+        # Pre-prompt for fresh adds (interactive only). Already-wired and
+        # existing-other-provider are handled inside wire() itself.
+        if (
+            not args.yes
+            and not st.get("wired_with_sibyl")
+            and not st.get("memory_provider")
+            and not st.get("sibyl_mcp")
+        ):
+            if name == "hermes":
+                q = f"Set SIBYL as default memory provider in {wirer.display_name}?"
+            else:
+                q = f"Add SIBYL Memory as an MCP server in {wirer.display_name}?"
+            ans = _interactive_prompt(q, default="Y")
+            if ans != "y":
+                outcomes.append(WireOutcome(name, "skipped", "Declined by user."))
+                continue
+
+        outcomes.append(
+            wirer.wire(force=args.force, dry_run=args.dry_run, prompt_fn=prompt_fn)
+        )
+
+    # Report
+    print()
+    any_wired = False
+    for o in outcomes:
+        marker = {
+            "wired": green("✓"),
+            "already": green("·"),
+            "skipped": yellow("·"),
+            "dry-run": cyan("→"),
+            "error": red("✗"),
+        }.get(o.status, "?")
+        print(f"  {marker} {o.name}: {o.message}")
+        if o.backup_path:
+            print(f"      {dim('backup at')} {o.backup_path}")
+        if o.status == "wired":
+            any_wired = True
+    print()
+
+    if any_wired:
+        print(green("Restart your agent(s) to load the new memory provider."))
+        print()
+
+    return 0 if all(o.status != "error" for o in outcomes) else 2

sibyl-memory-cli/tests/test_setup.py

@@ -0,0 +1,381 @@
+"""Tests for the v0.1.4 `sibyl setup` command.
+
+Covers:
+- Hermes wirer: fresh, existing-no-memory, existing-sibyl, existing-other-provider,
+  force-overwrite, dry-run, plugin-install side-effect.
+- Claude Code wirer: fresh-no-file, fresh-with-other-mcps, existing-sibyl,
+  existing-sibyl-mismatch, force-overwrite, dry-run.
+- Detection: is_present logic for both wirers.
+- Outcomes: WireOutcome status field correctness.
+- Atomic writes + backup files land at the expected paths.
+"""
+from __future__ import annotations
+
+import json
+import os
+import sys
+from pathlib import Path
+from unittest.mock import patch
+
+import pytest
+
+sys.path.insert(0, str(Path(__file__).parent.parent / "src"))
+
+from sibyl_memory_cli.setup import (  # noqa: E402
+    ALL_WIRERS,
+    ClaudeCodeWirer,
+    HermesWirer,
+    WireOutcome,
+    _accept_defaults_prompt,
+    _interactive_prompt,
+)
+
+
+# ----------------------------------------------------------------------
+# Helpers
+# ----------------------------------------------------------------------
+
+def _stub_install_plugin(hermes_home: str):
+    """Replacement for sibyl_memory_hermes.install_plugin.install — drops a fake
+    adapter file so the wirer sees plugin_installed=True afterwards."""
+    plugin_dir = Path(hermes_home) / "plugins" / "sibyl"
+    plugin_dir.mkdir(parents=True, exist_ok=True)
+    (plugin_dir / "__init__.py").write_text("# stub plugin\n")
+
+
+# ----------------------------------------------------------------------
+# WireOutcome basics
+# ----------------------------------------------------------------------
+
+def test_outcome_dataclass_basic():
+    o = WireOutcome("hermes", "wired", "test")
+    assert o.name == "hermes" and o.status == "wired" and o.backup_path is None
+    o2 = WireOutcome("claude-code", "skipped", "no", backup_path=Path("/tmp/x.bak"))
+    assert o2.backup_path == Path("/tmp/x.bak")
+
+
+# ----------------------------------------------------------------------
+# Prompt helpers
+# ----------------------------------------------------------------------
+
+def test_interactive_prompt_default_y_empty_input(monkeypatch):
+    monkeypatch.setattr("builtins.input", lambda _: "")
+    assert _interactive_prompt("Q?", default="Y") == "y"
+
+
+def test_interactive_prompt_default_n_empty_input(monkeypatch):
+    monkeypatch.setattr("builtins.input", lambda _: "")
+    assert _interactive_prompt("Q?", default="N") == "n"
+
+
+def test_interactive_prompt_explicit_y(monkeypatch):
+    monkeypatch.setattr("builtins.input", lambda _: "y")
+    assert _interactive_prompt("Q?", default="N") == "y"
+
+
+def test_interactive_prompt_explicit_n(monkeypatch):
+    monkeypatch.setattr("builtins.input", lambda _: "no")
+    assert _interactive_prompt("Q?", default="Y") == "n"
+
+
+def test_accept_defaults_prompt_returns_default():
+    assert _accept_defaults_prompt("Q?", default="Y") == "y"
+    assert _accept_defaults_prompt("Q?", default="N") == "n"
+
+
+# ----------------------------------------------------------------------
+# HermesWirer
+# ----------------------------------------------------------------------
+
+def test_hermes_wirer_auto_home_env(monkeypatch, tmp_path):
+    monkeypatch.setenv("HERMES_HOME", str(tmp_path / "custom-hermes"))
+    w = HermesWirer()
+    assert w.hermes_home == tmp_path / "custom-hermes"
+
+
+def test_hermes_wirer_auto_home_default(monkeypatch):
+    monkeypatch.delenv("HERMES_HOME", raising=False)
+    w = HermesWirer()
+    assert w.hermes_home == Path.home() / ".hermes"
+
+
+def test_hermes_is_present_false_when_no_dir_no_bin(monkeypatch, tmp_path):
+    monkeypatch.delenv("HERMES_HOME", raising=False)
+    w = HermesWirer(hermes_home=tmp_path / "nope")
+    with patch("sibyl_memory_cli.setup.shutil.which", return_value=None):
+        assert not w.is_present()
+
+
+def test_hermes_is_present_true_when_dir_exists(tmp_path):
+    (tmp_path / "hermes-home").mkdir()
+    w = HermesWirer(hermes_home=tmp_path / "hermes-home")
+    assert w.is_present()
+
+
+def test_hermes_state_fresh(tmp_path):
+    w = HermesWirer(hermes_home=tmp_path / "hermes-home")
+    st = w.current_state()
+    assert st["config_exists"] is False
+    assert st["plugin_installed"] is False
+    assert st["memory_provider"] is None
+    assert st["wired_with_sibyl"] is False
+
+
+def test_hermes_state_existing_sibyl(tmp_path):
+    home = tmp_path / "hermes-home"
+    home.mkdir()
+    (home / "config.yaml").write_text("memory:\n  provider: sibyl\n")
+    w = HermesWirer(hermes_home=home)
+    st = w.current_state()
+    assert st["memory_provider"] == "sibyl"
+    assert st["wired_with_sibyl"] is True
+
+
+def test_hermes_state_existing_other_provider(tmp_path):
+    home = tmp_path / "hermes-home"
+    home.mkdir()
+    (home / "config.yaml").write_text("memory:\n  provider: mem0\nother: thing\n")
+    w = HermesWirer(hermes_home=home)
+    st = w.current_state()
+    assert st["memory_provider"] == "mem0"
+    assert st["wired_with_sibyl"] is False
+
+
+def test_hermes_wire_fresh_creates_config_and_installs_plugin(tmp_path, monkeypatch):
+    home = tmp_path / "hermes-home"
+    home.mkdir()
+    w = HermesWirer(hermes_home=home)
+    # Stub the install_plugin import via the wirer's _install_plugin override
+    monkeypatch.setattr(
+        HermesWirer, "_install_plugin",
+        lambda self: _stub_install_plugin(str(self.hermes_home)),
+    )
+    outcome = w.wire()
+    assert outcome.status == "wired"
+    # Config now has memory.provider: sibyl
+    import yaml
+    cfg = yaml.safe_load((home / "config.yaml").read_text())
+    assert cfg == {"memory": {"provider": "sibyl"}}
+    # Plugin "installed" (stub created the file)
+    assert (home / "plugins" / "sibyl" / "__init__.py").exists()
+
+
+def test_hermes_wire_existing_sibyl_is_noop(tmp_path, monkeypatch):
+    home = tmp_path / "hermes-home"
+    home.mkdir()
+    (home / "config.yaml").write_text("memory:\n  provider: sibyl\n")
+    # Also pre-install the plugin so the noop path is true end-to-end
+    (home / "plugins" / "sibyl").mkdir(parents=True)
+    (home / "plugins" / "sibyl" / "__init__.py").write_text("# stub\n")
+    w = HermesWirer(hermes_home=home)
+    outcome = w.wire()
+    assert outcome.status == "already"
+
+
+def test_hermes_wire_existing_other_provider_refused_without_force(tmp_path, monkeypatch):
+    home = tmp_path / "hermes-home"
+    home.mkdir()
+    (home / "config.yaml").write_text("memory:\n  provider: mem0\n")
+    monkeypatch.setattr(
+        HermesWirer, "_install_plugin",
+        lambda self: _stub_install_plugin(str(self.hermes_home)),
+    )
+    w = HermesWirer(hermes_home=home)
+    # No prompt_fn means non-interactive refusal
+    outcome = w.wire()
+    assert outcome.status == "skipped"
+    # Config UNCHANGED
+    assert "mem0" in (home / "config.yaml").read_text()
+
+
+def test_hermes_wire_existing_other_provider_with_force(tmp_path, monkeypatch):
+    home = tmp_path / "hermes-home"
+    home.mkdir()
+    (home / "config.yaml").write_text("memory:\n  provider: mem0\n")
+    monkeypatch.setattr(
+        HermesWirer, "_install_plugin",
+        lambda self: _stub_install_plugin(str(self.hermes_home)),
+    )
+    w = HermesWirer(hermes_home=home)
+    outcome = w.wire(force=True)
+    assert outcome.status == "wired"
+    import yaml
+    cfg = yaml.safe_load((home / "config.yaml").read_text())
+    assert cfg["memory"]["provider"] == "sibyl"
+    # Backup landed
+    assert (home / "config.yaml.bak").exists()
+    assert "mem0" in (home / "config.yaml.bak").read_text()
+
+
+def test_hermes_wire_existing_other_provider_prompt_y_accepts(tmp_path, monkeypatch):
+    home = tmp_path / "hermes-home"
+    home.mkdir()
+    (home / "config.yaml").write_text("memory:\n  provider: mem0\n")
+    monkeypatch.setattr(
+        HermesWirer, "_install_plugin",
+        lambda self: _stub_install_plugin(str(self.hermes_home)),
+    )
+    w = HermesWirer(hermes_home=home)
+    outcome = w.wire(prompt_fn=lambda q, *, default: "y")
+    assert outcome.status == "wired"
+
+
+def test_hermes_wire_dry_run_no_writes(tmp_path):
+    home = tmp_path / "hermes-home"
+    home.mkdir()
+    w = HermesWirer(hermes_home=home)
+    outcome = w.wire(dry_run=True)
+    assert outcome.status == "dry-run"
+    assert not (home / "config.yaml").exists()
+    assert not (home / "plugins" / "sibyl" / "__init__.py").exists()
+
+
+def test_hermes_wire_preserves_other_top_level_keys(tmp_path, monkeypatch):
+    home = tmp_path / "hermes-home"
+    home.mkdir()
+    (home / "config.yaml").write_text(
+        "model:\n  name: gpt-4\ntools:\n  - search\n  - file\n"
+    )
+    monkeypatch.setattr(
+        HermesWirer, "_install_plugin",
+        lambda self: _stub_install_plugin(str(self.hermes_home)),
+    )
+    w = HermesWirer(hermes_home=home)
+    w.wire()
+    import yaml
+    cfg = yaml.safe_load((home / "config.yaml").read_text())
+    assert cfg["model"]["name"] == "gpt-4"
+    assert cfg["tools"] == ["search", "file"]
+    assert cfg["memory"]["provider"] == "sibyl"
+
+
+# ----------------------------------------------------------------------
+# ClaudeCodeWirer
+# ----------------------------------------------------------------------
+
+def test_claude_is_present_false_when_no_settings_no_bin(monkeypatch, tmp_path):
+    w = ClaudeCodeWirer(settings_path=tmp_path / "no.json")
+    with patch("sibyl_memory_cli.setup.shutil.which", return_value=None):
+        assert not w.is_present()
+
+
+def test_claude_is_present_true_when_settings_exists(tmp_path):
+    p = tmp_path / "settings.json"
+    p.write_text("{}")
+    w = ClaudeCodeWirer(settings_path=p)
+    assert w.is_present()
+
+
+def test_claude_state_fresh(tmp_path):
+    w = ClaudeCodeWirer(settings_path=tmp_path / "settings.json")
+    st = w.current_state()
+    assert st["settings_exists"] is False
+    assert st["mcp_servers_count"] == 0
+    assert st["sibyl_mcp"] is None
+    assert st["wired_with_sibyl"] is False
+
+
+def test_claude_state_existing_sibyl(tmp_path):
+    p = tmp_path / "settings.json"
+    p.write_text(json.dumps({"mcpServers": {"sibyl-memory": {"command": "sibyl-memory-mcp"}}}))
+    w = ClaudeCodeWirer(settings_path=p)
+    st = w.current_state()
+    assert st["wired_with_sibyl"] is True
+
+
+def test_claude_state_existing_other_mcps_no_sibyl(tmp_path):
+    p = tmp_path / "settings.json"
+    p.write_text(json.dumps({
+        "mcpServers": {"github": {"command": "gh-mcp"}, "filesystem": {"command": "fs-mcp"}}
+    }))
+    w = ClaudeCodeWirer(settings_path=p)
+    st = w.current_state()
+    assert st["mcp_servers_count"] == 2
+    assert st["sibyl_mcp"] is None
+    assert st["wired_with_sibyl"] is False
+
+
+def test_claude_wire_fresh_no_settings_creates(tmp_path):
+    p = tmp_path / "subdir" / "settings.json"  # parent doesn't exist yet
+    w = ClaudeCodeWirer(settings_path=p)
+    outcome = w.wire()
+    assert outcome.status == "wired"
+    cfg = json.loads(p.read_text())
+    assert cfg["mcpServers"]["sibyl-memory"] == {"command": "sibyl-memory-mcp"}
+
+
+def test_claude_wire_fresh_preserves_other_mcps(tmp_path):
+    p = tmp_path / "settings.json"
+    p.write_text(json.dumps({
+        "mcpServers": {"github": {"command": "gh-mcp"}},
+        "theme": "dark",
+    }))
+    w = ClaudeCodeWirer(settings_path=p)
+    outcome = w.wire()
+    assert outcome.status == "wired"
+    cfg = json.loads(p.read_text())
+    assert cfg["mcpServers"]["github"] == {"command": "gh-mcp"}
+    assert cfg["mcpServers"]["sibyl-memory"] == {"command": "sibyl-memory-mcp"}
+    assert cfg["theme"] == "dark"
+    # backup landed
+    assert (tmp_path / "settings.json.bak").exists()
+
+
+def test_claude_wire_existing_sibyl_is_noop(tmp_path):
+    p = tmp_path / "settings.json"
+    p.write_text(json.dumps({"mcpServers": {"sibyl-memory": {"command": "sibyl-memory-mcp"}}}))
+    w = ClaudeCodeWirer(settings_path=p)
+    outcome = w.wire()
+    assert outcome.status == "already"
+    # No backup written for no-op
+    assert not (tmp_path / "settings.json.bak").exists()
+
+
+def test_claude_wire_mismatched_sibyl_refused_without_force(tmp_path):
+    p = tmp_path / "settings.json"
+    # sibyl-memory key exists but command is different
+    p.write_text(json.dumps({"mcpServers": {"sibyl-memory": {"command": "/some/other/path"}}}))
+    w = ClaudeCodeWirer(settings_path=p)
+    outcome = w.wire()
+    assert outcome.status == "skipped"
+    # File UNCHANGED
+    assert "/some/other/path" in p.read_text()
+
+
+def test_claude_wire_mismatched_sibyl_with_force(tmp_path):
+    p = tmp_path / "settings.json"
+    p.write_text(json.dumps({"mcpServers": {"sibyl-memory": {"command": "/some/other/path"}}}))
+    w = ClaudeCodeWirer(settings_path=p)
+    outcome = w.wire(force=True)
+    assert outcome.status == "wired"
+    cfg = json.loads(p.read_text())
+    assert cfg["mcpServers"]["sibyl-memory"]["command"] == "sibyl-memory-mcp"
+
+
+def test_claude_wire_dry_run_no_writes(tmp_path):
+    p = tmp_path / "settings.json"
+    w = ClaudeCodeWirer(settings_path=p)
+    outcome = w.wire(dry_run=True)
+    assert outcome.status == "dry-run"
+    assert not p.exists()
+
+
+def test_claude_wire_mismatched_dry_run(tmp_path):
+    p = tmp_path / "settings.json"
+    p.write_text(json.dumps({"mcpServers": {"sibyl-memory": {"command": "/old"}}}))
+    w = ClaudeCodeWirer(settings_path=p, )
+    outcome = w.wire(dry_run=True, force=True)
+    assert outcome.status == "dry-run"
+    assert "update" in outcome.message
+    # Still no write
+    assert "/old" in p.read_text()
+
+
+# ----------------------------------------------------------------------
+# Registry
+# ----------------------------------------------------------------------
+
+def test_registry_has_both_wirers():
+    assert set(ALL_WIRERS) == {"hermes", "claude-code"}
+    assert ALL_WIRERS["hermes"] is HermesWirer
+    assert ALL_WIRERS["claude-code"] is ClaudeCodeWirer

sibyl-memory-client/CHANGELOG.md

@@ -0,0 +1,389 @@
+# Changelog
+
+All notable changes to `sibyl-memory-client` are recorded here. Format
+follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Versioning
+follows [SemVer](https://semver.org/).
+
+## [0.4.1] — 2026-05-19
+
+Auth-redesign wave 1 step 15 — forward-compat with the server's v6 bearer
+model. `/api/plugin/check-write` accepts `Authorization: Bearer <token>`
+headers in addition to the existing `session_token` body field. This
+release sends both: body field for older servers, header for the new
+protocol. Server-side schema v6 populated `bearer_tokens` at bind time,
+so legacy `session_token`-as-bearer credentials still resolve.
+
+### Changed
+
+- `_capcheck.py:_default_check_write_fn` sends
+  `Authorization: Bearer <token>` header on every check-write call.
+  Token source priority: `payload["bearer_token"]` (server-issued in
+  credentials.json schema_version >= 3) → `payload["session_token"]`
+  (v1 backward compat). No behavior change against current production
+  server. Companion: api-sibyllabs accepts both paths since v6 schema.
+
+## [0.4.0] — 2026-05-18
+
+KAPPA external-tester remediation release. Independent third-party install
+test (KAPPA, peer Tulip-referred) against the v0.3.3 family surfaced one
+blocker that broke `sibyl-memory-mcp` on PyPI plus four secondary findings.
+This release lands the engine-side fixes. Companion releases:
+`sibyl-memory-mcp` v0.1.2, `sibyl-memory-hermes` v0.3.2, `sibyl-memory-cli`
+v0.1.3.
+
+### Fixed
+
+- **KAPPA-BLOCKER** — `CapExceededError` and `TierVerificationError`
+  relocated from `_capcheck.py` to `exceptions.py` so they are importable
+  from the canonical `sibyl_memory_client.exceptions` submodule path. The
+  v0.3.3 family had them defined and re-exported only at the top-level
+  package; the `.exceptions` submodule path (which `sibyl-memory-mcp`
+  imports from) raised `ImportError`. `_capcheck.py` now imports them back
+  for full backwards compatibility with anyone reaching into the private
+  module.
+- **KAPPA-RED** — `~/.sibyl-memory/memory.db` now chmod 0600 after the
+  schema apply (was inheriting umask, typically 0644). WAL + SHM sidecar
+  files also tightened to 0600 if present. Idempotent + non-fatal on
+  chmod failure. Closes the file-perm gap KAPPA observed on a multi-user
+  / CI / shared-dev-box install.
+- **KAPPA-YELLOW** — `set_entity`, `set_state`, and `set_reference` now
+  validate user-supplied identifiers (category, name, key) before write.
+  Rejects: non-string, empty, control characters / null bytes, length
+  > 1024. Raises `ValidationError` with a recovery hint. Read paths are
+  unchanged: already-stored bad identifiers remain accessible so users
+  can introspect and migrate. New module-level helper
+  `validate_identifier(value, *, field_name)`.
+- **KAPPA-YELLOW** — `search()` and `search_entities()` no longer silently
+  swallow `sqlite3.OperationalError` into empty results. The error is now
+  classified by `_classify_fts5_error()`:
+  - schema-missing (`"no such table"`) returns empty (defense against
+    partial schema state on very old DBs);
+  - FTS5 syntax error (`"fts5"`, `"malformed match"`, `"syntax error near"`,
+    `"no such column"`) raises `ValidationError` with the original cause
+    chained;
+  - anything else raises `StorageError` with the original cause chained.
+
+### Added
+
+- `validate_identifier(value, *, field_name)` — public helper for
+  validating user-supplied identifiers consistently across the SDK.
+- `_classify_fts5_error(err)` — internal helper for translating FTS5
+  `OperationalError` into the appropriate exception type.
+
+### Notes
+
+- The 2 MB free-tier cap (KAPPA's product question) is NOT changed in this
+  release. Operator decision to be made separately on whether to raise
+  the cap or document the intent more explicitly.
+- Existing 53/53 client tests pass unchanged. New tests covering the
+  KAPPA-attributed fixes added in `tests/test_smoke.py`.
+
+---
+
+## [0.3.3] — 2026-05-18
+
+Audit-remediation release. v0.3.0 pre-ship audit (2026-05-18T05:05Z) surfaced
+10 critical findings across four lanes; this release lands the engine-side
+fixes. Companion releases: `sibyl-memory-hermes` v0.3.1, `sibyl-memory-cli`
+v0.1.2, `sibyl-memory-mcp` v0.1.1.
+
+### Added
+
+- `MemoryClient.search(query, *, limit=20, prefix=False, tiers=None)` —
+  cross-tier FTS5 search over entities + state + reference + journal. Each
+  hit is tier-tagged with `{tier, key, category, body, snippet, rank, ts}`.
+  Pass `tiers=("entity", "state")` to restrict scope. The marketing claim of
+  "FTS5 across all tiers" is now actually true.
+- FTS5 query sanitization: every user-supplied query is wrapped as a single
+  quoted FTS5 phrase before MATCH. Column-filter syntax (`name:foo`,
+  `rowid:*`, etc.) can no longer escape into the FTS5 parser. Empty queries
+  short-circuit to empty result (no SQL error leak).
+- `_sanitize_fts5_query(raw, *, prefix=False)` helper exposed for callers
+  building their own FTS5 queries.
+
+### Changed (schema v3 migration)
+
+- **Schema bumped to v3.** All four searchable tiers (entities, state,
+  reference, journal) now have FTS5 indexes:
+  - entities_fts → external-content (was standalone with body duplication)
+  - state_documents_fts → NEW, external-content
+  - reference_documents_fts → external-content (was standalone, never
+    exposed in the public SDK)
+  - journal_events_fts → NEW, contentless, payload = evaluated || acted ||
+    forward || extra concatenated
+- v2 → v3 migration runs automatically on first open. Detects v2's
+  standalone entities_fts shape, drops it and the old reference_documents_fts,
+  recreates in external-content form, and rebuilds the FTS5 indexes from
+  the existing base-table data. No application data lost. ~50ms per 10k
+  entities on first open after upgrade; idempotent thereafter.
+- FTS5 disk footprint reduced ~50% on body-dominated tenants (v2 stored
+  the entity body twice; v3 stores it once in the base table).
+- FTS5 update trigger pattern fixed: was O(N) DELETE-by-UNINDEXED-column;
+  now O(log N) external-content delete-by-rowid.
+- `search_entities()` updated to join via rowid (the external-content
+  primary key) instead of entity_id.
+- `search_entities()` now returns empty list on malformed FTS5 queries
+  rather than raising. Previously `client.search_entities('"')` would
+  surface a `sqlite3.OperationalError` wrapped as `StorageError` with the
+  full db_path interpolated into the message.
+
+### Security
+
+- **SEC-2** — Atomic 0600-at-create for `TierCache.store`. Previously
+  used `write_text(...)` then `os.chmod(..., 0o600)`, leaving a
+  world-readable window between syscalls every cache write. Now opens with
+  `O_WRONLY|O_CREAT|O_EXCL|O_NOFOLLOW` and mode `0o600` set at creation
+  time. No race window.
+- **SEC-3** — FTS5 query sanitization on every MATCH path. Prevents
+  FTS5 injection / DoS via malformed queries.
+- **SEC-3** — `StorageError` messages no longer echo the absolute
+  `db_path` or full SQLite error text. Original exception is chained via
+  `from e` for debugging; user-visible message stays generic.
+- **SEC-9** — `TierVerificationError` no longer echoes the server-side
+  `error` body string in the user-visible message — strips to a generic
+  "Retry shortly" pointer to avoid leaking internal server detail into
+  user logs.
+- **SEC-11** — `TierCache.load` refuses to follow symlinks. A
+  low-privilege attacker who once had write to `~/.sibyl-memory` cannot
+  redirect the cache to `/dev/null` or another file via symlink.
+
+### Fixed
+
+- **C2** — `__version__` no longer hardcoded. Now sourced from
+  `importlib.metadata.version("sibyl-memory-client")` with the same
+  `+source` fallback pattern as sibyl-memory-hermes v0.3.0. The wheel and
+  the in-Python `__version__` can no longer drift (v0.3.2 published with
+  `__init__.py` saying "0.3.1").
+- HTTP User-Agent in `_default_check_write_fn` now built from
+  `__version__` instead of hardcoded `"sibyl-memory-client/0.3.0"`. Server
+  telemetry will accurately reflect the installed version.
+- `from e` chaining added to `_default_check_write_fn`'s `HTTPError` and
+  `URLError`/`TimeoutError`/`OSError` handlers so the original cause is
+  preserved through `TierVerificationError`.
+
+### Hygiene
+
+- Dropped unused `Iterable` and `ConflictError` imports from `client.py`
+  (DC1/DC2). Both remain in `__all__` via re-export.
+
+## [0.3.2] — 2026-05-16
+
+Audit-remediation release. Companion to api-sibyllabs payment-rail fixes
+and the post-audit shipping pass. Closes T1-3, T1-4, T2-3 from the
+2026-05-16 audit pass (full report: `memory/research/` + email
+msg_id 19e33139dfc3e4d4).
+
+### Changed
+
+- **T1-3 — `archive_entity` now goes through CapGate**. The audit found
+  that `MemoryClient.archive_entity` bypassed the cap check, letting a
+  free user at 1.9 MB archive their largest entities (body copied into
+  archived_entities, doubling footprint) to keep writing past 2 MB. The
+  method now reads the entity body first to size the proposed insert
+  (`body + name + category + reason + 200B overhead`), then calls
+  `self._cap_gate.check(proposed_delta_bytes=delta)` before the write
+  transaction. NotFoundError still raised before any cap-gate side effect.
+- **T1-3 — `Learner.accept_proposal` now accepts an optional `cap_gate`**.
+  `Learner.__init__` gains a `cap_gate: Any = None` parameter. When
+  non-None, `accept_proposal` calls `cap_gate.check(proposed_delta_bytes=...)`
+  before inserting the `reference_documents` row (skill body can be
+  kilobytes). The convenience entry `MemoryClient.learner()` threads
+  the client's CapGate through automatically. Direct-import callers can
+  override `cap_gate=None` explicitly for tests.
+- **T2-3 — `_default_check_write_fn` no longer forges fake decisions on
+  HTTP error**. Previously a transient 502 response synthesized
+  `{ok: False, tier: "free"}` and the caller cached it as authoritative,
+  locking a paid user out for up to 7 days. Now raises
+  `TierVerificationError` on any HTTP error — the offline-grace path in
+  `_refresh_and_check` decides whether to honor a recent cache or hard-cap.
+- **T1-4 — TierCacheEntry gains `server_expires_at` + `cache_token` fields**.
+  `server_expires_at` is the server-supplied subscription expiry parsed
+  from the `expires_at` field on the `/check-write` response. The cache
+  is now honored only while `now < min(checked_at + grace_seconds,
+  server_expires_at)`, which prevents the multi-grace-period attack
+  where a user blackholes the network to keep using their cached paid
+  tier past actual subscription expiry. Authoritative end-of-validity
+  comes from the server's record, not from a refresh-able local timer.
+  `cache_token` stores the credentials.signature as a defense-in-depth
+  link between cache and credentials identity (sent on subsequent
+  cap-checks for tamper telemetry).
+- **TierCache.load/store round-trip the new fields**. Backwards
+  compatible with v0.3.1 cache files (missing fields default to None).
+
+### Schema
+
+- TierCache file schema bumped (implicitly v2). v1 caches load fine
+  with `server_expires_at=None` and `cache_token=None`; next successful
+  `/check-write` upgrades them.
+
+### Tests
+
+- 53/53 unchanged, all green. The cap-gate addition in `archive_entity`
+  fires under the default 2 MB cap on test data well below that
+  threshold — no test changes needed.
+
+### Notes for downstream
+
+- `sibyl-memory-hermes` v0.2.2 ships in lockstep (narrows `recall()`
+  exception handling to `NotFoundError` only, T2-2 fix). Earlier
+  hermes versions still work; the bug they had was over-aggressive
+  exception swallowing, harmless to the cap-gate plumbing.
+
+## [0.3.1] — 2026-05-16
+
+Tamper-evidence release. Companion to api-sibyllabs HMAC signing.
+
+### Added
+
+- `MemoryClient.__init__` and `MemoryClient.local()` accept two new
+  optional kwargs: `credentials_claim` (dict of the canonical signed
+  fields) and `credentials_signature` (hex HMAC). Both default to None
+  for backwards compatibility with unsigned v0.3.0 credentials.
+- `CapGate` accepts the same two kwargs and, when both are present,
+  attaches them to every `/check-write` POST body. The server uses
+  them to verify the signature and log `credentials_tamper_suspected`
+  telemetry on mismatch. The cap-gate decision itself is unaffected —
+  authoritative tier always comes from the database via
+  `effectiveAccess`.
+
+### Schema
+
+- Credentials JSON schema v2 (server-issued 2026-05-16+) — adds
+  `signature` (HMAC-SHA256 hex, 64 chars) and `signed_at` (ISO ts).
+  Old schema v1 credentials still load and work; the client just
+  sends an unsigned request and the server skips the tamper check.
+
+### Tests
+
+- 53/53 unchanged, all green. The signing path is purely additive.
+
+## [0.3.0] — 2026-05-15
+
+Hard-cap enforcement release. Operator directive 2026-05-15: "how do
+we hard-limit free users to the 2Mb size? and ensure they can't
+circumvent this" → Level 1 (hard write cap) + Level 2 (signed
+credentials.json, deferred) + server-authoritative tier check at the
+boundary. Locked in: 7-day grace cache, hard cap on by default.
+
+### Added
+
+- **`_capcheck.py` module** with the cap-enforcement primitives:
+  - `CapGate.check(proposed_delta_bytes)` — three fast paths plus one
+    slow server-refresh path. Most writes never phone home. The slow
+    path only fires when (a) a free-tier user is about to push past
+    2 MB or (b) the local tier cache has expired.
+  - `TierCache` — file-backed at `~/.sibyl-memory/tier_cache.json`,
+    mode 0600, atomic write, JSON shape `{ account_id, tier,
+    checked_at, cap_bytes }`. Honored as fresh for 7 days; honored
+    for an extended 14-day grace if the user is offline.
+  - `CapExceededError` (code `CAP_EXCEEDED`) — carries `upgrade_url`.
+  - `TierVerificationError` — raised only when the user is at the cap,
+    offline, AND has no valid grace cache. Distinct from CAP_EXCEEDED
+    so callers can route the two error states differently.
+  - `_default_check_write_fn` — pure stdlib urllib transport. The
+    default endpoint is `https://api.sibyllabs.org/api/plugin/check-write`.
+    Replaceable for tests via the `check_fn` constructor kwarg.
+  - Constants `FREE_TIER_CAP_BYTES = 2 * 1024 * 1024` and
+    `GRACE_PERIOD_SECONDS = 7 * 24 * 60 * 60`.
+
+- **`MemoryClient` cap wiring** (additive, non-breaking):
+  - `__init__` and `local()` accept `account_id`, `session_token`,
+    `tier`, and an optional `cap_gate` override.
+  - Every write path (`set_entity`, `write_event`, `set_state`,
+    `set_reference`) calls `self._cap_gate.check(proposed_delta_bytes=...)`
+    with a JSON-byte-length estimate. Reads are never gated.
+  - Pre-activation users (no `account_id`) get a strict local 2 MB cap
+    with no server check possible — by design.
+
+### Tests
+
+- 13 new tests in `tests/test_capcheck.py` covering: under-cap (no
+  server call), at-cap server says no, server upgrades a stale-cached
+  user, paid-cache short-circuits server, stale paid cache triggers
+  refresh, offline-at-cap with grace cache passes, offline-at-cap
+  with no cache raises, pre-activation under/at cap, e2e MemoryClient
+  free/paid, cache file mode is 0600, `invalidate_cache()` works.
+  Full suite 53/53 green.
+
+### Notes for downstream
+
+- `sibyl-memory-hermes` v0.2.0 plumbs `account_id` and `session_token`
+  through to the client. Earlier hermes versions still work but
+  pre-activation users hit the strict local 2 MB cap.
+- The Level 2 HMAC-signed `credentials.json` design is in
+  `memory/research/2026-05-15-hard-cap-enforcement.md` (deferred until
+  `PLUGIN_CREDENTIAL_SIGNING_KEY` is provisioned in Doppler/Vercel).
+
+## [0.2.0] — 2026-05-15
+
+Self-learning + memory-linting release. Operator directive 2026-05-15:
+"add a self-learning cron + function to the memory deployment so the
+memory learns and creates skills from things in the session just as you
+do. could we also do memory linter?"
+
+### Schema
+
+- **v2 migration** — adds two tables. Idempotent. v1 databases auto-upgrade on next open.
+  - `skill_proposals` — review queue for detected skills. Columns: id, tenant_id, created_at, pattern_kind, proposed_slug, proposed_title, proposed_body, evidence (JSON), confidence (REAL 0..1), summarizer, status (pending/accepted/rejected/superseded), reviewed_at, review_note, accepted_doc_key. UNIQUE indexes on (tenant_id, status, created_at) and (tenant_id, proposed_slug).
+  - `learning_runs` — watermark log so detectors don't rescan ground they covered. Columns: id, tenant_id, started_at, completed_at, summarizer, events_scanned, proposals_made, cursor_after_ts, notes.
+
+### Added
+
+- **`learning.py` module** with the full self-learning loop:
+  - `Learner` class — scans journal_events since last watermark, runs four pattern detectors, dedupes by slug, persists top-N proposals.
+  - Four deterministic detectors: `repeated_action`, `structural_similarity`, `co_occurrence`, `temporal_routine`.
+  - Three pluggable summarizer backends (per operator design directive 2026-05-15):
+    - `LocalDeterministicSummarizer` (free tier default) — pure SQL + Python templates, zero network.
+    - `BYOKSummarizer` (paid tier opt-in) — user supplies their own inference callable, SDK never holds the key.
+    - `VeniceX402Summarizer` (paid tier hosted) — Venice-routed via x402 against the user's pre-funded plugin balance. Endpoint design at `memory/research/2026-05-15-self-learning-design.md`.
+  - Review queue API: `list_proposals`, `get_proposal`, `accept_proposal` (writes `reference_documents` row under `skill/<slug>` key with provenance metadata), `reject_proposal`.
+  - Both LLM-backed summarizers gracefully fall back to local-deterministic output when the inference callable raises.
+
+- **`lint.py` module** — local memory linter mirroring `scripts/memory-lint.mjs`:
+  - `Linter` class with 9 checks across three severity tiers (critical / warning / info): schema-version, invalid-json-entity, invalid-json-state, invalid-json-journal, duplicate-entity, empty-reference, stale-entity, journal-without-acts, db-soft-cap, fts-rowcount-mismatch, flagged-actors-fresh.
+  - `LintReport` dataclass with `to_dict()` (JSON-serializable) + `to_ascii()` (single-block boxed report for CLI).
+  - Tunable thresholds: `soft_cap_bytes` (default 10 MB per operator decision), `stale_days` (default 90), `flag_recency_days` (default 30).
+
+- **`MemoryClient` API surface (additive)**:
+  - `client.learner(**kwargs)` — construct a tenant-bound Learner.
+  - `client.learn()` — convenience: one-shot Learner.run() returning a LearningRunReport.
+  - `client.list_skill_proposals(status='pending', limit=50)`.
+  - `client.accept_skill_proposal(id, note=None)`.
+  - `client.reject_skill_proposal(id, note=None)`.
+  - `client.lint(**kwargs)` — returns a LintReport.
+
+- **Public exports** (`__init__.py`): added `Learner`, `SkillProposal`, `LearningRunReport`, `Summarizer`, `LocalDeterministicSummarizer`, `BYOKSummarizer`, `VeniceX402Summarizer`, `Linter`, `LintReport`, `Finding`.
+
+### Tests
+
+- 22 new tests across two files:
+  - `tests/test_learning.py` — 12 tests: schema migration v2, no-event runs, repeated-action detection, watermark dedup, structural-similarity detection, accept/reject lifecycle, BYOK invocation, Venice/x402 fallback on failure, multi-tenant isolation.
+  - `tests/test_lint.py` — 10 tests: clean-DB baseline, duplicate-entity, empty-reference, stale-entity, journal-without-acts, soft-cap, ASCII report rendering, dict serialization, severity buckets, multi-tenant isolation.
+- Total package coverage: 10 (existing smoke) + 12 (learning) + 10 (lint) = **32 tests, all green**.
+
+### Compatibility
+
+- v0.1.0 databases auto-upgrade to v2 on first open via existing idempotent `_ensure_schema()` path — no manual migration needed.
+- `sibyl-memory-hermes` v0.1.0 is binary-compatible with v0.2.0 of this SDK (provider surface unchanged). Hermes-provider tests updated to expect schema_version=2.
+- Local-first promise unchanged: free tier remains zero-network. BYOK / Venice routes are paid-tier opt-in only and the CLI gate enforces tier checks upstream.
+
+### Notes for CLI integration (sibyl-labs-cli, next)
+
+The CLI package will expose:
+- `sibyl learn` → runs `client.learn()`.
+- `sibyl learn review` → interactive walk of `client.list_skill_proposals()` with y/n/edit prompts.
+- `sibyl lint` → runs `client.lint()`, prints `to_ascii()`, exits non-zero if `critical_count > 0`.
+- Optional cron install during `sibyl init` (Linux/macOS cron, Windows Task Scheduler) for daily learn + lint.
+
+## [0.1.0] — 2026-05-15
+
+Initial release.
+
+- SQLite + FTS5 port of the canonical `sibyl_memory.*` Postgres schema (10 base tables + 2 FTS5 virtuals + version table).
+- `MemoryClient` public API with polymorphic constructor: `MemoryClient.local(path)`.
+- Five-tier model: entities (WARM) / state_documents (HOT) / journal_events (COLD) / reference_documents (REFERENCE) / archived_entities (ARCHIVE) / flagged_actors (FLAGGED).
+- Multi-tenant isolation via `tenant_id` column.
+- `Storage` low-level wrapper with per-instance thread-local connection cache, WAL mode, foreign_keys=ON, busy_timeout=5000ms.
+- Typed exception hierarchy (`SibylMemoryError` + subclasses).
+- 10 smoke tests, all green.
+- Zero runtime dependencies, MIT, Python 3.10+.

sibyl-memory-client/README.md

@@ -0,0 +1,69 @@
+# sibyl-memory-client
+
+**Local-first agentic memory SDK. The foundation of the Sibyl Memory Plugin family.**
+
+A small Python library that gives any AI agent durable memory across sessions, stored in a SQLite database on the user's own computer. No round-trip to anyone's cloud. Organized by what kind of thing it is, not one fuzzy similarity bucket.
+
+```bash
+pip install sibyl-memory-client
+```
+
+## Quickstart
+
+```python
+from sibyl_memory_client import MemoryClient
+
+memory = MemoryClient.local("~/.sibyl-memory/memory.db")
+
+# Remember a fact (entity)
+memory.set_entity("project", "atlas", {"status": "active", "owner": "jane"})
+
+# Recall it
+print(memory.get_entity("project", "atlas"))
+
+# Record what happened (journal)
+memory.write_event(acted=["deployed atlas v1.2 to staging"])
+
+# Search across everything
+results = memory.search_entities("atlas")
+```
+
+## Why this exists
+
+Most agent-memory products store everything on someone else's servers, treat every piece of information the same way, and quietly forget the important things when you need them most. This SDK solves all three:
+
+- **Local-first.** Memory lives in a SQLite database in `~/.sibyl-memory/`. No cloud round-trip for any operation.
+- **Organized by kind.** Five separate tiers — state, entities, journal, reference, archive — each recalled the way it should be recalled.
+- **Benchmarked.** The Sibyl Memory Plugin (built on this SDK) sits at #2 globally on the LongMemEval Oracle benchmark when paired with Claude Opus 4.6. Methodology open at [blog.sibylcap.com/longmemeval-v2](https://blog.sibylcap.com/longmemeval-v2).
+
+## The five tiers
+
+| Intent | Tier | API |
+|---|---|---|
+| What you're working on right now | HOT state | `set_state(key, body)` / `get_state(key)` |
+| Things the agent knows about | WARM entities | `set_entity(kind, name, body)` / `get_entity` |
+| What happened, in time order | COLD journal | `write_event(...)` / `read_events(...)` |
+| Documents you look up by name | REFERENCE | `set_reference(key, body)` / `get_reference` |
+| Frozen things, kept but out of the way | ARCHIVE | `archive_entity(kind, name)` |
+| Search across everything | FTS5 | `search_entities(query)` |
+
+## What's in v0.2.x
+
+- The full five-tier memory model and the API surface above.
+- Multi-tenant isolation: one machine can hold separate memory for separate identities.
+- Self-learning module (paid-tier): the agent watches your patterns and proposes reusable skills.
+- Memory linter (paid-tier): a health check on the local database.
+- Tier gating: free-tier callers get clear errors pointing at the upgrade page; paid-tier callers get full access.
+
+## Tier model
+
+Free tier is generous on purpose. You can build real things with it. Paid plans add self-learning, the linter, and remove the 2 MB local cap. Full plan comparison at [docs.sibyllabs.org/memory/tiers](https://docs.sibyllabs.org/memory/tiers).
+
+## Documentation
+
+Full docs: [docs.sibyllabs.org/memory/](https://docs.sibyllabs.org/memory/).
+Install guide: [docs.sibyllabs.org/memory/install](https://docs.sibyllabs.org/memory/install).
+
+## License
+
+MIT. Published on PyPI at [pypi.org/project/sibyl-memory-client](https://pypi.org/project/sibyl-memory-client/).

sibyl-memory-client/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sibyl-memory-client"
+version = "0.4.1"
+description = "Local-first agentic memory SDK. SQLite-backed five-tier hierarchical schema, FTS5 search, multi-tenant, with self-learning skill detection and local memory linter. Foundation of the Sibyl Memory Plugin family."
+authors = [{ name = "SIBYL, Sibyl Labs LLC", email = "sibyl@sibyllabs.org" }]
+license = { text = "MIT" }
+readme = "README.md"
+requires-python = ">=3.10"
+keywords = ["sibyl", "memory", "agent", "sqlite", "local-first", "hermes"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Topic :: Database",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=7.0",
+  "pytest-cov>=4.0",
+]
+
+[project.urls]
+Homepage = "https://sibyllabs.org/plugin"
+Documentation = "https://docs.sibyllabs.org/memory/"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["sibyl_memory_client*"]
+
+[tool.setuptools.package-data]
+"sibyl_memory_client" = ["schema.sql"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra"

sibyl-memory-client/src/sibyl_memory_client/__init__.py

@@ -0,0 +1,109 @@
+"""sibyl-memory-client - Local-first agentic memory SDK.
+
+Public exports:
+    MemoryClient        the main interface
+    Storage             low-level connection wrapper (advanced use)
+    DEFAULT_TENANT      canonical single-user tenant UUID
+    Exceptions          SibylMemoryError + subclasses
+    Learner             self-learning pattern detector (v0.2.0)
+    SkillProposal       review-queue dataclass (v0.2.0)
+    LearningRunReport   summary of a learning pass (v0.2.0)
+    Summarizer*         pluggable LLM backends (v0.2.0)
+    Linter              local memory linter (v0.2.0)
+    LintReport          aggregated lint output (v0.2.0)
+    Finding             single lint finding (v0.2.0)
+
+Quickstart:
+
+    from sibyl_memory_client import MemoryClient
+    client = MemoryClient.local("~/.sibyl-memory/memory.db")
+    client.set_entity("project", "atlas", {"status": "active", "stage": "staging"})
+    client.write_event(acted=["deployed atlas v1.2"])
+
+    # Self-learning (v0.2.0): scan journal, propose skills, review queue
+    report = client.learn()
+    for proposal in client.list_skill_proposals():
+        print(proposal.proposed_title, proposal.confidence)
+        client.accept_skill_proposal(proposal.id)  # → writes reference/skill/<slug>
+
+    # Memory linter (v0.2.0):
+    print(client.lint().to_ascii())
+"""
+from ._capcheck import (
+    CapExceededError,
+    CapGate,
+    FREE_TIER_CAP_BYTES,
+    GRACE_PERIOD_SECONDS,
+    TierCache,
+    TierCacheEntry,
+    TierVerificationError,
+)
+from .client import DEFAULT_TENANT, MemoryClient
+from .exceptions import (
+    ConflictError,
+    NotFoundError,
+    SchemaError,
+    SibylMemoryError,
+    StorageError,
+    TenantError,
+    TierGateError,
+    ValidationError,
+)
+from .learning import (
+    BYOKSummarizer,
+    Learner,
+    LearningRunReport,
+    LocalDeterministicSummarizer,
+    SkillProposal,
+    Summarizer,
+    VeniceX402Summarizer,
+)
+from .lint import Finding, LintReport, Linter
+from .storage import Storage
+
+# Single-sourced from installed metadata so the wheel + code never drift
+# (C2 audit fix v0.3.3). Source-tree fallback for editable installs that
+# haven't been pip-installed yet.
+from importlib.metadata import PackageNotFoundError, version as _pkg_version
+try:
+    __version__ = _pkg_version("sibyl-memory-client")
+except PackageNotFoundError:  # pragma: no cover - source-tree dev only
+    __version__ = "0.0.0+source"
+
+__all__ = [
+    # core
+    "MemoryClient",
+    "Storage",
+    "DEFAULT_TENANT",
+    # exceptions
+    "SibylMemoryError",
+    "StorageError",
+    "SchemaError",
+    "TenantError",
+    "NotFoundError",
+    "ConflictError",
+    "ValidationError",
+    "TierGateError",
+    # cap enforcement (v0.3.0)
+    "CapExceededError",
+    "TierVerificationError",
+    "CapGate",
+    "TierCache",
+    "TierCacheEntry",
+    "FREE_TIER_CAP_BYTES",
+    "GRACE_PERIOD_SECONDS",
+    # learning (v0.2.0)
+    "Learner",
+    "SkillProposal",
+    "LearningRunReport",
+    "Summarizer",
+    "LocalDeterministicSummarizer",
+    "BYOKSummarizer",
+    "VeniceX402Summarizer",
+    # lint (v0.2.0)
+    "Linter",
+    "LintReport",
+    "Finding",
+    # meta
+    "__version__",
+]

sibyl-memory-client/src/sibyl_memory_client/_capcheck.py

@@ -0,0 +1,465 @@
+"""Hard-cap enforcement with server-authoritative tier verification.
+
+Design (v0.3.0):
+
+    1. Every write call (set_entity, write_event, set_state, set_reference)
+       calls _check_write_allowed(proposed_delta_bytes).
+    2. Three fast paths skip the server call:
+       a) tier in PAID_TIERS (locally cached, refreshed weekly)
+       b) db_size + delta would still be well under the cap
+       c) we have a recent cached server result that says we're under-cap
+    3. The slow path (only fires at the cap boundary) hits the server endpoint
+       POST /api/plugin/check-write with current_size + proposed_delta. The
+       server is the authoritative source for tier — credentials.json
+       tampering is detected here because the server looks up the real tier
+       from sibyl_plugin.accounts.
+    4. Server response is cached for 7 days. After that, the next write at the
+       cap forces a refresh. Users who go offline keep working under the
+       cached result; if their cached tier says paid, they keep their grant
+       for up to a week.
+    5. Offline at the cap boundary with NO cache: hard block with a clear
+       error pointing at the upgrade URL.
+
+The local-first promise is preserved: no memory content ever crosses the
+network. Only (account_id, current_size_bytes, proposed_delta_bytes) is sent
+to the check-write endpoint.
+"""
+from __future__ import annotations
+
+import json
+import os
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Callable
+
+# v0.4.0: CapExceededError + TierVerificationError live in exceptions.py
+# (canonical exception module). _capcheck imports them back so existing
+# callers that import from `sibyl_memory_client._capcheck` still resolve.
+# The MCP server (sibyl-memory-mcp >= 0.1.2) imports from the canonical
+# `.exceptions` path; this re-export keeps the historical path alive too.
+from .exceptions import (  # noqa: F401  (re-exported for backwards compat)
+    CapExceededError,
+    SibylMemoryError,
+    TierVerificationError,
+)
+
+# ----------------------------------------------------------------------
+# Constants
+# ----------------------------------------------------------------------
+
+FREE_TIER_CAP_BYTES = 2 * 1024 * 1024  # 2 MB
+GRACE_PERIOD_SECONDS = 7 * 24 * 60 * 60  # 7 days
+PAID_TIERS = frozenset({"sync", "team", "lifetime", "stake", "enterprise"})
+
+DEFAULT_CHECK_WRITE_URL = "https://api.sibyllabs.org/api/plugin/check-write"
+DEFAULT_UPGRADE_URL = "https://docs.sibyllabs.org/memory/tiers"
+DEFAULT_CACHE_PATH = "~/.sibyl-memory/tier_cache.json"
+
+# Network timeout for the check-write call. Short to keep latency tolerable
+# on the user's first write at the cap.
+HTTP_TIMEOUT_SECONDS = 4.0
+
+
+# ----------------------------------------------------------------------
+# Cache
+# ----------------------------------------------------------------------
+
+@dataclass
+class TierCacheEntry:
+    """A single tier-check result cached on disk.
+
+    Fields:
+        account_id, tier, checked_at, cap_bytes, last_known_size: original
+            v0.3.0 schema fields.
+        grace_seconds: legacy local grace window (default 7d).
+        server_expires_at: T1-4 anchor (v0.3.2+). The server-supplied
+            subscription expiry (epoch seconds). When set, this is the
+            authoritative end-of-validity. Cache is honored only while
+            `now < min(checked_at + grace_seconds, server_expires_at)`.
+            For staker/free tier this is None (cache uses grace_seconds only).
+        cache_token: T1-2-lite (v0.3.2+). Opaque token issued by the
+            server (currently a copy of `credentials.signature`). Sent back
+            on every cap-check so the server can detect tampering of the
+            cache file. Authoritative cap decision still comes from the
+            server-side tier lookup.
+    """
+    account_id: str
+    tier: str
+    checked_at: float          # epoch seconds when we got the result
+    cap_bytes: int | None      # None = uncapped (paid)
+    last_known_size: int = 0   # the size we reported when we made the check
+    grace_seconds: int = GRACE_PERIOD_SECONDS
+    server_expires_at: float | None = None
+    cache_token: str | None = None
+
+    @property
+    def expires_at(self) -> float:
+        local = self.checked_at + self.grace_seconds
+        if self.server_expires_at is not None:
+            return min(local, self.server_expires_at)
+        return local
+
+    @property
+    def is_fresh(self) -> bool:
+        return time.time() < self.expires_at
+
+
+class TierCache:
+    """File-backed tier cache. Mode 0600. Single entry per file."""
+
+    def __init__(self, path: str | Path = DEFAULT_CACHE_PATH) -> None:
+        self.path = Path(path).expanduser().resolve()
+        self.path.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
+
+    def load(self) -> TierCacheEntry | None:
+        """Load the cache entry. v0.3.3 hardens against symlink swapping:
+        refuses to follow symlinks (SEC-11). Returns None on missing,
+        symlinked, corrupted, or unreadable cache."""
+        if not self.path.exists():
+            return None
+        try:
+            # SEC-11: reject symlinks. A low-privilege attacker who once had
+            # write to ~/.sibyl-memory could symlink the cache to /dev/null
+            # or another sensitive file.
+            if self.path.is_symlink():
+                return None
+            raw = json.loads(self.path.read_text(encoding="utf-8"))
+            server_exp = raw.get("server_expires_at")
+            return TierCacheEntry(
+                account_id=raw["account_id"],
+                tier=raw["tier"],
+                checked_at=float(raw["checked_at"]),
+                cap_bytes=raw.get("cap_bytes"),
+                last_known_size=int(raw.get("last_known_size", 0)),
+                grace_seconds=int(raw.get("grace_seconds", GRACE_PERIOD_SECONDS)),
+                server_expires_at=(float(server_exp) if server_exp is not None else None),
+                cache_token=raw.get("cache_token"),
+            )
+        except (OSError, KeyError, ValueError, json.JSONDecodeError):
+            return None  # corrupted cache, treat as missing
+
+    def store(self, entry: TierCacheEntry) -> None:
+        """Atomic store with mode 0o600 set at creation (not after the fact).
+
+        SEC-2 hardening (v0.3.3): the previous write_text() + chmod() pattern
+        left a world-readable window between the syscalls. Now we open with
+        O_CREAT|O_EXCL|O_WRONLY and mode 0o600 — the kernel sets mode at the
+        moment of creation, no race window."""
+        payload = {
+            "account_id": entry.account_id,
+            "tier": entry.tier,
+            "checked_at": entry.checked_at,
+            "cap_bytes": entry.cap_bytes,
+            "last_known_size": entry.last_known_size,
+            "grace_seconds": entry.grace_seconds,
+            "server_expires_at": entry.server_expires_at,
+            "cache_token": entry.cache_token,
+        }
+        data = json.dumps(payload, indent=2).encode("utf-8")
+        tmp_path = self.path.with_suffix(self.path.suffix + ".tmp")
+        # Clean any leftover tmp from a crashed prior write so O_EXCL can succeed.
+        try:
+            os.unlink(tmp_path)
+        except FileNotFoundError:
+            pass
+        # Atomic create-with-mode. O_NOFOLLOW rejects symlink targets.
+        flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL
+        if hasattr(os, "O_NOFOLLOW"):
+            flags |= os.O_NOFOLLOW
+        fd = os.open(str(tmp_path), flags, 0o600)
+        try:
+            os.write(fd, data)
+            os.fsync(fd)
+        finally:
+            os.close(fd)
+        os.replace(str(tmp_path), str(self.path))
+
+    def clear(self) -> None:
+        if self.path.exists():
+            self.path.unlink()
+
+
+# ----------------------------------------------------------------------
+# Server check
+# ----------------------------------------------------------------------
+
+def _default_check_write_fn(
+    url: str,
+    payload: dict[str, Any],
+    timeout: float = HTTP_TIMEOUT_SECONDS,
+) -> dict[str, Any]:
+    """Default network transport for the check-write call.
+
+    Pure stdlib (urllib) to keep the SDK zero-dependency. If the call
+    fails (timeout, network error, non-2xx), raises TierVerificationError.
+    Callers can pass in a custom fn for testing or for using their own
+    HTTP client.
+    """
+    import urllib.request
+    import urllib.error
+    body = json.dumps(payload).encode("utf-8")
+    # User-Agent sourced from installed metadata so version drift is impossible.
+    try:
+        from importlib.metadata import version as _pkg_version, PackageNotFoundError
+        try:
+            _ua_ver = _pkg_version("sibyl-memory-client")
+        except PackageNotFoundError:
+            _ua_ver = "0.0.0+source"
+    except Exception:
+        _ua_ver = "0.0.0+source"
+    # v0.4.1 (auth-redesign wave 1 step 15): forward-compat with the v6
+    # bearer model. If the payload carries a bearer_token (new server protocol)
+    # OR session_token (v1 backward compat where bearer == session), send it
+    # as `Authorization: Bearer <token>` in addition to the body field. Server
+    # accepts either path; this aligns the SDK to the new protocol without
+    # breaking older servers that only read the body.
+    headers = {
+        "Content-Type": "application/json",
+        "User-Agent": f"sibyl-memory-client/{_ua_ver}",
+        "Accept": "application/json",
+    }
+    auth_value = payload.get("bearer_token") or payload.get("session_token")
+    if auth_value:
+        headers["Authorization"] = f"Bearer {auth_value}"
+    req = urllib.request.Request(
+        url,
+        data=body,
+        headers=headers,
+        method="POST",
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            return json.loads(resp.read().decode("utf-8"))
+    except urllib.error.HTTPError as e:
+        # T2-3 fix: do NOT synthesize a fake "free tier" decision on HTTP
+        # error. Previously a transient 502 would write `{tier:free, cap_bytes:2MB}`
+        # into the cache for a legitimately paid user, locking them out
+        # for up to 7 days. Now we raise TierVerificationError — the
+        # caller (_refresh_and_check) will fall back to a recent cache
+        # if one exists, or hard-cap if no cache.
+        try:
+            body = json.loads(e.read().decode("utf-8"))
+        except Exception:
+            body = {}
+        # SEC-9 (v0.3.3): strip the server-side `error` string from the
+        # surfaced message to avoid echoing verbose internal detail (or
+        # potential PII) into user logs.
+        raise TierVerificationError(
+            f"Sibyl Labs returned HTTP {e.code} while verifying your account. "
+            f"Retry shortly.",
+        ) from e
+    except (urllib.error.URLError, TimeoutError, OSError) as e:
+        raise TierVerificationError(
+            f"Could not reach Sibyl Labs to verify your account: {type(e).__name__}",
+        ) from e
+
+
+# ----------------------------------------------------------------------
+# Cap gate
+# ----------------------------------------------------------------------
+
+class CapGate:
+    """Orchestrates the cap check across the SDK write paths.
+
+    Args:
+        account_id: the account_id from credentials.json (None for
+            unactivated users; the gate behaves as free tier with no
+            server check capability)
+        session_token: bearer token sent with the check-write call
+        db_size_fn: callable returning the current SQLite db size in bytes
+        local_tier_hint: initial tier from credentials.json (advisory; the
+            server's answer always wins when we have one)
+        cache: TierCache instance (defaults to ~/.sibyl-memory/tier_cache.json)
+        check_url: full URL to the check-write endpoint
+        check_fn: pluggable transport (default: stdlib urllib)
+    """
+
+    def __init__(
+        self,
+        *,
+        account_id: str | None,
+        session_token: str | None,
+        db_size_fn: Callable[[], int],
+        local_tier_hint: str = "free",
+        cache: TierCache | None = None,
+        check_url: str = DEFAULT_CHECK_WRITE_URL,
+        check_fn: Callable[..., dict[str, Any]] | None = None,
+        cap_bytes: int = FREE_TIER_CAP_BYTES,
+        credentials_claim: dict[str, Any] | None = None,
+        credentials_signature: str | None = None,
+    ) -> None:
+        self.account_id = account_id
+        self.session_token = session_token
+        self._db_size_fn = db_size_fn
+        self._local_hint = local_tier_hint
+        self._cache = cache if cache is not None else TierCache()
+        self._check_url = check_url
+        self._check_fn = check_fn or _default_check_write_fn
+        self._cap = cap_bytes
+        # HMAC signature + the claim it commits to. When both are present,
+        # the server can verify and log mismatches as tamper-suspected
+        # telemetry. Authoritative tier always comes from the DB regardless
+        # — these fields are advisory, defense in depth only.
+        self._credentials_claim = credentials_claim
+        self._credentials_signature = credentials_signature
+
+    # ------------------------------------------------------------------
+    # Public entry point — called by every write path
+    # ------------------------------------------------------------------
+    def check(self, proposed_delta_bytes: int = 0) -> None:
+        """Verify that the proposed write is permitted. Raises
+        CapExceededError if not."""
+        # Fast path 1: locally hinted as paid AND we have a fresh cache
+        # that agrees → allow without network.
+        cached = self._cache.load()
+        if cached and cached.is_fresh and cached.account_id == self.account_id:
+            if cached.cap_bytes is None:
+                # Cached as paid (uncapped) within grace window — allow
+                return
+            # Cached as free with a cap. Enforce locally.
+            new_size = self._db_size_fn() + proposed_delta_bytes
+            if new_size <= cached.cap_bytes:
+                return
+            # Over the cached cap. Try to refresh (user may have upgraded).
+            return self._refresh_and_check(proposed_delta_bytes)
+
+        # No fresh cache. Use the credentials.json hint as a fast path
+        # for the "obviously under cap" case to avoid a server call for
+        # every brand-new user's first writes.
+        current = self._db_size_fn()
+        new_size = current + proposed_delta_bytes
+        if self._local_hint in PAID_TIERS:
+            # Credentials say paid; verify with server then cache the result.
+            # If user genuinely paid: server confirms, we cache, done. If
+            # credentials are tampered: server says free, we cache, enforce.
+            return self._refresh_and_check(proposed_delta_bytes)
+        if new_size <= self._cap:
+            # Free + under cap. Trust the credentials hint, no server call.
+            return
+        # Free + at/past cap → must call server.
+        return self._refresh_and_check(proposed_delta_bytes)
+
+    # ------------------------------------------------------------------
+    # Network refresh
+    # ------------------------------------------------------------------
+    def _refresh_and_check(self, proposed_delta_bytes: int) -> None:
+        if not self.account_id or not self.session_token:
+            # Pre-activation user trying to write past the cap. They never
+            # had a binding; we can't verify a tier they don't have.
+            current = self._db_size_fn()
+            new_size = current + proposed_delta_bytes
+            if new_size <= self._cap:
+                return
+            raise CapExceededError(
+                "You're at the 2 MB free-tier cap and your account isn't "
+                "activated. Run `sibyl init` to activate, or stay under "
+                "the cap.",
+                current_size=current,
+                cap=self._cap,
+                proposed_delta=proposed_delta_bytes,
+            )
+
+        current = self._db_size_fn()
+        payload = {
+            "account_id": self.account_id,
+            "session_token": self.session_token,
+            "current_size_bytes": current,
+            "proposed_delta_bytes": proposed_delta_bytes,
+        }
+        # Attach signed-credentials claim if we have one. Server uses it for
+        # tamper telemetry; the decision itself is unaffected.
+        if self._credentials_signature and self._credentials_claim:
+            payload["credentials_signature"] = self._credentials_signature
+            payload["credentials_claim"] = self._credentials_claim
+
+        try:
+            resp = self._check_fn(self._check_url, payload)
+        except TierVerificationError:
+            # Offline. Fall back to the most recent cache if we have one,
+            # even if technically expired (within an extended grace window
+            # of double the normal period — i.e., 14 days for tier=free).
+            #
+            # T1-4 fix: respect server-supplied subscription expiry on the
+            # offline path. The cache can no longer be honored past the
+            # actual subscription end-of-validity even if the user
+            # blackholes /api/plugin/check-write. Subscription expiry is
+            # authoritative, not a refresh-able grace window.
+            cached = self._cache.load()
+            if cached and cached.account_id == self.account_id:
+                now = time.time()
+                if cached.server_expires_at is not None and now >= cached.server_expires_at:
+                    raise  # subscription already expired per server's own record
+                age = now - cached.checked_at
+                if age < 2 * GRACE_PERIOD_SECONDS:
+                    # Honor the cached result a bit longer for honest
+                    # offline users.
+                    if cached.cap_bytes is None:
+                        return
+                    new_size = current + proposed_delta_bytes
+                    if new_size <= cached.cap_bytes:
+                        return
+            raise  # re-raise TierVerificationError; SDK will surface to caller
+
+        # Got a response. Update the cache.
+        ok = bool(resp.get("ok"))
+        tier = resp.get("tier", "free")
+        cap_bytes = resp.get("cap_bytes") if "cap_bytes" in resp else (
+            None if tier in PAID_TIERS else self._cap
+        )
+        # T1-4 anchor: capture server-supplied subscription expiry so the
+        # cache cannot be honored past actual end-of-validity, even if the
+        # user blackholes the network. Server returns ISO string; parse if
+        # present.
+        server_expires_at: float | None = None
+        raw_exp = resp.get("expires_at")
+        if raw_exp:
+            try:
+                from datetime import datetime, timezone
+                server_expires_at = datetime.fromisoformat(
+                    raw_exp.replace("Z", "+00:00")
+                ).astimezone(timezone.utc).timestamp()
+            except (ValueError, TypeError):
+                server_expires_at = None
+        entry = TierCacheEntry(
+            account_id=self.account_id,
+            tier=tier,
+            checked_at=time.time(),
+            cap_bytes=cap_bytes,
+            last_known_size=current,
+            server_expires_at=server_expires_at,
+            # Cache token = the credentials signature we hold (defense-in-depth
+            # link between cache and credentials.json identity). Server can
+            # cross-check on next /check-write call.
+            cache_token=self._credentials_signature,
+        )
+        self._cache.store(entry)
+
+        if ok:
+            return  # server permitted the write
+        # Server rejected — typically free tier over cap.
+        raise CapExceededError(
+            f"Your {tier} tier doesn't permit this write. "
+            f"Current memory size: {current / 1024:.1f} KB. "
+            f"Cap: {(cap_bytes or self._cap) / 1024:.1f} KB.",
+            current_size=current,
+            cap=cap_bytes or self._cap,
+            proposed_delta=proposed_delta_bytes,
+            upgrade_url=resp.get("upgrade_url", DEFAULT_UPGRADE_URL),
+        )
+
+    # ------------------------------------------------------------------
+    # Helpers
+    # ------------------------------------------------------------------
+    def invalidate_cache(self) -> None:
+        """Forget any cached tier result. Next write at the cap will refetch."""
+        self._cache.clear()
+
+    def current_cap(self) -> int | None:
+        """Return the current effective cap. None = uncapped."""
+        cached = self._cache.load()
+        if cached and cached.is_fresh:
+            return cached.cap_bytes
+        if self._local_hint in PAID_TIERS:
+            return None
+        return self._cap

sibyl-memory-client/src/sibyl_memory_client/client.py

@@ -0,0 +1,896 @@
+"""MemoryClient: the public API for sibyl-memory-client.
+
+Polymorphic constructor: open by local path OR by hosted-tier URL (v2+, not
+implemented yet). The local-first plugin v1 only uses the local path.
+
+The API surface mirrors the canonical sibyl_memory.* table shape so callers
+can move between local-SQLite-backed and Postgres-backed clients without
+re-learning the model.
+"""
+from __future__ import annotations
+
+import sqlite3
+from pathlib import Path
+from typing import Any
+
+from .exceptions import NotFoundError, StorageError, TenantError, ValidationError
+from .storage import Storage, dumps, loads, new_id, _utc_now_iso
+
+
+# ----------------------------------------------------------------------
+# Identifier validation (v0.4.0, KAPPA YELLOW finding)
+# ----------------------------------------------------------------------
+# Entity names, state keys, and reference doc keys are user-supplied
+# identifiers. SQL is parameterized everywhere so injection is closed today,
+# but null bytes break downstream consumers (logs, exports, CLI display),
+# empty strings are nonsense as primary keys, and unbounded length is a
+# latent vector if any code path ever spills to filesystem. Validate on
+# WRITE only — reads of already-stored bad identifiers still work so users
+# can introspect and migrate.
+
+_IDENT_MAX_LENGTH = 1024
+
+# Control chars (0x00-0x1F + DEL) are rejected. Tab/newline/CR included by
+# design: identifiers are short single-line strings, not arbitrary payloads.
+_IDENT_FORBIDDEN_CODE_POINTS = frozenset(range(0, 0x20)) | {0x7F}
+
+
+def validate_identifier(value: Any, *, field_name: str) -> str:
+    """Validate a user-supplied identifier (entity name, state key, etc.).
+
+    Rejects: non-string, empty, control characters / null bytes, length > 1024.
+
+    Args:
+        value: the identifier to validate.
+        field_name: name of the field for error messages.
+
+    Returns: the validated string (unchanged on success).
+    Raises: ValidationError on rejection, with a recovery hint.
+    """
+    if not isinstance(value, str):
+        raise ValidationError(
+            f"{field_name} must be a string (got {type(value).__name__})",
+            recovery=f"Pass a non-empty string for {field_name}.",
+        )
+    if not value:
+        raise ValidationError(
+            f"{field_name} cannot be empty",
+            recovery=f"Pass a non-empty string for {field_name}.",
+        )
+    if len(value) > _IDENT_MAX_LENGTH:
+        raise ValidationError(
+            f"{field_name} too long ({len(value)} chars, max {_IDENT_MAX_LENGTH})",
+            recovery=f"Use a shorter {field_name} (under {_IDENT_MAX_LENGTH} chars).",
+        )
+    for ch in value:
+        if ord(ch) in _IDENT_FORBIDDEN_CODE_POINTS:
+            raise ValidationError(
+                f"{field_name} contains a forbidden control character "
+                f"(code point 0x{ord(ch):02x} at index {value.index(ch)})",
+                recovery=(
+                    f"Identifiers must be printable single-line strings. "
+                    f"Remove control characters / null bytes / tabs / newlines."
+                ),
+            )
+    return value
+
+
+# ----------------------------------------------------------------------
+# FTS5 error surface (v0.4.0, KAPPA YELLOW finding)
+# ----------------------------------------------------------------------
+# Previously search() and search_entities() silently swallowed
+# sqlite3.OperationalError into `return []` / `pass`. KAPPA's complaint:
+# "a user has no signal whether their query was malformed or just genuinely
+# returned nothing." Now we classify: schema-missing → silent (defensive
+# against partial init), FTS5-syntax-error → ValidationError (caller bug),
+# anything else → StorageError (real backend issue).
+
+# Substrings that mark FTS5 query syntax errors. Matched case-insensitively
+# against str(OperationalError). Curated against the actual messages SQLite
+# emits in 3.38+ for FTS5 parse failures.
+_FTS5_QUERY_ERROR_MARKERS = (
+    "fts5",
+    "malformed match",
+    "syntax error near",
+    "no such column",
+)
+
+# Substring marking the schema-missing case — keep silent (return empty)
+# for defense against partial schema state on very old DBs.
+_SCHEMA_MISSING_MARKER = "no such table"
+
+
+def _classify_fts5_error(err: sqlite3.OperationalError) -> Exception | None:
+    """Translate an FTS5-related sqlite OperationalError.
+
+    Returns:
+        None  → schema-missing case; caller should treat as empty results.
+        ValidationError  → user-visible query syntax problem; raise.
+        StorageError  → real backend issue; raise.
+    """
+    msg = str(err).lower()
+    if _SCHEMA_MISSING_MARKER in msg:
+        return None  # defensive: schema partially applied, return empty
+    if any(marker in msg for marker in _FTS5_QUERY_ERROR_MARKERS):
+        return ValidationError(
+            f"FTS5 rejected the search query: {err}",
+            recovery=(
+                "The query passed sanitization but the FTS5 engine still "
+                "rejected it. Pass plain text or simple word tokens; FTS5 "
+                "operator syntax (NEAR, AND/OR/NOT, column filters) is "
+                "treated as literal text after sanitization."
+            ),
+        )
+    return StorageError(
+        f"SQLite error during FTS5 search: {err}",
+        recovery=(
+            "Backend error. Check disk space, file permissions, and that "
+            "the schema is intact. See exception chain for the underlying "
+            "sqlite3 message."
+        ),
+    )
+
+
+# ----------------------------------------------------------------------
+# FTS5 query sanitization
+# ----------------------------------------------------------------------
+# v0.3.3 hardens search() / search_entities() against FTS5 injection + DoS
+# (audit SEC-3). User input is wrapped as a single quoted FTS5 phrase so
+# column-filter syntax (`name:`, `category:`, `rowid:`, etc.) and unclosed
+# quotes can't escape into the FTS5 parser. Caller can still get prefix
+# matching by passing prefix=True.
+
+# Column names + FTS5 reserved operators we reject if they appear unquoted.
+_FTS5_COLUMN_TOKENS = frozenset({"name", "category", "body", "tenant_id",
+                                  "entity_id", "document_key", "doc_key",
+                                  "payload", "ts", "rowid"})
+
+
+def _sanitize_fts5_query(raw: str, *, prefix: bool = False) -> str:
+    """Wrap a user query as a safe FTS5 MATCH expression.
+
+    Two modes:
+      - Default (``prefix=False``): wrap the entire input as a single
+        double-quoted phrase. FTS5 treats `"a b c"` as a phrase match;
+        operators (AND/OR/NOT/NEAR/^/+/-) and column filters (`name:foo`)
+        inside the quotes are literal text. Internal double-quotes are
+        doubled per FTS5 escape rules. Safe against injection / DoS.
+      - Prefix (``prefix=True``): strip the input to alphanumeric +
+        underscore tokens, join with spaces, and append `*` to the last
+        token for prefix matching. FTS5 does NOT support prefix on
+        quoted phrases (`"phrase"*` is invalid syntax) so we use bare
+        tokens here. The character filter still blocks operator injection.
+
+    Empty / whitespace-only queries return an empty string — callers
+    should short-circuit on empty.
+    """
+    if not raw or not isinstance(raw, str):
+        return ""
+    s = raw.strip()
+    if not s:
+        return ""
+    # Strip control characters that could confuse the FTS5 tokenizer
+    s = "".join(ch for ch in s if ch.isprintable() or ch in (" ", "\t"))
+    if not s.strip():
+        return ""
+
+    if prefix:
+        # Reduce to safe bare tokens — alphanumeric + underscore only.
+        # Anything else (quotes, colons, hyphens, FTS5 operators) becomes
+        # a space, then we split-and-rejoin to get clean whitespace.
+        cleaned = "".join(ch if (ch.isalnum() or ch == "_") else " " for ch in s)
+        tokens = [t for t in cleaned.split() if t]
+        if not tokens:
+            return ""
+        if len(tokens) == 1:
+            return f"{tokens[0]}*"
+        # Multiple tokens: all earlier tokens are literal, the last gets `*`.
+        return " ".join(tokens[:-1]) + f" {tokens[-1]}*"
+
+    # Default: single quoted phrase. Escape embedded double-quotes.
+    escaped = s.replace('"', '""')
+    return f'"{escaped}"'
+
+# The default tenant for single-user local installs.
+DEFAULT_TENANT = "00000000-0000-0000-0000-000000000001"
+
+
+def _check_json(payload: Any, field: str = "body") -> str:
+    """Validate that payload is JSON-serializable, return the encoded string."""
+    try:
+        return dumps(payload)
+    except (TypeError, ValueError) as e:
+        raise ValidationError(
+            f"{field} is not JSON-serializable: {e}",
+            recovery=f"Pass a dict, list, or JSON primitive as {field}.",
+        ) from e
+
+
+class MemoryClient:
+    """Single canonical interface for reading and writing Sibyl Memory state."""
+
+    # Paid-tier-only features. Free tier raises TierGateError; upgrading to any
+    # paid tier unlocks both self-learning and the memory linter.
+    _PAID_ONLY_TIERS = frozenset({"sync", "team", "lifetime", "stake", "enterprise"})
+
+    def __init__(
+        self,
+        storage: Storage,
+        *,
+        tenant_id: str = DEFAULT_TENANT,
+        tier: str = "free",
+        account_id: str | None = None,
+        session_token: str | None = None,
+        cap_gate: Any = None,
+        credentials_claim: dict[str, Any] | None = None,
+        credentials_signature: str | None = None,
+    ) -> None:
+        self._storage = storage
+        self._tenant_id = tenant_id
+        self._tier = tier
+        self._account_id = account_id
+        self._session_token = session_token
+
+        # Cap gate — enforces the 2 MB free-tier cap with server-authoritative
+        # tier verification at the boundary. See _capcheck.py for the design.
+        if cap_gate is None:
+            from ._capcheck import CapGate, TierCache
+            cap_gate = CapGate(
+                account_id=account_id,
+                session_token=session_token,
+                db_size_fn=lambda: (
+                    Path(storage.db_path).stat().st_size
+                    if Path(storage.db_path).exists() else 0
+                ),
+                local_tier_hint=tier,
+                cache=TierCache(
+                    Path(storage.db_path).parent / "tier_cache.json"
+                ),
+                credentials_claim=credentials_claim,
+                credentials_signature=credentials_signature,
+            )
+        self._cap_gate = cap_gate
+
+    # ------------------------------------------------------------------
+    # Constructors
+    # ------------------------------------------------------------------
+    @classmethod
+    def local(
+        cls,
+        path: str | Path = "~/.sibyl-memory/memory.db",
+        *,
+        tenant_id: str = DEFAULT_TENANT,
+        tier: str = "free",
+        account_id: str | None = None,
+        session_token: str | None = None,
+        credentials_claim: dict[str, Any] | None = None,
+        credentials_signature: str | None = None,
+    ) -> "MemoryClient":
+        """Open a local SQLite-backed MemoryClient.
+
+        The directory at ``path``'s parent is created with mode 0700 if
+        missing. The schema is applied on first open and is idempotent.
+
+        Set ``tier`` to the user's plugin tier so paid-only features
+        (self-learning + memory linter) gate correctly. Defaults to "free".
+
+        Pass ``account_id`` and ``session_token`` from credentials.json so
+        the SDK can verify the user's tier against the server when they
+        approach the 2 MB free-tier cap. Without these, the SDK enforces
+        a strict local 2 MB cap (no server check possible).
+        """
+        storage = Storage(path)
+        return cls(
+            storage,
+            tenant_id=tenant_id,
+            tier=tier,
+            account_id=account_id,
+            session_token=session_token,
+            credentials_claim=credentials_claim,
+            credentials_signature=credentials_signature,
+        )
+
+    # ------------------------------------------------------------------
+    # Tenant management
+    # ------------------------------------------------------------------
+    def get_tenant(self) -> str:
+        return self._tenant_id
+
+    def set_tenant(self, tenant_id: str) -> None:
+        if not tenant_id or not isinstance(tenant_id, str):
+            raise TenantError("tenant_id must be a non-empty string")
+        self._tenant_id = tenant_id
+
+    @property
+    def storage(self) -> Storage:
+        return self._storage
+
+    def schema_version(self) -> int | None:
+        return self._storage.schema_version()
+
+    # ------------------------------------------------------------------
+    # Tier (paid-tier-only feature gating)
+    # ------------------------------------------------------------------
+    def get_tier(self) -> str:
+        return self._tier
+
+    def set_tier(self, tier: str) -> None:
+        """Update the user's tier. Called by the credentials loader when
+        the activation flow returns a tier upgrade."""
+        if not isinstance(tier, str) or not tier:
+            raise ValidationError("tier must be a non-empty string")
+        self._tier = tier
+
+    def _require_paid_tier(self, feature: str) -> None:
+        """Raise TierGateError if the current tier is not paid-tier."""
+        from .exceptions import TierGateError
+        if self._tier not in self._PAID_ONLY_TIERS:
+            raise TierGateError(
+                f"{feature} requires a paid tier. Current tier: {self._tier!r}.",
+                feature=feature,
+                current_tier=self._tier,
+            )
+
+    # ------------------------------------------------------------------
+    # Entities (WARM tier) — single source of truth per rule 43
+    # ------------------------------------------------------------------
+    def set_entity(
+        self,
+        category: str,
+        name: str,
+        body: dict[str, Any] | list[Any],
+        *,
+        status: str | None = None,
+    ) -> dict[str, Any]:
+        """Insert or update an entity.
+
+        UNIQUE (tenant_id, category, name) is enforced at the DB level. On
+        conflict the existing row is updated (body + status + updated_at).
+        Returns the resulting entity row as a dict.
+
+        Subject to the 2 MB free-tier cap when tier='free'. Raises
+        CapExceededError if the write would push the local DB past the cap
+        and the server-authoritative tier check confirms the account is
+        still free.
+
+        v0.4.0: category and name are validated as identifiers (non-empty
+        string, no control characters, length <= 1024). Raises
+        ValidationError on rejection."""
+        validate_identifier(category, field_name="category")
+        validate_identifier(name, field_name="name")
+        body_json = _check_json(body)
+        # Cap gate — rough byte estimate (FTS5 + indexes add overhead)
+        self._cap_gate.check(proposed_delta_bytes=len(body_json) + len(name) + len(category) + 200)
+        with self._storage.transaction() as conn:
+            existing = conn.execute(
+                "SELECT id FROM entities WHERE tenant_id = ? AND category = ? AND name = ?",
+                (self._tenant_id, category, name),
+            ).fetchone()
+            if existing is None:
+                ent_id = new_id()
+                conn.execute(
+                    "INSERT INTO entities (id, tenant_id, category, name, status, body) "
+                    "VALUES (?, ?, ?, ?, ?, ?)",
+                    (ent_id, self._tenant_id, category, name, status, body_json),
+                )
+            else:
+                ent_id = existing["id"]
+                conn.execute(
+                    "UPDATE entities SET status = ?, body = ?, "
+                    "updated_at = strftime('%Y-%m-%dT%H:%M:%fZ', 'now') "
+                    "WHERE id = ?",
+                    (status, body_json, ent_id),
+                )
+        return self.get_entity(category, name)
+
+    def get_entity(self, category: str, name: str) -> dict[str, Any]:
+        with self._storage.connection() as conn:
+            row = conn.execute(
+                "SELECT id, tenant_id, category, name, status, body, created_at, updated_at "
+                "FROM entities WHERE tenant_id = ? AND category = ? AND name = ?",
+                (self._tenant_id, category, name),
+            ).fetchone()
+        if row is None:
+            raise NotFoundError(f"entity {category}/{name} not found for tenant {self._tenant_id}")
+        return self._row_to_entity(row)
+
+    def list_entities(
+        self,
+        category: str | None = None,
+        *,
+        status: str | None = None,
+        limit: int = 100,
+    ) -> list[dict[str, Any]]:
+        sql = "SELECT id, tenant_id, category, name, status, body, created_at, updated_at FROM entities WHERE tenant_id = ?"
+        params: list[Any] = [self._tenant_id]
+        if category is not None:
+            sql += " AND category = ?"
+            params.append(category)
+        if status is not None:
+            sql += " AND status = ?"
+            params.append(status)
+        sql += " ORDER BY updated_at DESC LIMIT ?"
+        params.append(limit)
+        with self._storage.connection() as conn:
+            rows = conn.execute(sql, params).fetchall()
+        return [self._row_to_entity(r) for r in rows]
+
+    def delete_entity(self, category: str, name: str) -> bool:
+        with self._storage.transaction() as conn:
+            cur = conn.execute(
+                "DELETE FROM entities WHERE tenant_id = ? AND category = ? AND name = ?",
+                (self._tenant_id, category, name),
+            )
+        return cur.rowcount > 0
+
+    # ------------------------------------------------------------------
+    # State documents (HOT tier)
+    # ------------------------------------------------------------------
+    def set_state(self, key: str, body: dict[str, Any] | list[Any]) -> None:
+        """Insert or update a HOT-tier state document.
+
+        v0.4.0: ``key`` is validated as an identifier (non-empty string, no
+        control characters, length <= 1024). Raises ValidationError on
+        rejection."""
+        validate_identifier(key, field_name="key")
+        body_json = _check_json(body)
+        self._cap_gate.check(proposed_delta_bytes=len(body_json) + len(key) + 150)
+        with self._storage.transaction() as conn:
+            conn.execute(
+                "INSERT INTO state_documents (tenant_id, document_key, body) VALUES (?, ?, ?) "
+                "ON CONFLICT(tenant_id, document_key) DO UPDATE SET body = excluded.body, "
+                "updated_at = strftime('%Y-%m-%dT%H:%M:%fZ', 'now')",
+                (self._tenant_id, key, body_json),
+            )
+
+    def get_state(self, key: str) -> dict[str, Any] | None:
+        with self._storage.connection() as conn:
+            row = conn.execute(
+                "SELECT body, updated_at FROM state_documents WHERE tenant_id = ? AND document_key = ?",
+                (self._tenant_id, key),
+            ).fetchone()
+        if row is None:
+            return None
+        return {"body": loads(row["body"]), "updated_at": row["updated_at"]}
+
+    # ------------------------------------------------------------------
+    # Journal (COLD tier) — append-only event log
+    # ------------------------------------------------------------------
+    def write_event(
+        self,
+        *,
+        evaluated: Any = None,
+        acted: Any = None,
+        forward: Any = None,
+        extra: Any = None,
+        ts: str | None = None,
+    ) -> str:
+        # Estimate byte cost from each non-None payload
+        delta = 200  # row + index overhead
+        for payload in (evaluated, acted, forward, extra):
+            if payload is not None:
+                try:
+                    delta += len(dumps(payload))
+                except (TypeError, ValueError):
+                    delta += 100  # estimate; the JSON check below will catch real failures
+        self._cap_gate.check(proposed_delta_bytes=delta)
+        ev_id = new_id()
+        with self._storage.transaction() as conn:
+            conn.execute(
+                "INSERT INTO journal_events (id, tenant_id, ts, evaluated, acted, forward, extra) "
+                "VALUES (?, ?, ?, ?, ?, ?, ?)",
+                (
+                    ev_id,
+                    self._tenant_id,
+                    ts or _utc_now_iso(),
+                    _check_json(evaluated, "evaluated") if evaluated is not None else None,
+                    _check_json(acted, "acted") if acted is not None else None,
+                    _check_json(forward, "forward") if forward is not None else None,
+                    _check_json(extra, "extra") if extra is not None else None,
+                ),
+            )
+        return ev_id
+
+    def read_events(
+        self,
+        *,
+        limit: int = 50,
+        since: str | None = None,
+        until: str | None = None,
+    ) -> list[dict[str, Any]]:
+        sql = "SELECT id, tenant_id, ts, evaluated, acted, forward, extra FROM journal_events WHERE tenant_id = ?"
+        params: list[Any] = [self._tenant_id]
+        if since is not None:
+            sql += " AND ts >= ?"
+            params.append(since)
+        if until is not None:
+            sql += " AND ts <= ?"
+            params.append(until)
+        sql += " ORDER BY ts DESC, id DESC LIMIT ?"
+        params.append(limit)
+        with self._storage.connection() as conn:
+            rows = conn.execute(sql, params).fetchall()
+        return [
+            {
+                "id": r["id"],
+                "ts": r["ts"],
+                "evaluated": loads(r["evaluated"]),
+                "acted": loads(r["acted"]),
+                "forward": loads(r["forward"]),
+                "extra": loads(r["extra"]),
+            }
+            for r in rows
+        ]
+
+    # ------------------------------------------------------------------
+    # Reference (REFERENCE tier) — static lookup documents
+    # ------------------------------------------------------------------
+    def set_reference(
+        self,
+        key: str,
+        body: str,
+        *,
+        metadata: dict[str, Any] | None = None,
+    ) -> None:
+        """Insert or update a REFERENCE-tier document.
+
+        v0.4.0: ``key`` is validated as an identifier (non-empty string, no
+        control characters, length <= 1024). Raises ValidationError on
+        rejection."""
+        validate_identifier(key, field_name="key")
+        meta_json = _check_json(metadata, "metadata") if metadata is not None else None
+        delta = len(body) + len(key) + (len(meta_json) if meta_json else 0) + 200
+        self._cap_gate.check(proposed_delta_bytes=delta)
+        with self._storage.transaction() as conn:
+            conn.execute(
+                "INSERT INTO reference_documents (tenant_id, doc_key, body, metadata) VALUES (?, ?, ?, ?) "
+                "ON CONFLICT(tenant_id, doc_key) DO UPDATE SET body = excluded.body, "
+                "metadata = excluded.metadata, updated_at = strftime('%Y-%m-%dT%H:%M:%fZ', 'now')",
+                (self._tenant_id, key, body, meta_json),
+            )
+
+    def get_reference(self, key: str) -> dict[str, Any] | None:
+        with self._storage.connection() as conn:
+            row = conn.execute(
+                "SELECT body, metadata, updated_at FROM reference_documents WHERE tenant_id = ? AND doc_key = ?",
+                (self._tenant_id, key),
+            ).fetchone()
+        if row is None:
+            return None
+        return {"body": row["body"], "metadata": loads(row["metadata"]), "updated_at": row["updated_at"]}
+
+    # ------------------------------------------------------------------
+    # Archive
+    # ------------------------------------------------------------------
+    def archive_entity(self, category: str, name: str, reason: str | None = None) -> dict[str, Any]:
+        """Move an entity to the archive table and delete from the active set.
+
+        T1-3 fix: previously this bypassed the cap-gate. A free user at
+        1.9 MB could archive their largest entities (body copied into
+        archived_entities, doubling footprint temporarily before the
+        DELETE lands) to keep writing past the 2 MB cap. Now gated on
+        the size of the body being copied + 200 bytes overhead. Reads
+        the body first so we know the actual delta. NotFoundError still
+        raised before any cap-gate work.
+        """
+        # Read the row first so we can size the archive insert. NotFoundError
+        # propagates as before — no cap-gate side effect for missing entities.
+        with self._storage.connection() as conn:
+            preview = conn.execute(
+                "SELECT id, body FROM entities WHERE tenant_id = ? AND category = ? AND name = ?",
+                (self._tenant_id, category, name),
+            ).fetchone()
+        if preview is None:
+            raise NotFoundError(f"entity {category}/{name} not found")
+        body_bytes = len(preview["body"] or "") if preview["body"] else 0
+        # The archive insert copies the body. Delta = body + name + category
+        # + reason + ~200B SQLite/row overhead. Conservative estimate.
+        delta = body_bytes + len(name) + len(category) + len(reason or "") + 200
+        self._cap_gate.check(proposed_delta_bytes=delta)
+
+        with self._storage.transaction() as conn:
+            row = conn.execute(
+                "SELECT id, body FROM entities WHERE tenant_id = ? AND category = ? AND name = ?",
+                (self._tenant_id, category, name),
+            ).fetchone()
+            if row is None:
+                raise NotFoundError(f"entity {category}/{name} not found")
+            arch_id = new_id()
+            conn.execute(
+                "INSERT INTO archived_entities (id, tenant_id, original_entity_id, category, name, body, archive_reason) "
+                "VALUES (?, ?, ?, ?, ?, ?, ?)",
+                (arch_id, self._tenant_id, row["id"], category, name, row["body"], reason),
+            )
+            conn.execute("DELETE FROM entities WHERE id = ?", (row["id"],))
+        return {"archived_id": arch_id, "original_id": row["id"]}
+
+    # ------------------------------------------------------------------
+    # Self-learning + lint (v0.2.0) — paid-tier only
+    # ------------------------------------------------------------------
+    # Both convenience entrypoints below gate on tier and raise
+    # TierGateError for free-tier callers. The underlying Learner / Linter
+    # classes remain available for power users via direct import, but
+    # the documented surface is the gated convenience API.
+
+    def learner(self, **kwargs: Any):
+        """Return a Learner bound to this client's storage + tenant.
+
+        Paid-tier only. Lazy import so the lower SDK stays usable without
+        loading the learning module. Threads the client's CapGate into
+        the Learner so accept_proposal calls go through the cap-check
+        (T1-3 fix). Callers can override cap_gate=None explicitly to
+        opt out for tests."""
+        self._require_paid_tier("self-learning")
+        from .learning import Learner
+        kwargs.setdefault("cap_gate", self._cap_gate)
+        return Learner(self._storage, tenant_id=self._tenant_id, **kwargs)
+
+    def learn(self, **kwargs: Any):
+        """Convenience: construct a default Learner and run one pass.
+        Returns a LearningRunReport. Paid-tier only."""
+        return self.learner(**kwargs).run()
+
+    def list_skill_proposals(
+        self, *, status: str = "pending", limit: int = 50,
+    ) -> list[Any]:
+        """Paid-tier only."""
+        return self.learner().list_proposals(status=status, limit=limit)
+
+    def accept_skill_proposal(
+        self, proposal_id: str, *, note: str | None = None,
+    ) -> dict[str, Any]:
+        """Paid-tier only."""
+        return self.learner().accept_proposal(proposal_id, note=note)
+
+    def reject_skill_proposal(
+        self, proposal_id: str, *, note: str | None = None,
+    ) -> dict[str, Any]:
+        """Paid-tier only."""
+        return self.learner().reject_proposal(proposal_id, note=note)
+
+    def lint(self, **kwargs: Any):
+        """Run the local memory linter against this tenant. Returns a
+        LintReport with `.findings`, `.counts`, `.ok`, and `.to_ascii()`.
+
+        Paid-tier only. Free-tier callers raise TierGateError pointing at
+        the upgrade page.
+        """
+        self._require_paid_tier("memory linter")
+        from .lint import Linter
+        # If the caller didn't supply soft_cap_bytes, look up by tier
+        if "soft_cap_bytes" not in kwargs:
+            from .lint import TIER_SOFT_CAPS, DEFAULT_SOFT_CAP_BYTES
+            cap = TIER_SOFT_CAPS.get(self._tier, DEFAULT_SOFT_CAP_BYTES)
+            # Paid tiers map to None — pass a huge cap so the check effectively never fires
+            kwargs["soft_cap_bytes"] = cap if cap is not None else (1 << 62)
+        return Linter(self._storage, tenant_id=self._tenant_id, **kwargs).run()
+
+    # ------------------------------------------------------------------
+    # Free-tier read access (no gating) — visibility into the upgrade pressure
+    # ------------------------------------------------------------------
+    def free_tier_status(self) -> dict[str, Any]:
+        """Return current free-tier state: DB size, soft cap, % used.
+
+        Always available regardless of tier — free-tier callers use this
+        to render the "you're at X% of your free cap" upgrade prompt
+        without needing to call the (gated) linter.
+        """
+        from .lint import TIER_SOFT_CAPS, DEFAULT_SOFT_CAP_BYTES
+        from pathlib import Path
+        db_size = Path(self._storage.db_path).stat().st_size if Path(self._storage.db_path).exists() else 0
+        cap = TIER_SOFT_CAPS.get(self._tier, DEFAULT_SOFT_CAP_BYTES)
+        # Paid tier → no cap
+        if cap is None:
+            return {
+                "tier": self._tier,
+                "db_size_bytes": db_size,
+                "soft_cap_bytes": None,
+                "pct_used": None,
+                "uncapped": True,
+            }
+        return {
+            "tier": self._tier,
+            "db_size_bytes": db_size,
+            "soft_cap_bytes": cap,
+            "pct_used": db_size / cap if cap else None,
+            "uncapped": False,
+            "at_or_above_warning": db_size >= 0.8 * cap,
+            "at_or_above_cap": db_size >= cap,
+            "upgrade_url": "https://sibyllabs.org/plugin#tier",
+        }
+
+    # ------------------------------------------------------------------
+    # FTS5 search
+    # ------------------------------------------------------------------
+    def search_entities(self, query: str, *, limit: int = 20, prefix: bool = False) -> list[dict[str, Any]]:
+        """Full-text search over entity name + category + body via FTS5.
+
+        Returns warm-tier entity rows only. For cross-tier search (entities +
+        state + reference + journal in one call), use ``search()``.
+
+        Query is sanitized as a single FTS5 phrase — column-filter syntax
+        (``name:foo``) and unclosed quotes can't escape into the parser.
+        Set ``prefix=True`` for prefix matching on the final token.
+
+        Returns: list of entity rows. Each row is a dict with keys
+            id, tenant_id, category, name, status, body, created_at, updated_at
+            (body is JSON-deserialized).
+
+        Raises: StorageError on backend failure; empty list on empty / invalid query.
+        """
+        match_q = _sanitize_fts5_query(query, prefix=prefix)
+        if not match_q:
+            return []
+        # external-content FTS5: join by rowid back to base table
+        with self._storage.connection() as conn:
+            try:
+                rows = conn.execute(
+                    "SELECT e.id, e.tenant_id, e.category, e.name, e.status, e.body, e.created_at, e.updated_at "
+                    "FROM entities_fts f "
+                    "JOIN entities e ON e.rowid = f.rowid "
+                    "WHERE entities_fts MATCH ? AND f.tenant_id = ? "
+                    "ORDER BY rank LIMIT ?",
+                    (match_q, self._tenant_id, limit),
+                ).fetchall()
+            except sqlite3.OperationalError as e:
+                # v0.4.0 (KAPPA YELLOW finding): classify the error instead
+                # of silently returning []. Schema-missing → empty (defense
+                # against partial init). FTS5 syntax → ValidationError.
+                # Real backend → StorageError. Re-raise via classifier.
+                exc = _classify_fts5_error(e)
+                if exc is None:
+                    return []
+                raise exc from e
+        return [self._row_to_entity(r) for r in rows]
+
+    def search(self, query: str, *, limit: int = 20, prefix: bool = False,
+               tiers: tuple[str, ...] | None = None) -> list[dict[str, Any]]:
+        """Cross-tier full-text search over entities + state + reference + journal.
+
+        Each hit is tier-tagged so callers know which tier surfaced the match.
+
+        Returns: list of dicts shaped:
+            {
+              "tier":  "entity" | "state" | "reference" | "journal",
+              "key":   <entity name | state key | doc_key | journal id>,
+              "category": <entity category or None>,
+              "body":  <JSON-decoded payload or string>,
+              "snippet": <FTS5 snippet, up to ~120 chars around the match>,
+              "rank":  <FTS5 rank, lower is better>,
+              "ts":    <ISO timestamp — updated_at or journal ts>
+            }
+
+        Ordered by FTS5 rank across the union. The default ``limit`` applies
+        globally (combined across tiers). Pass ``tiers=("entity", "state")``
+        to restrict.
+
+        Query is sanitized as a single FTS5 phrase (see ``search_entities``
+        notes). Empty / invalid queries return [].
+
+        Raises: StorageError on backend failure.
+        """
+        match_q = _sanitize_fts5_query(query, prefix=prefix)
+        if not match_q:
+            return []
+        allowed = set(tiers) if tiers else {"entity", "state", "reference", "journal"}
+        hits: list[dict[str, Any]] = []
+        with self._storage.connection() as conn:
+            # v0.4.0 (KAPPA YELLOW finding): per-tier OperationalError handling
+            # now classifies via _classify_fts5_error. Schema-missing keeps the
+            # previous behavior (skip this tier silently, other tiers continue).
+            # FTS5 syntax / real backend errors raise — the query is bad for
+            # ALL tiers, no point continuing through the union.
+            if "entity" in allowed:
+                try:
+                    for r in conn.execute(
+                        "SELECT 'entity' AS tier, e.name AS key, e.category, e.body, "
+                        "       e.updated_at AS ts, "
+                        "       snippet(entities_fts, 2, '[', ']', '...', 12) AS snip, "
+                        "       rank "
+                        "FROM entities_fts f JOIN entities e ON e.rowid = f.rowid "
+                        "WHERE entities_fts MATCH ? AND f.tenant_id = ? "
+                        "ORDER BY rank LIMIT ?",
+                        (match_q, self._tenant_id, limit),
+                    ).fetchall():
+                        hits.append({
+                            "tier": "entity", "key": r["key"],
+                            "category": r["category"],
+                            "body": loads(r["body"]), "snippet": r["snip"],
+                            "rank": r["rank"], "ts": r["ts"],
+                        })
+                except sqlite3.OperationalError as e:
+                    exc = _classify_fts5_error(e)
+                    if exc is not None:
+                        raise exc from e
+            if "state" in allowed:
+                try:
+                    for r in conn.execute(
+                        "SELECT 'state' AS tier, s.document_key AS key, s.body, "
+                        "       s.updated_at AS ts, "
+                        "       snippet(state_documents_fts, 1, '[', ']', '...', 12) AS snip, "
+                        "       rank "
+                        "FROM state_documents_fts f JOIN state_documents s "
+                        "  ON s.rowid = f.rowid "
+                        "WHERE state_documents_fts MATCH ? AND f.tenant_id = ? "
+                        "ORDER BY rank LIMIT ?",
+                        (match_q, self._tenant_id, limit),
+                    ).fetchall():
+                        hits.append({
+                            "tier": "state", "key": r["key"], "category": None,
+                            "body": loads(r["body"]), "snippet": r["snip"],
+                            "rank": r["rank"], "ts": r["ts"],
+                        })
+                except sqlite3.OperationalError as e:
+                    exc = _classify_fts5_error(e)
+                    if exc is not None:
+                        raise exc from e
+            if "reference" in allowed:
+                try:
+                    for r in conn.execute(
+                        "SELECT 'reference' AS tier, d.doc_key AS key, d.body, "
+                        "       d.updated_at AS ts, "
+                        "       snippet(reference_documents_fts, 1, '[', ']', '...', 12) AS snip, "
+                        "       rank "
+                        "FROM reference_documents_fts f JOIN reference_documents d "
+                        "  ON d.rowid = f.rowid "
+                        "WHERE reference_documents_fts MATCH ? AND f.tenant_id = ? "
+                        "ORDER BY rank LIMIT ?",
+                        (match_q, self._tenant_id, limit),
+                    ).fetchall():
+                        hits.append({
+                            "tier": "reference", "key": r["key"], "category": None,
+                            "body": r["body"], "snippet": r["snip"],
+                            "rank": r["rank"], "ts": r["ts"],
+                        })
+                except sqlite3.OperationalError as e:
+                    exc = _classify_fts5_error(e)
+                    if exc is not None:
+                        raise exc from e
+            if "journal" in allowed:
+                try:
+                    # Journal FTS5 is standalone — fetch the event_id from
+                    # the FTS5 table directly, then join to journal_events
+                    # by id (TEXT PK) for the typed body fields.
+                    for r in conn.execute(
+                        "SELECT 'journal' AS tier, j.id AS key, j.ts, "
+                        "       j.evaluated, j.acted, j.forward, j.extra, "
+                        "       snippet(journal_events_fts, 1, '[', ']', '...', 12) AS snip, "
+                        "       f.rank AS rank "
+                        "FROM journal_events_fts f JOIN journal_events j "
+                        "  ON j.id = f.event_id "
+                        "WHERE journal_events_fts MATCH ? AND f.tenant_id = ? "
+                        "ORDER BY f.rank LIMIT ?",
+                        (match_q, self._tenant_id, limit),
+                    ).fetchall():
+                        hits.append({
+                            "tier": "journal", "key": r["key"], "category": None,
+                            "body": {
+                                "evaluated": loads(r["evaluated"]),
+                                "acted": loads(r["acted"]),
+                                "forward": loads(r["forward"]),
+                                "extra": loads(r["extra"]),
+                            },
+                            "snippet": r["snip"], "rank": r["rank"], "ts": r["ts"],
+                        })
+                except sqlite3.OperationalError as e:
+                    exc = _classify_fts5_error(e)
+                    if exc is not None:
+                        raise exc from e
+        # Sort by rank (lower = better in FTS5) and apply global limit
+        hits.sort(key=lambda h: h["rank"])
+        return hits[:limit]
+
+    # ------------------------------------------------------------------
+    # Helpers
+    # ------------------------------------------------------------------
+    def _row_to_entity(self, row: sqlite3.Row) -> dict[str, Any]:
+        return {
+            "id": row["id"],
+            "tenant_id": row["tenant_id"],
+            "category": row["category"],
+            "name": row["name"],
+            "status": row["status"],
+            "body": loads(row["body"]),
+            "created_at": row["created_at"],
+            "updated_at": row["updated_at"],
+        }

sibyl-memory-client/src/sibyl_memory_client/exceptions.py

@@ -0,0 +1,141 @@
+"""Typed exception hierarchy for sibyl-memory-client.
+
+Every error has a stable `code` for programmatic handling and a `recovery`
+string suggesting what the caller should try next.
+
+v0.4.0 (2026-05-18): `CapExceededError` + `TierVerificationError` relocated
+here from `_capcheck.py` so they are importable from the canonical
+`sibyl_memory_client.exceptions` submodule path (KAPPA bug report against
+sibyl-memory-mcp 0.1.1 — server imported these from `.exceptions` but they
+only lived on `._capcheck`).
+"""
+from __future__ import annotations
+
+
+# Default upgrade URL for cap / tier-related errors. Kept here as a string
+# literal so the exceptions module has no dependency on _capcheck (avoids the
+# circular import that motivated the v0.4.0 reorganization).
+_DEFAULT_UPGRADE_URL = "https://docs.sibyllabs.org/memory/tiers"
+
+
+class SibylMemoryError(Exception):
+    """Base for all sibyl-memory-client errors."""
+
+    code: str = "SIBYL_MEMORY_ERROR"
+    recovery: str = "See exception message for details."
+
+    def __init__(self, message: str, *, recovery: str | None = None) -> None:
+        super().__init__(message)
+        if recovery is not None:
+            self.recovery = recovery
+
+
+class StorageError(SibylMemoryError):
+    code = "STORAGE_ERROR"
+    recovery = "Check disk space and file permissions on ~/.sibyl-memory/."
+
+
+class SchemaError(SibylMemoryError):
+    code = "SCHEMA_ERROR"
+    recovery = "The schema file is missing or corrupt. Re-install sibyl-memory-client."
+
+
+class TenantError(SibylMemoryError):
+    code = "TENANT_ERROR"
+    recovery = "Set a tenant before calling write/read operations: client.set_tenant(uuid)."
+
+
+class NotFoundError(SibylMemoryError):
+    code = "NOT_FOUND"
+    recovery = "The requested entity / state / reference does not exist."
+
+
+class ConflictError(SibylMemoryError):
+    code = "CONFLICT"
+    recovery = "An entity with this (tenant_id, category, name) already exists. Use update_entity() instead."
+
+
+class ValidationError(SibylMemoryError):
+    code = "VALIDATION_ERROR"
+    recovery = "Body must be a JSON-serializable dict / list / primitive."
+
+
+class TierGateError(SibylMemoryError):
+    """Raised when a free-tier user invokes a paid-tier-only feature.
+
+    Carries the user's current tier + an upgrade URL so callers can render
+    a clean prompt. Self-learning + memory linter are both gated by this
+    on the free tier; upgrading to any paid tier unlocks both.
+    """
+
+    code = "TIER_GATE"
+    recovery = (
+        "Upgrade your plugin tier to unlock this feature. See "
+        "https://sibyllabs.org/plugin#tier for options "
+        "(Sibyl Stake / Sync / Lifetime / Enterprise)."
+    )
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        feature: str,
+        current_tier: str = "free",
+        upgrade_url: str = "https://sibyllabs.org/plugin#tier",
+    ) -> None:
+        super().__init__(message)
+        self.feature = feature
+        self.current_tier = current_tier
+        self.upgrade_url = upgrade_url
+
+
+class CapExceededError(SibylMemoryError):
+    """Raised when a free-tier user tries to write past the 2 MB cap.
+
+    Carries the upgrade URL so callers (CLIs, IDEs, agent frameworks) can
+    render a clean upgrade prompt.
+
+    v0.4.0: moved from `_capcheck.py` to `exceptions.py` so the canonical
+    `sibyl_memory_client.exceptions` submodule path exports it. The class
+    contract (code, recovery, current_size, cap, proposed_delta, upgrade_url
+    attributes) is unchanged.
+    """
+
+    code = "CAP_EXCEEDED"
+    recovery = (
+        "Upgrade to remove the 2 MB cap. See "
+        "https://docs.sibyllabs.org/memory/tiers for options "
+        "(Sibyl Stake / Sync / Lifetime / Enterprise)."
+    )
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        current_size: int,
+        cap: int,
+        proposed_delta: int = 0,
+        upgrade_url: str = _DEFAULT_UPGRADE_URL,
+    ) -> None:
+        super().__init__(message)
+        self.current_size = current_size
+        self.cap = cap
+        self.proposed_delta = proposed_delta
+        self.upgrade_url = upgrade_url
+
+
+class TierVerificationError(SibylMemoryError):
+    """Raised when the SDK can't verify the user's tier and has no cached
+    grace period to fall back on (offline at the cap with no recent
+    successful check).
+
+    v0.4.0: moved from `_capcheck.py` to `exceptions.py` so the canonical
+    `sibyl_memory_client.exceptions` submodule path exports it. The class
+    contract (code, recovery) is unchanged.
+    """
+
+    code = "TIER_VERIFY_FAILED"
+    recovery = (
+        "Connect to the internet so the SDK can verify your account, or "
+        "stay under the 2 MB free-tier cap until you're online."
+    )

sibyl-memory-client/src/sibyl_memory_client/learning.py

@@ -0,0 +1,925 @@
+"""Self-learning module for sibyl-memory-client.
+
+Mirrors the way SIBYL accumulates session memory into reusable skills:
+scan the journal for repeating patterns, abstract them into structured
+skill documents, and queue the proposals for user review.
+
+THREE RUNTIME MODES (operator directive 2026-05-15)
+===================================================
+
+1. **local-deterministic** (default, free tier)
+   Pure SQL + Python pattern detectors. No network, no LLM. Preserves the
+   strict local-first promise. Produces skill bodies via deterministic
+   templates from the matched event group.
+
+2. **byok** (paid-tier opt-in)
+   User pastes their own Anthropic / OpenAI / Venice key into config.
+   The Learner uses the key to summarize matched event clusters into
+   prose skill bodies. Local-first stays intact at the data layer —
+   the user controls where the inference call goes. Sibyl Labs never
+   sees the key or the payload.
+
+3. **venice-x402** (paid-tier hosted, value-add for Venice partnership)
+   User pre-funds their plugin account with FIAT or USDC. Sibyl Labs
+   auto-routes inference via Venice + x402 against the user's funded
+   balance from Sibyl's own infrastructure. Highest convenience, only
+   the prompt summary leaves the device (never the underlying memory
+   content). The Venice/x402 endpoint design is captured in the memo
+   `memory/research/2026-05-15-self-learning-design.md`.
+
+WHAT GETS DETECTED
+==================
+
+Four pattern kinds in v0.2.0:
+
+| pattern_kind            | what it catches                                |
+|-------------------------|------------------------------------------------|
+| repeated_action         | same/similar `acted` payload across N events  |
+| structural_similarity   | journal events with overlapping evaluated keys|
+| temporal_routine        | events that fire at a stable cadence          |
+| co_occurrence           | entities + actions that consistently appear   |
+|                         | together in the same journal entries          |
+
+Pattern detection is intentionally simple and explainable. Sophisticated
+embedding-based clustering can land in v0.3.0 as an optional add-on.
+
+REVIEW QUEUE
+============
+
+Detected patterns land in `skill_proposals` with status='pending'. The
+public API exposes:
+
+    list_proposals(status='pending', limit=N)
+    accept_proposal(proposal_id, note=None)   → writes to reference_documents
+    reject_proposal(proposal_id, note=None)
+    get_proposal(proposal_id)
+
+Accepted proposals create `reference_documents` rows keyed `skill/<slug>`.
+"""
+from __future__ import annotations
+
+import json
+import re
+import uuid
+from collections import Counter, defaultdict
+from dataclasses import dataclass, field
+from typing import Any, Callable, Iterable, Protocol
+
+from .client import DEFAULT_TENANT
+from .exceptions import NotFoundError, ValidationError
+from .storage import Storage, _utc_now_iso, dumps, loads, new_id
+
+
+# ----------------------------------------------------------------------
+# Public API surface
+# ----------------------------------------------------------------------
+
+@dataclass(frozen=True)
+class SkillProposal:
+    """Immutable view of a row in skill_proposals."""
+    id: str
+    tenant_id: str
+    pattern_kind: str
+    proposed_slug: str
+    proposed_title: str | None
+    proposed_body: str
+    evidence: list[dict[str, Any]]
+    confidence: float
+    summarizer: str
+    status: str
+    created_at: str
+    reviewed_at: str | None = None
+    review_note: str | None = None
+    accepted_doc_key: str | None = None
+
+
+@dataclass
+class LearningRunReport:
+    """Per-invocation summary returned by Learner.run()."""
+    run_id: str
+    events_scanned: int
+    proposals_made: int
+    proposal_ids: list[str] = field(default_factory=list)
+    started_at: str = ""
+    completed_at: str = ""
+    summarizer: str = ""
+
+
+class Summarizer(Protocol):
+    """Pluggable interface for converting a detected pattern into prose.
+
+    Implementations must be synchronous and side-effect-free with respect
+    to the local SQLite database. The Learner handles all persistence.
+    """
+
+    name: str
+
+    def summarize(
+        self,
+        pattern_kind: str,
+        events: list[dict[str, Any]],
+        hints: dict[str, Any],
+    ) -> tuple[str, str | None]:
+        """Return (body_markdown, title_or_None) for the proposal."""
+        ...
+
+
+# ----------------------------------------------------------------------
+# Local-deterministic summarizer (free-tier default)
+# ----------------------------------------------------------------------
+
+class LocalDeterministicSummarizer:
+    """Generates skill bodies via templates, no LLM call.
+
+    Useful properties:
+      • Zero network. Free-tier-safe.
+      • Deterministic — same input always produces the same body.
+      • Explains its own reasoning (so the user sees why the pattern
+        was surfaced).
+    """
+
+    name = "local-deterministic"
+
+    def summarize(
+        self,
+        pattern_kind: str,
+        events: list[dict[str, Any]],
+        hints: dict[str, Any],
+    ) -> tuple[str, str | None]:
+        title = hints.get("title") or _slug_to_title(hints.get("slug", pattern_kind))
+        lines: list[str] = []
+        lines.append(f"# {title}")
+        lines.append("")
+        lines.append(f"_Auto-detected from {len(events)} matching journal events._")
+        lines.append("")
+        lines.append("## Pattern")
+        lines.append("")
+        if pattern_kind == "repeated_action":
+            sample = hints.get("action_signature") or "(no action signature)"
+            lines.append(f"Recurring action: `{sample}`")
+        elif pattern_kind == "structural_similarity":
+            keys = ", ".join(hints.get("shared_keys", []) or [])
+            lines.append(f"Events consistently include input keys: `{keys}`")
+        elif pattern_kind == "temporal_routine":
+            cadence = hints.get("cadence_minutes")
+            lines.append(
+                f"Events fire at roughly stable cadence "
+                f"(~{cadence} min between occurrences)."
+                if cadence
+                else "Events fire at a stable cadence."
+            )
+        elif pattern_kind == "co_occurrence":
+            pair = hints.get("pair") or ("", "")
+            lines.append(
+                f"`{pair[0]}` and `{pair[1]}` consistently appear together in "
+                f"the same journal entries."
+            )
+        else:
+            lines.append("(pattern kind unrecognized — flagged for review)")
+
+        lines.append("")
+        lines.append("## Evidence")
+        lines.append("")
+        for ev in events[:5]:  # cap at five for readability
+            ts = ev.get("ts") or "?"
+            snippet = _short_event_snippet(ev)
+            lines.append(f"- `{ts}` — {snippet}")
+        if len(events) > 5:
+            lines.append(f"- _…and {len(events) - 5} more matching events_")
+        lines.append("")
+        lines.append("## Suggested use")
+        lines.append("")
+        lines.append(
+            "Reference this skill when the same situation recurs. "
+            "Edit, accept, or reject via `sibyl learn review`."
+        )
+        return "\n".join(lines), title
+
+
+# ----------------------------------------------------------------------
+# BYOK summarizer stub (paid-tier opt-in)
+# ----------------------------------------------------------------------
+
+class BYOKSummarizer:
+    """User-supplied-key summarizer.
+
+    The user passes a callable `inference_fn(prompt: str) -> str` so the
+    SDK never holds the key itself. The callable can be implemented
+    against Anthropic, OpenAI, Venice, or any provider — the SDK
+    doesn't care.
+
+    Free-tier installs cannot construct this class (the CLI's tier
+    check happens upstream). v0.2.0 ships the wiring; the CLI gate
+    enforces it.
+    """
+
+    def __init__(
+        self,
+        inference_fn: Callable[[str], str],
+        *,
+        provider_label: str = "byok",
+    ) -> None:
+        self._inference_fn = inference_fn
+        self.name = f"byok-{provider_label}"
+
+    def summarize(
+        self,
+        pattern_kind: str,
+        events: list[dict[str, Any]],
+        hints: dict[str, Any],
+    ) -> tuple[str, str | None]:
+        prompt = _build_summarization_prompt(pattern_kind, events, hints)
+        try:
+            body = self._inference_fn(prompt)
+        except Exception as e:  # pragma: no cover
+            # Fall back to deterministic if the user's key fails
+            fallback = LocalDeterministicSummarizer()
+            body, title = fallback.summarize(pattern_kind, events, hints)
+            return body + f"\n\n---\n_Note: BYOK call failed ({e}). Using local fallback._", title
+        title = hints.get("title") or _slug_to_title(hints.get("slug", pattern_kind))
+        return body, title
+
+
+# ----------------------------------------------------------------------
+# Venice + x402 routed summarizer stub (paid-tier hosted)
+# ----------------------------------------------------------------------
+
+class VeniceX402Summarizer:
+    """Routes inference through Venice via x402 against the user's
+    pre-funded Sibyl Labs plugin balance.
+
+    The actual network call lives behind `inference_fn` so this module
+    stays HTTP-library-free. The CLI layer (sibyl-labs-cli) provides
+    the real fn that signs an x402 payment header, hits the Sibyl
+    Labs inference proxy (planned: `POST /api/plugin/inference`), and
+    returns the Venice-routed completion.
+
+    Endpoint design recorded in
+    `memory/research/2026-05-15-self-learning-design.md`.
+    """
+
+    name = "venice-x402"
+
+    def __init__(
+        self,
+        inference_fn: Callable[[str], str],
+        *,
+        account_id: str,
+    ) -> None:
+        self._inference_fn = inference_fn
+        self._account_id = account_id
+
+    def summarize(
+        self,
+        pattern_kind: str,
+        events: list[dict[str, Any]],
+        hints: dict[str, Any],
+    ) -> tuple[str, str | None]:
+        prompt = _build_summarization_prompt(pattern_kind, events, hints)
+        try:
+            body = self._inference_fn(prompt)
+        except Exception as e:  # pragma: no cover
+            fallback = LocalDeterministicSummarizer()
+            body, title = fallback.summarize(pattern_kind, events, hints)
+            return body + f"\n\n---\n_Note: Venice/x402 call failed ({e}). Using local fallback._", title
+        title = hints.get("title") or _slug_to_title(hints.get("slug", pattern_kind))
+        return body, title
+
+
+# ----------------------------------------------------------------------
+# Learner — orchestrates detection + summarization + persistence
+# ----------------------------------------------------------------------
+
+class Learner:
+    """Periodic learning loop. Reads journal, writes skill proposals.
+
+    Args:
+        storage: the live Storage instance
+        tenant_id: which tenant's journal to scan
+        summarizer: pluggable summarizer (defaults to local-deterministic)
+        min_pattern_hits: minimum matched events to surface a pattern
+        max_proposals_per_run: cap to avoid swamping the review queue
+        cap_gate: optional CapGate. When provided, accept_proposal calls
+            the gate before writing the reference_documents row (T1-3 fix).
+            When None, no cap check is performed — exposed for advanced
+            callers who construct Learner directly and own their own
+            enforcement.
+    """
+
+    def __init__(
+        self,
+        storage: Storage,
+        *,
+        tenant_id: str = DEFAULT_TENANT,
+        summarizer: Summarizer | None = None,
+        min_pattern_hits: int = 3,
+        max_proposals_per_run: int = 20,
+        cap_gate: Any = None,
+    ) -> None:
+        self._storage = storage
+        self._tenant_id = tenant_id
+        self._summarizer = summarizer or LocalDeterministicSummarizer()
+        self._min_hits = max(2, min_pattern_hits)
+        self._max_per_run = max(1, max_proposals_per_run)
+        self._cap_gate = cap_gate
+
+    # ------------------------------------------------------------------
+    # Public entry points
+    # ------------------------------------------------------------------
+    def run(self, *, since: str | None = None) -> LearningRunReport:
+        """Scan journal events since the last watermark and propose skills."""
+        run_id = new_id()
+        started_at = _utc_now_iso()
+
+        # Resolve watermark — explicit `since` wins, otherwise look up last run
+        since_ts = since or self._last_watermark()
+        events = self._load_events(since=since_ts)
+        scanned = len(events)
+
+        # Skip detection entirely if there's nothing new
+        proposal_ids: list[str] = []
+        if scanned == 0:
+            self._log_run(
+                run_id=run_id,
+                started_at=started_at,
+                completed_at=_utc_now_iso(),
+                events_scanned=0,
+                proposals_made=0,
+                cursor_after_ts=since_ts,
+                notes="no new events since last run",
+            )
+            return LearningRunReport(
+                run_id=run_id,
+                events_scanned=0,
+                proposals_made=0,
+                proposal_ids=[],
+                started_at=started_at,
+                completed_at=_utc_now_iso(),
+                summarizer=self._summarizer.name,
+            )
+
+        # Run detectors, accumulate candidate proposals
+        candidates: list[_Candidate] = []
+        candidates.extend(_detect_repeated_actions(events, min_hits=self._min_hits))
+        candidates.extend(_detect_structural_similarity(events, min_hits=self._min_hits))
+        candidates.extend(_detect_co_occurrence(events, min_hits=self._min_hits))
+        # temporal_routine: light-touch detector, deliberately last
+        candidates.extend(_detect_temporal_routine(events, min_hits=self._min_hits))
+
+        # Deduplicate by slug — keep the highest-confidence candidate per slug
+        deduped: dict[str, _Candidate] = {}
+        for c in candidates:
+            existing = deduped.get(c.slug)
+            if existing is None or c.confidence > existing.confidence:
+                deduped[c.slug] = c
+
+        # Cap, sort by confidence
+        ranked = sorted(deduped.values(), key=lambda c: -c.confidence)[: self._max_per_run]
+
+        # Skip ones that already exist as pending proposals (same tenant, same slug)
+        existing_slugs = self._pending_slugs()
+        ranked = [c for c in ranked if c.slug not in existing_slugs]
+
+        # Persist
+        for c in ranked:
+            body, title = self._summarizer.summarize(c.kind, c.events, c.hints)
+            pid = self._insert_proposal(c, body=body, title=title)
+            proposal_ids.append(pid)
+
+        # Watermark
+        cursor_after = max((ev.get("ts") or "") for ev in events) or since_ts
+
+        self._log_run(
+            run_id=run_id,
+            started_at=started_at,
+            completed_at=_utc_now_iso(),
+            events_scanned=scanned,
+            proposals_made=len(proposal_ids),
+            cursor_after_ts=cursor_after,
+            notes=None,
+        )
+
+        return LearningRunReport(
+            run_id=run_id,
+            events_scanned=scanned,
+            proposals_made=len(proposal_ids),
+            proposal_ids=proposal_ids,
+            started_at=started_at,
+            completed_at=_utc_now_iso(),
+            summarizer=self._summarizer.name,
+        )
+
+    def list_proposals(
+        self,
+        *,
+        status: str = "pending",
+        limit: int = 50,
+    ) -> list[SkillProposal]:
+        with self._storage.connection() as conn:
+            rows = conn.execute(
+                "SELECT * FROM skill_proposals "
+                "WHERE tenant_id = ? AND status = ? "
+                "ORDER BY confidence DESC, created_at DESC LIMIT ?",
+                (self._tenant_id, status, limit),
+            ).fetchall()
+        return [_row_to_proposal(r) for r in rows]
+
+    def get_proposal(self, proposal_id: str) -> SkillProposal:
+        with self._storage.connection() as conn:
+            row = conn.execute(
+                "SELECT * FROM skill_proposals WHERE id = ? AND tenant_id = ?",
+                (proposal_id, self._tenant_id),
+            ).fetchone()
+        if row is None:
+            raise NotFoundError(f"skill_proposal {proposal_id} not found")
+        return _row_to_proposal(row)
+
+    def accept_proposal(
+        self,
+        proposal_id: str,
+        *,
+        note: str | None = None,
+    ) -> dict[str, Any]:
+        """Accept a proposal. Writes a reference_documents row keyed
+        `skill/<slug>` and marks the proposal accepted."""
+        proposal = self.get_proposal(proposal_id)
+        if proposal.status != "pending":
+            raise ValidationError(
+                f"proposal {proposal_id} is {proposal.status}, cannot accept",
+                recovery="Only pending proposals can be accepted. Use list_proposals(status='pending').",
+            )
+        doc_key = f"skill/{proposal.proposed_slug}"
+        # T1-3 fix: gate the reference_documents insert through the cap
+        # check. Free user at 1.9MB could previously accept skill proposals
+        # (often kilobytes of body) to keep writing past the 2 MB cap.
+        # When cap_gate is None (direct-Learner instantiation), no check.
+        if self._cap_gate is not None:
+            body_size = len(proposal.proposed_body or "") + len(doc_key) + 250
+            self._cap_gate.check(proposed_delta_bytes=body_size)
+        with self._storage.transaction() as conn:
+            conn.execute(
+                "INSERT INTO reference_documents (tenant_id, doc_key, body, metadata) "
+                "VALUES (?, ?, ?, ?) "
+                "ON CONFLICT(tenant_id, doc_key) DO UPDATE SET "
+                "body = excluded.body, metadata = excluded.metadata, "
+                "updated_at = strftime('%Y-%m-%dT%H:%M:%fZ', 'now')",
+                (
+                    self._tenant_id,
+                    doc_key,
+                    proposal.proposed_body,
+                    dumps({
+                        "source": "sibyl-memory-client/learning",
+                        "pattern_kind": proposal.pattern_kind,
+                        "summarizer": proposal.summarizer,
+                        "confidence": proposal.confidence,
+                        "evidence_count": len(proposal.evidence),
+                        "title": proposal.proposed_title,
+                    }),
+                ),
+            )
+            conn.execute(
+                "UPDATE skill_proposals "
+                "SET status = 'accepted', reviewed_at = strftime('%Y-%m-%dT%H:%M:%fZ', 'now'), "
+                "review_note = ?, accepted_doc_key = ? "
+                "WHERE id = ? AND tenant_id = ?",
+                (note, doc_key, proposal_id, self._tenant_id),
+            )
+        return {"accepted": True, "doc_key": doc_key, "proposal_id": proposal_id}
+
+    def reject_proposal(
+        self,
+        proposal_id: str,
+        *,
+        note: str | None = None,
+    ) -> dict[str, Any]:
+        proposal = self.get_proposal(proposal_id)
+        if proposal.status != "pending":
+            raise ValidationError(
+                f"proposal {proposal_id} is {proposal.status}, cannot reject",
+                recovery="Only pending proposals can be rejected.",
+            )
+        with self._storage.transaction() as conn:
+            conn.execute(
+                "UPDATE skill_proposals "
+                "SET status = 'rejected', reviewed_at = strftime('%Y-%m-%dT%H:%M:%fZ', 'now'), "
+                "review_note = ? "
+                "WHERE id = ? AND tenant_id = ?",
+                (note, proposal_id, self._tenant_id),
+            )
+        return {"rejected": True, "proposal_id": proposal_id}
+
+    # ------------------------------------------------------------------
+    # Internal
+    # ------------------------------------------------------------------
+    def _last_watermark(self) -> str | None:
+        with self._storage.connection() as conn:
+            row = conn.execute(
+                "SELECT cursor_after_ts FROM learning_runs "
+                "WHERE tenant_id = ? AND completed_at IS NOT NULL "
+                "ORDER BY started_at DESC LIMIT 1",
+                (self._tenant_id,),
+            ).fetchone()
+        return row["cursor_after_ts"] if row else None
+
+    def _load_events(self, *, since: str | None) -> list[dict[str, Any]]:
+        sql = (
+            "SELECT id, ts, evaluated, acted, forward, extra "
+            "FROM journal_events WHERE tenant_id = ?"
+        )
+        params: list[Any] = [self._tenant_id]
+        if since:
+            sql += " AND ts > ?"
+            params.append(since)
+        sql += " ORDER BY ts ASC, id ASC"
+        with self._storage.connection() as conn:
+            rows = conn.execute(sql, params).fetchall()
+        return [
+            {
+                "id": r["id"],
+                "ts": r["ts"],
+                "evaluated": loads(r["evaluated"]),
+                "acted": loads(r["acted"]),
+                "forward": loads(r["forward"]),
+                "extra": loads(r["extra"]),
+            }
+            for r in rows
+        ]
+
+    def _pending_slugs(self) -> set[str]:
+        with self._storage.connection() as conn:
+            rows = conn.execute(
+                "SELECT proposed_slug FROM skill_proposals "
+                "WHERE tenant_id = ? AND status = 'pending'",
+                (self._tenant_id,),
+            ).fetchall()
+        return {r["proposed_slug"] for r in rows}
+
+    def _insert_proposal(
+        self,
+        candidate: "_Candidate",
+        *,
+        body: str,
+        title: str | None,
+    ) -> str:
+        pid = new_id()
+        with self._storage.transaction() as conn:
+            conn.execute(
+                "INSERT INTO skill_proposals "
+                "(id, tenant_id, pattern_kind, proposed_slug, proposed_title, "
+                " proposed_body, evidence, confidence, summarizer) "
+                "VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)",
+                (
+                    pid,
+                    self._tenant_id,
+                    candidate.kind,
+                    candidate.slug,
+                    title,
+                    body,
+                    dumps([
+                        {"event_id": ev["id"], "ts": ev["ts"], "snippet": _short_event_snippet(ev)}
+                        for ev in candidate.events[:20]
+                    ]),
+                    candidate.confidence,
+                    self._summarizer.name,
+                ),
+            )
+        return pid
+
+    def _log_run(
+        self,
+        *,
+        run_id: str,
+        started_at: str,
+        completed_at: str,
+        events_scanned: int,
+        proposals_made: int,
+        cursor_after_ts: str | None,
+        notes: str | None,
+    ) -> None:
+        with self._storage.transaction() as conn:
+            conn.execute(
+                "INSERT INTO learning_runs "
+                "(id, tenant_id, started_at, completed_at, summarizer, "
+                " events_scanned, proposals_made, cursor_after_ts, notes) "
+                "VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)",
+                (
+                    run_id,
+                    self._tenant_id,
+                    started_at,
+                    completed_at,
+                    self._summarizer.name,
+                    events_scanned,
+                    proposals_made,
+                    cursor_after_ts,
+                    notes,
+                ),
+            )
+
+
+# ======================================================================
+# Pattern detectors (deterministic, local-only)
+# ======================================================================
+
+@dataclass
+class _Candidate:
+    kind: str
+    slug: str
+    confidence: float
+    events: list[dict[str, Any]]
+    hints: dict[str, Any]
+
+
+def _detect_repeated_actions(
+    events: list[dict[str, Any]],
+    *,
+    min_hits: int,
+) -> list[_Candidate]:
+    """Cluster events by an abstracted action signature; surface clusters
+    that occur >= min_hits times."""
+    by_sig: dict[str, list[dict[str, Any]]] = defaultdict(list)
+    for ev in events:
+        acted = ev.get("acted")
+        if acted is None:
+            continue
+        sig = _action_signature(acted)
+        if not sig:
+            continue
+        by_sig[sig].append(ev)
+
+    out: list[_Candidate] = []
+    for sig, group in by_sig.items():
+        if len(group) < min_hits:
+            continue
+        slug = _safe_slug("repeat-" + sig)
+        # confidence scales with hit count, capped at 0.95
+        confidence = min(0.95, 0.4 + 0.05 * len(group))
+        out.append(_Candidate(
+            kind="repeated_action",
+            slug=slug,
+            confidence=confidence,
+            events=group,
+            hints={"action_signature": sig, "slug": slug, "hits": len(group)},
+        ))
+    return out
+
+
+def _detect_structural_similarity(
+    events: list[dict[str, Any]],
+    *,
+    min_hits: int,
+) -> list[_Candidate]:
+    """Group events that share a stable set of input/output keys."""
+    by_keys: dict[tuple[str, ...], list[dict[str, Any]]] = defaultdict(list)
+    for ev in events:
+        evaluated = ev.get("evaluated")
+        if not isinstance(evaluated, dict):
+            continue
+        keyset = tuple(sorted(evaluated.keys()))
+        if not keyset:
+            continue
+        by_keys[keyset].append(ev)
+
+    out: list[_Candidate] = []
+    for keyset, group in by_keys.items():
+        if len(group) < min_hits:
+            continue
+        slug = _safe_slug("shape-" + "-".join(keyset[:4]))
+        confidence = min(0.85, 0.3 + 0.04 * len(group))
+        out.append(_Candidate(
+            kind="structural_similarity",
+            slug=slug,
+            confidence=confidence,
+            events=group,
+            hints={"shared_keys": list(keyset), "slug": slug, "hits": len(group)},
+        ))
+    return out
+
+
+def _detect_co_occurrence(
+    events: list[dict[str, Any]],
+    *,
+    min_hits: int,
+) -> list[_Candidate]:
+    """Find pairs of distinct tokens (entity names / action verbs) that
+    consistently appear together in the same journal entry."""
+    pair_counts: Counter[tuple[str, str]] = Counter()
+    pair_events: dict[tuple[str, str], list[dict[str, Any]]] = defaultdict(list)
+    for ev in events:
+        toks = _extract_tokens(ev)
+        if len(toks) < 2:
+            continue
+        toks_sorted = sorted(set(toks))
+        # All 2-combos
+        for i in range(len(toks_sorted)):
+            for j in range(i + 1, len(toks_sorted)):
+                pair = (toks_sorted[i], toks_sorted[j])
+                pair_counts[pair] += 1
+                pair_events[pair].append(ev)
+
+    out: list[_Candidate] = []
+    for pair, count in pair_counts.items():
+        if count < min_hits:
+            continue
+        slug = _safe_slug(f"pair-{pair[0]}-{pair[1]}")
+        confidence = min(0.80, 0.25 + 0.04 * count)
+        out.append(_Candidate(
+            kind="co_occurrence",
+            slug=slug,
+            confidence=confidence,
+            events=pair_events[pair],
+            hints={"pair": list(pair), "slug": slug, "hits": count},
+        ))
+    return out
+
+
+def _detect_temporal_routine(
+    events: list[dict[str, Any]],
+    *,
+    min_hits: int,
+) -> list[_Candidate]:
+    """Crude cadence detector: if same-signature events recur with low
+    variance in time-between-events, surface as a temporal routine."""
+    by_sig: dict[str, list[dict[str, Any]]] = defaultdict(list)
+    for ev in events:
+        acted = ev.get("acted")
+        if acted is None:
+            continue
+        sig = _action_signature(acted)
+        if sig:
+            by_sig[sig].append(ev)
+
+    out: list[_Candidate] = []
+    for sig, group in by_sig.items():
+        if len(group) < min_hits:
+            continue
+        gaps_min = _intervals_minutes([ev.get("ts") for ev in group])
+        if not gaps_min:
+            continue
+        mean = sum(gaps_min) / len(gaps_min)
+        if mean <= 0:
+            continue
+        # Coefficient of variation — lower = more regular
+        var = sum((g - mean) ** 2 for g in gaps_min) / len(gaps_min)
+        cov = (var ** 0.5) / mean
+        if cov >= 0.6:
+            continue  # too irregular to call a routine
+        slug = _safe_slug(f"routine-{sig}")
+        # Routine confidence rewards regularity
+        confidence = min(0.90, 0.5 + (0.5 * (1 - cov)))
+        out.append(_Candidate(
+            kind="temporal_routine",
+            slug=slug,
+            confidence=confidence,
+            events=group,
+            hints={
+                "action_signature": sig,
+                "slug": slug,
+                "hits": len(group),
+                "cadence_minutes": round(mean, 1),
+                "cov": round(cov, 3),
+            },
+        ))
+    return out
+
+
+# ======================================================================
+# Helpers
+# ======================================================================
+
+def _action_signature(acted: Any) -> str:
+    """Reduce an `acted` payload to a stable signature for clustering."""
+    if isinstance(acted, list):
+        # Use the first verb / phrase, lowercased + truncated
+        if not acted:
+            return ""
+        first = acted[0]
+        if isinstance(first, str):
+            return _normalize_phrase(first)
+        if isinstance(first, dict):
+            kind = first.get("kind") or first.get("action") or first.get("type")
+            if isinstance(kind, str):
+                return _normalize_phrase(kind)
+        return ""
+    if isinstance(acted, dict):
+        kind = acted.get("kind") or acted.get("action") or acted.get("type")
+        if isinstance(kind, str):
+            return _normalize_phrase(kind)
+        return ""
+    if isinstance(acted, str):
+        return _normalize_phrase(acted)
+    return ""
+
+
+_WORD_RE = re.compile(r"[a-z0-9][a-z0-9_-]+")
+
+
+def _normalize_phrase(text: str) -> str:
+    """Lowercase, strip non-alpha, collapse to first 3 tokens."""
+    text = text.lower().strip()
+    tokens = _WORD_RE.findall(text)
+    return "-".join(tokens[:3])
+
+
+def _safe_slug(s: str) -> str:
+    s = s.lower()
+    s = re.sub(r"[^a-z0-9-]+", "-", s)
+    s = re.sub(r"-+", "-", s).strip("-")
+    return s[:80] or "untitled"
+
+
+def _slug_to_title(slug: str) -> str:
+    return " ".join(w.capitalize() for w in slug.replace("-", " ").split())
+
+
+def _extract_tokens(ev: dict[str, Any]) -> list[str]:
+    """Pull a coarse bag-of-tokens out of an event for co-occurrence detection."""
+    out: list[str] = []
+    for field in ("evaluated", "acted"):
+        v = ev.get(field)
+        if isinstance(v, dict):
+            for key in v.keys():
+                out.append(_normalize_phrase(str(key)))
+        elif isinstance(v, list):
+            for item in v:
+                if isinstance(item, str):
+                    out.append(_normalize_phrase(item))
+        elif isinstance(v, str):
+            out.append(_normalize_phrase(v))
+    return [t for t in out if t]
+
+
+def _short_event_snippet(ev: dict[str, Any]) -> str:
+    acted = ev.get("acted")
+    if isinstance(acted, list) and acted:
+        first = acted[0]
+        if isinstance(first, str):
+            return first[:120]
+        return json.dumps(first)[:120]
+    if isinstance(acted, dict):
+        return json.dumps(acted)[:120]
+    if isinstance(acted, str):
+        return acted[:120]
+    evaluated = ev.get("evaluated")
+    if evaluated:
+        return f"evaluated: {json.dumps(evaluated)[:100]}"
+    return "(no action recorded)"
+
+
+def _intervals_minutes(timestamps: list[str | None]) -> list[float]:
+    """Compute consecutive timestamp gaps in minutes. ISO 8601 strings only."""
+    import datetime as _dt
+    parsed: list[_dt.datetime] = []
+    for t in timestamps:
+        if not t:
+            continue
+        try:
+            # Python 3.11+ handles 'Z' suffix natively via fromisoformat after replace
+            parsed.append(_dt.datetime.fromisoformat(t.replace("Z", "+00:00")))
+        except Exception:
+            continue
+    parsed.sort()
+    if len(parsed) < 2:
+        return []
+    return [(parsed[i + 1] - parsed[i]).total_seconds() / 60.0 for i in range(len(parsed) - 1)]
+
+
+def _build_summarization_prompt(
+    pattern_kind: str,
+    events: list[dict[str, Any]],
+    hints: dict[str, Any],
+) -> str:
+    """Build the LLM prompt for BYOK / Venice summarizers. The prompt is
+    deliberately compact; full evidence is included so the model can
+    produce a high-quality skill body."""
+    return (
+        f"You are summarizing a detected behavioral pattern from a personal "
+        f"agent's memory journal.\n"
+        f"Pattern kind: {pattern_kind}\n"
+        f"Hints: {json.dumps(hints, indent=2)}\n\n"
+        f"Matching journal events (up to 10 shown):\n"
+        f"{json.dumps(events[:10], indent=2)}\n\n"
+        f"Write a concise reusable skill in Markdown. Include: a clear title, "
+        f"one-paragraph description of when to apply this skill, an enumerated "
+        f"recipe of the steps the agent should follow, and any constraints "
+        f"observed in the source events. Be terse and actionable."
+    )
+
+
+def _row_to_proposal(row: Any) -> SkillProposal:
+    """Convert a sqlite3.Row into a SkillProposal dataclass."""
+    return SkillProposal(
+        id=row["id"],
+        tenant_id=row["tenant_id"],
+        pattern_kind=row["pattern_kind"],
+        proposed_slug=row["proposed_slug"],
+        proposed_title=row["proposed_title"],
+        proposed_body=row["proposed_body"],
+        evidence=loads(row["evidence"]) or [],
+        confidence=float(row["confidence"]),
+        summarizer=row["summarizer"],
+        status=row["status"],
+        created_at=row["created_at"],
+        reviewed_at=row["reviewed_at"],
+        review_note=row["review_note"],
+        accepted_doc_key=row["accepted_doc_key"],
+    )

sibyl-memory-client/src/sibyl_memory_client/lint.py

@@ -0,0 +1,453 @@
+"""Memory linter for sibyl-memory-client.
+
+Mirrors the spirit of `scripts/memory-lint.mjs` in the SIBYL operator
+codebase: scan the local memory state for structural drift, surface
+findings with severity + recovery hints, exit non-zero from CLI when
+critical findings exist.
+
+Designed to be invoked by:
+  • the plugin's `sibyl lint` CLI command (in sibyl-labs-cli)
+  • a scheduled cron job from `sibyl init`
+  • programmatic callers via `MemoryClient.lint()`
+
+CHECKS (v0.2.0)
+===============
+
+Severity levels: `critical` | `warning` | `info`
+
+| id                     | severity | what it catches                              |
+|------------------------|----------|----------------------------------------------|
+| schema-version         | critical | DB schema older than the package expects     |
+| invalid-json-entity    | critical | entities.body parses to non-object           |
+| invalid-json-state     | critical | state_documents.body parses to non-object    |
+| invalid-json-journal   | critical | journal_events fields are not valid JSON     |
+| duplicate-entity       | warning  | same entity name under multiple categories   |
+| empty-reference        | warning  | reference_documents.body is empty            |
+| stale-entity           | info     | entities not updated in >N days              |
+| journal-without-acts   | info     | journal events with no evaluated/acted/extra |
+| db-soft-cap            | warning  | DB size exceeds 80% of the soft cap (10 MB)  |
+| fts-rowcount-mismatch  | warning  | FTS5 index count differs from entities count |
+| flagged-actors-fresh   | info     | recent flagged_actors entries (≤ N days)     |
+
+The check list is intentionally conservative for v0.2.0 — easy to extend.
+"""
+from __future__ import annotations
+
+import datetime as _dt
+import json
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Any
+
+from .client import DEFAULT_TENANT
+from .storage import Storage
+
+# ----------------------------------------------------------------------
+# Public types
+# ----------------------------------------------------------------------
+
+SEVERITIES = ("critical", "warning", "info")
+# Free-tier soft cap. Tuned 2026-05-15 to land the power-user conversion event
+# in roughly 1-2 weeks of real use. Paid tiers remove the cap entirely.
+DEFAULT_SOFT_CAP_BYTES = 2 * 1024 * 1024  # 2 MB free-tier cap
+DEFAULT_STALE_DAYS = 90
+DEFAULT_FLAG_RECENCY_DAYS = 30
+EXPECTED_SCHEMA_VERSION = 2
+
+# Tier → soft cap mapping. None means uncapped.
+TIER_SOFT_CAPS: dict[str, int | None] = {
+    "free": 2 * 1024 * 1024,        # 2 MB
+    "sync": None,                    # uncapped — paid subscription
+    "team": None,                    # uncapped — paid subscription
+    "lifetime": None,                # uncapped — one-time payment
+    "stake": None,                   # uncapped — $SIBYL stake
+    "enterprise": None,              # uncapped — annual contract
+}
+
+
+@dataclass
+class Finding:
+    """A single lint result."""
+    check: str
+    severity: str  # critical | warning | info
+    message: str
+    recovery: str | None = None
+    detail: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class LintReport:
+    """Aggregated lint output."""
+    tenant_id: str
+    db_path: str
+    schema_version: int | None
+    db_size_bytes: int
+    counts: dict[str, int]
+    findings: list[Finding]
+    started_at: str
+    completed_at: str
+
+    @property
+    def critical(self) -> list[Finding]:
+        return [f for f in self.findings if f.severity == "critical"]
+
+    @property
+    def warnings(self) -> list[Finding]:
+        return [f for f in self.findings if f.severity == "warning"]
+
+    @property
+    def info(self) -> list[Finding]:
+        return [f for f in self.findings if f.severity == "info"]
+
+    @property
+    def ok(self) -> bool:
+        return not self.critical
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "tenant_id": self.tenant_id,
+            "db_path": self.db_path,
+            "schema_version": self.schema_version,
+            "db_size_bytes": self.db_size_bytes,
+            "counts": self.counts,
+            "findings": [asdict(f) for f in self.findings],
+            "started_at": self.started_at,
+            "completed_at": self.completed_at,
+            "ok": self.ok,
+            "critical_count": len(self.critical),
+            "warning_count": len(self.warnings),
+            "info_count": len(self.info),
+        }
+
+    def to_ascii(self) -> str:
+        """Render to a single-block ASCII report for CLI."""
+        lines: list[str] = []
+        bar = "═" * 64
+        lines.append("╔" + bar + "╗")
+        title = "  SIBYL MEMORY · LINT REPORT  "
+        pad = (66 - len(title)) // 2
+        lines.append("║" + " " * pad + title + " " * (66 - pad - len(title)) + "║")
+        lines.append("╠" + bar + "╣")
+        lines.append(f"║  tenant       │ {self.tenant_id[:46]:<46}║")
+        lines.append(f"║  db path      │ {Path(self.db_path).name[:46]:<46}║")
+        lines.append(f"║  schema v     │ {str(self.schema_version)[:46]:<46}║")
+        size_kb = self.db_size_bytes / 1024
+        lines.append(f"║  db size      │ {f'{size_kb:.1f} KB':<46}║")
+        lines.append("╠" + bar + "╣")
+        for k in sorted(self.counts):
+            lines.append(f"║  {k:<13}│ {str(self.counts[k]):<46}║")
+        lines.append("╠" + bar + "╣")
+        if not self.findings:
+            lines.append("║  no findings · memory looks clean" + " " * 30 + "║")
+        else:
+            for f in self.findings:
+                sev_marker = {"critical": "✗", "warning": "⚠", "info": "i"}.get(f.severity, "·")
+                hdr = f"  [{sev_marker} {f.severity}] {f.check}"
+                lines.append(f"║{hdr[:64]:<64}║")
+                msg = f"    {f.message}"
+                # wrap at 62 cols
+                while msg:
+                    chunk, msg = msg[:62], msg[62:]
+                    lines.append(f"║{chunk:<64}║")
+                if f.recovery:
+                    rec = f"    → {f.recovery}"
+                    while rec:
+                        chunk, rec = rec[:62], rec[62:]
+                        lines.append(f"║{chunk:<64}║")
+        lines.append("╠" + bar + "╣")
+        summary = f"  {len(self.critical)} critical · {len(self.warnings)} warnings · {len(self.info)} info"
+        lines.append(f"║{summary[:64]:<64}║")
+        lines.append("╚" + bar + "╝")
+        return "\n".join(lines)
+
+
+# ----------------------------------------------------------------------
+# Linter — the actual checks
+# ----------------------------------------------------------------------
+
+class Linter:
+    """Local memory linter. Stateless; safe to instantiate per call."""
+
+    def __init__(
+        self,
+        storage: Storage,
+        *,
+        tenant_id: str = DEFAULT_TENANT,
+        soft_cap_bytes: int = DEFAULT_SOFT_CAP_BYTES,
+        stale_days: int = DEFAULT_STALE_DAYS,
+        flag_recency_days: int = DEFAULT_FLAG_RECENCY_DAYS,
+    ) -> None:
+        self._storage = storage
+        self._tenant_id = tenant_id
+        self._soft_cap = soft_cap_bytes
+        self._stale_days = stale_days
+        self._flag_recency = flag_recency_days
+
+    def run(self) -> LintReport:
+        from .storage import _utc_now_iso
+        started_at = _utc_now_iso()
+
+        findings: list[Finding] = []
+        counts: dict[str, int] = {}
+
+        with self._storage.connection() as conn:
+            # schema version
+            schema_row = conn.execute(
+                "SELECT MAX(version) AS v FROM sibyl_memory_schema_version"
+            ).fetchone()
+            schema_version = schema_row["v"] if schema_row else None
+
+            if schema_version is None or schema_version < EXPECTED_SCHEMA_VERSION:
+                findings.append(Finding(
+                    check="schema-version",
+                    severity="critical",
+                    message=(
+                        f"DB schema version is {schema_version}, expected "
+                        f">= {EXPECTED_SCHEMA_VERSION}"
+                    ),
+                    recovery="Reopen the MemoryClient — schema migrations run on construction.",
+                ))
+
+            # Row counts
+            for tname in (
+                "entities", "state_documents", "journal_events",
+                "reference_documents", "archived_entities", "flagged_actors",
+                "skill_proposals", "learning_runs",
+            ):
+                try:
+                    row = conn.execute(
+                        f"SELECT COUNT(*) AS n FROM {tname} WHERE tenant_id = ?",
+                        (self._tenant_id,),
+                    ).fetchone()
+                    counts[tname] = int(row["n"]) if row else 0
+                except Exception:
+                    counts[tname] = -1  # table missing — schema-version check catches it
+
+            # ── JSON validity (defense-in-depth; CHECK constraints catch most)
+            findings.extend(self._lint_json_bodies(conn))
+
+            # ── duplicate entity names across categories
+            dupes = conn.execute(
+                "SELECT name, COUNT(DISTINCT category) AS c "
+                "FROM entities WHERE tenant_id = ? GROUP BY name HAVING c > 1",
+                (self._tenant_id,),
+            ).fetchall()
+            for row in dupes:
+                findings.append(Finding(
+                    check="duplicate-entity",
+                    severity="warning",
+                    message=f"entity name '{row['name']}' appears in {row['c']} categories",
+                    recovery="Pick one canonical category and archive or rename the others.",
+                    detail={"name": row["name"], "category_count": int(row["c"])},
+                ))
+
+            # ── empty reference documents
+            empties = conn.execute(
+                "SELECT doc_key FROM reference_documents "
+                "WHERE tenant_id = ? AND (body IS NULL OR length(trim(body)) = 0)",
+                (self._tenant_id,),
+            ).fetchall()
+            for row in empties:
+                findings.append(Finding(
+                    check="empty-reference",
+                    severity="warning",
+                    message=f"reference document '{row['doc_key']}' has empty body",
+                    recovery="Either populate the body or delete the row.",
+                    detail={"doc_key": row["doc_key"]},
+                ))
+
+            # ── stale entities
+            cutoff = (
+                _dt.datetime.utcnow() - _dt.timedelta(days=self._stale_days)
+            ).strftime("%Y-%m-%dT%H:%M:%fZ")
+            stale = conn.execute(
+                "SELECT category, name, updated_at FROM entities "
+                "WHERE tenant_id = ? AND updated_at < ? "
+                "ORDER BY updated_at ASC LIMIT 25",
+                (self._tenant_id, cutoff),
+            ).fetchall()
+            for row in stale:
+                findings.append(Finding(
+                    check="stale-entity",
+                    severity="info",
+                    message=(
+                        f"entity {row['category']}/{row['name']} hasn't been "
+                        f"updated since {row['updated_at']} "
+                        f"(> {self._stale_days} days)"
+                    ),
+                    recovery=(
+                        "Update the entity, archive it if no longer relevant, "
+                        "or extend the staleness window."
+                    ),
+                    detail={
+                        "category": row["category"],
+                        "name": row["name"],
+                        "updated_at": row["updated_at"],
+                    },
+                ))
+
+            # ── journal entries with no useful payload
+            empty_journal = conn.execute(
+                "SELECT id, ts FROM journal_events "
+                "WHERE tenant_id = ? "
+                "AND evaluated IS NULL AND acted IS NULL "
+                "AND forward IS NULL AND extra IS NULL "
+                "ORDER BY ts DESC LIMIT 10",
+                (self._tenant_id,),
+            ).fetchall()
+            for row in empty_journal:
+                findings.append(Finding(
+                    check="journal-without-acts",
+                    severity="info",
+                    message=f"journal event {row['id'][:12]}… at {row['ts']} has no payload",
+                    recovery="Either populate the event or delete it.",
+                    detail={"id": row["id"], "ts": row["ts"]},
+                ))
+
+            # ── DB size vs soft cap
+            db_size = Path(self._storage.db_path).stat().st_size
+            if db_size >= 0.8 * self._soft_cap:
+                pct = db_size / self._soft_cap
+                severity = "critical" if db_size >= self._soft_cap else "warning"
+                findings.append(Finding(
+                    check="db-soft-cap",
+                    severity=severity,
+                    message=(
+                        f"local DB is at {pct * 100:.1f}% of the {self._soft_cap // (1024 * 1024)} MB cap"
+                    ),
+                    recovery=(
+                        "Archive stale entities, prune old journal events, "
+                        "or upgrade to Stake / Cloud / Lifetime to remove the cap."
+                    ),
+                    detail={"db_size_bytes": db_size, "soft_cap_bytes": self._soft_cap},
+                ))
+
+            # ── FTS rowcount integrity
+            try:
+                ents = conn.execute(
+                    "SELECT COUNT(*) AS n FROM entities WHERE tenant_id = ?",
+                    (self._tenant_id,),
+                ).fetchone()["n"]
+                fts = conn.execute(
+                    "SELECT COUNT(*) AS n FROM entities_fts WHERE tenant_id = ?",
+                    (self._tenant_id,),
+                ).fetchone()["n"]
+                if ents != fts:
+                    findings.append(Finding(
+                        check="fts-rowcount-mismatch",
+                        severity="warning",
+                        message=(
+                            f"entities table has {ents} rows but FTS5 index "
+                            f"has {fts} — they should match"
+                        ),
+                        recovery="Rebuild FTS index: client.rebuild_fts() (planned).",
+                        detail={"entities": ents, "fts": fts},
+                    ))
+            except Exception:
+                pass  # missing fts table → caught by schema-version check
+
+            # ── recent flagged actors (info-level surface)
+            recent_cutoff = (
+                _dt.datetime.utcnow() - _dt.timedelta(days=self._flag_recency)
+            ).strftime("%Y-%m-%dT%H:%M:%fZ")
+            try:
+                flagged = conn.execute(
+                    "SELECT identifier, flagged_at, reason FROM flagged_actors "
+                    "WHERE tenant_id = ? AND flagged_at >= ? "
+                    "ORDER BY flagged_at DESC LIMIT 5",
+                    (self._tenant_id, recent_cutoff),
+                ).fetchall()
+                for row in flagged:
+                    findings.append(Finding(
+                        check="flagged-actors-fresh",
+                        severity="info",
+                        message=(
+                            f"recent flagged actor: {row['identifier']} "
+                            f"({row['reason'][:60] if row['reason'] else 'no reason given'})"
+                        ),
+                        recovery="Review the actor record; ensure downstream actions respect the flag.",
+                        detail={
+                            "identifier": row["identifier"],
+                            "flagged_at": row["flagged_at"],
+                        },
+                    ))
+            except Exception:
+                pass
+
+        completed_at = _utc_now_iso()
+
+        return LintReport(
+            tenant_id=self._tenant_id,
+            db_path=str(self._storage.db_path),
+            schema_version=schema_version,
+            db_size_bytes=Path(self._storage.db_path).stat().st_size,
+            counts=counts,
+            findings=findings,
+            started_at=started_at,
+            completed_at=completed_at,
+        )
+
+    # ------------------------------------------------------------------
+    # Internal — JSON validity probe
+    # ------------------------------------------------------------------
+    def _lint_json_bodies(self, conn: Any) -> list[Finding]:
+        out: list[Finding] = []
+        # entities.body must be JSON object/array
+        bad_entities = conn.execute(
+            "SELECT id, category, name FROM entities "
+            "WHERE tenant_id = ? AND json_valid(body) = 0 LIMIT 10",
+            (self._tenant_id,),
+        ).fetchall()
+        for row in bad_entities:
+            out.append(Finding(
+                check="invalid-json-entity",
+                severity="critical",
+                message=f"entity {row['category']}/{row['name']} has invalid JSON body",
+                recovery="Delete or repair the row. SDK CHECK constraints should have prevented this.",
+                detail={"id": row["id"]},
+            ))
+
+        bad_states = conn.execute(
+            "SELECT document_key FROM state_documents "
+            "WHERE tenant_id = ? AND json_valid(body) = 0 LIMIT 10",
+            (self._tenant_id,),
+        ).fetchall()
+        for row in bad_states:
+            out.append(Finding(
+                check="invalid-json-state",
+                severity="critical",
+                message=f"state_document {row['document_key']} has invalid JSON body",
+                recovery="Repair or delete the row.",
+                detail={"document_key": row["document_key"]},
+            ))
+
+        # journal_events fields are nullable but if present must be valid JSON
+        bad_journal = conn.execute(
+            "SELECT id FROM journal_events WHERE tenant_id = ? "
+            "AND ("
+            "(evaluated IS NOT NULL AND json_valid(evaluated) = 0) OR "
+            "(acted IS NOT NULL AND json_valid(acted) = 0) OR "
+            "(forward IS NOT NULL AND json_valid(forward) = 0) OR "
+            "(extra IS NOT NULL AND json_valid(extra) = 0)"
+            ") LIMIT 10",
+            (self._tenant_id,),
+        ).fetchall()
+        for row in bad_journal:
+            out.append(Finding(
+                check="invalid-json-journal",
+                severity="critical",
+                message=f"journal_event {row['id']} has invalid JSON in one of its fields",
+                recovery="Repair or delete the row.",
+                detail={"id": row["id"]},
+            ))
+
+        return out
+
+
+# ----------------------------------------------------------------------
+# Convenience module-level function (mirrors scripts/memory-lint.mjs UX)
+# ----------------------------------------------------------------------
+
+def lint(storage: Storage, *, tenant_id: str = DEFAULT_TENANT, **kwargs: Any) -> LintReport:
+    """Convenience: run a default lint pass."""
+    return Linter(storage, tenant_id=tenant_id, **kwargs).run()

sibyl-memory-client/src/sibyl_memory_client/schema.sql

@@ -0,0 +1,350 @@
+-- sibyl-memory-client SQLite schema v1
+--
+-- Port of the canonical sibyl_memory.* Postgres schema (scripts/sibyl-memory-schema.sql,
+-- applied to Neon 2026-05-01) to SQLite for the local-first plugin v1.
+--
+-- Dialect translations:
+--   UUID                → TEXT (Python uuid.uuid4() at write-time)
+--   JSONB               → TEXT with CHECK(json_valid(col)) using SQLite json1
+--   TIMESTAMPTZ + now() → TEXT ISO 8601 UTC via strftime('%Y-%m-%dT%H:%M:%fZ','now')
+--   gin jsonb_path_ops  → SQLite json_extract expression indexes where useful
+--   NUMERIC             → REAL (sufficient precision for plugin v1 use)
+--   tsvector            → FTS5 virtual tables for text search
+--
+-- Multi-tenant: every table carries tenant_id. Local-first means typically
+-- one tenant per machine, but the schema accepts N tenants (paid Team-tier
+-- federation forward-compatible).
+--
+-- Idempotent. Apply via CREATE TABLE IF NOT EXISTS. Schema version recorded
+-- in sibyl_memory_schema_version for future migrations.
+
+PRAGMA foreign_keys = ON;
+PRAGMA journal_mode = WAL;
+
+-- ============================================================================
+-- WARM tier: entities (single source of truth per rule 43)
+-- ============================================================================
+CREATE TABLE IF NOT EXISTS entities (
+  id          TEXT PRIMARY KEY,
+  tenant_id   TEXT NOT NULL,
+  category    TEXT NOT NULL,
+  name        TEXT NOT NULL,
+  status      TEXT,
+  body        TEXT NOT NULL CHECK (json_valid(body)),
+  created_at  TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+  updated_at  TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+  UNIQUE (tenant_id, category, name)
+);
+
+CREATE INDEX IF NOT EXISTS entities_tenant_cat_status
+  ON entities (tenant_id, category, status);
+CREATE INDEX IF NOT EXISTS entities_updated_at
+  ON entities (tenant_id, updated_at DESC);
+
+-- ============================================================================
+-- Cross-references: typed relations between entities
+-- ============================================================================
+CREATE TABLE IF NOT EXISTS entity_relations (
+  id            TEXT PRIMARY KEY,
+  tenant_id     TEXT NOT NULL,
+  from_id       TEXT NOT NULL REFERENCES entities(id) ON DELETE CASCADE,
+  to_id         TEXT NOT NULL REFERENCES entities(id) ON DELETE CASCADE,
+  relation_type TEXT NOT NULL,
+  metadata      TEXT CHECK (metadata IS NULL OR json_valid(metadata)),
+  created_at    TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))
+);
+
+CREATE INDEX IF NOT EXISTS entity_relations_from
+  ON entity_relations (tenant_id, from_id, relation_type);
+CREATE INDEX IF NOT EXISTS entity_relations_to
+  ON entity_relations (tenant_id, to_id, relation_type);
+
+-- ============================================================================
+-- HOT tier: state documents (treasury, priorities, session, index analogs)
+-- ============================================================================
+CREATE TABLE IF NOT EXISTS state_documents (
+  tenant_id    TEXT NOT NULL,
+  document_key TEXT NOT NULL,
+  body         TEXT NOT NULL CHECK (json_valid(body)),
+  updated_at   TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+  PRIMARY KEY (tenant_id, document_key)
+);
+
+-- ============================================================================
+-- COLD tier: append-only journal of events
+-- ============================================================================
+CREATE TABLE IF NOT EXISTS journal_events (
+  id         TEXT PRIMARY KEY,
+  tenant_id  TEXT NOT NULL,
+  ts         TEXT NOT NULL,
+  evaluated  TEXT CHECK (evaluated IS NULL OR json_valid(evaluated)),
+  acted      TEXT CHECK (acted IS NULL OR json_valid(acted)),
+  forward    TEXT CHECK (forward IS NULL OR json_valid(forward)),
+  extra      TEXT CHECK (extra IS NULL OR json_valid(extra))
+);
+
+CREATE INDEX IF NOT EXISTS journal_events_tenant_ts
+  ON journal_events (tenant_id, ts DESC);
+
+-- ============================================================================
+-- COLD tier: revenue events with optional entity ref
+-- ============================================================================
+CREATE TABLE IF NOT EXISTS revenue_events (
+  id                  TEXT PRIMARY KEY,
+  tenant_id           TEXT NOT NULL,
+  ts                  TEXT NOT NULL,
+  event_type          TEXT,
+  gross_usd           REAL,
+  operator_share_usd  REAL,
+  source              TEXT,
+  tx                  TEXT,
+  entity_id           TEXT REFERENCES entities(id) ON DELETE SET NULL
+);
+
+CREATE INDEX IF NOT EXISTS revenue_events_tenant_ts
+  ON revenue_events (tenant_id, ts DESC);
+
+-- ============================================================================
+-- COLD tier: error events
+-- ============================================================================
+CREATE TABLE IF NOT EXISTS error_events (
+  id         TEXT PRIMARY KEY,
+  tenant_id  TEXT NOT NULL,
+  ts         TEXT NOT NULL,
+  code       TEXT,
+  message    TEXT,
+  context    TEXT CHECK (context IS NULL OR json_valid(context))
+);
+
+CREATE INDEX IF NOT EXISTS error_events_tenant_ts
+  ON error_events (tenant_id, ts DESC);
+
+-- ============================================================================
+-- REFERENCE tier: static documents (markdown bodies, lookup-only)
+-- ============================================================================
+CREATE TABLE IF NOT EXISTS reference_documents (
+  tenant_id   TEXT NOT NULL,
+  doc_key     TEXT NOT NULL,
+  body        TEXT,
+  metadata    TEXT CHECK (metadata IS NULL OR json_valid(metadata)),
+  updated_at  TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+  PRIMARY KEY (tenant_id, doc_key)
+);
+
+-- ============================================================================
+-- ARCHIVE tier: frozen entities (out of working set, retrievable)
+-- ============================================================================
+CREATE TABLE IF NOT EXISTS archived_entities (
+  id                  TEXT PRIMARY KEY,
+  tenant_id           TEXT NOT NULL,
+  original_entity_id  TEXT,
+  category            TEXT,
+  name                TEXT,
+  body                TEXT CHECK (body IS NULL OR json_valid(body)),
+  archived_at         TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+  archive_reason      TEXT
+);
+
+CREATE INDEX IF NOT EXISTS archived_entities_tenant_cat
+  ON archived_entities (tenant_id, category, name);
+
+-- ============================================================================
+-- FLAGGED tier: actors flagged for social-engineering / fraud (rule 13/14/15)
+-- ============================================================================
+CREATE TABLE IF NOT EXISTS flagged_actors (
+  id              TEXT PRIMARY KEY,
+  tenant_id       TEXT NOT NULL,
+  actor_handle    TEXT,
+  actor_address   TEXT,
+  flagged_at      TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+  reason          TEXT,
+  evidence        TEXT CHECK (evidence IS NULL OR json_valid(evidence))
+);
+
+CREATE INDEX IF NOT EXISTS flagged_actors_tenant
+  ON flagged_actors (tenant_id);
+
+-- ============================================================================
+-- FTS5 virtual tables for full-text retrieval (the tsvector port)
+-- ============================================================================
+-- v3 (2026-05-18): all FTS5 tables now use external-content (or contentless
+-- for journal). Body lives in the base table, FTS5 stores only the index.
+-- Triggers fire transparently. Disk footprint stays flat (vs v2's 2x dup).
+-- Cross-tier search lands here: entities + state + reference + journal.
+-- v2 → v3 migration is handled in storage.py:_migrate_to_v3.
+
+-- ENTITIES: external-content FTS5 over entities table
+CREATE VIRTUAL TABLE IF NOT EXISTS entities_fts USING fts5(
+  name, category, body, tenant_id UNINDEXED,
+  content='entities', content_rowid='rowid',
+  tokenize = 'porter unicode61'
+);
+
+CREATE TRIGGER IF NOT EXISTS entities_ai_fts
+AFTER INSERT ON entities BEGIN
+  INSERT INTO entities_fts(rowid, name, category, body, tenant_id)
+  VALUES (new.rowid, new.name, new.category, new.body, new.tenant_id);
+END;
+
+CREATE TRIGGER IF NOT EXISTS entities_ad_fts
+AFTER DELETE ON entities BEGIN
+  INSERT INTO entities_fts(entities_fts, rowid, name, category, body, tenant_id)
+  VALUES ('delete', old.rowid, old.name, old.category, old.body, old.tenant_id);
+END;
+
+CREATE TRIGGER IF NOT EXISTS entities_au_fts
+AFTER UPDATE ON entities BEGIN
+  INSERT INTO entities_fts(entities_fts, rowid, name, category, body, tenant_id)
+  VALUES ('delete', old.rowid, old.name, old.category, old.body, old.tenant_id);
+  INSERT INTO entities_fts(rowid, name, category, body, tenant_id)
+  VALUES (new.rowid, new.name, new.category, new.body, new.tenant_id);
+END;
+
+-- STATE: external-content FTS5 over state_documents
+CREATE VIRTUAL TABLE IF NOT EXISTS state_documents_fts USING fts5(
+  document_key, body, tenant_id UNINDEXED,
+  content='state_documents', content_rowid='rowid',
+  tokenize = 'porter unicode61'
+);
+
+CREATE TRIGGER IF NOT EXISTS state_documents_ai_fts
+AFTER INSERT ON state_documents BEGIN
+  INSERT INTO state_documents_fts(rowid, document_key, body, tenant_id)
+  VALUES (new.rowid, new.document_key, new.body, new.tenant_id);
+END;
+
+CREATE TRIGGER IF NOT EXISTS state_documents_ad_fts
+AFTER DELETE ON state_documents BEGIN
+  INSERT INTO state_documents_fts(state_documents_fts, rowid, document_key, body, tenant_id)
+  VALUES ('delete', old.rowid, old.document_key, old.body, old.tenant_id);
+END;
+
+CREATE TRIGGER IF NOT EXISTS state_documents_au_fts
+AFTER UPDATE ON state_documents BEGIN
+  INSERT INTO state_documents_fts(state_documents_fts, rowid, document_key, body, tenant_id)
+  VALUES ('delete', old.rowid, old.document_key, old.body, old.tenant_id);
+  INSERT INTO state_documents_fts(rowid, document_key, body, tenant_id)
+  VALUES (new.rowid, new.document_key, new.body, new.tenant_id);
+END;
+
+-- REFERENCE: external-content FTS5 over reference_documents
+CREATE VIRTUAL TABLE IF NOT EXISTS reference_documents_fts USING fts5(
+  doc_key, body, tenant_id UNINDEXED,
+  content='reference_documents', content_rowid='rowid',
+  tokenize = 'porter unicode61'
+);
+
+CREATE TRIGGER IF NOT EXISTS reference_ai_fts
+AFTER INSERT ON reference_documents BEGIN
+  INSERT INTO reference_documents_fts(rowid, doc_key, body, tenant_id)
+  VALUES (new.rowid, new.doc_key, new.body, new.tenant_id);
+END;
+
+CREATE TRIGGER IF NOT EXISTS reference_ad_fts
+AFTER DELETE ON reference_documents BEGIN
+  INSERT INTO reference_documents_fts(reference_documents_fts, rowid, doc_key, body, tenant_id)
+  VALUES ('delete', old.rowid, old.doc_key, old.body, old.tenant_id);
+END;
+
+CREATE TRIGGER IF NOT EXISTS reference_au_fts
+AFTER UPDATE ON reference_documents BEGIN
+  INSERT INTO reference_documents_fts(reference_documents_fts, rowid, doc_key, body, tenant_id)
+  VALUES ('delete', old.rowid, old.doc_key, old.body, old.tenant_id);
+  INSERT INTO reference_documents_fts(rowid, doc_key, body, tenant_id)
+  VALUES (new.rowid, new.doc_key, new.body, new.tenant_id);
+END;
+
+-- JOURNAL: standalone FTS5 over journal_events (concatenated payload).
+-- Standalone (not external-content) because journal_events has 4 separate
+-- JSON payload columns we want searchable as one concatenated field, and
+-- there's no single base-table column we could external-content against.
+-- Acceptable cost: journal is append-only (no updates), so the body
+-- duplication doesn't compound on edits like it would on warm entities.
+CREATE VIRTUAL TABLE IF NOT EXISTS journal_events_fts USING fts5(
+  ts UNINDEXED, payload, tenant_id UNINDEXED, event_id UNINDEXED,
+  tokenize = 'porter unicode61'
+);
+
+CREATE TRIGGER IF NOT EXISTS journal_events_ai_fts
+AFTER INSERT ON journal_events BEGIN
+  INSERT INTO journal_events_fts(rowid, ts, payload, tenant_id, event_id)
+  VALUES (
+    new.rowid, new.ts,
+    COALESCE(new.evaluated, '') || ' ' || COALESCE(new.acted, '') || ' ' ||
+      COALESCE(new.forward, '') || ' ' || COALESCE(new.extra, ''),
+    new.tenant_id, new.id
+  );
+END;
+
+-- ============================================================================
+-- Schema version tracking
+-- ============================================================================
+CREATE TABLE IF NOT EXISTS sibyl_memory_schema_version (
+  version       INTEGER PRIMARY KEY,
+  applied_at    TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+  description   TEXT
+);
+
+INSERT OR IGNORE INTO sibyl_memory_schema_version (version, description)
+VALUES (1, 'sibyl-memory-client v1. SQLite port of sibyl_memory.* Postgres schema. 10 tables (entities, entity_relations, state_documents, journal_events, revenue_events, error_events, reference_documents, archived_entities, flagged_actors, schema_version) + 2 FTS5 virtual tables. Local-first plugin foundation.');
+
+-- ============================================================================
+-- Schema v2 — self-learning skill proposals (review queue)
+-- ============================================================================
+-- The Learner module scans journal_events for repeating patterns and writes
+-- proposed skill documents here. The user reviews via `sibyl learn review`
+-- and either accepts (which writes to reference_documents under skill/<slug>)
+-- or rejects. Idempotent; safe to re-apply against a v1 database.
+CREATE TABLE IF NOT EXISTS skill_proposals (
+  id              TEXT PRIMARY KEY,
+  tenant_id       TEXT NOT NULL,
+  created_at      TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+
+  -- detector output
+  pattern_kind    TEXT NOT NULL,   -- 'repeated_action' / 'structural_similarity' / 'temporal_routine' / 'co_occurrence'
+  proposed_slug   TEXT NOT NULL,   -- the reference_documents.doc_key it would land under (skill/<slug>)
+  proposed_title  TEXT,            -- one-line human-readable title
+  proposed_body   TEXT NOT NULL,   -- the actual skill body (markdown text)
+
+  -- evidence + provenance
+  evidence        TEXT NOT NULL CHECK (json_valid(evidence)),  -- list of source journal_event ids + snippets
+  confidence      REAL NOT NULL CHECK (confidence >= 0 AND confidence <= 1),
+  summarizer      TEXT NOT NULL,   -- 'local-deterministic' / 'byok-anthropic' / 'byok-openai' / 'venice-x402' / etc.
+
+  -- review state
+  status          TEXT NOT NULL DEFAULT 'pending' CHECK (status IN ('pending', 'accepted', 'rejected', 'superseded')),
+  reviewed_at     TEXT,
+  review_note     TEXT,
+
+  -- when accepted, points at the reference_documents row that was created
+  accepted_doc_key TEXT
+);
+
+CREATE INDEX IF NOT EXISTS skill_proposals_tenant_status
+  ON skill_proposals (tenant_id, status, created_at DESC);
+CREATE INDEX IF NOT EXISTS skill_proposals_slug
+  ON skill_proposals (tenant_id, proposed_slug);
+
+-- ============================================================================
+-- Schema v2 — learning run log (so detectors don't re-scan ground they covered)
+-- ============================================================================
+CREATE TABLE IF NOT EXISTS learning_runs (
+  id              TEXT PRIMARY KEY,
+  tenant_id       TEXT NOT NULL,
+  started_at      TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+  completed_at    TEXT,
+  summarizer      TEXT NOT NULL,
+  events_scanned  INTEGER NOT NULL DEFAULT 0,
+  proposals_made  INTEGER NOT NULL DEFAULT 0,
+  cursor_after_ts TEXT,             -- watermark — newest journal ts processed
+  notes           TEXT
+);
+
+CREATE INDEX IF NOT EXISTS learning_runs_tenant
+  ON learning_runs (tenant_id, started_at DESC);
+
+INSERT OR IGNORE INTO sibyl_memory_schema_version (version, description)
+VALUES (2, 'sibyl-memory-client v2. Adds skill_proposals (self-learning review queue) and learning_runs (detector watermark log). Idempotent migration; v1 databases auto-upgrade on first open. Free tier uses local-deterministic summarizer; paid tier can opt into BYOK or Venice/x402-routed summarization.');
+
+INSERT OR IGNORE INTO sibyl_memory_schema_version (version, description)
+VALUES (3, 'sibyl-memory-client v3. External-content FTS5 across entities + state_documents + reference_documents + contentless FTS5 over journal_events. Fixes the v0.3.0 "search covers warm entities only" bug. Eliminates body duplication (v2 stored body twice — base table + FTS5). v2 to v3 migration handled in storage.py:_migrate_to_v3: drops the standalone FTS5 tables and rebuilds in external-content shape from existing base-table data. No data loss.');

sibyl-memory-client/src/sibyl_memory_client/storage.py

@@ -0,0 +1,277 @@
+"""SQLite storage layer for sibyl-memory-client.
+
+Opens a per-tenant local SQLite database, applies the canonical schema, and
+exposes a connection helper plus low-level row IO. Thread-local connection
+pool keeps things simple for v1; we revisit if/when concurrent agent
+workloads emerge.
+
+Design notes:
+- WAL mode for concurrent reads + single writer (default for v1, matches
+  the local-first single-agent workload).
+- foreign_keys = ON enforced at connection time.
+- Schema applied on first open; idempotent via CREATE IF NOT EXISTS.
+- ISO 8601 UTC timestamps everywhere (`strftime('%Y-%m-%dT%H:%M:%fZ','now')`).
+- All JSON validated at write time via sqlite json_valid() CHECK constraints.
+"""
+from __future__ import annotations
+
+import json
+import os
+import sqlite3
+import threading
+from contextlib import contextmanager
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Iterator
+from uuid import uuid4
+
+from .exceptions import SchemaError, StorageError
+
+_SCHEMA_PATH = Path(__file__).parent / "schema.sql"
+
+# v0.4.0 (2026-05-18, KAPPA RED finding): the SQLite DB holds every entity
+# body, not just credentials. docs.sibyllabs.org/memory/install claims 0600
+# but sqlite3.connect inherits the process umask (typically yields 0644).
+# Tighten with explicit chmod after the schema apply guarantees the file
+# exists. Idempotent — safe to call every time. Also tightens WAL + SHM
+# sidecar files if they exist after the first transaction.
+_DB_FILE_MODE = 0o600
+_DB_SIDECAR_SUFFIXES = ("-wal", "-shm")
+
+
+def _utc_now_iso() -> str:
+    """Return current UTC time in ISO 8601 microsecond-precision format.
+
+    Higher precision than the schema's millisecond default (`%f` in
+    SQLite's strftime) reduces ts collisions when multiple writes land in
+    the same millisecond. Microsecond-precision strings sort correctly
+    lexically since the format is fixed-width."""
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%S.%fZ")
+
+
+def new_id() -> str:
+    """Generate a fresh UUID v4 string for primary keys."""
+    return str(uuid4())
+
+
+def dumps(payload: Any) -> str:
+    """Canonical JSON serialization for body / payload fields.
+    sort_keys=False (preserve insertion order — matters for downstream diff).
+    separators tight to keep DB rows compact."""
+    return json.dumps(payload, separators=(",", ":"), ensure_ascii=False)
+
+
+def loads(blob: str | None) -> Any:
+    """Inverse of dumps(). Returns None for None input (matches nullable
+    JSONB column semantics)."""
+    if blob is None:
+        return None
+    return json.loads(blob)
+
+
+class Storage:
+    """SQLite connection wrapper with schema bootstrap + transaction helpers."""
+
+    def __init__(self, db_path: str | Path):
+        self.db_path = Path(db_path).expanduser().resolve()
+        self.db_path.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
+        # Per-instance thread-local cache (avoids leaking connections across
+        # Storage instances pointing at different files).
+        self._tls = threading.local()
+        # Bootstrap schema on first open (idempotent)
+        self._ensure_schema()
+        # v0.4.0 (KAPPA RED finding): tighten file permissions on the main DB
+        # file + WAL + SHM sidecars after the schema apply has created them.
+        # Default umask leaves 0644 (world-readable); we want 0600 since the
+        # DB contains every entity body. Idempotent + tolerant of missing
+        # sidecars (WAL/SHM only exist after first write).
+        self._tighten_db_file_perms()
+
+    def _connect(self) -> sqlite3.Connection:
+        """Open a fresh connection. Callers should prefer connection() context
+        manager for proper cleanup.
+
+        SEC-3 hardening (v0.3.3): exception messages do not echo the absolute
+        db path — the original exception is chained via `from e` for debugging,
+        but the user-visible message stays generic."""
+        try:
+            conn = sqlite3.connect(
+                str(self.db_path),
+                isolation_level=None,  # autocommit; we manage transactions explicitly
+                check_same_thread=False,
+                detect_types=0,
+            )
+        except sqlite3.Error as e:
+            raise StorageError(
+                f"Could not open the local SQLite database: {type(e).__name__}",
+                recovery="Check disk space, file permissions, and that no other process holds an exclusive lock.",
+            ) from e
+
+        conn.execute("PRAGMA foreign_keys = ON")
+        conn.execute("PRAGMA journal_mode = WAL")
+        conn.execute("PRAGMA synchronous = NORMAL")  # safe with WAL, faster than FULL
+        conn.execute("PRAGMA busy_timeout = 5000")  # 5s before SQLITE_BUSY
+        conn.row_factory = sqlite3.Row
+        return conn
+
+    @contextmanager
+    def connection(self) -> Iterator[sqlite3.Connection]:
+        """Context manager that yields a per-instance, thread-local connection.
+        Connection stays open across calls for performance; cleanup happens at
+        Storage.close() or at process exit.
+
+        SEC-3 hardening (v0.3.3): wraps sqlite3.Error in a sanitized
+        StorageError without leaking db_path or query text."""
+        conn = getattr(self._tls, "conn", None)
+        if conn is None:
+            conn = self._connect()
+            self._tls.conn = conn
+        try:
+            yield conn
+        except sqlite3.Error as e:
+            raise StorageError(
+                f"SQLite error: {type(e).__name__}",
+                recovery="See exception cause for detail; consider checking schema version and disk health.",
+            ) from e
+
+    @contextmanager
+    def transaction(self) -> Iterator[sqlite3.Connection]:
+        """Atomic transaction. Rolls back on exception, commits on clean exit."""
+        with self.connection() as conn:
+            conn.execute("BEGIN IMMEDIATE")
+            try:
+                yield conn
+            except Exception:
+                conn.execute("ROLLBACK")
+                raise
+            else:
+                conn.execute("COMMIT")
+
+    def _ensure_schema(self) -> None:
+        """Apply the canonical schema. Idempotent — safe to call on every open.
+
+        After applying the schema, runs any pending migrations. v2 to v3 (2026-05-18)
+        is the only migration currently — it reshapes FTS5 tables from standalone
+        (body duplicated) to external-content (body lives in base tables only).
+        Migration runs once and is idempotent thereafter."""
+        if not _SCHEMA_PATH.exists():
+            raise SchemaError(
+                "Schema file missing from package install",
+                recovery="The package install is corrupted. Reinstall sibyl-memory-client.",
+            ) from None
+        sql = _SCHEMA_PATH.read_text(encoding="utf-8")
+        with self.connection() as conn:
+            try:
+                conn.executescript(sql)
+            except sqlite3.Error as e:
+                raise SchemaError(
+                    f"Failed to apply schema: {e}",
+                    recovery="Check sqlite3 version (need 3.38+ for json_valid). On older systems, upgrade.",
+                ) from e
+        # Run migrations that need imperative work beyond CREATE IF NOT EXISTS.
+        self._migrate_if_needed()
+
+    def _migrate_if_needed(self) -> None:
+        """Run any pending schema migrations.
+
+        Detection: examine `entities_fts`'s declared SQL via sqlite_master. If
+        the table was created in the v2 standalone shape (`entity_id UNINDEXED`)
+        we need to drop and rebuild it as external-content. The migration also
+        backfills state_documents_fts + journal_events_fts + the new
+        reference_documents_fts shape for existing v2 databases.
+
+        Safe to call repeatedly — operations short-circuit once v3 is in place.
+        """
+        with self.connection() as conn:
+            row = conn.execute(
+                "SELECT sql FROM sqlite_master WHERE type='table' AND name='entities_fts'"
+            ).fetchone()
+            if row is None:
+                # Fresh DB. Schema.sql already created v3 shape correctly.
+                return
+            sql = (row["sql"] or "").lower()
+            needs_v3 = "entity_id" in sql or "content='entities'" not in sql.replace(" ", "")
+            if not needs_v3:
+                # Already v3 shape — nothing to do.
+                return
+
+        # v2 → v3: drop standalone FTS5 + triggers, re-create in external-content
+        # shape, rebuild from base table data. The CREATE statements in
+        # schema.sql will pick up after the DROP because they're CREATE IF
+        # NOT EXISTS.
+        try:
+            with self.transaction() as conn:
+                # Drop old FTS5 tables + their triggers
+                conn.execute("DROP TRIGGER IF EXISTS entities_ai_fts")
+                conn.execute("DROP TRIGGER IF EXISTS entities_ad_fts")
+                conn.execute("DROP TRIGGER IF EXISTS entities_au_fts")
+                conn.execute("DROP TABLE IF EXISTS entities_fts")
+                conn.execute("DROP TRIGGER IF EXISTS reference_ai_fts")
+                conn.execute("DROP TRIGGER IF EXISTS reference_ad_fts")
+                conn.execute("DROP TRIGGER IF EXISTS reference_au_fts")
+                conn.execute("DROP TABLE IF EXISTS reference_documents_fts")
+            # Re-run schema.sql so the v3 external-content tables + triggers
+            # land (CREATE IF NOT EXISTS picks up the dropped tables).
+            sql_text = _SCHEMA_PATH.read_text(encoding="utf-8")
+            with self.connection() as conn:
+                conn.executescript(sql_text)
+            # Rebuild FTS5 indexes from base tables for any pre-existing data.
+            with self.transaction() as conn:
+                conn.execute("INSERT INTO entities_fts(entities_fts) VALUES('rebuild')")
+                conn.execute("INSERT INTO state_documents_fts(state_documents_fts) VALUES('rebuild')")
+                conn.execute("INSERT INTO reference_documents_fts(reference_documents_fts) VALUES('rebuild')")
+                # journal_events_fts is contentless — can't 'rebuild' from
+                # outside. Backfill manually for any existing journal rows.
+                conn.execute(
+                    """
+                    INSERT INTO journal_events_fts(rowid, ts, payload, tenant_id)
+                    SELECT rowid, ts,
+                           COALESCE(evaluated,'') || ' ' || COALESCE(acted,'') || ' ' ||
+                           COALESCE(forward,'') || ' ' || COALESCE(extra,''),
+                           tenant_id
+                      FROM journal_events
+                    """
+                )
+        except sqlite3.Error as e:
+            raise SchemaError(
+                f"FTS5 v2 to v3 migration failed: {e}",
+                recovery="Back up your memory.db, then delete it; the next open will create a fresh v3 DB. Your base-table data is unaffected by this migration failure — the FTS5 index will rebuild.",
+            ) from e
+
+    def schema_version(self) -> int | None:
+        """Return current schema version, or None if uninitialized."""
+        with self.connection() as conn:
+            row = conn.execute(
+                "SELECT MAX(version) AS v FROM sibyl_memory_schema_version"
+            ).fetchone()
+            return row["v"] if row else None
+
+    def _tighten_db_file_perms(self) -> None:
+        """Set memory.db (and WAL/SHM sidecars if present) to mode 0600.
+
+        Idempotent. Safe on systems where chmod is a no-op (Windows) — we
+        guard with hasattr. Errors during chmod are non-fatal: we want
+        secure-by-default but won't block a working DB if the chmod call
+        races a concurrent process or hits a read-only mount edge case.
+        """
+        if not hasattr(os, "chmod"):
+            return  # platform without POSIX chmod (Windows)
+        targets = [self.db_path]
+        for suffix in _DB_SIDECAR_SUFFIXES:
+            sidecar = self.db_path.with_name(self.db_path.name + suffix)
+            if sidecar.exists():
+                targets.append(sidecar)
+        for path in targets:
+            try:
+                os.chmod(path, _DB_FILE_MODE)
+            except OSError:
+                # Non-fatal: log nothing, defer to caller noticing if perms
+                # are truly broken (write operations will fail downstream).
+                pass
+
+    def close(self) -> None:
+        """Close the thread-local connection (mainly for tests / shutdown)."""
+        conn = getattr(self._tls, "conn", None)
+        if conn is not None:
+            conn.close()
+            self._tls.conn = None

sibyl-memory-client/tests/test_capcheck.py

@@ -0,0 +1,339 @@
+"""Tests for the v0.3.0 hard-cap enforcement.
+
+Three concerns covered:
+  1. Free-tier writes are blocked once the DB crosses 2 MB
+  2. The server check fires at the boundary and updates the local tier cache
+  3. The 7-day grace cache works (paid → uncapped writes without phoning home)
+"""
+from __future__ import annotations
+
+import time
+from pathlib import Path
+
+import pytest
+
+from sibyl_memory_client import (
+    CapExceededError,
+    CapGate,
+    MemoryClient,
+    TierCache,
+    TierCacheEntry,
+    TierVerificationError,
+)
+
+
+# ----------------------------------------------------------------------
+# Fake check-write transport — lets us simulate server responses without
+# hitting the network
+# ----------------------------------------------------------------------
+
+class FakeServer:
+    """Mocks the /api/plugin/check-write endpoint."""
+
+    def __init__(self, *, tier: str = "free", offline: bool = False) -> None:
+        self.tier = tier
+        self.offline = offline
+        self.calls: list[dict] = []
+
+    def __call__(self, url, payload, timeout=4.0):
+        if self.offline:
+            raise TierVerificationError("simulated network down")
+        self.calls.append(payload)
+        # Paid tier → unconditional ok
+        if self.tier in ("sync", "team", "lifetime", "stake", "enterprise"):
+            return {"ok": True, "tier": self.tier, "cap_bytes": None}
+        # Free tier → check size
+        new = payload["current_size_bytes"] + payload["proposed_delta_bytes"]
+        cap = 2 * 1024 * 1024
+        if new <= cap:
+            return {"ok": True, "tier": "free", "cap_bytes": cap,
+                    "remaining_bytes": cap - new}
+        return {
+            "ok": False, "tier": "free", "cap_bytes": cap,
+            "upgrade_url": "https://docs.sibyllabs.org/memory/tiers",
+        }
+
+
+# ----------------------------------------------------------------------
+# Direct CapGate tests
+# ----------------------------------------------------------------------
+
+def test_under_cap_no_server_call(tmp_path: Path) -> None:
+    server = FakeServer(tier="free")
+    cache = TierCache(tmp_path / "tc.json")
+    gate = CapGate(
+        account_id="acc-1",
+        session_token="sess-1",
+        db_size_fn=lambda: 100_000,
+        local_tier_hint="free",
+        cache=cache,
+        check_fn=server,
+    )
+    gate.check(proposed_delta_bytes=1000)
+    assert len(server.calls) == 0  # didn't phone home
+
+
+def test_at_cap_server_says_no(tmp_path: Path) -> None:
+    server = FakeServer(tier="free")
+    cache = TierCache(tmp_path / "tc.json")
+    gate = CapGate(
+        account_id="acc-1",
+        session_token="sess-1",
+        db_size_fn=lambda: 2 * 1024 * 1024 - 100,  # 100 bytes below cap
+        local_tier_hint="free",
+        cache=cache,
+        check_fn=server,
+    )
+    with pytest.raises(CapExceededError) as exc:
+        gate.check(proposed_delta_bytes=500)  # would push past cap
+    assert exc.value.cap == 2 * 1024 * 1024
+    assert "sibyllabs.org" in exc.value.upgrade_url
+    assert len(server.calls) == 1  # one boundary check
+
+
+def test_at_cap_server_upgrades_user(tmp_path: Path) -> None:
+    """User claims free in credentials but server says they're now paid
+    (upgraded since last activation). The write should be permitted."""
+    server = FakeServer(tier="lifetime")
+    cache = TierCache(tmp_path / "tc.json")
+    gate = CapGate(
+        account_id="acc-1",
+        session_token="sess-1",
+        db_size_fn=lambda: 2 * 1024 * 1024 + 1000,  # past free cap
+        local_tier_hint="free",  # cached credentials say free
+        cache=cache,
+        check_fn=server,
+    )
+    gate.check(proposed_delta_bytes=500)
+    # No exception — server told us we're paid
+    # Verify cache was updated
+    cached = cache.load()
+    assert cached is not None
+    assert cached.tier == "lifetime"
+    assert cached.cap_bytes is None  # paid = no cap
+
+
+def test_paid_cache_skips_server(tmp_path: Path) -> None:
+    """If we have a fresh cache saying we're paid, no server call needed."""
+    server = FakeServer(tier="free")  # would say no if called
+    cache = TierCache(tmp_path / "tc.json")
+    # Pre-populate cache as paid
+    cache.store(TierCacheEntry(
+        account_id="acc-1",
+        tier="lifetime",
+        checked_at=time.time(),
+        cap_bytes=None,
+    ))
+    gate = CapGate(
+        account_id="acc-1",
+        session_token="sess-1",
+        db_size_fn=lambda: 100 * 1024 * 1024,  # 100 MB — way past free cap
+        local_tier_hint="free",
+        cache=cache,
+        check_fn=server,
+    )
+    gate.check(proposed_delta_bytes=10_000)
+    assert len(server.calls) == 0  # cache short-circuited
+
+
+def test_stale_paid_cache_triggers_refresh(tmp_path: Path) -> None:
+    """An 8-day-old cache should NOT be honored as fresh."""
+    server = FakeServer(tier="lifetime")
+    cache = TierCache(tmp_path / "tc.json")
+    # Pre-populate cache as paid, but 8 days old
+    cache.store(TierCacheEntry(
+        account_id="acc-1",
+        tier="lifetime",
+        checked_at=time.time() - 8 * 24 * 60 * 60,  # 8 days ago
+        cap_bytes=None,
+    ))
+    gate = CapGate(
+        account_id="acc-1",
+        session_token="sess-1",
+        db_size_fn=lambda: 5 * 1024 * 1024,
+        local_tier_hint="free",
+        cache=cache,
+        check_fn=server,
+    )
+    gate.check(proposed_delta_bytes=10_000)
+    # Stale cache, so server WAS called
+    assert len(server.calls) == 1
+
+
+def test_offline_at_cap_with_recent_paid_cache(tmp_path: Path) -> None:
+    """Honest paid user goes offline. Should still be allowed to write."""
+    server = FakeServer(offline=True)
+    cache = TierCache(tmp_path / "tc.json")
+    cache.store(TierCacheEntry(
+        account_id="acc-1",
+        tier="lifetime",
+        checked_at=time.time(),
+        cap_bytes=None,
+    ))
+    gate = CapGate(
+        account_id="acc-1",
+        session_token="sess-1",
+        db_size_fn=lambda: 50 * 1024 * 1024,
+        local_tier_hint="free",
+        cache=cache,
+        check_fn=server,
+    )
+    # No exception — cache is fresh and says paid
+    gate.check(proposed_delta_bytes=10_000)
+
+
+def test_offline_at_cap_no_cache_raises(tmp_path: Path) -> None:
+    """No cache + offline + at the cap = TierVerificationError."""
+    server = FakeServer(offline=True)
+    cache = TierCache(tmp_path / "tc.json")
+    gate = CapGate(
+        account_id="acc-1",
+        session_token="sess-1",
+        db_size_fn=lambda: 2 * 1024 * 1024 + 100,
+        local_tier_hint="free",
+        cache=cache,
+        check_fn=server,
+    )
+    with pytest.raises(TierVerificationError):
+        gate.check(proposed_delta_bytes=500)
+
+
+def test_no_account_id_under_cap_passes(tmp_path: Path) -> None:
+    """Pre-activation user under the cap should work."""
+    server = FakeServer(tier="free")
+    cache = TierCache(tmp_path / "tc.json")
+    gate = CapGate(
+        account_id=None,
+        session_token=None,
+        db_size_fn=lambda: 1_000_000,
+        local_tier_hint="free",
+        cache=cache,
+        check_fn=server,
+    )
+    gate.check(proposed_delta_bytes=1000)
+    assert len(server.calls) == 0
+
+
+def test_no_account_id_at_cap_blocks(tmp_path: Path) -> None:
+    """Pre-activation user past the cap → hard block."""
+    server = FakeServer(tier="free")
+    cache = TierCache(tmp_path / "tc.json")
+    gate = CapGate(
+        account_id=None,
+        session_token=None,
+        db_size_fn=lambda: 2 * 1024 * 1024 + 100,
+        local_tier_hint="free",
+        cache=cache,
+        check_fn=server,
+    )
+    with pytest.raises(CapExceededError):
+        gate.check(proposed_delta_bytes=500)
+
+
+# ----------------------------------------------------------------------
+# End-to-end test through MemoryClient
+# ----------------------------------------------------------------------
+
+def test_e2e_free_tier_blocked_at_cap(tmp_path: Path) -> None:
+    """Writing past the 2 MB cap raises CapExceededError when the server
+    confirms free tier."""
+    server = FakeServer(tier="free")
+    cache = TierCache(tmp_path / "tc.json")
+    db_path = tmp_path / "memory.db"
+
+    # Build a custom gate using a synthetic large db_size to skip the slow
+    # path of actually writing 2 MB of data.
+    from sibyl_memory_client._capcheck import CapGate
+    fake_size = [100]  # mutable, lets us simulate growth
+
+    gate = CapGate(
+        account_id="acc-1",
+        session_token="sess-1",
+        db_size_fn=lambda: fake_size[0],
+        local_tier_hint="free",
+        cache=cache,
+        check_fn=server,
+    )
+    client = MemoryClient(
+        storage=__import__("sibyl_memory_client").Storage(str(db_path)),
+        tenant_id="alice",
+        tier="free",
+        account_id="acc-1",
+        session_token="sess-1",
+        cap_gate=gate,
+    )
+
+    # Under the cap — works fine
+    client.set_entity("project", "atlas", {"status": "active"})
+
+    # Simulate being near the cap
+    fake_size[0] = 2 * 1024 * 1024 - 100
+
+    # Next write would push over → server-checked → blocked
+    with pytest.raises(CapExceededError):
+        client.set_entity("project", "borealis", {"status": "active", "x": "y" * 500})
+
+    # Server was consulted
+    assert len(server.calls) >= 1
+
+
+def test_e2e_paid_tier_no_cap(tmp_path: Path) -> None:
+    """Paid tier bypasses the cap entirely (within grace period)."""
+    server = FakeServer(tier="lifetime")
+    cache = TierCache(tmp_path / "tc.json")
+    db_path = tmp_path / "memory.db"
+
+    fake_size = [50 * 1024 * 1024]  # 50 MB — way past free cap
+
+    from sibyl_memory_client._capcheck import CapGate
+    gate = CapGate(
+        account_id="acc-1",
+        session_token="sess-1",
+        db_size_fn=lambda: fake_size[0],
+        local_tier_hint="lifetime",
+        cache=cache,
+        check_fn=server,
+    )
+    client = MemoryClient(
+        storage=__import__("sibyl_memory_client").Storage(str(db_path)),
+        tenant_id="alice",
+        tier="lifetime",
+        account_id="acc-1",
+        session_token="sess-1",
+        cap_gate=gate,
+    )
+    # Writes succeed even though we're 50 MB in
+    client.set_entity("project", "atlas", {"status": "active"})
+    client.set_entity("project", "borealis", {"status": "active"})
+    client.set_state("priorities", {"top": ["ship"]})
+
+
+def test_cache_file_is_0600(tmp_path: Path) -> None:
+    """Tier cache must not be world-readable."""
+    cache = TierCache(tmp_path / "tc.json")
+    cache.store(TierCacheEntry(
+        account_id="acc-1",
+        tier="free",
+        checked_at=time.time(),
+        cap_bytes=2 * 1024 * 1024,
+    ))
+    mode = oct((tmp_path / "tc.json").stat().st_mode)[-3:]
+    assert mode == "600"
+
+
+def test_cap_gate_invalidate_cache(tmp_path: Path) -> None:
+    cache = TierCache(tmp_path / "tc.json")
+    cache.store(TierCacheEntry(
+        account_id="acc-1", tier="free", checked_at=time.time(), cap_bytes=2_000_000,
+    ))
+    assert cache.load() is not None
+    gate = CapGate(
+        account_id="acc-1",
+        session_token="sess-1",
+        db_size_fn=lambda: 0,
+        local_tier_hint="free",
+        cache=cache,
+        check_fn=FakeServer(),
+    )
+    gate.invalidate_cache()
+    assert cache.load() is None

sibyl-memory-client/tests/test_kappa_fixes.py

@@ -0,0 +1,283 @@
+"""Regression tests for the v0.4.0 KAPPA-attributed fixes.
+
+Covers:
+- BLOCKER: CapExceededError + TierVerificationError importable from
+  sibyl_memory_client.exceptions (the canonical submodule path).
+- RED:     memory.db is chmod 0600 after Storage init.
+- YELLOW:  validate_identifier rejects empty / null-byte / non-string /
+           oversized. set_entity, set_state, set_reference call it.
+- YELLOW:  _classify_fts5_error returns the right exception type for the
+           three buckets (schema-missing → None; FTS5-syntax → ValidationError;
+           backend → StorageError).
+
+Source bug report: /tmp/kappa-sibyl-memory-mcp-report.md
+(KAPPA, 2026-05-18, via Acer/Tulip referral).
+"""
+from __future__ import annotations
+
+import os
+import sqlite3
+import stat
+import sys
+from pathlib import Path
+
+import pytest
+
+sys.path.insert(0, str(Path(__file__).parent.parent / "src"))
+
+
+# ----------------------------------------------------------------------
+# BLOCKER — submodule exception path
+# ----------------------------------------------------------------------
+
+def test_cap_exceeded_error_importable_from_exceptions_submodule():
+    """KAPPA's exact import path. server.py:41 does this; before v0.4.0
+    it raised ImportError."""
+    from sibyl_memory_client.exceptions import CapExceededError
+    assert CapExceededError.__name__ == "CapExceededError"
+    assert CapExceededError.code == "CAP_EXCEEDED"
+    # Constructor contract: positional message + required keyword args
+    err = CapExceededError("test", current_size=100, cap=200, proposed_delta=10)
+    assert err.current_size == 100
+    assert err.cap == 200
+    assert err.proposed_delta == 10
+    assert "tiers" in err.upgrade_url
+
+
+def test_tier_verification_error_importable_from_exceptions_submodule():
+    """Same submodule path. KAPPA's blocker covered both classes."""
+    from sibyl_memory_client.exceptions import TierVerificationError
+    assert TierVerificationError.__name__ == "TierVerificationError"
+    assert TierVerificationError.code == "TIER_VERIFY_FAILED"
+    err = TierVerificationError("test")
+    assert "internet" in err.recovery or "verify" in err.recovery
+
+
+def test_capcheck_backwards_compat_reexports():
+    """Anyone reaching into the private _capcheck module should still get the
+    same class objects (identity check) post-relocation."""
+    from sibyl_memory_client.exceptions import CapExceededError as E_exc
+    from sibyl_memory_client._capcheck import CapExceededError as E_cap
+    assert E_exc is E_cap, "_capcheck must re-export the same class object"
+    from sibyl_memory_client.exceptions import TierVerificationError as T_exc
+    from sibyl_memory_client._capcheck import TierVerificationError as T_cap
+    assert T_exc is T_cap
+
+
+def test_top_level_package_still_exports_both():
+    """The top-level `from sibyl_memory_client import CapExceededError` path
+    that already worked in v0.3.3 must still work — no regression on the
+    main public surface."""
+    from sibyl_memory_client import CapExceededError, TierVerificationError
+    assert CapExceededError.__name__ == "CapExceededError"
+    assert TierVerificationError.__name__ == "TierVerificationError"
+
+
+# ----------------------------------------------------------------------
+# RED — memory.db file perms
+# ----------------------------------------------------------------------
+
+@pytest.mark.skipif(not hasattr(os, "chmod"), reason="POSIX-only test")
+def test_memory_db_file_perms_are_0600(tmp_path):
+    """KAPPA RED finding. Docs claim 0600, actual was 0644 (umask default).
+    After v0.4.0, Storage init tightens to 0600 unconditionally."""
+    from sibyl_memory_client import MemoryClient
+    db_path = tmp_path / "memory.db"
+    MemoryClient.local(db_path)
+    assert db_path.exists(), "DB file should exist after Storage init"
+    mode = stat.S_IMODE(db_path.stat().st_mode)
+    assert mode == 0o600, f"memory.db mode should be 0600, got 0o{mode:o}"
+
+
+@pytest.mark.skipif(not hasattr(os, "chmod"), reason="POSIX-only test")
+def test_memory_db_wal_sidecar_perms_tighten_when_present(tmp_path):
+    """WAL/SHM sidecar files also get 0600 if they exist after a write."""
+    from sibyl_memory_client import MemoryClient
+    db_path = tmp_path / "memory.db"
+    client = MemoryClient.local(db_path)
+    # Force a write so WAL/SHM appear, then re-init to trigger another chmod pass.
+    client.set_entity("test", "alpha", {"k": "v"})
+    # Re-open to trigger the chmod pass on the WAL/SHM files
+    MemoryClient.local(db_path)
+    for suffix in ("-wal", "-shm"):
+        sidecar = db_path.with_name(db_path.name + suffix)
+        if sidecar.exists():
+            mode = stat.S_IMODE(sidecar.stat().st_mode)
+            assert mode == 0o600, f"{sidecar.name} should be 0600, got 0o{mode:o}"
+
+
+# ----------------------------------------------------------------------
+# YELLOW — validate_identifier
+# ----------------------------------------------------------------------
+
+def test_validate_identifier_rejects_empty():
+    from sibyl_memory_client.client import validate_identifier
+    from sibyl_memory_client.exceptions import ValidationError
+    with pytest.raises(ValidationError, match="cannot be empty"):
+        validate_identifier("", field_name="name")
+
+
+def test_validate_identifier_rejects_non_string():
+    from sibyl_memory_client.client import validate_identifier
+    from sibyl_memory_client.exceptions import ValidationError
+    with pytest.raises(ValidationError, match="must be a string"):
+        validate_identifier(123, field_name="name")
+    with pytest.raises(ValidationError, match="must be a string"):
+        validate_identifier(None, field_name="name")
+
+
+def test_validate_identifier_rejects_null_bytes():
+    from sibyl_memory_client.client import validate_identifier
+    from sibyl_memory_client.exceptions import ValidationError
+    with pytest.raises(ValidationError, match="forbidden control character"):
+        validate_identifier("foo\x00bar", field_name="name")
+
+
+def test_validate_identifier_rejects_other_control_chars():
+    from sibyl_memory_client.client import validate_identifier
+    from sibyl_memory_client.exceptions import ValidationError
+    with pytest.raises(ValidationError, match="forbidden control character"):
+        validate_identifier("foo\tbar", field_name="key")  # tab
+    with pytest.raises(ValidationError, match="forbidden control character"):
+        validate_identifier("foo\nbar", field_name="key")  # newline
+
+
+def test_validate_identifier_rejects_oversized():
+    from sibyl_memory_client.client import validate_identifier
+    from sibyl_memory_client.exceptions import ValidationError
+    too_long = "a" * 1025
+    with pytest.raises(ValidationError, match="too long"):
+        validate_identifier(too_long, field_name="name")
+
+
+def test_validate_identifier_accepts_reasonable():
+    from sibyl_memory_client.client import validate_identifier
+    # All of these should pass
+    for ok in ("foo", "alice", "project-atlas", "a", "x" * 1024,
+               "with spaces", "unicode-é-ñ-中", "with.dot", "with/slash"):
+        assert validate_identifier(ok, field_name="name") == ok
+
+
+# ----------------------------------------------------------------------
+# YELLOW — write paths call validate_identifier
+# ----------------------------------------------------------------------
+
+def test_set_entity_rejects_empty_name(tmp_path):
+    from sibyl_memory_client import MemoryClient
+    from sibyl_memory_client.exceptions import ValidationError
+    client = MemoryClient.local(tmp_path / "memory.db")
+    with pytest.raises(ValidationError, match="cannot be empty"):
+        client.set_entity("project", "", {"k": "v"})
+
+
+def test_set_entity_rejects_null_byte_in_category(tmp_path):
+    from sibyl_memory_client import MemoryClient
+    from sibyl_memory_client.exceptions import ValidationError
+    client = MemoryClient.local(tmp_path / "memory.db")
+    with pytest.raises(ValidationError, match="forbidden control character"):
+        client.set_entity("proj\x00ect", "atlas", {"k": "v"})
+
+
+def test_set_state_rejects_oversized_key(tmp_path):
+    from sibyl_memory_client import MemoryClient
+    from sibyl_memory_client.exceptions import ValidationError
+    client = MemoryClient.local(tmp_path / "memory.db")
+    with pytest.raises(ValidationError, match="too long"):
+        client.set_state("k" * 2000, {"v": 1})
+
+
+def test_set_reference_rejects_empty_key(tmp_path):
+    from sibyl_memory_client import MemoryClient
+    from sibyl_memory_client.exceptions import ValidationError
+    client = MemoryClient.local(tmp_path / "memory.db")
+    with pytest.raises(ValidationError, match="cannot be empty"):
+        client.set_reference("", "body text")
+
+
+def test_read_paths_unaffected_by_validation(tmp_path):
+    """Read paths (get_entity, get_state, get_reference) must NOT validate —
+    users with already-stored bad identifiers should still be able to read
+    and migrate them.
+
+    We can't easily inject bad data through a write (validation blocks),
+    but we can confirm get_entity/get_state with weird-but-not-validated
+    inputs returns NotFoundError (the lookup path), not ValidationError."""
+    from sibyl_memory_client import MemoryClient
+    from sibyl_memory_client.exceptions import NotFoundError
+    client = MemoryClient.local(tmp_path / "memory.db")
+    # Read on bad identifier should be NotFound, not ValidationError —
+    # we don't gate reads. (NB: passing through SQLite, which handles it.)
+    with pytest.raises(NotFoundError):
+        client.get_entity("project", "nonexistent-but-validly-named")
+    # get_state returns None for missing keys (not raise).
+    assert client.get_state("nonexistent") is None
+
+
+# ----------------------------------------------------------------------
+# YELLOW — FTS5 error classifier
+# ----------------------------------------------------------------------
+
+def test_classify_fts5_error_schema_missing_returns_none():
+    """no such table case → caller should return empty (defensive)."""
+    from sibyl_memory_client.client import _classify_fts5_error
+    err = sqlite3.OperationalError("no such table: entities_fts")
+    assert _classify_fts5_error(err) is None
+
+
+def test_classify_fts5_error_syntax_returns_validation_error():
+    """malformed match / fts5 syntax errors → ValidationError."""
+    from sibyl_memory_client.client import _classify_fts5_error
+    from sibyl_memory_client.exceptions import ValidationError
+    for msg in (
+        "fts5: syntax error near \"AND\"",
+        "malformed MATCH expression: \"bad\"",
+        "fts5 query error",
+        "no such column: invalid_col",
+    ):
+        err = sqlite3.OperationalError(msg)
+        result = _classify_fts5_error(err)
+        assert isinstance(result, ValidationError), \
+            f"expected ValidationError for {msg!r}, got {type(result)}"
+
+
+def test_classify_fts5_error_other_returns_storage_error():
+    """Anything else (disk full, locked, etc.) → StorageError."""
+    from sibyl_memory_client.client import _classify_fts5_error
+    from sibyl_memory_client.exceptions import StorageError
+    err = sqlite3.OperationalError("database is locked")
+    result = _classify_fts5_error(err)
+    assert isinstance(result, StorageError)
+
+
+def test_search_with_valid_query_does_not_raise(tmp_path):
+    """Normal queries should still work — no false-positive ValidationError."""
+    from sibyl_memory_client import MemoryClient
+    client = MemoryClient.local(tmp_path / "memory.db")
+    client.set_entity("project", "atlas", {"description": "alpha bravo charlie"})
+    client.set_entity("project", "babel", {"description": "delta echo foxtrot"})
+    # Plain text query — should not raise, returns matching results
+    hits = client.search("alpha")
+    assert len(hits) >= 1
+    # Empty query short-circuits to []
+    assert client.search("") == []
+    # Whitespace-only query short-circuits to []
+    assert client.search("   ") == []
+
+
+def test_search_entities_phrase_match_semantics(tmp_path):
+    """Document the actual phrase-match behavior so KAPPA's confusion
+    (queries containing AND/OR/* return zero hits) is verified expected.
+    These queries get wrapped as phrases — they only match literal occurrences
+    of the phrase text in entity bodies."""
+    from sibyl_memory_client import MemoryClient
+    client = MemoryClient.local(tmp_path / "memory.db")
+    client.set_entity("project", "atlas", {"description": "alpha bravo charlie"})
+    # "alpha bravo" should match because the body contains that exact phrase
+    hits = client.search_entities("alpha bravo")
+    assert len(hits) == 1
+    # "AND" is a literal here — no entity body contains "AND"
+    hits = client.search_entities("AND OR NOT")
+    assert hits == []
+    # "*" is wrapped as a literal phrase
+    hits = client.search_entities("*")
+    assert hits == []

sibyl-memory-client/tests/test_learning.py

@@ -0,0 +1,269 @@
+"""Smoke tests for sibyl_memory_client.learning."""
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from sibyl_memory_client import (
+    BYOKSummarizer,
+    Learner,
+    LearningRunReport,
+    LocalDeterministicSummarizer,
+    MemoryClient,
+    SkillProposal,
+    VeniceX402Summarizer,
+)
+
+
+# ----------------------------------------------------------------------
+# Fixtures
+# ----------------------------------------------------------------------
+
+@pytest.fixture
+def client(tmp_path: Path) -> MemoryClient:
+    db = tmp_path / "memory.db"
+    # Self-learning is paid-tier only. Tests run as a lifetime-tier user.
+    return MemoryClient.local(str(db), tier="lifetime")
+
+
+def _seed_repeated_action(client: MemoryClient, n: int = 4) -> None:
+    """Write N events with the same action signature."""
+    for i in range(n):
+        client.write_event(
+            evaluated={"task": "fix bug", "ticket": f"TASK-{i}"},
+            acted=["deployed atlas to staging"],
+        )
+
+
+def _seed_structural_pattern(client: MemoryClient, n: int = 3) -> None:
+    """Write N events with the same evaluated key set."""
+    for i in range(n):
+        client.write_event(
+            evaluated={"step": i, "module": "auth", "owner": "jane"},
+            acted={"kind": f"checkpoint-{i}"},
+        )
+
+
+# ----------------------------------------------------------------------
+# Schema migration v1 → v2 (the new tables must exist after open)
+# ----------------------------------------------------------------------
+def test_schema_v2_applied(client: MemoryClient) -> None:
+    assert client.schema_version() >= 2
+    # Tables should be queryable without error
+    proposals = client.list_skill_proposals()
+    assert proposals == []
+
+
+# ----------------------------------------------------------------------
+# Learner basics
+# ----------------------------------------------------------------------
+def test_learner_no_events_no_proposals(client: MemoryClient) -> None:
+    report = client.learn()
+    assert isinstance(report, LearningRunReport)
+    assert report.events_scanned == 0
+    assert report.proposals_made == 0
+    assert report.summarizer == "local-deterministic"
+
+
+def test_learner_detects_repeated_action(client: MemoryClient) -> None:
+    _seed_repeated_action(client, n=4)
+    report = client.learn()
+    assert report.events_scanned >= 4
+    assert report.proposals_made >= 1
+
+    proposals = client.list_skill_proposals()
+    kinds = {p.pattern_kind for p in proposals}
+    assert "repeated_action" in kinds
+    rep = next(p for p in proposals if p.pattern_kind == "repeated_action")
+    assert rep.confidence > 0.4
+    assert rep.summarizer == "local-deterministic"
+    assert "deployed" in rep.proposed_body.lower()
+
+
+def test_learner_watermark_no_double_propose(client: MemoryClient) -> None:
+    _seed_repeated_action(client, n=4)
+    first = client.learn()
+    assert first.proposals_made >= 1
+    # Second run with no new events should skip
+    second = client.learn()
+    assert second.events_scanned == 0
+    assert second.proposals_made == 0
+
+
+def test_learner_detects_structural_similarity(client: MemoryClient) -> None:
+    _seed_structural_pattern(client, n=3)
+    report = client.learn()
+    proposals = client.list_skill_proposals()
+    kinds = {p.pattern_kind for p in proposals}
+    # Should at least pick up the shape
+    assert "structural_similarity" in kinds or "co_occurrence" in kinds
+
+
+# ----------------------------------------------------------------------
+# Review queue: accept / reject
+# ----------------------------------------------------------------------
+def test_accept_proposal_writes_reference(client: MemoryClient) -> None:
+    _seed_repeated_action(client, n=4)
+    client.learn()
+    proposals = client.list_skill_proposals()
+    assert proposals
+
+    target = proposals[0]
+    result = client.accept_skill_proposal(target.id, note="useful")
+    assert result["accepted"] is True
+    assert result["doc_key"].startswith("skill/")
+
+    # Reference doc landed
+    ref = client.get_reference(result["doc_key"])
+    assert ref is not None
+    assert target.proposed_body == ref["body"]
+
+    # Proposal status updated
+    after = client.list_skill_proposals(status="accepted")
+    assert any(p.id == target.id for p in after)
+
+
+def test_reject_proposal_does_not_write_reference(client: MemoryClient) -> None:
+    _seed_repeated_action(client, n=4)
+    client.learn()
+    proposals = client.list_skill_proposals()
+    target = proposals[0]
+
+    result = client.reject_skill_proposal(target.id, note="not useful")
+    assert result["rejected"] is True
+
+    # No skill/<slug> reference doc should exist
+    assert client.get_reference(f"skill/{target.proposed_slug}") is None
+
+    # Proposal removed from pending
+    pending = client.list_skill_proposals(status="pending")
+    assert not any(p.id == target.id for p in pending)
+
+
+def test_double_accept_raises(client: MemoryClient) -> None:
+    _seed_repeated_action(client, n=4)
+    client.learn()
+    target = client.list_skill_proposals()[0]
+    client.accept_skill_proposal(target.id)
+    with pytest.raises(Exception):
+        client.accept_skill_proposal(target.id)
+
+
+# ----------------------------------------------------------------------
+# Custom summarizer plumbing — BYOK + Venice/x402 stubs
+# ----------------------------------------------------------------------
+def test_byok_summarizer_invokes_inference_fn(client: MemoryClient) -> None:
+    captured = {}
+
+    def fake_inference(prompt: str) -> str:
+        captured["prompt"] = prompt
+        return "# Skill from BYOK\n\nDo the thing."
+
+    summarizer = BYOKSummarizer(fake_inference, provider_label="testlab")
+    assert summarizer.name == "byok-testlab"
+
+    _seed_repeated_action(client, n=4)
+    learner = client.learner(summarizer=summarizer)
+    report = learner.run()
+    assert report.summarizer == "byok-testlab"
+    assert report.proposals_made >= 1
+
+    # The summarizer was called with the journal context
+    assert "prompt" in captured
+    assert "behavioral pattern" in captured["prompt"]
+
+    proposals = learner.list_proposals()
+    assert any("Skill from BYOK" in p.proposed_body for p in proposals)
+
+
+def test_venice_x402_summarizer_fallback_on_error(client: MemoryClient) -> None:
+    def bad_inference(prompt: str) -> str:
+        raise RuntimeError("simulated network failure")
+
+    summarizer = VeniceX402Summarizer(bad_inference, account_id="acc-stub")
+    _seed_repeated_action(client, n=4)
+    learner = client.learner(summarizer=summarizer)
+    report = learner.run()
+    assert report.proposals_made >= 1
+
+    proposals = learner.list_proposals()
+    # Fallback note should be present
+    assert any("Venice/x402 call failed" in p.proposed_body for p in proposals)
+
+
+# ----------------------------------------------------------------------
+# Multi-tenant isolation
+# ----------------------------------------------------------------------
+def test_learner_is_tenant_scoped(tmp_path: Path) -> None:
+    db = tmp_path / "m.db"
+    alice = MemoryClient.local(str(db), tenant_id="alice", tier="lifetime")
+    bob = MemoryClient.local(str(db), tenant_id="bob", tier="lifetime")
+
+    _seed_repeated_action(alice, n=4)
+    alice.learn()
+
+    # Bob has not learned anything; should see zero proposals
+    bobs_proposals = bob.list_skill_proposals()
+    assert bobs_proposals == []
+
+    # Alice has at least one
+    alice_proposals = alice.list_skill_proposals()
+    assert alice_proposals
+    for p in alice_proposals:
+        assert p.tenant_id == "alice"
+
+
+# ----------------------------------------------------------------------
+# Tier gating — free tier blocked from self-learning
+# ----------------------------------------------------------------------
+def test_free_tier_cannot_learn(tmp_path: Path) -> None:
+    from sibyl_memory_client import TierGateError
+    free = MemoryClient.local(str(tmp_path / "free.db"))  # default tier="free"
+    with pytest.raises(TierGateError) as exc:
+        free.learn()
+    assert exc.value.feature == "self-learning"
+    assert exc.value.current_tier == "free"
+
+
+def test_free_tier_cannot_list_proposals(tmp_path: Path) -> None:
+    from sibyl_memory_client import TierGateError
+    free = MemoryClient.local(str(tmp_path / "free.db"))
+    with pytest.raises(TierGateError):
+        free.list_skill_proposals()
+
+
+def test_free_tier_can_still_use_core_memory(tmp_path: Path) -> None:
+    """Free-tier users get the full memory SDK — only learning/lint are gated.
+    This is the upgrade-pressure design: free tier is fully functional storage
+    + retrieval, paid tier adds the intelligence layer."""
+    free = MemoryClient.local(str(tmp_path / "free.db"))
+    free.set_entity("project", "atlas", {"status": "active"})
+    free.write_event(acted=["did something"])
+    free.set_state("priorities", {"top": ["ship"]})
+    free.set_reference("rule-1", "always ship")
+
+    # All core reads work
+    assert free.get_entity("project", "atlas")["body"]["status"] == "active"
+    assert free.get_state("priorities") is not None
+    assert free.get_reference("rule-1") is not None
+    assert free.read_events()
+    # FTS5 search works
+    results = free.search_entities("atlas")
+    assert results
+
+
+def test_paid_tier_upgrade_unlocks_learn(tmp_path: Path) -> None:
+    """Simulate upgrade flow: start free, set_tier('lifetime'), learn now works."""
+    client = MemoryClient.local(str(tmp_path / "u.db"))
+    _seed_repeated_action(client, n=4)
+
+    # Free tier blocks
+    from sibyl_memory_client import TierGateError
+    with pytest.raises(TierGateError):
+        client.learn()
+
+    # Upgrade → unlock
+    client.set_tier("lifetime")
+    report = client.learn()
+    assert report.proposals_made >= 1

sibyl-memory-client/tests/test_lint.py

@@ -0,0 +1,191 @@
+"""Smoke tests for sibyl_memory_client.lint."""
+from __future__ import annotations
+
+import sqlite3
+from pathlib import Path
+
+import pytest
+
+from sibyl_memory_client import (
+    Finding,
+    LintReport,
+    Linter,
+    MemoryClient,
+)
+
+
+# ----------------------------------------------------------------------
+# Fixtures
+# ----------------------------------------------------------------------
+@pytest.fixture
+def client(tmp_path: Path) -> MemoryClient:
+    # Memory linter is paid-tier only. Tests run as a lifetime-tier user.
+    return MemoryClient.local(str(tmp_path / "memory.db"), tier="lifetime")
+
+
+# ----------------------------------------------------------------------
+# Baseline
+# ----------------------------------------------------------------------
+def test_lint_clean_db_has_no_critical(client: MemoryClient) -> None:
+    report = client.lint()
+    assert isinstance(report, LintReport)
+    assert report.ok is True
+    assert report.schema_version >= 2
+    assert report.critical == []
+    # Counts all present
+    assert "entities" in report.counts
+    assert "skill_proposals" in report.counts
+
+
+def test_lint_includes_db_path_and_size(client: MemoryClient) -> None:
+    client.set_entity("project", "atlas", {"status": "active"})
+    report = client.lint()
+    assert report.db_path.endswith("memory.db")
+    assert report.db_size_bytes > 0
+
+
+def test_lint_to_ascii_renders(client: MemoryClient) -> None:
+    report = client.lint()
+    rendered = report.to_ascii()
+    assert "SIBYL MEMORY · LINT REPORT" in rendered
+    assert "schema v" in rendered
+    assert "critical" in rendered
+
+
+# ----------------------------------------------------------------------
+# Specific checks
+# ----------------------------------------------------------------------
+def test_duplicate_entity_finding(client: MemoryClient) -> None:
+    client.set_entity("project", "atlas", {"x": 1})
+    client.set_entity("product", "atlas", {"y": 2})  # same name, different category
+    report = client.lint()
+    msgs = [f.check for f in report.findings]
+    assert "duplicate-entity" in msgs
+
+
+def test_empty_reference_finding(client: MemoryClient) -> None:
+    # Insert an empty reference doc directly via storage to bypass SDK validation
+    with client.storage.transaction() as conn:
+        conn.execute(
+            "INSERT INTO reference_documents (tenant_id, doc_key, body) "
+            "VALUES (?, ?, '')",
+            (client.get_tenant(), "skill/empty-test"),
+        )
+    report = client.lint()
+    assert any(f.check == "empty-reference" for f in report.findings)
+
+
+def test_stale_entity_finding(client: MemoryClient) -> None:
+    # Force-write an entity with an ancient updated_at via direct SQL
+    client.set_entity("project", "ancient", {"created": True})
+    with client.storage.transaction() as conn:
+        conn.execute(
+            "UPDATE entities SET updated_at = '2020-01-01T00:00:00.000Z' "
+            "WHERE tenant_id = ? AND name = 'ancient'",
+            (client.get_tenant(),),
+        )
+    report = client.lint()
+    assert any(f.check == "stale-entity" for f in report.findings)
+
+
+def test_journal_without_acts_finding(client: MemoryClient) -> None:
+    # write_event refuses None for everything; insert directly
+    from sibyl_memory_client.storage import new_id
+    with client.storage.transaction() as conn:
+        conn.execute(
+            "INSERT INTO journal_events (id, tenant_id, ts) VALUES (?, ?, ?)",
+            (new_id(), client.get_tenant(), "2026-05-15T17:30:00.000Z"),
+        )
+    report = client.lint()
+    assert any(f.check == "journal-without-acts" for f in report.findings)
+
+
+def test_soft_cap_critical_threshold(client: MemoryClient) -> None:
+    # Write enough rows to push the DB well above any tiny cap we set.
+    for i in range(20):
+        client.set_entity("project", f"p{i}", {"i": i, "payload": "x" * 200})
+    # Run with a 2 KB cap — well below the actual DB size after writes
+    report = client.lint(soft_cap_bytes=2 * 1024)
+    matches = [f for f in report.findings if f.check == "db-soft-cap"]
+    assert matches, f"expected db-soft-cap finding; got {[f.check for f in report.findings]}"
+    assert matches[0].severity in ("warning", "critical")
+
+
+def test_findings_severity_buckets(client: MemoryClient) -> None:
+    client.set_entity("project", "atlas", {})
+    client.set_entity("person", "atlas", {})  # duplicate name -> warning
+    report = client.lint(soft_cap_bytes=4 * 1024)  # very tiny -> warning or critical
+    # Buckets resolve correctly
+    assert isinstance(report.critical, list)
+    assert isinstance(report.warnings, list)
+    assert isinstance(report.info, list)
+    total = len(report.critical) + len(report.warnings) + len(report.info)
+    assert total == len(report.findings)
+
+
+def test_lint_to_dict_serializes(client: MemoryClient) -> None:
+    report = client.lint()
+    d = report.to_dict()
+    assert "findings" in d
+    assert "counts" in d
+    assert "ok" in d
+    assert "schema_version" in d
+    assert isinstance(d["findings"], list)
+
+
+# ----------------------------------------------------------------------
+# Multi-tenant isolation
+# ----------------------------------------------------------------------
+def test_lint_is_tenant_scoped(tmp_path: Path) -> None:
+    db = tmp_path / "m.db"
+    alice = MemoryClient.local(str(db), tenant_id="alice", tier="lifetime")
+    bob = MemoryClient.local(str(db), tenant_id="bob", tier="lifetime")
+
+    # Only alice creates a duplicate-name pair
+    alice.set_entity("project", "atlas", {})
+    alice.set_entity("product", "atlas", {})
+
+    alice_report = alice.lint()
+    bob_report = bob.lint()
+
+    assert any(f.check == "duplicate-entity" for f in alice_report.findings)
+    assert not any(f.check == "duplicate-entity" for f in bob_report.findings)
+
+
+# ----------------------------------------------------------------------
+# Tier gating — free tier blocked, paid tier allowed
+# ----------------------------------------------------------------------
+def test_free_tier_cannot_lint(tmp_path: Path) -> None:
+    from sibyl_memory_client import TierGateError
+    free = MemoryClient.local(str(tmp_path / "f.db"))  # default tier="free"
+    with pytest.raises(TierGateError) as exc:
+        free.lint()
+    assert exc.value.feature == "memory linter"
+    assert exc.value.current_tier == "free"
+    assert "sibyllabs.org" in exc.value.upgrade_url
+
+
+def test_paid_tiers_can_lint(tmp_path: Path) -> None:
+    for tier in ("sync", "team", "lifetime", "stake", "enterprise"):
+        c = MemoryClient.local(str(tmp_path / f"{tier}.db"), tier=tier)
+        report = c.lint()
+        assert report.ok or report.warnings  # runs without raising
+
+
+def test_free_tier_status_visible_without_gate(tmp_path: Path) -> None:
+    """Free-tier users CAN see their cap status (for upgrade-prompt UX) without
+    being able to call lint() itself."""
+    free = MemoryClient.local(str(tmp_path / "f.db"))
+    status = free.free_tier_status()
+    assert status["tier"] == "free"
+    assert status["soft_cap_bytes"] == 2 * 1024 * 1024
+    assert "upgrade_url" in status
+    assert status["uncapped"] is False
+
+
+def test_paid_tier_status_shows_uncapped(tmp_path: Path) -> None:
+    paid = MemoryClient.local(str(tmp_path / "p.db"), tier="lifetime")
+    status = paid.free_tier_status()
+    assert status["tier"] == "lifetime"
+    assert status["uncapped"] is True
+    assert status["soft_cap_bytes"] is None

sibyl-memory-client/tests/test_smoke.py

@@ -0,0 +1,202 @@
+"""End-to-end smoke test for sibyl-memory-client v0.1.0.
+
+Exercises every public method against a fresh SQLite database in a temp
+directory. Verifies schema applies, FTS5 triggers fire, JSON validation
+holds, and the typed exceptions surface correctly.
+"""
+from __future__ import annotations
+
+import json
+import sqlite3
+import sys
+import tempfile
+from pathlib import Path
+
+# Run from repo: PYTHONPATH=src python tests/test_smoke.py
+sys.path.insert(0, str(Path(__file__).parent.parent / "src"))
+
+from sibyl_memory_client import (
+    DEFAULT_TENANT,
+    MemoryClient,
+    NotFoundError,
+    ValidationError,
+)
+
+
+def test_schema_applies_idempotently(tmp_path):
+    db = tmp_path / "memory.db"
+    client = MemoryClient.local(db)
+    # v2 is the current schema as of 2026-05-15 (added skill_proposals + learning_runs)
+    assert client.schema_version() >= 2, "schema_version should be 2 after first open"
+    # Re-open: no error
+    client2 = MemoryClient.local(db)
+    assert client2.schema_version() >= 2
+    return "schema applies and re-applies idempotently"
+
+
+def test_entity_roundtrip(tmp_path):
+    client = MemoryClient.local(tmp_path / "memory.db")
+    body = {"status": "active", "members": ["a", "b"], "score": 9.5}
+    written = client.set_entity("project", "atlas", body, status="active")
+    assert written["category"] == "project"
+    assert written["name"] == "atlas"
+    assert written["status"] == "active"
+    assert written["body"] == body
+    assert written["tenant_id"] == DEFAULT_TENANT
+    assert written["id"]  # UUID assigned
+
+    read = client.get_entity("project", "atlas")
+    assert read["body"] == body
+
+    # Update via set_entity overwrites
+    body["score"] = 9.7
+    updated = client.set_entity("project", "atlas", body, status="active")
+    assert updated["body"]["score"] == 9.7
+    assert updated["id"] == written["id"], "update preserves entity id"
+    return "entity roundtrip works (insert, read, update)"
+
+
+def test_entity_listing_and_filtering(tmp_path):
+    client = MemoryClient.local(tmp_path / "memory.db")
+    client.set_entity("project", "alpha", {}, status="active")
+    client.set_entity("project", "beta", {}, status="paused")
+    client.set_entity("person", "alice", {}, status="active")
+
+    all_projects = client.list_entities(category="project")
+    assert len(all_projects) == 2, f"expected 2 projects, got {len(all_projects)}"
+
+    active_projects = client.list_entities(category="project", status="active")
+    assert len(active_projects) == 1
+    assert active_projects[0]["name"] == "alpha"
+
+    all_active = client.list_entities(status="active")
+    assert len(all_active) == 2
+    return f"list/filter works: {len(all_projects)} projects, {len(active_projects)} active project"
+
+
+def test_journal_append_and_read(tmp_path):
+    import time
+    client = MemoryClient.local(tmp_path / "memory.db")
+    client.write_event(
+        evaluated=["option A", "option B"],
+        acted=["chose A", "tx 0xabc"],
+        forward=["follow up tomorrow"],
+        extra={"session": "smoke", "n": 1},
+    )
+    time.sleep(0.001)  # guarantee microsecond ts separation across writes
+    client.write_event(acted=["another event"])
+    events = client.read_events(limit=10)
+    assert len(events) == 2, f"expected 2 events, got {len(events)}"
+    # Newest first (ts DESC, id DESC tiebreaker)
+    assert events[0]["acted"] == ["another event"], f"events[0] acted = {events[0]['acted']}"
+    assert events[1]["evaluated"] == ["option A", "option B"], f"events[1] evaluated = {events[1]['evaluated']}"
+    return f"journal append+read works ({len(events)} events round-tripped)"
+
+
+def test_state_documents(tmp_path):
+    client = MemoryClient.local(tmp_path / "memory.db")
+    assert client.get_state("priorities") is None
+    client.set_state("priorities", {"items": [1, 2, 3], "version": "v2"})
+    got = client.get_state("priorities")
+    assert got["body"]["items"] == [1, 2, 3]
+    # Upsert
+    client.set_state("priorities", {"items": [4, 5], "version": "v3"})
+    got2 = client.get_state("priorities")
+    assert got2["body"]["version"] == "v3"
+    return "state_documents upsert + read works"
+
+
+def test_reference_documents(tmp_path):
+    client = MemoryClient.local(tmp_path / "memory.db")
+    client.set_reference(
+        "voice-rules",
+        "no em-dashes, no LLM tells, lowercase ok.",
+        metadata={"applies_to": ["x", "ping", "email"]},
+    )
+    ref = client.get_reference("voice-rules")
+    assert "em-dashes" in ref["body"]
+    assert ref["metadata"]["applies_to"] == ["x", "ping", "email"]
+    return "reference_documents (body + metadata) works"
+
+
+def test_archive_flow(tmp_path):
+    client = MemoryClient.local(tmp_path / "memory.db")
+    client.set_entity("project", "dead-deal", {"note": "abandoned"})
+    result = client.archive_entity("project", "dead-deal", reason="founder disappeared")
+    assert "archived_id" in result
+    # Entity should be gone from active set
+    try:
+        client.get_entity("project", "dead-deal")
+        return "FAIL: archived entity still in active set"
+    except NotFoundError:
+        pass
+    return "archive moves entity out of active set"
+
+
+def test_fts_search(tmp_path):
+    client = MemoryClient.local(tmp_path / "memory.db")
+    client.set_entity("project", "atlas", {"description": "Distributed inference platform"})
+    client.set_entity("project", "horizon", {"description": "On-chain prediction markets"})
+    client.set_entity("person", "alice", {"role": "infrastructure engineer"})
+    results = client.search_entities("inference")
+    assert len(results) >= 1
+    found_names = {r["name"] for r in results}
+    assert "atlas" in found_names
+    return f"FTS5 search works ({len(results)} hits for 'inference')"
+
+
+def test_json_validation(tmp_path):
+    client = MemoryClient.local(tmp_path / "memory.db")
+    class Unserializable:
+        pass
+    try:
+        client.set_entity("test", "broken", {"obj": Unserializable()})
+        return "FAIL: should have raised ValidationError"
+    except ValidationError:
+        pass
+    return "JSON validation rejects unserializable input"
+
+
+def test_tenant_isolation(tmp_path):
+    client_a = MemoryClient.local(tmp_path / "memory.db", tenant_id="tenant-a")
+    client_b = MemoryClient.local(tmp_path / "memory.db", tenant_id="tenant-b")
+    client_a.set_entity("project", "shared-name", {"owner": "a"})
+    client_b.set_entity("project", "shared-name", {"owner": "b"})
+    assert client_a.get_entity("project", "shared-name")["body"]["owner"] == "a"
+    assert client_b.get_entity("project", "shared-name")["body"]["owner"] == "b"
+    return "multi-tenant: same (category, name) isolated by tenant_id"
+
+
+def main():
+    tests = [
+        test_schema_applies_idempotently,
+        test_entity_roundtrip,
+        test_entity_listing_and_filtering,
+        test_journal_append_and_read,
+        test_state_documents,
+        test_reference_documents,
+        test_archive_flow,
+        test_fts_search,
+        test_json_validation,
+        test_tenant_isolation,
+    ]
+    passed = failed = 0
+    for t in tests:
+        with tempfile.TemporaryDirectory() as td:
+            try:
+                msg = t(Path(td))
+                print(f"  PASS  {t.__name__:48s}  {msg}")
+                passed += 1
+            except AssertionError as e:
+                print(f"  FAIL  {t.__name__:48s}  {e}")
+                failed += 1
+            except Exception as e:
+                print(f"  ERR   {t.__name__:48s}  {type(e).__name__}: {e}")
+                failed += 1
+    print()
+    print(f"  {passed}/{len(tests)} passed, {failed} failed")
+    return 0 if failed == 0 else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

sibyl-memory-hermes/CHANGELOG.md

@@ -0,0 +1,411 @@
+# Changelog
+
+All notable changes to `sibyl-memory-hermes` are recorded here. Format
+follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Versioning
+follows [SemVer](https://semver.org/).
+
+## [0.3.4] — 2026-05-20
+
+Branding pass on the vendored banner. Matches the change shipped in
+`sibyl-memory-cli` v0.3.2 in the same session. Operator directive:
+"beneath the large SIBYL title it needs to say underneath the memory
+you can hold in your hand tagline, 'a Sibyl Labs LLC Product.
+Agentic Infrastructure and Memory Products' or something similar."
+
+### Changed
+
+- Vendored `_banner.py` adds an attribution line under the tagline:
+  `a Sibyl Labs LLC Product. Agentic Infrastructure and Memory Products`.
+  Same deepest-gold color as the tagline + ANSI dim so the install
+  ceremony reads SIBYL > tagline > attribution at a glance. Visible
+  on both `install-plugin` and `uninstall-plugin` since both commands
+  print the banner before their section header.
+
+## [0.3.3] — 2026-05-20
+
+Visual identity pass on the `install-plugin` and `uninstall-plugin`
+commands. Operator directive: "typical app patterns — heavy menus on
+install window and initial setup, light on dashboards etc." The
+install-plugin command is THE second-most-ceremonial moment a user has
+with SIBYL (after `sibyl init`), so it gets the full SIBYL banner +
+sectioned numbered onboarding menu treatment.
+
+### Added
+
+- Vendored `_aesthetic.py` and `_banner.py` from `sibyl-memory-cli`
+  (small, stable files; avoids a hard runtime dep on the CLI package).
+- `install-plugin` output: SIBYL gradient banner → section header
+  ("install-plugin · hermes memory provider · drops adapter at...") →
+  KV rows for paths → "WRITING PAYLOAD" eyebrow with ✓ glyphs on each
+  write → success line → "next steps" section header → 3 numbered
+  chips with bold step titles and contextual help underneath each →
+  divider with uninstall hint and docs link.
+- `uninstall-plugin` output: same banner + section header treatment,
+  matching the ceremonial bookend.
+- Status / warning / error lines use the brand palette (jade pulse for
+  success, warm ochre for warn, measured red for error) instead of
+  generic ANSI 31/33.
+
+### Compatibility
+
+- No API changes. Same install_plugin entry point, same flags
+  (--hermes-home, --force, --dry-run).
+- All visual choices honor `NO_COLOR`. `SIBYL_FORCE_COLOR=1` available
+  for non-tty rendering (CI, doc captures).
+- Plain-text fallback preserves structure (still readable in dumb
+  terminals or pipes).
+
+## [0.3.2] — 2026-05-18
+
+KAPPA external-tester remediation release. Family-wide alignment with the
+v0.4.0 client (KAPPA-attributed fixes: exception export path, db file
+perms, identifier validation, FTS5 error surfacing). No Hermes adapter
+code changes in this release.
+
+### Changed
+
+- `sibyl-memory-client` pin: `>=0.3.3` → `>=0.4.0`.
+- KAPPA's fixes flow through automatically. Hermes tools (`sibyl_remember`,
+  `sibyl_recall`, `sibyl_search`, `sibyl_list`) now reject empty / null-byte
+  / oversized identifiers on write and surface malformed FTS5 queries as
+  `ValidationError` instead of silently returning empty.
+
+### Notes
+
+- 40/40 hermes tests pass unchanged. The provider + adapter contract is
+  unchanged from v0.3.1.
+
+---
+
+## [0.3.1] — 2026-05-18
+
+Audit-remediation release. v0.3.0 pre-ship audit (2026-05-18T05:05Z)
+surfaced 10 critical findings across four lanes. This release lands the
+Hermes-side fixes. Companion releases: `sibyl-memory-client` v0.3.3 (engine
++ schema v3 + cross-tier search), `sibyl-memory-cli` v0.1.2,
+`sibyl-memory-mcp` v0.1.1.
+
+### Added
+
+- `tests/test_adapter.py` — full regression coverage for the bundled Hermes
+  adapter. Validates: module imports cleanly off-Hermes (guarded ABC
+  import + tool_error fallback), all 4 tool schemas resolve, end-to-end
+  remember+recall round-trips through `handle_tool_call`, list filtering,
+  cross-tier search hits all four tiers, malformed FTS5 queries don't
+  crash or leak, missing required args produce structured errors,
+  shutdown sets the stop flag, sync_turn during shutdown skips cleanly.
+  Closes audit H1.
+
+### Changed
+
+- **`SibylMemoryProvider.search()` now spans all four tiers** — entities +
+  state + reference + journal. Returns tier-tagged hits (`{tier, key,
+  category, body, snippet, rank, ts}`). The marketing claim of "FTS5
+  across all tiers" is now true. Caller can restrict scope with
+  `tiers=("entity",)` for the pre-v0.3.1 behavior. Backed by the new
+  `MemoryClient.search()` in client v0.3.3.
+- `_hermes_plugin/adapter.py` — Hermes ABC + `tool_error` imports guarded
+  with try/except. The bundled module imports cleanly off-Hermes with
+  no-op fallbacks. Audit P1.
+- `SibylAdapter.sync_turn` retries on transient failure (SQLITE_BUSY etc.)
+  with exponential backoff up to 3 attempts. On final failure escalates
+  from DEBUG to WARNING log. Audit P-C1.
+- `SibylAdapter.shutdown` sets `_shutting_down` BEFORE joining the daemon
+  thread. The worker checks the flag and exits cleanly without issuing
+  a slow cap-gate refresh. Audit P-C2.
+- `SibylAdapter.handle_tool_call` exception path now returns exception
+  class name only, not `str(e)`. Prevents echoing arg contents back to
+  the agent on backend errors. Audit SEC-10.
+- Adapter type hints converted to PEP 604 unions throughout. Audit N5.
+- Default search/list limits extracted as named module constants
+  (`_DEFAULT_SEARCH_LIMIT=10`, `_DEFAULT_LIST_LIMIT=50`). Audit O1.
+- `RECALL_SCHEMA` description documents the row-wrapper return shape
+  explicitly. `SEARCH_SCHEMA` updated for cross-tier coverage. Audit H2.
+- `provider.py` — `recall`, `forget`, `archive`, `set_state`, `get_state`,
+  `set_reference`, `get_reference` docstrings now include explicit
+  `Raises:` sections and document return-shape asymmetry per tier.
+  Audit H2/H3.
+- `install_plugin.py` type hints converted to PEP 604 unions. Audit N5.
+
+### Security
+
+- **SEC-2** — `credentials.write_credentials` now creates files atomically
+  with mode 0o600 set at creation via `os.open(O_WRONLY|O_CREAT|O_EXCL|
+  O_NOFOLLOW, 0o600)`. No more world-readable window between `write_text()`
+  and `os.chmod()` syscalls.
+- **SEC-5** — `install-plugin --force` and `uninstall-plugin` refuse to
+  `shutil.rmtree` any directory that doesn't contain a recognized prior
+  Sibyl install (`plugin.yaml` with `name: sibyl` in the first 10 lines).
+  Prevents destruction of arbitrary user-writable trees from misconfigured
+  HERMES_HOME. Both commands also refuse symlinked destinations.
+- **SEC-11** — `load_credentials` refuses to follow symlinks. Checks
+  `is_symlink()` BEFORE `resolve()`.
+- **SEC-10** — `handle_tool_call` error response carries only the
+  exception class name.
+
+### Fixed
+
+- **H7** — `hermes_bound` property emits `DeprecationWarning` on read.
+  Always returns `False` (unchanged behavior). Slated for removal in v0.4.
+- `test_smoke.py` — schema_version assertion loosened to `>= 2` (audit T4);
+  hermes_bound assertion tightened from `isinstance(..., bool)` to
+  `is False` (audit T3).
+- README quickstart rewritten — removed the fictional
+  `Agent(memory=SibylMemoryProvider())` pattern (audit C5). Replaced
+  with the real flow: `pip install` → `install-plugin` → config.yaml.
+- README "Hermes contract" section rewritten — removed the false claim
+  that `SibylMemoryProvider` inherits Hermes' ABC at import time.
+
+### Dependencies
+
+- `sibyl-memory-client>=0.3.3` (was `>=0.3.2`). Required for cross-tier
+  `MemoryClient.search()` and atomic 0600-at-create.
+- Optional `hermes-agent>=0.13.0` unchanged.
+
+### How to upgrade from v0.3.0
+
+```
+pip install --upgrade sibyl-memory-hermes
+sibyl-memory-hermes install-plugin --force
+```
+
+The local SQLite schema auto-migrates from v2 to v3 on first open after
+upgrade. No application data is lost — FTS5 indexes rebuild from base
+tables. ~50ms per 10k entities on first open, idempotent thereafter.
+
+## [0.3.0] — 2026-05-17
+
+Real Hermes plugin landing. v0.2.x was structurally incompatible with
+Hermes' actual `MemoryProvider` ABC (wrong soft-bind import path, missing
+abstract methods, no plugin-loader awareness). Diagnosed end-to-end against
+the installed hermes-agent 0.13.0 wheel: full ABC source extracted, the
+bundled byterover reference implementation read for the idiomatic pattern,
+side-by-side method mapping built, discovery contract traced through
+`plugins/memory/__init__.py`. Adapter written from that ground-truth read
+and validated via Hermes' own `load_memory_provider('sibyl')` loader.
+
+### Architecture shift
+
+- **Split into SDK + adapter.** `SibylMemoryProvider` is now a pure SDK
+  class — framework-agnostic, no ABC inheritance, no Hermes-specific glue.
+  All Hermes contract code lives in the bundled adapter at
+  `_hermes_plugin/adapter.py`, copied to `$HERMES_HOME/plugins/sibyl/` by
+  the new `sibyl-memory-hermes install-plugin` console script.
+- **Hermes uses filesystem discovery, NOT pip entry points.** Verified
+  against `plugins/memory/__init__.py` source — there is no
+  `importlib.metadata.entry_points()` call anywhere in Hermes' loader.
+  `pip install sibyl-memory-hermes` is necessary but not sufficient; the
+  install-plugin script bridges the gap.
+
+### Added
+
+- **`_hermes_plugin/adapter.py`** — full `MemoryProvider` ABC implementation.
+  - 4 tools exposed: `sibyl_remember`, `sibyl_recall`, `sibyl_search`,
+    `sibyl_list`.
+  - Mandatory methods: `name`, `is_available`, `initialize`,
+    `get_tool_schemas`, `handle_tool_call`.
+  - Recommended overrides: `system_prompt_block` (model-facing tool list),
+    `prefetch` (FTS5 + load_context block, with noise filter),
+    `queue_prefetch` (no-op — local SQLite is fast), `sync_turn`
+    (daemon-threaded per byterover pattern, 5s join + 10s shutdown).
+  - Optional hooks: `on_session_switch`, `on_pre_compress`
+    (paired user+assistant flush), `on_delegation`, `on_memory_write`
+    (accepts `metadata=None` kwarg — avoids the byterover signature bug).
+  - Defensive: `agent_context != 'primary'` guard in sync_turn so cron /
+    subagent runs don't corrupt the user's representation.
+  - `_stable_key()` uses blake2b for deterministic content addressing,
+    so add+remove on the same content actually targets the same entity.
+  - Validated end-to-end via `load_memory_provider('sibyl')` dry-run + all
+    4 tool schemas resolved in OpenAI function-calling format.
+- **`_hermes_plugin/plugin.yaml`** — Hermes plugin metadata
+  (name, description, version, homepage).
+- **`sibyl_memory_hermes.install_plugin`** + console script
+  `sibyl-memory-hermes install-plugin`:
+  - Detects HERMES_HOME from CLI flag → `$HERMES_HOME` env var → `~/.hermes`.
+  - Copies bundled adapter via `importlib.resources` (no fragile path math).
+  - Renames `adapter.py` → `__init__.py` at destination (source can't be
+    `__init__.py` because the Hermes-only imports would TypeError under
+    our standalone tests).
+  - Prints activation steps (config.yaml edit + `sibyl init` reminder).
+  - Flags: `--hermes-home <path>`, `--force`, `--dry-run`.
+- **`sibyl-memory-hermes uninstall-plugin`** counterpart for clean removal.
+
+### Changed (breaking, but no users were affected — the prior path was broken)
+
+- **`SibylMemoryProvider` no longer subclasses `MemoryProvider`.** The
+  conditional soft-bind in v0.2.x always failed (wrong import path); the
+  class was effectively `object`-derived already. v0.3.0 makes that
+  explicit and moves all Hermes glue to the adapter. The `hermes_bound`
+  property and `health()` field are kept for backwards compatibility but
+  always return False; they're deprecated for removal in a future major.
+- **`__init__.py` docstring rewritten.** The fictional `from hermes_agent
+  import Agent; Agent(memory=SibylMemoryProvider())` quickstart is gone —
+  that API never existed in any Hermes release. Replaced with the real
+  install flow (`pip install` → `install-plugin` → config.yaml edit).
+- **`__version__` is now single-sourced** from `importlib.metadata.version(
+  'sibyl-memory-hermes')`. The v0.2.x drift (`__init__.py` said 0.2.1
+  while the wheel was 0.2.2) is no longer possible.
+
+### Fixed
+
+- `provider.py:57` no longer attempts `from hermes_agent.memory import
+  MemoryProvider`. That import path does not exist in hermes-agent — the
+  real module is `agent.memory_provider`. Removed entirely; the SDK class
+  doesn't inherit from the ABC anymore (see Architecture shift above).
+
+### Dependencies
+
+- `sibyl-memory-client>=0.3.2` (was `>=0.3.1` — picks up the cap-gate +
+  HTTPError fixes from yesterday's audit pass).
+- Optional: `hermes-agent>=0.13.0` (was `>=0.10.0` — the ABC is documented
+  for v0.13 specifically; older releases may work but aren't validated).
+
+### How to upgrade from v0.2.x
+
+```
+pip install --upgrade sibyl-memory-hermes
+sibyl-memory-hermes install-plugin
+# edit ~/.hermes/config.yaml: memory.provider: sibyl
+hermes                                # picks up the new tools
+```
+
+If you were importing `from hermes_agent import Agent` (per the old
+docstring), that never worked — delete those lines. If you were using
+`SibylMemoryProvider()` directly from a non-Hermes Python orchestration,
+no changes needed; the SDK surface is unchanged.
+
+### Verification
+
+- Adapter dry-run via Hermes' own `load_memory_provider('sibyl')` returns
+  the SibylAdapter instance with `name='sibyl'`, `is_available()=True`,
+  and all 4 tool schemas resolved.
+- File-bundle validated: `importlib.resources.files('sibyl_memory_hermes.
+  _hermes_plugin').joinpath('adapter.py').read_bytes()` returns the
+  expected 18,118-byte payload.
+- install-plugin smoke-tested against a `/tmp/fake_hermes_home` target —
+  files land at `$HERMES_HOME/plugins/sibyl/{__init__.py, plugin.yaml}`.
+
+### Authorship
+
+Developed by SIBYL, Sibyl Labs LLC. Adapter contract derived from the
+installed hermes-agent 0.13.0 wheel source — `agent/memory_provider.py`
+(the ABC) and `plugins/memory/byterover/` (the idiomatic threading +
+schema pattern). MIT licensed.
+
+## [0.2.2] — 2026-05-16
+
+Audit-remediation release. Companion to `sibyl-memory-client` v0.3.2.
+
+### Changed
+
+- **T2-2 — `SibylMemoryProvider.recall()` narrows exception handling to
+  `NotFoundError` only**. Previously caught bare `Exception`, which
+  swallowed `StorageError` / `TenantError` / `SchemaError` and returned
+  `None` (the Hermes-style soft-miss). That masked real storage failures
+  end-to-end — exactly the silent-fallback pattern that caused the
+  production Bug 2 on the server side. Now `NotFoundError` returns
+  `None` as intended; every other exception propagates so the caller
+  can surface or retry.
+
+### Tests
+
+- 21/21 unchanged, all green. The narrower exception class is a strict
+  subset of the prior catch-all behavior for the soft-miss case.
+
+### Notes
+
+- Depends on `sibyl-memory-client>=0.3.2` to pick up the matching
+  `_check_fn` raise-on-HTTPError fix (T2-3). v0.3.1 still works; the
+  changes are independent.
+
+## [0.2.1] — 2026-05-16
+
+HMAC signed-credentials plumbing. Companion to `sibyl-memory-client`
+v0.3.1 and the api-sibyllabs credential-signer release.
+
+### Changed
+
+- `Credentials` dataclass gained `signature: str | None = None` and
+  `signed_at: str | None = None` fields. Backwards compatible —
+  schema v1 credentials still load with these fields as `None`.
+- `SibylMemoryProvider.__init__` reads the signature + canonical
+  claim from credentials.json and passes them through to
+  `MemoryClient.local()`, which forwards to `CapGate`. The cap gate
+  attaches them to every server-side cap-check request so the server
+  can verify and log tampering.
+- `load_credentials` / `write_credentials` round-trip the new fields.
+
+The verification itself is server-side only (HMAC requires a shared
+secret the client cannot hold). The client's job is to faithfully
+echo back what was issued. Authoritative tier always comes from the
+database.
+
+### Tests
+
+- 21/21 unchanged, all green.
+
+## [0.2.0] — 2026-05-15
+
+Hard-cap plumbing release. Companion to `sibyl-memory-client` v0.3.0.
+
+### Changed
+
+- `SibylMemoryProvider.__init__` now passes `account_id`,
+  `session_token`, and `tier` from `credentials.json` through to
+  `MemoryClient.local()`. The v0.3.0 cap gate uses these to verify
+  the user's actual tier against the server when the local DB
+  approaches 2 MB. Without them, the SDK enforces a strict local
+  2 MB cap with no server-check fallback.
+- `Credentials` dataclass gained an optional `session_token` field
+  (the long-lived bearer issued by the activation flow). Backwards
+  compatible — existing v0.1.x credentials files load fine,
+  `session_token` simply lands as `None`.
+
+### Notes
+
+- Depends on `sibyl-memory-client>=0.3.0`. Earlier clients lack the
+  cap-gate plumbing.
+- Pre-activation users (no credentials.json) still work — they hit
+  the strict local 2 MB cap with no upgrade path until they run
+  `sibyl init`.
+
+## [0.1.1] — 2026-05-15
+
+Patch: stripped placeholder GitHub URLs from pyproject metadata
+(operator scar: never write a link to a domain not verified to
+exist). No code changes.
+
+## [0.1.0] — 2026-05-15
+
+First real release. Replaces the v0.0.1 PyPI name-reservation placeholder.
+
+### Added
+- `SibylMemoryProvider` — Hermes-compatible memory provider on top of
+  `sibyl-memory-client`. Auto-inherits Hermes' `MemoryProvider` ABC when
+  Hermes is installed; degrades to standalone object base when not.
+- Five-tier memory routing: journal (`save_context`/`load_context`),
+  entities (`remember`/`recall`/`list`/`forget`), state (`set_state`/
+  `get_state`), references (`set_reference`/`get_reference`), archive
+  (`archive`), FTS5 (`search`).
+- `Credentials` dataclass + `load_credentials` /  `write_credentials` for
+  the activation file at `~/.sibyl-memory/credentials.json`.
+- `CredentialsNotFoundError` with explicit recovery message pointing the
+  user to `sibyl init`.
+- Auto-detect activation: provider reads credentials.json on construction
+  by default; explicit `tenant_id=` overrides; missing credentials
+  degrade to `DEFAULT_TENANT` so tests / pre-activation use works.
+- `health()` diagnostic dict (used by `sibyl status`).
+- Comprehensive smoke test suite covering provider construction, tier
+  routing, search, archive, credentials, multi-tenant isolation, and
+  Hermes binding state.
+
+### Notes
+- Depends on `sibyl-memory-client>=0.1.0`. No Hermes hard dep — install
+  via `pip install sibyl-memory-hermes[hermes]` to opt into the ABC.
+- License: MIT.
+- Compatible with Python 3.10+.
+
+## [0.0.1] — 2026-05-15 (name-reservation placeholder)
+
+Initial PyPI upload to reserve the package name. Empty package; not
+intended for use. Superseded by v0.1.0 in the same session.

sibyl-memory-hermes/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sibyl Labs LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sibyl-memory-hermes/README.md

@@ -0,0 +1,127 @@
+# sibyl-memory-hermes
+
+**Sibyl Memory SDK + bundled Hermes plugin payload. Local-first, SQLite-backed, structured-tier memory for Hermes v0.13+ (and any Python orchestration that wants direct SDK access).**
+
+The package ships two things:
+1. **`SibylMemoryProvider`** — a framework-agnostic SDK class. Call it directly from any Python code that wants structured local memory.
+2. **A bundled Hermes plugin payload** — a thin adapter implementing Hermes v0.13's `MemoryProvider` ABC. Installed into `$HERMES_HOME/plugins/sibyl/` by the `sibyl-memory-hermes install-plugin` console script.
+
+Memory content lives on the user's own machine, never on our servers. Built on [`sibyl-memory-client`](https://pypi.org/project/sibyl-memory-client/), the SDK foundation.
+
+## Install (Hermes path)
+
+Hermes' loader uses filesystem discovery, NOT pip entry points. A pip install alone won't make Sibyl visible to Hermes — the `install-plugin` console script bridges the gap.
+
+```bash
+pip install sibyl-memory-hermes
+sibyl-memory-hermes install-plugin
+```
+
+Then edit `~/.hermes/config.yaml`:
+
+```yaml
+memory:
+  provider: sibyl
+```
+
+Restart Hermes. Four tools become available to the agent:
+
+- `sibyl_remember(category, name, body)` — store a structured fact
+- `sibyl_recall(category, name)` — look up a known fact
+- `sibyl_search(query)` — FTS5 search across **all four tiers** (entities, state, journal, reference); hits are tier-tagged
+- `sibyl_list(category?, status?)` — browse what's remembered
+
+Optional: lift the 2 MB free-tier cap by binding your account:
+
+```bash
+pip install sibyl-memory-cli
+sibyl init
+```
+
+## Direct SDK use (any Python orchestration)
+
+```python
+from sibyl_memory_hermes import SibylMemoryProvider
+
+provider = SibylMemoryProvider()         # auto-loads ~/.sibyl-memory/credentials.json
+provider.remember("project", "atlas", {"status": "shipping v2 friday"})
+provider.recall("project", "atlas")      # → {id, tenant_id, category, name, body, ...}
+provider.set_state("active_branch", {"name": "v0.3.1"})
+provider.save_context(
+    inputs={"user": "what changed in v0.3.1?"},
+    outputs={"assistant": "..."},
+)
+provider.search("v0.3.1")                # FTS5 across entities + state + reference + journal
+```
+
+## Why "local-first"?
+
+Mem0, Zep, Honcho, and most other agent-memory products centralize user context on their servers. The Sibyl Memory Plugin keeps the data on the user's disk. Our cloud schema has no memory-content tables. Even with admin DB access we cannot read what users have written. That's the difference between *"we promise we don't"* and *"we structurally can't."*
+
+| | Sibyl Memory Plugin | Typical hosted memory |
+|---|---|---|
+| Memory content lives | on user's disk | on vendor's servers |
+| Query latency | local SQLite (sub-ms) | round-trip + vector search |
+| Privacy claim | structurally enforced | policy-only |
+| Free-tier cost to vendor | near-zero | scales with users |
+
+## Architecture: five tiers, not one bucket
+
+The provider routes operations onto the appropriate memory tier instead of dumping everything into a single vector store:
+
+| Intent | Tier | Storage call |
+|---|---|---|
+| save the conversation turn | COLD journal | `save_context(inputs, outputs)` |
+| remember a fact | WARM entity | `remember(category, name, body)` |
+| current state | HOT state | `set_state(key, body)` |
+| lookup a runbook | REFERENCE | `set_reference(key, body)` |
+| archive stale entity | ARCHIVE | `archive(category, name)` |
+| search by content | FTS5 cross-tier | `search(query)` → tier-tagged hits |
+
+Different intents, different lookups, no embedding model required. FTS5 covers full-text search out of the box.
+
+## Hermes contract
+
+The Hermes plugin is implemented by a bundled adapter at `_hermes_plugin/adapter.py`. The adapter is copied into `$HERMES_HOME/plugins/sibyl/` by the `install-plugin` console script and is what Hermes' filesystem loader picks up. The adapter implements Hermes v0.13's `MemoryProvider` ABC and delegates every call to `SibylMemoryProvider`.
+
+The SDK class itself (`SibylMemoryProvider`) is framework-agnostic — it does not inherit from any framework ABC. This is the v0.3.0 architecture shift. v0.2.x and earlier attempted soft-inheritance via a broken import path; that path was removed and the adapter pattern replaced it.
+
+## Activation
+
+Most users get here via the `sibyl init` CLI (from [`sibyl-memory-cli`](https://pypi.org/project/sibyl-memory-cli/)), which writes `~/.sibyl-memory/credentials.json` after browser authentication. The provider auto-detects this file on construction.
+
+For pre-activation use (tests, internal tooling):
+
+```python
+from sibyl_memory_hermes import SibylMemoryProvider
+
+provider = SibylMemoryProvider(
+    db_path="/tmp/test-memory.db",
+    tenant_id="test-user",
+    autoload_credentials=False,
+)
+```
+
+## Free tier
+
+- 2 MB local soft cap (with server-authoritative tier verification at the cap boundary)
+- Single device
+- All five tiers (HOT/WARM/COLD/REFERENCE/ARCHIVE)
+- FTS5 full-text search across entities + state + reference + journal
+- Multi-tenant isolation
+
+Paid tiers (Stake, Sync, Lifetime, Enterprise) unlock self-learning, the memory check-up, no cap, and (in build) cross-device encrypted sync. See [docs.sibyllabs.org/memory/tiers](https://docs.sibyllabs.org/memory/tiers).
+
+## Documentation
+
+- Full docs: [docs.sibyllabs.org/memory/](https://docs.sibyllabs.org/memory/)
+- Hermes integration guide: [docs.sibyllabs.org/memory/integrations#hermes](https://docs.sibyllabs.org/memory/integrations#hermes)
+- Install guide: [docs.sibyllabs.org/memory/install](https://docs.sibyllabs.org/memory/install)
+
+## License
+
+MIT. Package on PyPI: [pypi.org/project/sibyl-memory-hermes](https://pypi.org/project/sibyl-memory-hermes/).
+
+## Citation
+
+The Sibyl Memory Plugin holds #2 globally on the LongMemEval Oracle benchmark. The benchmark methodology and report are at [blog.sibylcap.com/longmemeval-v2](https://blog.sibylcap.com/longmemeval-v2).

sibyl-memory-hermes/pyproject.toml

@@ -0,0 +1,64 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sibyl-memory-hermes"
+version = "0.3.4"
+description = "Sibyl Memory SDK + bundled Hermes plugin payload. Local-first, SQLite-backed, structured-tier memory for Hermes v0.13+ (and any other Python orchestration that wants direct SDK access)."
+authors = [{ name = "SIBYL, Sibyl Labs LLC", email = "sibyl@sibyllabs.org" }]
+license = { text = "MIT" }
+readme = "README.md"
+requires-python = ">=3.10"
+keywords = [
+  "sibyl", "memory", "hermes", "hermes-agent", "agent", "sqlite",
+  "local-first", "agentic-memory", "agent-framework", "fts5",
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+  "sibyl-memory-client>=0.4.0",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=7.0",
+  "pytest-cov>=4.0",
+]
+# Hermes is NOT a hard dep. Users who want the Hermes integration install
+# hermes-agent separately + run `sibyl-memory-hermes install-plugin` to
+# drop the bundled adapter into $HERMES_HOME/plugins/sibyl/.
+hermes = [
+  "hermes-agent>=0.13.0",
+]
+
+[project.scripts]
+sibyl-memory-hermes = "sibyl_memory_hermes.install_plugin:main"
+
+[project.urls]
+Homepage = "https://sibyllabs.org/memory"
+Documentation = "https://docs.sibyllabs.org/memory/integrations"
+Repository = "https://github.com/sibyllabs/sibyl-memory-plugin"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["sibyl_memory_hermes*"]
+
+[tool.setuptools.package-data]
+# Bundle the validated Hermes plugin adapter + metadata. The install-plugin
+# console script reads these via importlib.resources and copies bytes to
+# $HERMES_HOME/plugins/sibyl/ (renaming adapter.py → __init__.py at dest).
+"sibyl_memory_hermes._hermes_plugin" = ["adapter.py", "plugin.yaml"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra"

sibyl-memory-hermes/src/sibyl_memory_hermes/__init__.py

@@ -0,0 +1,93 @@
+"""sibyl-memory-hermes — Sibyl Memory SDK + bundled Hermes plugin payload.
+
+Public exports:
+    SibylMemoryProvider     framework-agnostic Sibyl Memory SDK class
+    DEFAULT_DB_PATH         ~/.sibyl-memory/memory.db
+    DEFAULT_CRED_PATH       ~/.sibyl-memory/credentials.json
+    load_credentials        helper for reading the activation credential file
+    HermesMemoryError       base exception (re-exports SibylMemoryError)
+
+ARCHITECTURE (v0.3.0+)
+======================
+
+This package ships two things:
+
+  1. `SibylMemoryProvider` — a pure-Python SDK class. Framework-agnostic.
+     Routes memory operations across the five Sibyl tiers (warm entities,
+     hot state, cold journal, reference docs, archive). Can be called
+     directly by any orchestration that wants a structured local memory
+     backend.
+
+  2. A bundled Hermes plugin payload (`_hermes_plugin/`) — a thin adapter
+     implementing Hermes v0.13+ `MemoryProvider` ABC that delegates to
+     `SibylMemoryProvider`. Installed into `$HERMES_HOME/plugins/sibyl/`
+     by the `sibyl-memory-hermes install-plugin` console script.
+
+Hermes' plugin loader uses filesystem discovery, NOT pip entry points
+(verified against `plugins/memory/__init__.py` source 2026-05-17). A pip
+install alone won't make Sibyl visible to Hermes — the install-plugin
+script bridges that gap.
+
+HERMES INSTALL FLOW
+===================
+
+    pip install sibyl-memory-hermes
+    sibyl-memory-hermes install-plugin
+
+    # then edit ~/.hermes/config.yaml:
+    #   memory:
+    #     provider: sibyl
+
+    # (optional) bind your account to lift the 2 MB free-tier cap:
+    pip install sibyl-memory-cli
+    sibyl init
+
+    hermes                         # sibyl_remember / recall / search / list
+                                   # now available to the agent
+
+DIRECT SDK USAGE (any Python orchestration)
+===========================================
+
+    from sibyl_memory_hermes import SibylMemoryProvider
+
+    provider = SibylMemoryProvider()         # auto-loads credentials.json
+    provider.remember("project", "atlas", {"status": "shipping v2 friday"})
+    provider.recall("project", "atlas")
+    provider.search("SAML", limit=10)
+
+See https://docs.sibyllabs.org/memory/integrations for the full integration
+matrix (Claude Code, Codex, Cursor, Continue, LangChain, LlamaIndex, custom).
+"""
+from importlib.metadata import PackageNotFoundError, version as _pkg_version
+
+from sibyl_memory_client import SibylMemoryError
+
+from .credentials import (
+    DEFAULT_CRED_PATH,
+    DEFAULT_DB_PATH,
+    Credentials,
+    CredentialsNotFoundError,
+    load_credentials,
+)
+from .provider import SibylMemoryProvider
+
+# Single-sourced from installed metadata. Fallback for editable / source-tree
+# usage where metadata isn't populated yet.
+try:
+    __version__ = _pkg_version("sibyl-memory-hermes")
+except PackageNotFoundError:  # pragma: no cover - source-tree dev only
+    __version__ = "0.0.0+source"
+
+# Backwards-compat alias for callers who want a Hermes-namespaced exception type
+HermesMemoryError = SibylMemoryError
+
+__all__ = [
+    "SibylMemoryProvider",
+    "Credentials",
+    "CredentialsNotFoundError",
+    "DEFAULT_DB_PATH",
+    "DEFAULT_CRED_PATH",
+    "load_credentials",
+    "HermesMemoryError",
+    "__version__",
+]

sibyl-memory-hermes/src/sibyl_memory_hermes/_aesthetic.py

@@ -0,0 +1,279 @@
+"""Shared visual identity for the sibyl CLI surface.
+
+Sister module to `_banner.py`. Where the banner is the identity-reveal
+moment for `sibyl init`, this module supplies the granular building
+blocks every subcommand uses to share one coherent look:
+
+  - 24-bit-truecolor → 256-color → plain-text degradation cascade
+  - Brand palette derived from the lab creme paper face (rule 46)
+  - Letter-spaced eyebrow labels, gradient titles, ASCII rule dividers
+  - Key/value rows, status chips, success/warn/error glyphs
+  - Pulsing accents for live states (activation, upgrade, watching)
+
+Voice constraint: precise, editorial, restrained. Gradients flow over
+2–3 stops max. No rainbow. The terminal is paper.
+"""
+from __future__ import annotations
+
+import os
+import sys
+from typing import Iterable
+
+# ─── Palette (RGB · derived from rule 46 creme-paper tokens) ─────────
+# Names map 1:1 to CSS custom properties on lab artifacts.
+
+PAPER       = (245, 241, 230)   # --paper        — foreground accent on dark
+PAPER_DEEP  = (237, 230, 211)   # --paper-deep   — depth on creme
+CARD        = (253, 251, 245)   # --card         — slightly lifted creme
+INK         = (21,  17,  10)    # --ink          — main text on creme
+INK_SOFT    = (44,  39,  29)    # --ink-soft     — body text
+INK_MUTE    = (106, 99,  86)    # --ink-mute     — secondary text
+INK_FAINT   = (152, 145, 127)   # --ink-faint    — tertiary text
+RULE        = (216, 208, 187)   # --rule         — hairline
+RULE_STRONG = (184, 174, 147)   # --rule-strong  — emphasised hairline
+ACCENT      = (138, 106, 42)    # --accent       — ochre highlight
+ACCENT_WARM = (160, 132, 56)    # --accent-warm  — softer ochre
+ACCENT_GOLD = (224, 194, 119)   # mid gold       — gradient bridge
+ACCENT_PALE = (244, 229, 184)   # pale gold      — gradient top
+JADE        = (45,  110, 106)   # --jade         — cool counterpoint
+PULSE       = (29,  138, 130)   # --pulse        — brighter jade (live signal)
+ERROR       = (162, 58,  42)    # --error        — measured red
+
+# Status glyphs (Unicode, terminal-safe in modern fonts)
+GLYPH_OK    = "✓"
+GLYPH_WARN  = "⚠"
+GLYPH_ERR   = "✗"
+GLYPH_DOT   = "·"
+GLYPH_ARROW = "→"
+GLYPH_BULLET = "▸"
+
+
+# ─── Terminal capability detection ────────────────────────────────────
+
+def supports_truecolor() -> bool:
+    """24-bit RGB ANSI. Same heuristic as _banner.py."""
+    if os.environ.get("NO_COLOR"):
+        return False
+    if os.environ.get("TERM", "").lower() == "dumb":
+        return False
+    # SIBYL_FORCE_COLOR=1 — explicit override for non-tty rendering
+    # (CI logs, doc captures, dev inspection in non-tty environments).
+    if os.environ.get("SIBYL_FORCE_COLOR") == "1":
+        return True
+    if not sys.stdout.isatty():
+        return False
+    colorterm = os.environ.get("COLORTERM", "").lower()
+    if "truecolor" in colorterm or "24bit" in colorterm:
+        return True
+    term_program = os.environ.get("TERM_PROGRAM", "").lower()
+    if term_program in {"iterm.app", "wezterm", "ghostty", "vscode", "tabby"}:
+        return True
+    term = os.environ.get("TERM", "").lower()
+    if any(k in term for k in ("256color", "kitty", "alacritty", "xterm-direct")):
+        return True
+    return False
+
+
+def supports_color() -> bool:
+    """Any color at all (3/4-bit fallback)."""
+    if os.environ.get("NO_COLOR"):
+        return False
+    if os.environ.get("TERM", "").lower() == "dumb":
+        return False
+    if os.environ.get("SIBYL_FORCE_COLOR") == "1":
+        return True
+    return sys.stdout.isatty()
+
+
+_TC = supports_truecolor()
+_C  = supports_color()
+RESET = "\033[0m" if _C else ""
+
+
+def rgb(r: int, g: int, b: int) -> str:
+    """24-bit foreground escape (no-op if color disabled)."""
+    if not _TC:
+        return ""
+    return f"\033[38;2;{r};{g};{b}m"
+
+
+def rgb_bg(r: int, g: int, b: int) -> str:
+    if not _TC:
+        return ""
+    return f"\033[48;2;{r};{g};{b}m"
+
+
+def color(text: str, c: tuple[int, int, int]) -> str:
+    if not _TC:
+        return text
+    return f"{rgb(*c)}{text}{RESET}"
+
+
+# ─── Gradient · char-by-char RGB interpolation ────────────────────────
+
+def _interp(a: int, b: int, t: float) -> int:
+    return round(a + (b - a) * t)
+
+
+def gradient(text: str, *stops: tuple[int, int, int]) -> str:
+    """Color a string with a gradient across N stops, one char at a time.
+
+    Plain-text fallback: returns the input unchanged when color is off.
+    Whitespace is preserved (uncolored to keep terminals consistent).
+    """
+    if not _TC or len(stops) < 2 or not text:
+        return text
+    out = []
+    chars = list(text)
+    # Distribute char index across stop segments
+    n = max(1, len(chars) - 1)
+    segs = len(stops) - 1
+    for i, ch in enumerate(chars):
+        if ch == " ":
+            out.append(ch)
+            continue
+        seg_f = (i / n) * segs
+        seg_i = min(int(seg_f), segs - 1)
+        t = seg_f - seg_i
+        a = stops[seg_i]
+        b = stops[seg_i + 1]
+        r = _interp(a[0], b[0], t)
+        g = _interp(a[1], b[1], t)
+        bb = _interp(a[2], b[2], t)
+        out.append(f"\033[38;2;{r};{g};{bb}m{ch}")
+    return "".join(out) + RESET
+
+
+def gradient_gold(text: str) -> str:
+    """Pale-gold → deep-ochre flow. The brand's headline gradient."""
+    return gradient(text, ACCENT_PALE, ACCENT_GOLD, ACCENT)
+
+
+def gradient_jade(text: str) -> str:
+    """Pulse → jade. Used for success states + live indicators."""
+    return gradient(text, PULSE, JADE)
+
+
+# ─── Style primitives ─────────────────────────────────────────────────
+
+def dim(s: str) -> str:
+    return color(s, INK_FAINT)
+
+
+def muted(s: str) -> str:
+    return color(s, INK_MUTE)
+
+
+def soft(s: str) -> str:
+    return color(s, INK_SOFT)
+
+
+def ink(s: str) -> str:
+    return color(s, INK)
+
+
+def ok(s: str) -> str:
+    return color(s, PULSE)
+
+
+def warn(s: str) -> str:
+    return color(s, ACCENT_WARM)
+
+
+def err(s: str) -> str:
+    return color(s, ERROR)
+
+
+def accent(s: str) -> str:
+    return color(s, ACCENT)
+
+
+def bold(s: str) -> str:
+    if not _C:
+        return s
+    return f"\033[1m{s}{RESET}"
+
+
+# ─── Composite primitives ─────────────────────────────────────────────
+
+def eyebrow(label: str) -> str:
+    """Uppercase letter-spaced ochre label. Editorial section marker."""
+    spaced = " ".join(label.upper())
+    return color(spaced, ACCENT)
+
+
+def divider(width: int = 60, *, glyph: str = "─") -> str:
+    """Creme-paper rule line."""
+    return color(glyph * width, RULE)
+
+
+def section_header(name: str, *, subtitle: str | None = None, width: int = 60) -> str:
+    """The standard subcommand opener.
+
+       ─ <name> ────────────────────────────────────────
+       <subtitle, dim>
+    """
+    name_part = f" {gradient_gold(name)} "
+    # Stripped-color length for visible width calc
+    visible_name_len = len(f" {name} ")
+    rule_left = "─"
+    rule_right = "─" * max(3, width - 1 - visible_name_len)
+    head = color(rule_left, RULE) + name_part + color(rule_right, RULE)
+    if subtitle:
+        return head + "\n" + dim(subtitle)
+    return head
+
+
+def chip(text: str, *, palette: str = "accent") -> str:
+    """Compact inline label · [text]."""
+    palettes = {
+        "accent": ACCENT,
+        "jade":   PULSE,
+        "warn":   ACCENT_WARM,
+        "error":  ERROR,
+        "mute":   INK_MUTE,
+    }
+    c = palettes.get(palette, ACCENT)
+    return color(f"[{text}]", c)
+
+
+def kv(label: str, value: str, *, label_width: int = 16, value_color: str = "ink") -> str:
+    """One left-aligned label / value row.
+
+    Used across status / whoami / devices for the LOCAL / SERVER blocks.
+    """
+    palettes = {
+        "ink": INK, "soft": INK_SOFT, "mute": INK_MUTE, "faint": INK_FAINT,
+        "accent": ACCENT, "ok": PULSE, "warn": ACCENT_WARM, "err": ERROR,
+    }
+    val_color = palettes.get(value_color, INK_SOFT)
+    return f"  {color(label.ljust(label_width), INK_FAINT)} {color(value, val_color)}"
+
+
+def block_title(text: str) -> str:
+    """Sub-section title within a command output. Like 'LOCAL' or 'SERVER'."""
+    return "\n" + eyebrow(text)
+
+
+def success_line(text: str) -> str:
+    """Single-line success marker with gradient + glyph."""
+    return f"  {ok(GLYPH_OK)} {gradient_jade(text)}"
+
+
+def warn_line(text: str) -> str:
+    return f"  {warn(GLYPH_WARN)} {warn(text)}"
+
+
+def err_line(text: str) -> str:
+    return f"  {err(GLYPH_ERR)} {err(text)}"
+
+
+def hr_caption(caption: str, *, width: int = 60) -> str:
+    """Caption line under a divider — small, muted, centered."""
+    pad = max(0, (width - len(caption)) // 2)
+    return " " * pad + dim(caption)
+
+
+def footer_credits(*, width: int = 60) -> str:
+    """Bottom-of-output line. Used at end of long outputs."""
+    return color("─" * width, RULE) + "\n" + dim("  sibyl labs · memory you can hold in your hand")

sibyl-memory-hermes/src/sibyl_memory_hermes/_banner.py

@@ -0,0 +1,123 @@
+"""ASCII banner for sibyl-memory-cli.
+
+Prints the SIBYL wordmark in ANSI Shadow boxchars with a 24-bit truecolor
+vertical gradient flowing from cream/white at the top through warm gold
+to deep ochre at the bottom — aligned with the lab visual identity per
+the operator's brand-discipline rule (creme palette, deep-ochre accent).
+
+Gracefully degrades:
+  - NO_COLOR env var set       → plain text fallback
+  - stdout is not a TTY        → plain text fallback (or skip entirely)
+  - TERM=dumb                  → plain text fallback
+
+Truecolor support is detected via $COLORTERM (truecolor / 24bit) — most
+modern terminals (iTerm2, Alacritty, Kitty, wezterm, Windows Terminal,
+modern xterm builds, Ghostty) advertise it. Falls back to 256-color
+gradient when not available.
+"""
+from __future__ import annotations
+
+import os
+import sys
+
+# ANSI Shadow rendering of "SIBYL" — 6 rows, 41 cols. Each row gets its
+# own gradient color (top = pale cream/white, bottom = deep ochre).
+_LINES = (
+    "███████╗██╗██████╗ ██╗   ██╗██╗     ",
+    "██╔════╝██║██╔══██╗╚██╗ ██╔╝██║     ",
+    "███████╗██║██████╔╝ ╚████╔╝ ██║     ",
+    "╚════██║██║██╔══██╗  ╚██╔╝  ██║     ",
+    "███████║██║██████╔╝   ██║   ███████╗",
+    "╚══════╝╚═╝╚═════╝    ╚═╝   ╚══════╝",
+)
+
+# Vertical gradient · cream → gold → deep ochre. One RGB tuple per row.
+# Tuned against the SIBYL palette: --paper #f5f1e6 (top blend),
+# --accent #8a6a2a (mid-bottom), with extra highlight + shadow stops
+# to give the wordmark visible dimension.
+_GRADIENT = (
+    (253, 251, 245),   # almost white, slight cream      (top highlight)
+    (244, 229, 184),   # pale gold                       (upper)
+    (224, 194, 119),   # mid gold                        (upper-mid)
+    (184, 146,  73),   # rich ochre gold                 (mid)
+    (138, 106,  42),   # deep ochre · brand --accent     (lower)
+    (106,  79,  31),   # deepest                         (bottom shadow)
+)
+
+_TAGLINE = "memory you can hold in your hand"
+_ATTRIBUTION = "a Sibyl Labs LLC Product. Agentic Infrastructure and Memory Products"
+
+
+def _supports_truecolor() -> bool:
+    """Detect 24-bit color support. Conservative — fall back gracefully."""
+    if os.environ.get("NO_COLOR"):
+        return False
+    if os.environ.get("TERM", "").lower() == "dumb":
+        return False
+    if not sys.stdout.isatty():
+        return False
+    colorterm = os.environ.get("COLORTERM", "").lower()
+    if "truecolor" in colorterm or "24bit" in colorterm:
+        return True
+    # Many modern terminals don't set COLORTERM but do support truecolor.
+    # Recognize the well-behaved emitters.
+    term_program = os.environ.get("TERM_PROGRAM", "").lower()
+    if term_program in {"iterm.app", "wezterm", "ghostty", "vscode", "tabby"}:
+        return True
+    term = os.environ.get("TERM", "").lower()
+    if any(k in term for k in ("256color", "kitty", "alacritty", "xterm-direct")):
+        return True
+    return False
+
+
+def _color_supported() -> bool:
+    """Plain ANSI color (3/4-bit). Stricter than truecolor."""
+    if os.environ.get("NO_COLOR"):
+        return False
+    if os.environ.get("TERM", "").lower() == "dumb":
+        return False
+    return sys.stdout.isatty()
+
+
+def _rgb(r: int, g: int, b: int) -> str:
+    return f"\033[38;2;{r};{g};{b}m"
+
+
+_RESET = "\033[0m"
+
+
+def render_banner(*, force_color: bool | None = None) -> str:
+    """Return the banner as a string ready to print.
+
+    Args:
+        force_color: Override auto-detection. None = auto, True = force
+            truecolor, False = force plain text. Useful for testing.
+    """
+    use_truecolor = force_color if force_color is not None else _supports_truecolor()
+
+    if not use_truecolor:
+        # Plain text — still visually clean, just no color.
+        body = "\n".join("  " + line for line in _LINES)
+        tagline = f"\n  {_TAGLINE}"
+        attribution = f"\n  {_ATTRIBUTION}\n"
+        return body + tagline + attribution
+
+    # Colored — apply per-row gradient.
+    colored_lines = []
+    for line, (r, g, b) in zip(_LINES, _GRADIENT):
+        colored_lines.append(f"  {_rgb(r, g, b)}{line}{_RESET}")
+
+    body = "\n".join(colored_lines)
+    # Tagline in the deepest gold — present, but not competing with the wordmark.
+    r, g, b = _GRADIENT[-1]
+    tagline = f"\n  {_rgb(r, g, b)}{_TAGLINE}{_RESET}"
+    # Attribution dimmer still — a half-step below the tagline so the hierarchy
+    # reads SIBYL > tagline > attribution at a glance. ANSI dim (\033[2m) gives
+    # ~55% perceived opacity across the supported terminals.
+    attribution = f"\n  \033[2m{_rgb(r, g, b)}{_ATTRIBUTION}{_RESET}\n"
+    return body + tagline + attribution
+
+
+def print_banner(*, force_color: bool | None = None) -> None:
+    """Print the banner. Safe to call unconditionally; honors NO_COLOR + TTY checks."""
+    print(render_banner(force_color=force_color))

sibyl-memory-hermes/src/sibyl_memory_hermes/_hermes_plugin/__init__.py

@@ -0,0 +1,12 @@
+"""Bundled Hermes plugin payload — NOT for direct import.
+
+Contains the validated MemoryProvider adapter (`adapter.py`) and its
+metadata (`plugin.yaml`). The `sibyl-memory-hermes install-plugin`
+console script copies these files to $HERMES_HOME/plugins/sibyl/ where
+Hermes' loader discovers them.
+
+`adapter.py` is intentionally NOT named `__init__.py` here: it imports
+`agent.memory_provider` which only exists inside a Hermes-installed
+environment. Naming it as a module member would cause Python to attempt
+to load it on package import and fail in our test environments.
+"""

sibyl-memory-hermes/src/sibyl_memory_hermes/_hermes_plugin/adapter.py

@@ -0,0 +1,531 @@
+"""Sibyl memory plugin — MemoryProvider adapter for sibyl-memory-hermes.
+
+Developed by SIBYL, Sibyl Labs LLC. MIT licensed.
+
+Bridges the Hermes v0.13 MemoryProvider ABC to the framework-agnostic
+SibylMemoryProvider exposed by the `sibyl-memory-hermes` SDK package.
+
+Why an adapter exists:
+    sibyl-memory-hermes ships a rich, LangChain-flavored surface
+    (save_context/load_context/remember/recall/search/set_state/...) but
+    does NOT implement Hermes' MemoryProvider ABC. This module is the
+    thin wrapper that exposes the SDK to Hermes' plugin loader.
+
+Install location:
+    Drop this directory at one of:
+      $HERMES_HOME/plugins/sibyl/     (user install)
+      <site-packages>/plugins/memory/sibyl/   (bundled install)
+    Then activate via config.yaml:
+      memory:
+        provider: sibyl
+
+Configuration:
+    Credentials live in ~/.sibyl-memory/credentials.json (managed by the
+    `sibyl init` CLI). This adapter does not duplicate that — it lets the
+    SDK auto-load credentials. The only Hermes-side option is `db_path`,
+    which defaults to <HERMES_HOME>/sibyl/memory.db so each profile has
+    its own database.
+
+v0.3.1 hardening (audit-remediation):
+    - Hermes ABC + tool_error imports are guarded — module imports cleanly
+      outside Hermes (tests, dry-run tooling). Off-Hermes the adapter
+      degrades to a no-op MemoryProvider base; the tool dispatcher still
+      works for offline validation.
+    - sync_turn daemon uses retry-on-busy with backoff + WARNING log on
+      final drop (was: silent log-and-drop).
+    - shutdown sets a stop flag the daemon checks before issuing slow
+      writes, so 10-second join-on-shutdown doesn't drop in-flight turns.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import threading
+import time
+from hashlib import blake2b
+from pathlib import Path
+from typing import Any
+
+# ---------------------------------------------------------------------------
+# Hermes-side imports (guarded so the module loads off-Hermes for tests)
+# ---------------------------------------------------------------------------
+try:
+    from agent.memory_provider import MemoryProvider  # type: ignore[import-not-found]
+    from tools.registry import tool_error  # type: ignore[import-not-found]
+    _HERMES_AVAILABLE = True
+except ImportError:
+    # Off-Hermes (test runner, dry-run, generic Python). Provide a no-op
+    # base + a tool_error stub that returns the same JSON shape Hermes
+    # would. The bundled module stays importable.
+    _HERMES_AVAILABLE = False
+
+    class MemoryProvider:  # type: ignore[no-redef]
+        """Standalone fallback base when hermes-agent isn't installed."""
+        pass
+
+    def tool_error(msg: str) -> str:  # type: ignore[misc]
+        return json.dumps({"error": msg})
+
+
+logger = logging.getLogger(__name__)
+
+# Timeouts + sizes — all named constants, no magic numbers in dispatch logic.
+_SYNC_JOIN_TIMEOUT = 5.0          # wait this long for previous sync_turn write
+_SHUTDOWN_JOIN_TIMEOUT = 10.0     # wait this long on shutdown
+_MIN_QUERY_LEN = 10               # skip tiny prefetch queries (noise)
+_PREFETCH_LIMIT = 5               # how many search hits to inject
+_MAX_PREFETCH_CHARS = 6000        # trim prefetch block
+_DEFAULT_SEARCH_LIMIT = 10        # sibyl_search default limit
+_DEFAULT_LIST_LIMIT = 50          # sibyl_list default limit
+_BUSY_RETRY_ATTEMPTS = 3          # sync_turn retry-on-busy attempts
+_BUSY_RETRY_BACKOFF = 0.2         # base seconds between retries
+
+
+def _hermes_home() -> Path:
+    """Resolve $HERMES_HOME at call time (profiles can rebind it)."""
+    from hermes_constants import get_hermes_home  # type: ignore[import-not-found]
+    return get_hermes_home()
+
+
+def _stable_key(content: str, prefix: str = "") -> str:
+    """Deterministic short id for on_memory_write mirroring.
+
+    blake2b keeps the value stable across runs so add+remove on the same
+    content actually targets the same entity name.
+    """
+    h = blake2b(content.encode("utf-8", errors="replace"), digest_size=6).hexdigest()
+    return f"{prefix}{h}" if prefix else h
+
+
+# ---------------------------------------------------------------------------
+# Tool schemas — OpenAI function-calling shape
+# ---------------------------------------------------------------------------
+
+REMEMBER_SCHEMA = {
+    "name": "sibyl_remember",
+    "description": (
+        "Upsert a structured fact into Sibyl's warm-entity tier. Use for "
+        "anything worth remembering across sessions: project decisions, user "
+        "preferences, API quirks, conventions. (category, name) is the unique "
+        "key — re-calling with the same pair overwrites."
+    ),
+    "parameters": {
+        "type": "object",
+        "properties": {
+            "category": {
+                "type": "string",
+                "description": "Logical grouping, e.g. 'project', 'user', 'pattern', 'decision'.",
+            },
+            "name": {
+                "type": "string",
+                "description": "Short identifier unique within the category.",
+            },
+            "body": {
+                "type": "object",
+                "description": "JSON body describing the entity. Free-form dict.",
+            },
+            "status": {
+                "type": "string",
+                "description": "Optional lifecycle status (e.g. 'active', 'draft').",
+            },
+        },
+        "required": ["category", "name", "body"],
+    },
+}
+
+RECALL_SCHEMA = {
+    "name": "sibyl_recall",
+    "description": (
+        "Look up a single entity by (category, name). Returns the entity row "
+        "(or null if absent) shaped {id, tenant_id, category, name, status, "
+        "body, created_at, updated_at} — the user data is under .body. Use "
+        "when you know exactly what to fetch; use sibyl_search for fuzzy/keyword lookup."
+    ),
+    "parameters": {
+        "type": "object",
+        "properties": {
+            "category": {"type": "string", "description": "Category the entity lives under."},
+            "name":     {"type": "string", "description": "Entity name within the category."},
+        },
+        "required": ["category", "name"],
+    },
+}
+
+SEARCH_SCHEMA = {
+    "name": "sibyl_search",
+    "description": (
+        "FTS5 full-text search across ALL Sibyl tiers (entities + state + "
+        "reference + journal) for this tenant. Each hit carries a `tier` tag "
+        "so you know where the match came from. Returns ranked matches. Use "
+        "whenever you want past context but don't know the exact (category, name)."
+    ),
+    "parameters": {
+        "type": "object",
+        "properties": {
+            "query": {"type": "string", "description": "Search query. User input is sanitized as a single FTS5 phrase — column-filter syntax (name:foo) is treated as literal text."},
+            "limit": {
+                "type": "integer",
+                "description": f"Max results (default {_DEFAULT_SEARCH_LIMIT}).",
+                "default": _DEFAULT_SEARCH_LIMIT,
+            },
+        },
+        "required": ["query"],
+    },
+}
+
+LIST_SCHEMA = {
+    "name": "sibyl_list",
+    "description": (
+        "List entities, optionally filtered by category and/or status. "
+        "Use for browsing what's been remembered rather than recalling a "
+        "specific item."
+    ),
+    "parameters": {
+        "type": "object",
+        "properties": {
+            "category": {
+                "type": "string",
+                "description": "Optional: restrict to this category.",
+            },
+            "status": {
+                "type": "string",
+                "description": "Optional: restrict to entities with this status.",
+            },
+            "limit": {
+                "type": "integer",
+                "description": f"Max entries to return (default {_DEFAULT_LIST_LIMIT}).",
+                "default": _DEFAULT_LIST_LIMIT,
+            },
+        },
+        "required": [],
+    },
+}
+
+
+# ---------------------------------------------------------------------------
+# Adapter
+# ---------------------------------------------------------------------------
+
+class SibylAdapter(MemoryProvider):
+    """Hermes MemoryProvider that delegates to sibyl-memory-hermes."""
+
+    def __init__(self) -> None:
+        self._sibyl = None  # type: ignore[assignment]  # set in initialize()
+        self._session_id: str = ""
+        self._hermes_home: Path | None = None
+        self._agent_context: str = "primary"
+        self._sync_thread: threading.Thread | None = None
+        self._sync_lock = threading.Lock()
+        self._shutting_down = False  # P-C2 fix: skip slow paths during shutdown
+
+    # -- mandatory ----------------------------------------------------------
+
+    @property
+    def name(self) -> str:
+        return "sibyl"
+
+    def is_available(self) -> bool:
+        """Cheap local check — no network, no DB open."""
+        try:
+            import sibyl_memory_hermes  # noqa: F401
+            return True
+        except Exception:
+            return False
+
+    def initialize(self, session_id: str, **kwargs: Any) -> None:
+        from sibyl_memory_hermes import SibylMemoryProvider
+
+        self._session_id = session_id
+        hermes_home_raw = kwargs.get("hermes_home") or str(_hermes_home())
+        self._hermes_home = Path(hermes_home_raw)
+        self._agent_context = kwargs.get("agent_context", "primary") or "primary"
+        self._shutting_down = False
+
+        db_dir = self._hermes_home / "sibyl"
+        db_dir.mkdir(parents=True, exist_ok=True)
+        db_path = db_dir / "memory.db"
+
+        # autoload_credentials=True picks up ~/.sibyl-memory/credentials.json
+        # (created by `sibyl init`). require_credentials=False so we degrade
+        # to DEFAULT_TENANT pre-activation rather than crash on first run.
+        self._sibyl = SibylMemoryProvider(
+            db_path=db_path,
+            autoload_credentials=True,
+            require_credentials=False,
+        )
+        logger.info("Sibyl memory initialized: db=%s session=%s", db_path, session_id)
+
+    def get_tool_schemas(self) -> list[dict[str, Any]]:
+        return [REMEMBER_SCHEMA, RECALL_SCHEMA, SEARCH_SCHEMA, LIST_SCHEMA]
+
+    # -- recommended overrides ---------------------------------------------
+
+    def system_prompt_block(self) -> str:
+        return (
+            "# Sibyl Memory\n"
+            "Active. Local SQLite-backed structured memory with four searchable "
+            "tiers (warm entities, hot state, cold journal, reference docs).\n"
+            "- sibyl_remember(category, name, body): store a fact\n"
+            "- sibyl_recall(category, name): look up a known fact (returns {body, ...} row)\n"
+            "- sibyl_search(query): FTS5 search across ALL tiers; hits are tier-tagged\n"
+            "- sibyl_list(category?, status?): browse what's remembered"
+        )
+
+    def prefetch(self, query: str, *, session_id: str = "") -> str:
+        if not self._sibyl or not query or len(query.strip()) < _MIN_QUERY_LEN:
+            return ""
+        try:
+            hits = self._sibyl.search(query.strip()[:1000], limit=_PREFETCH_LIMIT)
+        except Exception as e:
+            logger.debug("Sibyl prefetch search failed: %s", e)
+            return ""
+        if not hits:
+            return ""
+        lines = ["## Sibyl Memory — relevant context"]
+        for hit in hits:
+            tier = hit.get("tier", "?")
+            category = hit.get("category", "")
+            key = hit.get("key") or hit.get("name") or "?"
+            body = hit.get("body")
+            body_repr = json.dumps(body, ensure_ascii=False, default=str) if body else ""
+            if len(body_repr) > 400:
+                body_repr = body_repr[:400] + "…"
+            label = f"{category}/{key}" if category else f"{tier}:{key}"
+            lines.append(f"- [{label}] {body_repr}")
+        block = "\n".join(lines)
+        return block[:_MAX_PREFETCH_CHARS]
+
+    def queue_prefetch(self, query: str, *, session_id: str = "") -> None:
+        # Sibyl is local SQLite — prefetch() runs synchronously and is fast.
+        # Nothing to queue.
+        pass
+
+    def sync_turn(self, user_content: str, assistant_content: str,
+                  *, session_id: str = "") -> None:
+        """Append the turn to the cold journal in a daemon thread.
+
+        v0.3.1 (audit P-C1, P-C2):
+        - Retry-on-busy with backoff (was: silent log-and-drop on first failure)
+        - WARNING log on final drop after retries exhausted
+        - Skip the slow cap-gate path during shutdown
+        - Serializes consecutive writes by joining the previous thread first
+          (mirrors the byterover/honcho pattern)
+        """
+        if not self._sibyl:
+            return
+        if self._agent_context != "primary":
+            # Cron/subagent contexts: don't journal (would corrupt the user's
+            # representation as the ABC docstring warns).
+            return
+        if not user_content and not assistant_content:
+            return
+
+        sid = session_id or self._session_id
+        sibyl = self._sibyl
+
+        def _write() -> None:
+            attempts = _BUSY_RETRY_ATTEMPTS
+            for attempt in range(1, attempts + 1):
+                if self._shutting_down:
+                    logger.warning(
+                        "Sibyl sync_turn skipping write during shutdown (session=%s)", sid)
+                    return
+                try:
+                    sibyl.save_context(
+                        inputs={"user": user_content, "session_id": sid},
+                        outputs={"assistant": assistant_content},
+                    )
+                    return  # success
+                except Exception as e:
+                    if attempt < attempts:
+                        # Exponential backoff for SQLITE_BUSY / transient errors
+                        time.sleep(_BUSY_RETRY_BACKOFF * (2 ** (attempt - 1)))
+                        continue
+                    # Final attempt failed — escalate from debug to warning
+                    # so users see drops in production logs.
+                    logger.warning(
+                        "Sibyl sync_turn dropped a journal turn after %d attempts: %s",
+                        attempts, type(e).__name__,
+                    )
+
+        with self._sync_lock:
+            if self._sync_thread and self._sync_thread.is_alive():
+                self._sync_thread.join(timeout=_SYNC_JOIN_TIMEOUT)
+            t = threading.Thread(target=_write, daemon=True, name="sibyl-sync")
+            self._sync_thread = t
+            t.start()
+
+    def handle_tool_call(self, tool_name: str, args: dict[str, Any], **kwargs: Any) -> str:
+        if not self._sibyl:
+            return tool_error("Sibyl provider not initialized")
+
+        try:
+            if tool_name == "sibyl_remember":
+                category = args.get("category")
+                name = args.get("name")
+                body = args.get("body")
+                if not category or not name or body is None:
+                    return tool_error("category, name, and body are required")
+                status = args.get("status")
+                result = self._sibyl.remember(category, name, body, status=status)
+                return json.dumps({"ok": True, "entity": result}, default=str)
+
+            if tool_name == "sibyl_recall":
+                category = args.get("category")
+                name = args.get("name")
+                if not category or not name:
+                    return tool_error("category and name are required")
+                result = self._sibyl.recall(category, name)
+                return json.dumps({"entity": result}, default=str)
+
+            if tool_name == "sibyl_search":
+                query = args.get("query")
+                if not query:
+                    return tool_error("query is required")
+                limit = int(args.get("limit") or _DEFAULT_SEARCH_LIMIT)
+                hits = self._sibyl.search(query, limit=limit)
+                return json.dumps({"results": hits}, default=str)
+
+            if tool_name == "sibyl_list":
+                category = args.get("category")
+                status = args.get("status")
+                limit = int(args.get("limit") or _DEFAULT_LIST_LIMIT)
+                rows = self._sibyl.list(category=category, status=status, limit=limit)
+                return json.dumps({"entities": rows}, default=str)
+
+            return tool_error(f"Unknown tool: {tool_name}")
+
+        except Exception as e:
+            logger.exception("Sibyl tool %s failed", tool_name)
+            # SEC-10 hardening: send only the exception class name back to the
+            # agent. str(e) could echo entity bodies / args that contained
+            # sensitive content. The full exception is in the local log.
+            return tool_error(f"{type(e).__name__}")
+
+    def shutdown(self) -> None:
+        # P-C2 fix: set the stop flag BEFORE joining so in-flight write loops
+        # see it on their next iteration and exit without issuing a slow
+        # cap-gate refresh.
+        self._shutting_down = True
+        if self._sync_thread and self._sync_thread.is_alive():
+            self._sync_thread.join(timeout=_SHUTDOWN_JOIN_TIMEOUT)
+
+    # -- optional hooks ----------------------------------------------------
+
+    def on_session_switch(self, new_session_id: str, *,
+                          parent_session_id: str = "",
+                          reset: bool = False, **kwargs: Any) -> None:
+        # Sibyl doesn't cache per-session resources; just update the id we
+        # stamp onto journal events.
+        self._session_id = new_session_id
+
+    def on_pre_compress(self, messages: list[dict[str, Any]]) -> str:
+        """Flush soon-to-be-discarded turns to the journal."""
+        if not self._sibyl or not messages:
+            return ""
+
+        # Pair user+assistant messages in order; capture the last ~10 pairs.
+        pairs: list[tuple[str, str]] = []
+        pending_user: str | None = None
+        for msg in messages[-20:]:
+            role = msg.get("role")
+            content = msg.get("content")
+            if not isinstance(content, str) or not content.strip():
+                continue
+            if role == "user":
+                pending_user = content
+            elif role == "assistant" and pending_user is not None:
+                pairs.append((pending_user, content))
+                pending_user = None
+
+        if not pairs:
+            return ""
+
+        sibyl = self._sibyl
+        sid = self._session_id
+
+        def _flush() -> None:
+            for user_c, asst_c in pairs:
+                if self._shutting_down:
+                    return
+                try:
+                    sibyl.save_context(
+                        inputs={"user": user_c, "session_id": sid,
+                                "reason": "pre_compress"},
+                        outputs={"assistant": asst_c},
+                    )
+                except Exception as e:
+                    logger.debug("Sibyl pre_compress flush failed: %s", e)
+
+        threading.Thread(target=_flush, daemon=True, name="sibyl-flush").start()
+        return ""
+
+    def on_delegation(self, task: str, result: str, *,
+                      child_session_id: str = "", **kwargs: Any) -> None:
+        if not self._sibyl:
+            return
+        try:
+            self._sibyl.save_context(
+                inputs={"delegated_task": task, "child_sid": child_session_id,
+                        "session_id": self._session_id},
+                outputs={"child_result": result},
+            )
+        except Exception as e:
+            logger.debug("Sibyl on_delegation failed: %s", e)
+
+    def on_memory_write(self, action: str, target: str, content: str,
+                        metadata: dict[str, Any] | None = None) -> None:
+        """Mirror built-in `memory` tool writes into Sibyl's warm tier.
+
+        Accepts metadata even though we treat it as informational only —
+        ignoring the kwarg would TypeError under strict callers.
+        """
+        if not self._sibyl or not content:
+            return
+        name = _stable_key(content)
+        try:
+            if action in ("add", "replace"):
+                self._sibyl.remember(
+                    category=target,
+                    name=name,
+                    body={"content": content, "metadata": metadata or {}},
+                )
+            elif action == "remove":
+                self._sibyl.forget(category=target, name=name)
+        except Exception as e:
+            logger.debug("Sibyl on_memory_write (%s/%s) failed: %s", action, target, e)
+
+    # -- config ------------------------------------------------------------
+
+    def get_config_schema(self) -> list[dict[str, Any]]:
+        """No Hermes-side config — prerequisite is the `sibyl init` CLI.
+
+        Sibyl manages its own credentials and identity outside Hermes:
+        running `sibyl init` writes ~/.sibyl-memory/credentials.json,
+        which the SDK auto-loads at construction time. We deliberately
+        return [] here so `hermes memory setup` does NOT double-prompt
+        for credentials that already live in the Sibyl native file —
+        running both flows would diverge tenant ids and confuse users.
+
+        If a future version needs Hermes-side overrides (alt db_path,
+        explicit tenant_id for testing), add them here as non-secret
+        fields — keep secrets in credentials.json so there's one
+        source of truth.
+        """
+        return []
+
+    def save_config(self, values: dict[str, Any], hermes_home: str) -> None:
+        # Nothing to persist — values are read live from credentials.json and
+        # constructor args. This stays a no-op until a hermes-side config
+        # file is actually needed.
+        return
+
+
+# ---------------------------------------------------------------------------
+# Plugin entry point
+# ---------------------------------------------------------------------------
+
+def register(ctx: Any) -> None:
+    """Register Sibyl as a memory provider plugin."""
+    ctx.register_memory_provider(SibylAdapter())

sibyl-memory-hermes/src/sibyl_memory_hermes/_hermes_plugin/plugin.yaml

@@ -0,0 +1,6 @@
+name: sibyl
+description: Sibyl Memory — local-first, SQLite-backed, structured-tier memory (warm entities, hot state, cold journal, reference docs). Backed by sibyl-memory-hermes.
+version: 0.3.1
+homepage: https://sibyllabs.org/memory
+author: SIBYL, Sibyl Labs LLC
+license: MIT

sibyl-memory-hermes/src/sibyl_memory_hermes/credentials.py

@@ -0,0 +1,168 @@
+"""Credential loader for the Sibyl Memory plugin.
+
+`sibyl init` writes `~/.sibyl-memory/credentials.json` after a successful
+activation. The Hermes provider reads it at startup so callers don't have
+to pass account/tenant IDs explicitly. This file is mode 0600.
+
+Shape:
+
+    {
+      "account_id":   "uuid",
+      "tenant_id":    "uuid OR email-like string",
+      "email":        "alice@example.com",  // optional
+      "wallet":       "0x...",              // optional
+      "tier":         "free | sync | team | lifetime | stake | enterprise",
+      "issued_at":    "2026-05-21T14:32:18Z",
+      "schema_version": 1
+    }
+"""
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+DEFAULT_DB_PATH = "~/.sibyl-memory/memory.db"
+DEFAULT_CRED_PATH = "~/.sibyl-memory/credentials.json"
+
+
+class CredentialsNotFoundError(FileNotFoundError):
+    """Raised when the plugin has not been activated yet."""
+
+    def __init__(self, path: str | Path) -> None:
+        super().__init__(
+            f"No Sibyl Memory credentials found at {path}. "
+            f"Run `sibyl init` to activate the plugin, or pass tenant_id "
+            f"explicitly to SibylMemoryProvider(tenant_id=...)."
+        )
+        self.path = Path(path)
+
+
+@dataclass(frozen=True)
+class Credentials:
+    """Parsed credential file. Immutable for safety.
+
+    schema_version 2 (server-issued 2026-05-16+) adds two fields:
+      - signature: HMAC-SHA256 of the canonical credential fields
+                   (account_id, tenant_id, tier, email, wallet, issued_at,
+                   schema_version) signed server-side at issue time.
+      - signed_at: ISO timestamp when the signature was generated.
+
+    The SDK does NOT verify the signature locally (would require sharing the
+    server's HMAC key, which would defeat the purpose). Instead, the SDK
+    includes the signature alongside the claim in any cap-gate request, and
+    the server re-verifies. Mismatches surface as `credentials_tamper_suspected`
+    telemetry. The authoritative tier comes from the database regardless.
+
+    schema_version 1 credentials (no signature) still load — old fields are
+    None — and continue to work unsigned. The SDK just sends an unsigned
+    request and the server skips the tamper check."""
+
+    account_id: str
+    tenant_id: str
+    tier: str = "free"
+    email: str | None = None
+    wallet: str | None = None
+    issued_at: str | None = None
+    schema_version: int = 1
+    session_token: str | None = None  # long-lived bearer for tier-check calls
+    signature: str | None = None      # HMAC-SHA256 (hex, 64 chars), schema v2+
+    signed_at: str | None = None      # ISO timestamp, schema v2+
+
+
+def load_credentials(path: str | Path = DEFAULT_CRED_PATH) -> Credentials:
+    """Load credentials from disk.
+
+    v0.3.1 hardening (audit SEC-11): refuses to follow symlinks. A
+    low-privilege attacker who once had write to ~/.sibyl-memory could
+    redirect this file to read from /dev/null or any sensitive path. We
+    use ``Path.is_symlink()`` to detect, then ``lstat`` to confirm the
+    file type. On detection, raises ``CredentialsNotFoundError`` (the
+    safe default — caller falls back to DEFAULT_TENANT).
+
+    Raises:
+        CredentialsNotFoundError: file missing or symlinked
+        ValueError: file present but unparseable / missing required fields
+        OSError: I/O failure reading the file
+    """
+    resolved = Path(path).expanduser()
+    # SEC-11: detect symlinks BEFORE resolve() — resolve follows them silently.
+    if resolved.is_symlink():
+        raise CredentialsNotFoundError(resolved)
+    resolved = resolved.resolve()
+    if not resolved.exists():
+        raise CredentialsNotFoundError(resolved)
+
+    with resolved.open("r", encoding="utf-8") as fh:
+        raw = json.load(fh)
+
+    # Be lenient about missing optional fields; strict only about the two
+    # IDs we genuinely need.
+    if "tenant_id" not in raw and "account_id" not in raw:
+        raise ValueError(
+            f"Credentials file at {resolved} is missing both tenant_id and account_id; "
+            f"the file may be corrupted. Re-run `sibyl init` to refresh."
+        )
+
+    account_id = raw.get("account_id") or raw["tenant_id"]
+    tenant_id = raw.get("tenant_id") or raw["account_id"]
+
+    return Credentials(
+        account_id=account_id,
+        tenant_id=tenant_id,
+        tier=raw.get("tier", "free"),
+        email=raw.get("email"),
+        wallet=raw.get("wallet"),
+        issued_at=raw.get("issued_at"),
+        schema_version=int(raw.get("schema_version", 1)),
+        session_token=raw.get("session_token"),
+        signature=raw.get("signature"),
+        signed_at=raw.get("signed_at"),
+    )
+
+
+def write_credentials(creds: Credentials, path: str | Path = DEFAULT_CRED_PATH) -> Path:
+    """Write a credentials file at mode 0600.
+
+    v0.3.1 hardening (audit SEC-2): atomic create-with-mode using
+    ``os.open(O_WRONLY|O_CREAT|O_EXCL|O_NOFOLLOW, 0o600)``. Previously
+    used ``tmp.write_text()`` then ``os.chmod(0o600)``, leaving a
+    world-readable window between syscalls. Now mode is set by the
+    kernel at file-creation time — no race.
+
+    Used by `sibyl init`.
+    """
+    resolved = Path(path).expanduser().resolve()
+    resolved.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
+    payload = {
+        "account_id": creds.account_id,
+        "tenant_id": creds.tenant_id,
+        "tier": creds.tier,
+        "email": creds.email,
+        "wallet": creds.wallet,
+        "issued_at": creds.issued_at,
+        "schema_version": creds.schema_version,
+        "session_token": creds.session_token,
+        "signature": creds.signature,
+        "signed_at": creds.signed_at,
+    }
+    data = json.dumps(payload, indent=2).encode("utf-8")
+    tmp = resolved.with_suffix(resolved.suffix + ".tmp")
+    # Clean any leftover .tmp from a crashed prior write so O_EXCL can succeed.
+    try:
+        os.unlink(tmp)
+    except FileNotFoundError:
+        pass
+    # Atomic create-with-mode. O_NOFOLLOW rejects symlink targets.
+    flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL
+    if hasattr(os, "O_NOFOLLOW"):
+        flags |= os.O_NOFOLLOW
+    fd = os.open(str(tmp), flags, 0o600)
+    try:
+        os.write(fd, data)
+        os.fsync(fd)
+    finally:
+        os.close(fd)
+    os.replace(str(tmp), str(resolved))
+    return resolved

sibyl-memory-hermes/src/sibyl_memory_hermes/install_plugin.py

@@ -0,0 +1,255 @@
+"""`sibyl-memory-hermes install-plugin` — installs the Sibyl adapter into Hermes.
+
+Hermes' loader does NOT use pip entry points (verified against
+plugins/memory/__init__.py source 2026-05-17). It scans the filesystem
+for `__init__.py` files under two locations:
+
+  - bundled:  <site-packages>/plugins/memory/<name>/__init__.py
+  - user:     $HERMES_HOME/plugins/<name>/__init__.py       (note: no /memory/)
+
+After `pip install sibyl-memory-hermes`, the user runs this script to drop
+the bundled adapter into their HERMES_HOME. They then activate by setting
+`memory.provider: sibyl` in their config.yaml.
+
+Usage:
+  sibyl-memory-hermes install-plugin
+  sibyl-memory-hermes install-plugin --hermes-home /custom/path
+  sibyl-memory-hermes install-plugin --force
+  sibyl-memory-hermes install-plugin --dry-run
+  sibyl-memory-hermes uninstall-plugin
+
+v0.3.1 hardening (audit SEC-5):
+  --force will not rmtree a target directory unless it looks like an
+  actual prior Sibyl install (existing plugin.yaml with name: sibyl).
+  Prevents accidental destruction of arbitrary user-writable trees
+  via misconfigured HERMES_HOME.
+"""
+from __future__ import annotations
+
+import argparse
+import os
+import shutil
+import sys
+from importlib import resources
+from pathlib import Path
+
+from . import _aesthetic as a
+from ._banner import print_banner
+
+
+def _hermes_home(override: str | None = None) -> Path:
+    """Resolve the active HERMES_HOME directory.
+
+    Precedence: CLI flag → $HERMES_HOME env var → ~/.hermes default.
+    """
+    if override:
+        return Path(override).expanduser().resolve()
+    env = os.environ.get("HERMES_HOME")
+    if env:
+        return Path(env).expanduser().resolve()
+    return Path.home() / ".hermes"
+
+
+def _plugin_dest(hermes_home: Path) -> Path:
+    """User-install location for a Hermes memory provider plugin.
+
+    Note: asymmetric vs the bundled location. Bundled providers live at
+    <site-packages>/plugins/memory/<name>/, but user plugins live at
+    $HERMES_HOME/plugins/<name>/ without the /memory/ segment. Confirmed
+    against plugins/memory/__init__.py loader source.
+    """
+    return hermes_home / "plugins" / "sibyl"
+
+
+def _payload_files() -> list[tuple[str, str]]:
+    """Files to copy: (source_name_in_package, dest_name_in_plugin_dir).
+
+    adapter.py is renamed to __init__.py at destination so Hermes' filesystem
+    discovery (which looks for `<plugins>/<name>/__init__.py`) picks it up.
+    v0.3.1: adapter.py imports the Hermes ABC under a try/except guard, so
+    the source module is now importable in test / dry-run contexts where
+    hermes-agent isn't installed.
+    """
+    return [
+        ("adapter.py", "__init__.py"),
+        ("plugin.yaml", "plugin.yaml"),
+    ]
+
+
+def _read_payload(filename: str) -> bytes:
+    """Read a bundled file from the _hermes_plugin package."""
+    return (resources.files("sibyl_memory_hermes._hermes_plugin") / filename).read_bytes()
+
+
+def _looks_like_sibyl_install(dest: Path) -> bool:
+    """SEC-5 sentinel check: dest must contain a recognizable prior Sibyl
+    install before we'll rmtree it.
+
+    Recognizes the install by `plugin.yaml` with `name: sibyl` in it (the
+    canonical marker we ship). If the directory exists but doesn't match,
+    we refuse --force rather than destroy possibly-unrelated content."""
+    yaml_path = dest / "plugin.yaml"
+    if not yaml_path.exists() or not yaml_path.is_file():
+        return False
+    try:
+        content = yaml_path.read_text(encoding="utf-8")
+    except OSError:
+        return False
+    # Loose match — yaml has `name: sibyl` somewhere near the top
+    for line in content.splitlines()[:10]:
+        stripped = line.strip().lower()
+        if stripped.startswith("name:") and "sibyl" in stripped:
+            return True
+    return False
+
+
+def install(hermes_home: Path, force: bool, dry_run: bool) -> int:
+    dest = _plugin_dest(hermes_home)
+
+    # ── HEAVY: install moment. Full SIBYL banner + section header. ──
+    print_banner()
+    print(a.section_header("install-plugin",
+                          subtitle="hermes memory provider · drops adapter at $HERMES_HOME/plugins/sibyl/"))
+    print()
+    print(a.kv("Hermes home", str(hermes_home)))
+    print(a.kv("Plugin dest", str(dest)))
+    print()
+
+    # SEC-5: refuse to follow symlinks for the dest path.
+    if dest.exists() and dest.is_symlink():
+        print(a.err_line(f"Refused: {dest} is a symlink."))
+        print(a.dim("  Sibyl will not install through symlinks. Remove the symlink and rerun."))
+        return 3
+
+    if dest.exists() and any(dest.iterdir()):
+        if not force:
+            print(a.err_line(f"Refused: {dest} already exists and is not empty."))
+            print(a.dim("  Use --force to overwrite. Existing files will be replaced."))
+            return 2
+        # SEC-5: sentinel check
+        if not _looks_like_sibyl_install(dest):
+            print(a.err_line(f"Refused: {dest} is not empty but does not contain a prior Sibyl install."))
+            print(a.dim(f"  No plugin.yaml with `name: sibyl` found. Sibyl will not rmtree directories"))
+            print(a.dim(f"  it does not recognize, even with --force. Remove manually if intentional."))
+            return 4
+        if not dry_run:
+            print(a.warn_line(f"Removing existing plugin at {dest}"))
+            shutil.rmtree(dest)
+        else:
+            print(a.dim(f"  [dry-run] would remove existing plugin at {dest}"))
+
+    if not dry_run:
+        dest.mkdir(parents=True, exist_ok=True)
+
+    print(a.eyebrow("writing payload"))
+    for src_name, dest_name in _payload_files():
+        bytes_in = _read_payload(src_name)
+        out = dest / dest_name
+        if dry_run:
+            print(f"  {a.dim('[dry-run]')} would write {a.color(str(out), a.INK)}  {a.dim(f'({len(bytes_in)} bytes)')}")
+        else:
+            out.write_bytes(bytes_in)
+            print(f"  {a.ok(a.GLYPH_OK)} {a.color(str(out), a.INK)}  {a.dim(f'({len(bytes_in)} bytes)')}")
+
+    if dry_run:
+        print()
+        print(a.warn_line("Dry run complete. No files modified."))
+        return 0
+
+    print()
+    print(a.success_line("Plugin installed."))
+    print()
+    print(a.section_header("next steps", subtitle="three to go · then your agent has memory"))
+    print()
+
+    # Step 1 — activate in config.yaml
+    print(f"  {a.chip('1', palette='accent')}  {a.bold('Activate Sibyl in your Hermes config')}")
+    print(f"      {a.color(str(hermes_home / 'config.yaml'), a.INK)}")
+    print()
+    print(f"        {a.color('memory:', a.ACCENT)}")
+    print(f"          {a.color('provider:', a.ACCENT)} {a.color('sibyl', a.INK)}")
+    print()
+
+    # Step 2 — bind account
+    print(f"  {a.chip('2', palette='accent')}  {a.bold('Bind your account')}  {a.dim('(optional · lifts the 2 MB free-tier cap)')}")
+    print(f"      {a.color('sibyl init', a.INK)}")
+    print(a.dim("      three paths: desktop wallet · email + code · USDC-send from mobile"))
+    print(a.dim("      defer if you want — the plugin runs on a local default tenant without it"))
+    print()
+
+    # Step 3 — start hermes
+    print(f"  {a.chip('3', palette='accent')}  {a.bold('Start Hermes — your agent now has memory')}")
+    print(a.dim("      tools available to the agent:"))
+    for tool in ("sibyl_remember", "sibyl_recall", "sibyl_search", "sibyl_list"):
+        print(f"        {a.color(a.GLYPH_BULLET, a.PULSE)} {a.color(tool, a.INK)}")
+    print()
+
+    print(a.divider(60))
+    print(f"  {a.dim('uninstall later:')} {a.color('sibyl-memory-hermes uninstall-plugin', a.INK)}")
+    print(f"  {a.dim('docs:')}             {a.color('docs.sibyllabs.org/memory/integrations', a.INK)}")
+    print()
+    return 0
+
+
+def uninstall(hermes_home: Path, dry_run: bool) -> int:
+    dest = _plugin_dest(hermes_home)
+    # ── HEAVY: removal is also ceremonial — banner + section header.
+    print_banner()
+    print(a.section_header("uninstall-plugin",
+                          subtitle="remove sibyl from this hermes install"))
+    print()
+    print(a.kv("Hermes home", str(hermes_home)))
+    print(a.kv("Plugin dest", str(dest)))
+    print()
+    if not dest.exists():
+        print(a.warn_line("Nothing to uninstall — plugin directory does not exist."))
+        return 0
+    if dest.is_symlink():
+        print(a.err_line(f"Refused: {dest} is a symlink."))
+        print(a.dim("  Sibyl will not rmtree through symlinks."))
+        return 3
+    if not _looks_like_sibyl_install(dest):
+        print(a.err_line(f"Refused: {dest} is not recognized as a Sibyl install."))
+        print(a.dim("  No plugin.yaml with `name: sibyl`. Remove manually if intentional."))
+        return 4
+    if dry_run:
+        print(a.dim(f"  [dry-run] would remove {dest} (recursively)"))
+        return 0
+    shutil.rmtree(dest)
+    print(a.success_line(f"Removed {dest}"))
+    print()
+    print(a.dim(f"  remember to remove `memory.provider: sibyl` from"))
+    print(a.dim(f"  {hermes_home / 'config.yaml'}"))
+    print(a.dim("  if it's still set, or Hermes will warn on startup."))
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="sibyl-memory-hermes",
+        description="Install the Sibyl memory provider plugin into Hermes.",
+    )
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    p_install = sub.add_parser("install-plugin", help="Install the Sibyl plugin into HERMES_HOME.")
+    p_install.add_argument("--hermes-home", help="Override HERMES_HOME (defaults to env var or ~/.hermes).")
+    p_install.add_argument("--force", action="store_true", help="Overwrite an existing Sibyl plugin directory (refuses non-Sibyl content).")
+    p_install.add_argument("--dry-run", action="store_true", help="Show what would happen without writing.")
+
+    p_uninstall = sub.add_parser("uninstall-plugin", help="Remove the Sibyl plugin from HERMES_HOME.")
+    p_uninstall.add_argument("--hermes-home", help="Override HERMES_HOME (defaults to env var or ~/.hermes).")
+    p_uninstall.add_argument("--dry-run", action="store_true", help="Show what would happen without writing.")
+
+    args = parser.parse_args(argv)
+    hermes_home = _hermes_home(args.hermes_home)
+
+    if args.cmd == "install-plugin":
+        return install(hermes_home, force=args.force, dry_run=args.dry_run)
+    if args.cmd == "uninstall-plugin":
+        return uninstall(hermes_home, dry_run=args.dry_run)
+    parser.print_help()
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

sibyl-memory-hermes/src/sibyl_memory_hermes/provider.py

@@ -0,0 +1,433 @@
+"""SibylMemoryProvider — framework-agnostic Sibyl Memory SDK class.
+
+DESIGN NOTES
+============
+
+Pure-Python SDK class. NOT a Hermes plugin on its own. The Hermes plugin
+contract is satisfied by a thin adapter at `_hermes_plugin/adapter.py`
+that delegates to this class. The split is intentional:
+
+  - This class can be used by any orchestration (LangChain, LlamaIndex,
+    custom Python, the sibyl-memory-mcp server, direct callers).
+  - The Hermes adapter handles Hermes-specific lifecycle (initialize,
+    sync_turn, get_tool_schemas, etc.) and is installed via the
+    `sibyl-memory-hermes install-plugin` console script.
+
+Prior versions (v0.2.x) attempted conditional inheritance from Hermes'
+ABC at import time, but the import path was wrong (`hermes_agent.memory`
+vs the actual `agent.memory_provider`), so the soft-bind silently failed
+on every install. v0.3.0 removes the conditional inheritance entirely —
+the adapter handles all Hermes glue. See packages/sibyl-memory-hermes/
+CHANGELOG.md for the full ratification of this architectural shift.
+
+The provider routes operations onto the correct memory tier:
+
+    ┌─────────────────────────────────────────────────────────────┐
+    │   intent                  │ tier         │ storage call       │
+    ├─────────────────────────────────────────────────────────────┤
+    │   "save the conversation" │ COLD journal │ write_event(...)   │
+    │   "remember this fact"    │ WARM entity  │ set_entity(...)    │
+    │   "current state"         │ HOT state    │ set_state(...)     │
+    │   "lookup runbook"        │ REFERENCE    │ set_reference(...) │
+    │   "archive stale entity"  │ ARCHIVE      │ archive_entity     │
+    │   "search by content"     │ FTS5         │ search_entities    │
+    └─────────────────────────────────────────────────────────────┘
+
+The split is intentional. Vector-DB-only providers collapse all of the above
+onto similarity search, which loses structure. Sibyl Memory preserves it.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from sibyl_memory_client import DEFAULT_TENANT, MemoryClient
+from sibyl_memory_client.exceptions import NotFoundError
+
+from .credentials import (
+    DEFAULT_CRED_PATH,
+    DEFAULT_DB_PATH,
+    Credentials,
+    CredentialsNotFoundError,
+    load_credentials,
+)
+
+
+class SibylMemoryProvider:
+    """Hermes Agent memory provider backed by sibyl-memory-client.
+
+    Args:
+        db_path:        path to the local SQLite database. Defaults to
+                        ~/.sibyl-memory/memory.db (the path `sibyl init`
+                        creates).
+        tenant_id:      explicit tenant override. If None, credentials.json
+                        is loaded; if also missing, DEFAULT_TENANT is used.
+        credentials_path: override for credentials.json discovery.
+        require_credentials: if True, raise CredentialsNotFoundError when
+                        the file is missing. Default False — degrade to
+                        DEFAULT_TENANT so callers can run pre-activation.
+        autoload_credentials: if True (default), read credentials.json on
+                        construction and apply tenant_id from it.
+    """
+
+    def __init__(
+        self,
+        db_path: str | Path = DEFAULT_DB_PATH,
+        *,
+        tenant_id: str | None = None,
+        credentials_path: str | Path = DEFAULT_CRED_PATH,
+        require_credentials: bool = False,
+        autoload_credentials: bool = True,
+    ) -> None:
+        # Resolve tenant: explicit > credentials > default
+        resolved_tenant = tenant_id
+        creds: Credentials | None = None
+
+        if resolved_tenant is None and autoload_credentials:
+            try:
+                creds = load_credentials(credentials_path)
+                resolved_tenant = creds.tenant_id
+            except CredentialsNotFoundError:
+                if require_credentials:
+                    raise
+                resolved_tenant = DEFAULT_TENANT
+            except (OSError, ValueError):
+                if require_credentials:
+                    raise
+                resolved_tenant = DEFAULT_TENANT
+
+        if resolved_tenant is None:
+            resolved_tenant = DEFAULT_TENANT
+
+        self._credentials = creds
+        # Plumb account_id, session_token, tier, and the HMAC-signed
+        # credentials claim through to the client so the cap gate can:
+        #   1. verify free-tier writes against the authoritative server when
+        #      the local DB approaches 2 MB (v0.3.0 behavior), and
+        #   2. include the credentials_signature + claim in cap-check
+        #      requests so the server can detect local credentials.json
+        #      tampering and log it as telemetry (v0.3.1+).
+        client_tier = creds.tier if creds else "free"
+        client_account_id = creds.account_id if creds else None
+        client_session_token = creds.session_token if creds else None
+        # Build the canonical signed-claim object that matches the server's
+        # SIGNING_FIELDS shape. Order doesn't matter on the JSON wire —
+        # the server canonicalizes by field name.
+        client_claim = None
+        client_signature = None
+        if creds and creds.signature:
+            client_signature = creds.signature
+            client_claim = {
+                "account_id": creds.account_id,
+                "tenant_id": creds.tenant_id,
+                "tier": creds.tier,
+                "email": creds.email,
+                "wallet": creds.wallet,
+                "issued_at": creds.issued_at,
+                "schema_version": creds.schema_version,
+            }
+        self._client = MemoryClient.local(
+            db_path,
+            tenant_id=resolved_tenant,
+            tier=client_tier,
+            account_id=client_account_id,
+            session_token=client_session_token,
+            credentials_claim=client_claim,
+            credentials_signature=client_signature,
+        )
+
+        # v0.3.0: no conditional super().__init__() — class is no longer
+        # an ABC subclass. Hermes binding lives in the bundled adapter.
+
+    # ------------------------------------------------------------------
+    # Properties
+    # ------------------------------------------------------------------
+    @property
+    def client(self) -> MemoryClient:
+        """The underlying MemoryClient. Use for advanced operations not
+        covered by the provider surface."""
+        return self._client
+
+    @property
+    def credentials(self) -> Credentials | None:
+        return self._credentials
+
+    @property
+    def tenant_id(self) -> str:
+        return self._client.get_tenant()
+
+    @property
+    def hermes_bound(self) -> bool:
+        """Deprecated since v0.3.0. The Hermes plugin contract is now
+        satisfied by the bundled adapter (`_hermes_plugin/adapter.py`),
+        not by this class's inheritance. Always returns False.
+
+        v0.3.1: emits ``DeprecationWarning`` on read so users see the
+        signal before v0.4 removal.
+
+        Removed in v0.4.0.
+        """
+        import warnings
+        warnings.warn(
+            "SibylMemoryProvider.hermes_bound is deprecated and always "
+            "returns False since v0.3.0. The Hermes plugin contract is "
+            "now satisfied by the bundled adapter at _hermes_plugin/"
+            "adapter.py. Property will be removed in v0.4.0.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return False
+
+    # ==================================================================
+    # HERMES-STYLE PROVIDER SURFACE
+    # ==================================================================
+    # The Hermes v0.10.0 memory contract uses save_context / load_context
+    # for the per-turn agent memory loop. We map these onto the journal
+    # (COLD) tier — every turn is an event in the agent's session log.
+    #
+    # remember() / recall() / forget() are the higher-level fact-store
+    # operations that map onto entities (WARM tier).
+    # ==================================================================
+
+    def save_context(
+        self,
+        inputs: dict[str, Any],
+        outputs: dict[str, Any],
+        *,
+        ts: str | None = None,
+    ) -> str:
+        """Persist a single turn (inputs + outputs) to the journal.
+
+        Returns the journal event id."""
+        return self._client.write_event(
+            evaluated=inputs,
+            acted=outputs,
+            ts=ts,
+        )
+
+    def load_context(self, *, limit: int = 20) -> list[dict[str, Any]]:
+        """Return the most recent N turns from the journal."""
+        return self._client.read_events(limit=limit)
+
+    def clear_context(self) -> None:
+        """No-op for now — journal events are append-only by design.
+
+        If a caller genuinely wants to wipe the journal, they should drop
+        the database file. This method exists for Hermes contract
+        compatibility."""
+        return None
+
+    # ------------------------------------------------------------------
+    # Fact store (WARM tier)
+    # ------------------------------------------------------------------
+    def remember(
+        self,
+        category: str,
+        name: str,
+        body: dict[str, Any] | list[Any],
+        *,
+        status: str | None = None,
+    ) -> dict[str, Any]:
+        """Upsert an entity. Single source of truth per (tenant, category, name)."""
+        return self._client.set_entity(category, name, body, status=status)
+
+    def recall(self, category: str, name: str) -> dict[str, Any] | None:
+        """Look up a single entity by (category, name).
+
+        Returns: a row dict shaped ``{id, tenant_id, category, name, status,
+        body, created_at, updated_at}`` where ``body`` is the user-supplied
+        JSON payload, or ``None`` if no matching entity exists.
+
+        Note: the return shape is the full row wrapper, not just the body
+        dict. To get the user payload only, use ``recall(...).["body"]``.
+        State and reference tier reads (``get_state``, ``get_reference``)
+        return slimmer ``{body, updated_at}`` shapes — that asymmetry is
+        intentional (entities carry more provenance) and documented here
+        per audit H2.
+
+        Raises:
+            StorageError: backend (SQLite) failure
+            TenantError: misconfigured tenant_id
+            SchemaError: DB schema mismatch
+
+        T2-2 fix: previously caught bare ``Exception``, which swallowed
+        StorageError / TenantError / SchemaError as "not found". That
+        masked underlying-storage failures end-to-end. Now narrows to
+        NotFoundError only — every other exception propagates so the
+        caller can surface or retry.
+        """
+        try:
+            return self._client.get_entity(category, name)
+        except NotFoundError:
+            return None
+
+    def list(  # noqa: A003 — Hermes-compatible name
+        self,
+        category: str | None = None,
+        *,
+        status: str | None = None,
+        limit: int = 100,
+    ) -> list[dict[str, Any]]:
+        return self._client.list_entities(category=category, status=status, limit=limit)
+
+    def forget(self, category: str, name: str) -> bool:
+        """Delete an entity. Returns True if a row was deleted, False if
+        the entity didn't exist (no-op).
+
+        Raises:
+            StorageError: backend failure
+            TenantError: misconfigured tenant_id
+
+        Does NOT raise on missing entity — returns False instead (audit H3).
+        """
+        return self._client.delete_entity(category, name)
+
+    def archive(
+        self,
+        category: str,
+        name: str,
+        *,
+        reason: str | None = None,
+    ) -> dict[str, Any]:
+        """Move an entity to the archive tier.
+
+        Returns: dict shaped ``{archived_id, original_id}`` referencing the
+        new archive row.
+
+        Raises:
+            NotFoundError: no such (category, name) entity exists
+            CapExceededError: archive would push the DB past the free-tier cap
+            StorageError: backend failure
+
+        Unlike ``forget``, ``archive`` is strict — missing entities raise
+        NotFoundError rather than no-oping (audit H3).
+        """
+        return self._client.archive_entity(category, name, reason=reason)
+
+    # ------------------------------------------------------------------
+    # State documents (HOT tier)
+    # ------------------------------------------------------------------
+    def set_state(self, key: str, body: dict[str, Any] | list[Any]) -> None:
+        """Set a state-tier document. ``body`` must be a dict or list
+        (JSON-serializable container). To store a primitive, wrap in a
+        single-value dict, e.g. ``set_state("seq", {"value": 42})``.
+
+        Raises:
+            ValidationError: body not JSON-serializable
+            CapExceededError: write would push past the free-tier cap
+            StorageError: backend failure
+        """
+        self._client.set_state(key, body)
+
+    def get_state(self, key: str) -> dict[str, Any] | None:
+        """Read a state-tier document.
+
+        Returns: dict shaped ``{body, updated_at}`` (the user payload is
+        under ``body``), or ``None`` if no such key exists.
+
+        Raises:
+            StorageError: backend failure
+        """
+        return self._client.get_state(key)
+
+    # ------------------------------------------------------------------
+    # Reference docs (REFERENCE tier)
+    # ------------------------------------------------------------------
+    def set_reference(
+        self,
+        key: str,
+        body: str,
+        *,
+        metadata: dict[str, Any] | None = None,
+    ) -> None:
+        """Set a reference-tier document.
+
+        Note: reference bodies are plain ``str`` (markdown, runbooks,
+        notes), not dict — intentionally different from entity / state
+        which take dict|list bodies. Use the ``metadata`` kwarg for any
+        structured side-data.
+
+        Raises:
+            ValidationError: metadata not JSON-serializable
+            CapExceededError: write would push past the free-tier cap
+            StorageError: backend failure
+        """
+        self._client.set_reference(key, body, metadata=metadata)
+
+    def get_reference(self, key: str) -> dict[str, Any] | None:
+        """Read a reference-tier document.
+
+        Returns: dict shaped ``{body, metadata, updated_at}`` (body is
+        the raw string), or ``None`` if no such key exists.
+
+        Raises:
+            StorageError: backend failure
+        """
+        return self._client.get_reference(key)
+
+    # ------------------------------------------------------------------
+    # Search
+    # ------------------------------------------------------------------
+    def search(self, query: str, *, limit: int = 20,
+               prefix: bool = False,
+               tiers: tuple[str, ...] | None = None) -> list[dict[str, Any]]:
+        """Cross-tier FTS5 full-text search across all four searchable tiers.
+
+        v0.3.1: search now spans entities + state + reference + journal
+        (was: entities only — the marketing claim of "search across all
+        tiers" was not yet true in v0.3.0).
+
+        Returns: list of tier-tagged hits, each shaped::
+
+            {
+              "tier":  "entity" | "state" | "reference" | "journal",
+              "key":   <entity name | state key | doc_key | journal id>,
+              "category": <entity category or None>,
+              "body":  <JSON-decoded payload (str for reference tier)>,
+              "snippet": <FTS5 snippet with [highlight] markers>,
+              "rank":  <FTS5 rank, lower is better>,
+              "ts":    <ISO timestamp>
+            }
+
+        Hits sorted globally by FTS5 rank. ``limit`` applies to the
+        combined union (not per tier). Pass ``tiers=("entity",)`` to
+        restrict scope. ``prefix=True`` enables prefix matching on the
+        last token.
+
+        Query is sanitized as a single FTS5 phrase — column-filter
+        syntax (``name:foo``) is treated as literal text. Empty / invalid
+        queries return ``[]``.
+
+        For warm-entity-only search returning full entity rows, use
+        ``client.search_entities()`` directly.
+
+        Raises:
+            StorageError: backend failure
+        """
+        return self._client.search(query, limit=limit, prefix=prefix, tiers=tiers)
+
+    # ------------------------------------------------------------------
+    # Diagnostics
+    # ------------------------------------------------------------------
+    def health(self) -> dict[str, Any]:
+        """Return a small diagnostic dict — used by `sibyl status`."""
+        db_path = self._client.storage.db_path
+        return {
+            "ok": True,
+            "schema_version": self._client.schema_version(),
+            "db_path": str(db_path),
+            "db_size_bytes": db_path.stat().st_size if db_path.exists() else 0,
+            "tenant_id": self.tenant_id,
+            "hermes_bound": False,  # v0.3.0: adapter owns Hermes binding
+            "tier": self._credentials.tier if self._credentials else "free",
+            "email": self._credentials.email if self._credentials else None,
+        }
+
+    # ------------------------------------------------------------------
+    # repr
+    # ------------------------------------------------------------------
+    def __repr__(self) -> str:  # pragma: no cover - trivial
+        return (
+            f"SibylMemoryProvider(db={self._client.storage.db_path}, "
+            f"tenant={self.tenant_id!r})"
+        )

sibyl-memory-hermes/tests/test_adapter.py

@@ -0,0 +1,250 @@
+"""Tests for the bundled Hermes plugin adapter (`_hermes_plugin/adapter.py`).
+
+These tests close the validation gap flagged in the v0.3.1 pre-ship audit
+(H1): the v0.3.0 CHANGELOG claimed "validated via Hermes' own
+load_memory_provider('sibyl') dry-run + all 4 tool schemas resolved" but
+zero references to the adapter existed in the test suite. A future change
+that broke the adapter would have passed CI.
+
+The adapter is designed to import cleanly off-Hermes (v0.3.1 guarded
+imports): the `from agent.memory_provider import MemoryProvider` and
+`from tools.registry import tool_error` are wrapped in try/except, with
+no-op fallbacks. That means we can `import` and exercise the adapter
+directly in pytest without mocking the Hermes runtime.
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pytest
+
+from sibyl_memory_hermes import SibylMemoryProvider
+from sibyl_memory_hermes._hermes_plugin import adapter as adapter_module
+from sibyl_memory_hermes._hermes_plugin.adapter import (
+    LIST_SCHEMA,
+    RECALL_SCHEMA,
+    REMEMBER_SCHEMA,
+    SEARCH_SCHEMA,
+    SibylAdapter,
+    _stable_key,
+)
+
+
+# ----------------------------------------------------------------------
+# Module loadability
+# ----------------------------------------------------------------------
+def test_module_imports_without_hermes() -> None:
+    """Off-Hermes the adapter still imports — the Hermes ABC + tool_error
+    guards land their no-op fallbacks. Tests can therefore exercise it
+    without spinning up a Hermes runtime."""
+    # _HERMES_AVAILABLE reflects whether hermes-agent is installed.
+    # In CI / local dev it's typically False; in a real Hermes deployment
+    # it's True. Either way the module loaded successfully (we're here).
+    assert hasattr(adapter_module, "_HERMES_AVAILABLE")
+    assert hasattr(adapter_module, "tool_error")
+    # tool_error must return a string regardless of source (Hermes-real or fallback)
+    out = adapter_module.tool_error("test message")
+    assert isinstance(out, str)
+    assert "test message" in out
+
+
+def test_register_function_exists() -> None:
+    """register(ctx) is the Hermes plugin entry point — must exist for the
+    filesystem loader to find it."""
+    assert callable(adapter_module.register)
+
+
+# ----------------------------------------------------------------------
+# Tool schemas
+# ----------------------------------------------------------------------
+def test_tool_schemas_have_correct_count_and_names() -> None:
+    """The CHANGELOG promised 4 tools; this asserts they exist and are
+    named correctly. Catches accidental renames in future refactors."""
+    adapter = SibylAdapter()
+    schemas = adapter.get_tool_schemas()
+    assert len(schemas) == 4
+    names = sorted(s["name"] for s in schemas)
+    assert names == ["sibyl_list", "sibyl_recall", "sibyl_remember", "sibyl_search"]
+
+
+@pytest.mark.parametrize("schema", [REMEMBER_SCHEMA, RECALL_SCHEMA, SEARCH_SCHEMA, LIST_SCHEMA])
+def test_tool_schemas_are_valid_openai_function_shape(schema: dict) -> None:
+    """Each tool schema must follow OpenAI function-calling shape: name,
+    description, parameters (with type=object + properties + required)."""
+    assert "name" in schema
+    assert isinstance(schema["name"], str)
+    assert schema["name"].startswith("sibyl_")
+    assert "description" in schema
+    assert isinstance(schema["description"], str)
+    assert len(schema["description"]) > 0
+    assert "parameters" in schema
+    p = schema["parameters"]
+    assert p["type"] == "object"
+    assert "properties" in p
+    assert isinstance(p["properties"], dict)
+    assert "required" in p
+    assert isinstance(p["required"], list)
+
+
+# ----------------------------------------------------------------------
+# Adapter init + dispatch
+# ----------------------------------------------------------------------
+def _make_initialized_adapter(tmp_path: Path) -> SibylAdapter:
+    """Build a SibylAdapter wired to a temp DB. Bypasses Hermes' real
+    initialize() entry point (which calls _hermes_home from hermes_constants)
+    by setting the provider directly."""
+    adapter = SibylAdapter()
+    adapter._sibyl = SibylMemoryProvider(
+        db_path=str(tmp_path / "adapter.db"),
+        autoload_credentials=False,
+    )
+    adapter._session_id = "test-session"
+    adapter._hermes_home = tmp_path
+    return adapter
+
+
+def test_handle_tool_call_uninitialized_returns_error() -> None:
+    """Calling handle_tool_call before initialize must return a structured
+    error, not crash."""
+    adapter = SibylAdapter()
+    result = adapter.handle_tool_call("sibyl_remember", {"category": "x", "name": "y", "body": {}})
+    parsed = json.loads(result)
+    assert "error" in parsed
+
+
+def test_handle_tool_call_unknown_tool_returns_error(tmp_path: Path) -> None:
+    """Unknown tool names produce a clean error response, no exception."""
+    adapter = _make_initialized_adapter(tmp_path)
+    result = adapter.handle_tool_call("sibyl_does_not_exist", {})
+    parsed = json.loads(result)
+    assert "error" in parsed
+    assert "Unknown tool" in parsed["error"]
+
+
+def test_handle_tool_call_remember_then_recall(tmp_path: Path) -> None:
+    """End-to-end: remember an entity, recall it, verify the body roundtrips."""
+    adapter = _make_initialized_adapter(tmp_path)
+    # remember
+    r1 = json.loads(adapter.handle_tool_call("sibyl_remember", {
+        "category": "project",
+        "name": "atlas",
+        "body": {"status": "shipping", "owner": "tt"},
+    }))
+    assert r1["ok"] is True
+    assert r1["entity"]["body"]["status"] == "shipping"
+    # recall
+    r2 = json.loads(adapter.handle_tool_call("sibyl_recall", {
+        "category": "project", "name": "atlas",
+    }))
+    assert r2["entity"] is not None
+    assert r2["entity"]["body"]["status"] == "shipping"
+    assert r2["entity"]["body"]["owner"] == "tt"
+
+
+def test_handle_tool_call_recall_missing_returns_null(tmp_path: Path) -> None:
+    """Recall on a non-existent entity returns {"entity": null}, not an error."""
+    adapter = _make_initialized_adapter(tmp_path)
+    out = json.loads(adapter.handle_tool_call("sibyl_recall", {
+        "category": "project", "name": "nonexistent",
+    }))
+    assert out["entity"] is None
+
+
+def test_handle_tool_call_list_with_filter(tmp_path: Path) -> None:
+    """list filters by category."""
+    adapter = _make_initialized_adapter(tmp_path)
+    for n, cat in [("a", "alpha"), ("b", "alpha"), ("c", "beta")]:
+        adapter.handle_tool_call("sibyl_remember", {
+            "category": cat, "name": n, "body": {"x": n},
+        })
+    out = json.loads(adapter.handle_tool_call("sibyl_list", {"category": "alpha"}))
+    names = sorted(e["name"] for e in out["entities"])
+    assert names == ["a", "b"]
+
+
+def test_handle_tool_call_search_cross_tier(tmp_path: Path) -> None:
+    """v0.3.1 promise: search spans all four tiers, not entities only.
+
+    This is the regression test the audit (T5) said would have caught the
+    cross-tier-coverage bug if it had existed in v0.3.0."""
+    adapter = _make_initialized_adapter(tmp_path)
+    sibyl = adapter._sibyl
+    # Write a unique marker to each tier
+    sibyl.remember("project", "atlas", {"note": "entitytier_xyzzy"})
+    sibyl.set_state("active_branch", {"name": "statetier_xyzzy"})
+    sibyl.set_reference("runbook", "referencetier_xyzzy is the value")
+    sibyl.save_context(
+        inputs={"u": "journaltier_xyzzy is the user message"},
+        outputs={"a": "ok"},
+    )
+    out = json.loads(adapter.handle_tool_call("sibyl_search", {"query": "xyzzy"}))
+    hits = out["results"]
+    tiers_found = {h["tier"] for h in hits}
+    # Each tier should surface at least one hit
+    assert "entity" in tiers_found, f"entity tier missing from search: {tiers_found}"
+    assert "state" in tiers_found, f"state tier missing from search: {tiers_found}"
+    assert "reference" in tiers_found, f"reference tier missing from search: {tiers_found}"
+    assert "journal" in tiers_found, f"journal tier missing from search: {tiers_found}"
+
+
+def test_handle_tool_call_search_sanitizes_malformed_query(tmp_path: Path) -> None:
+    """SEC-3 hardening: malformed FTS5 queries (unclosed quotes, column
+    filters) must not crash or leak SQL error text."""
+    adapter = _make_initialized_adapter(tmp_path)
+    # Unclosed quote — pre-v0.3.1 would surface OperationalError + db_path leak
+    out = json.loads(adapter.handle_tool_call("sibyl_search", {"query": '"'}))
+    assert "results" in out
+    # Empty input — should return empty results, not error
+    out2 = json.loads(adapter.handle_tool_call("sibyl_search", {"query": ""}))
+    assert "error" in out2  # query is required
+
+
+def test_handle_tool_call_missing_required_args(tmp_path: Path) -> None:
+    """Required parameters surface a clean error, not a backend crash."""
+    adapter = _make_initialized_adapter(tmp_path)
+    out = json.loads(adapter.handle_tool_call("sibyl_remember", {"category": "x"}))
+    assert "error" in out
+
+
+# ----------------------------------------------------------------------
+# Shutdown behavior (P-C1, P-C2 audit fixes)
+# ----------------------------------------------------------------------
+def test_shutdown_sets_stop_flag(tmp_path: Path) -> None:
+    """shutdown() sets _shutting_down so daemon writes can skip slow paths."""
+    adapter = _make_initialized_adapter(tmp_path)
+    assert adapter._shutting_down is False
+    adapter.shutdown()
+    assert adapter._shutting_down is True
+
+
+def test_sync_turn_during_shutdown_skips(tmp_path: Path) -> None:
+    """sync_turn called after shutdown should not error out (writes are
+    skipped via the shutdown flag check in the worker loop)."""
+    adapter = _make_initialized_adapter(tmp_path)
+    adapter.shutdown()
+    # Should not raise — even though we shut down, the call itself is safe
+    adapter.sync_turn("user msg", "assistant reply")
+
+
+# ----------------------------------------------------------------------
+# Helper
+# ----------------------------------------------------------------------
+def test_stable_key_is_deterministic() -> None:
+    """blake2b _stable_key gives the same answer for the same input across
+    runs. This is what makes add+remove on the same content actually target
+    the same entity."""
+    k1 = _stable_key("hello world")
+    k2 = _stable_key("hello world")
+    k3 = _stable_key("hello world!")
+    assert k1 == k2
+    assert k1 != k3
+    assert len(k1) == 12  # 6 bytes = 12 hex chars
+
+
+def test_stable_key_with_prefix() -> None:
+    """prefix= argument prefixes the digest, used for namespacing built-in
+    memory-tool mirror writes."""
+    k = _stable_key("hello", prefix="mem-")
+    assert k.startswith("mem-")
+    assert len(k) == len("mem-") + 12

sibyl-memory-hermes/tests/test_smoke.py

@@ -0,0 +1,327 @@
+"""Smoke tests for sibyl-memory-hermes.
+
+These exercise the public provider surface. They run against a fresh
+SQLite DB per test via pytest tmp_path fixtures. Hermes is NOT required
+to be installed — the provider degrades gracefully.
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pytest
+
+from sibyl_memory_hermes import (
+    DEFAULT_DB_PATH,
+    Credentials,
+    CredentialsNotFoundError,
+    SibylMemoryProvider,
+    __version__,
+    load_credentials,
+)
+from sibyl_memory_hermes.credentials import write_credentials
+
+
+# ----------------------------------------------------------------------
+# Module-level sanity
+# ----------------------------------------------------------------------
+def test_version_is_pep440() -> None:
+    """__version__ must be PEP440 format and single-sourced from importlib.metadata (v0.3.0+)."""
+    import re
+    from importlib.metadata import version as _v
+
+    # PEP440 minimum: N.N.N with optional pre/post/dev/local suffix.
+    assert re.match(r"^\d+\.\d+\.\d+", __version__), f"non-PEP440 version: {__version__}"
+    # When the package is installed (not a raw source tree), __version__ must
+    # match what importlib.metadata returns. v0.3.0 fixed the drift bug where
+    # __init__.py and the wheel could disagree.
+    if not __version__.endswith("+source"):
+        assert __version__ == _v("sibyl-memory-hermes")
+
+
+def test_default_db_path_is_home_relative() -> None:
+    assert DEFAULT_DB_PATH.startswith("~")
+
+
+# ----------------------------------------------------------------------
+# Construction
+# ----------------------------------------------------------------------
+def test_construct_explicit_path_default_tenant(tmp_path: Path) -> None:
+    db = tmp_path / "memory.db"
+    provider = SibylMemoryProvider(db_path=str(db), autoload_credentials=False)
+    assert provider.tenant_id == "00000000-0000-0000-0000-000000000001"
+    # Schema is currently v3 (cross-tier FTS5 landed 2026-05-18). Assert >= 2
+    # so the test survives future schema bumps without spurious breakage.
+    assert provider.client.schema_version() >= 2
+    assert db.exists()
+
+
+def test_construct_explicit_tenant(tmp_path: Path) -> None:
+    db = tmp_path / "memory.db"
+    provider = SibylMemoryProvider(
+        db_path=str(db), tenant_id="alice@example.com", autoload_credentials=False
+    )
+    assert provider.tenant_id == "alice@example.com"
+
+
+def test_construct_with_missing_credentials_degrades(tmp_path: Path) -> None:
+    db = tmp_path / "memory.db"
+    cred = tmp_path / "no-creds.json"
+    provider = SibylMemoryProvider(
+        db_path=str(db),
+        credentials_path=str(cred),
+    )
+    # Default tenant when creds absent
+    assert provider.tenant_id == "00000000-0000-0000-0000-000000000001"
+    assert provider.credentials is None
+
+
+def test_construct_require_credentials_raises(tmp_path: Path) -> None:
+    db = tmp_path / "memory.db"
+    cred = tmp_path / "no-creds.json"
+    with pytest.raises(CredentialsNotFoundError):
+        SibylMemoryProvider(
+            db_path=str(db),
+            credentials_path=str(cred),
+            require_credentials=True,
+        )
+
+
+def test_construct_with_credentials_file(tmp_path: Path) -> None:
+    db = tmp_path / "memory.db"
+    cred_path = tmp_path / "credentials.json"
+    creds = Credentials(
+        account_id="acct-123",
+        tenant_id="alice@example.com",
+        tier="lifetime",
+        email="alice@example.com",
+        issued_at="2026-05-21T14:32:18Z",
+    )
+    write_credentials(creds, cred_path)
+
+    provider = SibylMemoryProvider(
+        db_path=str(db), credentials_path=str(cred_path)
+    )
+    assert provider.tenant_id == "alice@example.com"
+    assert provider.credentials is not None
+    assert provider.credentials.tier == "lifetime"
+
+
+# ----------------------------------------------------------------------
+# Hermes contract surface
+# ----------------------------------------------------------------------
+def test_save_and_load_context(tmp_path: Path) -> None:
+    provider = SibylMemoryProvider(
+        db_path=str(tmp_path / "m.db"), autoload_credentials=False
+    )
+    ev_id = provider.save_context(
+        inputs={"user": "what's the status?"},
+        outputs={"agent": "all green"},
+    )
+    assert isinstance(ev_id, str)
+    assert len(ev_id) >= 8
+
+    events = provider.load_context(limit=10)
+    assert len(events) == 1
+    assert events[0]["evaluated"] == {"user": "what's the status?"}
+    assert events[0]["acted"] == {"agent": "all green"}
+
+
+def test_clear_context_is_noop(tmp_path: Path) -> None:
+    provider = SibylMemoryProvider(
+        db_path=str(tmp_path / "m.db"), autoload_credentials=False
+    )
+    provider.save_context({"q": "hi"}, {"r": "hello"})
+    assert provider.clear_context() is None
+    # journal still has the entry
+    assert len(provider.load_context()) == 1
+
+
+# ----------------------------------------------------------------------
+# Fact store (entities)
+# ----------------------------------------------------------------------
+def test_remember_recall_forget(tmp_path: Path) -> None:
+    provider = SibylMemoryProvider(
+        db_path=str(tmp_path / "m.db"), autoload_credentials=False
+    )
+
+    ent = provider.remember(
+        "project", "atlas",
+        {"status": "active", "owner": "jane"},
+        status="active",
+    )
+    assert ent["category"] == "project"
+    assert ent["name"] == "atlas"
+    assert ent["body"]["status"] == "active"
+
+    fetched = provider.recall("project", "atlas")
+    assert fetched is not None
+    assert fetched["body"]["owner"] == "jane"
+
+    assert provider.recall("project", "nonexistent") is None
+
+    assert provider.forget("project", "atlas") is True
+    assert provider.recall("project", "atlas") is None
+
+
+def test_list_entities(tmp_path: Path) -> None:
+    provider = SibylMemoryProvider(
+        db_path=str(tmp_path / "m.db"), autoload_credentials=False
+    )
+    provider.remember("project", "atlas", {"status": "active"}, status="active")
+    provider.remember("project", "borealis", {"status": "stale"}, status="stale")
+    provider.remember("person", "jane", {"role": "ops"})
+
+    projects = provider.list(category="project")
+    assert {p["name"] for p in projects} == {"atlas", "borealis"}
+
+    active = provider.list(category="project", status="active")
+    assert len(active) == 1
+    assert active[0]["name"] == "atlas"
+
+
+def test_archive_round_trip(tmp_path: Path) -> None:
+    provider = SibylMemoryProvider(
+        db_path=str(tmp_path / "m.db"), autoload_credentials=False
+    )
+    provider.remember("project", "dead-prototype", {"status": "abandoned"})
+    result = provider.archive("project", "dead-prototype", reason="stale")
+    assert "archived_id" in result
+    # Active set no longer contains it
+    assert provider.recall("project", "dead-prototype") is None
+
+
+# ----------------------------------------------------------------------
+# State / reference / search
+# ----------------------------------------------------------------------
+def test_state_documents(tmp_path: Path) -> None:
+    provider = SibylMemoryProvider(
+        db_path=str(tmp_path / "m.db"), autoload_credentials=False
+    )
+    provider.set_state("current-priorities", {"top": ["ship plugin"]})
+    state = provider.get_state("current-priorities")
+    assert state is not None
+    assert state["body"]["top"] == ["ship plugin"]
+    assert provider.get_state("nonexistent") is None
+
+
+def test_reference_documents(tmp_path: Path) -> None:
+    provider = SibylMemoryProvider(
+        db_path=str(tmp_path / "m.db"), autoload_credentials=False
+    )
+    provider.set_reference(
+        "voice-rules", "lowercase is fine. no em dashes.",
+        metadata={"source": "SIBYL-VOICE.md"},
+    )
+    ref = provider.get_reference("voice-rules")
+    assert ref is not None
+    assert "em dashes" in ref["body"]
+    assert ref["metadata"]["source"] == "SIBYL-VOICE.md"
+
+
+def test_fts_search(tmp_path: Path) -> None:
+    provider = SibylMemoryProvider(
+        db_path=str(tmp_path / "m.db"), autoload_credentials=False
+    )
+    provider.remember("project", "atlas", {"summary": "memory plugin shipping"})
+    provider.remember("project", "borealis", {"summary": "audit dashboard"})
+    provider.remember("person", "jane", {"role": "operator ops"})
+
+    # v0.3.1: provider.search() now returns cross-tier hits with a `key`
+    # field (was: entity rows with `name`). The shape is documented in
+    # MemoryClient.search() — each hit is {tier, key, category, body, ...}.
+    results = provider.search("memory")
+    keys = {r["key"] for r in results if r["tier"] == "entity"}
+    assert "atlas" in keys
+    assert "borealis" not in keys
+
+
+# ----------------------------------------------------------------------
+# Multi-tenant isolation
+# ----------------------------------------------------------------------
+def test_multi_tenant_isolation(tmp_path: Path) -> None:
+    db = tmp_path / "m.db"
+    alice = SibylMemoryProvider(
+        db_path=str(db), tenant_id="alice", autoload_credentials=False
+    )
+    bob = SibylMemoryProvider(
+        db_path=str(db), tenant_id="bob", autoload_credentials=False
+    )
+
+    alice.remember("project", "atlas", {"owner": "alice"})
+    bob.remember("project", "atlas", {"owner": "bob"})
+
+    a = alice.recall("project", "atlas")
+    b = bob.recall("project", "atlas")
+    assert a is not None and b is not None
+    assert a["body"]["owner"] == "alice"
+    assert b["body"]["owner"] == "bob"
+
+    # Neither tenant sees the other's entities
+    assert len(alice.list(category="project")) == 1
+    assert len(bob.list(category="project")) == 1
+
+
+# ----------------------------------------------------------------------
+# Diagnostics
+# ----------------------------------------------------------------------
+def test_health(tmp_path: Path) -> None:
+    provider = SibylMemoryProvider(
+        db_path=str(tmp_path / "m.db"), autoload_credentials=False
+    )
+    h = provider.health()
+    assert h["ok"] is True
+    # Schema is currently v3 (cross-tier FTS5 landed 2026-05-18)
+    assert h["schema_version"] >= 2
+    assert h["db_size_bytes"] >= 0
+    assert h["tier"] == "free"
+    # hermes_bound is deprecated since v0.3.0 and always False — the asymmetry
+    # is the signal v0.4 cleanup is approaching. Tightened from bool-only check.
+    assert h["hermes_bound"] is False
+
+
+def test_provider_exposes_client(tmp_path: Path) -> None:
+    provider = SibylMemoryProvider(
+        db_path=str(tmp_path / "m.db"), autoload_credentials=False
+    )
+    # The underlying MemoryClient is accessible for advanced use
+    assert provider.client is not None
+    assert hasattr(provider.client, "set_entity")
+    assert hasattr(provider.client, "write_event")
+
+
+# ----------------------------------------------------------------------
+# Credentials file plumbing
+# ----------------------------------------------------------------------
+def test_write_then_load_credentials(tmp_path: Path) -> None:
+    cred_path = tmp_path / "credentials.json"
+    creds_in = Credentials(
+        account_id="abc-def",
+        tenant_id="user@example.com",
+        tier="sync",
+        email="user@example.com",
+        wallet="0xabc",
+        issued_at="2026-05-21T14:32:18Z",
+        schema_version=1,
+    )
+    write_credentials(creds_in, cred_path)
+
+    # File is mode 0600
+    assert oct(cred_path.stat().st_mode)[-3:] == "600"
+
+    creds_out = load_credentials(cred_path)
+    assert creds_out.tenant_id == "user@example.com"
+    assert creds_out.tier == "sync"
+    assert creds_out.wallet == "0xabc"
+
+
+def test_load_credentials_missing(tmp_path: Path) -> None:
+    with pytest.raises(CredentialsNotFoundError):
+        load_credentials(tmp_path / "nope.json")
+
+
+def test_load_credentials_missing_ids_raises(tmp_path: Path) -> None:
+    bad = tmp_path / "bad.json"
+    bad.write_text(json.dumps({"tier": "free"}), encoding="utf-8")
+    with pytest.raises(ValueError):
+        load_credentials(bad)

sibyl-memory-mcp/CHANGELOG.md

@@ -0,0 +1,149 @@
+# Changelog
+
+All notable changes to `sibyl-memory-mcp` are recorded here. Format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Versioning follows
+[SemVer](https://semver.org/).
+
+## [0.1.2] — 2026-05-18
+
+KAPPA external-tester remediation release. v0.1.1 was functionally broken
+on PyPI: `pip install sibyl-memory-mcp` followed by the entry-point invocation
+raised `ImportError: cannot import name 'CapExceededError' from
+'sibyl_memory_client.exceptions'`. Reported by KAPPA (independent
+third-party install test, peer Tulip-referred) after the v0.3.3 family ship.
+The 93/93 audit tests passed only because they ran in-tree; there was no
+clean-venv install smoke test in CI. Gap closed by the companion
+`tmp-test/clean-venv-install-smoke.sh` guardrail.
+
+### Fixed
+
+- **KAPPA-BLOCKER** — `sibyl-memory-mcp` now imports cleanly in a fresh
+  venv. The fix lives in the companion `sibyl-memory-client` v0.4.0 which
+  exports `CapExceededError` and `TierVerificationError` from the
+  `.exceptions` submodule path. This release bumps the client pin to
+  `>=0.4.0` to consume that fix and rolls the version forward so anyone
+  on `pip install sibyl-memory-mcp` picks up the working release.
+
+### Changed
+
+- `sibyl-memory-client` pin: `>=0.3.3` → `>=0.4.0`.
+- `sibyl-memory-hermes` pin: `>=0.3.1` → `>=0.3.2`.
+
+### Notes
+
+- Server code (`server.py`) is unchanged from v0.1.1. The 8-tool surface
+  (memory_remember / memory_recall / memory_search / memory_list /
+  memory_forget / memory_set_state / memory_get_state / memory_record_event)
+  remains stable.
+- v0.1.1 has been yanked on PyPI.
+
+---
+
+## [0.1.1] — 2026-05-18
+
+Audit-remediation release. v0.3.0 plugin-family pre-ship audit (2026-05-18T05:05Z)
+flagged this package's `memory_record_event` tool as broken end-to-end (every
+invocation raised TypeError). This release lands the MCP-side fixes.
+Companion releases: `sibyl-memory-client` v0.3.3, `sibyl-memory-hermes` v0.3.1,
+`sibyl-memory-cli` v0.1.2.
+
+### Fixed
+
+- **C1** — `memory_record_event` now calls the SDK's actual signature
+  ``client.write_event(*, evaluated, acted, forward, extra, ts)``. The
+  previous call ``client.write_event(kind, body, category=category,
+  name=name)`` referenced parameters that don't exist and raised
+  TypeError on every invocation. The high-level (kind, body, category,
+  name) contract is preserved by translating: kind+body → `acted={kind,
+  body}`, optional category+name → `extra={category, name}`.
+- **H2** — `memory_get_state` now unpacks the SDK's `{body, updated_at}`
+  return shape into a flat response: `{ok, key, body: <user payload>,
+  updated_at: <iso ts>}`. Previously returned `body` containing the full
+  wrapper, so "body" meant two different things at different nesting
+  depths in the same response.
+- **N3** — `memory_list` `category` parameter is now Optional. Matches
+  the SDK + Hermes adapter behavior — pass it to filter, omit to list
+  across all categories.
+
+### Changed
+
+- **P-H1** — `MemoryClient` is cached at module scope. Previously rebuilt
+  on every tool call (reading schema.sql from disk + bootstrapping FTS5
+  vtables — 10-50 ms per call). Cache invalidates on credentials.json
+  mtime change so `sibyl upgrade` is still picked up without a server
+  restart. Net effect: agent recall/search latency drops to single-digit
+  milliseconds.
+- **memory_search now spans all four tiers** (entities + state +
+  reference + journal). Backed by the new `MemoryClient.search()` in
+  client v0.3.3. Each hit carries a `tier` tag. The MCP server marketing
+  description and tool docstring now match the actual behavior.
+- Query sanitization handled by the client SDK (FTS5 column-filter
+  syntax can't break out into the parser). MCP server didn't need
+  its own sanitization — it's downstream of the SDK fix.
+
+### Security
+
+- **SEC-4 / SEC-11** — `_load_credentials` refuses to follow symlinks.
+  Previously called `read_text()` on the resolved path, which would
+  silently follow.
+
+### Dependencies
+
+- `sibyl-memory-client>=0.3.3` (was `>=0.3.2`)
+- `sibyl-memory-hermes>=0.3.1` (was `>=0.2.2`)
+
+## [0.1.0] — 2026-05-17
+
+Initial release. Operator question 2026-05-17: "currently i'm only seeing
+instructions for Hermes agent, how could this be used with claude code or
+codex?" — answer: an MCP server wrapping `MemoryClient.local()`. Both Claude
+Code and Codex CLI consume MCP, so a single server unlocks both.
+
+### Added
+
+- **MCP server** (`sibyl-memory-mcp` console script + `python -m sibyl_memory_mcp`)
+  using the official `mcp>=1.0.0` Python SDK with FastMCP convenience layer.
+- **8 tools** exposed over stdio transport:
+  - `memory_remember` — `set_entity(category, name, body)`
+  - `memory_recall` — `get_entity(category, name)`
+  - `memory_search` — `search_entities(query, limit)` (FTS5)
+  - `memory_list` — `list_entities(category, limit)`
+  - `memory_forget` — `archive_entity(category, name, reason)`
+  - `memory_set_state` — `set_state(key, body)` (HOT tier)
+  - `memory_get_state` — `get_state(key)`
+  - `memory_record_event` — `write_event(kind, body, category, name)` (COLD tier)
+- **Auto-reads** `~/.sibyl-memory/credentials.json` on every tool call so tier
+  changes from `sibyl upgrade` are picked up without restarting the server.
+- **Typed error envelope** mapping SDK exceptions to MCP-friendly payloads:
+  `CAP_EXCEEDED` (with `upgrade_url`), `TIER_GATED`, `TIER_VERIFICATION_FAILED`,
+  `NOT_FOUND`, `VALIDATION_ERROR`. Agents can reason about the right next move.
+- **Env overrides**: `SIBYL_MEMORY_DB`, `SIBYL_CREDENTIALS` for non-default
+  install locations + multi-account scenarios.
+
+### Design notes
+
+- Re-opens `MemoryClient.local()` on every tool call. SQLite open is
+  sub-millisecond and this keeps the server stateless — no stale tier cache
+  in the process, every call sees the current credentials.
+- Free-tier 2 MB cap is enforced server-side against the database (HMAC-signed
+  credentials prevent local tampering). The MCP server has no way to bypass it.
+- Tool names are prefixed `memory_` so they namespace cleanly when an agent
+  has multiple MCP servers loaded.
+
+### Depends on
+
+- `mcp>=1.0.0` (official Anthropic Python SDK)
+- `sibyl-memory-client>=0.3.2` (cap-gate + signed credentials)
+- `sibyl-memory-hermes>=0.2.2` (credentials loader)
+
+### Compatible with
+
+- **Claude Code** — add to `~/.claude/settings.json` or project `.mcp.json`
+- **Codex CLI** — add to `~/.codex/config.toml`
+- **Cursor** — add to `~/.cursor/mcp.json`
+- **Continue** — add to `~/.continue/config.json` mcpServers block
+- Any other MCP-spec-compliant client.
+
+### License
+
+MIT.

sibyl-memory-mcp/README.md

@@ -0,0 +1,78 @@
+# sibyl-memory-mcp
+
+MCP server for [Sibyl Memory Plugin](https://sibyllabs.org/memory). Exposes the local SQLite + FTS5 memory engine to any MCP-compatible agent: **Claude Code, Codex CLI, Cursor, Continue**, anything that speaks Model Context Protocol.
+
+## Install
+
+```bash
+pip install sibyl-memory-mcp
+```
+
+You also need an activated Sibyl Memory account. If you haven't already:
+
+```bash
+sibyl init
+```
+
+This creates `~/.sibyl-memory/credentials.json` (server-issued, HMAC-signed) and a local SQLite database at `~/.sibyl-memory/memory.db`. The MCP server reads both automatically.
+
+## Add to Claude Code
+
+Edit `~/.claude/settings.json` (global) or `.mcp.json` (project-local):
+
+```json
+{
+  "mcpServers": {
+    "sibyl-memory": {
+      "command": "sibyl-memory-mcp"
+    }
+  }
+}
+```
+
+Restart Claude Code. The 8 memory tools (prefixed `memory_*`) become available immediately.
+
+## Add to Codex CLI
+
+Edit `~/.codex/config.toml`:
+
+```toml
+[[mcp_servers]]
+name = "sibyl-memory"
+command = "sibyl-memory-mcp"
+```
+
+Restart Codex.
+
+## Tools exposed
+
+| Tool | What it does |
+|------|--------------|
+| `memory_remember` | Store an entity by (category, name) |
+| `memory_recall` | Read an entity by exact key |
+| `memory_search` | FTS5 search across all entities |
+| `memory_list` | List entities in a category |
+| `memory_forget` | Archive an entity (recoverable) |
+| `memory_set_state` | Write a HOT-tier state doc |
+| `memory_get_state` | Read a HOT-tier state doc |
+| `memory_record_event` | Append a COLD-tier journal event |
+
+Full docs at [docs.sibyllabs.org/memory/integrations](https://docs.sibyllabs.org/memory/integrations).
+
+## Environment overrides
+
+| Var | Default | What it overrides |
+|-----|---------|--------------------|
+| `SIBYL_MEMORY_DB` | `~/.sibyl-memory/memory.db` | Local SQLite path |
+| `SIBYL_CREDENTIALS` | `~/.sibyl-memory/credentials.json` | Credentials file path |
+
+## Tier behavior
+
+- **Free tier**: 8 tools work. Hard-capped at 2 MB of local storage. Writes that would push past the cap return `CAP_EXCEEDED` with an `upgrade_url`. Self-learning and memory-check-up tools are not exposed on free tier.
+- **Paid tiers** (Sync / Stake / Lifetime / Enterprise): cap removed. All tools enabled.
+
+The cap-gate runs against the **server-authoritative** tier (verified via HMAC-signed credentials) — the MCP server can't bypass it by editing the local file.
+
+## License
+
+MIT — same as the rest of the `sibyl-memory-*` family.

sibyl-memory-mcp/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["setuptools>=64", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sibyl-memory-mcp"
+version = "0.1.2"
+description = "MCP server for Sibyl Memory Plugin — wraps the local SQLite + FTS5 memory engine and exposes it to MCP-compatible agents (Claude Code, Codex, Cursor, Continue, anything that speaks MCP)."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "SIBYL, Sibyl Labs LLC", email = "sibyl@sibyllabs.org" }]
+keywords = ["mcp", "model-context-protocol", "memory", "agent", "claude", "claude-code", "codex", "sibyl"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Topic :: Software Development :: Libraries",
+]
+dependencies = [
+    "mcp>=1.0.0",
+    "sibyl-memory-client>=0.4.0",
+    "sibyl-memory-hermes>=0.3.2",
+]
+
+[project.scripts]
+sibyl-memory-mcp = "sibyl_memory_mcp.__main__:main"
+
+[project.urls]
+Homepage = "https://sibyllabs.org/memory"
+Documentation = "https://docs.sibyllabs.org/memory/integrations"
+Repository = "https://github.com/sibyllabs/sibyl-memory-plugin"
+
+[tool.setuptools.packages.find]
+where = ["src"]

sibyl-memory-mcp/src/sibyl_memory_mcp/__init__.py

@@ -0,0 +1,28 @@
+"""sibyl-memory-mcp — MCP server for Sibyl Memory Plugin.
+
+Wraps the local SQLite + FTS5 memory engine (sibyl-memory-client) and
+exposes it to any MCP-compatible agent: Claude Code, Codex CLI, Cursor,
+Continue, etc.
+
+Usage (Claude Code):
+    Add to ~/.claude/settings.json or project .mcp.json:
+        {
+          "mcpServers": {
+            "sibyl-memory": { "command": "sibyl-memory-mcp" }
+          }
+        }
+
+Usage (Codex CLI):
+    Add to ~/.codex/config.toml:
+        [[mcp_servers]]
+        name = "sibyl-memory"
+        command = "sibyl-memory-mcp"
+
+Both expect `sibyl init` to have been run first so credentials.json and
+memory.db exist at ~/.sibyl-memory/.
+"""
+
+from .server import build_server, run_stdio
+
+__version__ = "0.1.0"
+__all__ = ["build_server", "run_stdio", "__version__"]

sibyl-memory-mcp/src/sibyl_memory_mcp/__main__.py

@@ -0,0 +1,10 @@
+"""Entry point: `sibyl-memory-mcp` console script + `python -m sibyl_memory_mcp`."""
+from .server import run_stdio
+
+
+def main() -> None:
+    run_stdio()
+
+
+if __name__ == "__main__":
+    main()

sibyl-memory-mcp/src/sibyl_memory_mcp/server.py

@@ -0,0 +1,372 @@
+"""MCP server exposing Sibyl Memory Plugin tools.
+
+8 tools:
+  - memory_remember        store an entity
+  - memory_recall          read an entity by category+name
+  - memory_search          FTS5 search across ALL tiers (entities + state + reference + journal)
+  - memory_list            list entities, optionally filtered by category
+  - memory_forget          archive an entity (preserved, removed from active set)
+  - memory_set_state       write a HOT-tier state document
+  - memory_get_state       read a HOT-tier state document
+  - memory_record_event    append a COLD-tier journal event
+
+All operations run against the local SQLite at ~/.sibyl-memory/memory.db.
+The cap gate (free-tier 2 MB hard cap, paid-tier uncapped) is enforced
+automatically by the underlying sibyl-memory-client SDK — the MCP server
+just surfaces the typed errors back to the caller.
+
+v0.1.1 hardening (audit-remediation):
+  - MemoryClient cached at module scope, NOT reopened per call (audit P-H1).
+    Invalidation: file-mtime watch of credentials.json so `sibyl upgrade`
+    is picked up without a server restart.
+  - memory_record_event signature fixed against actual write_event
+    contract (audit C1). Previous signature called a non-existent positional
+    form and every invocation raised TypeError.
+  - memory_get_state unpacks the nested {body, updated_at} dict so the
+    response shape has body=user_payload, not body={user_payload, ...}
+    (audit H2 body double-meaning fix).
+  - memory_list category parameter is now Optional (audit N3).
+  - credentials.json reads honor the lstat / symlink check (audit SEC-4/11).
+"""
+from __future__ import annotations
+
+import json
+import os
+import threading
+from pathlib import Path
+from typing import Any
+
+from mcp.server.fastmcp import FastMCP
+from sibyl_memory_client import MemoryClient
+from sibyl_memory_client.exceptions import (
+    CapExceededError,
+    NotFoundError,
+    TierGateError,
+    TierVerificationError,
+    ValidationError,
+)
+
+# Default install location matches the rest of the plugin ecosystem.
+DEFAULT_DB_PATH = Path(os.environ.get(
+    "SIBYL_MEMORY_DB",
+    Path.home() / ".sibyl-memory" / "memory.db",
+))
+DEFAULT_CRED_PATH = Path(os.environ.get(
+    "SIBYL_CREDENTIALS",
+    Path.home() / ".sibyl-memory" / "credentials.json",
+))
+
+
+# ----------------------------------------------------------------------
+# Credential loading (audit SEC-4, SEC-11)
+# ----------------------------------------------------------------------
+
+def _load_credentials() -> dict[str, Any]:
+    """Read credentials.json if present. Missing file = pre-activation, free tier.
+
+    v0.1.1 hardening:
+      - Refuses to follow symlinks (SEC-11). If the file is a symlink,
+        treat as absent — same behavior as the Hermes provider.
+      - Treats any I/O / parse error as absent (existing behavior).
+    """
+    if not DEFAULT_CRED_PATH.exists():
+        return {}
+    if DEFAULT_CRED_PATH.is_symlink():
+        return {}
+    try:
+        return json.loads(DEFAULT_CRED_PATH.read_text())
+    except (OSError, json.JSONDecodeError):
+        return {}
+
+
+# ----------------------------------------------------------------------
+# Cached MemoryClient (audit P-H1)
+# ----------------------------------------------------------------------
+
+_client_lock = threading.Lock()
+_client_cache: dict[str, Any] = {
+    "client": None,           # MemoryClient instance, lazily built
+    "creds_mtime": None,      # mtime of credentials.json at last open
+    "creds_path_exists": False,
+}
+
+
+def _credentials_mtime() -> float | None:
+    """Return credentials.json mtime if present, else None.
+
+    Used to detect `sibyl upgrade` having written new credentials so the
+    cached MemoryClient can be rebuilt with the new tier."""
+    try:
+        if DEFAULT_CRED_PATH.exists() and not DEFAULT_CRED_PATH.is_symlink():
+            return DEFAULT_CRED_PATH.stat().st_mtime
+    except OSError:
+        pass
+    return None
+
+
+def _open_client() -> MemoryClient:
+    """Return a MemoryClient bound to the local DB + credentials.
+
+    v0.1.1 (audit P-H1): cached at module scope. Previously rebuilt every
+    tool call (reading schema.sql from disk + bootstrapping FTS5 vtables —
+    10-50ms per call). Now invalidated only when credentials.json mtime
+    changes, which is the only thing that should change tier behavior.
+    """
+    with _client_lock:
+        cur_mtime = _credentials_mtime()
+        cur_exists = DEFAULT_CRED_PATH.exists()
+        client = _client_cache["client"]
+        cached_mtime = _client_cache["creds_mtime"]
+        cached_exists = _client_cache["creds_path_exists"]
+        # Rebuild if no cached client, or credentials.json mtime changed,
+        # or credentials.json appeared / disappeared (post-init / post-logout).
+        if client is None or cur_mtime != cached_mtime or cur_exists != cached_exists:
+            client = _build_client()
+            _client_cache["client"] = client
+            _client_cache["creds_mtime"] = cur_mtime
+            _client_cache["creds_path_exists"] = cur_exists
+        return client
+
+
+def _build_client() -> MemoryClient:
+    """Construct a fresh MemoryClient. Called only on cache miss."""
+    creds = _load_credentials()
+    DEFAULT_DB_PATH.parent.mkdir(parents=True, exist_ok=True)
+    return MemoryClient.local(
+        str(DEFAULT_DB_PATH),
+        tenant_id=creds.get("tenant_id"),
+        account_id=creds.get("account_id"),
+        session_token=creds.get("session_token"),
+        tier=creds.get("tier", "free"),
+        credentials_claim={
+            "account_id": creds.get("account_id"),
+            "tenant_id": creds.get("tenant_id"),
+            "tier": creds.get("tier"),
+            "email": creds.get("email"),
+            "wallet": creds.get("wallet"),
+            "issued_at": creds.get("issued_at"),
+            "schema_version": creds.get("schema_version", 1),
+        } if creds.get("signature") else None,
+        credentials_signature=creds.get("signature"),
+    )
+
+
+# ----------------------------------------------------------------------
+# Error mapping
+# ----------------------------------------------------------------------
+
+def _err(e: Exception) -> dict[str, Any]:
+    """Map SDK exception → structured error payload the agent can reason about."""
+    cls = type(e).__name__
+    payload = {"error": cls, "message": str(e)}
+    if isinstance(e, CapExceededError):
+        payload["code"] = "CAP_EXCEEDED"
+        payload["recovery"] = "Run `sibyl upgrade` to lift the 2 MB free-tier cap."
+        payload["upgrade_url"] = getattr(e, "upgrade_url", "https://sibyllabs.org/plugin/upgrade")
+    elif isinstance(e, TierGateError):
+        payload["code"] = "TIER_GATED"
+        payload["recovery"] = "This feature requires a paid tier. Run `sibyl upgrade`."
+    elif isinstance(e, TierVerificationError):
+        payload["code"] = "TIER_VERIFICATION_FAILED"
+        payload["recovery"] = "The server couldn't verify your tier. Check connectivity and try again."
+    elif isinstance(e, NotFoundError):
+        payload["code"] = "NOT_FOUND"
+    elif isinstance(e, ValidationError):
+        payload["code"] = "VALIDATION_ERROR"
+    return payload
+
+
+# ----------------------------------------------------------------------
+# Server build
+# ----------------------------------------------------------------------
+
+def build_server() -> FastMCP:
+    """Build and return the MCP server. Tool names are prefixed with `memory_`."""
+    mcp = FastMCP("sibyl-memory")
+
+    @mcp.tool()
+    def memory_remember(category: str, name: str, body: dict[str, Any]) -> dict[str, Any]:
+        """Store an entity in long-term memory.
+
+        Use for facts, project state, person profiles, anything the agent
+        should remember across sessions. Idempotent on (category, name) —
+        a second call with the same key updates the entry.
+
+        Args:
+            category: Logical grouping (e.g. "people", "projects", "facts").
+            name: Unique-within-category identifier (e.g. "alice", "acme-deal").
+            body: Arbitrary JSON-serializable object. Becomes the entity body.
+        """
+        try:
+            client = _open_client()
+            client.set_entity(category, name, body)
+            return {"ok": True, "category": category, "name": name}
+        except Exception as e:
+            return _err(e)
+
+    @mcp.tool()
+    def memory_recall(category: str, name: str) -> dict[str, Any]:
+        """Read an entity by exact (category, name) lookup.
+
+        Returns: {ok: True, entity: {id, tenant_id, category, name, status,
+        body, created_at, updated_at}} where `body` is the user-supplied
+        payload. Or a NOT_FOUND error.
+        """
+        try:
+            client = _open_client()
+            return {"ok": True, "entity": client.get_entity(category, name)}
+        except Exception as e:
+            return _err(e)
+
+    @mcp.tool()
+    def memory_search(query: str, limit: int = 10) -> dict[str, Any]:
+        """Full-text search across ALL Sibyl tiers (entities + state +
+        reference + journal).
+
+        v0.1.1: spans all four searchable tiers. Each hit carries a `tier`
+        tag so the agent knows where the match came from. Previously was
+        entities-only — the v0.3.0 plugin family marketing claim of
+        "search across all tiers" is now actually true.
+
+        Query is sanitized as a single FTS5 phrase — column-filter syntax
+        (`name:foo`, `rowid:*`) is treated as literal text and cannot
+        break out into the FTS5 parser. Empty/invalid queries return [].
+
+        Args:
+            query: Search terms. User input is sanitized before MATCH.
+            limit: Maximum results to return (default 10, max 50).
+        """
+        try:
+            client = _open_client()
+            results = client.search(query, limit=min(max(limit, 1), 50))
+            return {"ok": True, "query": query, "count": len(results), "results": results}
+        except Exception as e:
+            return _err(e)
+
+    @mcp.tool()
+    def memory_list(
+        category: str | None = None,
+        limit: int = 50,
+    ) -> dict[str, Any]:
+        """List entities, optionally filtered by category. Most-recently-updated first.
+
+        v0.1.1: `category` is now optional (audit N3 — matches the SDK and
+        Hermes adapter behavior). Pass it to filter; omit to list across
+        all categories.
+
+        Args:
+            category: Optional category filter. Pass None or omit to list all.
+            limit: Max entities to return (default 50, max 200).
+        """
+        try:
+            client = _open_client()
+            results = client.list_entities(category=category, limit=min(max(limit, 1), 200))
+            return {"ok": True, "category": category, "count": len(results), "results": results}
+        except Exception as e:
+            return _err(e)
+
+    @mcp.tool()
+    def memory_forget(category: str, name: str, reason: str | None = None) -> dict[str, Any]:
+        """Archive an entity (not destroyed — moved to archived_entities).
+
+        The body is preserved in the archive table for forensic recovery
+        but no longer appears in recall/list/search. Pass a `reason` to
+        record why; useful in audit reviews.
+        """
+        try:
+            client = _open_client()
+            client.archive_entity(category, name, reason=reason)
+            return {"ok": True, "archived": {"category": category, "name": name}}
+        except Exception as e:
+            return _err(e)
+
+    @mcp.tool()
+    def memory_set_state(key: str, body: dict[str, Any] | list[Any]) -> dict[str, Any]:
+        """Write a HOT-tier state document.
+
+        Use for ephemeral working state the agent updates frequently —
+        current focus, in-flight task list, working draft. Faster than
+        entity writes; one row per key, overwritten on each set.
+        """
+        try:
+            client = _open_client()
+            client.set_state(key, body)
+            return {"ok": True, "key": key}
+        except Exception as e:
+            return _err(e)
+
+    @mcp.tool()
+    def memory_get_state(key: str) -> dict[str, Any]:
+        """Read a HOT-tier state document by key.
+
+        v0.1.1 (audit H2): response shape is now flat —
+            {ok, key, body: <user payload>, updated_at: <iso ts>}
+        Previously returned ``body`` = the full ``{body, updated_at}`` dict
+        from the SDK, so "body" meant two different things at different
+        nesting levels.
+        """
+        try:
+            client = _open_client()
+            doc = client.get_state(key)
+            if doc is None:
+                return {"ok": False, "code": "NOT_FOUND", "key": key}
+            # Unpack the SDK's {body, updated_at} wrapper so the MCP response
+            # uses `body` for the user payload only.
+            return {
+                "ok": True,
+                "key": key,
+                "body": doc.get("body"),
+                "updated_at": doc.get("updated_at"),
+            }
+        except Exception as e:
+            return _err(e)
+
+    @mcp.tool()
+    def memory_record_event(
+        kind: str,
+        body: dict[str, Any],
+        category: str | None = None,
+        name: str | None = None,
+    ) -> dict[str, Any]:
+        """Append a COLD-tier journal event.
+
+        Use for things that happened — actions taken, decisions made,
+        observations recorded. Append-only; never overwrites. Best paired
+        with entities (the entity is the noun, the journal is the verb).
+
+        v0.1.1 (audit C1): wired against the actual SDK signature
+        ``write_event(*, evaluated, acted, forward, extra, ts)``. Previously
+        called a positional form that doesn't exist and raised TypeError on
+        every invocation. The high-level (kind, body, category, name)
+        contract is preserved by translating into the SDK shape:
+          - kind / body → `acted = {kind, body}`
+          - category / name → `extra = {category, name}` (when supplied)
+
+        Args:
+            kind: Event class (e.g. "decision", "observation", "action").
+            body: JSON-serializable event payload.
+            category: Optional entity category this event is about.
+            name: Optional entity name this event is about.
+        """
+        try:
+            client = _open_client()
+            acted = {"kind": kind, "body": body}
+            extra = None
+            if category is not None or name is not None:
+                extra = {}
+                if category is not None:
+                    extra["category"] = category
+                if name is not None:
+                    extra["name"] = name
+            event_id = client.write_event(acted=acted, extra=extra)
+            return {"ok": True, "event_id": event_id, "kind": kind}
+        except Exception as e:
+            return _err(e)
+
+    return mcp
+
+
+def run_stdio() -> None:
+    """Run the server on stdio transport (what Claude Code / Codex / Cursor expect)."""
+    mcp = build_server()
+    mcp.run()