pycontextdb 0.1.1__tar.gz → 0.3.0__tar.gz

pycontextdb-0.3.0/.github/CODEOWNERS

@@ -0,0 +1,14 @@
+# Maintainer review on the SDK and on anything that could ship a bad
+# PyPI artifact.
+# Username: https://github.com/gaufire
+
+* @gaufire
+
+/.github/ @gaufire
+/legal/ @gaufire
+/scripts/ @gaufire
+/NOTICE @gaufire
+/LICENSE @gaufire
+/CONTRIBUTING.md @gaufire
+/pyproject.toml @gaufire
+/contextdb/ @gaufire

pycontextdb-0.3.0/.github/pull_request_template.md

@@ -0,0 +1,10 @@
+## Summary
+
+<!-- What changed, and why. Evals win over prose. -->
+
+## Checklist
+
+- [ ] `pytest tests/evals/ -v` passes, or I explain why not.
+- [ ] `contextdb.init`, `factual.add`, `factual.recall`, and `search` keep working; new fields have backward-compatible defaults.
+- [ ] No new runtime dependency without a discussion first.
+- [ ] Substantial contribution: I agree to the CLA in CONTRIBUTING.md (legal name and email in this description). Trivial typo PRs may skip this.

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

@@ -0,0 +1,64 @@
+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

