{
  "markdown": "# Heartwood Memory — governed memory for AI agents\n\n<!-- mcp-name: io.github.jermayne36/heartwood-memory -->\n\n**Heartwood Memory is a governed memory store for AI agents: provenance-signed\naudit, policy-gated recall, tenant isolation, and a per-subject key-destruction\nproof on erasure.**\n\n> **License at a glance.** Heartwood Memory 0.2.0 and later is\n> source-available under the [Business Source License 1.1](LICENSE) (BSL 1.1),\n> not an OSI \"open source\" license. Non-production use is free at any size.\n> Small Organizations—fewer than 100 employees and independent contractors and\n> less than $1M in prior-tax-year revenue, as adjusted from 2019 under the\n> license—may also use it in production at no charge. Each version converts\n> automatically to the Apache License 2.0 four years after release. Versions\n> 0.1.0–0.1.2 were MIT-licensed and remain MIT-licensed permanently.\n\n[Website](https://heartwoodmemory.com/) ·\n[Compare Heartwood](https://heartwoodmemory.com/vs) ·\n[FAQ](https://heartwoodmemory.com/faq) ·\n[PyPI](https://pypi.org/project/heartwood-memory/)\n\n**Governed, source-auditable memory for AI agents, embedded beside your existing systems of record.**\n\nHeartwood is a cryptographic trust root for agent memory: every memory is signed,\nrecall runs under policy before ranking, the audit log is hash-chained and\ntamper-evident, and erasure emits a falsifiable per-subject key-destruction\nreceipt. The package ships as an embedded Python library with governed adapter\nsurfaces that run on your infrastructure.\n\n> **Honest boundary.** Heartwood is managed-key: the server decrypts to serve\n> recall. The receipts below are source-auditable today. Deletion is a\n> per-subject key-destruction workflow, not an instantaneous deletion guarantee.\n> See [Key custody and erasure](docs/security/key-custody.md).\n\n## Install\n\n```bash\npython -m pip install \"heartwood-memory[recall,mcp]\"\n```\n\n## Development checks\n\nFrom a source checkout, use Python 3.11 and install the declared development\ndependencies before running the local quality gate:\n\n```bash\npython3.11 -m venv .venv\nsource .venv/bin/activate\npython -m pip install -e \".[dev]\"\nbash scripts/check.sh\n```\n\n`scripts/check.sh` runs Ruff and the full pytest suite. The optional Hermes\nAgent contract suite reports as skipped unless its separate integration\ndependency is installed. To install the same gate as a pre-commit hook without\noverwriting another hook, run `bash scripts/install-hooks.sh`.\n\n## Re-run the public trust suite\n\nThe public trust-receipts benchmark lives in the source repository rather than\nthe installed wheel. Starting from a clean clone, run:\n\n```bash\ngit clone https://github.com/jermayne36/heartwood-memory.git\ncd heartwood-memory\npython3.11 -m venv .venv\nsource .venv/bin/activate\npython -m pip install --quiet -e \".[dev]\"\npython bench/run_benchmark.py --out .heartwood/trust-receipt.json\n```\n\nOn Windows PowerShell, replace the activation line with\n`.\\.venv\\Scripts\\Activate.ps1`.\n\nThe command exits non-zero if an executable contract or positive-control case\nfails, or if the benchmark's existing claim-anchor scan finds a violation. Its\none-line terminal summary reports the live case counts; the JSON file contains\nthe per-probe results and the separately published boundary cases.\n\n## 5-minute quickstart\n\nRemember a governed memory, recall it under policy, and emit a key-destruction\nreceipt:\n\n```python\nfrom heartwood import Heartwood, Policy, Principal, prove_crypto_erase_path\n\n# 1. Open an embedded, tenant-scoped store.\ndb = Heartwood(path=\"./heartwood.db\", tenant=\"tenant:acme\")\n\n# 2. Remember. The record is signed and written to a hash-chained audit log.\ndb.remember(\n    \"Customer 42 is on the Enterprise plan.\",\n    subject=\"customer:42\",\n    created_by=\"agent:support\",\n    policy=Policy(classification=\"internal\"),\n)\n\n# 3. Recall. Policy gates the candidate set before ranking.\nprincipal = Principal(\n    id=\"agent:support\",\n    tenant=\"tenant:acme\",\n    roles=(\"support\",),\n    clearance=\"internal\",\n)\nout = db.recall(\n    \"what plan is customer 42 on?\",\n    principal=principal,\n    filters={\"subject\": \"customer:42\"},\n    k=5,\n)\n\nfor hit in out[\"results\"]:\n    print(hit[\"content\"], hit[\"provenance\"][\"signature_valid\"])\n\n# 4. Forget. This crypto-shreds the per-subject key and purges derived artifacts.\nreceipt = db.forget(\n    \"customer:42\",\n    mode=\"hard\",\n    actor=\"agent:support\",\n    reason=\"right-to-erasure request\",\n)\ndb.close()\n\nproof = prove_crypto_erase_path(\n    \"./heartwood.db\",\n    tenant=\"tenant:acme\",\n    root_present=False,\n).to_dict()\nprint(receipt[\"key_shredded\"], proof[\"content_unrecoverable\"])\n```\n\n> **Keep local artifacts out of Git.** This repository's `.gitignore` does not\n> propagate into downstream repositories. If you run these examples in another\n> checkout, add equivalent ignores there for local Heartwood databases and\n> sidecars, token/config files, root-local JSONL inputs, generated `*-report.json`\n> files, and `.venv/`; alternatively, keep sensitive runtime state under an\n> ignored `.heartwood/` directory. Keep deliberate fixtures in non-root paths so\n> they remain reviewable.\n\nWant governed memory for an MCP-capable agent instead of a library? See the\n[governed MCP quickstart](docs/integrations/mcp-quickstart.md) and the\n[Codex local-stdio quickstart](docs/integrations/codex-quickstart.md). Write\nand erase verbs are not exposed by default; operators opt in by naming them\nexplicitly.\n\n## What you get - five receipts\n\nGovernance you can inspect and re-run at the record level:\n\n| Receipt | What it does | Boundary today |\n|---|---|---|\n| **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. |\n| **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. |\n| **Policy before ranking** | Recall is restricted to cleared records before ranking; denied records are not scored, returned, or counted. | Source-auditable under the committed single-trust-domain pre-seed posture; multi-tenant deployment is not claimed. |\n| **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. |\n| **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. |\n\n## Key docs\n\n- [MCP quickstart](docs/integrations/mcp-quickstart.md)\n- [VS Code + GitHub Copilot MCP](docs/integrations/vscode-copilot.md)\n- [Rotation-continuity demo](examples/rotation-continuity/README.md)\n- [Codex local-stdio quickstart](docs/integrations/codex-quickstart.md)\n- [Onboarding guide](docs/integrations/onboarding-guide.md)\n- [Python API reference](docs/api/python-api.md)\n- [Strict mode and audit-anchor quickstart](docs/api/strict-mode-and-audit-anchor-quickstart.md)\n- [Signed audit export and offline verifier](docs/api/signed-audit-export.md)\n- [Key custody and erasure](docs/security/key-custody.md)\n- [Multi-agent identity](docs/security/multi-agent-identity.md)\n- [Postgres and SQLite migration guide](docs/migration/postgres-sqlite-migration-guide.md)\n- [Full public documentation map](docs/README.md)\n- [Release verification and publishing](docs/release/python-package-release.md)\n\nRun the console script after installation:\n\n```bash\nheartwood --help\n```\n\n## License\n\nFrom version 0.2.0, Heartwood Memory is source-available under the\n[Business Source License 1.1](LICENSE) (BSL 1.1) — not an OSI \"open source\"\nlicense. You may read the source, run it locally, develop against it, evaluate\nit, and self-host it for non-production use at no charge. Small organizations\n(fewer than 100 people and less than $1M annual revenue) may also run it in\nproduction at no charge. Larger organizations need a commercial license for\nproduction use. Each version converts automatically to the Apache License 2.0\nfour years after its release.\n\nVersions 0.1.0–0.1.2 are MIT-licensed and remain so permanently. See\n[NOTICE](NOTICE) for details. Commercial support, managed key custody, and\nhosted services are available separately.\n\n## Current Bias\n\nProve boring trust before building ambitious cognition:\n\n- provenance\n- typed memory routing\n- policy-aware recall\n- temporal state\n- deletion completeness\n- generated-memory faithfulness\n- repeatable evals\n\nThe cognitive database vision should be earned by evidence from these loops.\n",
  "bytes": 9091,
  "sha": "6e2d16f8f403b0231ee9dc5e6f90a72931236cfee27811548de427b98344087e",
  "repo_slug": "jermayne36/heartwood-memory",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_jermayne36_heartwood_memory_0f586502/readme"
}