pycontextdb 0.4.4__tar.gz → 0.4.6__tar.gz

{pycontextdb-0.4.4 → pycontextdb-0.4.6}/CHANGELOG.md

@@ -2,6 +2,41 @@
 
 ## Unreleased
 
+## 0.4.6 — 2026-10-08
+
+- A lower-trust write no longer replaces a first-party fact in its slot.
+  Writes made under one user id share a speaker, so a third-party document or
+  an agent inference stored for that user superseded what the user had said,
+  and the user would then be asked to confirm the document's value. A
+  user-stated or confirmed fact now stays current and the slot is contested
+  until `confirm()`. Corrections of equal or higher trust still supersede.
+  Advisory: GHSA-vpf9-5xgr-3x8m.
+- `factual.recall_for_action` and `factual.pending_confirmations` accept the
+  `entity` and `attribute` an action needs. With them, only current facts in
+  that slot count, read exactly rather than by similarity, and the read is
+  audited like a recall. Without them nothing changes: any trusted memory the
+  query retrieves counts, whether or not it answers the request.
+- The slot vocabulary (version 2) adds `user/billing_email`, `user/work_phone`,
+  and `user/work_address`. A user's billing email, work phone, or work address
+  no longer replaces their personal one. An email filed as a billing email
+  stays there instead of being moved to `user/email` and stored as
+  `agent_inferred`.
+
+## 0.4.5 — 2026-10-05
+
+- `forget_user` no longer deletes other users' memories. It added every graph
+  neighbor of the erased memories to the deletion set, and entity edges join
+  any memories that mention the same name, so on a shared client with the
+  entity graph and an extraction model, erasing one user could hard-delete
+  another user's memories. It now deletes only the user's memories and the
+  summaries derived from them, and severs their graph edges.
+- Consolidated summaries keep the weakest corroboration count of their inputs
+  instead of the sum. Repeated copies of one third-party claim could
+  consolidate into a summary that passed the default trust bar and was
+  returned by `recall_for_action`. The summary now stays pending confirmation.
+- Unchanged limitation: entity rows are shared across users, and attributes
+  merged into an entity from a user's text are not removed by `forget_user`.
+
 ## 0.4.4 — 2026-09-20
 
 - PostgreSQL sibling composition now uses an ordered user-plus-entity cache

