Heartwood Memory — governed memory for AI agents MCP server

Heartwood Memory — governed memory for AI agents

<!-- mcp-name: io.github.jermayne36/heartwood-memory -->

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"),
)

Shortened. The full README is on GitHub.