{"id":50426108,"url":"https://github.com/knowguard-ai/hotmem","last_synced_at":"2026-06-14T09:01:46.121Z","repository":{"id":355230793,"uuid":"1226276929","full_name":"KnowGuard-AI/HotMem","owner":"KnowGuard-AI","description":"Lets any running app attach a local semantic memory sidecar using ordinary writable storage.","archived":false,"fork":false,"pushed_at":"2026-06-09T07:59:40.000Z","size":904,"stargazers_count":0,"open_issues_count":15,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-09T09:28:34.755Z","etag":null,"topics":["ai-agents","fastapi","llm","memory","python","sidecar","sqlite","vector-search"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/hotmem/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/KnowGuard-AI.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-01T07:27:20.000Z","updated_at":"2026-06-06T09:04:08.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/KnowGuard-AI/HotMem","commit_stats":null,"previous_names":["knowguard-ai/hotmem"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/KnowGuard-AI/HotMem","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KnowGuard-AI%2FHotMem","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KnowGuard-AI%2FHotMem/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KnowGuard-AI%2FHotMem/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KnowGuard-AI%2FHotMem/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/KnowGuard-AI","download_url":"https://codeload.github.com/KnowGuard-AI/HotMem/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KnowGuard-AI%2FHotMem/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34315075,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-14T02:00:07.365Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","fastapi","llm","memory","python","sidecar","sqlite","vector-search"],"created_at":"2026-05-31T11:00:25.347Z","updated_at":"2026-06-14T09:01:46.113Z","avatar_url":"https://github.com/KnowGuard-AI.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"![HotMem banner](hotmem/hotmem-banner.png)\n\n# HotMem\n\n[![CI](https://github.com/KnowGuard-AI/HotMem/actions/workflows/ci.yml/badge.svg)](https://github.com/KnowGuard-AI/HotMem/actions/workflows/ci.yml)\n[![PyPI](https://img.shields.io/pypi/v/hotmem)](https://pypi.org/project/hotmem/)\n[![Python](https://img.shields.io/pypi/pyversions/hotmem)](https://pypi.org/project/hotmem/)\n[![codecov](https://codecov.io/gh/KnowGuard-AI/HotMem/branch/main/graph/badge.svg)](https://codecov.io/gh/KnowGuard-AI/HotMem)\n[![License: MIT](https://img.shields.io/github/license/KnowGuard-AI/HotMem)](LICENSE)\n[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)\n\nA local-first memory sidecar for agent applications. One SQLite DB. One port: 8711.\n\nHotMem 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.\n\nSupports Python 3.11, 3.12, 3.13, and 3.14.\n\n## Install\n\n```bash\npip install hotmem\n# or\nuv pip install hotmem\n```\n\n## Quick Start\n\n```bash\n# Start with a mount directory (portable memory)\nhotmem serve --mount ./hotmem\n\n# Or just start (uses temp DB)\nhotmem serve\n```\n\n## CLI\n\n```bash\nhotmem serve --port 8711 --mount ./data/hotmem\nhotmem serve --db ./my.sqlite\nhotmem hydrate --file swap.jsonl --db ./my.sqlite\nhotmem snapshot --file swap.jsonl --db ./my.sqlite\nhotmem status\n```\n\n## API\n\nAll endpoints under `/v1`. Default: `http://127.0.0.1:8711`\n\n### `GET /v1/health`\n\n```json\n{\"status\": \"ok\", \"memory_count\": 42, \"db_path\": \"...\", \"uptime_s\": 120.5}\n```\n\n### `POST /v1/add`\n\n```json\n{\"identifier\": \"vendor_x\", \"fact\": \"Invoice total was $5000\", \"importance\": 0.8}\n```\n\n### `POST /v1/search`\n\n```json\n{\"query\": \"duplicate invoice risk\", \"top_k\": 5, \"max_chars\": 1500}\n```\n\nReturns ranked message objects ready for LLM stitching:\n\n```json\n{\n  \"memories\": [\n    {\"role\": \"system\", \"content\": \"...\", \"memory_id\": \"...\", \"identifier\": \"...\", \"score\": 0.87}\n  ],\n  \"count\": 5,\n  \"trace_ms\": 2.1\n}\n```\n\n### `POST /v1/hydrate`\n\n```json\n{\"file\": \"swap.jsonl\"}\n```\n\n### `POST /v1/snapshot`\n\n```json\n{\"file\": \"swap.jsonl\"}\n```\n\n## Python Client\n\n```python\nfrom hotmem.client import HotMemClient\n\nwith HotMemClient(\"http://127.0.0.1:8711\") as client:\n    client.add(\"vendor_x\", \"Invoice total $5000\", importance=0.8)\n\n    memories = client.search(\"duplicate invoice risk\", top_k=5, max_chars=1500)\n\n    # memories are LLM-ready message objects\n    messages = memories + [{\"role\": \"user\", \"content\": \"Analyze this vendor.\"}]\n```\n\n## Mounting\n\nAny directory can be a HotMem mount. The mount contains:\n\n- `hotmem.sqlite` — the database\n- `swap.jsonl` — portable JSONL backup\n- `manifest.json` — mount metadata\n\n```bash\nhotmem serve --mount /mnt/usb/hotmem     # portable memory on USB\nhotmem serve --mount ./data/hotmem        # local project memory\n```\n\n## Development\n\n```bash\nuv sync                          # install deps\nuv run pytest                    # run tests\nuv run ruff check src/ tests/    # lint\nuv run ruff format src/ tests/   # format\nuv build                         # build wheel\n```\n\n## Architecture\n\nEach source module is self-contained with a docstring header describing its purpose and interface:\n\n| Module | Purpose |\n|--------|---------|\n| `trace.py` | Structured JSON logging |\n| `embed.py` | Hash-based embedder (dim=64) |\n| `db.py` | SQLite storage + cosine similarity UDF |\n| `search.py` | Hybrid ranking (cosine + keyword + importance) |\n| `swap.py` | JSONL hydrate/snapshot |\n| `mount.py` | Portable directory management |\n| `server.py` | FastAPI endpoints |\n| `cli.py` | Click CLI |\n| `client.py` | Python SDK (httpx) |\n\nEvery operation emits structured JSON traces to stderr with component tags:\n\n```bash\nhotmem serve --mount ./data 2\u003e\u00261 | grep '\"component\": \"search\"'\n```\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fknowguard-ai%2Fhotmem","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fknowguard-ai%2Fhotmem","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fknowguard-ai%2Fhotmem/lists"}