citadeldb-google-adk 2.0.0__tar.gz

citadeldb_google_adk-2.0.0/.gitignore

@@ -0,0 +1,18 @@
+/target
+**/*.rs.bk
+*.swp
+*.swo
+*~
+.DS_Store
+site/public/
+site/static/wasm/*.wasm
+site/static/wasm/*.js
+/notes/
+__pycache__/
+*.py[cod]
+# maturin build output; the .pyd is caught by the line above only by accident.
+*.pdb
+.pytest_cache/
+.mypy_cache/
+/dist/
+packaging/*/dist/

citadeldb_google_adk-2.0.0/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.5
+Name: citadeldb-google-adk
+Version: 2.0.0
+Summary: Google ADK memory backed by Citadel: encrypted at rest, with deletes that destroy the key
+Project-URL: Homepage, https://citadeldb.dev
+Project-URL: Repository, https://github.com/yp3y5akh0v/citadel
+Author: Yuriy Peysakhov
+License-Expression: Apache-2.0
+Keywords: adk,agent,agents,encryption,google-adk,memory
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Database
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: citadeldb<3,>=2.0
+Requires-Dist: google-adk<3,>=2.0
+Provides-Extra: test
+Requires-Dist: pytest-asyncio>=0.23; extra == 'test'
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# citadeldb-google-adk
+
+A [Google ADK](https://github.com/google/adk-python) `BaseMemoryService` backed by
+[Citadel](https://citadeldb.dev). Encrypted at rest, embedded in your process, and deletes
+that destroy the key, not just the row.
+
+```
+pip install citadeldb-google-adk
+```
+
+```python
+from google.adk.runners import Runner
+from citadeldb_google_adk import CitadelMemoryService
+
+memory = CitadelMemoryService("adk_memory.cdl", key="your-passphrase")
+
+runner = Runner(
+    app_name="my_app",
+    agent=agent,                       # your root agent
+    session_service=session_service,   # your session service
+    memory_service=memory,
+)
+```
+
+## Search is ranked recall, not word matching
+
+ADK hands the service a query string, so Citadel embeds it and runs hybrid recall: vector
+distance, keyword rank and recency, fused into one score. The reference
+`InMemoryMemoryService` returns only turns sharing a word with the query; nothing here is
+dropped for lacking one. With the default `MockEmbedder` that ranking is still lexical:
+
+```python
+await memory.add_session_to_memory(session)   # a Session your Runner already ran
+
+await memory.search_memory(app_name="my_app", user_id="alice",
+                           query="why did the release break?")
+# SearchMemoryResponse(memories=[MemoryEntry(...disk was full...)])
+```
+
+## Deletes destroy the key
+
+Every event is sealed under its own key. Erasing destroys those keys, so the bytes on disk
+stay unreadable. A backup taken before the delete carries its own copy of the wrapped key
+and is out of scope.
+
+```python
+memory.forget_user("my_app", "alice")               # returns the number erased
+memory.forget_session("my_app", "alice", "s-42")
+```
+
+ADK's own memory services expose no erasure method.
+
+## Direct writes are supported
+
+`add_memory` writes memories without going through a session. The reference
+`InMemoryMemoryService` raises `NotImplementedError` for it.
+
+```python
+from google.adk.memory.memory_entry import MemoryEntry
+from google.genai import types
+
+entry = MemoryEntry(content=types.Content(parts=[types.Part(text="prefers dark mode")]))
+await memory.add_memory(app_name="my_app", user_id="alice", memories=[entry])
+```
+
+`add_events_to_memory` likewise persists the events you pass rather than a whole session.
+
+## Notes
+
+`add_session_to_memory` sets the session's events, as `InMemoryMemoryService` does:
+re-adding never duplicates rows, and an event dropped from the session is dropped from
+memory. `add_events_to_memory` is the additive one, skipping ids already stored.
+
+Citadel is embedded and one process owns the file. A path already open on this thread,
+under the same passphrase, is shared, so this can sit on the same database as another
+Citadel adapter; construct them on the same thread.
+
+`MockEmbedder` is the default and needs no download, which is enough to run an agent and to
+test. For semantic recall pass a real embedder. `CandleEmbedder` is not in the default
+`citadeldb` wheel and needs a source build (`maturin build --features candle-embed`); any
+object exposing `dim`, `metric`, `model_id`, `embed` and `embed_queries` works too:
+
+```python
+import citadeldb
+memory = CitadelMemoryService(
+    "adk_memory.cdl",
+    key="your-passphrase",
+    embedder=citadeldb.CandleEmbedder("/path/to/e5-large", preset="e5-large"),
+)
+```
+
+## License
+
+Apache-2.0

citadeldb_google_adk-2.0.0/README.md

@@ -0,0 +1,94 @@
+# citadeldb-google-adk
+
+A [Google ADK](https://github.com/google/adk-python) `BaseMemoryService` backed by
+[Citadel](https://citadeldb.dev). Encrypted at rest, embedded in your process, and deletes
+that destroy the key, not just the row.
+
+```
+pip install citadeldb-google-adk
+```
+
+```python
+from google.adk.runners import Runner
+from citadeldb_google_adk import CitadelMemoryService
+
+memory = CitadelMemoryService("adk_memory.cdl", key="your-passphrase")
+
+runner = Runner(
+    app_name="my_app",
+    agent=agent,                       # your root agent
+    session_service=session_service,   # your session service
+    memory_service=memory,
+)
+```
+
+## Search is ranked recall, not word matching
+
+ADK hands the service a query string, so Citadel embeds it and runs hybrid recall: vector
+distance, keyword rank and recency, fused into one score. The reference
+`InMemoryMemoryService` returns only turns sharing a word with the query; nothing here is
+dropped for lacking one. With the default `MockEmbedder` that ranking is still lexical:
+
+```python
+await memory.add_session_to_memory(session)   # a Session your Runner already ran
+
+await memory.search_memory(app_name="my_app", user_id="alice",
+                           query="why did the release break?")
+# SearchMemoryResponse(memories=[MemoryEntry(...disk was full...)])
+```
+
+## Deletes destroy the key
+
+Every event is sealed under its own key. Erasing destroys those keys, so the bytes on disk
+stay unreadable. A backup taken before the delete carries its own copy of the wrapped key
+and is out of scope.
+
+```python
+memory.forget_user("my_app", "alice")               # returns the number erased
+memory.forget_session("my_app", "alice", "s-42")
+```
+
+ADK's own memory services expose no erasure method.
+
+## Direct writes are supported
+
+`add_memory` writes memories without going through a session. The reference
+`InMemoryMemoryService` raises `NotImplementedError` for it.
+
+```python
+from google.adk.memory.memory_entry import MemoryEntry
+from google.genai import types
+
+entry = MemoryEntry(content=types.Content(parts=[types.Part(text="prefers dark mode")]))
+await memory.add_memory(app_name="my_app", user_id="alice", memories=[entry])
+```
+
+`add_events_to_memory` likewise persists the events you pass rather than a whole session.
+
+## Notes
+
+`add_session_to_memory` sets the session's events, as `InMemoryMemoryService` does:
+re-adding never duplicates rows, and an event dropped from the session is dropped from
+memory. `add_events_to_memory` is the additive one, skipping ids already stored.
+
+Citadel is embedded and one process owns the file. A path already open on this thread,
+under the same passphrase, is shared, so this can sit on the same database as another
+Citadel adapter; construct them on the same thread.
+
+`MockEmbedder` is the default and needs no download, which is enough to run an agent and to
+test. For semantic recall pass a real embedder. `CandleEmbedder` is not in the default
+`citadeldb` wheel and needs a source build (`maturin build --features candle-embed`); any
+object exposing `dim`, `metric`, `model_id`, `embed` and `embed_queries` works too:
+
+```python
+import citadeldb
+memory = CitadelMemoryService(
+    "adk_memory.cdl",
+    key="your-passphrase",
+    embedder=citadeldb.CandleEmbedder("/path/to/e5-large", preset="e5-large"),
+)
+```
+
+## License
+
+Apache-2.0

citadeldb_google_adk-2.0.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[project]
+name = "citadeldb-google-adk"
+dynamic = ["version"]
+description = "Google ADK memory backed by Citadel: encrypted at rest, with deletes that destroy the key"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "Apache-2.0"
+authors = [{ name = "Yuriy Peysakhov" }]
+keywords = ["google-adk", "adk", "agents", "memory", "agent", "encryption"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Topic :: Database",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+# An event replaces under its own id, which needs the keyed write added in 2.0.
+dependencies = ["citadeldb>=2.0,<3", "google-adk>=2.0,<3"]
+
+[project.optional-dependencies]
+test = ["pytest>=8", "pytest-asyncio>=0.23"]
+
+[project.urls]
+Homepage = "https://citadeldb.dev"
+Repository = "https://github.com/yp3y5akh0v/citadel"
+
+# The version comes from the release tag, so there is nothing to bump.
+[tool.hatch.version]
+source = "vcs"
+raw-options = { root = "../..", tag_regex = '^v(?P<version>\d+\.\d+\.\d+)$' }
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/citadeldb_google_adk"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"

citadeldb_google_adk-2.0.0/src/citadeldb_google_adk/__init__.py

@@ -0,0 +1,13 @@
+"""Google ADK memory backed by Citadel, encrypted at rest."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from .memory import CitadelMemoryService
+
+__all__ = ["CitadelMemoryService", "__version__"]
+
+
+try:
+    __version__ = version("citadeldb-google-adk")
+except PackageNotFoundError:  # running from a source tree, never installed
+    __version__ = "0+unknown"

citadeldb_google_adk-2.0.0/src/citadeldb_google_adk/memory.py

@@ -0,0 +1,330 @@
+"""Google ADK memory service over an encrypted Citadel region."""
+from __future__ import annotations
+
+import asyncio
+import functools
+from collections.abc import Mapping, Sequence
+from datetime import datetime
+from typing import TYPE_CHECKING, Any
+
+import citadeldb
+from google.adk.memory.base_memory_service import BaseMemoryService, SearchMemoryResponse
+from google.adk.memory.memory_entry import MemoryEntry
+from google.genai import types
+
+if TYPE_CHECKING:
+    from google.adk.events.event import Event
+    from google.adk.sessions.session import Session
+
+KIND = "event"
+DEFAULT_PATH = "adk_memory.cdl"
+DEFAULT_REGION = "adk_memory"
+# A scope is read whole and filtered in Python; recall over-fetches too.
+PAGE = 10_000
+# `search_memory` takes no limit, so the service owns one; raise it on the constructor.
+DEFAULT_SEARCH_LIMIT = 64
+
+
+def _page(mem: Any, region: str, criterion: dict[str, Any] | None = None) -> list[Any]:
+    """Page to the end: one fetch is bounded, and a partial erase must not look whole."""
+    out: list[Any] = []
+    after = None
+    while True:
+        got = mem.fetch(region, KIND, payload_filter=criterion, limit=PAGE, after_id=after)
+        out.extend(got)
+        if len(got) < PAGE:
+            return out
+        after = got[-1].id
+# ADK partitions memory by (app_name, user_id); nothing crosses that boundary.
+_UNKNOWN_SESSION = "__unknown_session_id__"
+
+
+def _text_of(content: types.Content | None) -> str:
+    """The searchable text of an event, which is what Citadel embeds."""
+    if content is None or not content.parts:
+        return ""
+    return " ".join(p.text for p in content.parts if getattr(p, "text", None))
+
+
+def _stamp(timestamp: float | None) -> str | None:
+    """ADK formats memory timestamps as local-time ISO 8601, so match it."""
+    return datetime.fromtimestamp(timestamp).isoformat() if timestamp else None
+
+
+def _scope(app_name: str, user_id: str) -> dict[str, str]:
+    return {"app": app_name, "user": user_id}
+
+
+# A Database is pinned to its opening thread, so workers take Memory, not self.
+
+
+def _memory_key(*parts: str) -> str:
+    """One engine key from several names, length-prefixed so that no two name
+    tuples can spell the same key."""
+    return "".join(f"{len(p)}\x1f{p}" for p in parts)
+
+
+def _write_events(
+    mem: Any,
+    region: str,
+    app_name: str,
+    user_id: str,
+    session_id: str,
+    events: Sequence[Event],
+    custom_metadata: Mapping[str, object] | None,
+    *,
+    replace_session: bool = False,
+) -> None:
+    scope = _scope(app_name, user_id)
+    # Read before the write, so the erase below cannot take a row this call just
+    # made. Rows superseded by the keyed write are already gone by then, and
+    # forgetting an id twice is a no-op.
+    prior = (
+        _page(mem, region, scope | {"sid": session_id}) if replace_session else []
+    )
+    keyed: dict[str, dict[str, Any]] = {}
+    anonymous: list[dict[str, Any]] = []
+    for event in events:
+        if not event.content or not event.content.parts:
+            continue  # the reference skips contentless events
+        text = _text_of(event.content)
+        if not text:
+            continue  # nothing to embed, so nothing recall could ever return
+        atom = {
+            "kind": KIND,
+            "text": text,
+            "payload": {
+                **scope,
+                "sid": session_id,
+                "eid": event.id,
+                "author": event.author,
+                "ts": _stamp(event.timestamp),
+                # Stored whole so a memory hands back the content ADK gave us.
+                "content": event.content.model_dump(mode="json", exclude_none=True),
+                "meta": dict(custom_metadata) if custom_metadata else {},
+            },
+        }
+        if event.id:
+            # The first copy of an id in one call stands, as it did when a read
+            # of the stored ids decided this.
+            keyed.setdefault(_memory_key(app_name, user_id, session_id, event.id), atom)
+        else:
+            anonymous.append(atom)  # no stable name to key on
+    if keyed:
+        # Keyed, so re-ingesting a session converges on the stored events instead
+        # of duplicating them, and two concurrent ingests of one event cannot
+        # both observe it absent and both write it.
+        mem.remember_replacing_keyed_batch(
+            region, [(atom, k) for k, atom in keyed.items()]
+        )
+    if anonymous:
+        mem.remember_batch(region, anonymous)
+    if replace_session:
+        # add_session_to_memory SETS the session's events rather than merging
+        # them, so an event dropped from the session is dropped from memory too.
+        # add_events_to_memory is the additive one and leaves this alone.
+        written = {atom["payload"]["eid"] for atom in keyed.values()}
+        stale = [h for h in prior if h.payload.get("eid") not in written]
+        if stale:
+            mem.forget(region, [h.id for h in stale])
+
+
+def _write_memories(
+    mem: Any,
+    region: str,
+    app_name: str,
+    user_id: str,
+    memories: Sequence[MemoryEntry],
+    custom_metadata: Mapping[str, object] | None,
+) -> None:
+    scope = _scope(app_name, user_id)
+    # An id replaces rather than skips: ignoring an update is a silent no-op.
+    keyed: dict[str, dict[str, Any]] = {}
+    anonymous: list[dict[str, Any]] = []
+    for m in memories:
+        text = _text_of(m.content)
+        if not text:
+            continue
+        meta = dict(m.custom_metadata)
+        if custom_metadata:
+            meta.update(custom_metadata)
+        atom = {
+            "kind": KIND,
+            "text": text,
+            "payload": {
+                **scope,
+                "sid": _UNKNOWN_SESSION,
+                "eid": m.id,
+                "author": m.author,
+                "ts": m.timestamp,
+                "content": m.content.model_dump(mode="json", exclude_none=True),
+                "meta": meta,
+            },
+        }
+        if m.id:
+            keyed[m.id] = atom
+        else:
+            anonymous.append(atom)  # no identity to replace, so it is always new
+    if keyed:
+        # Keyed, so an id replaces in one transaction. Two concurrent adds of one
+        # id supersede rather than both landing, which the read-then-write-then-
+        # erase this replaces could not prevent.
+        mem.remember_replacing_keyed_batch(
+            region,
+            [(atom, _memory_key(app_name, user_id, eid)) for eid, atom in keyed.items()],
+        )
+    if anonymous:
+        mem.remember_batch(region, anonymous)
+
+
+def _entry(hit) -> MemoryEntry:
+    p = hit.payload
+    return MemoryEntry(
+        content=types.Content.model_validate(p["content"]),
+        custom_metadata=p.get("meta") or {},
+        id=p.get("eid"),
+        author=p.get("author"),
+        timestamp=p.get("ts"),
+    )
+
+
+def _search(
+    mem: Any, region: str, app_name: str, user_id: str, query: str, limit: int
+) -> SearchMemoryResponse:
+    hits = mem.recall(
+        region,
+        text=query,
+        k=limit,
+        kinds=[KIND],
+        options=citadeldb.RecallOptions(payload_filter=_scope(app_name, user_id)),
+    )
+    return SearchMemoryResponse(memories=[_entry(h) for h in hits])
+
+
+class CitadelMemoryService(BaseMemoryService):
+    """An ADK `BaseMemoryService` backed by one encrypted Citadel region."""
+
+    def __init__(
+        self,
+        path: str = DEFAULT_PATH,
+        key: str = "",
+        *,
+        region: str = DEFAULT_REGION,
+        embedder: Any | None = None,
+        search_limit: int = DEFAULT_SEARCH_LIMIT,
+    ) -> None:
+        if not key:
+            raise ValueError("a passphrase is required: conversations are the payload")
+        self._search_limit = search_limit
+        try:
+            self._db = citadeldb.connect(path, key=key, region_keys=True)
+        except citadeldb.OperationalError as e:
+            if "locked" not in str(e):
+                raise
+            raise RuntimeError(
+                f"{path} is open in another process. Citadel is embedded, so one "
+                f"process owns the file."
+            ) from e
+        self._mem = self._db.memory()
+        self._region = region
+        # Idempotent for a region of the same width, so a dim clash raises here.
+        self._mem.create_encrypted_region(
+            region, embedder or citadeldb.MockEmbedder(dim=64)
+        )
+
+    # ---- storage helpers --------------------------------------------------
+
+    def _owned(self, app_name: str, user_id: str) -> list[Any]:
+        """Every atom for one (app, user). Served by the payload index."""
+        return _page(self._mem, self._region, _scope(app_name, user_id))
+
+    # ---- the abstract surface --------------------------------------------
+
+    async def add_session_to_memory(self, session: Session) -> None:
+        await asyncio.to_thread(
+            functools.partial(
+                _write_events,
+                self._mem,
+                self._region,
+                session.app_name,
+                session.user_id,
+                session.id,
+                session.events,
+                None,
+                replace_session=True,
+            )
+        )
+
+    async def search_memory(
+        self, *, app_name: str, user_id: str, query: str
+    ) -> SearchMemoryResponse:
+        return await asyncio.to_thread(
+            _search,
+            self._mem,
+            self._region,
+            app_name,
+            user_id,
+            query,
+            self._search_limit,
+        )
+
+    # ---- optional surface the reference refuses ---------------------------
+
+    async def add_events_to_memory(
+        self,
+        *,
+        app_name: str,
+        user_id: str,
+        events: Sequence[Event],
+        session_id: str | None = None,
+        custom_metadata: Mapping[str, object] | None = None,
+    ) -> None:
+        await asyncio.to_thread(
+            _write_events,
+            self._mem,
+            self._region,
+            app_name,
+            user_id,
+            session_id or _UNKNOWN_SESSION,
+            events,
+            custom_metadata,
+        )
+
+    async def add_memory(
+        self,
+        *,
+        app_name: str,
+        user_id: str,
+        memories: Sequence[MemoryEntry],
+        custom_metadata: Mapping[str, object] | None = None,
+    ) -> None:
+        """Write memories directly, without a session."""
+        await asyncio.to_thread(
+            _write_memories,
+            self._mem,
+            self._region,
+            app_name,
+            user_id,
+            memories,
+            custom_metadata,
+        )
+
+    # ---- beyond the protocol ----------------------------------------------
+
+    def forget_user(self, app_name: str, user_id: str) -> int:
+        """Destroy everything one user owns, returning the number erased."""
+        doomed = self._owned(app_name, user_id)
+        if not doomed:
+            return 0
+        return self._mem.forget(self._region, [h.id for h in doomed]).erased_count
+
+    def forget_session(self, app_name: str, user_id: str, session_id: str) -> int:
+        """The same for one session of one user."""
+        scope = _scope(app_name, user_id) | {"sid": session_id}
+        doomed = _page(self._mem, self._region, scope)
+        if not doomed:
+            return 0
+        return self._mem.forget(self._region, [h.id for h in doomed]).erased_count
+
+    def count(self, app_name: str, user_id: str) -> int:
+        return len(self._owned(app_name, user_id))

citadeldb_google_adk-2.0.0/tests/test_memory.py

@@ -0,0 +1,380 @@
+import pytest
+from google.adk.events.event import Event
+from google.adk.memory.base_memory_service import BaseMemoryService
+from google.adk.memory.memory_entry import MemoryEntry
+from google.adk.sessions.session import Session
+from google.genai import types
+
+from citadeldb_google_adk import CitadelMemoryService
+
+APP = "app"
+USER = "user-1"
+
+
+@pytest.fixture(scope="module")
+def svc(tmp_path_factory):
+    # Citadel takes an exclusive lock, so the whole module shares one handle.
+    path = tmp_path_factory.mktemp("adk") / "m.cdl"
+    return CitadelMemoryService(str(path), key="test-passphrase")
+
+
+def ev(text, *, author="user", eid=None, ts=1.0):
+    return Event(
+        id=eid or f"e-{text[:8]}-{ts}",
+        author=author,
+        timestamp=ts,
+        content=types.Content(role=author, parts=[types.Part(text=text)]),
+    )
+
+
+def sess(sid, events, *, app=APP, user=USER):
+    return Session(id=sid, app_name=app, user_id=user, events=events)
+
+
+# ---- protocol conformance ------------------------------------------------
+
+
+def test_is_a_memory_service(svc):
+    assert isinstance(svc, BaseMemoryService)
+
+
+# ---- ingest --------------------------------------------------------------
+
+
+async def test_a_session_becomes_searchable(svc):
+    await svc.add_session_to_memory(
+        sess("s1", [ev("the deployment failed because the disk was full")])
+    )
+    found = await svc.search_memory(app_name=APP, user_id=USER, query="disk was full")
+    assert found.memories
+    assert "disk was full" in found.memories[0].content.parts[0].text
+
+
+async def test_search_is_semantic_not_word_overlap(svc):
+    """The reference service matches shared words; recall shares none here."""
+    await svc.add_session_to_memory(
+        sess("sem", [ev("the deployment failed because the disk was full")])
+    )
+    found = await svc.search_memory(
+        app_name=APP, user_id=USER, query="why did the release break?"
+    )
+    assert found.memories, "hybrid recall returned nothing"
+
+
+async def test_contentless_events_are_skipped(svc):
+    empty = Event(id="empty", author="user", timestamp=1.0, content=None)
+    await svc.add_session_to_memory(sess("skip", [empty]))
+    assert svc.count(APP, USER) == svc.count(APP, USER)  # no crash, nothing stored
+
+
+async def test_re_adding_a_session_does_not_duplicate(svc):
+    """ADK says a session may be added many times, so ingest must be a delta."""
+    s = sess("dup", [ev("only once", eid="fixed-1")])
+    await svc.add_session_to_memory(s)
+    before = svc.count(APP, USER)
+    await svc.add_session_to_memory(s)
+    assert svc.count(APP, USER) == before
+
+
+async def test_a_growing_session_adds_only_the_new_events(svc):
+    first = ev("turn one", eid="g-1")
+    s = sess("grow", [first])
+    await svc.add_session_to_memory(s)
+    before = svc.count(APP, USER)
+    s.events.append(ev("turn two", eid="g-2"))
+    await svc.add_session_to_memory(s)
+    assert svc.count(APP, USER) == before + 1
+
+
+# ---- scope ---------------------------------------------------------------
+
+
+async def test_users_do_not_see_each_other(svc):
+    await svc.add_session_to_memory(sess("u1", [ev("mine alone")], user="alice"))
+    await svc.add_session_to_memory(sess("u2", [ev("yours alone")], user="bob"))
+    alice = await svc.search_memory(app_name=APP, user_id="alice", query="alone")
+    texts = [m.content.parts[0].text for m in alice.memories]
+    assert "mine alone" in texts and "yours alone" not in texts
+
+
+async def test_apps_do_not_see_each_other(svc):
+    await svc.add_session_to_memory(sess("a1", [ev("app one secret")], app="one"))
+    found = await svc.search_memory(app_name="two", user_id=USER, query="secret")
+    assert [m for m in found.memories if "app one" in m.content.parts[0].text] == []
+
+
+# ---- projection ----------------------------------------------------------
+
+
+async def test_memory_entry_carries_author_and_timestamp(svc):
+    await svc.add_session_to_memory(
+        sess("meta", [ev("stamped", author="assistant", eid="m-1", ts=1700000000.0)])
+    )
+    found = await svc.search_memory(app_name=APP, user_id=USER, query="stamped")
+    entry = next(m for m in found.memories if m.id == "m-1")
+    assert entry.author == "assistant"
+    assert entry.timestamp and entry.timestamp.startswith("20")
+
+
+async def test_non_text_parts_round_trip_verbatim(svc):
+    """Content is a union owned by google.genai; nothing may normalise it."""
+    content = types.Content(
+        role="model",
+        parts=[
+            types.Part(text="looking that up"),
+            types.Part(
+                function_call=types.FunctionCall(name="lookup", args={"q": "berlin"})
+            ),
+        ],
+    )
+    e = Event(id="fc-1", author="model", timestamp=3.0, content=content)
+    await svc.add_session_to_memory(sess("fc", [e]))
+    found = await svc.search_memory(app_name=APP, user_id=USER, query="looking that up")
+    entry = next(m for m in found.memories if m.id == "fc-1")
+    call = entry.content.parts[1].function_call
+    assert call.name == "lookup"
+    assert call.args == {"q": "berlin"}
+
+
+async def test_an_event_with_no_text_at_all_is_skipped(svc):
+    """Nothing to embed means recall could never return it."""
+    only_call = types.Content(
+        role="model",
+        parts=[types.Part(function_call=types.FunctionCall(name="noop", args={}))],
+    )
+    e = Event(id="silent", author="model", timestamp=4.0, content=only_call)
+    before = svc.count(APP, USER)
+    await svc.add_session_to_memory(sess("silent", [e]))
+    assert svc.count(APP, USER) == before
+
+
+async def test_search_for_an_unknown_user_is_empty(svc):
+    found = await svc.search_memory(app_name=APP, user_id="nobody", query="anything")
+    assert found.memories == []
+
+
+async def test_search_on_an_empty_service_is_empty(tmp_path):
+    fresh = CitadelMemoryService(str(tmp_path / "empty.cdl"), key="pw")
+    found = await fresh.search_memory(app_name=APP, user_id=USER, query="anything")
+    assert found.memories == []
+
+
+async def test_the_event_loop_is_not_blocked(svc):
+    """ADK's Runner is async, so the sync bindings must run off the loop."""
+    import asyncio
+
+    ticks = 0
+
+    async def tick():
+        nonlocal ticks
+        while True:
+            ticks += 1
+            await asyncio.sleep(0)
+
+    ticker = asyncio.create_task(tick())
+    await asyncio.sleep(0)
+    await svc.add_session_to_memory(
+        sess("loop", [ev(f"loop turn {n}", eid=f"l-{n}") for n in range(40)])
+    )
+    await svc.search_memory(app_name=APP, user_id=USER, query="loop turn")
+    ticker.cancel()
+    assert ticks > 1, "the loop made no progress during a memory call"
+
+
+async def test_multi_part_content_round_trips(svc):
+    """Content is stored whole, so a memory hands back what ADK gave us."""
+    content = types.Content(
+        role="user",
+        parts=[types.Part(text="first part"), types.Part(text="second part")],
+    )
+    e = Event(id="multi", author="user", timestamp=2.0, content=content)
+    await svc.add_session_to_memory(sess("multi", [e]))
+    found = await svc.search_memory(app_name=APP, user_id=USER, query="second part")
+    entry = next(m for m in found.memories if m.id == "multi")
+    assert [p.text for p in entry.content.parts] == ["first part", "second part"]
+
+
+# ---- the surface the reference refuses -----------------------------------
+
+
+async def test_events_can_be_added_without_a_session(svc):
+    await svc.add_events_to_memory(
+        app_name=APP, user_id=USER, events=[ev("delta only", eid="d-1")],
+        session_id="delta", custom_metadata={"source": "webhook"},
+    )
+    found = await svc.search_memory(app_name=APP, user_id=USER, query="delta only")
+    entry = next(m for m in found.memories if m.id == "d-1")
+    assert entry.custom_metadata["source"] == "webhook"
+
+
+async def test_re_adding_a_memory_id_replaces_it(svc):
+    """An id makes a second write a replacement, not a second copy."""
+    def entry(text):
+        return MemoryEntry(
+            content=types.Content(role="user", parts=[types.Part(text=text)]),
+            id="dup-1", author="user",
+        )
+
+    await svc.add_memory(app_name=APP, user_id="dupuser", memories=[entry("first")])
+    await svc.add_memory(app_name=APP, user_id="dupuser", memories=[entry("second")])
+    assert svc.count(APP, "dupuser") == 1
+    found = await svc.search_memory(app_name=APP, user_id="dupuser", query="first second")
+    assert [m.content.parts[0].text for m in found.memories] == ["second"]
+
+
+async def test_duplicate_ids_within_one_call_keep_the_last(svc):
+    def entry(text):
+        return MemoryEntry(
+            content=types.Content(role="user", parts=[types.Part(text=text)]),
+            id="batch-dup", author="user",
+        )
+
+    await svc.add_memory(
+        app_name=APP, user_id="batchuser", memories=[entry("one"), entry("two")]
+    )
+    assert svc.count(APP, "batchuser") == 1
+
+
+async def test_memories_without_an_id_are_always_new(svc):
+    """Nothing identifies them, so they cannot replace anything."""
+    def entry():
+        return MemoryEntry(
+            content=types.Content(role="user", parts=[types.Part(text="anonymous")]),
+            author="user",
+        )
+
+    await svc.add_memory(app_name=APP, user_id="anon", memories=[entry()])
+    await svc.add_memory(app_name=APP, user_id="anon", memories=[entry()])
+    assert svc.count(APP, "anon") == 2
+
+
+async def test_memories_can_be_written_directly(svc):
+    """The reference service raises NotImplementedError here."""
+    m = MemoryEntry(
+        content=types.Content(role="user", parts=[types.Part(text="written directly")]),
+        id="direct-1",
+        author="user",
+    )
+    await svc.add_memory(app_name=APP, user_id=USER, memories=[m])
+    found = await svc.search_memory(app_name=APP, user_id=USER, query="written directly")
+    assert any(x.id == "direct-1" for x in found.memories)
+
+
+# ---- erasure -------------------------------------------------------------
+
+
+async def test_forgetting_a_session_leaves_the_rest(svc):
+    await svc.add_session_to_memory(sess("keep", [ev("keep me", eid="k-1")], user="carol"))
+    await svc.add_session_to_memory(sess("drop", [ev("drop me", eid="k-2")], user="carol"))
+    assert svc.forget_session(APP, "carol", "drop") == 1
+    left = await svc.search_memory(app_name=APP, user_id="carol", query="me")
+    assert [m.id for m in left.memories] == ["k-1"]
+
+
+async def test_forgetting_a_user_erases_everything_they_own(svc):
+    await svc.add_session_to_memory(sess("g1", [ev("gone one")], user="dave"))
+    await svc.add_session_to_memory(sess("g2", [ev("gone two")], user="dave"))
+    assert svc.forget_user(APP, "dave") == 2
+    assert svc.count(APP, "dave") == 0
+
+
+def test_forgetting_nothing_is_zero_not_an_error(svc):
+    assert svc.forget_user(APP, "nobody") == 0
+
+
+async def test_it_survives_a_reopen(tmp_path):
+    """A region's embedder must survive the reopen, not just the events."""
+    import gc
+
+    p = str(tmp_path / "reopen.cdl")
+    first = CitadelMemoryService(p, key="pw")
+    await first.add_session_to_memory(
+        sess("s", [ev("the deployment failed because the disk was full")], user="ru")
+    )
+    del first
+    gc.collect()
+
+    again = CitadelMemoryService(p, key="pw")
+    assert again.count(APP, "ru") == 1
+    found = await again.search_memory(
+        app_name=APP, user_id="ru", query="why did the release break?"
+    )
+    assert found.memories, "recall did not survive the reopen"
+
+
+def test_a_passphrase_is_required(tmp_path):
+    with pytest.raises(ValueError, match="passphrase"):
+        CitadelMemoryService(str(tmp_path / "nokey.cdl"), key="")
+
+
+async def test_concurrent_ingestion_all_lands(tmp_path):
+    """Many in-flight sessions means many threads against one engine."""
+    import asyncio
+
+    svc = CitadelMemoryService(str(tmp_path / "conc.cdl"), key="pw")
+    await asyncio.gather(*(
+        svc.add_session_to_memory(sess(f"s{i}", [ev(f"event {i}")], user="cu"))
+        for i in range(40)
+    ))
+    assert svc.count(APP, "cu") == 40
+
+
+async def test_re_adding_a_session_drops_events_removed_from_it(tmp_path):
+    """add_session_to_memory SETS the session's events; add_events_to_memory is
+    the additive one. Merging on both leaves a retracted turn searchable."""
+    svc = CitadelMemoryService(str(tmp_path / "retract.cdl"), key="pw")
+    keep, retract = ev("keep this"), ev("retract this")
+    await svc.add_session_to_memory(sess("s", [keep, retract], user="ru"))
+    assert svc.count(APP, "ru") == 2
+
+    await svc.add_session_to_memory(sess("s", [keep], user="ru"))
+    assert svc.count(APP, "ru") == 1
+    found = await svc.search_memory(app_name=APP, user_id="ru", query="retract this")
+    texts = [p.text for m in found.memories for p in m.content.parts]
+    assert "retract this" not in texts
+
+    # The additive path still adds rather than replacing.
+    await svc.add_events_to_memory(
+        app_name=APP, user_id="ru", session_id="s", events=[ev("added later")]
+    )
+    assert svc.count(APP, "ru") == 2
+
+
+async def test_concurrent_ingestion_of_one_session_stores_it_once(tmp_path):
+    """Re-ingesting a session converges; racing ingests of it must too, or the
+    same turn comes back from search several times."""
+    import asyncio
+
+    svc = CitadelMemoryService(str(tmp_path / "onesess.cdl"), key="pw")
+    session = sess("s", [ev("the only turn")], user="ru")
+    await asyncio.gather(*(svc.add_session_to_memory(session) for _ in range(8)))
+    assert svc.count(APP, "ru") == 1
+
+    found = await svc.search_memory(app_name=APP, user_id="ru", query="the only turn")
+    assert len(found.memories) == 1
+
+
+async def test_a_wrong_passphrase_cannot_reopen(tmp_path):
+    """Pins the encryption claim rather than inferring it from a reopen."""
+    import gc
+
+    import citadeldb
+
+    p = str(tmp_path / "enc.cdl")
+    first = CitadelMemoryService(p, key="right")
+    await first.add_session_to_memory(sess("s", [ev("secret")], user="ru"))
+    del first
+    gc.collect()
+
+    with pytest.raises(citadeldb.EncryptionError):
+        CitadelMemoryService(p, key="wrong")
+
+
+async def test_shares_one_database_with_another_adapter(tmp_path):
+    """Two Citadel-backed services on one file must not fight over the lock."""
+    path = str(tmp_path / "shared.cdl")
+    a = CitadelMemoryService(path, key="pw", region="memory")
+    b = CitadelMemoryService(path, key="pw", region="other")
+    await a.add_session_to_memory(sess("s", [ev("in region a")]))
+    assert a.count(APP, USER) == 1
+    assert b.count(APP, USER) == 0, "regions must stay separate"