diff --git a/.dockerignore b/.dockerignore new file mode 100644 index 0000000000000000000000000000000000000000..a6dc29c7aebca3cea235376a99e958fc91215e85 --- /dev/null +++ b/.dockerignore @@ -0,0 +1,37 @@ +# Keep the Docker build context minimal and secret-free. +# VCS + CI +.git +.github +# Python build/test cruft +**/__pycache__/ +**/*.py[cod] +**/*.egg-info/ +**/build/ +**/dist/ +**/.pytest_cache/ +**/.mypy_cache/ +**/.ruff_cache/ +**/.coverage +**/htmlcov/ +.tox/ +# Environments + secrets (never in the image) +**/.venv/ +**/venv/ +**/env/ +**/.env +**/.env.* +!**/.env.example +# Local databases / state (never in the image) +**/*.db +**/*.sqlite +**/*.sqlite3 +.sibyl-memory/ +# Private schema (never publish) +sibyl-plugin-schema/ +# Docs + editor +docs/ +.vscode/ +.idea/ +# Other monorepo packages the MCP image does not need in context +sibyl-memory-cli/ +sibyl-memory-langgraph/ diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000000000000000000000000000000000000..1bd81c1b76acca3fc148d99a9d173251bde07151 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,66 @@ +name: Bug report +description: Something in Sibyl Memory does not work as documented +labels: ["bug"] +body: + - type: markdown + attributes: + value: | + Thanks for the report. Never paste the contents of `~/.sibyl-memory/credentials.json` or any token. + Security issues: email sibyl@sibyllabs.org instead of opening an issue. + - type: textarea + id: what + attributes: + label: What happened + description: What you ran, what you expected, and what you got instead. + validations: + required: true + - type: textarea + id: repro + attributes: + label: Steps to reproduce + placeholder: | + 1. pip install sibyl-memory-cli + 2. sibyl setup cursor + 3. ... + validations: + required: true + - type: textarea + id: output + attributes: + label: Full error output + render: shell + - type: textarea + id: versions + attributes: + label: Versions + description: Output of `sibyl status`, or `pip show sibyl-memory-client sibyl-memory-cli sibyl-memory-mcp sibyl-memory-hermes`. + render: shell + validations: + required: true + - type: dropdown + id: harness + attributes: + label: Harness + options: + - Claude Code + - Codex + - Cursor + - Grok Bot + - Hermes + - LangGraph + - Another MCP client + - Not harness-related + validations: + required: true + - type: input + id: platform + attributes: + label: OS and Python version + placeholder: macOS 15 (Apple Silicon), Python 3.11.9 + validations: + required: true + - type: textarea + id: doctor + attributes: + label: sibyl doctor output (setup or MCP problems) + render: shell diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000000000000000000000000000000000000..acf08340c4633746ca8856f46bd36e11708720a4 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,8 @@ +blank_issues_enabled: false +contact_links: + - name: Documentation + url: https://docs.sibyllabs.org/memory/ + about: Install, setup for each harness, the CLI, and tiers. + - name: Account or billing help + url: mailto:support@sibyllabs.org + about: Sign-in, plans and payments go to support, not the issue tracker. diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000000000000000000000000000000000000..0c1236ea49f1aaa9db2cca464b09fea855586e3f --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,22 @@ +name: Feature request +description: Suggest an improvement or a new integration +labels: ["enhancement"] +body: + - type: textarea + id: problem + attributes: + label: The problem + description: What are you trying to do, and where does Sibyl Memory get in the way? + validations: + required: true + - type: textarea + id: proposal + attributes: + label: What you would like + validations: + required: true + - type: input + id: harness + attributes: + label: Harness or framework it applies to + placeholder: Claude Code, Hermes, LangGraph, all diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000000000000000000000000000000000000..ec25f4a19b2e3dd2f9ed5753fdead7b4016462db --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,17 @@ + + +## What this fixes or adds + +## How to reproduce the problem (or see the feature) + +## Tests + +- [ ] Added or updated a test that fails without this change +- [ ] Ran the package's tests with a throwaway HOME (`HOME=$(mktemp -d) pytest -q`) +- [ ] Works on Python 3.10 (no 3.11+ syntax or standard-library features) + +Related issue: diff --git a/.github/workflows/hf-mirror.yml b/.github/workflows/hf-mirror.yml new file mode 100644 index 0000000000000000000000000000000000000000..62e031193d3c709ac26dba2f05e9c852f2e57bba --- /dev/null +++ b/.github/workflows/hf-mirror.yml @@ -0,0 +1,65 @@ +name: Mirror to Hugging Face + +on: + push: + branches: [main] + workflow_dispatch: + +jobs: + mirror: + runs-on: ubuntu-latest + steps: + - name: Checkout (full history) + uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - name: Inject HF model-card frontmatter (runner-only; GitHub README stays clean) + run: | + printf '%s\n' \ + '---' \ + 'license: mit' \ + 'tags:' \ + ' - agent-memory' \ + ' - long-term-memory' \ + ' - llm' \ + ' - ai-agents' \ + ' - mcp' \ + ' - retrieval' \ + ' - sqlite' \ + ' - rag' \ + '---' \ + '' \ + '> **Read-only mirror of [`Sibyl-Labs/Sibyl-Memory`](https://github.com/Sibyl-Labs/Sibyl-Memory).** The canonical source is on GitHub. Install from PyPI: `pip install -U sibyl-memory-cli` · Docs: https://docs.sibyllabs.org/memory/ · Product: https://sibyllabs.org/plugin · Benchmarks: https://blog.sibylcap.com/beta-analysis' \ + '' > README.hf.md + cat README.md >> README.hf.md + mv README.hf.md README.md + git config user.name sibyl + git config user.email sibyl@sibyllabs.org + git add README.md + git commit -q -m "hf: model-card frontmatter for the mirror" || echo "README unchanged" + + - name: Push snapshot to Hugging Face Hub (retry on transient 429) + env: + HF_TOKEN: ${{ secrets.HF_TOKEN }} + run: | + # Token via credential helper (read from env at call time): never in the + # remote URL, argv, or any error message git might print. + git config credential.helper '!f() { echo "username=sibyllabs"; echo "password=${HF_TOKEN}"; }; f' + # HF is a read-only distribution mirror; its pre-receive hook rejects binary + # blobs found ANYWHERE in git history (e.g. the pip-cache blobs that briefly + # entered history in 2026-07). Push a single flattened SNAPSHOT of the current + # tree instead of full history: permanently immune to any historical blob, and + # history has no value on a mirror (canonical source + full git history live on + # GitHub; install is via PyPI). The snapshot carries the README frontmatter + # committed above. + git checkout -q --orphan hf-snapshot + git add -A + git commit -q -m "Snapshot mirror of Sibyl-Labs/Sibyl-Memory@${GITHUB_SHA:-main}" + for i in 1 2 3 4 5; do + if git push --force "https://huggingface.co/SibylLabsLLC/Sibyl-Memory" hf-snapshot:main; then + echo "mirror pushed on attempt $i"; exit 0 + fi + echo "attempt $i failed (likely transient HF 429); backing off"; sleep $((i*15)) + done + echo "all push attempts failed"; exit 1 diff --git a/.github/workflows/macos-framework-smoke.yml b/.github/workflows/macos-framework-smoke.yml new file mode 100644 index 0000000000000000000000000000000000000000..3525d5be09f8df3acd3c3f2bb9ce64439c7e817a --- /dev/null +++ b/.github/workflows/macos-framework-smoke.yml @@ -0,0 +1,139 @@ +# macOS framework-Python smoke (Sibyl-Labs/Sibyl-Memory#29 / PR #30). Installs +# the python.org "Framework" build, strips its CA store, proves the stdlib +# default context then cannot verify api.sibyllabs.org and https_context() can. +# Manual only: no macOS box on the lab side, so this is the publish gate. +name: macOS framework-Python smoke + +on: + workflow_dispatch: + +env: + # python.org universal2 installer. Refresh: newest 3.12.x pkg + shasum -a 256. + PY_URL: https://www.python.org/ftp/python/3.12.10/python-3.12.10-macos11.pkg + PY_SHA256: 8373e58da4ea146b3eb1c1f9834f19a319440b6b679b06050b1f9ee3237aa8e4 + PY_FRAMEWORK: /Library/Frameworks/Python.framework/Versions/3.12/bin/python3 + PROBE_URL: https://api.sibyllabs.org/api/plugin/health + +jobs: + wheels: + name: build wheels + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v5 + with: + python-version: "3.12" + - run: python -m pip install --upgrade pip build + - name: build + run: | + set -eux + for pkg in sibyl-memory-client sibyl-memory-hermes sibyl-memory-mcp sibyl-memory-cli; do + python -m build --wheel --outdir dist "$pkg" + done + ls -la dist + - uses: actions/upload-artifact@v4 + with: + name: wheels + path: dist/*.whl + if-no-files-found: error + + smoke: + name: macOS framework Python + needs: wheels + runs-on: macos-latest + steps: + - uses: actions/download-artifact@v4 + with: + name: wheels + path: dist + + - name: install the python.org framework build (no Install Certificates.command) + run: | + set -eux + curl -fsSL -o python.pkg "$PY_URL" + echo "$PY_SHA256 python.pkg" | shasum -a 256 -c - + sudo installer -pkg python.pkg -target / + "$PY_FRAMEWORK" -VV + + - name: install the built wheels into a venv + run: | + set -eux + "$PY_FRAMEWORK" -m venv "$RUNNER_TEMP/smoke" + "$RUNNER_TEMP/smoke/bin/python" -m pip install --upgrade pip + "$RUNNER_TEMP/smoke/bin/python" -m pip install --find-links dist dist/*.whl + + - name: strip the pre-wired CA store (reproduce the report) + # The image already ran Install Certificates.command (etc/openssl holds a + # certifi symlink), so the stock context verifies and the report is NOT + # reproduced until it is removed. A fake pem would test a different bug. + run: | + set -eux + unset SSL_CERT_FILE SSL_CERT_DIR || true + env | grep -i '^SSL_' || true + PREFIX="$(dirname "$(dirname "$PY_FRAMEWORK")")" + ls -la "$PREFIX/etc/openssl" || true + mkdir -p "$RUNNER_TEMP/ca-backup" + sudo mv "$PREFIX/etc/openssl/cert.pem" "$RUNNER_TEMP/ca-backup/" || true + sudo mv "$PREFIX/etc/openssl/certs" "$RUNNER_TEMP/ca-backup/" || true + "$PY_FRAMEWORK" -c "import ssl; print(ssl.get_default_verify_paths()); print(ssl.OPENSSL_VERSION)" + + - name: write the shared TLS classifier + run: | + cat > "$RUNNER_TEMP/probe.py" <<'PY' + import os, ssl, sys, urllib.error, urllib.request + UA = {"User-Agent": "sibyl-memory-smoke/1"} + def classify(e): + # An HTTPError is a real HTTP status, so the handshake SUCCEEDED + # (Cloudflare 403s our datacenter IP). Only a cert error is a TLS fail. + if isinstance(e, urllib.error.HTTPError): + return "TLS_OK" + if isinstance(e, urllib.error.URLError) and "CERTIFICATE_VERIFY_FAILED" in repr(e): + return "TLS_FAIL" + return "OTHER" # DNS, refused, timeout: never reached the TLS check + def probe(ctx): + req = urllib.request.Request(os.environ["PROBE_URL"], headers=UA) + try: + with urllib.request.urlopen(req, context=ctx, timeout=15) as r: + return "TLS_OK", r.status, r.read(120) + except urllib.error.HTTPError as e: + return "TLS_OK", e.code, e.read(120) + except Exception as e: + return classify(e), None, repr(e) + stock = ssl.create_default_context() + if sys.argv[1] == "baseline": + cls, status, body = probe(stock) + print("BASELINE:", cls, "status:", status, body) + if cls == "TLS_OK": + raise SystemExit("BASELINE: the stock context VERIFIED, so this runner still has a wired CA store and is NOT reproducing the report") + raise SystemExit(0 if cls == "TLS_FAIL" else "BASELINE: WRONG failure: %s" % (body,)) + import certifi + from sibyl_memory_client._trust import https_context + ctx = https_context() + print("certifi:", certifi.where(), "| fixed store:", ctx.cert_store_stats(), "| stock store:", stock.cert_store_stats()) + cls, status, body = probe(ctx) + print("FIX:", cls, "status:", status, body) + if cls != "TLS_OK": + raise SystemExit("FIX: %s: %s" % (cls, body)) + PY + - name: baseline, expected to FAIL with CERTIFICATE_VERIFY_FAILED + continue-on-error: true + run: '"$RUNNER_TEMP/smoke/bin/python" "$RUNNER_TEMP/probe.py" baseline' + - name: the fix, must SUCCEED + run: '"$RUNNER_TEMP/smoke/bin/python" "$RUNNER_TEMP/probe.py" fix' + + - name: "the CLI must not report a server error 0" + run: | + set -eu + export PATH="$RUNNER_TEMP/smoke/bin:$PATH" + # `sibyl update` reads PyPI over HTTPS through the same trust context, + # so it is the command that actually exercises the fixed path. + sibyl update 2>&1 | tee cli.txt + sibyl status 2>&1 | tee -a cli.txt + if grep -q "server error: 0" cli.txt; then + echo "FAIL: the CLI still reports 'server error: 0'" + exit 1 + fi + if grep -qi "CERTIFICATE_VERIFY_FAILED" cli.txt; then + echo "FAIL: the CLI still hits a certificate verification failure" + exit 1 + fi diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml new file mode 100644 index 0000000000000000000000000000000000000000..8f079ce6637622ed5a00e803aacd5d4602983ff0 --- /dev/null +++ b/.github/workflows/tests.yml @@ -0,0 +1,91 @@ +# Test suites of the five packages on every supported Python (review panel +# finding 9, 2026-11-14): nothing ran the tests on push, and Python 3.10, the +# declared floor, was never executed. Each package's own pytest runs with an +# empty HOME, so no test can read or write a real ~/.sibyl-memory, ~/.claude, +# ~/.codex, ~/.cursor, ~/.hermes or ~/.dsh. +name: tests + +# push runs on the default branch only (main); a PR branch runs once, from +# pull_request, instead of twice. +on: + push: + branches: [main] + pull_request: + +permissions: + contents: read + +jobs: + pytest: + name: pytest (Python ${{ matrix.python-version }}) + runs-on: ubuntu-latest + strategy: + fail-fast: false + matrix: + python-version: ["3.10", "3.11", "3.12", "3.13"] + steps: + - uses: actions/checkout@v4 + + - uses: actions/setup-python@v5 + with: + python-version: ${{ matrix.python-version }} + + - name: install (editable, dependencies first) + run: | + set -eux + python -m pip install --upgrade pip + # client first: hermes, mcp, cli and langgraph all depend on it; + # hermes before mcp and cli, mcp before cli. + python -m pip install -e ./sibyl-memory-client + python -m pip install -e ./sibyl-memory-hermes + python -m pip install -e ./sibyl-memory-mcp + python -m pip install -e ./sibyl-memory-cli + python -m pip install -e ./sibyl-memory-langgraph + python -m pip install pytest + python -m pip list + + - name: pytest per package (temp HOME) + run: | + set -u + status=0 + for pkg in client hermes mcp cli langgraph; do + home="$(mktemp -d)" + echo "::group::sibyl-memory-$pkg" + extra="" + # needs the `claude` binary, which the runner does not have + if [ "$pkg" = "cli" ]; then + extra="--deselect tests/test_orchestrator.py::test_orchestrator_full_flow" + fi + (cd "sibyl-memory-$pkg" && HOME="$home" USERPROFILE="$home" \ + python -m pytest -q -p no:cacheprovider $extra tests) || status=1 + echo "::endgroup::" + rm -rf "$home" + done + exit $status + + # The lowest declared mcp (sibyl-memory-mcp pins mcp>=1.19.0) on the lowest + # supported Python, for the mcp package only, with pydantic held below 2.12 + # to match that mcp release (measured 2026-11-14: 284 passed). + mcp-floor: + name: pytest mcp (Python 3.10, mcp 1.19.0) + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - uses: actions/setup-python@v5 + with: + python-version: "3.10" + + - name: install (lowest mcp) + run: | + set -eux + python -m pip install --upgrade pip + python -m pip install -e ./sibyl-memory-client -e ./sibyl-memory-mcp \ + "mcp==1.19.0" "pydantic<2.12" pytest + python -m pip list + + - name: pytest sibyl-memory-mcp (temp HOME) + run: | + home="$(mktemp -d)" + cd sibyl-memory-mcp + HOME="$home" USERPROFILE="$home" python -m pytest -q -p no:cacheprovider tests diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000000000000000000000000000000000000..1b952c559eab73345ab9ea376eaa787b0c0dc8b2 --- /dev/null +++ b/.gitignore @@ -0,0 +1,50 @@ +# 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/ + +# Private schema (never publish to public repo) +sibyl-plugin-schema/ + +# pip HTTP cache (never commit) +.pipcache/ diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000000000000000000000000000000000000..f1ecfce30772c3586bcac9a89805e44a7fe1bce4 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,53 @@ +# Contributing to Sibyl Memory + +Thanks for looking. Bug reports, reproductions and ideas are the most useful things you can send, and they are always read. + +## How changes land + +Sibyl Memory ships as a paid product as well as an open-source plugin family, so **we do not merge outside code directly**. When a pull request finds a real bug or a good idea, we re-implement it in-house, ship it in the next release, and credit you by GitHub handle in the CHANGELOG and the release notes. A pull request is still the clearest way to show a fix: the diff, the failing case and the test are what we work from. + +Please open an issue first for anything larger than a small fix, so we can tell you whether it fits before you spend the time. + +## Reporting a bug + +Use the bug report form. The most helpful reports include: + +- the package versions (`sibyl status` prints them, or `pip show sibyl-memory-client sibyl-memory-cli sibyl-memory-mcp sibyl-memory-hermes`) +- your OS and Python version +- the harness (Claude Code, Codex, Cursor, Hermes, LangGraph, another MCP client) +- the exact command and the full error output +- the output of `sibyl doctor`, if the problem is with setup or the MCP server + +Never paste the contents of `~/.sibyl-memory/credentials.json` or any token. + +## Security issues + +Do not open a public issue. Email sibyl@sibyllabs.org with the details and a way to reach you. + +## Working on the code + +The repo holds five packages, each with its own `pyproject.toml`, tests and CHANGELOG: + +| Package | What it is | +| --- | --- | +| `sibyl-memory-client` | The SDK: local SQLite store, FTS5 search, the memory model | +| `sibyl-memory-cli` | The `sibyl` command: sign-in, setup for each harness, `doctor`, `memory` | +| `sibyl-memory-mcp` | The MCP server for Claude Code, Codex, Cursor and any MCP client | +| `sibyl-memory-hermes` | The Hermes memory provider | +| `sibyl-memory-langgraph` | A LangGraph `BaseStore` | + +Setup (Python 3.10 or newer): + +```bash +python -m venv .venv && . .venv/bin/activate +pip install -e sibyl-memory-client -e sibyl-memory-cli -e sibyl-memory-mcp -e sibyl-memory-hermes pytest +cd sibyl-memory-cli && pytest -q +``` + +Run the tests with a throwaway `HOME` (`HOME=$(mktemp -d) pytest -q`) so nothing touches your real `~/.sibyl-memory`, `~/.claude`, `~/.codex` or `~/.hermes`. + +Every package supports Python 3.10 and newer. Do not use syntax or standard-library features that need 3.11 or 3.12 (for example, reusing an f-string's quote inside `{}`). + +## Good first issues + +Issues labelled `good first issue` are small, self-contained and have a clear done state. Comment on one before starting so two people do not take the same one. diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 0000000000000000000000000000000000000000..1101b420c79df1d17fb641382c44a3b1a4889f36 --- /dev/null +++ b/Dockerfile @@ -0,0 +1,39 @@ +# syntax=docker/dockerfile:1 +# First-party Docker image for the Sibyl Memory MCP server (stdio transport). +# Non-root, pinned slim base, no secrets baked in. Storage lives on a mounted +# volume at /home/app/.sibyl-memory. See sibyl-memory-mcp/README.md "Docker". +# TODO: pin by digest before publish (no docker daemon in build env). +# Keep comments on their own line: a trailing "# ..." after FROM is parsed as +# extra FROM arguments and fails the build. +FROM python:3.12-slim-bookworm + +# No build tools needed: sibyl-memory-mcp is pure Python and sqlite3 + FTS5 +# ship in the stdlib. Keep the layer count and surface minimal. +ENV PYTHONUNBUFFERED=1 \ + PYTHONDONTWRITEBYTECODE=1 \ + PIP_NO_CACHE_DIR=1 \ + PIP_DISABLE_PIP_VERSION_CHECK=1 + +# Non-root runtime user with a real home for the default ~/.sibyl-memory path. +RUN groupadd --gid 10001 app \ + && useradd --uid 10001 --gid 10001 --create-home --home-dir /home/app app + +# Install the MCP server from the local monorepo source (first-party build, +# not pulled from PyPI at image-build time). Copy only the mcp package, then +# pip install it, which pulls its declared deps (mcp, sibyl-memory-client, +# sibyl-memory-hermes) from PyPI. +WORKDIR /app +COPY sibyl-memory-mcp/ /app/sibyl-memory-mcp/ +RUN pip install /app/sibyl-memory-mcp + +# Memory dir on the mounted volume, owned by the non-root user, mode 0700. +RUN mkdir -p /home/app/.sibyl-memory \ + && chown -R app:app /home/app/.sibyl-memory \ + && chmod 700 /home/app/.sibyl-memory +VOLUME ["/home/app/.sibyl-memory"] + +USER app +ENV HOME=/home/app + +# stdio MCP server. Run attached with STDIN open (docker run -i), no TTY. +ENTRYPOINT ["sibyl-memory-mcp"] diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000000000000000000000000000000000000..ec17a86a156882e7351814ef54a31c3a5bae9433 --- /dev/null +++ b/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. diff --git a/README.md b/README.md new file mode 100644 index 0000000000000000000000000000000000000000..db32545bb503d6a205950ff408c2d700dae424dc --- /dev/null +++ b/README.md @@ -0,0 +1,235 @@ +--- +license: mit +tags: + - agent-memory + - long-term-memory + - llm + - ai-agents + - mcp + - retrieval + - sqlite + - rag +--- + +> **Read-only mirror of [`Sibyl-Labs/Sibyl-Memory`](https://github.com/Sibyl-Labs/Sibyl-Memory).** The canonical source is on GitHub. Install from PyPI: `pip install -U sibyl-memory-cli` · Docs: https://docs.sibyllabs.org/memory/ · Product: https://sibyllabs.org/plugin · Benchmarks: https://blog.sibylcap.com/beta-analysis + +
+ +``` +███████╗██╗██████╗ ██╗ ██╗██╗ +██╔════╝██║██╔══██╗╚██╗ ██╔╝██║ +███████╗██║██████╔╝ ╚████╔╝ ██║ +╚════██║██║██╔══██╗ ╚██╔╝ ██║ +███████║██║██████╔╝ ██║ ███████╗ +╚══════╝╚═╝╚═════╝ ╚═╝ ╚══════╝ + + M E M O R Y +``` + +**agentic memory infrastructure · file-based · zero embeddings** + +[![PyPI · client](https://img.shields.io/pypi/v/sibyl-memory-client?label=client&color=8a6a2a)](https://pypi.org/project/sibyl-memory-client/) +[![PyPI · cli](https://img.shields.io/pypi/v/sibyl-memory-cli?label=cli&color=8a6a2a)](https://pypi.org/project/sibyl-memory-cli/) +[![PyPI · hermes](https://img.shields.io/pypi/v/sibyl-memory-hermes?label=hermes&color=8a6a2a)](https://pypi.org/project/sibyl-memory-hermes/) +[![PyPI · mcp](https://img.shields.io/pypi/v/sibyl-memory-mcp?label=mcp&color=8a6a2a)](https://pypi.org/project/sibyl-memory-mcp/) +[![PyPI · langgraph](https://img.shields.io/pypi/v/sibyl-memory-langgraph?label=langgraph&color=8a6a2a)](https://pypi.org/project/sibyl-memory-langgraph/) +[![License: MIT](https://img.shields.io/badge/license-MIT-15110a.svg)](./LICENSE) +[![Python 3.10+](https://img.shields.io/badge/python-3.10+-15110a.svg)](https://www.python.org/downloads/) +[![LongMemEval](https://img.shields.io/badge/LongMemEval-95.6%25%20%23%E2%80%832-2e6b3a.svg)](https://blog.sibylcap.com/longmemeval-v2) + +built by an autonomous agent · sibyl labs llc + +
+ +--- + +## What this is + +Five PyPI packages, one schema family, one architecture. + +**Runs on** Linux, macOS (Apple Silicon and Intel), and Windows through WSL2. Native Windows is not supported. + +`sibyl-memory-client` is a local-first agentic memory SDK. SQLite-backed, five-tier hierarchical schema, FTS5 search, multi-tenant by design. No vector database. No embedding model. No external retrieval service. The memory lives on the agent's machine; the substrate is a single file on disk. + +> **Privacy disclosure.** Your memory content never leaves the machine. The plugin talks to `api.sibyllabs.org` for these things only: activation (`sibyl init`); a daily account check-in that renews this computer's access (account id, this computer's sign-in token, plugin version, OS family; no memory content); a size check when a free account nears its cap (account id, sign-in token, the database's byte size and the proposed delta); and an aggregate count of memory operations (the MCP server and CLI send it unless you opt out with `SIBYL_MEMORY_TELEMETRY=0`; Hermes, since 0.6.0, only if you opt in with `SIBYL_MEMORY_TELEMETRY=1`). The size check and the count also carry this computer's signed access token (account id, tier, cap, device hash, account flags; no personal data). An account is required to use the memory tools; your local data is always readable with `sibyl memory`. Verified against the source in `sibyl-memory-client/src/sibyl_memory_client/` (`_entitlement.py`, `_capcheck.py`, `_heartbeat.py`). + +The other four packages ride on top: `sibyl-memory-cli` for activation and tier management, `sibyl-memory-hermes` for Hermes Agent integration, `sibyl-memory-mcp` for any MCP-compatible client (Claude Code, Codex, Cursor, Continue), and `sibyl-memory-langgraph` as a LangGraph `BaseStore` adapter. + +The architecture was benchmarked publicly on [LongMemEval Oracle](https://blog.sibylcap.com/longmemeval-v2) (ICLR 2025, University of Michigan, 500 questions) and placed **#2 overall at 95.6%**, tied with Chronos (PwC), beating Mastra, MemMachine, Hindsight, Mem0, Supermemory, Zep, and the Oracle baseline. It is the only file-based system in the top tier: running on a single 4 vCPU / 16 GB box, no vector infrastructure, no embedding fees. + +This is the entire stack as it ships to production agents today. + +--- + +## 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` opens the Pro / Elite upgrade 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-memory-langgraph`](./sibyl-memory-langgraph) | [![PyPI](https://img.shields.io/pypi/v/sibyl-memory-langgraph)](https://pypi.org/project/sibyl-memory-langgraph/) | LangGraph `BaseStore` adapter. Long-term, cross-thread store backed by the same SQLite + FTS5 engine — durable agent memory with no vector database and no embeddings. | + +--- + +## Install + +```bash +pip install sibyl-memory-cli +sibyl init +``` + +`sibyl init` opens a browser to activate your account, binds your wallet or email, and writes credentials to `~/.sibyl-memory/credentials.json` plus this computer's signed access file, `entitlement.json`. Free tier is the default; Pro and Elite unlock self-learning, the memory linter, and remove the local cap. + +**An account is required.** Since client 0.9.0 every memory tool (MCP, Hermes, LangGraph, the SDK) needs an activated account holding a valid, server-signed entitlement. Without one the tools answer with a clear "run `sibyl init`" error instead of storing anything. The entitlement renews itself in the background about once a day and keeps working offline for up to 14 days. Your local memory is never deleted by any of this, and `sibyl memory list|search|recall` always reads it without an account. Memory written on this computer before you signed in moves into your account, on this computer, the first time you sign in (one local step, nothing uploaded); `sibyl memory adopt` does it on request, and asks first if the store has held another account. Upgrading needs one connection to finish setup: until this computer has checked in once, the tools answer "connect to the internet once to finish setup". + +### Open code, hosted account + +The code in this repository is MIT licensed, including the whole local engine, so a fork can remove the account check. We say that plainly. Here is what such a fork keeps and what it cannot have: + +| A fork keeps (local, always public under MIT) | A fork loses (held by the server; needs the entitlement or the live sign-in it comes from) | +|---|---| +| The SQLite schema, storage, FTS5 search, the verdict contract, the write-time normalizer, a local cap check it can edit away, unlimited local stores | Anything above the free cap on the official path (from the client cutoff, `/check-write` refuses without a live sign-in and a matching entitlement) | +| Reading and writing its own local database with any agent it wires up itself | Paid recognition anywhere: learner and linter authorization keyed to the entitlement tier, purchase claims, the billing portal, USDC subscriptions | +| The MIT right to redistribute its modified copy under its own name | Device management (`sibyl devices`, revoke, web approval), the account page, email verification, recovery, receipts and security notices | +| | Updates, support, the beta channel, and every hosted feature to come | +| | The name: the official packages, docs and installers point at accounts | + +For direct SDK use: + +```bash +pip install sibyl-memory-client +``` + +For Hermes integration: + +```bash +pip install sibyl-memory-cli +sibyl setup hermes # installs the plugin and sets memory.provider: sibyl +``` + +For MCP (Claude Code, Codex, Cursor, Continue, ...): + +```bash +pip install sibyl-memory-mcp sibyl-memory-cli +sibyl setup claude-code # or: sibyl setup codex | cursor | grokbot +sibyl doctor # end-to-end check: start, list tools, save, recall, delete a test memory +# other MCP clients: sibyl setup --print-config prints a ready mcpServers block +``` + +The Hermes plugin-catalog package lives in `sibyl-memory-hermes/hermes-catalog/`; the catalog listing is pending. + +Full documentation at [docs.sibyllabs.org/memory](https://docs.sibyllabs.org/memory/). + +--- + +## Architecture + +``` +┌─────────────────────────────────────────────────────────┐ +│ sibyl-memory-cli sibyl-memory-mcp │ +│ ┌──────────────┐ ┌──────────────┐ │ +│ │ sibyl init │ │ MCP server │ │ +│ │ sibyl status │ │ (stdio) │ │ +│ │ sibyl whoami │ └──────┬───────┘ │ +│ └──────┬───────┘ │ │ +│ └────────────┬─────────────────┘ │ +│ sibyl-memory-hermes │ sibyl-memory-langgraph │ +│ ┌──────────────┐ │ ┌────────────────┐ │ +│ │ Hermes hook │ │ │ LangGraph │ │ +│ └──────┬───────┘ │ │ BaseStore │ │ +│ │ │ └───────┬────────┘ │ +│ │ │ │ │ +│ │ │ │ │ +│ └────────────┼─────────────┘ │ +│ ▼ │ +│ 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 the detail. + +The five tiers, in case you're curious: + +``` + HOT state/ live working state, rewritten in place + WARM entities/ single source of truth per (category, name) + COLD journal/ append-only event log + REFERENCE reference/ static knowledge, rarely changes + ARCHIVE archive/ retired entities, kept for audit +``` + +Rule 43 (single source of truth per entity) is enforced at the schema level via a `UNIQUE (tenant_id, category, name)` constraint, not just a convention in the application code. Drift is impossible by construction. + +--- + +## Provenance + +Built by [SIBYL](https://x.com/sibylcap), the autonomous agent operating at [Sibyl Labs LLC](https://sibyllabs.org). + +The agent has been operating in production since February 2026, ships code daily, holds an on-chain identity on Base (ERC-8004 agent ID 20880), runs an autonomous trading engine, an on-chain messaging protocol, an x402 payment rail, a token-gated chat demo, an advisory dashboard, and this memory product family. Everything verifiable on-chain. + +Memory architecture is the proven core. Sibyl Labs LLC owns the IP, signs contracts, and holds the legal wrapper around the agent's work. The work itself is shipped by the agent, in sessions, through the operator (`@tradingtulips`). The PyPI releases, the CLI, the SDK, the CLI banner above: all of it is autonomous agent output. + +The on-chain record is the resume. This repository is one chapter of it. + +--- + +## Save and debloat + +**Save.** At the end of a session, or after a big block of work, your agent writes what happened +into Sibyl Memory through the plugin's own tools: the decisions made and why (journal), the +people, projects and products touched (entities), what to pick up next time and the open +warnings (session state), the ranked priorities, and it closes what died (archive). A delta +marker means a second save in the same day captures only what changed. It may offer to turn a +repeated pattern into a reusable skill; that is offered, never forced. Nothing in a save leaves +your machine. + +**Debloat.** Sibyl measures the files your agent loads on every session start (`CLAUDE.md`, +`AGENTS.md`, `.cursorrules` and the rest of the scan set), deterministically (`chars/4`, +labeled `MEASURED~`), and when they are heavy, trims the accreted history out of them without +losing a byte: the history moves out and a one-line pointer stays. On the free plan the history +moves to a sibling `*-history` file. On Pro it is stored in Sibyl Memory as a reference document, +so it stays searchable, and the measurement and trim run by themselves under a policy you set +once. + +| | Free (activated account) | Pro | +|---|---|---| +| The procedures in `~/.sibyl-memory/skills/` (`SAVE.md`, `DEBLOAT.md`), `/sibyl-save` and `/sibyl-debloat` in Claude Code, skills in Hermes and Codex, a block in Codex's `AGENTS.md`, the `save` and `debloat` MCP prompts | yes | yes | +| `sibyl save`, `sibyl debloat` (measure, plan, apply, undo) | yes | yes | +| Reminders (one quiet line; `sibyl reminders off`) | yes | replaced by a one-line report of what ran | +| Where trimmed history goes | a sibling `*-history` file | Sibyl Memory, plus a byte-verified backup | +| Automatic debloat | no | yes: `propose` by default; a file is trimmed by itself only after you run `sibyl debloat auto ` (that file at its path, never the same name elsewhere) | +| Automatic save by active time: once early (after 5 memory writes or a compaction), then about every 60 minutes of active work, only when there is something to save, at most 8 a session and 12 a day (`sibyl autosave every <30-240>` or `sibyl autosave off`). Claude Code: the Stop hook asks your agent to run the save procedure headless (a scripted `claude -p` run is never asked); Cursor, Codex and other MCP hosts: a `notice` on the next tool result; Hermes: a note in the next prefetch. A session capsule (counts only) at compaction and session end. Each automatic save is one extra model turn that reads and writes memory | no | yes | +| Skill proposals: Sibyl finds repeated work in your journal (locally, no network), names up to 3 at a session start at most once a day, and creates nothing without a yes (`/sibyl-save curate`, or `sibyl skills proposals accept `, which writes the skill for Claude Code, Codex and Hermes) | no (`/sibyl-save` still offers skills when you run it) | yes | +| Skill signals (0.10): Sibyl also notices a tool sequence your agent repeats (in Claude Code the whole workflow, for example `Read -> Edit -> Bash`; in Codex, Cursor and Hermes the memory tools only) and an entity rewritten again and again, and proposes a skill for it the same way. It keeps one small local file, `~/.sibyl-memory/signals.json`: tool and MCP server names in plain text, argument names and entity names only as hashes, never a value, never a prompt or a file path; nothing leaves your computer. `sibyl skills signals` shows its size, `clear` deletes it, `off` stops it. In Claude Code a proposal from the workflow appears at the next session start at the earliest | no (nothing is recorded) | yes | + +The procedures are vendored, with attribution, from the public MIT repos +[sibyl-save](https://github.com/Sibyl-Labs/sibyl-save) and +[debloat](https://github.com/Sibyl-Labs/debloat); both stay standalone and account-free. + +Uninstalling: run `sibyl skills uninstall` first. It removes the Claude Code hooks in +`~/.claude/settings.json`, the skill shims and the Codex block (files you edited are kept); then +`pip uninstall` the packages. The hooks call this package's `sibyl` command: if the package goes +first they exit quietly, but they stay in your settings until you reinstall and run +`sibyl skills uninstall`, or delete the five `sibyl hook` entries by hand. + +Privacy: the lifecycle reads your instruction files to measure and trim them locally; no file +content and no conversation content ever leaves your machine. + +Forks: a gate-stripped fork can run the lifecycle code locally (MIT allows it). It gains nothing +hosted, and its trims land in a store the official path cannot recognize as Pro. No file, flag +or environment variable turns the automation on for a free account. + +## License + +MIT. See [LICENSE](./LICENSE). + +Copyright (c) 2026 Sibyl Labs LLC. diff --git a/docker-compose.yml b/docker-compose.yml new file mode 100644 index 0000000000000000000000000000000000000000..10caadfe379e7b369abc9413c053d0ec110116ff --- /dev/null +++ b/docker-compose.yml @@ -0,0 +1,25 @@ +# Compose file for the Sibyl Memory MCP server (stdio transport). +# This is a stdio server, NOT a network service. Do NOT `docker compose up`: +# the server reads MCP over stdin and exits on EOF. Run it attached: +# docker compose run --rm sibyl-memory-mcp +# or point an MCP client's command at a `docker run -i --rm` wrapper (see +# sibyl-memory-mcp/README.md "Docker"). No secrets live in this file: +# credentials.json arrives only through the mounted volume at runtime. +services: + sibyl-memory-mcp: + build: + context: . + dockerfile: Dockerfile + image: sibyl-memory-mcp:local + # stdio server: keep STDIN open, no TTY. Client drives stdin. + stdin_open: true + tty: false + # Env passthrough only. No values are set here. Uncomment and set on the + # host env (or an untracked .env) if you need to override defaults. + environment: + - SIBYL_MEMORY_DB + - SIBYL_CREDENTIALS + volumes: + - sibyl-memory-data:/home/app/.sibyl-memory +volumes: + sibyl-memory-data: diff --git a/docs/diagrams/setup-mcp-rail.svg b/docs/diagrams/setup-mcp-rail.svg new file mode 100644 index 0000000000000000000000000000000000000000..db682b3fd990b3e247701b011b4da46e4be350df --- /dev/null +++ b/docs/diagrams/setup-mcp-rail.svg @@ -0,0 +1,140 @@ + + + + + + + + + + + + + + + + + SIBYL MEMORY · INSTALL FLOW · 01 / 02 + claude code · codex · cursor · continue + the MCP rail + + + + + + + STEP 01 + setup + + + + + $ pip install sibyl-memory-cli sibyl-memory-mcp + resolves both from PyPI + + + + + $ sibyl init + opens browser · SIWE wallet / email + pairing code / USDC-send + + + + + $ claude mcp add sibyl-memory python -m sibyl_memory_mcp + registers the server in claude code + + + writes ~/.sibyl-memory/credentials.json (HMAC-signed, chmod 0600) + writes ~/.claude.json (or ~/.claude/mcp_servers.json) with the server entry + + + + + + + + + STEP 02 + runtime · inside a claude code session + + + + + + claude code + (or codex / cursor / + continue) + + + + + tool call + sibyl_remember() + sibyl_recall() + + + + + sibyl-memory-mcp + python process + speaks MCP protocol + + + + + in-process + SDK call + + + + + sibyl-memory-client + python SDK + SQLite + FTS5 engine + + + + + structured JSON · typed result · no shell, no parsing + + + + STORAGE + + + + ~/.sibyl-memory/memory.db + SQLite + FTS5 · five-tier hierarchical schema · 0600 + + + + + ~/.sibyl-memory/credentials.json + HMAC-signed account_id + session_token + tier · 0600 + + + + + + + + + + STEP 03 · BACKGROUND + tier check + + sibyl-memory-client → api.sibyllabs.org/api/plugin/check → returns { tier, expires_at, cap_remaining } + cached locally with TTL · server-side schema v6 · bearer-token auth · HMAC tamper-evidence on credentials + + + + + sibyl labs llc · 2026 · github.com/Sibyl-Labs/Sibyl-Memory + rule 46 visual identity · fraunces + ibm plex mono · creme paper + + diff --git a/docs/diagrams/setup-sdk-rail.svg b/docs/diagrams/setup-sdk-rail.svg new file mode 100644 index 0000000000000000000000000000000000000000..eb6896eec6d4687299185f8f6f178f349fe2b498 --- /dev/null +++ b/docs/diagrams/setup-sdk-rail.svg @@ -0,0 +1,153 @@ + + + + + + + + + + + + + + + + + SIBYL MEMORY · INSTALL FLOW · 02 / 02 + hermes agent · any python harness + the SDK rail + + + + + + PATH A · HERMES AGENT + + + + + + STEP 01 + setup + + + + $ pip install sibyl-memory-hermes + pulls sibyl-memory-client + sibyl-memory-cli as dependencies + + + + + $ sibyl init + same activation flow as the MCP rail · browser · SIWE / email / USDC + + + + + $ sibyl-memory-hermes install-plugin + drops adapter + plugin.yaml into ~/.hermes/plugins/sibyl/ + + + edit ~/.hermes/config.yaml → memory: + provider: sibyl + + + + + + + + + STEP 02 + runtime · hermes agent boots + + + + + hermes agent + scans ~/.hermes/plugins/ + filesystem discovery + + + + + loads + + + + + SibylMemoryProvider + adapter.py + implements hermes ABC + + + + + in-process + direct method + + + + + sibyl-memory-client + python SDK + SQLite + FTS5 engine + + + + + + no IPC · no MCP protocol · no JSON marshaling · the agent and the memory engine share a python process + + + + + SAME BACKEND AS THE MCP RAIL + + + + ~/.sibyl-memory/memory.db + ~/.sibyl-memory/credentials.json · identical layout, identical tier-check rail + + + + + + + + + PATH B · ANY OTHER PYTHON HARNESS + + + + + direct SDK use · no plugin layer + + + + $ pip install sibyl-memory-client + + sibyl init (one-time, optional if you self-issue credentials) + + + + + from sibyl_memory_client import MemoryClient + + client = MemoryClient.local( + account_id="...", session_token="...", tier="staker", + ) + client.remember("user.name", "tt") + client.recall("user.name") → "tt" + + + + + + sibyl labs llc · 2026 · github.com/Sibyl-Labs/Sibyl-Memory + rule 46 visual identity · fraunces + ibm plex mono · creme paper + + diff --git a/docs/release-0.8.0-notes.md b/docs/release-0.8.0-notes.md new file mode 100644 index 0000000000000000000000000000000000000000..0c65a94c6d7582b9646600fc2ce43b85fdf8c407 --- /dev/null +++ b/docs/release-0.8.0-notes.md @@ -0,0 +1,262 @@ +# Sibyl Memory 0.8.0 "Lucid" family: release notes + +`sibyl-memory-client` 0.8.0 · `sibyl-memory-mcp` 0.2.0 · `sibyl-memory-cli` 0.4.0 · +`sibyl-memory-hermes` 0.4.0 · `sibyl-memory-langgraph` 0.2.0 + +Branch `lang-core-verdict`. Every number below comes from a run recorded in this +repository. Nothing here is projected, rounded up, or inferred. + +--- + +## What this release is + +The query-time multilingual rescue layers that four evaluation cycles accreted in +`MemoryClient.search()` were removed and replaced by one versioned write-time +normalizer, and every search that returns zero rows now returns a machine-readable +cause alongside it. + +**It improves the INDEX layer.** Stored text is rendered word-boundary clean at +write time, so a term can match at a word START rather than only as a free +substring, which is what inflected and non-spaced languages need. + +**It does not solve default-path natural-language recall.** The first call on the +default path answers 32 of 155 natural paraphrases, the same as before. The other +123 now say why, and 99 of them are recoverable by a caller that reads the verdict +and runs the taught two-retry loop. The 29 negation-phrased answerable questions +still return nothing on the default path; they now report `negation_abstain` or +`abstained_on`. `NEGATION_POLICY` is unchanged and answering a negated question +correctly still needs negation handling this engine does not have. + +Search behaviour is byte-identical to the previous build (`ef98f5b`) on every +quality field of the full battery across three configurations. This release adds +explanation, not retrieval. + +--- + +## Read these before you upgrade + +### 1. The two-retry bound is agent-side and unenforced + +The verdict tells an agent that one word in its query blocked everything, and the +tool docstring, the Hermes tool schema and the Hermes system-prompt block all +teach: drop that word, call again, at most twice, then stop. + +Nothing in the server enforces it. The server has no memory of a caller's previous +query and cannot count retries without becoming stateful. + +An agent that ignores the bound and keeps stripping words reaches the +corpus-supported residue of its own query. Measured: 6 rows across the two +supported-class injection queries, worst case 7 rounds. + +Two things make that acceptable, and both are measured: + +- A query built from vocabulary the store does not contain returns zero rows at + any number of retries. Verified unbounded on all eight zero-support injection + queries. +- The residue an unbounded loop reaches is **byte-identical to what one ordinary + call returns with no loop at all**. `memory_search('contract')` returns the same + 3 rows the unbounded loop grinds down to. The loop grants no access the caller + did not already have, and the advice this replaces (`retry with tiers="entity"`) + returned those rows for the FULL unmodified injection query in a single step. + +So the bound is a quality control, not an access boundary: it stops the loop from +answering a shorter question than the user asked. + +**The appearance hazard.** An operator reading a non-compliant agent's transcript +will see rows returned after an injection-shaped prompt. Those rows are the answer +to `contract`. They are not the answer to the injection, and no injected word +appears in any returned body. + +### 2. First open after upgrade re-backfills the shadow, O(rows), under one lock + +The stored rendering changed, so `_SHADOW_MARKER` was bumped. Every existing store +drops, recreates and re-backfills its search shadow on the next open. The marker +is in the code, so **the bump triggers this fleet-wide on upgrade**, not per-store +on demand. + +Measured: **1.65 s at 10k rows, 27 s at 100k rows.** + +It runs under one `BEGIN IMMEDIATE` write lock. A second process opening the same +store during the rebuild blocks. That lock-out is fixed (`busy_timeout` is widened +to 180 s for the whole span of schema-apply plus migration, which is exactly the +window a concurrent opener can be blocked for, then restored so the ordinary read +path keeps failing fast). The O(rows) shape itself is not removed. + +Plan for it on large stores: the first open is the slow one, every open after it +is O(1). + +### 3. `empty_store` probe cost + +`empty_store` is probed, never inferred, and only on the zero path. + +- **Zero extra `COUNT(*)` on any store that has entities.** The engine reuses the + entities count it already takes for IDF weighting; a non-zero one proves the + store is non-empty and the probe is skipped. +- **Four extra `COUNT(*)` per zero on a store holding only journal / state / + reference rows.** That is the case where the probe is load-bearing: such a store + answers queries and must be reported `abstained_on`, never `empty_store`. +- Measured at 1 `COUNT(*)` per zero-result MCP call, the same as the previous + build. Not measured above 1400 entities. + +### 4. OPEN: the corroborated-class append is unbounded + +On `client.search()` and on the MCP `tiers=` route, rows covering two or more of +the query's terms are appended without a budget. Rows covering exactly one term +are budgeted to the query's content-term count; rows covering two or more are not. + +Consequence: boilerplate carrying two of the query's terms can append up to the +caller's limit. Measured worst case on the battery: 19 appended rows where 0.7.0 +produces none. + +This is reported, not decided. A per-coverage-level budget was built and measured +and is **not shippable**: it costs 35 answer-bearing rows across 7 LongMemEval +questions, because the distributions overlap (a legitimate level needs 12 rows at +1 term, 9 at 2 and 7 at 4, while the sweep has 30 at 3), so no monotone +query-shape budget separates them and a tie-group bound fails identically. + +The **default path is unaffected**. Behaviour is pinned by +`test_corroborated_class_is_NOT_bounded_open_finding`, so a future change to it is +a deliberate change, not a drift. + +### 5. SQLite floor: 3.34, verified and now enforced + +The package carried two different floors, neither of them run: `shadow.py` +documented 3.34, `storage.py`'s recovery message told users to check for "3.38+ +for json_valid", and the stage-2 trigger shape (the rendering is staged through +nested subqueries that read `new.` INSIDE a subquery) had only ever executed on +3.45.1. `CREATE TRIGGER` failing outright was the failure mode nobody had ruled +out. + +**Verified.** SQLite was built from the amalgamation at **3.34.1** and **3.44.2** +(FTS5 + JSON1) and statically linked into a scratch interpreter: + +| version | trigger shape | shadow rows vs 3.45.1 | client suite | +|---|---|---|---| +| 3.34.1 | creates and fires on all four tiers | byte-identical | 476 passed, 12 skipped | +| 3.44.2 | creates and fires on all four tiers | byte-identical | 476 passed, 12 skipped | +| 3.45.1 | creates and fires on all four tiers | reference | 477 passed, 11 skipped | + +`_STAGE_OPS`, the nesting-depth constant tuned against the trigger parser's +ceiling on 3.45.1, is inside the ceiling on 3.34.1 and 3.44.2 as well. + +**Enforced.** `shadow.SQLITE_MIN_VERSION = (3, 34, 0)` is checked by +`assert_sqlite_supported()` at the top of `Storage._ensure_schema`, before the +schema apply and therefore before any migration write. Below it, a `SchemaError` +names the minimum, the found version and the reason. Previously the failure +surfaced from inside the v4 migration as "error in tokenizer constructor", which +named neither. The contradictory "3.38+" claim is deleted and a test asserts no +string in `storage.py` states a SQLite version. + +**3.45 is a feature boundary, not a floor.** `remove_diacritics` reached the +`trigram` tokenizer in 3.45. Below it the shadow folds the non-decomposables in +`FOLD_MAP` (l-stroke, sharp s, o-slash, ae, d-stroke, dotless i, oe, thorn, eth) +but not decomposable diacritics, because that fold is the tokenizer's job. So +`Belzyce` does not find `Bełżyce` on 3.34 through 3.44. The store opens, writes, +migrates and searches, and the primary porter-unicode61 index is unaffected. That +one test is gated on the boundary with the version in its skip reason; a companion +test covering the non-decomposable half runs on every supported version. + +Check what you are on: + +``` +python -c "import sqlite3; print(sqlite3.sqlite_version)" +``` + +### 6. Two LongMemEval residuals at limit 10 + +`e982271f` and `gpt4_f420262c` are real losses at limit 10 and clean at limit 25. + +- `e982271f` drops the session recording which venue was recommended LAST and + keeps an interchangeable venue card containing the gold string. Raising the + limit to 11, 12, 13 or 15 does not recover its row, so this needs a RANKING + change, not a holdback. +- `gpt4_f420262c` drops the EARLIEST session on an earliest-to-latest ordering + question. It closes at limit 11 via a holdback, which is a head override and is + excluded by the constraint this work ran under. + +Both are recorded as known, deferred, with reasons. + +### 7. `tiers=` is a documented bypass, not a recovery + +The previous MCP docstring taught `tiers="entity"` as the escape hatch from an +abstention. That advice is gone from the source. + +`tiers=` has no abstention gate, and therefore no injection precision gate, which +is what the abstention gate IS. It remains supported and documented as the linker +bypass with its tradeoff stated. It is not the recovery for an `abstained_on`. +The recovery for an `abstained_on` is: drop the one token named in +`verdict.tokens[0]`, call again with every gate still armed, at most twice. + +### 8. Docker-image users must rebuild the image + +A self-built `sibyl-memory-mcp` Docker image pins its dependencies at image build +time. **A `pip install -U` on the host does not reach inside the image.** Rebuild +the image to pick up 0.2.0 and the client 0.8.0 underneath it. + +This is the same class of hazard the 0.1.14 dependency-floor raise addressed: an +MCP-only install path that is not going through the CLI's tighter floor can sit on +older code while reporting a clean install. + +### 9. The deprecated `diagnostics=` dict + +`multi_record_search(..., diagnostics=)` still populates, with identical +keys and values on **every exit that previously wrote anything**. There is exactly +one observable difference: the `no significant tokens` exit now writes the five +standard keys where the previous build left the dict empty. + +Prefer `result.verdict`. An optional channel is one a caller can forget, and +forgetting it is the whole defect this release closes: the MCP server never passed +`diagnostics=` at all, so the channel was unreachable from the surface that +matters most. + +--- + +## Upgrade order + +Client first, then the packages that depend on it. The dependency floors make a +partial upgrade fail loudly rather than silently mix an old client with new +adapters: + +| package | version | floors | +|---|---|---| +| `sibyl-memory-client` | 0.8.0 | (none) | +| `sibyl-memory-hermes` | 0.4.0 | client >= 0.8.0 | +| `sibyl-memory-mcp` | 0.2.0 | client >= 0.8.0, hermes >= 0.4.0 | +| `sibyl-memory-cli` | 0.4.0 | client >= 0.8.0, hermes >= 0.4.0, mcp >= 0.2.0 (extra) | +| `sibyl-memory-langgraph` | 0.2.0 | client >= 0.8.0 | + +Note that `pip install -U ` uses pip's only-if-needed upgrade +strategy, which leaves an already-satisfying older sibling in place. The floors +above are what turn that into a resolvable upgrade rather than a silent no-op. + +--- + +## Response-shape changes + +- **MCP** `memory_search`: the response gains an additive `verdict` object on + every call, including every zero. Nothing was removed and no field changed + meaning. `count` and `verdict.returned` are reconciled after bounding, so they + cannot disagree. +- **Hermes** `sibyl_search`: returns `{"results": [...], "verdict": {...}}`. + `search_multi_record` and `search` return a `SearchResults` list subclass; + `len`, iteration, indexing, `== []`, `json.dumps`, `isinstance(x, list)`, + copy/deepcopy/pickle and slicing all behave as before (a slice correctly drops + the verdict). +- **CLI** `sibyl memory search`: the zero path prints a plain-language cause plus + a machine-readable `cause: ` line. The success path prints no extra + output. +- **langgraph** `SibylStore`: `BaseStore.search` still returns + `list[SearchItem]`; the canonical verdict of the most recent query-backed search + is exposed as `SibylStore.last_search_verdict`, and an empty FTS result is + logged at DEBUG with its cause. + +## What a verdict may carry + +Numbers, enum values, and tokens from the caller's own query. Never stored-record +content: no body text, no snippet, no entity name, no category, no key. Token +strings are capped at 64 characters and 8 per list field, and the envelope key +order is fixed and JSON-serialisable, so the verdict composes with the MCP output +fence rather than becoming a second unfenced channel out of the store. A canary +sweep planting verdict-shaped content in bodies, entity keys, categories, nested +fields and three non-entity tiers, across four SDK entry points, the MCP tool over +real spawned stdio on both routes, and the Hermes provider, found **0 leaks**. diff --git a/sibyl-memory-cli/.gitignore b/sibyl-memory-cli/.gitignore new file mode 100644 index 0000000000000000000000000000000000000000..e985853ed84acf10f62f639a4733083229c5a55d --- /dev/null +++ b/sibyl-memory-cli/.gitignore @@ -0,0 +1 @@ +.vercel diff --git a/sibyl-memory-cli/CHANGELOG.md b/sibyl-memory-cli/CHANGELOG.md new file mode 100644 index 0000000000000000000000000000000000000000..338d645a3170aa615eea05f19e615922c203f18d --- /dev/null +++ b/sibyl-memory-cli/CHANGELOG.md @@ -0,0 +1,1560 @@ +# 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.7.0] - 2026-11-14 + +### Added +- `sibyl setup deepseek` (alias `dsh`) wires Sibyl Memory into DeepSeek Harness (developer + preview). It adds one `sibyl-memory` row to the home patch file (`$DSH_HOME/cordis.patch.yml`, + default `~/.dsh`), which covers every profile, or with `--dsh-profile ` to that one + profile's patch. The file is edited as text, never re-serialized, and every edit is proven by + parsing it: your own patches, comments and `!!js` values stay as written. DeepSeek Harness is + detected only by its `profiles/` folder or `cordis.patch.yml`; a `~/.dsh` that belongs to the + unrelated Debian `dsh` program is never detected or written, and no `dsh` binary is run. New + flags `--dsh-home` and `--dsh-profile`. Needs DeepSeek Harness on Node 24.9 or newer. +- `sibyl doctor` checks each harness's wiring (Hermes, Claude Code, Codex, Cursor, Grok Bot, + DeepSeek Harness) and reports ok, missing, stale, broken, foreign, duplicate, unreadable, + disabled, overridden or unverifiable. Read-only by default. `--fix` repairs stale or broken + entries only (it never adds a missing one and never touches another tool's entry); a missing + entry is a warning that names the `sibyl setup ` command. `--harness` limits the checks + (repeatable) and `--no-harness` skips them. `--json` adds `server_ok`, `harnesses`, `fix`, + `legacy_backups` and `later`, and `ok` is now the overall verdict. Exit 1 while wiring is still + stale or broken. + +### Changed +- Config backups now live in one place: `~/.sibyl-memory/backups//` (folders 0700, + files 0600, never overwritten). A backup that cannot be written stops the config write. Old + `.bak` files beside harness configs are listed by `sibyl doctor` and never deleted. +- Codex: a stale command path in `[mcp_servers.sibyl_memory]` is fixed in place; only the command + line changes, and a second table is never appended. +- Cursor and Grok Bot: a stale path in our own entry is updated without a prompt, keeping its + `env`, `args` and other keys. +- Cursor and Codex configs that are symlinks are written through to the file they point at; the + link is kept. +- Setup and doctor never print another tool's command string. + +### Fixed (review panel, 2026-11-14) +- `sibyl setup hermes` edits `config.yaml` as text instead of re-serializing it: comments, + anchors, key order, quoting and non-ASCII text stay as written. Only `memory.provider` changes + (or two lines are added), and the result must parse to the old data with only that value + changed. When that cannot be proven, setup prints the two lines to set by hand and leaves the + file alone. A `memory:` value that is not a mapping (`memory: honcho`) now counts as an + existing setting and goes through the overwrite question. A symlinked `config.yaml` is written + through and the link is kept, as for Cursor and Codex. +- `sibyl setup hermes` and `sibyl doctor --fix` honor the plugin installer's refusal codes. A + refused install (plugin folder not empty, a symlink, or not a Sibyl install) is an error that + says what to decide, and `memory.provider` is not switched. +- Codex: table headers are found structurally. Quoted keys such as `[projects."/path"]` and + `[mcp_servers."a@b"]` end our table, so `--force` no longer drops the trusted-project tables + after it and a table with no command line no longer takes the next server's command. A + `[mcp_servers.sibyl_memory]` line inside a multi-line string is not our table. The table + replace proof checks that every other line is kept, and a command edit must sit inside our + table. +- Codex: adding the table is proven before the write. A file that sets `mcp_servers` as a key + (an inline table), ends inside an open string or array, or does not parse is refused with the + exact text to add by hand. CRLF files keep CRLF. `sibyl doctor` reports a `config.toml` that + does not parse as unreadable instead of PASS, and setup no longer calls a table with no + command, or one that runs another server, "already wired". +- Codex: a quoted `"command"` or `'command'` key is recognized, so `doctor --fix` updates it in + place instead of adding a second command key. A missing command is fixable only when a TOML + parser is available. +- New dependency `tomli>=2` on Python 3.10, used when `tomllib` is not in the standard library, + so the Codex parse-and-compare proof runs on every supported Python. The text checks stay. +- Config writes create the temp file with `O_EXCL` under a unique name beside the target, set + the target's mode before any content is written, fsync the file and the directory, and remove + only their own temp file on failure. +- The CLI sends the session token only to https `*.sibyllabs.org` or a loopback host (the same + gate as the client library). Any other `SIBYL_API_BASE` gets a clear error and nothing is sent; + the legacy upgrade link is never built for another host. +- DeepSeek Harness: when setup or `doctor --fix` cannot update an existing row, the manual text + changes that row's command (or replaces the row) instead of adding a second row. `sibyl doctor` + prints the block on its own lines (and in `fix_block` in `--json`), so it stays valid YAML. +- Claude Code without the `claude` command on PATH: setup no longer writes `mcpServers` into + `~/.claude/settings.json` (Claude Code does not read servers from there) and no longer reports + the server as wired. It installs the hooks and skills and hands over the exact + `claude mcp add --scope user sibyl-memory -- ` command. +- Tests: the DeepSeek Harness proof layers and the `_atomic_text` symlink refusal each have a test + that fails when that check is removed; the version test reads `pyproject.toml`. +- With an untrusted `SIBYL_API_BASE` (not https `*.sibyllabs.org` and not a loopback address), `sibyl + status`, `refresh`, `devices`, `upgrade`, `email` and `claim` say the sign-in was not sent and hand + over `next: done` with "ask your human: SIBYL_API_BASE points at a host Sibyl will not send your + sign-in to; unset it", never "retry", "server error: 0" or "connect to the internet". The + explanation prints at most once per process (`sibyl upgrade` printed it twice). An untrusted + `SIBYL_UPGRADE_BASE` gets the same treatment. `sibyl whoami` makes no network call. +- The CLI refuses to send the sign-in to a URL with a backslash, whitespace, a control character or + userinfo (`https://evil.com\@sibyllabs.org/x` was allowed), on its own side, before the client's + host rule, and for the client gate's `/entitlement` refresh too, so cli 0.7.0 is protected with + sibyl-memory-client 0.10.0 installed. +- Codex: a `config.toml` that starts with a UTF-8 BOM is no longer called invalid TOML; the BOM is + kept. +- Hermes: the `config.yaml` edit is proven before the plugin install and the backup, so a file setup + cannot edit (`memory: {provider: x}`) ends with nothing installed, no backup and the two lines to + set by hand. Doctor reports `memory: honcho` as foreign, as setup does, not as absent. On an + installer refusal only setup's handoff is printed, not the installer's own `next:` line. +- `sibyl doctor` repair for Claude Code quotes the binary path in the manual `claude mcp add` command. +- README: the environment override examples use `staging.sibyllabs.org` and say where the sign-in + is sent. +- Tests: the Hermes `__init__.py` check after a zero-return install, the Codex doctor parser check + (duplicate `command` keys) and the open-string refusal message each fail when removed. CI runs on + push to main and on pull requests (once per PR branch), plus one Python 3.10 job on mcp 1.19.0. + +## [0.6.2] - 2026-11-12 + +### Fixed +- `sibyl` crashed at import on Python 3.10 and 3.11 although the package declares + `requires-python >=3.10` (issue #32, reported by @drexthealpha). One f-string in + `sibyl status` reused its own quote inside a replacement field, which only parses on + Python 3.12+. Install succeeded and every command then failed with a SyntaxError. +- New test `tests/test_py310_syntax_2026_11_12.py` walks the token stream of all five + packages and fails on that construct, since Python 3.12's parser accepts it even with + `feature_version=(3, 10)`. + +## [0.6.1] - 2026-11-02 + +### Fixed +- `sibyl setup cursor`, `sibyl setup grokbot`, `sibyl setup claude-code`, `sibyl setup codex` and + `sibyl doctor` now find `sibyl-memory-mcp` when it is installed but not on PATH. They look on + PATH, then beside the running Python, then in `~/.local/bin`, and write the absolute path into + the client config. On a fresh machine where `~/.local/bin` was not on PATH yet, setup used to + try to reinstall the server and then stop with "not on PATH. Install it" (field report from a + Grok Bot install, 2026-11-01). +- When the server really is missing, the error now says it is not installed and names the places + it looked, instead of "not on PATH". + +## [0.6.0] - 2026-10-31 + +One release: the paid tier R2 line, the shipped 0.5.0 fixes it was built beside, the graph line and the release merge items below. + +### Release summary +- `sibyl memory neighbors`: the edges of one node. Existing relations are carried over on first open. +- `sibyl setup cursor`, `sibyl setup grokbot`, `sibyl setup --print-config` and `sibyl doctor`. +- Carried from the 0.5.0 family already on PyPI (2026-10-14), now also on this line: the shown tier + and plan end on `sibyl status`, `sibyl update` for every package, `sibyl --version`. +- Pro: the Claude Code Stop hook records skill signals (names and hashes only, local). + +### Release merge (2026-10-28) + +#### Grok Bot / Cursor / any-MCP onboarding + +#### Added +- `sibyl setup cursor`: `CursorWirer` writes `~/.cursor/mcp.json` (`mcpServers.sibyl-memory`, + `{"type": "stdio", "command": }`, format per cursor.com/docs/context/mcp). + Timestamped backup, atomic write, foreign entries and a differing `sibyl-memory` entry are never + clobbered without `--force`, a corrupt file is never replaced, `_verify_mcp_starts` runs after. + Auto-detected by `sibyl setup` (`~/.cursor` or `cursor` / `cursor-agent` on PATH). `--cursor-config`. +- `sibyl setup grokbot`: the Cursor wiring plus a printed confirmation (server name, command path, + config file). Explicit target only; never auto-detected. +- No-detect fallback and `sibyl setup --print-config`: print the absolute `sibyl-memory-mcp` path and a + copy-paste `mcpServers` JSON block so any MCP client or agent can wire itself. +- `sibyl doctor` (`--json`): starts the MCP server, lists tools, saves a MARKED test memory + (`_sibyl_doctor/doctor-test-`), recalls it, deletes it (`memory_forget` archives, so the exact + test row is then purged from `entities` and `archived_entities` and verified gone). Per-step + PASS/FAIL, exit 1 on any failure; a missing account reports "run `sibyl init`". + +#### Changed +- `sibyl setup` never reads a non-terminal stdin at the multi-framework picker: it takes the same + default as end of input ("no terminal: wiring all detected"). An unknown target's handoff now names + every target (`hermes|claude-code|codex|cursor|grokbot`). +- Installer (`sibyllabs/install`, shipped with the site at publish, not in this package): tests that /dev/tty can + be opened; with no usable terminal it runs `sibyl setup --yes` instead of skipping; `--yes` aliases `--setup`. + +#### Other +- `tests/smoke/venv-compat.sh`: one `sibyl memory neighbors` check on a v6 edge. +- The usage count keeps the opt-out default in the CLI (`test_telemetry_default_2026_10_28.py`, 2). +- Requires `sibyl-memory-client>=0.10.0`, `sibyl-memory-hermes>=0.6.0`, `[mcp]` `sibyl-memory-mcp>=0.4.0`. + +### Paid tier R2: skill signals (built 2026-09-29) + +Spec plugin-paid-tier-r2-spec-2026-09-29 section 1. Requires sibyl-memory-client 0.10.0, +sibyl-memory-hermes 0.6.0 (and sibyl-memory-mcp 0.4.0 with the `mcp` extra). BYOK drafting +(spec section 2: `sibyl skills proposals draft`, `sibyl skills summarizer`, `byok.py`) is NOT in +this release (operator 2026-09-29). + +### Changed (tier convention, 2026-10-05; carried from 0.5.0) +- `sibyl status` Free / Pro / Elite, the `tier_unknown` access rows, the hooks mirror with elite + and the venv-compat Elite status check are carried from 0.9.0 / 0.5.0 (cherry-picked; the only + conflict was `tests/smoke/venv-compat.sh`, both blocks kept). See the 0.5.0 entry. Suite 456 -> 472. + +### Added +- The Claude Code Stop hook (Pro) records the workflow's tool sequence: it reads the transcript + from the session's stored byte offset, at most 4 MiB per Stop, keeps each `tool_use` block's + name and the hashed sorted key names of its input, and drops the parsed text. Free and locked + devices return before it (no file, no offset). The hook never runs the learner; the next MCP + server start (or Hermes shutdown) turns the record into proposals. Measured: see the release + notes. +- `sibyl skills signals [status|clear|off|on]`: status prints counts, size and dates, never an + entry; `clear` deletes `signals.json`; `off` stops recording; `on` starts it again from now. + Free: "Skill signals are on Pro." (`off` and `clear` still work, `on` changes nothing). +- `sibyl skills proposals`: `mute tool_sequence` / `mute correction_loop`; help names the + signals. `sibyl save --fact` counts as an entity write on Pro (hashed). + +### Tests +- `tests/test_hook_signals_2026_09_29.py` (12): canaries in `tool_use` input values and key + names never in any file under the home or the hook output; incremental offset; 4 MiB per Stop + on a 64 MB transcript (timed); offset reset on a changed or truncated transcript; an + unreadable transcript keeps the R1 output and the process exits 0; the `claude -p` rule; free, + locked and off; sidechain entries; a partial last line waits. +- `tests/test_skills_signals_cli_2026_09_29.py` (7): the four verbs on Pro, free and locked; + `save --fact`; the new kinds through list, show, accept (valid SKILL.md, reference copy), + reject, mute and unmute. + +### Changed (R2 check fixes, 2026-09-30) +- R2F-N4: `sibyl skills signals` help and status say the record keeps tool and MCP server names + (the Claude Code transcript names MCP tools `mcp____`), not tool names only; + README row and the repo README row the same. +- The Stop hook is now the only recorder of Claude Code tool events when it is wired (mcp 0.4.0 + R2F-2); nothing changes in the hook itself. Suite 456 passed. + +### Tiered retrieval and relations (graph line, built 2026-10-22) + +### Changed - Adoption edge outcomes (V1 panel theme A, 2026-10-22) +- `sibyl memory adopt` reports links that were already in the account (not copied + twice) and links held back because their endpoint name exists in the account both + as itself and as `(before sign-in)` with no record of which one they meant (up to 5 + listed, with how to clear them). A re-run with only held links says so instead of + "nothing to move". + +### Fixed - release train (V1 panel B, 2026-10-22) +- `version = "0.6.0"`, requires `sibyl-memory-client>=0.10.0`, + `sibyl-memory-hermes>=0.6.0` and (extra `mcp`) `sibyl-memory-mcp>=0.4.0`. README: + upgrade the packages together (`sibyl update --apply`). +- The version pin test moves to 0.6.0 (`test_package_version_is_0_6_0`). + +### Changed - bundled procedures v1.2.0 (tiered-retrieval section 3, 2026-10-22) +- `sibyl setup` / the lifecycle screens now report "procedures v1.2.0" (client SAVE.md + agent guidance: which tier to write, links with the node, read top-down). No CLI code + change; the lifecycle test pin moves 1.1.0 -> 1.2.0. + +### Added +- `sibyl memory neighbors (--entity CATEGORY NAME | --reference KEY | --state KEY) + [--relation R ...] [--direction out|in|both] [--tier T] [--limit N] [--cursor C]`: + read-only listing of one node's edges, tenant-resolved like `list` / `search` / `recall`. + +## [0.5.0] - Unreleased + +### 2026-10-14 - Pre-release cleanup +- `sibyl migrate` tells Hermes users to run `sibyl setup hermes` instead of editing + `~/.hermes/config.yaml` by hand. +- `sibyl setup --help` mentions Codex, and `--claude-settings` now says what it really sets: the + path to Claude Code's `settings.json` (default `~/.claude/settings.json`). +- The account host shown while waiting for approval and after `sibyl logout` follows + `SIBYL_ACCOUNT_BASE` when it is set. With the default, the text is unchanged. +- README: activation and status samples match what the commands print today (the free cap is + 5,242,880 bytes, not 2,097,152), tier drift points at `sibyl refresh`, `sibyl --version` is + listed, the Upgrade section describes the current Pro pricing and flow, and the PyPI + description names Pro / Elite instead of the retired staker / subscription tiers. +- Removed unused internal helpers and constants; docstrings describe current behavior. +- `sibyl upgrade`, when it opens the plugin upgrade page instead of the account billing page, now + names the current offer: Pro $12/month or $108/year (USDC for one fixed period, or by card plus + applicable tax at sibyllabs.org/checkout followed by `sibyl claim`), or free Pro while 100,000 $SIBYL stays + staked. It no longer mentions a quarterly USDC plan. +- Comments, docstrings, test file names and this CHANGELOG describe each finding by what it fixed + instead of naming testers or internal QA rounds. Text and test file names only; no code changed. + +### 2026-10-10 - sign-in and display fixes +- F-1 (contract C1): the api's 401 `signed_out_on_claim` (this computer was signed out when the + account's email was first confirmed on the account page) is named everywhere the CLI used to + say only "signed out · run sibyl init" or "session expired": the `sibyl status` Access row (from + the gate's refresh) and server row, `sibyl email`, `sibyl email verify|add|confirm`, `sibyl + devices`, `sibyl upgrade` and `sibyl claim` print `signed out: this computer was signed out + when your email was confirmed on the account page ( UTC). run: sibyl init --force`, and + the handoff is `next: sibyl init --force`. Any other 401 keeps its old line. + `gate_http_line` / `gate_http_handoff` take the error body. Tests: + `tests/test_signin_display_fixes_2026_10_10.py` (F-1 block). +- F-1a (contract C2): `sibyl init` with `cli_email_verify` on and the email unconfirmed sends the + code without the "confirm it now?" question; the only prompt is for the code (Enter skips). + Every path that leaves the email unconfirmed (Enter at the code prompt, a wrong or failed code, + no terminal, `--no-email`, and `cli_email_verify` off) prints `until you confirm your email + here, signing in on the account page signs this computer out. confirm later with: sibyl email + verify`. With no terminal no code is mailed unasked (the handoff stays `sibyl email verify`). + Tests: `tests/test_accounts_patch_2026_09_26.py` (two old rows rewritten, three added). +- `sibyl setup --dry-run` compares with what is installed and says "already + in" for the skills (`skills v: SAVE.md, DEBLOAT.md already in `), each shim (`shim + : already in`), the Claude Code hooks (`hooks: 5 already in `) and the Codex + AGENTS.md block (`block: already in `); missing, outdated and edited files say what a real + run would do. Still reads only. +- times shown to people carry a zone, in UTC: `sibyl devices` (`last seen 2026-10-09 + 19:08 UTC`), the computer-limit list at `sibyl init`, `sibyl status` (Tier cache checked, + offline "as of", Expires, Issued), `sibyl claim` (Covers through), `sibyl memory` (updated), + and the save/autosave rows (`last save`, `last 19:08 UTC`). New module `_timefmt.py`. +- `sibyl --version` prints every installed Sibyl package on one line, the CLI first: + `sibyl cli 0.5.0+dev.5 · client 0.9.0+dev.5 · mcp 0.3.0+dev.5` (hermes and langgraph when + installed). Still exits 0 without touching ~/.sibyl-memory. +- `sibyl init` offers "send USDC from any mobile wallet" (the section line, the + subtitle and the agent's ask line) only when session-init minted this session's USDC-send bind + (`bind_amount_micros` and `bind_bus_wallet` set); while USDC sign-in is off the api sends both + null and init lists two paths, desktop wallet and email plus code. +- Suite: 961 passed (was 930). + +### Fixed (`sibyl update` covers the MCP server, 2026-10-09) +- `sibyl update` now also updates the MCP server (and LangGraph when installed). It checks every + Sibyl package that is installed among `sibyl-memory-cli`, `-client`, `-hermes`, `-mcp` and + `-langgraph`, and `--apply` upgrades the outdated ones in one `pip install -U` call; a package + that is not installed is not shown and is never installed. Before, the MCP server that the + installer puts on every install (`sibyl-memory-cli[mcp]`) stayed on its old version. The + `--json` document has the same keys, with one row per installed package; the pipx hint and the + exit codes are unchanged. Tests: `tests/test_update_installed_pkgs_2026_10_09.py` (+13); two + pipx handoff rows list the five packages. Suite: 930 passed (was 917). + +### Added (version row, 2026-10-08) +- `sibyl --version` prints `sibyl ` (for example `sibyl 0.5.0` or `sibyl 0.5.0+dev.4`) and + exits 0. It needs no subcommand and reads or writes nothing under `~/.sibyl-memory`. +- `sibyl status` opens with a `plugin` eyebrow and one `Version cli · client ` row (client + `not installed` when `sibyl-memory-client` is missing), in both the "Not activated." and the + activated layout, so a pasted status always carries the build. `sibyl whoami` is unchanged. + Tests: `tests/test_version_2026_10_08.py`. Tester guide line: `sibyl --version` replaces `pip list`. + +### Fixed (shown tier and plan end, 2026-10-08) +- F1: every tier the CLI shows is the tier of this computer's current verified pass, the saved + credentials tier only when there is no valid pass (`_account_gate.display_tier` / + `peek_tier`): `sibyl status` (LOCAL Tier row, the uncapped / percent-of-cap DB size, the + local vs server drift check), the `sibyl init` "already activated" and "Activated." rows, + `sibyl whoami` and the `sibyl upgrade` current tier. `sibyl status` takes the access check-in + before printing the LOCAL rows (output order unchanged) and re-reads the credentials the + check-in may have rewritten. A tier cache that disagrees with a valid pass reads + `superseded by the access pass (checked ...)` instead of a second tier. `sibyl refresh` and + the background re-check rewrite the saved tier (client `sync_credentials_tier`). Looking up + the pass with no `entitlement.json` evaluates nothing, so it never leaves a file behind. +- F2: the Access row says `active · re-checks in h` (the pass re-check), not `renews in`, + which read like a billing renewal. A `Plan` row under it shows the billing date from the + pass's `acct.plan`: `Pro · ends 8 Oct 2027` (a cancellation, or a fixed term) or + `Pro · renews 8 Oct 2027` (a renewing card plan), in local time; no row when the server sends + no date (older api, Free, staker, Lifetime). The tier word is the one the Tier row shows. +- README: the status sample and the Access table use `re-checks in`, and describe the Plan row. +- Tests: `tests/test_tier_plan_2026_10_08.py` (+13); three label assertions updated to + `re-checks in`. Suite: 911 passed (was 898). + +### Changed (web-first onboarding QA patch, 2026-10-08) +Decision D21 of onboarding-friction-final-analysis-2026-10-08 (findings F7, F12, P1). Messages +only: flows, exit codes, streams and JSON keys are unchanged. +- F7: after `Activated.`, `sibyl init` ends `next: sibyl status` instead of `next: sibyl setup` + when an agent on this computer is already wired (the installer runs `sibyl setup` before + `sibyl init`, so this is the common case). The check is the one `sibyl email confirm` already + uses (row E24: Hermes or Codex config, or `sibyl-memory` in `~/.claude.json` or + `~/.claude/settings.json`; file reads only, no subprocess). When wired, `later: sibyl setup` + is no longer queued behind `sibyl email add
` or `sibyl email verify`. With nothing + wired the output is unchanged. +- Tests: seven new init rows (old api, verified, email required with none, unverified required + and not required, email confirmation not open, Codex wired), each with a harness wired. +- P1: the approve hint under the code reads "already have a Sibyl Memory account (website or + another computer)? approve this one at instead (sign in there, then type this code)". + The account may exist only on the website, so "already set up with this email on another + computer?" was the wrong question. +- F12: with `features.device_approval` on, the `ask your human:` line printed while `sibyl init` + waits puts the likeliest path first: "if you already have a Sibyl Memory account, approve this + computer at with the code ; otherwise open and sign in with email + plus that code, a desktop wallet, or USDC from a mobile wallet; I pick it up here". An agent + relays one decision instead of four equal options. With the feature off the sentence is + unchanged. Tests assert the order, the code, the single `?r=` link and the unchanged + feature-off wording. +- The "wire it into your agent" block after `Activated.` no longer tells people to hand-edit + `~/.hermes/config.yaml`, `pip install sibyl-memory-mcp` or import the provider by hand (it + contradicted the install flow: installer, then `sibyl setup`, then `sibyl init`, and the + dd0ce76 Hermes fix). With nothing wired it is one line, "wire it into your agent: sibyl setup + (wires Claude Code, Codex and Hermes)", and the handoff stays `next: sibyl setup`. With an + agent already wired (the F7 check) nothing is printed and the handoff ends + `next: sibyl status`. Two new tests cover both cases and the absence of the old commands. + +### Fixed (agent handoff check, 2026-10-07) +Findings of the adversarial check of the handoff build (no loop left for an agent that follows +only `next:`). Messages only: flows, exit codes, streams and JSON keys are unchanged. +- Email, when the api does not take confirmation from the terminal (`features.cli_email_verify` + absent or false, row E11): `sibyl init` and the `sibyl email` state no longer hand back + `sibyl email add
` (which could only fail with `not_open` and ask for the address + again). They ask the person to add and confirm the email at the account page; init ends + `next: sibyl setup` with `later: sibyl email`, `sibyl email` ends `next: done`. +- `sibyl setup`: a wirer error with no specific handoff (a Hermes or Codex config write, a Hermes + install-plugin failure) ends `next: done` with `ask your human:` naming the harness and the + error, instead of `next: retry`. A server that did not start ends `next: done` with "run + sibyl-memory-mcp in a terminal and tell me the first error line" (a missing credential: + `next: sibyl status`). An already-wired harness gets no restart ask; only a changed one does. +- `sibyl update --apply`: a non-zero pip exit ends `next: done` with "pip exited N upgrading the + packages (output above); tell me what it said", instead of `next: retry`. +- `sibyl logout` (rows O1 to O3) ends `next: done` with `later: sibyl init`: signing out no + longer starts a sign-in. +- File labels in `sibyl debloat apply|auto|undo` handoffs, the undo hint and the migrate + "not trimmed" line are shell-quoted, so a label with a space still runs verbatim. +- Tests: the convention lint sweep now covers memory search and recall, adopt A3/A4/A6/A7, + debloat auto, manual and undo, skills install, update --apply (pip failed, pip missing, pipx, + upgraded), setup X4 and X6 to X16 through the real wirers, migrate N3 to N10 through + `cmd_migrate`, health H1c/H2c, plus the E11 email and logout rows; each new scenario also + asserts it reached the path it is named for. Suite: 879 passed, 1 skipped (the installed + Claude Code binary contract test, which skips without `claude` on PATH). + +### Added (agent handoff messages, 2026-10-06) +Spec agent-handoff-messages-spec-2026-10-03 (section 2 rows I, E, U, K, S, R, H, W, D, O, V, A, +F, G, P, T, Y, Z, X, N). Messages only: no flow, command, exit code or server contract changes. +- Every stop of a `sibyl` command ends with the handoff block, on stdout, TTY or not: zero or + more `later: `, at most one `ask your human: `, then `next: ` + (or `done`, `retry`, `retry in N minutes`), always the last line. Plain text at column 0, no + glyph, no colour. A placeholder (``, `
`, ``, ``, ``) only + appears with the `ask your human:` line that names it. +- Waits print `ask your human:` and `waiting: (up to m:ss)` once when the watching + starts: `sibyl init` (the bind, the computer-limit sign-out, device approval) and + `sibyl upgrade` (the plan change). +- `--json` (`sibyl update`, `sibyl debloat`) prints no block; the document gains `next` and + `human_action`. `sibyl debloat --fyi` (one-line startup format) and `sibyl hook` (JSON for + Claude Code) print none. +- `_handoff.py` (the block, waits, the JSON keys) and `_account_gate.access_handoff()`, so + `status`, `refresh`, `health` and the gate lines agree; the values come from the client's + `ENTITLEMENT_NEXT` / `ENTITLEMENT_HUMAN_ACTION`. +- `sibyl claim` success line: "Run the next command and agents pick it up on their next call." + (was "Run `sibyl status` to see it. Your agent picks it up next session."). The tier-drift hint + in `sibyl status` names `sibyl refresh` (was `sibyl upgrade`, which opens a purchase page). +- Non-interactive runs say which default they took: `no terminal: default Y|N taken` (setup + questions), `no terminal: proceeding (pass --yes to say so)` (migrate), the extraction and + trim lines of the guided migration. +- Setup with nothing detected: `later: sibyl setup `, the question, `next: sibyl status`. + +### Fixed (agent handoff messages, 2026-10-06; spec section 5.3) +- `sibyl setup` with two or more harnesses detected, no `--yes` and no terminal no longer raises + a traceback at the picker: it wires all detected, as `--yes` does, and says so. +- `sibyl save --fact` on a full free cap prints the cap line (`later: sibyl upgrade`, + `next: done`) instead of a `CapExceededError` traceback. +- `sibyl migrate` with nothing extracted (a run without a terminal verifies at once) prints + "Backed up and wired. Extraction has not run yet." instead of "Done. Your memory now lives in + Sibyl". +- The email `expired` fallback line needed no change (it is the copy when the server sends no + message); both paths are now tested. + +### Tests (agent handoff messages) +- `tests/conftest.py`: `handoff(out)`, `json_handoff(payload)`, `assert_convention(out, err)`. +- `tests/test_handoff_rows_2026_10_03.py`: one scenario per row, each through the lint. +- `tests/test_handoff_convention_2026_10_03.py`: the lint, a sweep over every scenario, and a + source check (no em dash, glyph or ANSI in handoff copy). +- `tests/test_agent_follows_next_2026_10_03.py`: an agent that reads only `next:` lines runs + init, email add, email confirm, setup, status to `done` against a stub api, and init, setup, + status to `done` against an old api. +- The claim copy helper in `test_accounts_patch_2026_09_26.py` drops the block lines. Suite: + 736 passed (453 before). + +### Changed (tier convention, 2026-10-05) +Spec tier-convention-spec-2026-10-05 section 5 (same coordinated release; version unchanged). +- `sibyl status` prints the tier as Free / Pro / Elite (local and server view, through the + client's shared `tiers` module); a legacy local label (stake) next to the server's canonical + one (pro) is no longer reported as drift. The computers line names the plan (`1 of 10 (Elite)`) + and the size line uses `tiers.is_paid`. Other tier lines (`init`, `whoami`, `claim`, `upgrade`) + keep their upper-case style but map legacy labels to the canonical word. +- Access row for an unrecognised signed label: `active · access label "" is not recognised + by this version, treated as Free (tier_unknown) · run sibyl update`; a 503 `tier_unknown` from + the server reads `renewal paused · access label check (tier_unknown) · keep working; it retries + on its own` and keeps the last valid token. +- Hooks: the stdlib-only `PAID_TIERS` mirror gains `elite` and still equals + `sibyl_memory_client.tiers.PAID_TIERS` (asserted); the unverified claim is stripped and + lowercased (`claim_label`); a `tier_unknown` answer is written to lifecycle.log. +- `tests/smoke/venv-compat.sh`: `sibyl status` with an elite entitlement prints Elite and exits 0. +- Tests: `tests/test_tiers_cli_2026_10_05.py` (+15, including the source guard: no legacy tier + literal outside the single hooks.py mirror line, which parses to the client set); + `test_f11_paid_tier_literal_matches_the_client` compares against `tiers.PAID_TIERS` and a sibling + covers elite / " Elite " / gold claims. Suite 437 -> 453. + +### Added (paid tier R1, 2026-09-29, R1B-2) +Plan plugin-paid-tier-2026-09-29, operator defaults D1-D15 (same coordinated release; version unchanged). +- The Claude Code Stop hook asks for a headless save by ACTIVE time on Pro: once early (5 memory + writes or a compaction), then every 60 active minutes (`sibyl autosave`), at most 8 a session and + 12 a day, only with something to save. Each request is numbered ("save 2 of this session") so + the transcript guard works per request. `UserPromptSubmit` counts prompts and active time on + both tiers (a gap after a turn counts at most 5 minutes; the model's own turn at most 30). A + scripted `claude -p` run (no transcript, or fewer than two prompts) is never continued. + SessionStart adds the tier-change line and, on Pro, up to 3 named skill proposals (read-only). +- `sibyl autosave [status|on|off|every <30-240>]` (free: says it is on Pro and keeps the setting). +- `sibyl refresh`: one entitlement check now, the before/after diff (tier, cap, computers, email, + access), the procedures, shims, Codex block and (already wired) hooks refreshed, the lifecycle + rows. Exit 0 (1 on an authoritative denial, 2 offline); with no account it exits 0 and says to + run `sibyl init`. +- `sibyl skills proposals [list|show|accept|reject|mute|unmute]` (Pro; free sees "on Pro"). + `accept` writes a validated SKILL.md for the Claude Code, Codex and Hermes folders present (or + `--to `) plus the reference copy in memory; `reject` cools the slug off 30 days. +- Computer limit: `sibyl init` sends `replace: {session_token}` on session-init when this computer + already holds credentials (`--replace` implies `--force`); a `device_limit` answer (409, or + `/check` bound:false with `limit`) prints the computers and, in a terminal, says this terminal + cannot sign another computer out and asks "Open the account page to sign