{pycontextdb-0.4.4 → pycontextdb-0.4.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pycontextdb
-Version: 0.4.4
+Version: 0.4.6
 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
@@ -118,9 +118,9 @@ Hermetic, reproducible — run the suite yourself: `python benchmarks/run_benchm
 
 Speed is table stakes. The production failure that gets agents fired is **acting on a wish as if it were a fact**: a caller says *"I'd like to come in Thursday"* and the agent answers *"we penciled you in."* A wish and a confirmed fact are the same object in every memory store on the market — so ContextDB types them.
 
-Every memory carries **epistemic provenance** (`user_stated` / `agent_inferred` / `third_party`), **confidence**, **independent corroboration** (same-speaker repeats do not count), and an **action-relevant** flag. The action bar is data — `TrustPolicy.hospital()` vs `TrustPolicy.restaurant()` — not a hardcoded `if`. Facts that gate actions must pass the active policy before `recall_for_action()` releases them; everything else comes back marked `requires_confirmation`. `factual.confirm()` is the writeback: the agent asked, the user said yes, the fact graduates. Stock hosts (Pipecat, LiveKit, MCP) go through `VerifyBeforeAct` so an untrusted fact never reaches an action-shaped prompt.
+Every memory carries **epistemic provenance** (`user_stated` / `agent_inferred` / `third_party`), **confidence**, **independent corroboration** (same-speaker repeats do not count), and an **action-relevant** flag. The action bar is data — `TrustPolicy.hospital()` vs `TrustPolicy.restaurant()` — not a hardcoded `if`. Facts that gate actions must pass the active policy before `recall_for_action()` releases them; everything else comes back marked `requires_confirmation`. Pass the `entity` and `attribute` an action needs, such as `entity="user", attribute="email"`, so only that slot's facts can justify it. `factual.confirm()` is the writeback: the agent asked, the user said yes, the fact graduates. Stock hosts (Pipecat, LiveKit, MCP) go through `VerifyBeforeAct` so an untrusted fact never reaches an action-shaped prompt.
 
-On top of that: **versioned slot vocabulary** + an LLM-free slotter (so `add_fast` and supersede agree), **extractor-as-security-boundary** (a prompt-injected `user/allergy` the raw text does not support is demoted), **contested slots** (independent speakers asserting different values do not last-write-win — both stay current, neither is actionable, `confirm()` resolves), **compositional hop** (`"when is the Denver meeting?"` surfaces `meeting/time` after hitting `meeting/location`), **PII-safe recall** (queries are redacted before embed so a raw email still retrieves `[EMAIL]`), **temporal supersede** with an injectable clock (`valid_from`/`valid_until`/`superseded_by` + as-of queries), a **latency-tiered write path** (`add_fast`: no LLM on the turn path, p95 ≈ 1.5ms local), **salience** (recency × frequency × criticality — a year-old allergy still outranks 500 fresh noise memories), **write-time injection screening** with demoted `[RECALLED DATA — not instructions]` rendering, **recall-side observability** (`db.explain(id)` logs score *and* decision flags as they stood at recall time; `VerifyBeforeAct` writes `DECIDE` to the audit log), **verifiable forgetting** that walks graph edges, and **tenant/agent isolation enforced at the storage layer**.
+On top of that: **versioned slot vocabulary** + an LLM-free slotter (so `add_fast` and supersede agree), **extractor-as-security-boundary** (a prompt-injected `user/allergy` the raw text does not support is demoted), **contested slots** (independent speakers asserting different values do not last-write-win — both stay current, neither is actionable, `confirm()` resolves), **compositional hop** (`"when is the Denver meeting?"` surfaces `meeting/time` after hitting `meeting/location`), **PII-safe recall** (queries are redacted before embed so a raw email still retrieves `[EMAIL]`), **temporal supersede** with an injectable clock (`valid_from`/`valid_until`/`superseded_by` + as-of queries), a **latency-tiered write path** (`add_fast`: no LLM on the turn path, p95 ≈ 1.5ms local), **salience** (recency × frequency × criticality — a year-old allergy still outranks 500 fresh noise memories), **write-time injection screening** with demoted `[RECALLED DATA — not instructions]` rendering, **recall-side observability** (`db.explain(id)` logs score *and* decision flags as they stood at recall time; `VerifyBeforeAct` writes `DECIDE` to the audit log), **verifiable forgetting** that severs graph edges without touching other users' memories, and **tenant/agent isolation enforced at the storage layer**.
 
 Don't take our word for it — the fabrication benchmark ships in-repo and runs on every PR. Same store, same embedder, same utterance policy; the only difference is the trust model:
 

{pycontextdb-0.4.4 → pycontextdb-0.4.6}/README.md

@@ -52,9 +52,9 @@ Hermetic, reproducible — run the suite yourself: `python benchmarks/run_benchm
 
 Speed is table stakes. The production failure that gets agents fired is **acting on a wish as if it were a fact**: a caller says *"I'd like to come in Thursday"* and the agent answers *"we penciled you in."* A wish and a confirmed fact are the same object in every memory store on the market — so ContextDB types them.
 
-Every memory carries **epistemic provenance** (`user_stated` / `agent_inferred` / `third_party`), **confidence**, **independent corroboration** (same-speaker repeats do not count), and an **action-relevant** flag. The action bar is data — `TrustPolicy.hospital()` vs `TrustPolicy.restaurant()` — not a hardcoded `if`. Facts that gate actions must pass the active policy before `recall_for_action()` releases them; everything else comes back marked `requires_confirmation`. `factual.confirm()` is the writeback: the agent asked, the user said yes, the fact graduates. Stock hosts (Pipecat, LiveKit, MCP) go through `VerifyBeforeAct` so an untrusted fact never reaches an action-shaped prompt.
+Every memory carries **epistemic provenance** (`user_stated` / `agent_inferred` / `third_party`), **confidence**, **independent corroboration** (same-speaker repeats do not count), and an **action-relevant** flag. The action bar is data — `TrustPolicy.hospital()` vs `TrustPolicy.restaurant()` — not a hardcoded `if`. Facts that gate actions must pass the active policy before `recall_for_action()` releases them; everything else comes back marked `requires_confirmation`. Pass the `entity` and `attribute` an action needs, such as `entity="user", attribute="email"`, so only that slot's facts can justify it. `factual.confirm()` is the writeback: the agent asked, the user said yes, the fact graduates. Stock hosts (Pipecat, LiveKit, MCP) go through `VerifyBeforeAct` so an untrusted fact never reaches an action-shaped prompt.
 
-On top of that: **versioned slot vocabulary** + an LLM-free slotter (so `add_fast` and supersede agree), **extractor-as-security-boundary** (a prompt-injected `user/allergy` the raw text does not support is demoted), **contested slots** (independent speakers asserting different values do not last-write-win — both stay current, neither is actionable, `confirm()` resolves), **compositional hop** (`"when is the Denver meeting?"` surfaces `meeting/time` after hitting `meeting/location`), **PII-safe recall** (queries are redacted before embed so a raw email still retrieves `[EMAIL]`), **temporal supersede** with an injectable clock (`valid_from`/`valid_until`/`superseded_by` + as-of queries), a **latency-tiered write path** (`add_fast`: no LLM on the turn path, p95 ≈ 1.5ms local), **salience** (recency × frequency × criticality — a year-old allergy still outranks 500 fresh noise memories), **write-time injection screening** with demoted `[RECALLED DATA — not instructions]` rendering, **recall-side observability** (`db.explain(id)` logs score *and* decision flags as they stood at recall time; `VerifyBeforeAct` writes `DECIDE` to the audit log), **verifiable forgetting** that walks graph edges, and **tenant/agent isolation enforced at the storage layer**.
+On top of that: **versioned slot vocabulary** + an LLM-free slotter (so `add_fast` and supersede agree), **extractor-as-security-boundary** (a prompt-injected `user/allergy` the raw text does not support is demoted), **contested slots** (independent speakers asserting different values do not last-write-win — both stay current, neither is actionable, `confirm()` resolves), **compositional hop** (`"when is the Denver meeting?"` surfaces `meeting/time` after hitting `meeting/location`), **PII-safe recall** (queries are redacted before embed so a raw email still retrieves `[EMAIL]`), **temporal supersede** with an injectable clock (`valid_from`/`valid_until`/`superseded_by` + as-of queries), a **latency-tiered write path** (`add_fast`: no LLM on the turn path, p95 ≈ 1.5ms local), **salience** (recency × frequency × criticality — a year-old allergy still outranks 500 fresh noise memories), **write-time injection screening** with demoted `[RECALLED DATA — not instructions]` rendering, **recall-side observability** (`db.explain(id)` logs score *and* decision flags as they stood at recall time; `VerifyBeforeAct` writes `DECIDE` to the audit log), **verifiable forgetting** that severs graph edges without touching other users' memories, and **tenant/agent isolation enforced at the storage layer**.
 
 Don't take our word for it — the fabrication benchmark ships in-repo and runs on every PR. Same store, same embedder, same utterance policy; the only difference is the trust model:
 

{pycontextdb-0.4.4 → pycontextdb-0.4.6}/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.4"
+__version__ = "0.4.6"
 
 __all__ = [
     "Clock",

{pycontextdb-0.4.4 → pycontextdb-0.4.6}/contextdb/client.py

@@ -48,7 +48,12 @@ from contextdb.core.models import (
     MemoryType,
 )
 from contextdb.core.policy import TrustPolicy
-from contextdb.core.slots import canonicalize_slot, infer_negation, infer_slot
+from contextdb.core.slots import (
+    canonicalize_slot,
+    infer_negation,
+    infer_slot,
+    slot_supported_by,
+)
 from contextdb.dynamics.trust import TrustEngine, infer_action_relevant, speaker_id
 from contextdb.privacy.injection import screen_injection
 from contextdb.privacy.pii_detector import PIIDetector
@@ -389,7 +394,7 @@ class ContextDB:
         inferred = infer_slot(source_text)
         chosen = explicit or inferred
         if explicit is not None and inferred is not None:
-            if (explicit.entity, explicit.attribute) != (inferred.entity, inferred.attribute):
+            if not slot_supported_by(explicit, inferred):
                 chosen = inferred
                 item.epistemic_source = "agent_inferred"
                 item.confidence = min(item.confidence, 0.4)
@@ -1685,21 +1690,13 @@ class ContextDB:
             if added == 0:
                 break
 
-        # Walk graph edges: a forgotten fact that still has neighbors is
-        # how "forgotten" memories regenerate — not from the row, from
-        # the graph.
+        # Sever graph edges so a forgotten memory cannot be reached or
+        # rebuilt through the graph. Neighbors are never added to the
+        # deletion set: entity edges join every memory that mentions the
+        # same name, including other users' memories, and this user's own
+        # and derived memories are already in ``targets``.
         for graph in self._graphs.values():
             for memory_id in list(targets):
-                try:
-                    neighbors = await graph.get_neighbors(memory_id, max_results=50)
-                except Exception:  # noqa: BLE001
-                    continue
-                for nid, _weight in neighbors:
-                    if nid in targets:
-                        continue
-                    neighbor = await store.get_raw(nid)
-                    if neighbor is not None:
-                        targets[nid] = neighbor
                 try:
                     await graph.remove_node(memory_id)
                 except Exception:  # noqa: BLE001
@@ -1999,8 +1996,18 @@ class ContextDB:
         self,
         user_id: str | None = None,
         limit: int = 100,
+        *,
+        entity: str | None = None,
+        attribute: str | None = None,
     ) -> list[MemoryItem]:
-        """Facts that are action-relevant and do not yet pass the trust policy."""
+        """Facts that are action-relevant and do not yet pass the trust policy.
+
+        With ``entity`` and ``attribute``, only the current facts in that slot.
+        """
+        if entity is not None or attribute is not None:
+            rows = await self.slot_facts(entity, attribute, user_id=user_id)
+            pending = [item for item in rows if self.trust_policy.requires_confirmation(item)]
+            return pending[:limit]
         uid = self._resolve_user(user_id)
         await self._ensure_init()
         store = self._require_store()
@@ -2009,6 +2016,45 @@ class ContextDB:
         )
         return [item for item in rows if self.trust_policy.requires_confirmation(item)]
 
