homestead-memory

Stop renting your mind.

A tamper-evident record of what your AI agent actually did, in a local file, that someone who does not trust you can verify. Tamper-evident, not tamper-proof: what it defends against and what it does not.

Agents fail quietly. The run reports success, the tool returns 200, and the thing you asked for did not happen. There is usually no record to contradict it. This keeps one, and every entry is hash-chained to the one before it, so see it catch a forged record, live:

pip install homestead-memory      # Python 3.10+, macOS / Linux / Windows

hsm watch --demo
#      0  14:02:11  Bash    npm test
#      1  14:02:19  Read    src/api/billing.py
#      2  14:02:24  Edit    src/api/billing.py
#
# ② now someone edits record 1…
#   !! chain break at index 1: hash_mismatch
#      record content does not match its own hash (edited in place)
#   exit 1  ·  gate it in CI like a test

Got No matching distribution found? macOS still ships Python 3.9 as its built-in python3, and this needs 3.10+. Nothing is wrong with the package. Either use a newer Python, or skip installing entirely: uvx --from homestead-memory hsm watch --demo (uv fetches a suitable Python for you.)

Record your own agent

hsm hook --install     # prints a Claude Code hook; you paste it, nothing is edited for you
hsm watch              # what your agent did, in order

Every entry is hash-chained to the one before it, so editing, deleting, or reordering any record breaks every hash after it. hsm watch reports the break at the exact index and exits non-zero. Sign it and a wholly rebuilt chain is caught too.

Both phases are recorded, which is what makes it evidence rather than a log. The hook captures the decision before a tool runs and the outcome after. A record of outcomes alone shows what happened; it cannot show that anything was authorised first. As the IETF Agent Audit Trail draft puts it, "a denial that is only logged after execution provides no evidence that the denial was enforced".

hsm export --format aat     # the same ledger as draft-sharif-agent-audit-trail-01

That draft maps explicitly to EU AI Act Article 12, and this emits it alongside the native format rather than replacing it, so nothing already on disk changes. Where we differ we say so: it specifies ECDSA P-256, which the AAT export uses, while the native EvidencePack stays Ed25519 so its verifier can remain standard-library only and a recipient needs nothing installed.

Know this before you rely on the AAT export. That draft is an individual Internet-Draft, not an adopted standard: it has no working group behind it and carries the usual notice that it "is not endorsed by the IETF". Its author has also filed IPR disclosure 7558, covering revisions 00 and 01 in full, declaring "Reasonable and Non-Discriminatory License to All Implementers with Possible Royalty/Fee". RAND with a possible fee is not royalty-free, and this package is MIT, which grants you no patent licence. We ship the export because interoperability is worth having and we have asked the author to clarify what implementers are taking on. Until there is an answer, treat --format aat as a convenience rather than something to build a compliance programme on. The native ledger and EvidencePack carry no such disclosure, and they are what the rest of this README argues for.

What it costs you: about 124ms per tool call (median; 138ms p95, measured on an M3 Pro with a 4KB tool response). Since 0.4.0 the hook records both phases, so it runs as a fresh process twice per call, once before your tool runs and once after: about 61ms and 63ms respectively. On a 100-call session that is roughly 12 seconds spread across the run. Almost all of it is Python interpreter and import startup rather than the recording itself. If that is too much for your loop, do not install the hook: the number is here so you can decide before you find out.

Earlier releases documented 68ms, which was correct when only PostToolUse was recorded. Recording the decision phase is what makes the ledger evidence of enforcement rather than of observation, and it costs a second process. Stating the higher number rather than the one that flatters us is the same reason the rest of these figures are here.

This is a file, not a platform. Agent observability tools are far richer than this and they want a deployment: the self-hosted ones document a production floor of several services and roughly 16 GB of RAM. This is pip install, one hook line, and a JSONL file on your disk. Different job. If you need dashboards, evals, and span analytics, use one of those. If you want a record you can grep and prove, use this.

Secret-shaped values are redacted and payloads truncated to a 200-character head, with a SHA-256 of the full original kept so the evidence survives redaction. That is a mitigation, not a guarantee: no pattern list is complete.

hsm export --evidence  # a pack anyone can verify with no install at all

The pack carries the records, the signature, the public key, an integrity report, and a standard-library verifier a third party can read in full and run. It states what it does NOT prove, including that a signature only establishes origin if you already know which key to expect.

What this defends against, and what it does not

Tamper-evident, not tamper-proof. The difference matters, so here it is plainly.

It catches:

• A record edited in place. The hash stops matching and hsm watch names the index.

• A record deleted or reordered. Every hash after it breaks.

• A silently dropped write. Drops are recorded and reported, never swallowed.

• A whole chain rebuilt from scratch by someone who recomputed every hash, provided you ran hsm checkpoint, you pin the expected signer, and they do not hold your key. All three matter. A checkpoint verified without a pinned key is self-asserted: it checks the signature against whichever key sits beside it, so a rebuilt chain re-signed with the attacker's own key also passes. hsm verify --deep now says so when no key is pinned.

  bash

  Copy

  hsm verify --deep --signer <your pubkey>   # or the checkpoint is self-asserted
  

• Anything altered after you handed someone an EvidencePack, which they can check with no install and nothing from us.

A checkpoint covers its prefix, not the future. Records appended after your last checkpoint can be replaced with a correctly re-chained forgery and still verify, because a signature cannot cover records that did not exist when it was made. hsm verify tells you how many records are uncovered. Re-checkpoint often, or that tail grows.

It does not catch:

• An attacker who holds your signing key. The key lives at ~/.config/homestead-memory/ed25519_key, on the same machine as the ledger. Anyone who can rewrite the file can usually read that key, re-sign the rewrite, and pass. If that is your threat model, run hsm checkpoint --export, publish the line somewhere they do not control, and check the ledger against it later with hsm checkpoint --verify. A head hash reveals nothing about the records, so publishing one leaks nothing.
• A tool that lies. See below.
• Anything that never reached the ledger at all, such as a hook you did not install.

hsm checkpoint            # sign the current head
hsm checkpoint --export   # one line to publish where an attacker cannot reach
hsm checkpoint --verify   # check this ledger against a line you published earlier

hsm watch reports how much of the ledger the checkpoint covers, and fails if the checkpoint no longer verifies. Everything appended since your last checkpoint is uncovered, so re-checkpoint often.

It records what your harness reported

The hook receives what the harness says a tool did. It is not independent observation.

If a tool reports success while doing nothing, that is precisely the failure this exists to catch, because you get a durable record of the claim and can compare it against reality. But if a tool reports something false about what it did, the ledger will faithfully record a hash-chained, signed falsehood.

The record proves the record was not altered. It does not make the harness truthful.

Why not just OpenTelemetry, or signed logs, or Langfuse

Reasonable questions, and mostly they are different jobs.