Metadata-Version: 2.4
Name: heartwood-memory
Version: 0.1.2
Summary: Governed, provenance-first agent memory for AI systems.
Author: Heartwood Memory
License-Expression: MIT
Keywords: agent-memory,ai-agents,governance,provenance,retrieval,database
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Database
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: cryptography>=42
Requires-Dist: numpy>=1.26
Provides-Extra: crypto
Requires-Dist: cryptography>=42; extra == "crypto"
Provides-Extra: sqlite
Requires-Dist: sqlite-vec>=0.1.6; extra == "sqlite"
Provides-Extra: models
Requires-Dist: sentence-transformers>=3; extra == "models"
Provides-Extra: recall
Requires-Dist: sentence-transformers>=3; extra == "recall"
Requires-Dist: sqlite-vec>=0.1.6; extra == "recall"
Provides-Extra: mcp
Requires-Dist: mcp>=1; extra == "mcp"
Provides-Extra: postgres
Requires-Dist: psycopg[binary]>=3.2; extra == "postgres"
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: cryptography>=42; extra == "dev"
Requires-Dist: mcp>=1; extra == "dev"
Requires-Dist: psycopg[binary]>=3.2; extra == "dev"
Requires-Dist: sqlite-vec>=0.1.6; extra == "dev"
Dynamic: license-file

# 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 plus governed MCP
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 & erasure](docs/security/key-custody.md).

## Install

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

