feat: controlled Bot memory projections and Cortex integration contract

.github/workflows/ci.yml

@@ -42,6 +42,44 @@ jobs:
       - name: Assert cortex-core default build has no network/telemetry deps
         run: bash scripts/check-no-network-egress.sh
 
+  controlled-wheel:
+    name: Controlled wheel (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - uses: Swatinem/rust-cache@v2
+      - name: Build native wheel
+        run: |
+          python -m pip install 'maturin>=1.0,<2.0'
+          maturin build --release -m cortex-python/Cargo.toml --out dist --interpreter python
+      - name: Install wheel and run isolated acceptance
+        run: |
+          python -m pip install --force-reinstall dist/*.whl
+          python -I "$GITHUB_WORKSPACE/cortex-python/tests/test_controlled_store.py"
+      - name: Reject writable foreign-owned database (real filesystem)
+        if: runner.os == 'Linux'
+        run: |
+          fixture_dir=$(mktemp -d)
+          chmod 755 "$fixture_dir"
+          fixture_path="$fixture_dir/foreign.db"
+          touch "$fixture_path"
+          sudo chown 65534:65534 "$fixture_path"
+          sudo chmod 666 "$fixture_path"
+          CORTEX_FOREIGN_OWNED_DB="$fixture_path" python -I "$GITHUB_WORKSPACE/cortex-python/tests/test_foreign_owned_database.py"
+      - uses: actions/upload-artifact@v4
+        with:
+          name: controlled-wheel-${{ matrix.os }}
+          path: dist/*.whl
+          retention-days: 14
+
   bench:
     name: Benchmark
     runs-on: ubuntu-latest

Cargo.toml

@@ -7,3 +7,8 @@ lto = true
 codegen-units = 1
 strip = true
 panic = "abort"
+
+# Keep native wheel symbols: stripping this cdylib can produce a misaligned
+# LINKEDIT string table with current macOS linker/install-name tooling.
+[profile.release.package.cortex-python]
+strip = false

README.md

@@ -137,6 +137,22 @@ Cortex implements a 4-tier memory model inspired by human cognition:
 
 **Working** holds the current session scratch pad. **Episodic** stores raw experiences with timestamps and source metadata. The **Consolidation Engine** periodically promotes recurring patterns into **Semantic** facts and decays stale episodes. **Procedural** captures learned workflows and routines.
 
+### Bot integration architecture
+
+For a hosted Bot with existing PostgreSQL memory and account permissions, Cortex is an
+optional derived retrieval backend behind its MemoryManager. PostgreSQL remains the
+authority for confirmed values, scope, provenance, revisions and withdrawal;
+ContextProjector remains the single model-context composer, and Workflow keeps execution
+and approvals. Search hits must pass current authoritative validation before entering
+model context. A controlled projection store must not import personal archives or enable
+sync, automatic inference or consolidation by default.
+
+The [controlled API contract](docs/controlled-memory-api.md) documents the implemented
+`ControlledStore` Python interface, snapshot/replay lifecycle and error codes. The
+[implementation plan](docs/design/bot-memory-integration.md) separates Cortex-side
+acceptance from host-owned PostgreSQL and Bot integration. Package publication and Bot
+deployment are separate steps; existing personal-agent interfaces remain available.
+
 ## Key Components
 
 ### People Graph

cortex-core/Cargo.toml

@@ -14,7 +14,7 @@ uuid = { version = "1", features = ["v4", "serde"] }
 chrono = { version = "0.4", features = ["serde"] }
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"
-rusqlite = { version = "0.31", features = ["bundled"] }
+rusqlite = { version = "0.31", features = ["bundled", "hooks"] }
 thiserror = "1"
 tracing = "0.1"
 parking_lot = "0.12"
@@ -47,3 +47,7 @@ harness = false
 [[bench]]
 name = "comparison_bench"
 harness = false
+
+[target.'cfg(unix)'.dependencies]
+libc = "0.2"
+tempfile = "3"