heartwood-memory 0.1.0__tar.gz

heartwood_memory-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Heartwood Memory
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

heartwood_memory-0.1.0/PKG-INFO

@@ -0,0 +1,326 @@
+Metadata-Version: 2.4
+Name: heartwood-memory
+Version: 0.1.0
+Summary: Governed, provenance-first agent memory for AI systems.
+Author: Heartwood Memory
+License-Expression: MIT
+Keywords: agent-memory,ai-agents,governance,provenance,retrieval,database
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: cryptography>=42
+Requires-Dist: numpy>=1.26
+Provides-Extra: crypto
+Requires-Dist: cryptography>=42; extra == "crypto"
+Provides-Extra: sqlite
+Requires-Dist: sqlite-vec>=0.1.6; extra == "sqlite"
+Provides-Extra: models
+Requires-Dist: sentence-transformers>=3; extra == "models"
+Provides-Extra: recall
+Requires-Dist: sentence-transformers>=3; extra == "recall"
+Requires-Dist: sqlite-vec>=0.1.6; extra == "recall"
+Provides-Extra: mcp
+Requires-Dist: mcp>=1; extra == "mcp"
+Provides-Extra: postgres
+Requires-Dist: psycopg[binary]>=3.2; extra == "postgres"
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: cryptography>=42; extra == "dev"
+Requires-Dist: mcp>=1; extra == "dev"
+Requires-Dist: psycopg[binary]>=3.2; extra == "dev"
+Requires-Dist: sqlite-vec>=0.1.6; extra == "dev"
+Dynamic: license-file
+
+# Heartwood Memory Codex Workspace
+
+This workspace contains the early product and proof artifacts for Heartwood, an agent-native memory/database product.
+
+The current direction is de-risked:
+
+- V1 is **Heartwood Memory**, a derived, rebuildable, provenance-first memory layer beside existing systems of record.
+- The native standalone database remains the north star, not the first implementation target.
+- Phase 0 focuses on proving retrieval quality, generated-memory faithfulness, and deletion lineage before engine work.
+
+Evidence boundary: the shipped package is `heartwood/` plus its SDK and adapter surfaces. Product-facing enterprise retrieval evidence now comes from `experiments/product-retrieval/`, which ingests the enterprise trace through `Heartwood.remember()` and evaluates `Heartwood.recall()`. The older `experiments/typed-memory/` retrieval numbers remain research/proof-core evidence, useful for design exploration and adapter validation but not a substitute for product API gates.
+
+## Key Docs
+
+- `docs/README.md` - current documentation map and historical-doc boundary
+- `docs/heartwood-memory-v1-prd.md` - de-risked V1 PRD
+- `docs/heartwood-cohesive-solution.md` - merged product architecture and release gates
+- `docs/heartwood-embedded-library-spec.md` - embedded SDK/product shell spec
+- `docs/platform-support.md` - macOS, Linux, Windows, Docker, and dataset-location support notes
+- `docs/integrations/onboarding-guide.md` - Phase 1 onboarding guide
+- `docs/integrations/mcp-quickstart.md` - governed MCP quickstart
+- `docs/phase-0-prove-plan.md` - Phase 0 hypotheses, pass/fail criteria, and deliverables
+- `docs/integrations/api-ergonomics.md` - Phase 1 tenant/bulk API quickstart
+- `docs/security/key-custody.md` - key-custody pattern
+- `docs/api/python-api.md` and `docs/api/typescript-api.md` - generated API references
+- `docs/migration/postgres-sqlite-migration-guide.md` - migration/projection guidance
+- `docs/deployment/docker-usage.md` - Docker runtime and verification usage
+- `docs/release/python-package-release.md` - signed Python wheel and manifest flow
+- `docs/results/phase-1-completion-report.md` - Phase 1 evidence and live-adoption boundary
+- `docs/typed-memory-plane-design.md` - executable typed-memory architecture
+- `docs/outreach/heartwood-memory-2-minute-demo-script.md` - production-ready 2-minute demo script
+- `docs/outreach/heartwood-memory-one-pager.md` - outreach one-pager grounded in the working demo
+- `docs/pre-registered-thresholds.md` - locked Phase 0 realistic-trace recall thresholds
+- `docs/results/phase-0-threshold-results.md` - realistic-trace threshold gate results
+- `docs/results/phase-0-trust-suite-results.md` - latest end-to-end Phase 0 suite result
+- `docs/results/phase-0-product-retrieval-results.md` - product API enterprise retrieval result
+- `docs/results/phase-0-typed-memory-results.md` - typed-memory enterprise result
+- `docs/results/phase-0-filtered-search-results.md` - filtered-search policy result
+- `docs/results/phase-0-temporal-conflict-results.md` - temporal conflict result
+- `docs/results/phase-0-context-ablation-results.md` - query-bias/context ablation result
+- `docs/results/phase-0-storage-adapter-results.md` - SQLite storage adapter result
+- `docs/results/phase-0-snapshot-import-results.md` - SQLite snapshot importer result
+- `docs/results/phase-0-confidence-interval-results.md` - bootstrap confidence interval result
+- `docs/deletion-lineage-design.md` - derived-artifact deletion architecture
+- `docs/faithfulness-gate-design.md` - generated-memory faithfulness gate
+- `docs/egress-policy-gate-design.md` - external-model egress policy gate
+
+## Product Shell
+
+Heartwood Memory now has a developer-facing shell layered on top of the proof harnesses:
+
+- `heartwood/` - Python embedded memory library with `remember`, `recall`, `explain_recall`, `approve`, `forget`, `evaluate_egress`, `assess_faithfulness`, and `remember_generated`
+- `heartwood/adapters/` - Anthropic Memory Tool and MCP adapter surfaces
+- `sdk/typescript/` - TypeScript SDK helpers for governed memory and memory-tool workflows; governed recall parity is not shipped yet
+- `examples/regulated-support/` - regulated-support demo with a generated compliance report
+- `tests/` - product-shell smoke, provenance, policy, index, and memory-tool tests
+
+Run the Python product shell:
+
+```bash
+python -m pip install -e ".[recall,mcp]"
+heartwood --help
+heartwood import-markdown ./memory ./team-memory --db ./heartwood.db --tenant-map-json '{"acme":"tenant:acme-payments"}' --output ./heartwood-import-report.json
+python ./tests/smoke_test.py
+python ./tests/test_memory_tool.py
+python ./tests/test_provenance.py
+python ./tests/test_trust_controls.py
+python ./tests/test_index.py
+python ./tests/test_inheritance.py
+```
+
+The `heartwood` console script is equivalent to `python -m heartwood.cli` after
+installation. Use the module form only when you are running directly from a
+checkout before installing the package.
+
+Run the TypeScript SDK tests:
+
+```bash
+npm --prefix ./sdk/typescript test
+```
+
+Run the regulated-support demo:
+
+```bash
+python ./examples/regulated-support/run_demo.py
+```
+
+Import Markdown memory:
+
+```bash
+heartwood import-markdown ./memory ./team-memory --db ./heartwood.db --tenant-map-json '{"acme":"tenant:acme-payments"}' --output ./heartwood-import-report.json
+```
+
+Run warm recall for hook/agent integration:
+
+```bash
+export HEARTWOOD_RECALL_TOKEN="$(openssl rand -hex 24)"
+heartwood serve-recall --db ./heartwood.db --tenant tenant:ops --host 127.0.0.1 --port 8765
+heartwood recall --url http://127.0.0.1:8765 --tenant tenant:ops --query "what memory applies here?" --k 5 --json
+heartwood bench-recall --url http://127.0.0.1:8765 --tenant tenant:ops --query "what memory applies here?" --repeat 10 --max-p95-ms 500 --require-pass
+```
+
+Bulk-write JSON/JSONL records through the public tenant-aware API:
+
+```bash
+heartwood bulk-remember --input ./records.jsonl --db ./heartwood.db --tenant tenant:ops --output ./heartwood-bulk-report.json
+python ./tests/test_bulk_api.py
+```
+
+## Experiments
+
+Run the Phase 0 end-to-end suite:
+
+```bash
+python ./experiments/phase0-trust-suite/src/phase0_trust_suite.py
+```
+
+Run the portable suite for fresh clones, manual verification, or containers without local LongMemEval fixtures:
+
+```bash
+python ./experiments/phase0-trust-suite/src/phase0_trust_suite.py --skip-longmemeval
+```
+
+Run the suite with the live Postgres adapter gate:
+
+```bash
+python ./experiments/phase0-trust-suite/src/phase0_trust_suite.py --include-postgres
+```
+
+Run typed-memory enterprise and LongMemEval benchmarks:
+
+```bash
+python ./experiments/typed-memory/src/typed_memory_benchmark.py --dataset enterprise --require-pass
+python ./experiments/typed-memory/src/typed_memory_benchmark.py --dataset longmemeval-s-session-100 --require-pass
+```
+
+Run the product API enterprise retrieval benchmark:
+
+```bash
+python ./experiments/product-retrieval/src/heartwood_product_benchmark.py --require-pass
+python ./experiments/product-retrieval/src/heartwood_product_benchmark.py --phase1-scale --require-pass
+```
+
+Run the SQLite-backed local memory-plane path:
+
+```bash
+python ./experiments/typed-memory/src/memory_plane_cli.py ingest --db ./experiments/typed-memory/results/heartwood_memory_plane.sqlite
+python ./experiments/typed-memory/src/memory_plane_cli.py recall --db ./experiments/typed-memory/results/heartwood_memory_plane.sqlite --query-id q_customer42_refund_eligibility
+python ./experiments/typed-memory/src/memory_plane_cli.py inspect --db ./experiments/typed-memory/results/heartwood_memory_plane.sqlite
+python ./experiments/typed-memory/src/memory_plane_cli.py export-eval --db ./experiments/typed-memory/results/heartwood_memory_plane.sqlite --jsonl-output ./experiments/typed-memory/results/recall_eval_export.jsonl
+python ./experiments/typed-memory/src/storage_adapter_smoke.py --require-pass
+```
+
+Run snapshot import and statistical reporting:
+
+```bash
+python ./experiments/typed-memory/src/snapshot_import_smoke.py --require-pass
+python ./experiments/typed-memory/src/confidence_interval_report.py --result ./experiments/typed-memory/results/enterprise_latest.json --require-pass
+```
+
+Run the live Postgres adapter directly:
+
+```bash
+python ./experiments/typed-memory/src/postgres_adapter_smoke.py --require-pass
+```
+
+Run database/search-specific Phase 0 harnesses:
+
+```bash
+python ./experiments/filtered-search/src/filtered_search_benchmark.py --require-pass
+python ./experiments/temporal-conflict/src/temporal_conflict_benchmark.py --require-pass
+python ./experiments/context-ablation/src/context_ablation_benchmark.py --require-pass
+```
+
+Run the recall benchmark:
+
+```bash
+python ./experiments/recall-benchmark/src/benchmark.py
+```
+
+Run the realistic-trace threshold gate after benchmark result files exist:
+
+```bash
+python ./experiments/recall-benchmark/src/evaluate_thresholds.py ./experiments/recall-benchmark/results/longmemeval_s_session_100.json ./experiments/recall-benchmark/results/longmemeval_s_turn_100.json ./experiments/recall-benchmark/results/longmemeval_m_session_25.json ./experiments/recall-benchmark/results/longmemeval_m_turn_25.json ./experiments/recall-benchmark/results/longmemeval_s_session_50_dense.json ./experiments/recall-benchmark/results/longmemeval_s_turn_50_dense.json --output ./experiments/recall-benchmark/results/phase0_threshold_results.json --markdown-output ./docs/results/phase-0-threshold-results.md
+```
+
+Run deletion-lineage smoke test:
+
+```bash
+python ./experiments/deletion-lineage/src/deletion_smoke.py --subject customer_42
+```
+
+Run realistic deletion-lineage retrieval-path test:
+
+```bash
+python ./experiments/deletion-lineage/src/deletion_realistic.py --subject customer_42
+```
+
+Run negative missing-lineage deletion test:
+
+```bash
+python ./experiments/deletion-lineage/src/deletion_negative.py --subject customer_42
+```
+
+Run faithfulness-gate smoke test:
+
+```bash
+python ./experiments/faithfulness-gate/src/faithfulness_smoke.py
+```
+
+Run realistic and negative faithfulness-gate tests:
+
+```bash
+python ./experiments/faithfulness-gate/src/faithfulness_realistic.py
+python ./experiments/faithfulness-gate/src/faithfulness_negative.py
+```
+
+Run egress-policy gate tests:
+
+```bash
+python ./experiments/egress-policy/src/egress_policy_gate.py
+python ./experiments/egress-policy/src/egress_policy_gate.py --requests ./experiments/egress-policy/data/negative_requests.jsonl --output ./experiments/egress-policy/results/negative_latest.json --expect-no-unsafe-external
+python ./experiments/egress-policy/src/provider_registry_gate.py
+```
+
+Run resilience gates for adversarial tenancy, local concurrency, and deletion chaos:
+
+```bash
+python ./experiments/resilience/src/adversarial_multitenant.py
+python ./experiments/resilience/src/scale_concurrency_soak.py
+python ./experiments/resilience/src/deletion_chaos.py
+```
+
+Run example framework adapter contract tests for Hermes/OpenClaw-style memory surfaces:
+
+```bash
+python ./experiments/adapter-contracts/src/framework_adapter_contracts.py
+```
+
+Build the local container image:
+
+```bash
+docker build -t heartwood-memory:local .
+```
+
+Run the Heartwood MCP server with a persistent local volume:
+
+```bash
+docker run --rm -it -v heartwood-data:/data -e HEARTWOOD_TENANT=tenant:local heartwood-memory:local
+```
+
+Run the local Compose stack with Heartwood MCP plus Postgres:
+
+```bash
+docker compose up --build
+```
+
+Build and run the verification image instead of the runtime image:
+
+```bash
+docker build --target verify -t heartwood-memory-verify .
+docker run --rm heartwood-memory-verify
+```
+
+The verification image runs the portable trust suite. Run the local suite from the repo when the generated LongMemEval fixtures are available.
+
+## License
+
+The core package in this repository is MIT licensed; see `LICENSE`. Commercial
+support, signed release distribution, managed key custody, and hosted services
+may be offered separately from the MIT core.
+
+## Current Bias
+
+Prove boring trust before building ambitious cognition:
+
+- provenance
+- typed memory routing
+- policy-aware recall
+- temporal state
+- deletion completeness
+- generated-memory faithfulness
+- repeatable evals
+
+The cognitive database vision should be earned by evidence from these loops.

