pycontextdb 0.4.0__tar.gz → 0.4.2__tar.gz

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

@@ -2,6 +2,20 @@
 
 ## 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
+  identifiers when a duplicate, explicit target, or unambiguous slot resolves
+  to a current memory. Ambiguous slot-only NOOPs fail closed, while all NOOPs
+  remain content-free and leave the memory version unchanged.
+
 ## 0.4.0 — 2026-08-23
 
 - Explicit deterministic `add` / `update` / `delete` / `noop` memory

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pycontextdb
-Version: 0.4.0
+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.0 → 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.0"
+__version__ = "0.4.2"
 
 __all__ = [
     "Clock",

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

@@ -639,13 +639,26 @@ class ContextDB:
                     attribute=attribute,
                 )
                 if self._audit is not None:
+                    details: dict[str, object] = {
+                        "operation": EvolutionOperation.NOOP.value,
+                        "reason": safe_reason,
+                    }
+                    verified_slot = (
+                        canonicalize_slot(
+                            verified.entity_key,
+                            verified.attribute_key,
+                        )
+                        if verified is not None
+                        else None
+                    )
+                    if verified_slot is not None:
+                        details["entity"] = verified_slot.entity
+                        details["attribute"] = verified_slot.attribute
                     await self._audit.log(
                         operation="NOOP",
+                        memory_id=verified.id if verified is not None else None,
                         user_id=uid,
-                        details={
-                            "operation": EvolutionOperation.NOOP.value,
-                            "reason": safe_reason,
-                        },
+                        details=details,
                     )
             token = await store.consistency_token()
             return MemoryEvolutionResult(
@@ -890,12 +903,20 @@ class ContextDB:
             target = await self._evolution_target(
                 target_memory_id,
                 user_id=user_id,
-                require_current=False,
+                require_current=True,
             )
 
         slot = canonicalize_slot(entity, attribute)
-        if slot is not None:
-            if target is not None:
+        has_slot_reference = bool(entity and entity.strip()) and bool(
+            attribute and attribute.strip()
+        )
+        if has_slot_reference and slot is None:
+            raise EvolutionTargetRequiredError(
+                "NOOP entity/attribute must resolve to a slot"
+            )
+
+        if target is not None:
+            if slot is not None:
                 target_slot = canonicalize_slot(
                     target.entity_key,
                     target.attribute_key,
@@ -907,17 +928,27 @@ class ContextDB:
                     raise EvolutionOperationConflictError(
                         "target memory and requested entity/attribute identify different slots"
                     )
-            rows = await self._require_store().list_by_slot(
-                slot.entity,
-                slot.attribute,
-                user_id=user_id,
+            return target
+
+        if slot is None:
+            return None
+
+        rows = await self._require_store().list_by_slot(
+            slot.entity,
+            slot.attribute,
+            user_id=user_id,
+        )
+        current_at = self.clock()
+        current = [row for row in rows if row.is_valid_at(current_at)]
+        if not current:
+            raise EvolutionTargetNotFoundError(
+                f"{slot.entity}/{slot.attribute}"
             )
-            current = [row for row in rows if row.is_valid_at(self.clock())]
-            if not current:
-                raise EvolutionTargetNotFoundError(
-                    f"{slot.entity}/{slot.attribute}"
-                )
-        return target
+        if len(current) != 1:
+            raise EvolutionOperationConflictError(
+                "slot NOOP is ambiguous; pass target_memory_id"
+            )
+        return current[0]
 
     async def _evolve_delete_transactional(
         self,
@@ -1897,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:
@@ -1909,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.0 → 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.0 → pycontextdb-0.4.2}/contextdb/dynamics/trust.py

@@ -225,8 +225,11 @@ class TrustEngine:
             speakers = list(candidate.corroborated_by)
             if incoming_speaker in speakers:
                 await self._log_noop(
+                    candidate.id,
                     user_id,
                     reason="same_speaker_same_value",
+                    entity=item.entity_key,
+                    attribute=item.attribute_key,
                 )
                 return candidate, "noop"
             speakers.append(incoming_speaker)
@@ -495,7 +498,13 @@ class TrustEngine:
             speakers = list(candidate.corroborated_by)
             if incoming_speaker in speakers:
                 reason = "same_speaker_same_value"
-                await self._log_noop(user_id, reason=reason)
+                await self._log_noop(
+                    candidate.id,
+                    user_id,
+                    reason=reason,
+                    entity=slot.entity,
+                    attribute=slot.attribute,
+                )
                 return EvolutionWrite(
                     applied_operation=EvolutionOperation.NOOP,
                     outcome=EvolutionOutcome.NOOP,
@@ -543,7 +552,13 @@ class TrustEngine:
             speakers = list(candidate.corroborated_by)
             if incoming_speaker in speakers:
                 reason = "same_speaker_same_value"
-                await self._log_noop(user_id, reason=reason)
+                await self._log_noop(
+                    candidate.id,
+                    user_id,
+                    reason=reason,
+                    entity=slot.entity,
+                    attribute=slot.attribute,
+                )
                 return EvolutionWrite(
                     applied_operation=EvolutionOperation.NOOP,
                     outcome=EvolutionOutcome.NOOP,
@@ -768,17 +783,26 @@ class TrustEngine:
 
     async def _log_noop(
         self,
+        memory_id: str,
         user_id: str | None,
         *,
         reason: str,
+        entity: str | None,
+        attribute: str | None,
     ) -> None:
-        """Append a content-free NOOP audit without touching memory state."""
+        """Append scoped, content-free NOOP lineage without mutating memory."""
         if self.audit is not None:
+            details: dict[str, object] = {
+                "operation": EvolutionOperation.NOOP.value,
+                "reason": reason,
+            }
+            slot = canonicalize_slot(entity, attribute)
+            if slot is not None:
+                details["entity"] = slot.entity
+                details["attribute"] = slot.attribute
             await self.audit.log(
                 operation="NOOP",
+                memory_id=memory_id,
                 user_id=user_id,
-                details={
-                    "operation": EvolutionOperation.NOOP.value,
-                    "reason": reason,
-                },
+                details=details,
             )

{pycontextdb-0.4.0 → 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.0 → 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.0 → 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.0 → pycontextdb-0.4.2}/docs/memory_evolution.md

@@ -33,9 +33,10 @@ canonicalized, and injection-shaped content is demoted.
 
 For an empty slot, ADD stores a new memory. If the same speaker repeats the
 same canonical slot value, the applied operation is NOOP: no row is inserted
-or updated and the memory version does not advance. The audit entry contains
-only the fixed operation and reason. A new independent speaker asserting the
-same value corroborates the current memory and applies as UPDATE.
+or updated and the memory version does not advance. The audit entry points to
+the existing memory and contains only the fixed operation and reason plus its
+canonical entity and attribute identifiers. A new independent speaker
+asserting the same value corroborates the current memory and applies as UPDATE.
 
 ADD fails with `EvolutionOperationConflictError` when the slot already holds a
 different value. Use UPDATE to correct an occupied slot.
@@ -83,9 +84,19 @@ the broader `forget_user()` and `verify_forgotten()` contracts.
 
 ## NOOP
 
-NOOP requires a nonempty reason of at most 256 characters. Optional target or
-slot references are scope-checked. The reason is passed through the configured
-PII processor before the content-free `NOOP` audit entry is appended.
+NOOP requires a nonempty reason of at most 256 characters. An optional
+`target_memory_id` must resolve to a current memory in the caller's scope. A
+slot-only reference resolves only when exactly one current occupant exists;
+an ambiguous contested slot raises `EvolutionOperationConflictError` and
+requires an explicit target. The resolved memory is returned and its ID is
+attached to the audit entry. A NOOP without a target or slot remains valid,
+returns no memory, and has no audit `memory_id`.
+
+The reason is passed through the configured PII processor and bounded to 256
+characters before the content-free `NOOP` audit entry is appended. When a
+memory resolves to a slot, the details include only the operation, processed
+reason, and canonical entity and attribute identifiers. They never include
+memory content, old or new values, raw user IDs, or PII annotation originals.
 
 NOOP does not change memory rows, vectors, or the memory version. Its result
 token therefore reports the same memory version visible before the operation

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pycontextdb"
-version = "0.4.0"
+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"