hotmem 0.1.3__py3-none-any.whl

hotmem/__init__.py

@@ -0,0 +1,3 @@
+"""HotMem — A local-first memory sidecar for agent applications."""
+
+__version__ = "0.1.0"

hotmem/cli.py

@@ -0,0 +1,118 @@
+"""HotMem CLI — command-line interface for the memory sidecar.
+
+Purpose:
+    Provide serve, hydrate, snapshot, and status commands.
+    Entry point: `hotmem` (registered in pyproject.toml).
+
+Interface:
+    main() — Click group with subcommands
+
+Deps: click, uvicorn, hotmem.server, hotmem.mount, hotmem.db, hotmem.swap, hotmem.trace
+Extension: add new subcommands (e.g. `hotmem inspect`, `hotmem gc`) here.
+"""
+
+from __future__ import annotations
+
+import tempfile
+
+import click
+
+from hotmem.trace import get_tracer
+
+_trace = get_tracer("cli")
+
+
+@click.group()
+@click.version_option(package_name="hotmem")
+def main():
+    """HotMem — local-first memory sidecar for agent applications."""
+
+
+@main.command()
+@click.option("--port", default=8711, type=int, help="Port to listen on.")
+@click.option("--mount", default=None, type=click.Path(), help="Mount directory path.")
+@click.option("--db", "db_path", default=None, type=click.Path(), help="Explicit database path.")
+@click.option("--host", default="127.0.0.1", help="Host to bind to.")
+def serve(port: int, mount: str | None, db_path: str | None, host: str):
+    """Start the HotMem sidecar server."""
+    import uvicorn
+
+    from hotmem.mount import bootstrap_mount
+    from hotmem.server import create_app
+
+    swap_path = None
+
+    if mount:
+        config = bootstrap_mount(mount)
+        db_path = str(config.db_path)
+        swap_path = str(config.swap_path)
+    elif not db_path:
+        db_path = tempfile.mktemp(suffix=".sqlite", prefix="hotmem_")
+        _trace.warn(
+            "serve", "no mount or db path specified, using temp db",
+            detail={"path": db_path},
+        )
+
+    app = create_app(db_path=db_path, swap_path=swap_path, port=port)
+
+    _trace.info(
+        "serve", f"starting server on {host}:{port}",
+        detail={"db": db_path, "mount": mount},
+    )
+    uvicorn.run(app, host=host, port=port, log_level="warning")
+
+
+@main.command()
+@click.option(
+    "--file", "swap_file", default="swap.jsonl",
+    type=click.Path(), help="Swap file path.",
+)
+@click.option("--db", "db_path", required=True, type=click.Path(), help="Database path.")
+def hydrate(swap_file: str, db_path: str):
+    """Load a swap file into the database."""
+    from hotmem.db import MemoryDB
+    from hotmem.swap import hydrate as do_hydrate
+
+    db = MemoryDB(db_path)
+    result = do_hydrate(db, swap_file)
+    db.close()
+
+    click.echo(f"Loaded: {result.loaded}, Skipped dupes: {result.skipped_dupes}")
+
+
+@main.command()
+@click.option(
+    "--file", "swap_file", default="swap.jsonl",
+    type=click.Path(), help="Output swap file path.",
+)
+@click.option("--db", "db_path", required=True, type=click.Path(), help="Database path.")
+def snapshot(swap_file: str, db_path: str):
+    """Export database memories to a swap file."""
+    from hotmem.db import MemoryDB
+    from hotmem.swap import snapshot as do_snapshot
+
+    db = MemoryDB(db_path)
+    result = do_snapshot(db, swap_file)
+    db.close()
+
+    click.echo(f"Exported: {result.exported} → {result.path}")
+
+
+@main.command()
+@click.option("--port", default=8711, type=int, help="Port to check.")
+@click.option("--host", default="127.0.0.1", help="Host to check.")
+def status(port: int, host: str):
+    """Check if a HotMem server is running."""
+    import httpx
+
+    url = f"http://{host}:{port}/v1/health"
+    try:
+        resp = httpx.get(url, timeout=3.0)
+        data = resp.json()
+        click.echo(f"Status: {data['status']}")
+        click.echo(f"Memories: {data['memory_count']}")
+        click.echo(f"DB: {data['db_path']}")
+        click.echo(f"Uptime: {data['uptime_s']}s")
+    except httpx.ConnectError as err:
+        click.echo(f"No HotMem server found at {url}", err=True)
+        raise SystemExit(1) from err

hotmem/client.py

