Heartwood Memory — governed memory for AI agents

Heartwood Memory — governed memory for AI agents

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.

Website · Compare Heartwood · FAQ · PyPI

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.

Install

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

Development checks

From a source checkout, use Python 3.11 and install the declared development dependencies before running the local quality gate:

python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[dev]"
bash scripts/check.sh

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:

git clone https://github.com/jermayne36/heartwood-memory.git
cd heartwood-memory
python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install --quiet -e ".[dev]"
python bench/run_benchmark.py --out .heartwood/trust-receipt.json

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.

Key docs

• MCP quickstart
• VS Code + GitHub Copilot MCP
• Rotation-continuity demo
• Codex local-stdio quickstart
• Onboarding guide
• Python API reference
• Strict mode and audit-anchor quickstart
• Signed audit export and offline verifier
• Key custody and erasure
• Multi-agent identity
• Postgres and SQLite migration guide
• Full public documentation map
• Release verification and publishing

Run the console script after installation:

heartwood --help

License

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.