pycontextdb 0.4.6__tar.gz → 0.4.8__tar.gz

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

@@ -2,6 +2,58 @@
 
 ## Unreleased
 
+## 0.4.8 — 2026-10-21
+
+- `factual.add()`, `add_fast()`, and `add_many()` accept optional `event_time`
+  and set `valid_from = event_time` (closing superseded slot occupants at
+  `valid_until = event_time`) so backdated writes carry their real validity
+  window.
+- `RetrievalEngine.search_scored()` applies `as_of` filtering in `SQLiteStore`
+  and `PostgresStore` before top-k truncation and computes salience decay
+  relative to `as_of`.
+- `RetrievalEngine.search_scored()` adds a general BM25 keyword ranking arm
+  (`_bm25_ranking`) fused via Reciprocal Rank Fusion alongside semantic and
+  graph rankings, while keeping `recall_for_action` relevance-floor bypass
+  restricted to digit-bearing `identifier_tokens`.
+- `render_recalled_context()` adds optional `include_timestamps` and
+  `chronological` ordering and marks `CONTESTED` memories.
+
+## 0.4.7 — 2026-10-12
+
+- `forget_user` now removes what the user added to shared entities. Entity
+  attributes record the memory that supplied them, are rebuilt from the
+  remaining sources when a memory is removed, and an entity no memory still
+  mentions is deleted. `verify_forgotten` fails if an edge or attribute source
+  still points at a deleted memory. Attributes merged before 0.4.7 have no
+  recorded source and stay until their entity is unreferenced.
+- In encrypt and redact modes, a slot value that contains a detected PII span
+  is stored as a fingerprint, keyed with the PII encryption key when one is
+  configured. Slot values were taken from the original
+  utterance, so encrypt mode still wrote plaintext emails and phone numbers to
+  disk. Comparisons are unchanged. A value written before 0.4.7 compares as
+  different from the same value written now, so it is superseded once.
+- `consolidate_pending` no longer drops a new value that reads the same once
+  redacted. Two emails saved with `add_fast` both stored as `[EMAIL]`, so the
+  second consolidated into a no-op and was lost.
+- Recall adds a lexical ranking for identifiers (tokens of three or more
+  characters that contain a digit, such as order numbers and SKUs). An exact
+  identifier match passes the relevance floor. Stores gain `search_text`; no
+  schema change.
+- `pii_detect_names_and_addresses=True` also redacts street addresses and cued
+  names ("my name is", "call me", "this is" followed by two capitalized
+  words). Off by default, because a redacted address is hidden from the agent
+  too.
+- Appointment kinds get their own slots: "my dentist appointment" and "my
+  haircut appointment" no longer replace or merge with each other. Kind
+  entities such as `dentist_appointment` use the booking class, and a generic
+  `appointment` slot is still accepted where the text names a kind.
+- The relevance floor no longer recommends a fixed 0.15 to 0.25 band. Cosine
+  ranges are embedder-specific, and a floor cannot tell whether a memory
+  answers a request.
+- README and docs replace v0.1.0 performance numbers and fixed test counts
+  with current measurements, and state that no competitor arms ship in the
+  bake-off.
+
 ## 0.4.6 — 2026-10-08
 
 - A lower-trust write no longer replaces a first-party fact in its slot.

pycontextdb-0.4.8/COMMERCIAL.md