@@ -0,0 +1,100 @@
+"""HotMem client — Python SDK for the memory sidecar.
+
+Purpose:
+    Provide a simple, typed client for the HotMem HTTP API.
+    Designed for direct use in agent applications and SPA backends.
+
+Interface:
+    HotMemClient(base_url)
+        .add(identifier, fact, ...) -> dict
+        .search(query, top_k, max_chars?) -> list[MessageObject]
+        .health() -> dict
+        .hydrate(file?) -> dict
+        .snapshot(file?) -> dict
+
+Deps: httpx
+Extension: add async client, retry logic, or connection pooling here.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+
+class HotMemClient:
+    """Synchronous client for the HotMem sidecar API."""
+
+    def __init__(self, base_url: str = "http://127.0.0.1:8711") -> None:
+        self.base_url = base_url.rstrip("/")
+        self._client = httpx.Client(base_url=self.base_url, timeout=30.0)
+
+    def health(self) -> dict[str, Any]:
+        """Check server health."""
+        resp = self._client.get("/v1/health")
+        resp.raise_for_status()
+        return resp.json()
+
+    def add(
+        self,
+        identifier: str,
+        fact: str,
+        *,
+        source: str = "",
+        importance: float = 0.5,
+        metadata: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """Add a fact to memory."""
+        payload = {
+            "identifier": identifier,
+            "fact": fact,
+            "source": source,
+            "importance": importance,
+            "metadata": metadata or {},
+        }
+        resp = self._client.post("/v1/add", json=payload)
+        resp.raise_for_status()
+        return resp.json()
+
+    def search(
+        self,
+        query: str,
+        top_k: int = 5,
+        max_chars: int | None = None,
+    ) -> list[dict[str, Any]]:
+        """Search memories and return LLM-ready message objects."""
+        payload: dict[str, Any] = {"query": query, "top_k": top_k}
+        if max_chars is not None:
+            payload["max_chars"] = max_chars
+        resp = self._client.post("/v1/search", json=payload)
+        resp.raise_for_status()
+        return resp.json()["memories"]
+
+    def hydrate(self, file: str | None = None) -> dict[str, Any]:
+        """Trigger swap file hydration."""
+        payload: dict[str, Any] = {}
+        if file:
+            payload["file"] = file
+        resp = self._client.post("/v1/hydrate", json=payload)
+        resp.raise_for_status()
+        return resp.json()
+
+    def snapshot(self, file: str | None = None) -> dict[str, Any]:
+        """Trigger database snapshot to swap file."""
+        payload: dict[str, Any] = {}
+        if file:
+            payload["file"] = file
+        resp = self._client.post("/v1/snapshot", json=payload)
+        resp.raise_for_status()
+        return resp.json()
+
+    def close(self) -> None:
+        """Close the underlying HTTP client."""
+        self._client.close()
+
+    def __enter__(self) -> HotMemClient:
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()

hotmem/db.py

@@ -0,0 +1,152 @@
+"""HotMem database — SQLite storage with cosine similarity UDF.
+
+Purpose:
+    Manage the memories table: create schema, insert, query, count.
+    Registers a pure-python cosine similarity function as a SQLite UDF
+    so vector search runs inside the DB engine.
+
+Interface:
+    MemoryDB(db_path: str | Path)
+        .insert(id, identifier, fact_text, embedding_blob, ...) -> None
+        .search_all() -> list[Row]
+        .count() -> int
+        .all_rows() -> list[Row]
+        .exists(content_hash: str) -> bool
+        .close() -> None
+
+Deps: hotmem.embed (for unpack_embedding), hotmem.trace
+Extension: add indexes, FTS5, or WAL mode tuning here.
+"""
+
+from __future__ import annotations
+
+import math
+import sqlite3
+import struct
+from pathlib import Path
+from typing import Any
+
+from hotmem.embed import EMBEDDING_DIM
+from hotmem.trace import get_tracer
+
+_trace = get_tracer("db")
+
+_SCHEMA = f"""
+CREATE TABLE IF NOT EXISTS memories (
+    id              TEXT PRIMARY KEY,
+    identifier      TEXT NOT NULL,
+    fact_text       TEXT NOT NULL,
+    embedding       BLOB,
+    embedding_dim   INTEGER DEFAULT {EMBEDDING_DIM},
+    embedding_model TEXT DEFAULT '',
+    source          TEXT DEFAULT '',
+    importance      REAL DEFAULT 0.5,
+    metadata_json   TEXT DEFAULT '{{}}',
+    content_hash    TEXT DEFAULT '',
+    created_at      TEXT DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ', 'now'))
+);
+CREATE INDEX IF NOT EXISTS idx_memories_identifier ON memories(identifier);
+CREATE INDEX IF NOT EXISTS idx_memories_content_hash ON memories(content_hash);
+"""
+
+
+def _cosine_similarity(blob_a: bytes | None, blob_b: bytes | None) -> float | None:
+    """SQLite UDF: cosine similarity between two packed float32 blobs."""
+    if blob_a is None or blob_b is None:
+        return None
+    n = len(blob_a) // 4
+    a = struct.unpack(f"{n}f", blob_a)
+    b = struct.unpack(f"{n}f", blob_b)
+    dot = sum(x * y for x, y in zip(a, b, strict=True))
+    norm_a = math.sqrt(sum(x * x for x in a))
+    norm_b = math.sqrt(sum(x * x for x in b))
+    if norm_a == 0 or norm_b == 0:
+        return 0.0
+    return dot / (norm_a * norm_b)
+
+
+class MemoryDB:
+    """SQLite-backed memory store with cosine similarity UDF."""
+
+    def __init__(self, db_path: str | Path) -> None:
+        self.db_path = str(db_path)
+        self._conn = sqlite3.connect(self.db_path, check_same_thread=False)
+        self._conn.row_factory = sqlite3.Row
+        self._conn.execute("PRAGMA journal_mode=WAL")
+        self._conn.execute("PRAGMA synchronous=NORMAL")
+        self._conn.create_function("cosine_sim", 2, _cosine_similarity)
+        self._conn.executescript(_SCHEMA)
+        _trace.info("init", "database opened", detail={"path": self.db_path})
+
+    def insert(
+        self,
+        id: str,
+        identifier: str,
+        fact_text: str,
+        embedding: bytes,
+        *,
+        embedding_dim: int = EMBEDDING_DIM,
+        embedding_model: str = "",
+        source: str = "",
+        importance: float = 0.5,
+        metadata_json: str = "{}",
+        content_hash: str = "",
+    ) -> None:
+        """Insert a memory row."""
+        self._conn.execute(
+            """INSERT OR REPLACE INTO memories
+            (id, identifier, fact_text, embedding, embedding_dim, embedding_model,
+             source, importance, metadata_json, content_hash)
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)""",
+            (
+                id,
+                identifier,
+                fact_text,
+                embedding,
+                embedding_dim,
+                embedding_model,
+                source,
+                importance,
+                metadata_json,
+                content_hash,
+            ),
+        )
+        self._conn.commit()
+        _trace.debug("insert", f"stored memory {id[:8]}…", detail={"identifier": identifier})
+
+    def search_with_cosine(self, query_embedding: bytes) -> list[dict[str, Any]]:
+        """Return all memories with their cosine similarity to the query embedding."""
+        rows = self._conn.execute(
+            """SELECT id, identifier, fact_text, importance, metadata_json, source,
+                      cosine_sim(embedding, ?) AS cosine_score
+               FROM memories
+               ORDER BY cosine_score DESC""",
+            (query_embedding,),
+        ).fetchall()
+        return [dict(r) for r in rows]
+
+    def count(self) -> int:
+        """Return total number of stored memories."""
+        row = self._conn.execute("SELECT COUNT(*) FROM memories").fetchone()
+        return row[0]
+
+    def all_rows(self) -> list[dict[str, Any]]:
+        """Return all memory rows as dicts (for snapshot export)."""
+        rows = self._conn.execute(
+            """SELECT id, identifier, fact_text, embedding_dim, embedding_model,
+                      source, importance, metadata_json, content_hash, created_at
+               FROM memories"""
+        ).fetchall()
+        return [dict(r) for r in rows]
+
+    def exists(self, content_hash: str) -> bool:
+        """Check if a memory with this content hash already exists."""
+        row = self._conn.execute(
+            "SELECT 1 FROM memories WHERE content_hash = ? LIMIT 1", (content_hash,)
+        ).fetchone()
+        return row is not None
+
+    def close(self) -> None:
+        """Close the database connection."""
+        self._conn.close()
+        _trace.info("close", "database closed", detail={"path": self.db_path})

hotmem/embed.py

@@ -0,0 +1,69 @@
+"""HotMem embedding — deterministic hash-based embedder for MVP.
+
+Purpose:
+    Convert text into a fixed-dimension float vector using deterministic hashing.
+    No external model required. Provides real cosine-similarity semantics via
+    character n-gram hashing.
+
+Interface:
+    embed_text(text: str) -> list[float]
+    pack_embedding(vec: list[float]) -> bytes
+    unpack_embedding(blob: bytes) -> list[float]
+    EMBEDDING_DIM: int
+    EMBEDDING_MODEL: str
+
+Deps: none (stdlib only)
+Extension: replace embed_text() with a real model call (sentence-transformers, OpenAI, etc.).
+"""
+
+from __future__ import annotations
+
+import hashlib
+import math
+import struct
+
+from hotmem.trace import Timer, get_tracer
+
+_trace = get_tracer("embed")
+
+EMBEDDING_DIM = 64
+EMBEDDING_MODEL = "hotmem-hash-v1"
+
+
+def embed_text(text: str) -> list[float]:
+    """Produce a deterministic embedding vector from text.
+
+    Uses overlapping character trigrams hashed into buckets, then L2-normalized.
+    Semantically similar strings share trigrams and thus produce closer vectors.
+    """
+    with Timer() as t:
+        vec = [0.0] * EMBEDDING_DIM
+        text_lower = text.lower()
+
+        # Hash overlapping trigrams into embedding buckets
+        for i in range(max(1, len(text_lower) - 2)):
+            gram = text_lower[i : i + 3]
+            h = int(hashlib.md5(gram.encode(), usedforsecurity=False).hexdigest(), 16)
+            bucket = h % EMBEDDING_DIM
+            # Use upper bits for sign/magnitude
+            sign = 1.0 if (h >> 64) % 2 == 0 else -1.0
+            vec[bucket] += sign
+
+        # L2 normalize
+        norm = math.sqrt(sum(x * x for x in vec))
+        if norm > 0:
+            vec = [x / norm for x in vec]
+
+    _trace.debug("compute", "embedded text", detail={"chars": len(text), "ms": round(t.ms, 2)})
+    return vec
+
+
+def pack_embedding(vec: list[float]) -> bytes:
+    """Pack float vector into a compact binary blob (float32 array)."""
+    return struct.pack(f"{len(vec)}f", *vec)
+
+
+def unpack_embedding(blob: bytes) -> list[float]:
+    """Unpack binary blob back into float vector."""
+    count = len(blob) // 4
+    return list(struct.unpack(f"{count}f", blob))

hotmem/mount.py

@@ -0,0 +1,69 @@
+"""HotMem mount — portable memory directory management.
+
+Purpose:
+    Bootstrap and manage a mount directory that contains hotmem.sqlite,
+    swap.jsonl, and manifest.json. Any directory can become a HotMem mount.
+
+Interface:
+    MountConfig(mount_path) — resolves paths within the mount
+    bootstrap_mount(mount_path) -> MountConfig — creates dir + manifest if needed
+
+Deps: hotmem.trace
+Extension: add manifest versioning, remote mount sync, or encryption here.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from pathlib import Path
+
+from hotmem import __version__
+from hotmem.trace import get_tracer
+
+_trace = get_tracer("mount")
+
+
+@dataclass
+class MountConfig:
+    """Resolved paths within a HotMem mount directory."""
+
+    mount_path: Path
+    db_path: Path
+    swap_path: Path
+    manifest_path: Path
+
+
+def bootstrap_mount(mount_path: str | Path) -> MountConfig:
+    """Ensure a mount directory exists with the expected structure.
+
+    Creates the directory and manifest.json if they don't exist.
+    Returns resolved paths for db, swap, and manifest files.
+    """
+    mount_path = Path(mount_path).resolve()
+    mount_path.mkdir(parents=True, exist_ok=True)
+
+    config = MountConfig(
+        mount_path=mount_path,
+        db_path=mount_path / "hotmem.sqlite",
+        swap_path=mount_path / "swap.jsonl",
+        manifest_path=mount_path / "manifest.json",
+    )
+
+    if not config.manifest_path.exists():
+        manifest = {
+            "hotmem_version": __version__,
+            "created_at": datetime.now(UTC).isoformat(),
+            "mount_path": str(mount_path),
+        }
+        config.manifest_path.write_text(json.dumps(manifest, indent=2) + "\n")
+        _trace.info(
+            "bootstrap", "created mount directory", detail={"path": str(mount_path)}
+        )
+    else:
+        _trace.info(
+            "bootstrap", "using existing mount", detail={"path": str(mount_path)}
+        )
+
+    return config

