pycontextdb 0.3.0__tar.gz → 0.4.0__tar.gz

pycontextdb-0.4.0/.github/pull_request_template.md

@@ -0,0 +1,28 @@
+## Summary
+
+<!-- What changed, and why. Evals win over prose. -->
+
+## Open-core classification
+
+Select exactly one and justify placement against `OPEN_CORE.md`.
+
+- [ ] No capability change — docs/tests/build/maintenance only.
+- [ ] Semantic — portable offline correctness.
+- [ ] Contract — interface/schema/protocol.
+- [ ] Reference — minimal single-node implementation.
+- [ ] Operated — multi-tenant/process/region/people/SLA coordination; this PR
+      does not belong in the public SDK.
+
+**Why this repository is the correct side of the boundary:**
+
+<!-- For mixed features, identify the open contract and private implementation. -->
+
+## Checklist
+
+- [ ] `pytest tests/evals/ -v` passes, or I explain why not.
+- [ ] `python scripts/check_open_core_boundary.py` passes.
+- [ ] `contextdb.init`, `factual.add`, `factual.recall`, and `search` keep working; new fields have backward-compatible defaults.
+- [ ] No new runtime dependency without a discussion first.
+- [ ] No hosted auth, entitlements, billing, control-plane, enterprise,
+      deployment, migration-orchestration, or fleet code entered the SDK.
+- [ ] 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 → pycontextdb-0.4.0}/.github/workflows/ci.yml

@@ -54,6 +54,12 @@ jobs:
           python -m pip install --upgrade pip
           pip install -e ".[dev]"
 
+      - name: Open-core boundary
+        run: python scripts/check_open_core_boundary.py
+        env:
+          CONTEXTDB_REQUIRE_PR_CLASSIFICATION: ${{ github.event_name == 'pull_request' }}
+          CONTEXTDB_PR_BODY: ${{ github.event.pull_request.body }}
+
       - name: Lint with ruff
         run: ruff check .
 
@@ -62,3 +68,44 @@ jobs:
 
       - name: Run tests
         run: pytest
+
+  postgres:
+    name: Postgres integration
+    runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_USER: postgres
+          POSTGRES_PASSWORD: postgres
+          POSTGRES_DB: postgres
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U postgres"
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 10
+    env:
+      CONTEXTDB_TEST_POSTGRES_URL: postgresql://postgres:postgres@127.0.0.1:5432/postgres
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      - name: Install package with Postgres support
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev,postgres]"
+
+      - name: Run real Postgres tests
+        run: |
+          pytest \
+            tests/unit/test_postgres_concurrency.py \
+            tests/unit/test_postgres_connector.py \
+            tests/unit/test_postgres_memory_evolution.py \
+            tests/unit/test_scoped_id_access.py \
+            tests/unit/test_vector_scope.py

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

@@ -2,6 +2,57 @@
 
 ## Unreleased
 
+## 0.4.0 — 2026-08-23
+
+- Explicit deterministic `add` / `update` / `delete` / `noop` memory
+  evolution with public result and error contracts, lineage, scoped hard
+  deletion, content-free NOOP audit, and post-commit consistency tokens.
+  Postgres applies memory rows, revisions, and audit in one transaction;
+  ordinary `factual.add()` remains compatible and same-speaker duplicates
+  are now true no-ops.
+- Public connector contracts plus a minimal local PostgreSQL/Supabase reader
+  with stable timestamp-plus-key cursors and soft-delete mapping. Hosts retain
+  control of credentials, scheduling, retries, and memory writes.
+
+## 0.3.2 — 2026-08-20
+
+### Added
+
+- Host-owned asyncpg pools and embedding providers can be shared safely across
+  project runtimes without being closed on runtime eviction.
+- Mutations return project-scoped memory versions and Postgres WAL positions;
+  reads can require those floors and fail closed when unavailable.
+- Embeddings carry model identity and distinct query/document roles, including
+  role-aware OpenAI-compatible transport.
+- Project-scoped vector and immutable item caches remove redundant warm recall
+  queries while preserving user isolation and cross-worker coherence.
+- A durable read-audit hook lets hosted runtimes persist exact PII-processed
+  recall evidence outside the synchronous SDK audit chain.
+- The open-core constitution, PR classification, CI source scanner, and release
+  gate prevent operated Cloud capabilities from entering the Apache package.
+
+### Fixed
+
+- Memory mutation, project/global revision changes, and write audit now commit
+  in one Postgres transaction.
+- Advisory locks execute their protected work on the same transaction-bound
+  connection instead of accidentally hopping pool connections.
+- Public commercial-use guidance now matches Apache-2.0 while preserving
+  ContextDB trademark controls.
+
+`contextdb.init`, `factual.add`, `factual.recall`, and `search` remain
+backward-compatible. All new host-sharing and consistency arguments are
+optional.
+
+## 0.3.1 — 2026-08-18
+
+### Fixed
+
+- README links to docs/COMMERCIAL.md/CONTRIBUTING.md are absolute GitHub
+  URLs — relative targets 404 on the PyPI project page.
+- `scripts/check_release.py` now scans the built package description for
+  relative Markdown links so this fails in CI before it reaches PyPI.
+
 ## 0.3.0 — 2026-08-18
 
 Host API scope hardening:

