heartwood-memory 0.1.1

Governed, provenance-first agent memory for AI systems.

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/customer-implementation-guide.md - customer implementation guide with runnable safe-recall examples
• 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:

python -m pip install "heartwood-memory[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

For checkout development and test runs, install the local editable package:

python -m pip install -e ".[recall,mcp]"
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:

npm --prefix ./sdk/typescript test

Run the regulated-support demo:

python ./examples/regulated-support/run_demo.py

Import Markdown memory:

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:

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:

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:

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:

python ./experiments/phase0-trust-suite/src/phase0_trust_suite.py --skip-longmemeval

Run the suite with the live Postgres adapter gate:

python ./experiments/phase0-trust-suite/src/phase0_trust_suite.py --include-postgres

Run typed-memory enterprise and LongMemEval benchmarks:

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:

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:

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:

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:

python ./experiments/typed-memory/src/postgres_adapter_smoke.py --require-pass

Run database/search-specific Phase 0 harnesses:

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:

python ./experiments/recall-benchmark/src/benchmark.py

Run the realistic-trace threshold gate after benchmark result files exist:

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:

python ./experiments/deletion-lineage/src/deletion_smoke.py --subject customer_42

Run realistic deletion-lineage retrieval-path test:

python ./experiments/deletion-lineage/src/deletion_realistic.py --subject customer_42

Run negative missing-lineage deletion test:

python ./experiments/deletion-lineage/src/deletion_negative.py --subject customer_42

Run faithfulness-gate smoke test:

python ./experiments/faithfulness-gate/src/faithfulness_smoke.py

Run realistic and negative faithfulness-gate tests:

python ./experiments/faithfulness-gate/src/faithfulness_realistic.py
python ./experiments/faithfulness-gate/src/faithfulness_negative.py

Run egress-policy gate tests:

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:

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:

python ./experiments/adapter-contracts/src/framework_adapter_contracts.py

Build the local container image:

docker build -t heartwood-memory:local .

Run the Heartwood MCP server with a persistent local volume:

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:

docker compose up --build

Build and run the verification image instead of the runtime image:

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.