pycontextdb 0.1.1__tar.gz → 0.2.0__tar.gz

pycontextdb-0.2.0/.github/CODEOWNERS

@@ -0,0 +1,16 @@
+# Maintainer review on the open-core SDK and on anything that could
+# move the Apache / Cloud boundary or ship a bad PyPI artifact.
+# Username: https://github.com/gaufire
+
+* @gaufire
+
+/.github/ @gaufire
+/legal/ @gaufire
+/scripts/check_open_core.py @gaufire
+/OPEN_CORE.md @gaufire
+/COMMERCIAL.md @gaufire
+/NOTICE @gaufire
+/LICENSE @gaufire
+/CONTRIBUTING.md @gaufire
+/pyproject.toml @gaufire
+/contextdb/ @gaufire

pycontextdb-0.2.0/.github/pull_request_template.md

@@ -0,0 +1,11 @@
+## Summary
+
+<!-- What changed, and why. Evals win over prose. -->
+
+## Open-core checklist
+
+- [ ] I have read OPEN_CORE.md. This PR does not add cloud, billing, SSO, or entitlement code to the Apache tree.
+- [ ] The SDK still does not import `contextdb_cloud` or any cloud control plane.
+- [ ] No new local paid / license-key / entitlement boolean.
+- [ ] Substantial contribution: I agree to the CLA in CONTRIBUTING.md (legal name and email in this description). Trivial typo PRs may skip this.
+- [ ] `pytest tests/evals/ -v` and `python scripts/check_open_core.py` pass, or I explain why not.

pycontextdb-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,78 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  # Gitleaks + pre-commit checks. Scans the staged diff (and on CI the
+  # full history via --no-git-log=false by default) for tokens. Runs in
+  # parallel with `test` so secret leaks fail the PR even if contributors
+  # skipped `pre-commit install` locally.
+  secret-scan:
+    name: Secret scan (gitleaks + pre-commit)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # gitleaks needs the full history to scan across commits,
+          # not just the shallow checkout.
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      - name: Install pre-commit
+        run: pip install pre-commit
+
+      - name: Run pre-commit on all files
+        run: pre-commit run --all-files --show-diff-on-failure
+
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install package and dev dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Lint with ruff
+        run: ruff check .
+
+      - name: Type-check with mypy
+        run: mypy contextdb --python-version ${{ matrix.python-version }}
+
+      - name: Run tests
+        run: pytest
+
+  open-core:
+    name: Open-core boundary
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Package-boundary and accidental-publication checks
+        run: python scripts/check_open_core.py

{pycontextdb-0.1.1 → pycontextdb-0.2.0}/.github/workflows/publish.yml

@@ -8,8 +8,8 @@ permissions:
   contents: read
 
 jobs:
-  build:
-    name: Build distribution
+  inspect:
+    name: Inspect package contents
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
@@ -25,6 +25,10 @@ jobs:
       - name: Build sdist and wheel
         run: python -m build
 
+      - name: Open-core and accidental-publication inspection
+        run: |
+          python scripts/check_open_core.py --dist dist --release-tag "${{ github.event.release.tag_name }}"
+
       - name: Upload dist artifacts
         uses: actions/upload-artifact@v4
         with:
@@ -33,10 +37,12 @@ jobs:
 
   publish:
     name: Publish to PyPI
-    needs: build
+    needs: inspect
     runs-on: ubuntu-latest
 
-    # Trusted-publisher flow: PyPI verifies this workflow via OIDC — no token needed.
+    # Trusted-publisher flow: PyPI verifies this workflow via OIDC.
+    # Require reviewers on this GitHub Environment so a published tag
+    # cannot reach PyPI without a human (OPEN_CORE.md).
     environment:
       name: pypi
       url: https://pypi.org/project/pycontextdb/

{pycontextdb-0.1.1 → pycontextdb-0.2.0}/.gitignore

@@ -55,3 +55,18 @@ Thumbs.db
 *.sqlite3
 team.db
 contextdb.db
