hotmem 0.1.3__tar.gz

hotmem-0.1.3/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,144 @@
+# 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/pyproject.toml

@@ -0,0 +1,57 @@
+[project]
+name = "hotmem"
+version = "0.1.3"
+description = "A local-first memory sidecar for agent applications"
+readme = "README.md"
+requires-python = ">=3.11"
+
+authors = [
+    { name = "valiantone", email = "zrjohn@yahoo.com" }
+]
+
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+]
+
+dependencies = [
+    "click>=8.1,<9",
+    "fastapi>=0.115,<1",
+    "httpx>=0.28,<1",
+    "uvicorn>=0.30,<1",
+]
+
+[project.urls]
+Homepage = "https://github.com/valiantone/hotmem"
+Repository = "https://github.com/valiantone/hotmem"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=9,<10",
+    "ruff>=0.15,<1",
+]
+
+[project.scripts]
+hotmem = "hotmem.cli:main"
+
+[build-system]
+requires = [
+    "setuptools>=75",
+    "wheel"
+]
+build-backend = "setuptools.build_meta"
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+

hotmem-0.1.3/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

hotmem-0.1.3/src/hotmem/__init__.py

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

hotmem-0.1.3/src/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-0.1.3/src/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()