Heartwood Memory is a governed memory store for AI agents: provenance-signed
audit, policy-gated recall, tenant isolation, and a per-subject key-destruction
proof on erasure.
License at a glance. Heartwood Memory 0.2.0 and later is
source-available under the Business Source License 1.1 (BSL 1.1),
not an OSI "open source" license. Non-production use is free at any size.
Small Organizations—fewer than 100 employees and independent contractors and
less than $1M in prior-tax-year revenue, as adjusted from 2019 under the
license—may also use it in production at no charge. Each version converts
automatically to the Apache License 2.0 four years after release. Versions
0.1.0–0.1.2 were MIT-licensed and remain MIT-licensed permanently.
Heartwood Memory — governed AI agent memory; signed provenance. BUSL-1.1; not OSI open source.
Governed, source-auditable memory for AI agents, embedded beside your existing systems of record.
Heartwood is a cryptographic trust root for agent memory: every memory is signed,
recall runs under policy before ranking, the audit log is hash-chained and
tamper-evident, and erasure emits a falsifiable per-subject key-destruction
receipt. The package ships as an embedded Python library with governed adapter
surfaces that run on your infrastructure.
Honest boundary. Heartwood is managed-key: the server decrypts to serve
recall. The receipts below are source-auditable today. Deletion is a
per-subject key-destruction workflow, not an instantaneous deletion guarantee.
See Key custody and erasure.
scripts/check.sh runs Ruff and the full pytest suite. The optional Hermes
Agent contract suite reports as skipped unless its separate integration
dependency is installed. To install the same gate as a pre-commit hook without
overwriting another hook, run bash scripts/install-hooks.sh.
Re-run the public trust suite
The public trust-receipts benchmark lives in the source repository rather than
the installed wheel. Starting from a clean clone, run:
On Windows PowerShell, replace the activation line with
.\.venv\Scripts\Activate.ps1.
The command exits non-zero if an executable contract or positive-control case
fails, or if the benchmark's existing claim-anchor scan finds a violation. Its
one-line terminal summary reports the live case counts; the JSON file contains
the per-probe results and the separately published boundary cases.
5-minute quickstart
Remember a governed memory, recall it under policy, and emit a key-destruction
receipt:
from heartwood import Heartwood, Policy, Principal, prove_crypto_erase_path
# 1. Open an embedded, tenant-scoped store.
db = Heartwood(path="./heartwood.db", tenant="tenant:acme")
# 2. Remember. The record is signed and written to a hash-chained audit log.
db.remember(
"Customer 42 is on the Enterprise plan.",
subject="customer:42",
created_by="agent:support",
policy=Policy(classification="internal"),
)
# 3. Recall. Policy gates the candidate set before ranking.
principal = Principal(
id="agent:support",
tenant="tenant:acme",
roles=("support",),
clearance="internal",
)
out = db.recall(
"what plan is customer 42 on?",
principal=principal,
filters={"subject": "customer:42"},
k=5,
)
for hit in out["results"]:
print(hit["content"], hit["provenance"]["signature_valid"])
# 4. Forget. This crypto-shreds the per-subject key and purges derived artifacts.
receipt = db.forget(
"customer:42",
mode="hard",
actor="agent:support",
reason="right-to-erasure request",
)
db.close()
proof = prove_crypto_erase_path(
"./heartwood.db",
tenant="tenant:acme",
root_present=False,
).to_dict()
print(receipt["key_shredded"], proof["content_unrecoverable"])
Keep local artifacts out of Git. This repository's .gitignore does not
propagate into downstream repositories. If you run these examples in another
checkout, add equivalent ignores there for local Heartwood databases and
sidecars, token/config files, root-local JSONL inputs, generated *-report.json
files, and .venv/; alternatively, keep sensitive runtime state under an
ignored .heartwood/ directory. Keep deliberate fixtures in non-root paths so
they remain reviewable.
Want governed memory for an MCP-capable agent instead of a library? See the
governed MCP quickstart and the
Codex local-stdio quickstart. Write
and erase verbs are not exposed by default; operators opt in by naming them
explicitly.
What you get - five receipts
Governance you can inspect and re-run at the record level:
Receipt
What it does
Boundary today
Signed provenance
Every memory is signed; the signature and content hash are re-verified at read and surfaced on each result.
Default OFF surfaces verification state; opt-in FILTER drops failed records and ENFORCE fails before returning results. The signed scope does not cover authorization metadata.
Tamper-evident audit
Hash-chained append-only log; verify_chain() detects an in-place edit or dropped row.
While the external AnchorSink and pinned verification root remain outside the attacker boundary, rollback at or below the latest anchor is detected; post-anchor rows remain an explicit open window.
Policy before ranking
Recall is restricted to cleared records before ranking; denied records are not scored or returned, and neither the results nor the signed receipt carries a count of them.
Source-auditable under the committed single-trust-domain pre-seed posture; multi-tenant deployment is not claimed.
Key-destruction receipt
forget(mode="hard") destroys the per-subject key and purges derived artifacts.
Reports per-subject key destruction and purge counts; it does not prove byte-level content deletion.
Faithfulness + egress gate
Generated memories fail closed unless they pass a faithfulness check; rejected egress requests block the external-model call.
Unaccepted faithfulness results are blocked by default; store_unaccepted=True stores a generated_needs_review proposal, which typed ranking downweights.
Replacing a memory
From 0.2.10, when a new memory names the memory it replaces, or a file is
edited or deleted through the memory tool (MCP memory or
MemoryToolBackend), Heartwood's default recall stops
returning the old text, including after a restart. Earlier versions of an
edited file stay reachable only when history is asked for explicitly.
Limit. Heartwood does not detect replacements by itself: if a new memory
is written without naming what it replaces, both stay current and the old one
can still be recalled.
To name it, pass the old memory's id when you write the new one:
db.remember(..., supersedes=old_id). History stays reachable with
filters={"include_review_states": ["superseded"]} until forget() erases its
subject. A memory-tool file written by an older release keeps its earlier
versions in default recall until its next edit, rename or delete; see
"Existing data" in the 0.2.10 changelog.
Details: Recall visibility and retirement.
From version 0.2.0, Heartwood Memory is source-available under the
Business Source License 1.1 (BSL 1.1) — not an OSI "open source"
license. You may read the source, run it locally, develop against it, evaluate
it, and self-host it for non-production use at no charge. Small organizations
(fewer than 100 people and less than $1M annual revenue) may also run it in
production at no charge. Larger organizations need a commercial license for
production use. Each version converts automatically to the Apache License 2.0
four years after its release.
Versions 0.1.0–0.1.2 are MIT-licensed and remain so permanently. See
NOTICE for details. Commercial support, managed key custody, and
hosted services are available separately.
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.