hotmem/search.py

@@ -0,0 +1,100 @@
+"""HotMem search — hybrid ranking with message-shaped output.
+
+Purpose:
+    Given a query, embed it, retrieve candidates from the DB, apply hybrid scoring
+    (cosine + keyword overlap + importance), and return LLM-ready message objects.
+
+Interface:
+    search_memories(db, query, top_k, max_chars?) -> list[MessageObject]
+
+Deps: hotmem.db, hotmem.embed, hotmem.trace
+Extension: add reranking, decay weighting, or MMR diversity here.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from hotmem.db import MemoryDB
+from hotmem.embed import embed_text, pack_embedding
+from hotmem.trace import Timer, get_tracer
+
+_trace = get_tracer("search")
+
+# Scoring weights
+W_COSINE = 0.6
+W_KEYWORD = 0.2
+W_IMPORTANCE = 0.2
+
+
+def _keyword_overlap(query: str, text: str) -> float:
+    """Compute Jaccard-like keyword overlap between query and text."""
+    q_words = set(query.lower().split())
+    t_words = set(text.lower().split())
+    if not q_words:
+        return 0.0
+    overlap = q_words & t_words
+    return len(overlap) / len(q_words)
+
+
+def search_memories(
+    db: MemoryDB,
+    query: str,
+    top_k: int = 5,
+    max_chars: int | None = None,
+) -> list[dict[str, Any]]:
+    """Search memories and return ranked, LLM-ready message objects.
+
+    Returns:
+        List of dicts with keys: role, content, memory_id, identifier, score
+    """
+    with Timer() as t:
+        # Embed the query
+        query_vec = embed_text(query)
+        query_blob = pack_embedding(query_vec)
+
+        # Get all candidates with cosine scores from DB
+        candidates = db.search_with_cosine(query_blob)
+
+        # Apply hybrid scoring
+        scored = []
+        for row in candidates:
+            cosine_score = row.get("cosine_score") or 0.0
+            keyword_score = _keyword_overlap(query, row["fact_text"])
+            importance = row.get("importance", 0.5)
+
+            final_score = (
+                W_COSINE * cosine_score + W_KEYWORD * keyword_score + W_IMPORTANCE * importance
+            )
+
+            scored.append({**row, "final_score": final_score})
+
+        # Sort by final score descending, take top_k
+        scored.sort(key=lambda x: x["final_score"], reverse=True)
+        top = scored[:top_k]
+
+        # Build message objects
+        messages = []
+        char_budget = max_chars
+        for item in top:
+            content = item["fact_text"]
+            if char_budget is not None:
+                if char_budget <= 0:
+                    break
+                content = content[:char_budget]
+                char_budget -= len(content)
+
+            messages.append({
+                "role": "system",
+                "content": content,
+                "memory_id": item["id"],
+                "identifier": item["identifier"],
+                "score": round(item["final_score"], 4),
+            })
+
+    _trace.info(
+        "rank",
+        f"searched {len(candidates)} memories, returned {len(messages)}",
+        detail={"query_len": len(query), "top_k": top_k, "ms": round(t.ms, 2)},
+    )
+    return messages

hotmem/server.py

@@ -0,0 +1,206 @@
+"""HotMem server — FastAPI app with traced endpoints.
+
+Purpose:
+    HTTP sidecar serving memory operations on a single port.
+    5 endpoints under /v1: health, add, search, hydrate, snapshot.
+    Every response includes X-HotMem-Trace-Id header and trace_ms timing.
+
+Interface:
+    create_app(db_path, swap_path?) -> FastAPI
+    The app is created with a lifespan that opens the DB and optionally hydrates.
+
+Deps: fastapi, hotmem.db, hotmem.embed, hotmem.search, hotmem.swap, hotmem.trace
+Extension: add middleware, CORS, rate limiting, or new endpoint groups here.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+import uuid
+from contextlib import asynccontextmanager
+from pathlib import Path
+from typing import Any
+
+from fastapi import FastAPI, Request
+from pydantic import BaseModel, Field
+
+from hotmem.db import MemoryDB
+from hotmem.embed import EMBEDDING_DIM, EMBEDDING_MODEL, embed_text, pack_embedding
+from hotmem.search import search_memories
+from hotmem.swap import compute_content_hash
+from hotmem.swap import hydrate as swap_hydrate
+from hotmem.swap import snapshot as swap_snapshot
+from hotmem.trace import Timer, get_tracer, new_trace_id
+
+_trace = get_tracer("server")
+
+# ── App state (set during lifespan) ──────────────────────────────────────────
+
+_state: dict[str, Any] = {}
+
+
+# ── Request / Response models ────────────────────────────────────────────────
+
+
+class AddRequest(BaseModel):
+    identifier: str
+    fact: str
+    source: str = ""
+    importance: float = Field(default=0.5, ge=0.0, le=1.0)
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class SearchRequest(BaseModel):
+    query: str
+    top_k: int = Field(default=5, ge=1, le=100)
+    max_chars: int | None = None
+
+
+class HydrateRequest(BaseModel):
+    file: str | None = None
+
+
+class SnapshotRequest(BaseModel):
+    file: str | None = None
+
+
+# ── Lifespan ─────────────────────────────────────────────────────────────────
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """Open DB, optionally hydrate from swap, yield, then close."""
+    db_path = _state["db_path"]
+    swap_path = _state.get("swap_path")
+
+    db = MemoryDB(db_path)
+    _state["db"] = db
+    _state["start_time"] = time.time()
+
+    # Auto-hydrate if swap file exists
+    if swap_path and Path(swap_path).exists():
+        result = swap_hydrate(db, swap_path)
+        _trace.info(
+            "startup",
+            f"auto-hydrated {result.loaded} memories",
+            detail={"swap_path": str(swap_path)},
+        )
+
+    _trace.info(
+        "startup", "server ready",
+        detail={"db_path": str(db_path), "port": _state.get("port", 8711)},
+    )
+    yield
+    db.close()
+
+
+# ── App factory ──────────────────────────────────────────────────────────────
+
+
+def create_app(
+    db_path: str | Path,
+    swap_path: str | Path | None = None,
+    port: int = 8711,
+) -> FastAPI:
+    """Create and configure the FastAPI application."""
+    _state["db_path"] = str(db_path)
+    _state["swap_path"] = str(swap_path) if swap_path else None
+    _state["port"] = port
+
+    app = FastAPI(
+        title="HotMem",
+        description="Local-first memory sidecar for agent applications",
+        version="0.1.0",
+        lifespan=lifespan,
+    )
+
+    # ── Trace middleware ─────────────────────────────────────────────────
+
+    @app.middleware("http")
+    async def trace_middleware(request: Request, call_next):
+        trace_id = new_trace_id()
+        with Timer() as t:
+            response = await call_next(request)
+        response.headers["X-HotMem-Trace-Id"] = trace_id
+        _trace.info(
+            "request",
+            f"{request.method} {request.url.path}",
+            detail={"ms": round(t.ms, 2), "status": response.status_code},
+            trace_id=trace_id,
+        )
+        return response
+
+    # ── Endpoints ────────────────────────────────────────────────────────
+
+    @app.get("/v1/health")
+    async def health():
+        db: MemoryDB = _state["db"]
+        return {
+            "status": "ok",
+            "memory_count": db.count(),
+            "db_path": _state["db_path"],
+            "uptime_s": round(time.time() - _state["start_time"], 1),
+        }
+
+    @app.post("/v1/add")
+    async def add_memory(req: AddRequest):
+        db: MemoryDB = _state["db"]
+        with Timer() as t:
+            memory_id = uuid.uuid4().hex
+            content_hash = compute_content_hash(req.identifier, req.fact)
+            vec = embed_text(req.fact)
+            blob = pack_embedding(vec)
+
+            db.insert(
+                id=memory_id,
+                identifier=req.identifier,
+                fact_text=req.fact,
+                embedding=blob,
+                embedding_dim=EMBEDDING_DIM,
+                embedding_model=EMBEDDING_MODEL,
+                source=req.source,
+                importance=req.importance,
+                metadata_json=json.dumps(req.metadata),
+                content_hash=content_hash,
+            )
+        return {
+            "memory_id": memory_id,
+            "content_hash": content_hash,
+            "trace_ms": round(t.ms, 2),
+        }
+
+    @app.post("/v1/search")
+    async def search(req: SearchRequest):
+        db: MemoryDB = _state["db"]
+        with Timer() as t:
+            messages = search_memories(
+                db, query=req.query, top_k=req.top_k, max_chars=req.max_chars
+            )
+        return {
+            "memories": messages,
+            "count": len(messages),
+            "trace_ms": round(t.ms, 2),
+        }
+
+    @app.post("/v1/hydrate")
+    async def hydrate(req: HydrateRequest):
+        db: MemoryDB = _state["db"]
+        swap = req.file or _state.get("swap_path") or "swap.jsonl"
+        result = swap_hydrate(db, swap)
+        return {
+            "loaded": result.loaded,
+            "skipped_dupes": result.skipped_dupes,
+        }
+
+    @app.post("/v1/snapshot")
+    async def snapshot(req: SnapshotRequest):
+        db: MemoryDB = _state["db"]
+        swap = req.file or _state.get("swap_path") or "swap.jsonl"
+        result = swap_snapshot(db, swap)
+        return {
+            "exported": result.exported,
+            "path": result.path,
+        }
+
+    return app

