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.
