pycontextdb 0.4.1__tar.gz → 0.4.2__tar.gz

{pycontextdb-0.4.1 → pycontextdb-0.4.2}/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## Unreleased
 
+## 0.4.2 — 2026-09-20
+
+- Recall now bounds sibling composition before deep-copying Postgres cache
+  entries and borrows read-only candidate references while ranking. Final
+  results remain detached, and entity priority, temporal validity, user scope,
+  and composition limits are unchanged.
+
 ## 0.4.1 — 2026-08-24
 
 - NOOP audit entries now carry the existing memory ID and canonical slot

{pycontextdb-0.4.1 → pycontextdb-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pycontextdb
-Version: 0.4.1
+Version: 0.4.2
 Summary: The unified context layer for AI agents — memory you can act on without treating wishes as facts
 Project-URL: Homepage, https://github.com/atomsai/contextdb
 Project-URL: Documentation, https://contextdb.dev

{pycontextdb-0.4.1 → pycontextdb-0.4.2}/contextdb/__init__.py

@@ -41,7 +41,7 @@ from contextdb.core.policy import TrustPolicy
 from contextdb.pool import ContextDBPool
 from contextdb.utils.embeddings import EmbeddingProvider
 
-__version__ = "0.4.1"
+__version__ = "0.4.2"
 
 __all__ = [
     "Clock",

{pycontextdb-0.4.1 → pycontextdb-0.4.2}/contextdb/client.py

@@ -1928,6 +1928,9 @@ class ContextDB:
         siblings = await store.list_by_entities(
             entity_keys,
             user_id=user_id,
+            exclude_ids=seen,
+            valid_at=moment,
+            limit=extra,
         )
         siblings_by_entity: dict[str, list[MemoryItem]] = {}
         for sibling in siblings:
@@ -1940,8 +1943,6 @@ class ContextDB:
             if not item.entity_key:
                 continue
             for sibling in siblings_by_entity.get(item.entity_key, []):
-                if sibling.id in seen or not sibling.is_valid_at(moment):
-                    continue
                 seen.add(sibling.id)
                 extras.append(sibling)
                 if len(extras) >= extra:

{pycontextdb-0.4.1 → pycontextdb-0.4.2}/contextdb/dynamics/retrieval.py

@@ -15,7 +15,7 @@ heuristics below get ~80% of the signal for zero cost.
 from __future__ import annotations
 
 import re
-from dataclasses import dataclass, field
+from dataclasses import dataclass, field, replace
 from datetime import datetime
 from typing import TYPE_CHECKING
 
@@ -166,7 +166,10 @@ class RetrievalEngine:
         """RRF-fuse per-graph rankings, then multiply by salience."""
         weights = self.classifier.classify(query)
         seed_items = await self.store.search_by_embedding(
-            query_embedding, top_k=top_k * 2, user_id=user_id
+            query_embedding,
+            top_k=top_k * 2,
+            user_id=user_id,
+            copy_items=False,
         )
         semantic_ranking = [(item.id, 1.0 / (rank + 1)) for rank, item in enumerate(seed_items)]
         rankings: dict[str, list[tuple[str, float]]] = {"semantic": semantic_ranking}
@@ -201,25 +204,34 @@ class RetrievalEngine:
         if not fused:
             # No fusion signal (empty store or zero weights): rank the seeds
             # directly, still applying salience.
-            return [
+            scored = [
                 self._score(
                     item, 1.0 / (rank + 1), per_graph_ranks, now, seed_cosine.get(item.id, 0.0)
                 )
                 for rank, item in enumerate(seed_items[:top_k])
             ]
-
-        scored: list[ScoredMemory] = []
-        for mid, rrf_score in fused:
-            item = seed_by_id.get(mid)
-            if item is None:
-                item = await self.store.get_raw(mid)
-            if item is None:
-                continue
-            scored.append(
-                self._score(item, rrf_score, per_graph_ranks, now, seed_cosine.get(mid, 0.0))
-            )
-        scored.sort(key=lambda s: s.final_score, reverse=True)
-        return scored[:top_k]
+        else:
+            scored = []
+            for mid, rrf_score in fused:
+                item = seed_by_id.get(mid)
+                if item is None:
+                    item = await self.store.get_raw(mid)
+                if item is None:
+                    continue
+                scored.append(
+                    self._score(
+                        item,
+                        rrf_score,
+                        per_graph_ranks,
+                        now,
+                        seed_cosine.get(mid, 0.0),
+                    )
+                )
+            scored.sort(key=lambda s: s.final_score, reverse=True)
+        return [
+            replace(score, item=score.item.model_copy(deep=True))
+            for score in scored[:top_k]
+        ]
 
     def _score(
         self,

{pycontextdb-0.4.1 → pycontextdb-0.4.2}/contextdb/store/base.py

@@ -12,6 +12,7 @@ from contextdb.core.models import MemoryConsistencyToken, MemoryStatus
 
 if TYPE_CHECKING:
     from contextlib import AbstractAsyncContextManager
+    from datetime import datetime
 
     from contextdb.core.models import MemoryItem, MemoryType
 
@@ -54,11 +55,15 @@ class BaseStore(ABC):
         top_k: int = 10,
         filters: dict[str, object] | None = None,
         user_id: str | None = None,
+        *,
+        copy_items: bool = True,
     ) -> list[MemoryItem]:
         """Return top-k most similar memories by cosine similarity.
 
         ``user_id`` filters the result. A store constructed with a fixed
         user scope ignores a conflicting per-call value and stays scoped.
+        ``copy_items=False`` is reserved for internal read-only ranking;
+        public callers receive detached items by default.
         """
 
     @abstractmethod
@@ -148,16 +153,31 @@ class BaseStore(ABC):
         entity_keys: list[str],
         status: MemoryStatus | None = MemoryStatus.ACTIVE,
         user_id: str | None = None,
+        *,
+        exclude_ids: set[str] | None = None,
+        valid_at: datetime | None = None,
+        limit: int | None = None,
     ) -> list[MemoryItem]:
+        """List scoped entity memories with optional bounded composition filters."""
+
+        if limit is not None and limit <= 0:
+            return []
+        excluded = exclude_ids or set()
         items: list[MemoryItem] = []
         for entity_key in dict.fromkeys(entity_keys):
-            items.extend(
-                await self.list_by_entity(
-                    entity_key,
-                    status=status,
-                    user_id=user_id,
-                )
+            candidates = await self.list_by_entity(
+                entity_key,
+                status=status,
+                user_id=user_id,
             )
+            for item in candidates:
+                if item.id in excluded:
+                    continue
+                if valid_at is not None and not item.is_valid_at(valid_at):
+                    continue
+                items.append(item)
+                if limit is not None and len(items) >= limit:
+                    return items
         return items
 
     async def list_pending_consolidation(self, limit: int = 100) -> list[MemoryItem]:

{pycontextdb-0.4.1 → pycontextdb-0.4.2}/contextdb/store/postgres_store.py

@@ -940,6 +940,8 @@ class PostgresStore(BaseStore):
         top_k: int = 10,
         filters: dict[str, object] | None = None,
         user_id: str | None = None,
+        *,
+        copy_items: bool = True,
     ) -> list[MemoryItem]:
         index = await self._ensure_index()
         query = np.asarray(embedding, dtype=np.float32)
@@ -968,7 +970,7 @@ class PostgresStore(BaseStore):
                 continue
             if filters and not _passes_filters(item, filters):
                 continue
-            results.append(item.model_copy(deep=True))
+            results.append(item.model_copy(deep=True) if copy_items else item)
             if len(results) >= top_k:
                 break
         return results
@@ -1047,22 +1049,40 @@ class PostgresStore(BaseStore):
         entity_keys: list[str],
         status: MemoryStatus | None = MemoryStatus.ACTIVE,
         user_id: str | None = None,
+        *,
+        exclude_ids: set[str] | None = None,
+        valid_at: datetime | None = None,
+        limit: int | None = None,
     ) -> list[MemoryItem]:
         if status != MemoryStatus.ACTIVE:
             return await super().list_by_entities(
                 entity_keys,
                 status=status,
                 user_id=user_id,
+                exclude_ids=exclude_ids,
+                valid_at=valid_at,
+                limit=limit,
             )
+        if limit is not None and limit <= 0:
+            return []
         if not self._index_loaded:
             await self._ensure_index()
-        keys = set(entity_keys)
-        return [
-            item.model_copy(deep=True)
-            for item in self._index_items.values()
-            if item.entity_key in keys
-            and self._item_scope_allows(item, user_id)
-        ]
+        excluded = exclude_ids or set()
+        items: list[MemoryItem] = []
+        for entity_key in dict.fromkeys(entity_keys):
+            for item in self._index_items.values():
+                if item.entity_key != entity_key:
+                    continue
+                if not self._item_scope_allows(item, user_id):
+                    continue
+                if item.id in excluded:
+                    continue
+                if valid_at is not None and not item.is_valid_at(valid_at):
+                    continue
+                items.append(item.model_copy(deep=True))
+                if limit is not None and len(items) >= limit:
+                    return items
+        return items
 
     async def list_pending_consolidation(self, limit: int = 100) -> list[MemoryItem]:
         sql = (

{pycontextdb-0.4.1 → pycontextdb-0.4.2}/contextdb/store/sqlite_store.py

@@ -821,6 +821,8 @@ class SQLiteStore(BaseStore):
         top_k: int = 10,
         filters: dict[str, object] | None = None,
         user_id: str | None = None,
+        *,
+        copy_items: bool = True,
     ) -> list[MemoryItem]:
         conn = self._require_conn()
         index = await self._ensure_index()

{pycontextdb-0.4.1 → pycontextdb-0.4.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pycontextdb"
-version = "0.4.1"
+version = "0.4.2"
 description = "The unified context layer for AI agents — memory you can act on without treating wishes as facts"
 readme = "README.md"
 license = "Apache-2.0"

pycontextdb-0.4.2/tests/unit/test_pg_sql.py

@@ -0,0 +1,228 @@
+from datetime import datetime, timedelta, timezone
+from typing import Any
+
+import pytest
+
+from contextdb.core.exceptions import ConfigError
+from contextdb.core.models import MemoryItem
+from contextdb.store.factory import (
+    is_postgres_url,
+    normalize_postgres_url,
+    open_store,
+)
+from contextdb.store.pg_sql import qmark_to_dollar, split_script, translate_sqlite_sql
+from contextdb.store.postgres_store import PostgresStore, _PgAdapter
+
+
+def test_qmark_to_dollar() -> None:
+    assert qmark_to_dollar("SELECT * FROM t WHERE a = ? AND b = ?") == (
+        "SELECT * FROM t WHERE a = $1 AND b = $2"
+    )
+
+
+def test_insert_or_replace_semantic() -> None:
+    sql = translate_sqlite_sql(
+        "INSERT OR REPLACE INTO semantic_edges "
+        "(source_id, target_id, weight, metadata, created_at) VALUES (?,?,?,?,?)"
+    )
+    assert "ON CONFLICT (source_id, target_id) DO UPDATE" in sql
+    assert "$5" in sql
+
+
+def test_insert_or_ignore() -> None:
+    sql = translate_sqlite_sql("INSERT OR IGNORE INTO memory_entity_edges VALUES (?,?,?,?)")
+    assert "ON CONFLICT DO NOTHING" in sql
+    assert "$4" in sql
+
+
+def test_split_script() -> None:
+    assert split_script("A;\nB;\n") == ["A", "B"]
+
+
+def test_postgres_url() -> None:
+    assert is_postgres_url("postgresql://localhost/db")
+    assert is_postgres_url("postgres://localhost/db")
+    assert not is_postgres_url("sqlite:///x.db")
+    assert normalize_postgres_url("postgresql+asyncpg://h/db") == "postgresql://h/db"
+
+
+def test_external_postgres_pool_rejects_sqlite() -> None:
+    with pytest.raises(ConfigError, match="requires a PostgreSQL"):
+        open_store("sqlite:///:memory:", postgres_pool=object())
+
+
+@pytest.mark.asyncio
+async def test_postgres_store_does_not_close_external_pool() -> None:
+    class FakePool:
+        def __init__(self) -> None:
+            self.closed = 0
+
+        async def close(self) -> None:
+            self.closed += 1
+
+    pool = FakePool()
+    store = PostgresStore("postgresql://example/contextdb", pool=pool)
+    await store.close()
+    assert pool.closed == 0
+
+
+@pytest.mark.asyncio
+async def test_list_by_entities_filters_and_copies_only_the_requested_limit(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    store = PostgresStore(
+        "postgresql://example/contextdb",
+        tenant_id="tenant-1",
+        agent_id="agent-1",
+        pool=object(),
+    )
+    now = datetime.now(tz=timezone.utc)
+    entity_b = [
+        MemoryItem(
+            content=f"b-{index}",
+            entity_key="entity-b",
+            user_id="user-1",
+            tenant_id="tenant-1",
+            agent_id="agent-1",
+        )
+        for index in range(10)
+    ]
+    entity_a = [
+        MemoryItem(
+            content=f"a-{index}",
+            entity_key="entity-a",
+            user_id="user-1",
+            tenant_id="tenant-1",
+            agent_id="agent-1",
+            metadata={"nested": [index]},
+        )
+        for index in range(20)
+    ]
+    future = MemoryItem(
+        content="future",
+        entity_key="entity-a",
+        user_id="user-1",
+        tenant_id="tenant-1",
+        agent_id="agent-1",
+        valid_from=now + timedelta(days=1),
+    )
+    indexed = [*entity_b, future, *entity_a]
+    store._index_items = {item.id: item for item in indexed}
+    store._index_loaded = True
+
+    original_model_copy = MemoryItem.model_copy
+    copies = 0
+
+    def counted_model_copy(
+        self: MemoryItem,
+        *,
+        update: dict[str, Any] | None = None,
+        deep: bool = False,
+    ) -> MemoryItem:
+        nonlocal copies
+        copies += 1
+        return original_model_copy(self, update=update, deep=deep)
+
+    monkeypatch.setattr(MemoryItem, "model_copy", counted_model_copy)
+    results = await store.list_by_entities(
+        ["entity-a", "entity-b"],
+        user_id="user-1",
+        exclude_ids={entity_a[0].id},
+        valid_at=now,
+        limit=5,
+    )
+
+    assert len(results) == 5
+    assert copies == 5
+    assert all(item.entity_key == "entity-a" for item in results)
+    assert entity_a[0].id not in {item.id for item in results}
+    results[0].metadata["nested"].append(99)
+    source = store._index_items[results[0].id]
+    assert source.metadata["nested"] != results[0].metadata["nested"]
+
+
+@pytest.mark.asyncio
+async def test_postgres_embedding_search_can_borrow_read_only_index_items(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    store = PostgresStore(
+        "postgresql://example/contextdb",
+        tenant_id="tenant-1",
+        agent_id="agent-1",
+        pool=object(),
+    )
+    source = MemoryItem(
+        content="Thursday is confirmed",
+        embedding=[1.0, 0.0],
+        user_id="user-1",
+        tenant_id="tenant-1",
+        agent_id="agent-1",
+        metadata={"nested": ["source"]},
+    )
+    store._index_items = {source.id: source}
+
+    class FakeIndex:
+        def search(
+            self,
+            _query: object,
+            *,
+            top_k: int,
+            include_ids: set[str],
+        ) -> list[tuple[str, float]]:
+            assert top_k == 1
+            assert include_ids == {source.id}
+            return [(source.id, 1.0)]
+
+    async def ensure_index() -> Any:
+        return FakeIndex()
+
+    monkeypatch.setattr(store, "_ensure_index", ensure_index)
+    copied = await store.search_by_embedding(
+        [1.0, 0.0],
+        top_k=1,
+        user_id="user-1",
+    )
+    borrowed = await store.search_by_embedding(
+        [1.0, 0.0],
+        top_k=1,
+        user_id="user-1",
+        copy_items=False,
+    )
+
+    assert copied == [source]
+    assert copied[0] is not source
+    assert borrowed[0] is source
+    copied[0].metadata["nested"].append("caller")
+    assert source.metadata == {"nested": ["source"]}
+
+
+@pytest.mark.asyncio
+async def test_bound_adapter_reuses_advisory_transaction_connection() -> None:
+    class NoAcquirePool:
+        def acquire(self) -> None:
+            raise AssertionError("bound execution must not acquire another connection")
+
+    class FakeConnection:
+        def __init__(self) -> None:
+            self.statements: list[str] = []
+
+        async def fetch(self, sql: str, *params: object) -> list[dict[str, int]]:
+            self.statements.append(sql)
+            return [{"value": 1}]
+
+        async def execute(self, sql: str, *params: object) -> str:
+            self.statements.append(sql)
+            return "UPDATE 1"
+
+    adapter = _PgAdapter(NoAcquirePool())
+    connection = FakeConnection()
+    token = adapter.bind(connection)
+    try:
+        selected = await adapter.execute("SELECT value FROM example")
+        updated = await adapter.execute("UPDATE example SET value = ?", (2,))
+    finally:
+        adapter.reset(token)
+
+    assert await selected.fetchall() == [{"value": 1}]
+    assert updated.rowcount == 1
+    assert len(connection.statements) == 2

pycontextdb-0.4.2/tests/unit/test_retrieval.py

@@ -0,0 +1,84 @@
+"""Tests for multi-graph retrieval."""
+
+from __future__ import annotations
+
+import pytest
+
+from contextdb.core.models import MemoryItem
+from contextdb.dynamics.retrieval import (
+    QueryClassifier,
+    RetrievalEngine,
+    RetrievalFuser,
+)
+
+
+def test_query_classifier_weights() -> None:
+    qc = QueryClassifier()
+    weights_temporal = qc.classify("when did we last talk?")
+    assert "temporal" in weights_temporal
+    weights_causal = qc.classify("why did the build fail?")
+    assert "causal" in weights_causal
+    weights_generic = qc.classify("tell me about python")
+    assert weights_generic["semantic"] == 1.0
+
+
+def test_rrf_fusion() -> None:
+    fuser = RetrievalFuser(k=60)
+    rankings = {
+        "semantic": [("a", 0.9), ("b", 0.7), ("c", 0.5)],
+        "temporal": [("b", 1.0), ("c", 0.8)],
+    }
+    weights = {"semantic": 0.5, "temporal": 0.5}
+    fused = fuser.fuse(rankings, weights)
+    ranked_ids = [mid for mid, _ in fused]
+    # "b" appears higher than "a" on aggregate (rank 2 semantic + rank 1 temporal
+    # vs. rank 1 semantic only).
+    assert ranked_ids[0] == "b"
+    assert set(ranked_ids) == {"a", "b", "c"}
+
+
+@pytest.mark.asyncio
+async def test_retrieval_ranks_store_references_but_returns_detached_items() -> None:
+    source = MemoryItem(
+        content="Thursday is confirmed",
+        embedding=[1.0, 0.0],
+        metadata={"nested": ["source"]},
+    )
+
+    class ReferenceStore:
+        async def search_by_embedding(
+            self,
+            _embedding: list[float],
+            top_k: int = 10,
+            filters: dict[str, object] | None = None,
+            user_id: str | None = None,
+            *,
+            copy_items: bool = True,
+        ) -> list[MemoryItem]:
+            assert top_k == 2
+            assert filters is None
+            assert user_id == "user-1"
+            assert copy_items is False
+            return [source]
+
+        async def get_raw(self, _memory_id: str) -> MemoryItem | None:
+            return None
+
+    engine = RetrievalEngine(
+        ReferenceStore(),  # type: ignore[arg-type]
+        {},
+        QueryClassifier(),
+        RetrievalFuser(),
+    )
+    results = await engine.search_scored(
+        "visit day",
+        [1.0, 0.0],
+        top_k=1,
+        user_id="user-1",
+    )
+
+    assert len(results) == 1
+    assert results[0].item == source
+    assert results[0].item is not source
+    results[0].item.metadata["nested"].append("caller")
+    assert source.metadata == {"nested": ["source"]}

{pycontextdb-0.4.1 → pycontextdb-0.4.2}/tests/unit/test_store.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import asyncio
+from datetime import datetime, timedelta, timezone
 from pathlib import Path
 
 import pytest
@@ -174,6 +175,44 @@ async def test_list_and_count(tmp_store: SQLiteStore) -> None:
     assert len(items) == 3
 
 
+@pytest.mark.asyncio
+async def test_list_by_entities_applies_composition_filters(
+    tmp_store: SQLiteStore,
+) -> None:
+    now = datetime.now(tz=timezone.utc)
+    first = await tmp_store.add(
+        MemoryItem(
+            content="first",
+            entity_key="customer",
+            attribute_key="first",
+        )
+    )
+    second = await tmp_store.add(
+        MemoryItem(
+            content="second",
+            entity_key="customer",
+            attribute_key="second",
+        )
+    )
+    await tmp_store.add(
+        MemoryItem(
+            content="future",
+            entity_key="customer",
+            attribute_key="future",
+            valid_from=now + timedelta(days=1),
+        )
+    )
+
+    results = await tmp_store.list_by_entities(
+        ["customer"],
+        exclude_ids={first.id},
+        valid_at=now,
+        limit=1,
+    )
+
+    assert [item.id for item in results] == [second.id]
+
+
 @pytest.mark.asyncio
 async def test_search_by_embedding(tmp_store: SQLiteStore) -> None:
     a = await tmp_store.add(MemoryItem(content="a", embedding=[1.0] + [0.0] * 31))
@@ -249,8 +288,6 @@ async def test_iter_memories_paginates(tmp_store: SQLiteStore) -> None:
 @pytest.mark.asyncio
 async def test_delete_older_than(tmp_store: SQLiteStore) -> None:
     """delete_older_than issues a single SQL delete."""
-    from datetime import datetime, timezone
-
     item = await tmp_store.add(MemoryItem(content="x", embedding=[0.0] * 32))
     future = datetime.now(tz=timezone.utc).replace(year=2099).isoformat()
     removed = await tmp_store.delete_older_than(future, hard=True)