+    async def slot_facts(
+        self,
+        entity: str | None,
+        attribute: str | None,
+        *,
+        user_id: str | None = None,
+        as_of: datetime | None = None,
+    ) -> list[MemoryItem]:
+        """Current facts in one slot, read exactly rather than by similarity.
+
+        A similarity search returns the nearest memories whether or not they
+        answer the request. When the caller knows which slot an action needs,
+        this is the evidence that action may rely on.
+        """
+        slot = canonicalize_slot(entity, attribute)
+        if slot is None:
+            raise ValueError("entity and attribute are both required to name a slot")
+        uid = self._resolve_user(user_id)
+        await self._ensure_init()
+        store = self._require_store()
+        moment = as_of or self.clock()
+        rows = await store.list_by_slot(slot.entity, slot.attribute, user_id=uid)
+        items = sorted(
+            (m for m in rows if m.memory_type == MemoryType.FACTUAL and m.is_valid_at(moment)),
+            key=lambda m: m.write_generation,
+            reverse=True,
+        )
+        audit_details = {
+            "slot": [slot.entity, slot.attribute],
+            "hits": len(items),
+            "returned_ids": [m.id for m in items],
+            "as_of": moment.isoformat(),
+            "abstained": not items,
+        }
+        if self._audit is not None and self.config.enable_read_audit:
+            await self._audit.log(operation="SLOT_READ", user_id=uid, details=audit_details)
+        await self._emit("read_audit", user_id=uid, audit_details=audit_details)
+        return items
+
     # ------------------------------------------------------------------ #
     # Typed memory surfaces
     # ------------------------------------------------------------------ #