hotmem/swap.py

@@ -0,0 +1,120 @@
+"""HotMem swap — JSONL hydration and snapshot.
+
+Purpose:
+    Load memories from a swap file (JSONL) into the database, and export
+    the current database state back to a swap file. Deduplicates on content_hash.
+
+Interface:
+    hydrate(db, swap_path) -> HydrateResult
+    snapshot(db, swap_path) -> SnapshotResult
+    compute_content_hash(identifier, fact_text) -> str
+
+Deps: hotmem.db, hotmem.embed, hotmem.trace
+Extension: add compression, encryption, or remote swap sources here.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import uuid
+from dataclasses import dataclass
+from pathlib import Path
+
+from hotmem.db import MemoryDB
+from hotmem.embed import EMBEDDING_DIM, EMBEDDING_MODEL, embed_text, pack_embedding
+from hotmem.trace import Timer, get_tracer
+
+_trace = get_tracer("swap")
+
+
+def compute_content_hash(identifier: str, fact_text: str) -> str:
+    """SHA-256 hash of identifier + fact_text for deduplication."""
+    return hashlib.sha256(f"{identifier}:{fact_text}".encode()).hexdigest()
+
+
+@dataclass
+class HydrateResult:
+    loaded: int
+    skipped_dupes: int
+
+
+@dataclass
+class SnapshotResult:
+    exported: int
+    path: str
+
+
+def hydrate(db: MemoryDB, swap_path: str | Path) -> HydrateResult:
+    """Load memories from a JSONL swap file into the database.
+
+    Deduplicates by content_hash — skips rows that already exist in the DB.
+    """
+    swap_path = Path(swap_path)
+    if not swap_path.exists():
+        _trace.warn("hydrate", "swap file not found", detail={"path": str(swap_path)})
+        return HydrateResult(loaded=0, skipped_dupes=0)
+
+    with Timer() as t:
+        loaded = 0
+        skipped = 0
+
+        with open(swap_path) as f:
+            for line in f:
+                line = line.strip()
+                if not line:
+                    continue
+                record = json.loads(line)
+
+                identifier = record.get("identifier", "")
+                fact_text = record.get("fact_text", "")
+                content_hash = record.get(
+                    "content_hash", compute_content_hash(identifier, fact_text)
+                )
+
+                if db.exists(content_hash):
+                    skipped += 1
+                    continue
+
+                # Compute embedding for the fact
+                vec = embed_text(fact_text)
+                blob = pack_embedding(vec)
+
+                db.insert(
+                    id=record.get("id", uuid.uuid4().hex),
+                    identifier=identifier,
+                    fact_text=fact_text,
+                    embedding=blob,
+                    embedding_dim=record.get("embedding_dim", EMBEDDING_DIM),
+                    embedding_model=record.get("embedding_model", EMBEDDING_MODEL),
+                    source=record.get("source", "swap"),
+                    importance=record.get("importance", 0.5),
+                    metadata_json=json.dumps(record.get("metadata", {})),
+                    content_hash=content_hash,
+                )
+                loaded += 1
+
+    _trace.info(
+        "hydrate",
+        f"hydrated {loaded} memories, skipped {skipped} dupes",
+        detail={"path": str(swap_path), "ms": round(t.ms, 2)},
+    )
+    return HydrateResult(loaded=loaded, skipped_dupes=skipped)
+
+
+def snapshot(db: MemoryDB, swap_path: str | Path) -> SnapshotResult:
+    """Export all memories from the database to a JSONL swap file."""
+    swap_path = Path(swap_path)
+
+    with Timer() as t:
+        rows = db.all_rows()
+        with open(swap_path, "w") as f:
+            for row in rows:
+                f.write(json.dumps(row, default=str) + "\n")
+
+    _trace.info(
+        "snapshot",
+        f"exported {len(rows)} memories",
+        detail={"path": str(swap_path), "ms": round(t.ms, 2)},
+    )
+    return SnapshotResult(exported=len(rows), path=str(swap_path))

hotmem/trace.py

@@ -0,0 +1,129 @@
+"""HotMem tracing — structured, component-tagged logging for agent observability.
+
+Purpose:
+    Provide structured JSON-line logs to stderr so agents can grep by component
+    and correlate operations across the sidecar lifecycle.
+
+Interface:
+    get_tracer(component: str) -> Tracer
+    new_trace_id() -> str
+
+Deps: none (stdlib only)
+Extension: swap the formatter or add sinks (file, HTTP) by subclassing Tracer.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import sys
+import time
+import uuid
+
+
+def new_trace_id() -> str:
+    """Generate a short unique trace ID."""
+    return uuid.uuid4().hex[:12]
+
+
+class _JsonFormatter(logging.Formatter):
+    """Emit each log record as a single JSON line."""
+
+    def format(self, record: logging.LogRecord) -> str:
+        entry = {
+            "ts": self.formatTime(record, "%Y-%m-%dT%H:%M:%S"),
+            "component": getattr(record, "component", "unknown"),
+            "level": record.levelname,
+            "op": getattr(record, "op", ""),
+            "msg": record.getMessage(),
+        }
+        detail = getattr(record, "detail", None)
+        if detail is not None:
+            entry["detail"] = detail
+        trace_id = getattr(record, "trace_id", None)
+        if trace_id is not None:
+            entry["trace_id"] = trace_id
+        return json.dumps(entry, default=str)
+
+
+class Tracer:
+    """Component-scoped structured logger.
+
+    Usage:
+        tracer = get_tracer("db")
+        tracer.info("init", "database opened", detail={"path": "/tmp/hotmem.sqlite"})
+    """
+
+    def __init__(self, component: str) -> None:
+        self.component = component
+        self._logger = logging.getLogger(f"hotmem.{component}")
+        if not self._logger.handlers:
+            handler = logging.StreamHandler(sys.stderr)
+            handler.setFormatter(_JsonFormatter())
+            self._logger.addHandler(handler)
+            self._logger.setLevel(logging.DEBUG)
+            self._logger.propagate = False
+
+    def _log(
+        self,
+        level: int,
+        op: str,
+        msg: str,
+        *,
+        detail: dict | None = None,
+        trace_id: str | None = None,
+    ) -> None:
+        self._logger.log(
+            level,
+            msg,
+            extra={
+                "component": self.component,
+                "op": op,
+                "detail": detail,
+                "trace_id": trace_id,
+            },
+        )
+
+    def info(
+        self, op: str, msg: str, *, detail: dict | None = None, trace_id: str | None = None
+    ) -> None:
+        self._log(logging.INFO, op, msg, detail=detail, trace_id=trace_id)
+
+    def debug(
+        self, op: str, msg: str, *, detail: dict | None = None, trace_id: str | None = None
+    ) -> None:
+        self._log(logging.DEBUG, op, msg, detail=detail, trace_id=trace_id)
+
+    def error(
+        self, op: str, msg: str, *, detail: dict | None = None, trace_id: str | None = None
+    ) -> None:
+        self._log(logging.ERROR, op, msg, detail=detail, trace_id=trace_id)
+
+    def warn(
+        self, op: str, msg: str, *, detail: dict | None = None, trace_id: str | None = None
+    ) -> None:
+        self._log(logging.WARNING, op, msg, detail=detail, trace_id=trace_id)
+
+
+_tracers: dict[str, Tracer] = {}
+
+
+def get_tracer(component: str) -> Tracer:
+    """Get or create a tracer for the given component name."""
+    if component not in _tracers:
+        _tracers[component] = Tracer(component)
+    return _tracers[component]
+
+
+class Timer:
+    """Context manager that measures elapsed milliseconds."""
+
+    def __init__(self) -> None:
+        self.ms: float = 0.0
+
+    def __enter__(self) -> Timer:
+        self._start = time.perf_counter()
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.ms = (time.perf_counter() - self._start) * 1000