{pycontextdb-0.3.0 → pycontextdb-0.4.0}/COMMERCIAL.md

@@ -26,9 +26,13 @@ You may not, without a commercial agreement with Atoms AI:
 
 ## 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.
+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**.
 
 ## Attribution (optional)
 

{pycontextdb-0.3.0 → pycontextdb-0.4.0}/CONTRIBUTING.md

@@ -7,7 +7,10 @@ gates.
 ## What we accept here
 
 Trust and safety correctness, local runtime fixes, adapters, docs, and
-evals. Evals win over prose: `pytest tests/evals/ -v`.
+evals. Portable contracts and minimal single-node reference implementations
+also belong here. Classify every substantial change under
+[OPEN_CORE.md](OPEN_CORE.md). Evals win over prose:
+`pytest tests/evals/ -v`.
 
 We do **not** accept:
 
@@ -15,6 +18,9 @@ We do **not** accept:
   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
+- Hosted auth, tenancy, entitlements, billing, organization control-plane,
+  enterprise governance, managed-service, deployment, migration-orchestration,
+  or fleet code
 
 ## Contributor License Agreement
 

pycontextdb-0.4.0/OPEN_CORE.md

@@ -0,0 +1,80 @@
+# ContextDB open-core constitution
+
+**Status: binding for all future work.** Changes require an explicit
+architecture decision and maintainer approval.
+
+> Open the single-node semantics and reference engine. Keep multi-tenant coordination, operated guarantees, governance, and proof private.
+
+This repository is the public Apache-2.0 engine. It must remain complete,
+useful offline, inspectable, and safe without a hosted account, license key,
+paid flag, time bomb, or phone-home.
+
+Existing Apache grants are permanent. New code is reviewed prospectively
+against this constitution before merge and again before package publication.
+
+## Four change classes
+
+Every capability-changing contribution is classified as exactly one:
+
+1. **Semantic** — portable correctness required offline: open implementation.
+2. **Contract** — interface, schema, protocol, or compatibility test: open.
+3. **Reference** — minimal single-node implementation proving a contract: open.
+4. **Operated** — coordinates tenants, processes, regions, people, or an SLA:
+   private Cloud implementation, not this repository.
+
+Docs, tests, and maintenance with no capability change declare that explicitly.
+Mixed features are split. This repository may contain the contract and minimal
+reference implementation. Distributed schedulers, controllers, managed
+workers, deployment topology, and operations stay private.
+
+## What belongs here
+
+- Memory and epistemic data models.
+- `TrustPolicy`, act/ask/abstain, confirmation, and local explanation.
+- PII-before-embed, injection defenses, and public adversarial evals.
+- Local CRUD, SQLite, and a basic Postgres reference adapter.
+- Atomic mutation/version/audit behavior required for correct storage.
+- Deletion semantics and local verification.
+- Portable consistency-token, embedding-provider, and connector contracts.
+- Minimal reference implementations and compatibility tests.
+
+Safety and correctness are never commercially gated or intentionally weaker
+than the hosted service.
+
+## What does not belong here
+
+- Hosted gateway, tenancy, API-key auth, entitlements, quotas, billing, or
+  abuse controls.
+- Organization/project/team control plane or governance console.
+- Multi-worker routing, replica orchestration, failover, autoscaling, backups,
+  incidents, or availability guarantees.
+- Managed model fleet, batching service, backfill control, or deployment code.
+- Managed connector sync, checkpoints, retries, observability, or support SLAs.
+- Organization Action Ledger, signed compliance exports, or retention service.
+- Policy rollout/canary/approval controllers.
+- SSO, SCIM, KMS/BYOK, private networking, residency, or contractual controls.
+
+Thin generated Cloud clients, public API schemas, connector interfaces, and
+common community adapters are public distribution artifacts because they grow
+the ecosystem; they may live in separate public packages and contain no hosted
+implementation.
+
+## Contribution and release gate
+
+- Pull requests declare one change class and justify repository placement.
+- Ambiguous changes stop for boundary review; publication is never the default.
+- Contract tests may be shared; private implementations are not copied here.
+- Every PyPI release receives an open-core diff review.
+- `scripts/check_open_core_boundary.py` and CI enforce mechanical invariants.
+
+Private code can be opened later. An Apache grant cannot be clawed back.
+
+## Commercial model
+
+ContextDB Cloud sells operation, coordination, governance, and proof of this
+open correctness model. The SDK is not a crippled free tier. If Cloud cannot
+win while this engine is useful, Cloud must become stronger rather than making
+the SDK weaker.
+
+See [COMMERCIAL.md](COMMERCIAL.md) for trademark rules. Apache-2.0 permits
+commercial use of the code; it does not grant rights to ContextDB trademarks.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pycontextdb
-Version: 0.3.0
+Version: 0.4.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
@@ -74,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-139%20passing-brightgreen.svg" alt="Tests"></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://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>
@@ -102,7 +102,7 @@ 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** | 139 passing (incl. 34 trust-model acceptance evals) · ruff clean · mypy `--strict` clean |
+| **Tests** | 195 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
@@ -155,7 +155,7 @@ Databricks Lakebase gives agents a hard drive. ContextDB gives agents a brain.
 | PostgreSQL / MongoDB | Static rows; no lifecycle; no graph links | `FactualMemory` with formation, evolution, and consolidation |
 | S3 / flat files | Write-only archive; not queryable by meaning or time | `ExperientialMemory` for trajectories, reflections, and workflows |
 | Custom glue code | Brittle; rebuilt at every company; 2-4 engineering months | One `init()` call, one async SDK, one dependency |