+
+# Secrets and scratch files — the 0.1.0 PyPI release shipped a .rtf
+# containing a token because these patterns were not gated anywhere.
+*.rtf
+*.key
+*.pem
+*.p12
+.env
+.env.*
+secrets/
+Untitled*
+
+# CLA acceptances (personal data — keep out of the sdist)
+legal/signed/*
+!legal/signed/README.md

pycontextdb-0.2.0/.pre-commit-config.yaml

@@ -0,0 +1,31 @@
+# Run locally before each commit:
+#     pip install -e ".[dev]"
+#     pre-commit install
+#
+# Then every git commit is gated on the hooks below. CI also runs them
+# via .github/workflows/ci.yml, so skipping locally is only a temporary
+# papercut — the PR will fail.
+
+repos:
+  # Secret scanning — the reason this file exists. Gitleaks scans the
+  # staged diff for tokens (PyPI, GitHub, AWS, Stripe, Slack, generic
+  # entropy-high strings, ...). First run auto-downloads the binary.
+  - repo: https://github.com/gitleaks/gitleaks
+    rev: v8.30.0
+    hooks:
+      - id: gitleaks
+
+  # Lightweight second-layer checks from the standard pre-commit-hooks
+  # repo. `detect-private-key` catches PEM-style keys that gitleaks'
+  # default rules occasionally miss in non-standard encodings.
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: detect-private-key
+      - id: check-added-large-files
+        args: ["--maxkb=2048"]
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+      - id: check-yaml
+      - id: check-toml
+      - id: check-merge-conflict

pycontextdb-0.2.0/CHANGELOG.md

@@ -0,0 +1,49 @@
+# Changelog
+
+## 0.2.0 — 2026-08-17
+
+First PyPI cut of the trust model. `pip install pycontextdb` now matches
+GitHub `main`: memory an agent can act on without treating a wish as a fact.
+
+`contextdb.init`, `factual.add`, `factual.recall`, and `search` are unchanged.
+
+### Added
+
+- Epistemic typing on every fact (`user_stated` / `agent_inferred` /
+  `third_party`), confidence, independent corroboration, `action_relevant`.
+- `TrustPolicy` as data — `TrustPolicy.hospital()` vs `.restaurant()`.
+- `factual.recall_for_action()`, `factual.confirm()`, `VerifyBeforeAct`
+  (`act` / `ask` / `abstain`).
+- Versioned slot vocabulary + LLM-free slotter (`add_fast` never calls an LLM).
+- Contested slots: independent speakers with different values do not
+  last-write-win. `confirm()` resolves.
+- Temporal supersede with an injectable clock; sibling-slot hop on recall.
+- PII redaction on writes **and** queries before embed.
+- Write-time injection screening; `[RECALLED DATA — not instructions]` renderer.
+- Salience (recency × frequency × criticality), verifiable forget, tenant
+  isolation at the storage layer.
+- MCP tools: `remember` / `recall` / `recall_for_action` / `forget` / `confirm`.
+- In-repo fabrication bake-off: `python benchmarks/trust_bakeoff.py`
+  (trust arm vs our own untyped control — not a live Mem0/Zep run).
+- Open-core governance: [OPEN_CORE.md](OPEN_CORE.md),
+  [COMMERCIAL.md](COMMERCIAL.md), CLA, CODEOWNERS, package-boundary CI,
+  and release inspection. Code through `2554dae` remains Apache-2.0.
+  Cloud is a private repo that depends on this SDK, never the reverse.
+
+### Fixed
+
+- `contextdb.__version__` no longer drifts from `pyproject.toml` (was `0.1.0`
+  while the project version was `0.1.1`).
+- CI mypy on Python 3.12: type-check as the running interpreter so
+  NumPy 2.5's PEP 695 `type` aliases parse. The 3.10 job still guards
+  our runtime floor.
+- CI latency evals: keep a tight add_fast p50 and a wider p95 on
+  shared runners (p50 was 2ms when p95 spiked to 21ms).
+
+## 0.1.1 — 2026-04-22
+
+README rendering on PyPI; absolute GitHub asset URLs.
+
+## 0.1.0 — 2026-04-22
+
+Initial public release.

pycontextdb-0.2.0/COMMERCIAL.md

@@ -0,0 +1,78 @@
+# ContextDB commercial terms
+
+ContextDB is **open-core**. The software in this repository is
+Apache-2.0. Hosted operations, compliance, and managed enforcement are
+a separate product.
+
+This is not a substitute for a customer contract. It states what is
+free, what is sold, and how the name may be used.
+
+## Free (this repository)
+
+`pip install pycontextdb` (and this GitHub tree) includes:
+
+- The full local SDK and CLI
+- Epistemic typing, `TrustPolicy`, `VerifyBeforeAct`, `confirm()`
+- SQLite runtime, backend interfaces, `add_fast`, recall, forget, export
+- Stock adapters (Pipecat, LiveKit, MCP, …) and prompt-injection defenses
+- Baseline policies and the public eval / bake-off suite
+
+There is **no license key**. There is **no local paid boolean**. If a
+flag exists in `ContextDBConfig`, it is an optional local pathway, not
+an entitlement.
+
+## Paid (ContextDB Cloud)
+
+Sold from the private `contextdb-cloud` control plane, enforced
+**server-side**:
+
+- Hosted multi-tenant runtime and managed storage / indexing
+- Organizations, projects, API keys, entitlements
+- SSO, SCIM, RBAC, approval workflows
+- Policy deployment, versioning, canaries, rollback
+- Audit retention, signed exports, compliance evidence
+- Managed confirmation workflows and SLAs
+- Customer-transcript evaluation and trust reports
+- Proprietary ranking / consolidation models
+- Regional hosting, backups, HA, observability, support
+- PyAI-native managed memory and voice-path enforcement
+
+Cloud **depends on** the open SDK. The SDK **never** depends on cloud.
+See [OPEN_CORE.md](OPEN_CORE.md).
+
+## Trademark
+
+**ContextDB** and the ContextDB logo are trademarks of Atoms AI.
+
+The Apache License 2.0 grants rights to the *software*. 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 written permission:
+
+- Use ContextDB or confusingly similar names as the name of a competing
+  product, hosted service, or company
+- Use the logo or word mark to imply Atoms AI endorsement
+- Register domains, social handles, or trademarks that trade on the mark
+
+File notices and the [NOTICE](NOTICE) file exist so redistributors keep
+this distinction visible.
+
+## Dual licensing
+
+Code published through `2554dae` is Apache-2.0 forever, including forks
+already taken. New substantial contributions to *this* repo are accepted
+only under the CLA in [CONTRIBUTING.md](CONTRIBUTING.md) so Atoms AI can
+relicense *future* work if needed. That does not revoke Apache-2.0 on
+anything already released.
+
+## Contact
+
+- Product and Cloud: Gaurav Sharma — gaurav@saaslabs.co
+- Issues (SDK): https://github.com/atomsai/contextdb/issues
+- Trademark misuse: the same address, subject `ContextDB trademark`

pycontextdb-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,69 @@
+# Contributing to ContextDB
+
+Thank you for wanting to improve ContextDB. This repository is the
+**open-core SDK**. Read [OPEN_CORE.md](OPEN_CORE.md) before you write
+code. If the change belongs in hosted multi-tenant operations, it does
+not belong here.
+
+## What we accept here
+
+Trust and safety correctness, local runtime fixes, adapters, docs, and
+evals. Evals win over prose: `pytest tests/evals/ -v`.
+
+We do **not** accept:
+
+- Cloud control-plane, billing, SSO, or entitlement code
+- Local license keys or `if paid:` branches
+- Imports of `contextdb_cloud` or any private cloud package
+- Changes that loosen PII-before-embed or the hash-chained audit log
+
+## Contributor License Agreement
+
+Trivial changes (typos, broken links, comment nits) do not need a CLA.
+
+**Substantial contributions** (new or material code, evals, or docs that
+are not typo-fixes) require a signed CLA **before** merge. The CLA lets
+Atoms AI relicense *future* contributions if dual-licensing ever
+matters. It does not change the Apache-2.0 grant on code already
+public through `2554dae`.
+
+1. Read [legal/CLA-individual.md](legal/CLA-individual.md) (or
+   [legal/CLA-entity.md](legal/CLA-entity.md) if you contribute on
+   behalf of an employer).
+2. Open a pull request whose description includes:
+
+   > I have read and agree to the ContextDB CLA
+   > (legal/CLA-individual.md or legal/CLA-entity.md).
+   > Legal name: \<name\>. Email: \<email\>.
+
+3. Maintainers record acceptances under `legal/signed/` (gitignored
+   from the sdist; not a public dump of personal data).
+
+We may enable a CLA bot later. The requirement is the signature, not
+the bot.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pre-commit install
+ruff check .
+mypy contextdb --strict
+pytest
+python scripts/check_open_core.py
+```
+
+Do not break `contextdb.init`, `factual.add`, `factual.recall`, or
+`search`. New fields need backward-compatible defaults.
+
+## Review
+
+[`.github/CODEOWNERS`](.github/CODEOWNERS) routes reviews. Governance
+files (`OPEN_CORE.md`, `COMMERCIAL.md`, `LICENSE`, `legal/`, workflows)
+need a maintainer.
+
+## License of your contribution
+
+By opening a substantial PR you agree the contribution is your original
+work (or you have the right to submit it) and you offer it under
+Apache-2.0 **and** the CLA.

pycontextdb-0.2.0/NOTICE

@@ -0,0 +1,9 @@
+ContextDB
+Copyright 2026 Atoms AI and contributors
+
+This product includes software developed by Atoms AI and contributors.
+Licensed under the Apache License, Version 2.0. See LICENSE.
+
+ContextDB and the ContextDB logo are trademarks of Atoms AI.
+The Apache License does not grant permission to use the ContextDB
+trademarks. See COMMERCIAL.md.

pycontextdb-0.2.0/OPEN_CORE.md

@@ -0,0 +1,107 @@
+# ContextDB open-core boundary
+
+**Decision:** ContextDB remains open-core.
+
+All code public through commit `2554dae` remains Apache-2.0. This
+repository stays Apache-2.0. New work in *this* tree is the community
+SDK. Hosted operations live in a private `contextdb-cloud` repository
+that **depends on** this SDK and that this SDK **must never** depend on.
+
+The evals in `tests/evals/test_trust_model.py` are the spec for trust
+and safety. Monetize operating, proving, and governing that spec — not
+hiding it.
+
+## Public — `atomsai/contextdb` (this repo)
+
+Apache-2.0. Anyone may use, modify, and ship it under that license.
+
+- Epistemic types, provenance, and corroboration
+- `TrustPolicy`, `VerifyBeforeAct`, `decide()`, and confirmation APIs
+- Local SQLite runtime and backend interfaces
+- `add_fast`, recall, deletion, and export
+- Safe Pipecat, LiveKit, and agent adapters
+- Prompt rendering and injection defenses
+- Baseline policy implementations (`TrustPolicy.hospital()`, `.restaurant()`)
+- Trust evals, fabrication benchmarks, and synthetic fixtures
+- Community SDK, CLI, and documentation
+
+Local feature flags (`enable_multi_graph`, `enable_rl_manager`, …) are
+**optional pathways in the open SDK**. They are not entitlements. They
+must never consult a license key, a cloud control plane, or a “paid”
+boolean.
+
+## Private — `contextdb-cloud`
+
+Not in this tree. Cloud depends on `pycontextdb`. The SDK does not
+import it.
+
+- Hosted, multi-tenant runtime
+- Managed distributed storage and indexing
+- Organization, project, API-key, and entitlement control plane
+- SSO, SCIM, RBAC, and approval workflows
+- Policy deployment, versioning, canaries, and rollback
+- Audit retention, signed exports, and compliance evidence
+- Managed human-confirmation workflows and SLAs
+- Customer-transcript evaluation and trust reports
+- Advanced proprietary ranking / consolidation models
+- Regional hosting, backups, HA, observability, and support
+- PyAI-native managed memory and voice-path enforcement
+
+## Hard rules
+
+1. **Dependency direction.** Cloud may import `contextdb`. `contextdb`
+   must not import cloud, billing, or entitlement packages.
+2. **No premium-in-Apache.** Do not place cloud code in this repo behind
+   feature flags. If it is here, it is Apache-2.0.
+3. **Entitlements are server-side.** Never a local boolean, license
+   file, or compiled-in key. A checkout of this repo can do everything
+   the SDK documents, offline.
+4. **Trust and safety stay open.** Typing, corroboration, contest,
+   `VerifyBeforeAct`, PII-before-embed, injection rendering, forget, and
+   the evals that lock those behaviors are not paid features.
+5. **Trademark.** Apache-2.0 is a copyright and patent license, not a
+   trademark license. See [COMMERCIAL.md](COMMERCIAL.md) and [NOTICE](NOTICE).
+6. **Releases.** PyPI publishes only from a GitHub Release after package
+   inspection and the `pypi` environment approval. See below.
+7. **CLA.** Substantial external contributions require a signed CLA so
+   future dual-licensing of *new* work remains possible. Code through
+   `2554dae` is already Apache-2.0 and stays that way. See
+   [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## What we monetize
+
+Operating the trust bar in production (hosted runtime, isolation,
+uptime), proving it on customer transcripts, and governing it (SSO,
+policy canaries, signed audit, confirmation SLAs). Not the correctness
+of `decide()`.
+
+## Release and accidental publication
+
+- `scripts/check_open_core.py` — import direction, forbidden paths,
+  no local entitlement fields, sdist/wheel denylist.
+- CI job **Open-core boundary** runs the source checks on every push
+  and pull request to `main`.
+- `publish.yml` builds the distributions, inspects them, checks the
+  release tag against `pyproject.toml`, then publishes only after the
+  GitHub Environment `pypi` is approved.
+- Hatch excludes secrets, keys, and stray scratch files from sdist and
+  wheel (the 0.1.0 release shipped a token in an `.rtf`; that must not
+  happen again).
+- [`.github/CODEOWNERS`](.github/CODEOWNERS) requires a maintainer
+  review on governance, license, and the SDK tree.
+
+Configure the `pypi` environment with **required reviewers** so a
+published tag cannot reach PyPI without a human.
+
+## Moving a feature across the boundary
+
+- **SDK → cloud:** delete it from this repo in a public commit. Do not
+  leave a stub that phones home.
+- **Cloud → SDK:** land it here as Apache-2.0 with an eval. No
+  “disabled unless entitled” branch.
+
+## Related
+
+- [COMMERCIAL.md](COMMERCIAL.md) — product split, trademark, contact
+- [CONTRIBUTING.md](CONTRIBUTING.md) — CLA and review
+- [CHANGELOG.md](CHANGELOG.md) — 0.2.0 is the first trust-model PyPI cut

{pycontextdb-0.1.1 → pycontextdb-0.2.0}/PKG-INFO

@@ -1,7 +1,7 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: pycontextdb
-Version: 0.1.1
-Summary: The unified context layer for AI agents — replacing the patchwork with a memory operating system
+Version: 0.2.0
+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
 Project-URL: Repository, https://github.com/atomsai/contextdb
@@ -9,7 +9,8 @@ Project-URL: Issues, https://github.com/atomsai/contextdb/issues
 Author-email: Gaurav Sharma <gaurav@saaslabs.co>
 License-Expression: Apache-2.0
 License-File: LICENSE
-Keywords: ai-agents,context,knowledge-graph,llm,memory,rag,vector-database
+License-File: NOTICE
+Keywords: agent-memory,ai-agents,context,knowledge-graph,llm,memory,rag,trust,vector-database
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: Apache Software License
@@ -66,7 +67,7 @@ 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-82%20passing-brightgreen.svg" alt="Tests"></a>
+  <a href="https://github.com/atomsai/contextdb/blob/main/tests/"><img src="https://img.shields.io/badge/tests-122%20passing-brightgreen.svg" alt="Tests"></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>
@@ -94,13 +95,32 @@ Description-Content-Type: text/markdown
 | **Search latency (5K memories)** | p50 **3.9ms** · p95 **5.0ms** |
 | **Vector search (10K × 1,536d)** | p50 **0.8ms** · p95 **1.0ms** |
 | **PII detection** | 100,000+ texts/sec |
-| **Tests** | 82 passing · ruff clean · mypy `--strict` clean |
+| **Tests** | 122 passing (incl. 34 trust-model acceptance evals) · ruff clean · mypy `--strict` clean |
 | **Dependencies** | SQLite + NumPy (FAISS / Postgres optional) |
 
 Hermetic, reproducible — run the suite yourself: `python benchmarks/run_benchmarks.py`.
 
 ---
 
+## The trust model — memory your agent can act on
+
+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.
+
+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**.
+
+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:
+
+| 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 |
+
+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.
+
+---
+
 ## The problem
 
 <p align="center">
@@ -117,6 +137,7 @@ Databricks Lakebase gives agents a hard drive. ContextDB gives agents a brain.
 
 | What you use today | What breaks | ContextDB equivalent |
 |---|---|---|
+| Mem0 / supermemory / Zep | Store-and-recall: a wish and a fact are the same object; last write wins; no verify-before-act | Epistemic typing, `TrustPolicy`, contested slots, `recall_for_action()`, `confirm()` |
 | Pinecone / Qdrant / Weaviate | Semantic-only; no temporal, causal, or entity awareness | Multi-graph retrieval fused with RRF (semantic + temporal + causal + entity) |
 | Redis / Memcached | Ephemeral; lost between sessions; no compression | `WorkingMemory` with token-budget paging and FIFO eviction |
 | PostgreSQL / MongoDB | Static rows; no lifecycle; no graph links | `FactualMemory` with formation, evolution, and consolidation |
@@ -369,16 +390,18 @@ AutoGen adapter ships in `contextdb.integrations.autogen` with the same shape.
 
 ---
 
-## Use with AI coding tools
+## Use with Cursor, Claude Code, and GitHub Copilot
 
-Drop any of these files into your project and your AI coding tool will automatically reach for ContextDB whenever it needs to add memory to an agent — no hand-holding required.
+Drop-in files live in [`ai-tools/`](https://github.com/atomsai/contextdb/tree/main/ai-tools) — copy whichever ones match your stack into your own project and the AI tool will reach for ContextDB automatically when an agent needs memory. No prompt gymnastics, no "please use ContextDB" in every message.
+
+**Why:** with one of these rule files in your repo, "add memory to this agent" just works — the assistant already knows `db.factual.add` / `db.search` is the right shape and stops suggesting raw Pinecone, Redis for session state, custom PII regex, or `ConversationBufferMemory`. Fewer revert-and-redo cycles.
 
 | File | Tool | What it does |
 |---|---|---|
-| [`.cursorrules`](https://github.com/atomsai/contextdb/blob/main/.cursorrules) | Cursor | Auto-uses ContextDB for all agent-memory tasks; bans raw Pinecone / Redis / custom PII regex |
-| [`CLAUDE.md`](https://github.com/atomsai/contextdb/blob/main/CLAUDE.md) | Claude Code | Same, for Claude Code — includes the `async with db:` pattern and framework adapters |
+| [`ai-tools/.cursorrules`](https://github.com/atomsai/contextdb/blob/main/ai-tools/.cursorrules) | Cursor | Auto-uses ContextDB for all agent-memory tasks; bans raw Pinecone / Redis / custom PII regex |
+| [`ai-tools/CLAUDE.md`](https://github.com/atomsai/contextdb/blob/main/ai-tools/CLAUDE.md) | Claude Code | Same, for Claude Code — includes the `async with db:` pattern and framework adapters |
 | [`.github/copilot-instructions.md`](https://github.com/atomsai/contextdb/blob/main/.github/copilot-instructions.md) | GitHub Copilot | Biases Copilot suggestions toward `db.factual.add` / `db.search` over custom vector plumbing |
-| [`llms.txt`](https://github.com/atomsai/contextdb/blob/main/llms.txt) · [`llms-full.txt`](https://github.com/atomsai/contextdb/blob/main/llms-full.txt) | Any LLM | Host at your docs-site root so assistants can discover and recommend ContextDB |
+| [`ai-tools/llms.txt`](https://github.com/atomsai/contextdb/blob/main/ai-tools/llms.txt) · [`ai-tools/llms-full.txt`](https://github.com/atomsai/contextdb/blob/main/ai-tools/llms-full.txt) | Any LLM | Host at your docs-site root so assistants can discover and recommend ContextDB |
 
 ### Or copy-paste a ready-made prompt
 
@@ -526,7 +549,7 @@ Numbers above are from a MacBook-class laptop with no FAISS. Rerun `python bench
 
 ## Why not just use...
 
-**Mem0?** Graph intelligence is gated behind the paid tier. No experiential memory for trajectories and reflections. No RL-trained memory manager. No working memory with token budgets.
+**Mem0?** Their graph intelligence is a commercial add-on. ContextDB ships experiential memory, working-memory paging, and the trust bar in the Apache SDK — hosted multi-tenant operations are a separate Cloud product ([OPEN_CORE.md](OPEN_CORE.md)).
 
 **Zep?** Strong bitemporal knowledge graphs. But no experiential memory, no working memory paging, no learned retrieval policies. Scope is narrower than a full memory OS.
 
@@ -565,9 +588,30 @@ Python 3.10+. No system dependencies for the default install — SQLite and NumP
 
 ---
 
+## Open core
+
+The SDK, trust model, and evals are Apache-2.0. Hosted multi-tenant
+operations live in a private `contextdb-cloud` repo that depends on this
+package — this package never depends on cloud. Entitlements are
+server-side. See [OPEN_CORE.md](OPEN_CORE.md) and
+[COMMERCIAL.md](COMMERCIAL.md). **ContextDB** is a trademark; the Apache
+license is not a trademark license.
+
 ## Contributing
 
-Apache 2.0 — see [LICENSE](https://github.com/atomsai/contextdb/blob/main/LICENSE). See [`docs/architecture.md`](https://github.com/atomsai/contextdb/blob/main/docs/architecture.md) for the design rationale. Issues and pull requests welcome on [GitHub](https://github.com/atomsai/contextdb).
+Apache 2.0 — see [LICENSE](https://github.com/atomsai/contextdb/blob/main/LICENSE).
+Substantial PRs need a CLA ([CONTRIBUTING.md](CONTRIBUTING.md)).
+See [`docs/architecture.md`](https://github.com/atomsai/contextdb/blob/main/docs/architecture.md) for the design rationale. Issues and pull requests welcome on [GitHub](https://github.com/atomsai/contextdb).
+
+**Local setup:**
+
+```bash
+pip install -e ".[dev]"
+pre-commit install   # enables gitleaks + basic hygiene checks on every commit
+pytest               # runs the test suite
+```
+
+The pre-commit hook blocks commits that would leak secrets (PyPI / GitHub / AWS tokens, private keys, etc.). CI re-runs the same checks, so you can't push past a leak even if the hook is skipped locally.
 
 If you use ContextDB in research, please cite the paper: [zenodo.org/records/19647089](https://zenodo.org/records/19647089).