hotmem-0.1.3.dist-info/METADATA

@@ -0,0 +1,169 @@
+Metadata-Version: 2.4
+Name: hotmem
+Version: 0.1.3
+Summary: A local-first memory sidecar for agent applications
+Author-email: valiantone <zrjohn@yahoo.com>
+Project-URL: Homepage, https://github.com/valiantone/hotmem
+Project-URL: Repository, https://github.com/valiantone/hotmem
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click<9,>=8.1
+Requires-Dist: fastapi<1,>=0.115
+Requires-Dist: httpx<1,>=0.28
+Requires-Dist: uvicorn<1,>=0.30
+Provides-Extra: dev
+Requires-Dist: pytest<10,>=9; extra == "dev"
+Requires-Dist: ruff<1,>=0.15; extra == "dev"
+Dynamic: license-file
+
+# HotMem
+
+A local-first memory sidecar for agent applications. One SQLite DB. One port: 8711.
+
+HotMem provides fast, queryable working memory with hybrid vector + keyword search. Store facts, retrieve them ranked, and get back LLM-ready message objects you can stitch directly into prompts.
+
+## Install
+
+```bash
+pip install hotmem@git+https://github.com/KnowGuard-AI/HotMem.git
+# or
+uv add hotmem@git+https://github.com/KnowGuard-AI/HotMem.git
+```
+
+Or add to `requirements.txt`:
+
+```
+hotmem @ git+https://github.com/KnowGuard-AI/HotMem.git
+```
+
+## Quick Start
+
+```bash
+# Start with a mount directory (portable memory)
+hotmem serve --mount ./hotmem
+
+# Or just start (uses temp DB)
+hotmem serve
+```
+
+## CLI
+
+```bash
+hotmem serve --port 8711 --mount ./data/hotmem
+hotmem serve --db ./my.sqlite
+hotmem hydrate --file swap.jsonl --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`
+
+```json
+{"status": "ok", "memory_count": 42, "db_path": "...", "uptime_s": 120.5}
+```
+
+### `POST /v1/add`
+
+```json
+{"identifier": "vendor_x", "fact": "Invoice total was $5000", "importance": 0.8}
+```
+
+### `POST /v1/search`
+
+```json
+{"query": "duplicate invoice risk", "top_k": 5, "max_chars": 1500}
+```
+
+Returns ranked message objects ready for LLM stitching:
+
+```json
+{
+  "memories": [
+    {"role": "system", "content": "...", "memory_id": "...", "identifier": "...", "score": 0.87}
+  ],
+  "count": 5,
+  "trace_ms": 2.1
+}
+```
+
+### `POST /v1/hydrate`
+
+```json
+{"file": "swap.jsonl"}
+```
+
+### `POST /v1/snapshot`
+
+```json
+{"file": "swap.jsonl"}
+```
+
+## Python Client
+
+```python
+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."}]
+```
+
+## Mounting
+
+Any directory can be a HotMem mount. The mount contains:
+
+- `hotmem.sqlite` — the database
+- `swap.jsonl` — portable JSONL backup
+- `manifest.json` — mount metadata
+
+```bash
+hotmem serve --mount /mnt/usb/hotmem     # portable memory on USB
+hotmem serve --mount ./data/hotmem        # local project memory
+```
+
+## Development
+
+```bash
+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 (for agents)
+
+Each source module is independently extensible with self-documenting headers:
+
+| Module | Purpose | Extension Point |
+|--------|---------|------------------|
+| `trace.py` | Structured JSON logging | Add sinks, formatters |
+| `embed.py` | Hash-based embedder (dim=64) | Swap for real model |
+| `db.py` | SQLite + cosine UDF | Add FTS5, indexes |
+| `search.py` | Hybrid ranking | Add reranking, MMR |
+| `swap.py` | JSONL hydrate/snapshot | Add compression |
+| `mount.py` | Directory bootstrap | Add remote sync |
+| `server.py` | FastAPI endpoints | Add CORS, new routes |
+| `cli.py` | Click CLI | Add subcommands |
+| `client.py` | httpx SDK | Add async client |
+
+Every operation emits structured JSON traces to stderr with component tags:
+
+```bash
+hotmem serve --mount ./data 2>&1 | grep '"component": "search"'
+```

hotmem-0.1.3.dist-info/RECORD

@@ -0,0 +1,17 @@
+hotmem/__init__.py,sha256=EmW5IF0PNAG3PdmtYaPkjw9YI__9awrAk-kEukxbtKA,93
+hotmem/cli.py,sha256=PJW7q5IjL3_zf-JQx3ne0I5iHofFEKZYs5Waf1uxhsQ,3750
+hotmem/client.py,sha256=9-fj0DeznjHjkNmkZgfDivc0VoGPJoX5nXrXKYSBjLE,2998
+hotmem/db.py,sha256=Kt1H9ClOZnuNhqtibR7NwyoPn6-Ce33Unqax6l2-SAY,5397
+hotmem/embed.py,sha256=oB0whKhrOIMT7eWggxZkC3c78hzvBXpTZVhbW6wt9Po,2173
+hotmem/mount.py,sha256=JH65_PLSWIC0x9fPpmp6D5o7dt6txtG1ybQHdp2oj4A,2010
+hotmem/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+hotmem/search.py,sha256=xfO7vIQYIsoTHeusLqyVmF8C5saO3nqLuoryUfkDjqU,3036
+hotmem/server.py,sha256=1DIARxg33fZA8IGShc2PaAL9w70UvwH6ES7HxoNpdcs,6835
+hotmem/swap.py,sha256=Yh5Jb4MkhWvonEyA8xzydIIdB9a7Nvbu4G6fNDZTJZE,3811
+hotmem/trace.py,sha256=Pa2hLUirIseKRdAtoLHV2CdMRmRBETlera2wPEC1MmU,3809
+hotmem-0.1.3.dist-info/licenses/LICENSE,sha256=picLsifdD2sT3GzbjjehqkLGX09itju9Xj6znNG1P9w,1067
+hotmem-0.1.3.dist-info/METADATA,sha256=xZ2LSJm61AnTHopuY40TdCoVBcOqFzc03MISaWGIV24,4384
+hotmem-0.1.3.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+hotmem-0.1.3.dist-info/entry_points.txt,sha256=G9jNJ3CmvaaURNyTLroK3SSyr9Ku924bjNBOCDRc9z4,43
+hotmem-0.1.3.dist-info/top_level.txt,sha256=NEoA1mQ9SNCFkQ_Z5axO__Hj4NwTQmF10dA2lAyDhp4,7
+hotmem-0.1.3.dist-info/RECORD,,

hotmem-0.1.3.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

hotmem-0.1.3.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+hotmem = hotmem.cli:main

hotmem-0.1.3.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 valiantone
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hotmem-0.1.3.dist-info/top_level.txt

@@ -0,0 +1 @@
+hotmem