heartwood_memory-0.1.0/README.md

@@ -0,0 +1,285 @@
+# Heartwood Memory Codex Workspace
+
+This workspace contains the early product and proof artifacts for Heartwood, an agent-native memory/database product.
+
+The current direction is de-risked:
+
+- V1 is **Heartwood Memory**, a derived, rebuildable, provenance-first memory layer beside existing systems of record.
+- The native standalone database remains the north star, not the first implementation target.
+- Phase 0 focuses on proving retrieval quality, generated-memory faithfulness, and deletion lineage before engine work.
+
+Evidence boundary: the shipped package is `heartwood/` plus its SDK and adapter surfaces. Product-facing enterprise retrieval evidence now comes from `experiments/product-retrieval/`, which ingests the enterprise trace through `Heartwood.remember()` and evaluates `Heartwood.recall()`. The older `experiments/typed-memory/` retrieval numbers remain research/proof-core evidence, useful for design exploration and adapter validation but not a substitute for product API gates.
+
+## Key Docs
+
+- `docs/README.md` - current documentation map and historical-doc boundary
+- `docs/heartwood-memory-v1-prd.md` - de-risked V1 PRD
+- `docs/heartwood-cohesive-solution.md` - merged product architecture and release gates
+- `docs/heartwood-embedded-library-spec.md` - embedded SDK/product shell spec
+- `docs/platform-support.md` - macOS, Linux, Windows, Docker, and dataset-location support notes
+- `docs/integrations/onboarding-guide.md` - Phase 1 onboarding guide
+- `docs/integrations/mcp-quickstart.md` - governed MCP quickstart
+- `docs/phase-0-prove-plan.md` - Phase 0 hypotheses, pass/fail criteria, and deliverables
+- `docs/integrations/api-ergonomics.md` - Phase 1 tenant/bulk API quickstart
+- `docs/security/key-custody.md` - key-custody pattern
+- `docs/api/python-api.md` and `docs/api/typescript-api.md` - generated API references
+- `docs/migration/postgres-sqlite-migration-guide.md` - migration/projection guidance
+- `docs/deployment/docker-usage.md` - Docker runtime and verification usage
+- `docs/release/python-package-release.md` - signed Python wheel and manifest flow
+- `docs/results/phase-1-completion-report.md` - Phase 1 evidence and live-adoption boundary
+- `docs/typed-memory-plane-design.md` - executable typed-memory architecture
+- `docs/outreach/heartwood-memory-2-minute-demo-script.md` - production-ready 2-minute demo script
+- `docs/outreach/heartwood-memory-one-pager.md` - outreach one-pager grounded in the working demo
+- `docs/pre-registered-thresholds.md` - locked Phase 0 realistic-trace recall thresholds
+- `docs/results/phase-0-threshold-results.md` - realistic-trace threshold gate results
+- `docs/results/phase-0-trust-suite-results.md` - latest end-to-end Phase 0 suite result
+- `docs/results/phase-0-product-retrieval-results.md` - product API enterprise retrieval result
+- `docs/results/phase-0-typed-memory-results.md` - typed-memory enterprise result
+- `docs/results/phase-0-filtered-search-results.md` - filtered-search policy result
+- `docs/results/phase-0-temporal-conflict-results.md` - temporal conflict result
+- `docs/results/phase-0-context-ablation-results.md` - query-bias/context ablation result
+- `docs/results/phase-0-storage-adapter-results.md` - SQLite storage adapter result
+- `docs/results/phase-0-snapshot-import-results.md` - SQLite snapshot importer result
+- `docs/results/phase-0-confidence-interval-results.md` - bootstrap confidence interval result
+- `docs/deletion-lineage-design.md` - derived-artifact deletion architecture
+- `docs/faithfulness-gate-design.md` - generated-memory faithfulness gate
+- `docs/egress-policy-gate-design.md` - external-model egress policy gate
+
+## Product Shell
+
+Heartwood Memory now has a developer-facing shell layered on top of the proof harnesses:
+
+- `heartwood/` - Python embedded memory library with `remember`, `recall`, `explain_recall`, `approve`, `forget`, `evaluate_egress`, `assess_faithfulness`, and `remember_generated`
+- `heartwood/adapters/` - Anthropic Memory Tool and MCP adapter surfaces
+- `sdk/typescript/` - TypeScript SDK helpers for governed memory and memory-tool workflows; governed recall parity is not shipped yet
+- `examples/regulated-support/` - regulated-support demo with a generated compliance report
+- `tests/` - product-shell smoke, provenance, policy, index, and memory-tool tests
+
+Run the Python product shell:
+
+```bash
+python -m pip install -e ".[recall,mcp]"
+heartwood --help
+heartwood import-markdown ./memory ./team-memory --db ./heartwood.db --tenant-map-json '{"acme":"tenant:acme-payments"}' --output ./heartwood-import-report.json
+python ./tests/smoke_test.py
+python ./tests/test_memory_tool.py
+python ./tests/test_provenance.py
+python ./tests/test_trust_controls.py
+python ./tests/test_index.py
+python ./tests/test_inheritance.py
+```
+
+The `heartwood` console script is equivalent to `python -m heartwood.cli` after
+installation. Use the module form only when you are running directly from a
+checkout before installing the package.
+
+Run the TypeScript SDK tests:
+
+```bash
+npm --prefix ./sdk/typescript test
+```
+
+Run the regulated-support demo:
+
+```bash
+python ./examples/regulated-support/run_demo.py
+```
+
+Import Markdown memory:
+
+```bash
+heartwood import-markdown ./memory ./team-memory --db ./heartwood.db --tenant-map-json '{"acme":"tenant:acme-payments"}' --output ./heartwood-import-report.json
+```
+
+Run warm recall for hook/agent integration:
+
+```bash
+export HEARTWOOD_RECALL_TOKEN="$(openssl rand -hex 24)"
+heartwood serve-recall --db ./heartwood.db --tenant tenant:ops --host 127.0.0.1 --port 8765
+heartwood recall --url http://127.0.0.1:8765 --tenant tenant:ops --query "what memory applies here?" --k 5 --json
+heartwood bench-recall --url http://127.0.0.1:8765 --tenant tenant:ops --query "what memory applies here?" --repeat 10 --max-p95-ms 500 --require-pass
+```
+
+Bulk-write JSON/JSONL records through the public tenant-aware API:
+
+```bash
+heartwood bulk-remember --input ./records.jsonl --db ./heartwood.db --tenant tenant:ops --output ./heartwood-bulk-report.json
+python ./tests/test_bulk_api.py
+```
+
+## Experiments
+
+Run the Phase 0 end-to-end suite:
+
+```bash
+python ./experiments/phase0-trust-suite/src/phase0_trust_suite.py
+```
+
+Run the portable suite for fresh clones, manual verification, or containers without local LongMemEval fixtures:
+
+```bash
+python ./experiments/phase0-trust-suite/src/phase0_trust_suite.py --skip-longmemeval
+```
+
+Run the suite with the live Postgres adapter gate:
+
+```bash
+python ./experiments/phase0-trust-suite/src/phase0_trust_suite.py --include-postgres
+```
+
+Run typed-memory enterprise and LongMemEval benchmarks:
+
+```bash
+python ./experiments/typed-memory/src/typed_memory_benchmark.py --dataset enterprise --require-pass
+python ./experiments/typed-memory/src/typed_memory_benchmark.py --dataset longmemeval-s-session-100 --require-pass
+```
+
+Run the product API enterprise retrieval benchmark:
+
+```bash
+python ./experiments/product-retrieval/src/heartwood_product_benchmark.py --require-pass
+python ./experiments/product-retrieval/src/heartwood_product_benchmark.py --phase1-scale --require-pass
+```
+
+Run the SQLite-backed local memory-plane path:
+
+```bash
+python ./experiments/typed-memory/src/memory_plane_cli.py ingest --db ./experiments/typed-memory/results/heartwood_memory_plane.sqlite
+python ./experiments/typed-memory/src/memory_plane_cli.py recall --db ./experiments/typed-memory/results/heartwood_memory_plane.sqlite --query-id q_customer42_refund_eligibility
+python ./experiments/typed-memory/src/memory_plane_cli.py inspect --db ./experiments/typed-memory/results/heartwood_memory_plane.sqlite
+python ./experiments/typed-memory/src/memory_plane_cli.py export-eval --db ./experiments/typed-memory/results/heartwood_memory_plane.sqlite --jsonl-output ./experiments/typed-memory/results/recall_eval_export.jsonl
+python ./experiments/typed-memory/src/storage_adapter_smoke.py --require-pass
+```
+
+Run snapshot import and statistical reporting:
+
+```bash
+python ./experiments/typed-memory/src/snapshot_import_smoke.py --require-pass
+python ./experiments/typed-memory/src/confidence_interval_report.py --result ./experiments/typed-memory/results/enterprise_latest.json --require-pass
+```
+
+Run the live Postgres adapter directly:
+
+```bash
+python ./experiments/typed-memory/src/postgres_adapter_smoke.py --require-pass
+```
+
+Run database/search-specific Phase 0 harnesses:
+
+```bash
+python ./experiments/filtered-search/src/filtered_search_benchmark.py --require-pass
+python ./experiments/temporal-conflict/src/temporal_conflict_benchmark.py --require-pass
+python ./experiments/context-ablation/src/context_ablation_benchmark.py --require-pass
+```
+
+Run the recall benchmark:
+
+```bash
+python ./experiments/recall-benchmark/src/benchmark.py
+```
+
+Run the realistic-trace threshold gate after benchmark result files exist:
+
+```bash
+python ./experiments/recall-benchmark/src/evaluate_thresholds.py ./experiments/recall-benchmark/results/longmemeval_s_session_100.json ./experiments/recall-benchmark/results/longmemeval_s_turn_100.json ./experiments/recall-benchmark/results/longmemeval_m_session_25.json ./experiments/recall-benchmark/results/longmemeval_m_turn_25.json ./experiments/recall-benchmark/results/longmemeval_s_session_50_dense.json ./experiments/recall-benchmark/results/longmemeval_s_turn_50_dense.json --output ./experiments/recall-benchmark/results/phase0_threshold_results.json --markdown-output ./docs/results/phase-0-threshold-results.md
+```
+
+Run deletion-lineage smoke test:
+
+```bash
+python ./experiments/deletion-lineage/src/deletion_smoke.py --subject customer_42
+```
+
+Run realistic deletion-lineage retrieval-path test:
+
+```bash
+python ./experiments/deletion-lineage/src/deletion_realistic.py --subject customer_42
+```
+
+Run negative missing-lineage deletion test:
+
+```bash
+python ./experiments/deletion-lineage/src/deletion_negative.py --subject customer_42
+```
+
+Run faithfulness-gate smoke test:
+
+```bash
+python ./experiments/faithfulness-gate/src/faithfulness_smoke.py
+```
+
+Run realistic and negative faithfulness-gate tests:
+
+```bash
+python ./experiments/faithfulness-gate/src/faithfulness_realistic.py
+python ./experiments/faithfulness-gate/src/faithfulness_negative.py
+```
+
+Run egress-policy gate tests:
+
+```bash
+python ./experiments/egress-policy/src/egress_policy_gate.py
+python ./experiments/egress-policy/src/egress_policy_gate.py --requests ./experiments/egress-policy/data/negative_requests.jsonl --output ./experiments/egress-policy/results/negative_latest.json --expect-no-unsafe-external
+python ./experiments/egress-policy/src/provider_registry_gate.py
+```
+
+Run resilience gates for adversarial tenancy, local concurrency, and deletion chaos:
+
+```bash
+python ./experiments/resilience/src/adversarial_multitenant.py
+python ./experiments/resilience/src/scale_concurrency_soak.py
+python ./experiments/resilience/src/deletion_chaos.py
+```
+
+Run example framework adapter contract tests for Hermes/OpenClaw-style memory surfaces:
+
+```bash
+python ./experiments/adapter-contracts/src/framework_adapter_contracts.py
+```
+
+Build the local container image:
+
+```bash
+docker build -t heartwood-memory:local .
+```
+
+Run the Heartwood MCP server with a persistent local volume:
+
+```bash
+docker run --rm -it -v heartwood-data:/data -e HEARTWOOD_TENANT=tenant:local heartwood-memory:local
+```
+
+Run the local Compose stack with Heartwood MCP plus Postgres:
+
+```bash
+docker compose up --build
+```
+
+Build and run the verification image instead of the runtime image:
+
+```bash
+docker build --target verify -t heartwood-memory-verify .
+docker run --rm heartwood-memory-verify
+```
+
+The verification image runs the portable trust suite. Run the local suite from the repo when the generated LongMemEval fixtures are available.
+
+## License
+
+The core package in this repository is MIT licensed; see `LICENSE`. Commercial
+support, signed release distribution, managed key custody, and hosted services
+may be offered separately from the MIT core.
+
+## Current Bias
+
+Prove boring trust before building ambitious cognition:
+
+- provenance
+- typed memory routing
+- policy-aware recall
+- temporal state
+- deletion completeness
+- generated-memory faithfulness
+- repeatable evals
+
+The cognitive database vision should be earned by evidence from these loops.