## 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"])
```

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. | Re-verified and surfaced, not yet enforced as a hard read failure. |
| **Tamper-evident audit** | Hash-chained append-only log; `verify_chain()` detects an in-place edit or dropped row. | Catches in-place tampering; tail-truncation needs an external anchor. |
| **Policy before ranking** | Recall is restricted to cleared records before ranking; denied records are not scored, returned, or counted. | Source-auditable; multi-tenant-at-scale validation is still in progress. |
| **Key-destruction receipt** | `forget(mode="hard")` destroys the per-subject key and purges derived artifacts. | Shows key destruction, not 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. | Explicit override stores a downweighted, review-only copy. |

## Product shell

- `heartwood/` - embedded Python library: `remember`, `recall`,
  `explain_recall`, `approve`, `forget`, `evaluate_egress`,
  `assess_faithfulness`, `remember_generated`
- `heartwood/adapters/` - Anthropic Memory Tool and MCP adapter surfaces
- `sdk/typescript/` - TypeScript SDK helpers for governed memory and
  memory-tool workflows; governed recall parity is not shipped yet
- `examples/regulated-support/` - regulated-support demo with a generated
  compliance report
- `tests/` - product-shell smoke, provenance, policy, index, and memory-tool tests

## Key docs

- [`docs/integrations/mcp-quickstart.md`](docs/integrations/mcp-quickstart.md) -
  governed MCP quickstart
- [`docs/integrations/codex-quickstart.md`](docs/integrations/codex-quickstart.md) -
  Codex local-stdio MCP quickstart
- [`docs/security/key-custody.md`](docs/security/key-custody.md) - key custody
  and erasure pattern
- [`docs/security/multi-agent-identity.md`](docs/security/multi-agent-identity.md) -
  env-root multi-agent identity setup
- [`docs/heartwood-memory-v1-prd.md`](docs/heartwood-memory-v1-prd.md) -
  de-risked V1 PRD
- [`docs/api/python-api.md`](docs/api/python-api.md) and
  [`docs/api/typescript-api.md`](docs/api/typescript-api.md) - API references
- Full documentation map: [`docs/README.md`](docs/README.md)

Run the console script after installation:

```bash
heartwood --help
```

For checkout development and test runs, install the local editable package:

```bash
python -m pip install -e ".[recall,mcp]"
python ./tests/smoke_test.py
python ./tests/test_memory_tool.py
python ./tests/test_provenance.py
python ./tests/test_trust_controls.py
python ./tests/test_index.py
python ./tests/test_inheritance.py
```

Run the TypeScript SDK tests:

```bash
npm --prefix ./sdk/typescript test
```

Run warm recall for hook/agent integration:

```bash
export HEARTWOOD_RECALL_TOKEN="$(openssl rand -hex 24)"
heartwood serve-recall --db ./heartwood.db --tenant tenant:ops --host 127.0.0.1 --port 8765
heartwood recall --url http://127.0.0.1:8765 --tenant tenant:ops --query "what memory applies here?" --k 5 --json
heartwood bench-recall --url http://127.0.0.1:8765 --tenant tenant:ops --query "what memory applies here?" --repeat 10 --max-p95-ms 500 --require-pass
```

Bulk-write JSON/JSONL records through the public tenant-aware API:

```bash
heartwood bulk-remember --input ./records.jsonl --db ./heartwood.db --tenant tenant:ops --output ./heartwood-bulk-report.json
python ./tests/test_bulk_api.py
```

## Research & Proof Harnesses

Heartwood began as a proof project: before building ambitious cognition, prove
boring trust - retrieval quality, generated-memory faithfulness, and deletion
lineage. You do not need these harnesses to use the product; they exist so the
governance claims above can be inspected and re-run.

Evidence boundary: the shipped package is `heartwood/` plus its SDK and adapter
surfaces. Product-facing enterprise retrieval evidence comes from
`experiments/product-retrieval/`, which ingests the enterprise trace through
`Heartwood.remember()` and evaluates `Heartwood.recall()`. The older
`experiments/typed-memory/` retrieval numbers remain research/proof-core
evidence, useful for design exploration and adapter validation but not a
substitute for product API gates.

## Experiments

Run the Phase 0 end-to-end suite:

```bash
python ./experiments/phase0-trust-suite/src/phase0_trust_suite.py
```

Run the portable suite for fresh clones, manual verification, or containers without local LongMemEval fixtures:

```bash
python ./experiments/phase0-trust-suite/src/phase0_trust_suite.py --skip-longmemeval
```

Run the suite with the live Postgres adapter gate:

```bash
python ./experiments/phase0-trust-suite/src/phase0_trust_suite.py --include-postgres
```

Run typed-memory enterprise and LongMemEval benchmarks:

```bash
python ./experiments/typed-memory/src/typed_memory_benchmark.py --dataset enterprise --require-pass
python ./experiments/typed-memory/src/typed_memory_benchmark.py --dataset longmemeval-s-session-100 --require-pass
```

Run the product API enterprise retrieval benchmark:

```bash
python ./experiments/product-retrieval/src/heartwood_product_benchmark.py --require-pass
python ./experiments/product-retrieval/src/heartwood_product_benchmark.py --phase1-scale --require-pass
```

Run the SQLite-backed local memory-plane path:

```bash
python ./experiments/typed-memory/src/memory_plane_cli.py ingest --db ./experiments/typed-memory/results/heartwood_memory_plane.sqlite
python ./experiments/typed-memory/src/memory_plane_cli.py recall --db ./experiments/typed-memory/results/heartwood_memory_plane.sqlite --query-id q_customer42_refund_eligibility
python ./experiments/typed-memory/src/memory_plane_cli.py inspect --db ./experiments/typed-memory/results/heartwood_memory_plane.sqlite
python ./experiments/typed-memory/src/memory_plane_cli.py export-eval --db ./experiments/typed-memory/results/heartwood_memory_plane.sqlite --jsonl-output ./experiments/typed-memory/results/recall_eval_export.jsonl
python ./experiments/typed-memory/src/storage_adapter_smoke.py --require-pass
```

Run snapshot import and statistical reporting:

```bash
python ./experiments/typed-memory/src/snapshot_import_smoke.py --require-pass
python ./experiments/typed-memory/src/confidence_interval_report.py --result ./experiments/typed-memory/results/enterprise_latest.json --require-pass
```

Run the live Postgres adapter directly:

```bash
python ./experiments/typed-memory/src/postgres_adapter_smoke.py --require-pass
```

Run database/search-specific Phase 0 harnesses:

```bash
python ./experiments/filtered-search/src/filtered_search_benchmark.py --require-pass
python ./experiments/temporal-conflict/src/temporal_conflict_benchmark.py --require-pass
python ./experiments/context-ablation/src/context_ablation_benchmark.py --require-pass
```

Run the recall benchmark:

```bash
python ./experiments/recall-benchmark/src/benchmark.py
```

Run the realistic-trace threshold gate after benchmark result files exist:

```bash
python ./experiments/recall-benchmark/src/evaluate_thresholds.py ./experiments/recall-benchmark/results/longmemeval_s_session_100.json ./experiments/recall-benchmark/results/longmemeval_s_turn_100.json ./experiments/recall-benchmark/results/longmemeval_m_session_25.json ./experiments/recall-benchmark/results/longmemeval_m_turn_25.json ./experiments/recall-benchmark/results/longmemeval_s_session_50_dense.json ./experiments/recall-benchmark/results/longmemeval_s_turn_50_dense.json --output ./experiments/recall-benchmark/results/phase0_threshold_results.json --markdown-output ./docs/results/phase-0-threshold-results.md
```

Run deletion-lineage smoke test:

```bash
python ./experiments/deletion-lineage/src/deletion_smoke.py --subject customer_42
```

Run realistic deletion-lineage retrieval-path test:

```bash
python ./experiments/deletion-lineage/src/deletion_realistic.py --subject customer_42
```

Run negative missing-lineage deletion test:

```bash
python ./experiments/deletion-lineage/src/deletion_negative.py --subject customer_42
```

Run faithfulness-gate smoke test:

```bash
python ./experiments/faithfulness-gate/src/faithfulness_smoke.py
```

Run realistic and negative faithfulness-gate tests:

```bash
python ./experiments/faithfulness-gate/src/faithfulness_realistic.py
python ./experiments/faithfulness-gate/src/faithfulness_negative.py
```

Run egress-policy gate tests:

```bash
python ./experiments/egress-policy/src/egress_policy_gate.py
python ./experiments/egress-policy/src/egress_policy_gate.py --requests ./experiments/egress-policy/data/negative_requests.jsonl --output ./experiments/egress-policy/results/negative_latest.json --expect-no-unsafe-external
python ./experiments/egress-policy/src/provider_registry_gate.py
```

Run resilience gates for adversarial tenancy, local concurrency, and deletion chaos:

```bash
python ./experiments/resilience/src/adversarial_multitenant.py
python ./experiments/resilience/src/scale_concurrency_soak.py
python ./experiments/resilience/src/deletion_chaos.py
```

Run example framework adapter contract tests for Hermes/OpenClaw-style memory surfaces:

```bash
python ./experiments/adapter-contracts/src/framework_adapter_contracts.py
```

Build the local container image:

```bash
docker build -t heartwood-memory:local .
```

Run the Heartwood MCP server with a persistent local volume:

```bash
docker run --rm -it -v heartwood-data:/data -e HEARTWOOD_TENANT=tenant:local heartwood-memory:local
```

Run the local Compose stack with Heartwood MCP plus Postgres:

```bash
docker compose up --build
```

Build and run the verification image instead of the runtime image:

```bash
docker build --target verify -t heartwood-memory-verify .
docker run --rm heartwood-memory-verify
```

The verification image runs the portable trust suite. Run the local suite from the repo when the generated LongMemEval fixtures are available.

## License

The core package in this repository is MIT licensed; see `LICENSE`. Commercial
support, signed release distribution, managed key custody, and hosted services
may be offered separately from the MIT core.

## 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.
