Skip to content

Architecture Overview

HotMem is a local-first memory sidecar. It keeps the canonical runtime state in SQLite, exposes a small HTTP/API surface, and supports Python, TypeScript, and MCP integrations.

Runtime path

agent or application
  -> HTTP, SDK, or MCP client
  -> HotMem runtime
  -> SQLite records and local file references
  -> search, inspection, snapshot, or hydration

The runtime is designed to be inspectable and embeddable. It does not require a hosted database or a separate control plane for local use.

Memory records

Small, prompt-ready facts can be stored inline. A file-backed memory can retain the source URI, byte range, format, checksum, and optional summary without copying the referenced content into SQLite. File references are hydrated only when requested and are checked against their recorded provenance when a checksum is available.

The built-in storage adapter is local filesystem-only. Unsupported remote URI schemes fail explicitly instead of being silently fetched.

Search and inspection

HotMem combines deterministic text embeddings, keyword overlap, and importance to rank local memories. Read-only inspectors provide lightweight metadata for CSV, JSONL, and Parquet files without turning the runtime into a query engine.

Inspection is advisory: it never authorizes import, hydration, snapshot, or provenance decisions. JSONL validation is sampled by default (lines inside the declared sample window only) and the result declares its assurance level via metadata.validation (sampled | full); pass --full-validation (CLI) or validation="full" to parse every line. Authoritative verification of canonical memory content always happens through provenance checksums, not through inspection.

An optional derived vector index can accelerate candidate retrieval. The index is disposable and rebuildable from SQLite, sits in front of the canonical hybrid ranker rather than replacing it, and search falls back to the deterministic SQLite scan whenever the index is absent or stale. SQLite, files, bundles, and manifests remain canonical storage; the index is never a source of truth.

Portability

JSONL and JSONL.GZ are supported portable record formats. Snapshot v2 adds a versioned manifest, per-file checksums, an aggregate digest, and optional attachments or file references. Hydration verifies the package before loading records and skips equivalent logical memories on repeat imports.

New file and provenance fields are additive: existing identifier/fact payloads, search responses, JSONL files, and client integrations remain supported.