{pycontextdb-0.4.4 → pycontextdb-0.4.6}/contextdb/core/slots.py

@@ -14,7 +14,7 @@ from __future__ import annotations
 import re
 from dataclasses import dataclass
 
-SLOT_VOCAB_VERSION = "1"
+SLOT_VOCAB_VERSION = "2"
 
 # Canonical (entity, attribute) → class. The class drives the per-class
 # corroboration bar in :class:`TrustPolicy`.
@@ -31,8 +31,11 @@ SLOT_VOCAB: dict[tuple[str, str], str] = {
     ("reservation", "time"): "booking",
     ("reservation", "day"): "booking",
     ("user", "email"): "contact",
+    ("user", "billing_email"): "contact",
     ("user", "phone"): "contact",
+    ("user", "work_phone"): "contact",
     ("user", "address"): "contact",
+    ("user", "work_address"): "contact",
     ("user", "name"): "identity",
     ("account", "number"): "identity",
     ("account", "pin"): "identity",
@@ -77,6 +80,15 @@ _ATTRIBUTE_ALIASES: dict[str, str] = {
     "mobile": "phone",
     "allergies": "allergy",
     "allergic": "allergy",
+    "invoice_email": "billing_email",
+    "office_phone": "work_phone",
+    "office_address": "work_address",
+}
+
+# Slots the text slotter cannot tell from a broader one: any email address
+# reads as user/email, whether it is personal or where invoices go.
+_REFINES: dict[tuple[str, str], tuple[str, str]] = {
+    ("user", "billing_email"): ("user", "email"),
 }
 
 
@@ -111,6 +123,13 @@ def canonicalize_slot(entity: str | None, attribute: str | None) -> Slot | None:
     return Slot(entity=ent, attribute=attr, slot_class=slot_class)
 
 
+def slot_supported_by(explicit: Slot, inferred: Slot) -> bool:
+    """Whether the slot the text implies is consistent with the one chosen."""
+    chosen = (explicit.entity, explicit.attribute)
+    implied = (inferred.entity, inferred.attribute)
+    return chosen == implied or _REFINES.get(chosen) == implied
+
+
 _WEEKDAYS = (
     "monday",
     "tuesday",

{pycontextdb-0.4.4 → pycontextdb-0.4.6}/contextdb/dynamics/evolution.py

@@ -98,7 +98,8 @@ class Consolidator:
             # Trust-conservative merge: a summary must never be MORE trusted
             # than its least trusted input. Otherwise consolidation launders
             # epistemic status — five third-party hearsay fragments would
-            # emerge as a confident first-party fact.
+            # emerge as a confident first-party fact. Corroboration is not
+            # summed: copies of one claim are not independent support.
             new_item = MemoryItem(
                 content=summary,
                 embedding=cluster_items[0].embedding,
@@ -110,7 +111,7 @@ class Consolidator:
                     key=lambda s: _SOURCE_RANK[s],
                 ),
                 confidence=min(m.confidence for m in cluster_items),
-                corroboration_count=sum(m.corroboration_count for m in cluster_items),
+                corroboration_count=min(m.independent_corroboration for m in cluster_items),
                 action_relevant=any(m.action_relevant for m in cluster_items),
                 injection_suspect=any(m.injection_suspect for m in cluster_items),
             )

{pycontextdb-0.4.4 → pycontextdb-0.4.6}/contextdb/dynamics/trust.py

@@ -137,6 +137,21 @@ def speaker_id(
     return "anonymous"
 
 
+def _first_party(item: MemoryItem) -> bool:
+    return item.confirmed or item.epistemic_source == "user_stated"
+
+
+def outranks(current: MemoryItem, incoming: MemoryItem) -> bool:
+    """Whether ``incoming`` may not replace ``current`` in a slot.
+
+    Speaker identity alone cannot tell a user's correction from a document
+    the agent stored on the user's behalf: both arrive under the same user.
+    A first-party or confirmed fact is therefore never superseded by a
+    lower-trust write; the slot is contested instead.
+    """
+    return _first_party(current) and not _first_party(incoming)
+
+
 class TrustEngine:
     """Slot-aware write path used by ``factual.add`` and consolidation."""
 
@@ -252,20 +267,27 @@ class TrustEngine:
             )
             return updated, "corroborated"
 
+        protected = [c for c in current if outranks(c, item)]
         same_speaker = [
-            c for c in current if incoming_speaker in (c.corroborated_by or [])
+            c
+            for c in current
+            if c not in protected and incoming_speaker in (c.corroborated_by or [])
         ]
         other_speaker = [
-            c for c in current if incoming_speaker not in (c.corroborated_by or [])
+            c
+            for c in current
+            if c not in protected and incoming_speaker not in (c.corroborated_by or [])
         ]
 
         item.write_generation = max_gen + 1
         # Independent speakers asserting different values: contest, do not
-        # last-write-win. Same-speaker corrections still supersede.
-        if other_speaker and not same_speaker and not item.pending_consolidation:
+        # last-write-win. Same-speaker corrections still supersede, except a
+        # lower-trust write never replaces a first-party fact.
+        contest = protected + ([] if same_speaker else other_speaker)
+        if contest and not item.pending_consolidation:
             item.contested = True
             stored = await self.store.add(item)
-            for candidate in other_speaker:
+            for candidate in contest:
                 await self.store.update(candidate.id, contested=True)
                 await self._log(
                     "CONFLICT",
@@ -278,8 +300,13 @@ class TrustEngine:
                         "old_value": candidate.content,
                         "new_value": stored.content,
                         "speaker": incoming_speaker,
+                        "reason": (
+                            "outranked_source" if candidate in protected else "other_speaker"
+                        ),
                     },
                 )