-| *(nothing today)* | Agents never learn from outcomes | RL-trained memory manager (`ADD` / `UPDATE` / `DELETE` / `NOOP`) |
+| Ad hoc update/delete glue | Corrections overwrite history; deletion leaves vector residue | Deterministic `evolve()` operations with lineage, audit, and consistency results |
 | *(nothing today)* | Raw PII stored indefinitely; compliance risk | PII detection, typed TTLs, hash-chained audit log |
 
 ---
@@ -217,6 +217,43 @@ async def main() -> None:
 asyncio.run(main())
 ```
 
+### Explicit memory evolution
+
+When the caller already knows the operation, apply it directly:
+
+```python
+current = await db.factual.evolve(
+    "add",
+    "Customer prefers email.",
+    source="user_stated",
+    entity="user",
+    attribute="contact_preference",
+)
+assert current.memory is not None
+result = await db.factual.evolve(
+    "update",
+    "Customer prefers SMS, not email.",
+    source="user_stated",
+    target_memory_id=current.memory.id,
+)
+
+print(result.previous_memory_ids)
+print(result.memory.id)
+print(result.consistency_token.memory_version)
+```
+
+`evolve()` supports `add`, `update`, `delete`, and `noop`. Corrections create a
+successor and close the predecessor; they do not overwrite corrected content
+in place. Delete hard-removes the selected row and vector. Same-speaker
+duplicates are true no-ops and do not advance the memory version. The caller
+selects the operation; this path does not use an LLM planner or the optional RL
+manager.
+
+See the
+[explicit evolution contract](https://github.com/atomsai/contextdb/blob/main/docs/memory_evolution.md)
+for conflict, contested-slot, audit, scoping, and Postgres transaction
+semantics.
+
 ---
 
 ## Experiential memory
@@ -618,8 +655,8 @@ pip install 'pycontextdb[postgres]'
 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).
+See [docs/serve.md](https://github.com/atomsai/contextdb/blob/main/docs/serve.md), [docs/multi_tenant.md](https://github.com/atomsai/contextdb/blob/main/docs/multi_tenant.md),
+and [docs/trust_policy.md](https://github.com/atomsai/contextdb/blob/main/docs/trust_policy.md).
 
 ## License and attribution
 
@@ -628,14 +665,16 @@ 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
+contextdb@atomsai.com (see [COMMERCIAL.md](https://github.com/atomsai/contextdb/blob/main/COMMERCIAL.md)).
+The binding product boundary is documented in
+[OPEN_CORE.md](https://github.com/atomsai/contextdb/blob/main/OPEN_CORE.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).
-Substantial PRs need a CLA ([CONTRIBUTING.md](CONTRIBUTING.md)).
+Substantial PRs need a CLA ([CONTRIBUTING.md](https://github.com/atomsai/contextdb/blob/main/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:**

{pycontextdb-0.3.0 → pycontextdb-0.4.0}/README.md

@@ -8,7 +8,7 @@
 <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-139%20passing-brightgreen.svg" alt="Tests"></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://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>
@@ -36,7 +36,7 @@
 | **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** | 139 passing (incl. 34 trust-model acceptance evals) · ruff clean · mypy `--strict` clean |
+| **Tests** | 195 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
@@ -89,7 +89,7 @@ Databricks Lakebase gives agents a hard drive. ContextDB gives agents a brain.
 | PostgreSQL / MongoDB | Static rows; no lifecycle; no graph links | `FactualMemory` with formation, evolution, and consolidation |
 | S3 / flat files | Write-only archive; not queryable by meaning or time | `ExperientialMemory` for trajectories, reflections, and workflows |
 | Custom glue code | Brittle; rebuilt at every company; 2-4 engineering months | One `init()` call, one async SDK, one dependency |
-| *(nothing today)* | Agents never learn from outcomes | RL-trained memory manager (`ADD` / `UPDATE` / `DELETE` / `NOOP`) |
+| Ad hoc update/delete glue | Corrections overwrite history; deletion leaves vector residue | Deterministic `evolve()` operations with lineage, audit, and consistency results |
 | *(nothing today)* | Raw PII stored indefinitely; compliance risk | PII detection, typed TTLs, hash-chained audit log |
 
 ---
@@ -151,6 +151,43 @@ async def main() -> None:
 asyncio.run(main())
 ```
 