@@ -0,0 +1,71 @@
+# Commercial use and trademark
+
+The software in this repository is open source under the Apache License,
+Version 2.0 (see [LICENSE](LICENSE)). That license covers the code. It
+does not cover the name.
+
+Releases through `v0.4.8`, and the code published through `c84d78b`, are
+Apache-2.0 with no profile cap. Those grants are permanent, including
+for forks already taken. There is no license key and no phone-home check.
+
+## Profile line from 1.0
+
+`pycontextdb` 1.0 is a fresh release. It does not relicense 0.4.8 or any
+earlier package. Production use of 1.0 and later requires a commercial
+license from Atoms AI above 10,000 active profiles in a month. An active
+profile is one person whose agent used ContextDB that month, counted once.
+At or below that line, use stays free, including commercial use and
+self-hosting. The free grant does not depend on a license key inside the
+program, and it does not depend on revenue.
+
+The 1.0 `LICENSE` file will carry this split, after legal review of the
+text. Until that tag exists, Apache-2.0 is the grant for the code in this
+repository.
+
+New substantial contributions are accepted only under the CLA in
+[CONTRIBUTING.md](CONTRIBUTING.md), so Atoms AI can license future work on
+these terms. The CLA does not revoke Apache-2.0 on anything already released.
+
+## Trademark
+
+**ContextDB** and the ContextDB logo are trademarks of Atoms AI. The
+Apache License is a copyright and patent license; it does not grant
+rights to the marks (Apache License §6).
+
+You may:
+
+- Say you use ContextDB, cite the project, and link to this repository.
+- State compatibility ("works with ContextDB") when that is true.
+
+You may not, without a commercial agreement with Atoms AI:
+
+- Offer ContextDB as a hosted or managed service, or resell it as part
+  of a service, under the ContextDB name or branding.
+- Use ContextDB or a confusingly similar mark as the name of a competing
+  product, hosted service, or company.
+- Use the logo or word mark to imply endorsement by Atoms AI.
+- Register domains, social handles, or trademarks that trade on the mark.
+
+## Resale and commercial agreements
+
+For releases through `v0.4.8`, Apache-2.0 permits commercial use,
+modification, redistribution, embedding, and hosted use of the code,
+subject to its terms. No separate copyright license is required for those
+uses.
+
+If your company wants to use the ContextDB name or logo for a hosted offering,
+or wants a supported OEM arrangement, Cloud service, support, or a trademark
+agreement, contact **contextdb@atomsai.com**. Organizations above 10,000 active profiles in a month should use the
+same address for the commercial license that applies to 1.0 and later.
+
+## Attribution (optional)
+
+Apache-2.0 does not require a public credit line. If you ship a product
+that uses ContextDB and want to credit the project, the preferred form
+is a visible **Built with ContextDB** link to
+https://github.com/atomsai/contextdb. That is a courtesy, not a license
+condition. Redistributors must still keep `LICENSE` and `NOTICE` as
+Apache requires.
+
+Research citations should use the paper:
+https://zenodo.org/records/19647089

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pycontextdb
-Version: 0.4.6
+Version: 0.4.8
 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
@@ -74,10 +74,10 @@ Description-Content-Type: text/markdown
 <p align="center">
   <a href="https://pypi.org/project/pycontextdb/"><img src="https://img.shields.io/pypi/v/pycontextdb.svg" alt="PyPI version"></a>
   <a href="https://github.com/atomsai/contextdb/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg" alt="License: Apache 2.0"></a>
-  <a href="https://github.com/atomsai/contextdb/blob/main/tests/"><img src="https://img.shields.io/badge/tests-195%20passing-brightgreen.svg" alt="Tests"></a>
+  <a href="https://github.com/atomsai/contextdb/actions/workflows/ci.yml"><img src="https://github.com/atomsai/contextdb/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI"></a>
   <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.10%2B-blue.svg" alt="Python 3.10+"></a>
   <a href="https://github.com/atomsai/contextdb/blob/main/pyproject.toml"><img src="https://img.shields.io/badge/mypy-strict-blue.svg" alt="Type Checked"></a>
-  <a href="https://github.com/atomsai/contextdb/blob/main/benchmarks/run_benchmarks.py"><img src="https://img.shields.io/badge/search_p95-%3C5ms_%40_5K-brightgreen.svg" alt="Search p95"></a>
+  <a href="https://github.com/atomsai/contextdb/blob/main/benchmarks/run_benchmarks.py"><img src="https://img.shields.io/badge/search_p95-18ms_%40_5K_(mock_embedder)-blue.svg" alt="Search p95 18 ms at 5K memories with the mock embedder"></a>
   <a href="https://github.com/atomsai/contextdb/stargazers"><img src="https://img.shields.io/github/stars/atomsai/contextdb?style=social" alt="GitHub stars"></a>
 </p>
 