+            for candidate in [c for c in current if c not in contest]:
+                await self._supersede(candidate, stored, user_id, item, now)
             await self._log(
                 "CREATE",
                 stored.id,
@@ -297,25 +324,9 @@ class TrustEngine:
         for candidate in current:
             if item.pending_consolidation and not candidate.pending_consolidation:
                 continue
-            await self.store.update(
-                candidate.id,
-                valid_until=now,
-                superseded_by=stored.id,
-                contested=False,
-            )
-            await self._log(
-                "SUPERSEDE",
-                candidate.id,
-                user_id,
-                {
-                    "superseded_by": stored.id,
-                    "entity": item.entity_key,
-                    "attribute": item.attribute_key,
-                    "old_value": candidate.content,
-                    "new_value": stored.content,
-                    "generation": item.write_generation,
-                },
-            )
+            if candidate in protected:
+                continue
+            await self._supersede(candidate, stored, user_id, item, now)
             outcome = "superseded"
         await self._log(
             "CREATE",
@@ -325,6 +336,34 @@ class TrustEngine:
         )
         return stored, outcome
 
+    async def _supersede(
+        self,
+        candidate: MemoryItem,
+        stored: MemoryItem,
+        user_id: str | None,
+        item: MemoryItem,
+        now: datetime,
+    ) -> None:
+        await self.store.update(
+            candidate.id,
+            valid_until=now,
+            superseded_by=stored.id,
+            contested=False,
+        )
+        await self._log(
+            "SUPERSEDE",
+            candidate.id,
+            user_id,
+            {
+                "superseded_by": stored.id,
+                "entity": item.entity_key,
+                "attribute": item.attribute_key,
+                "old_value": candidate.content,
+                "new_value": stored.content,
+                "generation": item.write_generation,
+            },
+        )
+
     async def evolve_write(
         self,
         item: MemoryItem,
@@ -591,22 +630,24 @@ class TrustEngine:
                 previous_memory_ids=previous_ids,
             )
 
+        protected = [candidate for candidate in current if outranks(candidate, item)]
         same_speaker = [
             candidate
             for candidate in current
-            if incoming_speaker in candidate.corroborated_by
+            if candidate not in protected and incoming_speaker in candidate.corroborated_by
         ]
         other_speaker = [
             candidate
             for candidate in current
-            if incoming_speaker not in candidate.corroborated_by
+            if candidate not in protected and incoming_speaker not in candidate.corroborated_by
         ]
         item.write_generation = max_generation + 1
 
-        if other_speaker and not same_speaker:
+        contest = protected + ([] if same_speaker else other_speaker)
+        if contest:
             item.contested = True
             stored = await self.store.add(item)
-            for candidate in other_speaker:
+            for candidate in contest:
                 await self.store.update(candidate.id, contested=True)
                 await self._log(
                     "CONFLICT",
@@ -619,8 +660,13 @@ class TrustEngine:
                         "old_value": candidate.content,
                         "new_value": stored.content,
                         "speaker": incoming_speaker,
+                        "reason": (
+                            "outranked_source" if candidate in protected else "other_speaker"
+                        ),
                     },
                 )
