release: client 0.4.4 + mcp 0.1.3 — beta bug-fix remediation

client 0.4.4:
- FTS5 search: drop AND/OR/NOT/NEAR operator keywords during tokenization
so natural-language queries return results instead of ~0 hits
- validate_identifier rejects '..' traversal + shell metachars (defense-in-depth);
SQL was already parameterized, this guards downstream non-parameterized consumers

mcp 0.1.3:
- first-use writes no longer fail pre-activation: tenant_id falls back to
DEFAULT_TENANT instead of forcing NULL (reads + tool discovery worked, so a
broken install looked healthy); regression test added
- __version__ single-sourced from importlib.metadata (no more drift)
- pin bumped to sibyl-memory-client>=0.4.4

sibyl-memory-client/CHANGELOG.md

@@ -4,6 +4,33 @@ All notable changes to `sibyl-memory-client` are recorded here. Format
 follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Versioning
 follows [SemVer](https://semver.org/).
 
+## [0.4.4] - 2026-05-28
+
+Beta-tester bug-report remediation (chainriffs Discord + KAPPA rounds 3/4).
+
+### Fixed
+
+- **FTS5 search: uppercase operator keywords poisoned recall.** A
+  natural-language query containing `AND` / `OR` / `NOT` / `NEAR`
+  (e.g. `"auth AND db"`, `"cache NEAR eviction"`) had each token
+  phrase-quoted into a *required literal* term, so a matched row had to
+  literally contain the word "AND"/"NEAR" — recall silently collapsed to
+  ~0 hits. These keywords are now dropped during tokenization so the
+  remaining terms AND together (the natural intent). A query that is
+  *only* operator keywords keeps them as literals so searching for the
+  word "and" still resolves. (`_drop_fts5_operator_tokens`.)
+
+### Security
+
+- **Identifier validation: path-traversal + metacharacter defense-in-depth**
+  (KAPPA #3 PARTIAL). `validate_identifier` now rejects the `..` traversal
+  marker and the shell/redirection/quote metacharacters `< > | ; " \``. SQL
+  was already parameterized; this guards downstream non-parameterized
+  consumers (filesystem export, CLI display, logs). Apostrophe is
+  deliberately allowed (legit in name-shaped keys). Bare `/` and `\` remain
+  allowed per the v0.4.0 contract — rejecting raw separators is a contract
+  change flagged for team decision.
+
 ## [0.4.3] - 2026-05-26
 
 ### Fixed

sibyl-memory-client/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "sibyl-memory-client"
-version = "0.4.3"
+version = "0.4.4"
 description = "Local-first agentic memory SDK. SQLite-backed five-tier hierarchical schema, FTS5 search, multi-tenant, with self-learning skill detection and local memory linter. Foundation of the Sibyl Memory Plugin family."
 authors = [{ name = "SIBYL, Sibyl Labs LLC", email = "sibyl@sibyllabs.org" }]
 license = { text = "MIT" }

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

@@ -34,6 +34,22 @@ _IDENT_MAX_LENGTH = 1024
 # design: identifiers are short single-line strings, not arbitrary payloads.
 _IDENT_FORBIDDEN_CODE_POINTS = frozenset(range(0, 0x20)) | {0x7F}
 
+# v0.4.4 (KAPPA #3 defense-in-depth): SQL is parameterized so injection is
+# closed at the DB, but identifiers flow into consumers that do NOT parameterize
+# -- filesystem export (a `name` becomes a path component), CLI display, log
+# lines, future per-entity backends. Reject path-traversal shapes and the
+# shell/redirection/quote metacharacters that have no place in a short flat key.
+# Apostrophe is deliberately ALLOWED (legit in name-shaped keys like "o'brien");
+# double-quote is rejected because it is also the FTS5 phrase delimiter.
+#
+# NOTE: we reject the traversal MARKER ".." (catches KAPPA's "../../etc/passwd"
+# and "..\\..\\windows") but NOT bare "/" or "\\" -- the v0.4.0 contract
+# explicitly permits slash-containing keys ("with/slash"). Rejecting raw path
+# separators for export-safety would be a public-contract change; flagged for
+# the team rather than taken unilaterally.
+_IDENT_FORBIDDEN_SUBSTRINGS = ("..",)
+_IDENT_FORBIDDEN_CHARS = frozenset('<>|;"`')
+
 
 def validate_identifier(value: Any, *, field_name: str) -> str:
     """Validate a user-supplied identifier (entity name, state key, etc.).
@@ -72,6 +88,25 @@ def validate_identifier(value: Any, *, field_name: str) -> str:
                     f"Remove control characters / null bytes / tabs / newlines."
                 ),
             )
+    # v0.4.4: path-traversal + dangerous metacharacter defense-in-depth.
+    for bad in _IDENT_FORBIDDEN_SUBSTRINGS:
+        if bad in value:
+            raise ValidationError(
+                f"{field_name} contains a forbidden path sequence ({bad!r})",
+                recovery=(
+                    "Identifiers are flat keys, not paths. Remove '/', '\\', "
+                    "and '..' sequences."
+                ),
+            )
+    bad_chars = sorted(_IDENT_FORBIDDEN_CHARS & set(value))
+    if bad_chars:
+        raise ValidationError(
+            f"{field_name} contains forbidden character(s): {' '.join(bad_chars)}",
+            recovery=(
+                "Remove shell / redirection / quote metacharacters "
+                "( < > | ; \" ` ) from the identifier. Apostrophe is allowed."
+            ),
+        )
     return value
 
 
@@ -146,6 +181,23 @@ _FTS5_COLUMN_TOKENS = frozenset({"name", "category", "body", "tenant_id",
                                   "payload", "ts", "rowid"})
 
 
+# v0.4.4 (chainriffs Discord report + KAPPA #4): bare uppercase FTS5 operator
+# keywords typed inside a natural-language query ("auth AND db", "cache NEAR
+# eviction") were being phrase-quoted into REQUIRED LITERAL tokens, so a matched
+# row had to literally contain the word "AND" / "NEAR" -- recall silently
+# collapsed to ~0 hits. Users mean these as connectors, not search terms. Drop
+# them during tokenization so the remaining terms AND together (FTS5's implicit
+# space-join), which is the natural intent. If a query is ONLY operator keywords,
+# keep them as literals so a genuine search for the word "and" still resolves.
+_FTS5_OPERATOR_KEYWORDS = frozenset({"AND", "OR", "NOT", "NEAR"})
+
+
+def _drop_fts5_operator_tokens(tokens: list[str]) -> list[str]:
+    """Drop standalone FTS5 operator keywords; keep all tokens if that empties it."""
+    kept = [t for t in tokens if t.upper() not in _FTS5_OPERATOR_KEYWORDS]
+    return kept or tokens
+
+
 def _sanitize_fts5_query(raw: str, *, prefix: bool = False, as_phrase: bool = False) -> str:
     """Wrap a user query as a safe FTS5 MATCH expression.
 
@@ -196,6 +248,7 @@ def _sanitize_fts5_query(raw: str, *, prefix: bool = False, as_phrase: bool = Fa
         tokens = [t for t in cleaned.split() if t]
         if not tokens:
             return ""
+        tokens = _drop_fts5_operator_tokens(tokens)
         if len(tokens) == 1:
             return f"{tokens[0]}*"
         # Multiple tokens: all earlier tokens are literal, the last gets `*`.
@@ -217,6 +270,7 @@ def _sanitize_fts5_query(raw: str, *, prefix: bool = False, as_phrase: bool = Fa
         # query still has SOME defensible shape rather than empty.
         escaped = s.replace('"', '""')
         return f'"{escaped}"'
+    tokens = _drop_fts5_operator_tokens(tokens)
     return " ".join(f'"{t}"' for t in tokens)
 
 # The default tenant for single-user local installs.

sibyl-memory-client/tests/test_kappa_fixes.py

@@ -281,3 +281,70 @@ def test_search_entities_phrase_match_semantics(tmp_path):
     # "*" is wrapped as a literal phrase
     hits = client.search_entities("*")
     assert hits == []
+
+
+# ----------------------------------------------------------------------
+# v0.4.4: entity-name path-traversal + metacharacter defense-in-depth
+# (KAPPA #3 PARTIAL — path-traversal shape + SQL-keyword shape were ACCEPTED)
+# ----------------------------------------------------------------------
+
+def test_validate_identifier_rejects_path_traversal():
+    from sibyl_memory_client.client import validate_identifier
+    from sibyl_memory_client.exceptions import ValidationError
+    # ".." traversal marker is rejected; bare "/" stays allowed per the v0.4.0
+    # contract (test_validate_identifier_accepts_reasonable covers "with/slash").
+    for bad in ("../../etc/passwd", "..\\..\\windows", "foo/..", ".."):
+        with pytest.raises(ValidationError, match="forbidden path sequence"):
+            validate_identifier(bad, field_name="name")
+
+
+def test_validate_identifier_rejects_sql_and_shell_metacharacters():
+    from sibyl_memory_client.client import validate_identifier
+    from sibyl_memory_client.exceptions import ValidationError
+    # KAPPA's SQL-keyword shape ("'; DROP TABLE entities;--") is caught by ';'
+    for bad in ("'; DROP TABLE entities;--", "a;b", 'a"b', "a`b", "a|b", "a<b", "a>b"):
+        with pytest.raises(ValidationError, match="forbidden character"):
+            validate_identifier(bad, field_name="name")
+
+
+def test_validate_identifier_allows_apostrophe_and_normal_names():
+    """Apostrophe is deliberately allowed so name-shaped keys survive; plain
+    identifiers, dashes, underscores, dots-without-traversal pass."""
+    from sibyl_memory_client.client import validate_identifier
+    for ok in ("o'brien", "acme-deal", "alice", "project_atlas", "v0.4.4", "L-S-ratio"):
+        assert validate_identifier(ok, field_name="name") == ok
+
+
+# ----------------------------------------------------------------------
+# v0.4.4: FTS5 operator-keyword drop
+# (chainriffs Discord + KAPPA #4 — uppercase AND/OR/NOT/NEAR became required
+# literal tokens, silently collapsing recall to ~0 hits)
+# ----------------------------------------------------------------------
+
+def test_sanitizer_drops_operator_keywords_default_mode():
+    from sibyl_memory_client.client import _sanitize_fts5_query
+    # operator words must NOT survive as quoted literal tokens
+    assert _sanitize_fts5_query("auth AND db") == '"auth" "db"'
+    assert _sanitize_fts5_query("cache NEAR eviction") == '"cache" "eviction"'
+    assert _sanitize_fts5_query("foo OR bar NOT baz") == '"foo" "bar" "baz"'
+
+
+def test_sanitizer_keeps_operator_only_query_as_literal():
+    """If the query is ONLY operator keywords, keep them so a genuine search
+    for the literal word 'and' still resolves (no empty-query surprise)."""
+    from sibyl_memory_client.client import _sanitize_fts5_query
+    assert _sanitize_fts5_query("AND") == '"AND"'
+    assert _sanitize_fts5_query("AND OR NOT") == '"AND" "OR" "NOT"'
+
+
+def test_search_with_operator_words_returns_hits_end_to_end(tmp_path):
+    """The actual reported failure: a natural-language query containing an
+    uppercase operator word used to return 0 hits. It must now match."""
+    from sibyl_memory_client import MemoryClient
+    client = MemoryClient.local(tmp_path / "memory.db")
+    client.set_entity("debug", "authnote",
+                      {"text": "auth uses JWT and a db connection for cache eviction"})
+    # Pre-fix: "AND"/"NEAR" became required literal tokens -> 0 hits.
+    assert len(client.search("auth AND db")) >= 1
+    assert len(client.search("cache NEAR eviction")) >= 1
+    assert len(client.search_entities("auth AND db")) >= 1

sibyl-memory-mcp/CHANGELOG.md

@@ -4,6 +4,29 @@ All notable changes to `sibyl-memory-mcp` are recorded here. Format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Versioning follows
 [SemVer](https://semver.org/).
 
+## [0.1.3] - 2026-05-28
+
+Beta-tester bug-report remediation (sylvain1550 Discord + QA note).
+
+### Fixed
+
+- **First-use writes failed with an opaque `SQLite IntegrityError`
+  pre-activation.** With no `credentials.json`, `_build_client()` passed
+  `tenant_id=None` *explicitly*, overriding the SDK's `DEFAULT_TENANT`
+  default. Every write then violated the `entities.tenant_id NOT NULL`
+  constraint while reads + tool discovery still worked — so a broken
+  install looked healthy. Now falls back to `DEFAULT_TENANT`, matching
+  `sibyl-memory-hermes`' provider behavior. Free local pre-activation
+  writes succeed. (Regression test: `tests/test_first_use_tenant.py`.)
+- **`__version__` drift.** The hardcoded `"0.1.0"` had drifted from the
+  `0.1.2` published wheel. Now single-sourced from installed metadata via
+  `importlib.metadata` (mirrors `sibyl-memory-client`), so it can never
+  drift again.
+
+### Changed
+
+- Pin bumped to `sibyl-memory-client>=0.4.4` (FTS5 + identifier fixes).
+
 ## [0.1.2] - 2026-05-18
 
 KAPPA external-tester remediation release. v0.1.1 was functionally broken

sibyl-memory-mcp/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "sibyl-memory-mcp"
-version = "0.1.2"
+version = "0.1.3"
 description = "MCP server for Sibyl Memory Plugin: wraps the local SQLite + FTS5 memory engine and exposes it to MCP-compatible agents (Claude Code, Codex, Cursor, Continue, anything that speaks MCP)."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -23,7 +23,7 @@ classifiers = [
 ]
 dependencies = [
     "mcp>=1.0.0",
-    "sibyl-memory-client>=0.4.0",
+    "sibyl-memory-client>=0.4.4",
     "sibyl-memory-hermes>=0.3.2",
 ]
 

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

@@ -24,5 +24,14 @@ memory.db exist at ~/.sibyl-memory/.
 
 from .server import build_server, run_stdio
 
-__version__ = "0.1.0"
+# Single-sourced from installed metadata so the wheel + code never drift
+# (v0.1.3: the hardcoded "0.1.0" had drifted from the 0.1.2 published wheel;
+# mirrors sibyl-memory-client's dynamic-version pattern). Source-tree fallback
+# for editable installs that haven't been pip-installed yet.
+from importlib.metadata import PackageNotFoundError, version as _pkg_version
+try:
+    __version__ = _pkg_version("sibyl-memory-mcp")
+except PackageNotFoundError:  # pragma: no cover - source-tree dev only
+    __version__ = "0.0.0+source"
+
 __all__ = ["build_server", "run_stdio", "__version__"]

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

@@ -37,7 +37,7 @@ from pathlib import Path
 from typing import Any
 
 from mcp.server.fastmcp import FastMCP
-from sibyl_memory_client import MemoryClient
+from sibyl_memory_client import DEFAULT_TENANT, MemoryClient
 from sibyl_memory_client.exceptions import (
     CapExceededError,
     NotFoundError,
@@ -129,12 +129,22 @@ def _open_client() -> MemoryClient:
 
 
 def _build_client() -> MemoryClient:
-    """Construct a fresh MemoryClient. Called only on cache miss."""
+    """Construct a fresh MemoryClient. Called only on cache miss.
+
+    v0.1.3 (sylvain1550 / KAPPA first-use bug): when credentials.json is
+    absent, ``creds`` is ``{}`` and ``creds.get("tenant_id")`` is ``None``.
+    Passing ``tenant_id=None`` *explicitly* overrode the SDK's DEFAULT_TENANT
+    default, so every write hit the ``entities.tenant_id NOT NULL`` constraint
+    and failed with an opaque ``SQLite error: IntegrityError`` -- while reads
+    and tool discovery still worked, making a broken install look healthy.
+    Fall back to DEFAULT_TENANT so pre-activation free local mode writes
+    succeed, matching sibyl-memory-hermes' provider behavior.
+    """
     creds = _load_credentials()
     DEFAULT_DB_PATH.parent.mkdir(parents=True, exist_ok=True)
     return MemoryClient.local(
         str(DEFAULT_DB_PATH),
-        tenant_id=creds.get("tenant_id"),
+        tenant_id=creds.get("tenant_id") or DEFAULT_TENANT,
         account_id=creds.get("account_id"),
         session_token=creds.get("session_token"),
         tier=creds.get("tier", "free"),

sibyl-memory-mcp/tests/test_first_use_tenant.py

@@ -0,0 +1,61 @@
+"""Regression test for the v0.1.3 first-use write bug.
+
+Bug (sylvain1550 Discord report 2026-05-27 + QA note run-2026-05-28-mcp-run05;
+related to KAPPA's coordination thread): with no credentials.json present,
+`_build_client()` passed `tenant_id=creds.get("tenant_id")` == None EXPLICITLY,
+overriding MemoryClient.local's DEFAULT_TENANT default. Every write then hit the
+`entities.tenant_id NOT NULL` constraint and failed with an opaque
+`SQLite error: IntegrityError`, while reads + tool discovery still worked -- so a
+broken install looked healthy.
+
+Fix: `tenant_id=creds.get("tenant_id") or DEFAULT_TENANT`. This test fails on the
+pre-fix code (IntegrityError) and passes after.
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+# Make both packages importable from a source checkout.
+_HERE = Path(__file__).resolve()
+sys.path.insert(0, str(_HERE.parent.parent / "src"))
+sys.path.insert(0, str(_HERE.parent.parent.parent / "sibyl-memory-client" / "src"))
+
+
+def test_build_client_writes_succeed_without_credentials(tmp_path, monkeypatch):
+    import sibyl_memory_mcp.server as server
+    from sibyl_memory_client import DEFAULT_TENANT
+
+    monkeypatch.setattr(server, "DEFAULT_DB_PATH", tmp_path / "memory.db")
+    monkeypatch.setattr(server, "DEFAULT_CRED_PATH", tmp_path / "credentials.json")
+    # credentials.json deliberately absent -> pre-activation free local mode.
+    assert not (tmp_path / "credentials.json").exists()
+
+    client = server._build_client()
+    assert client is not None
+
+    # THE regression: this write raised StorageError(IntegrityError) before the fix.
+    client.set_entity("debug", "first-use", {"text": "pre-activation write probe"})
+
+    # And it must be retrievable, proving the row actually landed under a tenant.
+    hits = client.search_entities("probe")
+    assert len(hits) >= 1
+    assert hits[0]["tenant_id"] == DEFAULT_TENANT
+
+
+def test_build_client_honors_real_tenant_when_present(tmp_path, monkeypatch):
+    """When credentials DO carry a tenant_id, it is still used (no regression)."""
+    import json
+    import sibyl_memory_mcp.server as server
+
+    cred = tmp_path / "credentials.json"
+    real_tenant = "11111111-1111-1111-1111-111111111111"
+    cred.write_text(json.dumps({"tenant_id": real_tenant, "account_id": "acct", "tier": "free"}))
+    monkeypatch.setattr(server, "DEFAULT_DB_PATH", tmp_path / "memory.db")
+    monkeypatch.setattr(server, "DEFAULT_CRED_PATH", cred)
+
+    client = server._build_client()
+    client.set_entity("debug", "scoped", {"text": "scoped write probe"})
+    hits = client.search_entities("scoped")
+    assert len(hits) >= 1
+    assert hits[0]["tenant_id"] == real_tenant