Remembra 5.4.0 — Developer platform

Remembra 5.4.0 — Developer platform

Remembra is external memory for AI assistants. This release makes it
straightforward to integrate: explicit API versioning, hardened SDKs in two
languages, frozen batch semantics with durable idempotency, signed webhook
delivery, and a machine-readable contract with a verified example suite.

It is additive. Existing /api/v1 paths, legacy routes, and response bodies
are unchanged, and no upgrade action is required.

What is new

• Versioned API metadata — GET /api/v1/capabilities and an
  X-Remembra-API-Version header, with /api/v1 remaining the canonical
  namespace. No second /v1 alias.
• Hardened TypeScript SDK — typed snapshot create/restore, bounded timeout
  composition, request-ID propagation, typed network-error normalization,
  opt-in read-only retries, stable opaque cursor pagination, and a client-side
  batch budget guard.
• Frozen batch contract — explicit per-item and read-only execution
  metadata, sanitized per-item failures, bounded read-only batch search, and a
  transactional SQLite Idempotency-Key ledger with current-authorization
  preflight and recheck, integrity-protected rows, non-expiring claims,
  capacity limits, and a durable data gate.
• Signed webhook delivery (@hilbras/remembra/webhooks) — a closed event
  set, allowlist-only payloads with no embedding vectors or credential-like
  fields, HMAC-SHA256 t,v1 signatures with a bounded timestamp window, a
  receiver replay guard, an integrity-protected durable queue, and bounded
  exponential backoff. Opt-in through REMEMBRA_WEBHOOKS.
• Receiver examples — the delivery contract is only useful if the
  subscriber checks it, so verified Node and Python receivers ship alongside
  the sender. Each reads the raw body, verifies x-remembra-signature against
  those exact bytes, and rejects a repeated delivery id. An end-to-end test
  drives the real CLI into the real receiver and confirms a forged body, an
  expired timestamp, a foreign secret, and a replayed delivery id are each
  refused.
• Dependency-free Python SDK (hilbras-remembra) — synchronous and
  asynchronous clients with the same routes, authentication, error hierarchy,
  retry policy, pagination, and idempotency rules, using only the standard
  library. A parity test reads the published TypeScript contract so the two
  SDKs cannot drift apart.
• OpenAPI 3.1 contract and examples — docs/openapi.yaml documents the
  full /api/v1 surface, with a regression test that fails when a served
  route, limit, idempotency rule, or capability is undocumented. Runnable
  examples cover Node, Python, FastAPI, RAG, local-LLM, Next.js, React, and an
  AI agent.
• An honest CLI — remembra --version and remembra --help answer before
  any configuration validation, storage-directory creation, or server start.

Safety properties that are now enforced

• The durable data gate records its owner. A data restore is completed with
  remembra recover verify; an interrupted tenant migration stays resumable
  through migrate apply, and verification refuses to publish a half-applied
  migration.
• An unsafe or replaced gate marker is never auto-cleared and can no longer
  discard replay claims.
• A released keyed-batch claim keeps binding the key to its original operation,
  so a released key can never be reused for a different operation.
• A pre-existing claim ledger is verified row by row and rebuilt in place, so
  replay history survives an upgrade while tampering still fails closed.
• An unreadable durable recovery state fails that one write closed without
  latching Failed for every later write and read.
• Webhook payloads never carry embedding vectors, provenance internals, or
  credential-like fields, and a failed delivery can never fail the write that
  produced the event.

Gate evidence

Verified on Node 18.20.8 and Node 24.21.0:

Gate	Result
Build	pass
Full suite	567 tests, 0 failures
Security matrix	139 tests, 0 failures
Recovery matrix	52 tests, 0 failures
Python SDK	28 tests, 0 failures
Documentation links	39 files, 0 broken
npm audit --omit=dev	0 vulnerabilities
Package dry run	241 files
Registry install	npm install @hilbras/remembra@5.4.0; every subpath imports and a signature verifies
PyPI publication	pip install hilbras-remembra==5.4.0; zero dependencies, identical batch limits
Artifact identity	published wheel and sdist hash-match the artifacts built from this commit
Tenant and scale benchmarks	within documented ceilings

Deliberate non-claims

V5.4.0 does not claim distributed quotas, distributed workers, or the advanced
retrieval engine — V5.1 through V5.3 remain unfinished. Public batch embedding
remains unavailable, idempotency and webhook delivery state are single-host,
and no V5.5 tenancy or V6 runtime work is included.

Known limitation

The pinned better-sqlite3 11.x binding can abort a test process during
environment teardown after every assertion has reported. The test scripts
re-run only the aborted files, log each recovery, and still fail immediately on
any real failure. Upgrading past 11.x requires Node 20+, which conflicts with
this release line's Node 18 gate.

Documentation

• Compatibility report: docs/v5.4.0-compatibility.md
• Public API: docs/public-api.md
• TypeScript SDK: docs/sdk.md
• Python SDK: docs/python.md
• Examples: docs/examples.md
• OpenAPI: docs/openapi.yaml

Thanks to everyone who reported issues and tested the pre-release builds.