HotMem

Portable, local-first memory for AI agents and digital organizations. HotMem turns the facts, decisions, project context, and provenance an agent needs into a queryable memory store that can be snapshotted, verified, restored, and moved between compatible HotMem runtimes.

It is the memory layer for teams building with coding agents, enterprise workflows, creative tools, and personal knowledge systems: one SQLite runtime, one local HTTP port, and a portable JSONL-based interchange path. Agents can write, retrieve, inspect, and manage their own scoped memory through HTTP, Python, TypeScript, or MCP.

HotMem provides fast hybrid vector + keyword retrieval and returns LLM-ready message objects you can stitch directly into prompts. It supports Python 3.11, 3.12, 3.13, and 3.14.

What is available today: local-first runtime memory, portable JSONL and integrity-checked Snapshot v2 exports, restore/hydration, provenance, lifecycle events, and framework/MCP integrations. Verified interchange packages and incremental synchronization are active roadmap work; HotMem does not yet claim hosted sync, encryption, signing, or automatic multi-writer conflict resolution.

Why HotMem

• Move an agent's working brain. Snapshot project or session memory and hydrate it in a clean HotMem instance without rebuilding the context by hand.
• Keep the source of truth local. The runtime is a SQLite mount, not a required hosted vector database or proprietary control plane.
• Make memory agent-operable. HTTP, Python, TypeScript, and MCP surfaces let an agent add facts, recall context, create snapshots, and inspect state.
• Preserve provenance and integrity. Snapshot v2 carries a versioned manifest, deterministic identifiers, SHA-256 file checksums, and optional file references.
• Hand sessions across agents with verification. hotmem-handoff-v1 packages (#101) move a Codex session's useful working context into a Claude target: ordered stream, bounded resume brief, selected durable memories, explicit consent, deny-by-default redaction, fail-closed verification, and atomic idempotent hydration — one implementation behind CLI, MCP, and HTTP. Clean-room walkthrough: examples/handoff_showcase.
• Avoid a migration cliff. HotMem supports legacy JSONL/JSONL.GZ snapshots and includes a one-command importer for a Mem0 SQLite history database.

Read the agent-memory portability guide for the current contract, examples, and roadmap boundaries.

The long-term direction is intentionally explicit: the HotMem Vision and Canon records the non-negotiable product principles and the delivery path toward a universal memory-interchange standard. It distinguishes that destination from features that are available in the current release.

Install

pip install hotmem
# or
uv pip install hotmem

Quick Start

# Start with a mount directory (portable memory)
hotmem serve --mount ./hotmem

# Or just start (uses temp DB)
hotmem serve

CLI

hotmem serve --port 8711 --mount ./data/hotmem
hotmem serve --db ./my.sqlite
hotmem hydrate --file swap.jsonl --db ./my.sqlite
hotmem hydrate --file swap.jsonl.gz --db ./my.sqlite
hotmem snapshot --file swap.jsonl --db ./my.sqlite
hotmem status

API

All endpoints under /v1. Default: http://127.0.0.1:8711

GET /v1/health

{"status": "ok", "memory_count": 42, "db_path": "...", "uptime_s": 120.5}

POST /v1/add

{"identifier": "vendor_x", "fact": "Invoice total was $5000", "importance": 0.8}

POST /v1/search

{"query": "duplicate invoice risk", "top_k": 5, "max_chars": 1500}

Returns ranked message objects ready for LLM stitching:

{
  "memories": [
    {"role": "system", "content": "...", "memory_id": "...", "identifier": "...", "score": 0.87}
  ],
  "count": 5,
  "trace_ms": 2.1
}

POST /v1/hydrate

{"file": "swap.jsonl"}

POST /v1/snapshot

{"file": "swap.jsonl"}

Python Client

from hotmem.client import HotMemClient

with HotMemClient("http://127.0.0.1:8711") as client:
    client.add("vendor_x", "Invoice total $5000", importance=0.8)

    memories = client.search("duplicate invoice risk", top_k=5, max_chars=1500)

    # memories are LLM-ready message objects
    messages = memories + [{"role": "user", "content": "Analyze this vendor."}]

Ecosystem

HotMem core stays zero-dep. Framework adapters live in adapters/, each a separate pip-installable package wrapping HotMemClient:

The hotmem-hermes adapter is the deep integration: HotMem implements the Hermes Memory Provider Plugin interface, so Hermes calls into HotMem at every lifecycle point automatically (prefetch, sync, memory-write mirroring, pre-compress extraction, session-end snapshot).

A typed TypeScript client (npm install hotmem) lives in ts/ — zero-dependency, works in Node 18+, Deno, Bun, and edge runtimes.

Mounting

Any directory can be a HotMem mount. The mount contains:

• hotmem.sqlite - the database
• swap.jsonl - portable JSONL backup
• manifest.json - mount metadata

Plain .jsonl is the canonical portable swap format. HotMem can also hydrate from and snapshot to .jsonl.gz for compressed archives.

hotmem serve --mount /mnt/usb/hotmem     # portable memory on USB
hotmem serve --mount ./data/hotmem        # local project memory

Snapshot, restore, and migration

Use a directory path for an integrity-checked Snapshot v2 package, or use .jsonl / .jsonl.gz for the canonical portable record stream:

# Create a verified directory snapshot from one workspace.
hotmem snapshot --db ./source/hotmem.sqlite --file ./company-brain

# Restore it into a new workspace or runtime.
hotmem hydrate --db ./target/hotmem.sqlite --file ./company-brain

# Import current state from a Mem0 SQLite history database.
hotmem import --from mem0 --db ./mem0/history.db --target ./hotmem.sqlite

Snapshot v2 verifies SHA-256 checksums before hydration. Replaying the same snapshot does not create duplicate logical memories. See the Snapshot v2 format for the exact current guarantees.

Development

uv sync                          # install deps
uv run pytest                    # run tests
uv run ruff check src/ tests/    # lint
uv run ruff format src/ tests/   # format
uv build                         # build wheel

Architecture

HotMem keeps runtime state in SQLite and uses small, explicit modules for storage, ranking, portability, the HTTP server, and client integrations:

Contributing

See CONTRIBUTING.md for development setup and guidelines.

License

MIT - see LICENSE.