@@ -91,20 +91,18 @@ Description-Content-Type: text/markdown
 
 ## At a glance
 
-<p align="center">
-  <img src="https://raw.githubusercontent.com/atomsai/contextdb/main/assets/performance.png" alt="Performance at a glance — search p50 3.4ms, 1,930 writes/sec, 112K PII/sec, 5.0ms p95 at 5K memories, 800K vectors/sec index build, 82/82 tests" width="100%">
-</p>
-
 | | |
 |---|---|
-| **Write throughput** | 1,900+ memories/sec |
-| **Search latency (1K memories)** | p50 **3.4ms** · p95 **4.5ms** |
-| **Search latency (5K memories)** | p50 **3.9ms** · p95 **5.0ms** |
-| **Vector search (10K × 1,536d)** | p50 **0.8ms** · p95 **1.0ms** |
+| **Write throughput** | about 1,600 to 1,800 memories/sec |
+| **Search latency (1K memories)** | p50 **11 ms** · p95 **12 to 14 ms** |
+| **Search latency (5K memories)** | p50 **17 ms** · p95 **18 ms** |
+| **Vector search (10K × 1,536d)** | p50 **0.8 ms** · p95 **1.0 ms** |
 | **PII detection** | 100,000+ texts/sec |
-| **Tests** | 195 passing (incl. 34 trust-model acceptance evals) · ruff clean · mypy `--strict` clean |
+| **Tests** | full suite and trust-model acceptance evals in CI on every pull request · ruff · mypy `--strict` |
 | **Dependencies** | SQLite + NumPy (FAISS / Postgres optional) |
 
+Measured in October 2026 with `python benchmarks/run_benchmarks.py` on an Apple M4 Max, Python 3.12, SQLite, and the mock embedder, so no model call is included. These numbers are the SDK's own overhead; a real embedding model adds its own latency.
+
 Those search numbers are **SQLite + the in-repo mock embedder**. A recall
 that embeds the query with OpenAI is typically **100–300ms** before the
 store is touched. Use `embedding_cache_size`, `pip install 'pycontextdb[local]'`,
@@ -120,16 +118,16 @@ Speed is table stakes. The production failure that gets agents fired is **acting
 
 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 severs graph edges without touching other users' memories, 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]`), **exact-identifier recall** (order numbers and SKUs are matched as whole tokens even when vector similarity misses them), **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, write p95 about 1 ms locally in the bake-off), **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 removes what the user added to shared entities, 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:
+The fabrication benchmark ships in the repository, and a test checks it on every pull request. Both arms use the same store, the same mock embedder, and the same scripted utterance policy; the only difference is the trust model:
 
 | Arm | Fabrication rate (lower=better) | Recall accuracy | Temporal supersede | Over-refusal | Write p95 |
 | --- | --- | --- | --- | --- | --- |
-| `contextdb-trust` | **0%** | **100%** | yes | no | 1.5ms |
-| `raw-store-baseline` (untyped control) | 50% | 88% | NO | no | 0.9ms |
+| `contextdb-trust` | **0%** | **100%** | yes | no | 0.99 ms |
+| `raw-store-baseline` (untyped control) | 50% | 88% | NO | no | 0.45 ms |
 
-Traps: wish-vs-fact, temporal move, prompt injection, PII redaction, cross-tenant bleed, negation, quantity update, over-refusal. Run it: `python benchmarks/trust_bakeoff.py` — acceptance evals live in `tests/evals/`. Mem0/Zep/Letta/supermemory arms implement the `MemoryArm` protocol and plug into the same harness.
+Traps: wish-vs-fact, temporal move, prompt injection, PII redaction, cross-tenant bleed, negation, quantity update, over-refusal. Run it with `python benchmarks/trust_bakeoff.py`. These eight synthetic traps are regression evidence inside the harness, not a measure of production behavior, and no other memory product has been run through it. Another system can be compared by implementing the `MemoryArm` protocol. The acceptance evals live in `tests/evals/`.
 
 ---
 
@@ -507,49 +505,44 @@ Five layers, one dependency. Every component is modular, testable, and replaceab
 
 ## Benchmarks
 