heartwood_memory-0.1.0/heartwood/__init__.py

@@ -0,0 +1,42 @@
+"""Heartwood — provenance-first, embedded agent-memory library (Phase 0).
+
+The differentiation is governance — tamper-evident provenance + policy-enforced
+recall + crypto-shred erasure — over benchmark-validated hybrid retrieval. NOT a
+novel retrieval mechanism (spreading activation was CUT; see
+experiments/recall-benchmark/RESULTS.md).
+
+    from heartwood import Heartwood, Principal, Policy
+    db = Heartwood(path="mem.db", tenant="tenant:acme")
+    mid = db.remember("User prefers concise answers.", subject="user:1",
+                      created_by="agent:asst", kind="semantic", epistemic="user-stated")
+    out = db.recall("how should I talk to this user?",
+                    principal=Principal(id="agent:asst", tenant="tenant:acme"))
+"""
+from .client import Heartwood
+from .egress import DENIED, EXTERNAL_ALLOWED, EXTERNAL_REDACTED, HUMAN_REVIEW, LOCAL_ONLY
+from .envelope import Epistemic, Kind, Memory, Policy, TruthStatus
+from .ergonomics import normalize_tenant, policy_from, principal_from, tenant_slug
+from .key_custody import LocalKmsCustodian, RawKeyCustodian
+from .policy import Principal
+
+__all__ = [
+    "Heartwood",
+    "Principal",
+    "Policy",
+    "Memory",
+    "Kind",
+    "Epistemic",
+    "TruthStatus",
+    "normalize_tenant",
+    "tenant_slug",
+    "policy_from",
+    "principal_from",
+    "LocalKmsCustodian",
+    "RawKeyCustodian",
+    "EXTERNAL_ALLOWED",
+    "EXTERNAL_REDACTED",
+    "LOCAL_ONLY",
+    "HUMAN_REVIEW",
+    "DENIED",
+]
+__version__ = "0.1.0"