+### Explicit memory evolution
+
+When the caller already knows the operation, apply it directly:
+
+```python
+current = await db.factual.evolve(
+    "add",
+    "Customer prefers email.",
+    source="user_stated",
+    entity="user",
+    attribute="contact_preference",
+)
+assert current.memory is not None
+result = await db.factual.evolve(
+    "update",
+    "Customer prefers SMS, not email.",
+    source="user_stated",
+    target_memory_id=current.memory.id,
+)
+
+print(result.previous_memory_ids)
+print(result.memory.id)
+print(result.consistency_token.memory_version)
+```
+
+`evolve()` supports `add`, `update`, `delete`, and `noop`. Corrections create a
+successor and close the predecessor; they do not overwrite corrected content
+in place. Delete hard-removes the selected row and vector. Same-speaker
+duplicates are true no-ops and do not advance the memory version. The caller
+selects the operation; this path does not use an LLM planner or the optional RL
+manager.
+
+See the
+[explicit evolution contract](https://github.com/atomsai/contextdb/blob/main/docs/memory_evolution.md)
+for conflict, contested-slot, audit, scoping, and Postgres transaction
+semantics.
+
 ---
 
 ## Experiential memory
@@ -552,8 +589,8 @@ pip install 'pycontextdb[postgres]'
 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).