-<p align="center">
-  <img src="https://raw.githubusercontent.com/atomsai/contextdb/main/assets/benchmarks.png" alt="ContextDB v0.1.0 performance dashboard — search p50 3.4ms, 1,930 writes/sec, 112K PII/sec, 82/82 tests" width="100%">
-</p>
-
-Six workloads, all hermetic, all reproducible. No API keys, no network, no cached results — just `python benchmarks/run_benchmarks.py`.
+Six workloads, all hermetic and reproducible: no API keys, no network, no cached results. Run `python benchmarks/run_benchmarks.py`. The numbers below are from October 2026 on an Apple M4 Max with Python 3.12, SQLite, the mock embedder, and no FAISS. They measure the SDK's own overhead; a real embedding model adds its own latency.
 
 ### 1. Write throughput
 
-1,000 sequential `add()` calls including Pydantic validation, embedding, SQLite INSERT, and vector-index update.
+1,000 sequential `add()` calls including Pydantic validation, embedding, trust checks, SQLite INSERT, and vector-index update.
 
 ```
-Throughput:           1,930 writes/sec
-Average per write:    0.52ms
+Throughput:           about 1,600 to 1,800 writes/sec
+Average per write:    0.6ms
 ```
 
-### 2. Search latency — 100 queries against 1,000 memories
+### 2. Search latency: 100 queries against 1,000 memories
 
 ```
-p50:    3.40ms
-p95:    4.54ms
-p99:    4.75ms
-Mean:   3.59ms
+p50:    11.0ms
+p95:    14.3ms
+p99:    21.1ms
+Mean:   11.7ms
 ```
 
-Target was <100ms p95. We hit it by an order of magnitude with room to spare.
+Search includes PII redaction of the query, vector and graph fusion, salience, the trust filter, and the read audit.
 
 ### 3. Search latency vs scale
 
-Latency grows sub-linearly; write cost stays flat until the vector index rebuilds.
-
 | Memories | Add (ms/op) | Search p50 | Search p95 |
 |---:|---:|---:|---:|
-| 100 | 0.47ms | 3.26ms | 4.25ms |
-| 500 | 0.45ms | 3.59ms | 4.16ms |
-| 1,000 | 0.43ms | 3.50ms | 4.24ms |
-| 5,000 | 0.53ms | 3.89ms | 4.96ms |
+| 100 | 0.52ms | 9.2ms | 9.8ms |
+| 500 | 0.55ms | 10.0ms | 11.6ms |
+| 1,000 | 0.55ms | 11.1ms | 14.3ms |
+| 5,000 | 0.55ms | 17.2ms | 17.8ms |
 
-### 4. PII detection & redaction — 1,000 texts
+### 4. PII detection & redaction: 1,000 texts
 
 ```
-Throughput:     111,745 texts/sec
+Throughput:     128,194 texts/sec
 Per text:       0.01ms
 Types covered:  EMAIL, PHONE, SSN, CREDIT_CARD
+                (ADDRESS and cued NAME with pii_detect_names_and_addresses=True)
 ```
 
 Correctness spot-check:
@@ -559,29 +552,29 @@ Input:     Contact me at test@example.com or 555-123-4567. SSN: 123-45-6789
 Redacted:  Contact me at [EMAIL] or [PHONE]. SSN: [SSN]
 ```
 
-PII runs before content reaches storage. It never gets embedded. It never gets logged.
+PII runs before content reaches storage. It never gets embedded. It never gets logged. In encrypt mode, slot values that contain PII are stored as keyed fingerprints, so no plaintext email or phone number is written to disk.
 
-### 5. Vector index — 10K × 1,536-dim vectors
+### 5. Vector index: 10K × 1,536-dim vectors
 
 Pure-NumPy brute force, no FAISS dependency.
 
 ```
