pycontextdb 0.3.2__tar.gz → 0.4.0__tar.gz

{pycontextdb-0.3.2 → pycontextdb-0.4.0}/.github/workflows/ci.yml

@@ -105,5 +105,7 @@ jobs:
         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.2 → pycontextdb-0.4.0}/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## 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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pycontextdb
-Version: 0.3.2
+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

{pycontextdb-0.3.2 → 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

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

@@ -10,6 +10,11 @@ from contextdb.core.config import ContextDBConfig
 from contextdb.core.exceptions import (
     ConfigError,
     ContextDBError,
+    EvolutionConflictError,
+    EvolutionOperationConflictError,
+    EvolutionTargetNotFoundError,
+    EvolutionTargetRequiredError,
+    MemoryEvolutionError,
     MemoryNotFoundError,
     PrivacyError,
     ScopeConflictError,
@@ -21,7 +26,10 @@ from contextdb.core.exceptions import (
 from contextdb.core.models import (
     Edge,
     Entity,
+    EvolutionOperation,
+    EvolutionOutcome,
     MemoryConsistencyToken,
+    MemoryEvolutionResult,
     MemoryItem,
     MemoryStatus,
     MemoryType,
@@ -33,7 +41,7 @@ from contextdb.core.policy import TrustPolicy
 from contextdb.pool import ContextDBPool
 from contextdb.utils.embeddings import EmbeddingProvider
 
-__version__ = "0.3.2"
+__version__ = "0.4.0"
 
 __all__ = [
     "Clock",
@@ -45,7 +53,15 @@ __all__ = [
     "Edge",
     "EmbeddingProvider",
     "Entity",
+    "EvolutionConflictError",
+    "EvolutionOperationConflictError",
+    "EvolutionOperation",
+    "EvolutionOutcome",
+    "EvolutionTargetNotFoundError",
+    "EvolutionTargetRequiredError",
     "FrozenClock",
+    "MemoryEvolutionError",
+    "MemoryEvolutionResult",
     "MemoryItem",
     "MemoryConsistencyToken",
     "MemoryNotFoundError",