+See [docs/serve.md](https://github.com/atomsai/contextdb/blob/main/docs/serve.md), [docs/multi_tenant.md](https://github.com/atomsai/contextdb/blob/main/docs/multi_tenant.md),
+and [docs/trust_policy.md](https://github.com/atomsai/contextdb/blob/main/docs/trust_policy.md).
 
 ## License and attribution
 
@@ -562,14 +599,16 @@ 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
+contextdb@atomsai.com (see [COMMERCIAL.md](https://github.com/atomsai/contextdb/blob/main/COMMERCIAL.md)).
+The binding product boundary is documented in
+[OPEN_CORE.md](https://github.com/atomsai/contextdb/blob/main/OPEN_CORE.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).
-Substantial PRs need a CLA ([CONTRIBUTING.md](CONTRIBUTING.md)).
+Substantial PRs need a CLA ([CONTRIBUTING.md](https://github.com/atomsai/contextdb/blob/main/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:**

{pycontextdb-0.3.0 → pycontextdb-0.4.0}/contextdb/__init__.py

@@ -10,16 +10,26 @@ from contextdb.core.config import ContextDBConfig
 from contextdb.core.exceptions import (
     ConfigError,
     ContextDBError,
+    EvolutionConflictError,
+    EvolutionOperationConflictError,
+    EvolutionTargetNotFoundError,
+    EvolutionTargetRequiredError,
+    MemoryEvolutionError,
     MemoryNotFoundError,
     PrivacyError,
     ScopeConflictError,
     SourceRequiredError,
+    StaleReadError,
     StorageError,
     UnauthorizedError,
 )
 from contextdb.core.models import (
     Edge,
     Entity,
+    EvolutionOperation,
+    EvolutionOutcome,
+    MemoryConsistencyToken,
+    MemoryEvolutionResult,
     MemoryItem,
     MemoryStatus,
     MemoryType,
@@ -29,8 +39,9 @@ from contextdb.core.models import (
 )
 from contextdb.core.policy import TrustPolicy
 from contextdb.pool import ContextDBPool
+from contextdb.utils.embeddings import EmbeddingProvider
 
-__version__ = "0.3.0"
+__version__ = "0.4.0"
 
 __all__ = [
     "Clock",
@@ -40,9 +51,19 @@ __all__ = [
     "ContextDBError",
     "ContextDBPool",
     "Edge",
+    "EmbeddingProvider",
     "Entity",
+    "EvolutionConflictError",
+    "EvolutionOperationConflictError",
+    "EvolutionOperation",
+    "EvolutionOutcome",
+    "EvolutionTargetNotFoundError",
+    "EvolutionTargetRequiredError",
     "FrozenClock",
+    "MemoryEvolutionError",
+    "MemoryEvolutionResult",
     "MemoryItem",
+    "MemoryConsistencyToken",
     "MemoryNotFoundError",
     "MemoryStatus",
     "MemoryType",
@@ -52,6 +73,7 @@ __all__ = [
     "RetentionPolicy",
     "ScopeConflictError",
     "SourceRequiredError",
+    "StaleReadError",
     "StorageError",
     "TrustPolicy",
     "UnauthorizedError",
@@ -70,6 +92,8 @@ def init(
     session_id: str | None = None,
     clock: Clock | None = None,
     trust_policy: TrustPolicy | None = None,
+    postgres_pool: Any | None = None,
+    embedding_provider: EmbeddingProvider | None = None,
     **kwargs: Any,
 ) -> ContextDB:
     """Create a :class:`ContextDB` client.
@@ -84,6 +108,10 @@ def init(
         config: Pre-built configuration. When ``None`` one is constructed
             from ``kwargs`` and environment variables prefixed with
             ``CONTEXTDB_``.
+        postgres_pool: Optional externally owned asyncpg pool. Valid only with
+            a PostgreSQL ``storage_url``. ContextDB never closes this pool.
+        embedding_provider: Optional externally owned provider shared by the
+            host. ContextDB uses but never closes this provider.
         **kwargs: Forwarded to :class:`ContextDBConfig` if ``config`` is
             not provided.
 
@@ -99,4 +127,6 @@ def init(
         session_id=session_id,
         clock=clock,
         trust_policy=trust_policy,
+        postgres_pool=postgres_pool,
+        embedding_provider=embedding_provider,
     )