-Index build:               0.013s  (~800K vectors/sec)
-Search p50:                0.80ms
-Search p95:                1.04ms
+Index build:               0.011 to 0.017s
+Search p50:                0.8ms
+Search p95:                1.0ms
 Self-retrieval accuracy:   PASS
 ```
 
 FAISS is available as an optional backend for datasets beyond ~100K vectors.
 
-### 6. End-to-end — customer support agent
+### 6. End-to-end: customer support agent
 
-50 mixed factual/experiential memories, 20 semantic searches, one PII-laden write with redaction verification.
+50 mixed factual and experiential memories, 20 semantic searches, one PII-laden write with redaction verification.
 
 ```
-Add 50 memories:          0.03s  (1,849/sec)
-Search p50:               1.70ms
-PII add + redact:         0.76ms
+Add 50 memories:          0.03s  (about 1,540/sec)
+Search p50:               4.9ms
+PII add + redact:         1.4ms
 PII correctly redacted:   PASS
 ```
 
@@ -592,7 +585,7 @@ Input:    Customer John Smith, email john@acme.com, SSN 123-45-6789 called about
 Stored:   Customer John Smith, email [EMAIL], SSN [SSN] called about billing
 ```
 
-Numbers above are from a MacBook-class laptop with no FAISS. Rerun `python benchmarks/run_benchmarks.py` on your own hardware — the script prints everything you see here.
+Rerun `python benchmarks/run_benchmarks.py` on your own hardware; the script prints everything shown here.
 
 ---
 

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

@@ -8,10 +8,10 @@
 <p align="center">
   <a href="https://pypi.org/project/pycontextdb/"><img src="https://img.shields.io/pypi/v/pycontextdb.svg" alt="PyPI version"></a>
   <a href="https://github.com/atomsai/contextdb/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg" alt="License: Apache 2.0"></a>
-  <a href="https://github.com/atomsai/contextdb/blob/main/tests/"><img src="https://img.shields.io/badge/tests-195%20passing-brightgreen.svg" alt="Tests"></a>
+  <a href="https://github.com/atomsai/contextdb/actions/workflows/ci.yml"><img src="https://github.com/atomsai/contextdb/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI"></a>
   <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.10%2B-blue.svg" alt="Python 3.10+"></a>
   <a href="https://github.com/atomsai/contextdb/blob/main/pyproject.toml"><img src="https://img.shields.io/badge/mypy-strict-blue.svg" alt="Type Checked"></a>
-  <a href="https://github.com/atomsai/contextdb/blob/main/benchmarks/run_benchmarks.py"><img src="https://img.shields.io/badge/search_p95-%3C5ms_%40_5K-brightgreen.svg" alt="Search p95"></a>
+  <a href="https://github.com/atomsai/contextdb/blob/main/benchmarks/run_benchmarks.py"><img src="https://img.shields.io/badge/search_p95-18ms_%40_5K_(mock_embedder)-blue.svg" alt="Search p95 18 ms at 5K memories with the mock embedder"></a>
   <a href="https://github.com/atomsai/contextdb/stargazers"><img src="https://img.shields.io/github/stars/atomsai/contextdb?style=social" alt="GitHub stars"></a>
 </p>
 
@@ -25,20 +25,18 @@
 
 ## At a glance
 
-<p align="center">
-  <img src="https://raw.githubusercontent.com/atomsai/contextdb/main/assets/performance.png" alt="Performance at a glance — search p50 3.4ms, 1,930 writes/sec, 112K PII/sec, 5.0ms p95 at 5K memories, 800K vectors/sec index build, 82/82 tests" width="100%">
-</p>
-
 | | |
 |---|---|
-| **Write throughput** | 1,900+ memories/sec |
-| **Search latency (1K memories)** | p50 **3.4ms** · p95 **4.5ms** |
-| **Search latency (5K memories)** | p50 **3.9ms** · p95 **5.0ms** |
-| **Vector search (10K × 1,536d)** | p50 **0.8ms** · p95 **1.0ms** |
+| **Write throughput** | about 1,600 to 1,800 memories/sec |
+| **Search latency (1K memories)** | p50 **11 ms** · p95 **12 to 14 ms** |
+| **Search latency (5K memories)** | p50 **17 ms** · p95 **18 ms** |
+| **Vector search (10K × 1,536d)** | p50 **0.8 ms** · p95 **1.0 ms** |
 | **PII detection** | 100,000+ texts/sec |