+            for candidate in [c for c in current if c not in contest]:
+                await self._supersede(candidate, stored, user_id, item, now)
             await self._log(
                 "CREATE",
                 stored.id,

{pycontextdb-0.4.4 → pycontextdb-0.4.6}/contextdb/memory/factual.py

@@ -166,12 +166,24 @@ class FactualMemory:
         as_of: datetime | None = None,
         *,
         user_id: str | None = None,
+        entity: str | None = None,
+        attribute: str | None = None,
     ) -> list[MemoryItem]:
-        """Recall only facts an agent may act on without confirming first."""
+        """Recall only facts an agent may act on without confirming first.
+
+        Without a slot, any trusted memory the query retrieves counts, related
+        or not. Pass the ``entity`` and ``attribute`` the action needs to rely
+        only on trusted facts in that slot.
+        """
         policy = self.client.trust_policy
-        candidates = await self.recall(
-            query, top_k=top_k * 4, as_of=as_of, user_id=self._user(user_id)
-        )
+        if entity is not None or attribute is not None:
+            candidates = await self.client.slot_facts(
+                entity, attribute, user_id=self._user(user_id), as_of=as_of
+            )
+        else:
+            candidates = await self.recall(
+                query, top_k=top_k * 4, as_of=as_of, user_id=self._user(user_id)
+            )
         return [m for m in candidates if policy.is_trusted(m)][:top_k]
 
     async def confirm(self, memory_id: str, user_id: str | None = None) -> MemoryItem:
