End-to-end onboarding

1 · Install & build the store

python -m pip install "heartwood-memory[recall,mcp]"

python -m heartwood.cli import-markdown `
  C:\path\to\workspace\memory `
  --db .\heartwood.db `
  --tenant-map-json '{"acme":"tenant:acme-payments"}' `
  --output .\heartwood-import-report.json

2 · Configure key custody

For production-like local use, provide a vault-sourced root secret. Rotate by writing new memories under a new key id, then rebuilding the derived store from source if needed.

$env:HEARTWOOD_KEY_CUSTODY_ROOT_B64 = "<32-byte-base64url-secret>"
$env:HEARTWOOD_KEY_CUSTODY_KEY_ID = "local-root-v1"

3 · Acceptance checklist

Before a consumer cutover, verify: top-3 recall beats the current keyword-scoring baseline on held-out prompts; p95 warm recall is under 500ms; no cross-tenant leakage; every recalled result has source IDs and valid provenance; forget() purges source-derived memories; and at least one real agent flow runs in shadow mode for two weeks.

python tests/test_markdown_importer.py
python tests/test_warm_recall.py
python tests/test_bulk_api.py
python tests/test_mcp_hardening.py
python tests/test_key_custody.py
python experiments/product-retrieval/src/heartwood_product_benchmark.py --phase1-scale --require-pass

4 · Shadow mode

Run Heartwood recall beside the existing memory path and log: query text, tenant, baseline output, Heartwood top-3 result IDs, p95 latency, whether the agent used the Heartwood answer, and any missing-memory or bad-ranking notes. The two-week adoption gate is calendar-bound and completed in the consuming workspace.