-| **Tests** | 195 passing (incl. 34 trust-model acceptance evals) · ruff clean · mypy `--strict` clean |
+| **Tests** | full suite and trust-model acceptance evals in CI on every pull request · ruff · mypy `--strict` |
 | **Dependencies** | SQLite + NumPy (FAISS / Postgres optional) |
 
+Measured in October 2026 with `python benchmarks/run_benchmarks.py` on an Apple M4 Max, Python 3.12, SQLite, and the mock embedder, so no model call is included. These numbers are the SDK's own overhead; a real embedding model adds its own latency.
+
 Those search numbers are **SQLite + the in-repo mock embedder**. A recall
 that embeds the query with OpenAI is typically **100–300ms** before the
 store is touched. Use `embedding_cache_size`, `pip install 'pycontextdb[local]'`,
@@ -54,16 +52,16 @@ Speed is table stakes. The production failure that gets agents fired is **acting
 
 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 severs graph edges without touching other users' memories, 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]`), **exact-identifier recall** (order numbers and SKUs are matched as whole tokens even when vector similarity misses them), **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, write p95 about 1 ms locally in the bake-off), **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 removes what the user added to shared entities, 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:
+The fabrication benchmark ships in the repository, and a test checks it on every pull request. Both arms use the same store, the same mock embedder, and the same scripted utterance policy; the only difference is the trust model:
 
 | Arm | Fabrication rate (lower=better) | Recall accuracy | Temporal supersede | Over-refusal | Write p95 |
 | --- | --- | --- | --- | --- | --- |
-| `contextdb-trust` | **0%** | **100%** | yes | no | 1.5ms |
-| `raw-store-baseline` (untyped control) | 50% | 88% | NO | no | 0.9ms |
+| `contextdb-trust` | **0%** | **100%** | yes | no | 0.99 ms |
+| `raw-store-baseline` (untyped control) | 50% | 88% | NO | no | 0.45 ms |
 
-Traps: wish-vs-fact, temporal move, prompt injection, PII redaction, cross-tenant bleed, negation, quantity update, over-refusal. Run it: `python benchmarks/trust_bakeoff.py` — acceptance evals live in `tests/evals/`. Mem0/Zep/Letta/supermemory arms implement the `MemoryArm` protocol and plug into the same harness.
+Traps: wish-vs-fact, temporal move, prompt injection, PII redaction, cross-tenant bleed, negation, quantity update, over-refusal. Run it with `python benchmarks/trust_bakeoff.py`. These eight synthetic traps are regression evidence inside the harness, not a measure of production behavior, and no other memory product has been run through it. Another system can be compared by implementing the `MemoryArm` protocol. The acceptance evals live in `tests/evals/`.
 
 ---
 
@@ -441,49 +439,44 @@ Five layers, one dependency. Every component is modular, testable, and replaceab
 
 ## Benchmarks
 
-<p align="center">
-  <img src="https://raw.githubusercontent.com/atomsai/contextdb/main/assets/benchmarks.png" alt="ContextDB v0.1.0 performance dashboard — search p50 3.4ms, 1,930 writes/sec, 112K PII/sec, 82/82 tests" width="100%">
-</p>
-
-Six workloads, all hermetic, all reproducible. No API keys, no network, no cached results — just `python benchmarks/run_benchmarks.py`.
+Six workloads, all hermetic and reproducible: no API keys, no network, no cached results. Run `python benchmarks/run_benchmarks.py`. The numbers below are from October 2026 on an Apple M4 Max with Python 3.12, SQLite, the mock embedder, and no FAISS. They measure the SDK's own overhead; a real embedding model adds its own latency.
 
 ### 1. Write throughput
 
-1,000 sequential `add()` calls including Pydantic validation, embedding, SQLite INSERT, and vector-index update.
+1,000 sequential `add()` calls including Pydantic validation, embedding, trust checks, SQLite INSERT, and vector-index update.
 
 ```
-Throughput:           1,930 writes/sec
-Average per write:    0.52ms
+Throughput:           about 1,600 to 1,800 writes/sec
+Average per write:    0.6ms
 ```
 