@@ -182,10 +194,13 @@ class FactualMemory:
         self,
         user_id: str | None = None,
         limit: int = 100,
+        *,
+        entity: str | None = None,
+        attribute: str | None = None,
     ) -> list[MemoryItem]:
         """Action-relevant facts that still need a yes from the user."""
         return await self.client.pending_confirmations(
-            user_id=self._user(user_id), limit=limit
+            user_id=self._user(user_id), limit=limit, entity=entity, attribute=attribute
         )
 
     async def update_fact(

{pycontextdb-0.4.4 → pycontextdb-0.4.6}/docs/architecture.md

@@ -41,7 +41,8 @@ Three pipelines operate over the storage layer:
    NOOP operations with lineage and consistency results. Separately, the
    auto-linker mirrors each new write into graph indices; the consolidator
    merges dense semantic clusters into summaries that inherit *worst-case*
-   trust (no laundering); the pruner drops stale / redundant memories by
+   trust, including the weakest corroboration count (no laundering); the
+   pruner drops stale / redundant memories by
    policy.
 3. **Retrieval** — a query becomes an answer. The query is PII-redacted
    before embed. Query classifier picks graph weights; each graph produces
@@ -78,7 +79,9 @@ search, `DECIDE` (act/ask/abstain), and deletion — and because the chain
 is append-only, only the PII-processed form of a query is ever logged.
 `pii_action="encrypt"` fails closed: without a key the client refuses to
 initialize rather than store plaintext annotation originals.
-`forget_user` walks graph edges and signs the deletion set. The retention
+`forget_user` deletes the user's memories and the summaries derived from them,
+severs their graph edges, and signs the deletion set. It never deletes another
+user's memory through a shared edge. The retention
 manager applies typed TTLs and honors right-to-erasure requests. Isolation
 is a store predicate (`user_id` / `tenant_id` / `agent_id`), not a
 convention.

{pycontextdb-0.4.4 → pycontextdb-0.4.6}/pyproject.toml

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