heartwood-memory

# 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](LICENSE) (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](https://heartwoodmemory.com/) ·
[Compare Heartwood](https://heartwoodmemory.com/vs) ·
[FAQ](https://heartwoodmemory.com/faq) ·
[PyPI](https://pypi.org/project/heartwood-memory/)

**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](docs/security/key-custody.md).

## Install

```bash
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:

```bash
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:

```bash
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:

```python
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](docs/integrations/mcp-quickstart.md) and the
[Codex local-stdio quickstart](docs/integrations/codex-quickstart.md). 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. |

## Key docs

- [MCP quickstart](docs/integrations/mcp-quickstart.md)
- [VS Code + GitHub Copilot MCP](docs/integrations/vscode-copilot.md)
- [Rotation-continuity demo](examples/rotation-continuity/README.md)
- [Codex local-stdio quickstart](docs/integrations/codex-quickstart.md)
- [Onboarding guide](docs/integrations/onboarding-guide.md)
- [Python API reference](docs/api/python-api.md)
- [Strict mode and audit-anchor quickstart](docs/api/strict-mode-and-audit-anchor-quickstart.md)
- [Signed audit export and offline verifier](docs/api/signed-audit-export.md)
- [Key custody and erasure](docs/security/key-custody.md)
- [Multi-agent identity](docs/security/multi-agent-identity.md)
- [Postgres and SQLite migration guide](docs/migration/postgres-sqlite-migration-guide.md)
- [Full public documentation map](docs/README.md)
- [Release verification and publishing](docs/release/python-package-release.md)

Run the console script after installation:

```bash
heartwood --help
```

## License

From version 0.2.0, Heartwood Memory is source-available under the
[Business Source License 1.1](LICENSE) (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](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.