-### 2. Search latency — 100 queries against 1,000 memories
+### 2. Search latency: 100 queries against 1,000 memories
 
 ```
-p50:    3.40ms
-p95:    4.54ms
-p99:    4.75ms
-Mean:   3.59ms
+p50:    11.0ms
+p95:    14.3ms
+p99:    21.1ms
+Mean:   11.7ms
 ```
 
-Target was <100ms p95. We hit it by an order of magnitude with room to spare.
+Search includes PII redaction of the query, vector and graph fusion, salience, the trust filter, and the read audit.
 
 ### 3. Search latency vs scale
 
-Latency grows sub-linearly; write cost stays flat until the vector index rebuilds.
-
 | Memories | Add (ms/op) | Search p50 | Search p95 |
 |---:|---:|---:|---:|
-| 100 | 0.47ms | 3.26ms | 4.25ms |
-| 500 | 0.45ms | 3.59ms | 4.16ms |
-| 1,000 | 0.43ms | 3.50ms | 4.24ms |
-| 5,000 | 0.53ms | 3.89ms | 4.96ms |
+| 100 | 0.52ms | 9.2ms | 9.8ms |
+| 500 | 0.55ms | 10.0ms | 11.6ms |
+| 1,000 | 0.55ms | 11.1ms | 14.3ms |
+| 5,000 | 0.55ms | 17.2ms | 17.8ms |
 
-### 4. PII detection & redaction — 1,000 texts
+### 4. PII detection & redaction: 1,000 texts
 
 ```
-Throughput:     111,745 texts/sec
+Throughput:     128,194 texts/sec
 Per text:       0.01ms
 Types covered:  EMAIL, PHONE, SSN, CREDIT_CARD
+                (ADDRESS and cued NAME with pii_detect_names_and_addresses=True)
 ```
 
 Correctness spot-check:
@@ -493,29 +486,29 @@ Input:     Contact me at test@example.com or 555-123-4567. SSN: 123-45-6789
 Redacted:  Contact me at [EMAIL] or [PHONE]. SSN: [SSN]
 ```
 
-PII runs before content reaches storage. It never gets embedded. It never gets logged.
+PII runs before content reaches storage. It never gets embedded. It never gets logged. In encrypt mode, slot values that contain PII are stored as keyed fingerprints, so no plaintext email or phone number is written to disk.
 
-### 5. Vector index — 10K × 1,536-dim vectors
+### 5. Vector index: 10K × 1,536-dim vectors
 
 Pure-NumPy brute force, no FAISS dependency.
 
 ```
-Index build:               0.013s  (~800K vectors/sec)
-Search p50:                0.80ms
-Search p95:                1.04ms
+Index build:               0.011 to 0.017s
+Search p50:                0.8ms
+Search p95:                1.0ms
 Self-retrieval accuracy:   PASS
 ```
 
 FAISS is available as an optional backend for datasets beyond ~100K vectors.
 
-### 6. End-to-end — customer support agent
+### 6. End-to-end: customer support agent
 
-50 mixed factual/experiential memories, 20 semantic searches, one PII-laden write with redaction verification.
+50 mixed factual and experiential memories, 20 semantic searches, one PII-laden write with redaction verification.
 
 ```
-Add 50 memories:          0.03s  (1,849/sec)
-Search p50:               1.70ms
-PII add + redact:         0.76ms
+Add 50 memories:          0.03s  (about 1,540/sec)
+Search p50:               4.9ms
+PII add + redact:         1.4ms
 PII correctly redacted:   PASS
 ```
 
@@ -526,7 +519,7 @@ Input:    Customer John Smith, email john@acme.com, SSN 123-45-6789 called about
 Stored:   Customer John Smith, email [EMAIL], SSN [SSN] called about billing
 ```
 
-Numbers above are from a MacBook-class laptop with no FAISS. Rerun `python benchmarks/run_benchmarks.py` on your own hardware — the script prints everything you see here.
+Rerun `python benchmarks/run_benchmarks.py` on your own hardware; the script prints everything shown here.
 
 ---
 

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