{pycontextdb-0.1.1 → pycontextdb-0.3.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: Release-safety inspection
+        run: |
+          python scripts/check_release.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.
     environment:
       name: pypi
       url: https://pypi.org/project/pycontextdb/

{pycontextdb-0.1.1 → pycontextdb-0.3.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.3.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, 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.3.0/CHANGELOG.md

@@ -0,0 +1,107 @@
+# Changelog
+
+## Unreleased
+
+## 0.3.0 — 2026-08-18
+
+Host API scope hardening:
+
+- Every non-health HTTP route now runs the configured authentication,
+  including `/v1/trust_policy` and `/mcp`.
+- An authenticated `user_id` (from `auth_hook`) can no longer be
+  overridden by the JSON body, `X-ContextDB-User` header, query string,
+  or MCP tool arguments; a conflict is a clear 400 (`ScopeConflictError`)
+  instead of a silent pick.
+- `/mcp` propagates the authenticated scope into every tool call.
+- ID-based `confirm` / `forget` verify the target belongs to the resolved
+  user scope; a foreign `memory_id` raises `MemoryNotFoundError`,
+  indistinguishable from a missing one. Same guarantee on SQLite and
+  Postgres stores.
+- Anonymous loopback serving is unchanged and documented as *not* an
+  authorization boundary.
+
+Decision-layer and PII correctness:
+
+- `VerifyBeforeAct.decide()` / `confirm_pending()` accept an additive
+  per-call `user_id=` for shared clients; a scoped client still rejects a
+  foreign one.
+- SEARCH and DECIDE audit entries now persist only the PII-processed form
+  of the query — the append-only chain must never hold raw PII.
+- `pii_action="encrypt"` fails closed: without a key, `PIIDetector`
+  raises `ConfigError` instead of degrading to redact, and encryption
+  mode can never persist plaintext annotation originals.
+
+Postgres and audit concurrency:
+
+- Vector candidates are scoped by SQL *before* ranking — a large foreign
+  scope can no longer starve an in-scope hit out of the candidate budget.
+- The process-local vector index tracks a global store revision; a write
+  from another instance or process forces a rebuild before the next
+  search (stale reads are no longer served indefinitely).
+- Slot operations on Postgres serialize across processes via a
+  transaction-scoped advisory lock; audit-chain appends serialize
+  in-process (SQLite) and cross-process (Postgres), so the hash chain
+  cannot fork.
+- Real Postgres concurrent-worker tests cover corroboration, slot
+  supersede, audit-chain integrity, and cross-worker recall
+  (`CONTEXTDB_TEST_POSTGRES_URL`).
+
+Host-adoption work:
+
+- `contextdb serve --http` (`pycontextdb[serve]`) — JSON API + `/mcp`, Bearer token, `auth_hook`.
+- Per-call `user_id=` on add/recall/confirm/forget. Shared `init()` is the multi-tenant path; `ContextDBPool` is LRU if you still need one client per user.
+- OSS `PostgresStore` for `postgresql://` URLs (`pycontextdb[postgres]`).
+- `factual.pending_confirmations()`, `forget(memory_id=)` / `forget(entity=, attribute=)`, `add_many` / `add_fast_many`.
+- Recall filters: `entity`, `min_confidence`, `include_third_party`.
+- `db.on(event, hook)` for write/recall/confirm/forget/injection_suspect.
+- Query embedding LRU cache; lexical recall if embedding fails.
+- Missing epistemic `source` warns in the SDK; HTTP/MCP remember return 400.
+- Docs: trust policy matrix, Postgres, multi-tenant, SQLite migrations.
+
+`contextdb.init`, `factual.add`, `factual.recall`, and `search` keep working. New keyword arguments are optional.
+
+## 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).
+- Contribution and release hygiene: CLA, CODEOWNERS, and release
+  inspection. Code through `2554dae` remains Apache-2.0.
+
+### 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.3.0/COMMERCIAL.md

@@ -0,0 +1,40 @@
+# 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.
+
+## 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
+
+If your company resells ContextDB as a service or as part of a service,
+or wants OEM/embedded licensing, support, or a trademark arrangement,
+contact **contextdb@atomsai.com** before you ship.
+
+## 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 — a courtesy, not a license
+condition. Redistributors must still keep `LICENSE` and `NOTICE` as
+Apache requires.

pycontextdb-0.3.0/CONTRIBUTING.md

@@ -0,0 +1,66 @@
+# Contributing to ContextDB
+
+Thank you for wanting to improve ContextDB. This repository is the
+Apache-2.0 ContextDB SDK: everything here works offline, with no feature
+gates.
+
+## 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:
+
+- Feature gates of any kind — no license keys, no `if paid:` branches,
+  no flags that only work against a hosted service
+- Imports of packages outside the declared dependencies
+- 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 grants
+the project broad rights to distribute your contribution, including under
+different license terms; code already released under Apache-2.0 stays
+Apache-2.0.
+
+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
+```
+
+Do not break `contextdb.init`, `factual.add`, `factual.recall`, or
+`search`. New fields need backward-compatible defaults.
+
+## Review
+
+[`.github/CODEOWNERS`](.github/CODEOWNERS) routes reviews. `LICENSE`,
+`NOTICE`, `legal/`, and the 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.3.0/NOTICE

@@ -0,0 +1,10 @@
+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. For trademark and commercial licensing (including resale
+or hosted services), contact contextdb@atomsai.com. See COMMERCIAL.md.

{pycontextdb-0.1.1 → pycontextdb-0.3.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.3.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
@@ -32,7 +33,10 @@ Requires-Dist: neo4j>=5.0; extra == 'all'
 Requires-Dist: pgvector>=0.2; extra == 'all'
 Requires-Dist: redis>=5.0; extra == 'all'
 Requires-Dist: sentence-transformers>=2.0; extra == 'all'
+Requires-Dist: starlette>=0.37; extra == 'all'
+Requires-Dist: uvicorn>=0.27; extra == 'all'
 Provides-Extra: dev
+Requires-Dist: httpx>=0.27; extra == 'dev'
 Requires-Dist: hypothesis>=6.0; extra == 'dev'
 Requires-Dist: mypy>=1.8; extra == 'dev'
 Requires-Dist: pre-commit>=3.0; extra == 'dev'
@@ -40,6 +44,7 @@ Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
 Requires-Dist: pytest-cov>=4.0; extra == 'dev'
 Requires-Dist: pytest>=7.0; extra == 'dev'
 Requires-Dist: ruff>=0.4; extra == 'dev'
+Requires-Dist: starlette>=0.37; extra == 'dev'
 Provides-Extra: faiss
 Requires-Dist: faiss-cpu>=1.7; extra == 'faiss'
 Provides-Extra: local
@@ -54,6 +59,9 @@ Requires-Dist: redis>=5.0; extra == 'redis'
 Provides-Extra: rl
 Requires-Dist: torch>=2.0; extra == 'rl'
 Requires-Dist: trl>=0.7; extra == 'rl'
+Provides-Extra: serve
+Requires-Dist: starlette>=0.37; extra == 'serve'
+Requires-Dist: uvicorn>=0.27; extra == 'serve'
 Description-Content-Type: text/markdown
 
 <p align="center">
@@ -66,7 +74,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-139%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 +102,37 @@ 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** | 139 passing (incl. 34 trust-model acceptance evals) · ruff clean · mypy `--strict` clean |
 | **Dependencies** | SQLite + NumPy (FAISS / Postgres optional) |
 
+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]'`,
+or `lexical_on_embed_failure` when the voice turn budget cannot wait.
+
 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 +149,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 +402,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 +561,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.
 
 **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 +600,53 @@ Python 3.10+. No system dependencies for the default install — SQLite and NumP
 
 ---
 
+## HTTP and multi-tenant hosts
+
+```bash
+pip install 'pycontextdb[serve]'
+contextdb serve --http --port 8080 --token "$CONTEXTDB_SERVE_TOKEN"
+```
+
+One process, many users: `init()` without `user_id`, then pass `user_id=`
+on each call (or `X-ContextDB-User` on HTTP). Postgres:
+
+```bash
+pip install 'pycontextdb[postgres]'
+```
+
+```python
+db = contextdb.init(storage_url="postgresql://...")
+```
+
+See [docs/serve.md](docs/serve.md), [docs/multi_tenant.md](docs/multi_tenant.md),
+and [docs/trust_policy.md](docs/trust_policy.md).
+
+## License and attribution
+
+The SDK, trust model, and evals are Apache-2.0 — everything described in
+this README ships in this tree, with no feature gates. **ContextDB** is a
+trademark; the Apache license is not a trademark license. Reselling
+ContextDB as a service, or as part of one, under the ContextDB name or
+branding requires a commercial agreement with Atoms AI — contact
+contextdb@atomsai.com (see [COMMERCIAL.md](COMMERCIAL.md)). A public
+credit line is optional — if you want one, use **Built with ContextDB**
+linking to this repository.
+
 ## 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).