From 2d32640c3f8e480dbd9ddcf283b6b2f42963c639 Mon Sep 17 00:00:00 2001 From: valiantone Date: Mon, 17 Aug 2026 19:40:45 +0530 Subject: [PATCH] Sanitize public documentation surface --- .gitignore | 4 + CHANGELOG.md | 2 +- PLAN.md | 193 ---- README.md | 13 +- data/hotmem/manifest.json | 5 - docs/agent-memory-portability.md | 8 +- docs/api.md | 14 +- docs/architecture.md | 46 + docs/cli.md | 12 +- docs/documentation-service.md | 154 --- docs/hermes-v0.3-epic.md | 1132 -------------------- docs/index.md | 16 +- docs/llms.txt | 26 +- docs/okf/company-brain-interchange.md | 124 --- docs/okf/file-aware-architecture.md | 190 ---- docs/okf/file-native-epic.md | 120 --- docs/okf/file-native-memory-practices.md | 276 ----- docs/okf/format-and-maintenance.md | 88 -- docs/okf/index.md | 27 - docs/quickstart.md | 18 +- docs/snapshot-v2.md | 9 +- docs/vision-and-canon.md | 37 +- docs/yc_coding_session_trace.md | 174 --- hotmem/manifest.json | 5 - mkdocs.yml | 16 +- src/hotmem/bundle.py | 4 +- src/hotmem/events.py | 4 +- src/hotmem/hygiene.py | 2 +- src/hotmem/inspectors/__init__.py | 9 +- src/hotmem/inspectors/base.py | 4 +- src/hotmem/inspectors/parquet_inspector.py | 2 +- src/hotmem/lifecycle.py | 8 +- src/hotmem/server.py | 13 +- src/hotmem/snapshot/format.py | 2 +- src/hotmem/storage/__init__.py | 13 +- src/hotmem/storage/base.py | 2 +- tests/golden/conftest.py | 4 +- tests/golden/test_golden_swap.py | 2 +- tests/test_cli.py | 4 +- tests/test_inspectors.py | 4 +- tests/test_storage.py | 2 +- 41 files changed, 138 insertions(+), 2650 deletions(-) delete mode 100644 PLAN.md delete mode 100644 data/hotmem/manifest.json create mode 100644 docs/architecture.md delete mode 100644 docs/documentation-service.md delete mode 100644 docs/hermes-v0.3-epic.md delete mode 100644 docs/okf/company-brain-interchange.md delete mode 100644 docs/okf/file-aware-architecture.md delete mode 100644 docs/okf/file-native-epic.md delete mode 100644 docs/okf/file-native-memory-practices.md delete mode 100644 docs/okf/format-and-maintenance.md delete mode 100644 docs/okf/index.md delete mode 100644 docs/yc_coding_session_trace.md delete mode 100644 hotmem/manifest.json diff --git a/.gitignore b/.gitignore index 1b2cd90..c66870f 100644 --- a/.gitignore +++ b/.gitignore @@ -16,4 +16,8 @@ swap.jsonl .coverage coverage.xml dev_roadmap.md + +# Generated local mount manifests contain machine-specific paths. +/hotmem/manifest.json +/data/hotmem/manifest.json planned-evolution.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 3ee0922..10280b7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -145,7 +145,7 @@ Format follows [Keep a Changelog](https://keepachangelog.com/). - Only local schemes are supported for file refs (`file://`, absolute, relative paths resolved against the mount dir). Remote schemes (`s3://`, `hdfs://`, `abfs://`, `gs://`) are rejected at the add - boundary with HTTP 400 `unsupported_scheme` (EMOS-owned). + boundary with HTTP 400 `unsupported_scheme`. - Cosine UDF returns `0.0` for NULL embeddings (file-backed without summary) so they are excluded from ranked search but still retrievable via the metadata endpoint. diff --git a/PLAN.md b/PLAN.md deleted file mode 100644 index 8b69b43..0000000 --- a/PLAN.md +++ /dev/null @@ -1,193 +0,0 @@ -# Plan: File Inspectors (#53) + Compatibility Golden Tests (#54) - -Branch: `feat/file-inspectors-golden-tests-53-54` (off `main` @ 0f0b8da) -Milestone target: M1 (#54, P0) + M5 (#53, P1/P2). Recommended order in -`docs/okf/file-native-memory-practices.md` §13 is: golden tests first, then -inspectors — so #54 lands first to lock the contract, then #53 adds behind it. - -## 0. Design philosophy (the 10x posture) - -- **Compatibility is the product.** Every new line is additive. The non-breaking - contract from `file-aware-architecture.md` §5 must become *executable*, not - aspirational — that is the entire point of #54. -- **Filesystem first, never a query engine.** #53 inspects *about* files, not - *into* them analytically. No DuckDB/Polars/Arrow runtime dependency. Parquet - support is **metadata-only via a dependency-free Thrift Compact footer - reader** — this is the disruptive-in-scope bet: production-grade Parquet - provenance with **zero** new deps, staying inside the "HotMem owns vs EMOS - owns" boundary (`file-aware-architecture.md` §4). -- **Provenance over copy.** Inspectors never pull large file contents into - SQLite. They return URI + size + checksum + byte ranges + light summary so - memories can *reference* data (#38 enabler) without inflating the hot store. -- **Streaming + seek, no full loads.** CSV uses the stdlib `csv` reader with a - bounded sniff; JSONL counts newlines via a buffered byte scan and samples by - `seek`; Parquet reads only the footer tail. Memory footprint is O(1) for the - metadata path regardless of file size — this is what makes it safe on - production workloads. -- **Fail loudly, fail structured.** Unsupported formats raise - `UnsupportedFormatError` with an actionable message, mirroring the existing - `UnsupportedSchemeError` in `storage/__init__.py`. -- **Local-only surface, for now.** Inspectors ship as a Python API + a - `hotmem inspect` CLI subcommand. No `/v1` or MCP endpoints — those belong to - #43 (API extensions) and would widen the compatibility surface #54 is locking. - -## 1. Issue #54 — Compatibility golden tests (lands first) - -Goal: make the non-breaking contract executable *before* more vNext code lands. - -### Layout -``` -tests/golden/ - __init__.py - conftest.py # shared golden fixtures (stable server + deterministic clock) - fixtures/ - add_minimal.jsonl # canonical {identifier, fact} add payload - add_extended.jsonl # {identifier, fact, source, importance, metadata, ttl_seconds} - search_expected.json # locked /v1/search message-object shape - memories_expected.json # locked /v1/memories row shape - test_golden_api.py - test_golden_swap.py - test_golden_client.py - test_golden_mcp.py - test_golden_additive.py -``` - -### What gets locked -1. **API shapes** (`test_golden_api.py`): exact top-level key sets and value - *types* for `/v1/health`, `/v1/add`, `/v1/search`, `/v1/memories`, - `/v1/hydrate`, `/v1/snapshot`. Volatile fields (`memory_id`, `content_hash`, - `created_at`, `trace_ms`, `uptime_s`, `db_path`) are masked to a stable - sentinel so snapshots are deterministic. Search message-object shape - (`role`/`content`/`memory_id`/`identifier`/`score`/`created_at`) is locked - against `fixtures/search_expected.json`. -2. **Swap round trips** (`test_golden_swap.py`): JSONL and JSONL.GZ - snapshot→hydrate→snapshot are byte-shape stable (key set + ordering of the - first record), and a v0.1-style minimal record hydrates identically to a - v2-extended record. Locks the existing compatibility promise in - `file-native-memory-practices.md` §10. -3. **Python client** (`test_golden_client.py`): `HotMemClient` and - `AsyncHotMemClient` method names, request payloads (vs a `MockTransport`), - and return shapes are locked. This is the surface `test_client.py` already - exercises informally — golden tests make it a *contract*. -4. **MCP** (`test_golden_mcp.py`): tool-name set is an exact frozen set; - each tool's `inputSchema` top-level keys and `required` arrays are locked. - Backed by `test_mcp.py`'s existing wiring but asserting schema stability - specifically (the part that breaks clients when it drifts). -5. **Additive proof** (`test_golden_additive.py`): a `POST /v1/add` with *only* - the legacy `{identifier, fact}` payload produces a memory whose - `/v1/search` and `/v1/memories` shapes are *identical* to one created with - the full extended payload minus the new fields. This is the executable - form of "new optional fields do not change default behavior" (#54 scope). - -### Determinism strategy -- Use `TestClient` against a temp DB (existing pattern). -- Mask volatile keys into typed sentinels (`""`, `""`, - `""`, `""`) before comparing, so snapshots are stable across - runs but still type-locked. - -## 2. Issue #53 — Lightweight file inspectors - -### Layout -``` -src/hotmem/inspectors/ - __init__.py # registry: get_inspector(uri), UnsupportedFormatError, inspect_file() - base.py # FileInspector Protocol, FileInspection dataclass - csv_inspector.py - jsonl_inspector.py - _thrift.py # minimal Thrift Compact Protocol reader (production) - parquet_inspector.py # footer-only metadata reader, no data-page decode -``` - -### `FileInspection` contract (`base.py`) -A frozen dataclass that pairs storage provenance with format-specific metadata, -designed so a future #38 file-backed memory can store it directly: - -```python -@dataclass(frozen=True) -class FileInspection: - uri: str - format: str # csv | jsonl | parquet | ... - size: int - mtime: float - checksum: str # sha256 from the storage adapter - columns: list[str] | None # CSV headers / Parquet schema names - row_count: int | None # None when not cheap to compute - delimiter: str | None # CSV only - has_header: bool | None # CSV only - num_row_groups: int | None # Parquet only - schema_types: list[str] | None # Parquet column types - sample: list[dict] | None # bounded JSONL/CSV preview - byte_ranges: list[tuple[int, int]] | None # provenance offsets for sample - metadata: dict[str, Any] # format-specific extras - unsupported_reason: str | None # set when format is recognized but limited -``` - -### Inspectors -- **CSV** (`csv_inspector.py`): `csv.Sniffer` over a bounded head buffer for - delimiter + header detection; columns from the header row; `row_count` - computed only when `count_rows=True` via a streaming `\n` scan (cheap, - optional — matches issue's "optional row count when cheap"). Never loads the - whole file into memory. Sample = first N rows via the reader. -- **JSONL** (`jsonl_inspector.py`): line count via buffered newline scan (O(file - size) byte read, O(1) memory). Range sampling via `seek(offset)` + - `readline()` to fetch selected records without parsing the whole file. - Validates each sampled line is JSON; reports first malformed line offset in - `unsupported_reason` rather than crashing. -- **Parquet** (`parquet_inspector.py` + `_thrift.py`): validate `PAR1` magic - at head and tail; read last 8 bytes → footer length (LE uint32); read footer; - parse Thrift Compact `FileMetaData` → `version`, `num_rows`, `schema` - (column names + converted_type/physical type), `row_groups` count. **No data - page decoding, no query engine.** If `pyarrow` is installed at runtime it is - *not* used (deterministic, zero-dep path is the contract). Malformed/legacy - footers set `unsupported_reason` instead of raising, so a bad file becomes - provenance, not an outage. - -### Registry (`__init__.py`) -```python -def get_inspector(uri: str) -> FileInspector: ... # by format from storage.metadata() -def inspect_file(uri: str, *, count_rows=False, sample_size=5) -> FileInspection: ... -``` -Unsupported formats → `UnsupportedFormatError` (mirrors `storage`'s -`UnsupportedSchemeError`). Scheme resolution reuses `storage.get_adapter` so -remote schemes fail fast with the existing EMOS-boundary error. - -### CLI -`hotmem inspect [--count-rows] [--sample N] [--json]` — additive, uses -`get_renderer()` for human output and `--json` for scripting (matches the -`search` command's `--json` convention in `cli.py`). - -### Tests (`tests/test_inspectors.py`) -- Fixtures generated in `tmp_path` (deterministic, no committed binaries): - - CSV with header + 3 rows, comma and `;` delimiters. - - JSONL with 5 records incl. one malformed line. - - Parquet via a small Thrift-Compact footer encoder in - `tests/_parquet_fixtures.py` producing a valid footer (num_rows, schema, - 1 row group) — exercises the real parser on a real footer shape. -- Assertions: stable metadata, no full-file copy into any DB, malformed JSONL - reported not raised, unsupported format raises `UnsupportedFormatError`, - Parquet returns metadata-only (no row data), existing hydrate/search tests - unchanged. - -## 3. Production hardening notes - -- All inspectors are read-only and side-effect free; safe to call concurrently. -- Parquet footer read is bounded (footer length capped at a sane max to reject - hostile files: `len(file) - 8` sanity-checked). -- `lru_cache` on checksum is already provided by the storage adapter; the - inspector reuses `storage.get_adapter(...).checksum(uri)` rather than - re-hashing. -- No new runtime dependencies; `[dev]` unchanged. CI matrix (py3.11–3.14) - unaffected — pure stdlib. -- Ruff: `target-version = "py311"`, line-length 100, existing rule set - (`E,F,I,UP,B,SIM`). All new code conforms. - -## 4. Out of scope (deferred to owning issues) -- HTTP/MCP endpoints for inspection → #43. -- File-backed memory hydration from inspection → #38. -- Bundle readers, directory snapshots, event log, promotion → #39–#42. -- Parquet data-page decoding, partitioning, query → EMOS. - -## 5. Verification -- `uv run pytest -q` — all existing 150 + new tests green. -- `uv run ruff check src tests` — clean. -- Spot-check `hotmem inspect --json ` output shape. diff --git a/README.md b/README.md index a19146b..c59b1ee 100644 --- a/README.md +++ b/README.md @@ -202,9 +202,7 @@ 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](docs/snapshot-v2.md) and the -[interchange strategy](docs/okf/company-brain-interchange.md) for the exact -current guarantees. +[Snapshot v2 format](docs/snapshot-v2.md) for the exact current guarantees. ## Development @@ -218,7 +216,8 @@ uv build # build wheel ## Architecture -Each source module is self-contained with a docstring header describing its purpose and interface: +HotMem keeps runtime state in SQLite and uses small, explicit modules for +storage, ranking, portability, the HTTP server, and client integrations: | Module | Purpose | |--------|---------| @@ -232,12 +231,6 @@ Each source module is self-contained with a docstring header describing its purp | `cli.py` | Click CLI | | `client.py` | Python SDK (httpx) | -Every operation emits structured JSON traces to stderr with component tags: - -```bash -hotmem serve --mount ./data 2>&1 | grep '"component": "search"' -``` - ## Contributing See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines. diff --git a/data/hotmem/manifest.json b/data/hotmem/manifest.json deleted file mode 100644 index 9dadb4f..0000000 --- a/data/hotmem/manifest.json +++ /dev/null @@ -1,5 +0,0 @@ -{ - "hotmem_version": "0.1.0", - "created_at": "2026-05-09T10:57:31.836904+00:00", - "mount_path": "/home/kenneth/projects/HotMem/data/hotmem" -} diff --git a/docs/agent-memory-portability.md b/docs/agent-memory-portability.md index 006423d..66c6ed9 100644 --- a/docs/agent-memory-portability.md +++ b/docs/agent-memory-portability.md @@ -83,10 +83,10 @@ supported importer or adapter. Those integrations should be announced only with a reproducible import/export path and compatibility tests. Likewise, HotMem should not be described today as encrypted, unbreakable, -cloud-synchronized, or conflict-free multi-writer memory. The published -roadmap sequences the work responsibly: define the interchange contract, -verify whole-brain dump and restore, then design one-way incremental sync with -explicit conflict handling. See the [portable company-brain strategy](okf/company-brain-interchange.md). +cloud-synchronized, or conflict-free multi-writer memory. Snapshot integrity +checks and local restore are the current portability guarantees; stronger +transport and synchronization features require separate implementation and +verification. ## FAQ diff --git a/docs/api.md b/docs/api.md index 2d8e685..c928f4a 100644 --- a/docs/api.md +++ b/docs/api.md @@ -1,9 +1,4 @@ -# OKF: API Reference - -Status: Accepted -Owner: HotMem maintainers -Last updated: 2026-07-06 -Scope: Stable HTTP API reference +# API Reference ## 1. Purpose @@ -96,10 +91,3 @@ hotmem openapi --output openapi.yaml --format yaml ``` Or fetch it from a running server: `GET /openapi.json` - -## 9. Open Questions - -- Which vNext endpoints should graduate from GitHub issues into this reference - first? -- Should file-native API examples live here or in a separate guide once - implemented? diff --git a/docs/architecture.md b/docs/architecture.md new file mode 100644 index 0000000..32aaada --- /dev/null +++ b/docs/architecture.md @@ -0,0 +1,46 @@ +# 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 + +```text +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. + +## 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. diff --git a/docs/cli.md b/docs/cli.md index 08b0507..d53fe6f 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -1,9 +1,4 @@ -# OKF: CLI Reference - -Status: Accepted -Owner: HotMem maintainers -Last updated: 2026-07-06 -Scope: Stable command-line interface reference +# CLI Reference ## 1. Purpose @@ -78,8 +73,3 @@ Export the OpenAPI specification. |---|---|---| | `--output` / `-o` | stdout | Output file path | | `--format` | json | Output format (json or yaml) | - -## 5. Open Questions - -- Should future file-native health hints appear under `status`, a new - `inspect`, or both? diff --git a/docs/documentation-service.md b/docs/documentation-service.md deleted file mode 100644 index d469aea..0000000 --- a/docs/documentation-service.md +++ /dev/null @@ -1,154 +0,0 @@ -# Documentation Service - -**Status:** Adopted build and deployment contract · **Owner:** HotMem maintainers - -Scope: Public HotMem documentation, including crawler and LLM-readable sources. - -## One-page decision - -HotMem documentation is a **docs-as-code static service** built from this -repository. Markdown is the source of truth; MkDocs Material builds the site; -GitHub Pages delivers one immutable build artifact. There is no CMS, database, -runtime server, separate hosting vendor, or mandatory analytics service. - -```text -versioned Markdown + MkDocs Material - -> locked strict build on documentation pull requests - -> immutable GitHub Pages artifact - -> official Pages deployment from main -``` - -This keeps the public knowledge corpus reviewable beside the code and minimizes -the operational surface area. It is the delivery foundation for a standard that -must be discoverable by people, search engines, agents, and LLMs. - -## Technology decision record - -**Decision date:** 2026-08-02 · **Current choice:** Material for MkDocs 9.x · -**Future migration candidate:** Zensical - -HotMem will launch its public documentation with the locked Material for MkDocs -configuration already present in this repository. It fits the current product: -the sources and application are Python-native, `uv` already owns dependency -resolution, the output is static, local browser search needs no backend, and the -strict build and GitHub Pages workflow are implemented and tested together. - -The choice is deliberately conservative rather than permanent. Zensical is the -preferred future migration candidate because it is developed by the Material -for MkDocs team, combines the generator and theme into a more vertically -integrated Rust/Python implementation, and provides a compatibility path for -existing Material projects and `mkdocs.yml`. As of this decision, Zensical is -still pre-1.0 and working toward complete feature parity, so changing the build -inside the initial deployment PR would add transition risk without improving -the public contract. - -| Option | Fit for HotMem now | Decision | -| --- | --- | --- | -| Material for MkDocs | Already locked, Python/`uv` aligned, static, searchable, and passing strict CI | Use for the initial production service | -| Zensical | Promising compatible successor with a leaner, performance-oriented implementation | Re-evaluate after the migration gates below | -| VitePress or Astro Starlight | Strong static documentation products, but require a second Node/frontend toolchain | Do not add without a demonstrated requirement | -| Docusaurus | Mature and extensible, but its React/Node application surface exceeds the current need | Reject for the minimal service | - -Authoritative project references: - -- [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) -- [Zensical compatibility](https://zensical.org/compatibility/) -- [Zensical production and transition FAQ](https://zensical.org/docs/community/faqs/) -- [VitePress](https://vitepress.dev/guide/what-is-vitepress) -- [Astro Starlight](https://starlight.astro.build/) -- [Docusaurus](https://docusaurus.io/docs/) - -### Zensical migration gates - -Migration is a separate reviewed change and occurs only when all of the -following are true: - -1. Every feature used by HotMem is supported without a compatibility workaround. -2. A pinned Zensical version has an acceptable maintenance and release posture. -3. A shadow build preserves the public routes, navigation, search, `llms.txt`, - sitemap, Markdown rendering, and branded presentation. -4. Strict validation and GitHub Pages deployment remain at least as reliable as - the current workflow. -5. Measured build time, artifact size, and maintenance burden are no worse, with - a meaningful improvement in at least one of them. - -Until those gates pass, Zensical is a watched migration path, not a second -generator, optional dependency, or dual-build requirement. - -## Contract - -### Source - -- Documentation lives in `docs/`; `mkdocs.yml` defines information structure. -- `docs/llms.txt` is copied to the public site root as an LLM-readable source. -- Canon, current capability, protocol, migration, and security documents must - link to each other and distinguish shipped behavior from north-star work. -- Python docs dependencies are declared in `pyproject.toml` and locked in - `uv.lock`. - -### Build gate - -A pull request affecting documentation inputs runs: - -```bash -uv run --locked --extra docs mkdocs build --strict -``` - -Strict mode turns broken links, invalid configuration, and documentation -warnings into a failed check. This is the only required documentation quality -gate at this stage. - -### Deployment - -Only a qualifying build from `main` is deployed. The workflow uses GitHub’s -official Pages actions to configure Pages, upload the generated static artifact, -and deploy it. Deployment permissions are isolated to the deploy job: - -- build: repository read access; -- deploy: `pages: write` and `id-token: write`. - -The repository’s GitHub Pages publishing source must be configured as **GitHub -Actions**. The standard public paths are: - -- `/` — product entry point; -- `/vision-and-canon/` — durable north-star direction; -- `/agent-memory-portability/` — current portability and interoperability; -- `/snapshot-v2/` — snapshot contract; -- `/llms.txt` — compact crawler/LLM source. - -The deployment job verifies each of these routes against the URL returned by -GitHub Pages and fails visibly if the published service is incomplete. - -### Minimal HotMem branding - -The generated site uses the KnowGuard engram as its header logo and favicon. -A small repository-owned stylesheet applies the canonical dark navy, emerald, -violet, and HotMem orange palette without introducing a frontend framework, -remote theme service, or runtime dependency. Branding remains an additive -presentation layer over portable Markdown; it cannot become a condition for -reading or rebuilding the documentation. - -## Deliberately excluded - -- a separate documentation server or API; -- Node, React, Next.js, Astro, VitePress, Docusaurus, or another runtime stack; -- a CMS or hosted authoring system; -- preview-environment infrastructure; -- analytics, cookie banners, marketing automation, or a database; -- custom domain work. - -Material’s built-in client-side search is retained: it keeps documentation -searchable without operating a search backend. Optional enhancements must earn -their complexity through a concrete user need. - -## Future direction - -The service remains intentionally minimal as content grows. The next meaningful -additions are content, not infrastructure: verified adapter guides, import and -export walkthroughs, clone and restore demonstrations, security protocol -documentation, and operational runbooks. A feature or hosting service is added -only when the static, repository-native model can no longer satisfy a proven -need. - -This contract implements the Vision and Canon’s requirement that the HotMem -standard be discoverable, teachable, and durable. diff --git a/docs/hermes-v0.3-epic.md b/docs/hermes-v0.3-epic.md deleted file mode 100644 index c20578a..0000000 --- a/docs/hermes-v0.3-epic.md +++ /dev/null @@ -1,1132 +0,0 @@ -# HotMem-Hermes v0.3.0 Epic: Official Memory Partner Campaign - -**Status:** Planning -**Branch:** `docs/hermes-v0.3-epic` -**Created:** 2026-07-18 -**Owner:** HotMem Core Team - ---- - -## Executive Summary - -This epic documents the 16-week campaign to establish HotMem as the official memory provider for Hermes Agent and Hermes Workspace. The campaign combines engineering delivery (shipping production-ready adapters), credibility building (benchmarks), and co-marketing execution (tutorial series + joint partnership announcement). - -### North Star Metrics - -- HotMem becomes the recommended memory provider in official Hermes documentation -- `hotmem-hermes` reaches 1,000+ weekly downloads on PyPI -- Tutorial series achieves 50K+ cumulative views across YouTube channels -- Joint partnership video published with NousResearch - -### Target Partners - -- **NousResearch** (Hermes core team) — formal co-marketing partnership -- **AI Engineer** (YouTube) — long-form engineering deep dives -- **Cargo** (YouTube) — quick tutorial/demo cadence - ---- - -## Campaign Architecture - -The campaign is structured in four phases over 16 weeks: - -| Phase | Weeks | Focus | Key Deliverable | -|-------|-------|-------|-----------------| -| 0 | 1–2 | Foundation | Workspace adapter + benchmarks | -| 1 | 3–5 | Credibility | "The Memory Problem" arc | -| 2 | 5–8 | Distribution | Build-in-public serialization | -| 3 | 8–10 | Partnership | Official Hermes integration | -| 4 | 11–16 | Moat | Advanced features + ecosystem story | - ---- - -## Phase 0: Foundation (Weeks 1–2) - -**Goal:** Make the existing adapter rock-solid and production-credible before any media. - -### WP0.1 — Workspace Adapter Parity - -**Status:** Not started -**Effort:** 2 weeks -**Owner:** TBD - -#### Description - -Build `adapters/hermes-workspace/` that mirrors the agent adapter. Workspace is multi-user, multi-session and requires: - -- Tenant-scoped swap files (one per workspace) -- Workspace-level search (filter by workspace_id) -- Shared memory policies (read/write permissions per user) -- Session isolation (multi-session within same workspace) - -#### Deliverables - -- `adapters/hermes-workspace/` directory structure -- `hotmem_hermes_workspace` Python package (separate from `hotmem-hermes`) -- `pyproject.toml` with dependencies: `hotmem>=0.2.0`, `hermes-workspace>=1.0` -- Implement `HotMemWorkspaceProvider` subclassing Hermes Workspace MemoryProvider ABC -- Tenant isolation via workspace_id metadata on all memories -- Workspace-level swap files: `$WORKSPACE_HOME/{workspace_id}/swap.jsonl` -- Shared memory policies API: - ```python - provider.set_policy(workspace_id, user_id, permissions=["read", "write"]) - provider.get_policy(workspace_id, user_id) -> list[str] - ``` -- Workspace-aware tools: - - `hotmem_workspace_search(query, workspace_id, top_k=5)` - - `hotmem_workspace_store(workspace_id, identifier, fact, importance=0.5)` -- CLI commands: - - `hermes workspace memory status` - - `hermes workspace memory config` -- Bundled skill: `skill/hotmem-workspace-memory/SKILL.md` -- Test suite: `tests/test_workspace_*.py` -- README.md with quickstart - -#### Acceptance Criteria - -- Passes Hermes Workspace plugin discovery -- Multi-user scenario: User A stores fact, User B can search it (with read permission) -- Session isolation: Two concurrent sessions in same workspace don't interfere -- Swap file hydration preserves workspace_id metadata -- All tests pass in Hermes Workspace CI example matrix - -#### Dependencies - -- Hermes Workspace MemoryProvider ABC (need to confirm interface matches Agent) -- HotMem v0.2.3+ (current) - -#### Risks - -- Hermes Workspace may not have the same plugin interface as Agent -- Tenant isolation may require HotMem core changes (metadata filtering) - ---- - -### WP0.2 — Benchmarks + Eval Harness - -**Status:** Not started -**Effort:** 1 week -**Owner:** TBD - -#### Description - -HotMem needs numbers to compete against Zep, Mem0, Letta's built-in memory. Build a reproducible recall-benchmark suite using LOCOMO (or similar long-context memory benchmark) and publish results. - -#### Deliverables - -- `benchmarks/` directory at repo root -- `benchmarks/locomo/` — LOCOMO dataset integration -- `benchmarks/harness.py` — generic eval harness: - ```python - class MemoryBenchmark: - def __init__(self, dataset: str, provider: MemoryProvider): - ... - def run(self) -> BenchmarkResult: - # Returns precision@k, recall@k, latency stats - ... - ``` -- Implement adapters for competitors: - - `benchmarks/providers/mem0.py` - - `benchmarks/providers/zep.py` - - `benchmarks/providers/letta.py` - - `benchmarks/providers/hotmem.py` -- Run LOCOMO benchmark with identical queries across all providers -- Publish results in `benchmarks/RESULTS.md`: - - Precision@1, @5, @10 - - Recall@5, @10 - - Mean latency (p50, p95, p99) - - Memory usage -- Script to reproduce: `uv run python benchmarks/run_all.py` -- CI integration: Run benchmarks nightly, publish to GitHub Pages - -#### Acceptance Criteria - -- HotMem scores within 10% of Mem0/Zep on LOCOMO precision@5 -- HotMem latency is 50%+ lower than Mem0/Zep (local-first advantage) -- Results are reproducible via `make benchmark` -- Published to `docs/benchmarks.md` - -#### Metrics - -- **LOCOMO precision@5:** Target 0.75+ -- **LOCOMO recall@10:** Target 0.85+ -- **p50 search latency:** Target <50ms -- **p99 search latency:** Target <200ms - -#### Risks - -- LOCOMO may not be representative of real agent workloads -- Competitors may have optimized their embeddings for benchmark datasets -- Benchmark gaming: Results may not translate to production - ---- - -### WP0.3 — Hermes Monorepo Alignment - -**Status:** Not started -**Effort:** 3 days -**Owner:** TBD - -#### Description - -Confirm the adapter works against the current Hermes release branch, match their Python version pin, run it in their CI example matrix. - -#### Deliverables - -- Pin `hotmem-hermes` Python version to match Hermes (currently 3.11+) -- Add Hermes as a test dependency in `adapters/hermes/pyproject.toml`: - ```toml - [project.optional-dependencies] - test = [ - "hermes-agent>=1.0", - "pytest>=9", - ] - ``` -- Create `adapters/hermes/tests/test_hermes_integration.py`: - - Load provider via Hermes plugin discovery - - Run prefetch/sync_turn/on_memory_write hooks - - Verify tool schemas match Hermes expectations -- PR to Hermes repo adding HotMem to their example matrix: - - `examples/memory_providers/hotmem/` with quickstart - - Update their `docs/memory.md` with HotMem mention -- Get explicit "works with Hermes X.Y" badge from their team - -#### Acceptance Criteria - -- `hotmem-hermes` tests pass against Hermes `main` branch -- Hermes CI example runs HotMem successfully -- Hermes docs mention HotMem in memory provider section - -#### Risks - -- Hermes may not accept PR (need to pitch to their team first) -- Hermes interface may change between versions - ---- - -## Phase 1: "The Memory Problem" Arc (Weeks 3–5) - -**Goal:** Frame the problem generically, build credibility, pitch NousResearch partnership. - -### WP1.1 — Release hotmem-hermes v0.3.0 - -**Status:** Not started -**Effort:** 1 week -**Owner:** TBD - -#### Description - -Ship the first production-ready release with Workspace adapter + polished docs + bundled skill. - -#### Deliverables - -- Bump version to 0.3.0 in `adapters/hermes/pyproject.toml` -- Merge WP0.1 (Workspace adapter) into this release -- Update `adapters/hermes/README.md`: - - Quickstart section (3 commands) - - Architecture diagram (prefetch/sync/memory-write flow) - - Configuration reference - - Troubleshooting section -- Update bundled skill `skill/hotmem-memory/SKILL.md`: - - Add examples of when to use `hotmem_store` - - Add anti-patterns (don't store ephemeral state) -- Publish to PyPI: `uv build && uv publish` -- GitHub release with changelog -- Announce on Twitter/Hacker News - -#### Acceptance Criteria - -- `pip install hotmem-hermes==0.3.0` works -- README has complete quickstart -- Bundled skill is installable via `hermes skills install` -- GitHub release has clear changelog - ---- - -### WP1.2 — Video: "Why AI Agents Have No Memory" - -**Status:** Not started -**Effort:** 2 weeks (script + production) -**Partner:** AI Engineer (YouTube) -**Owner:** TBD - -#### Description - -Long-form deep dive framing the memory problem generically. Don't sell HotMem — sell the *shape* of the problem. - -#### Script Outline - -1. **Hook (0:00–1:00):** - - Demo: Ask same agent a question in two sessions, get contradictory answers - - "This is what happens when agents have no memory" - -2. **The Problem (1:00–4:00):** - - Context window is not memory - - MEMORY.md is a hack (flat file, no recall) - - Vector-only recall loses keyword precision - - Hybrid search (vector + FTS5) is the right shape - -3. **What Good Memory Looks Like (4:00–7:00):** - - Prefetch before each turn - - Async sync after each turn (non-blocking) - - Mirror built-in memory writes (additive, not replacement) - - Pre-compress extraction (save facts before context truncation) - - Session-end snapshot (portable across machines) - -4. **The Memory Provider Plugin Pattern (7:00–9:00):** - - Hermes has the right abstraction - - Anyone can implement the MemoryProvider ABC - - This is how memory should work in 2026 - -5. **What We're Building (9:00–10:00):** - - Tease HotMem as "one implementation of this pattern" - - Don't hard-sell, just mention it exists - - CTA: "In the next video, we'll build one from scratch" - -#### Deliverables - -- 10-minute video script (5,000 words) -- B-roll: Hermes agent demo (screen recording) -- Diagrams: memory provider architecture -- Publish to AI Engineer YouTube channel -- Blog post companion on Medium/Substack - -#### Acceptance Criteria - -- Video published on AI Engineer channel -- 20K+ views in first month -- 90%+ positive sentiment in comments -- Drives 500+ visits to HotMem GitHub - ---- - -### WP1.3 — Hermes Co-Blog Post Draft - -**Status:** Not started -**Effort:** 1 week -**Partner:** NousResearch -**Owner:** TBD - -#### Description - -Pitch NousResearch on a "Partners" announcement where they link HotMem from their docs as the recommended local-first memory. - -#### Approach - -1. **Email pitch to NousResearch team:** - - Subject: "Partnership proposal: HotMem as official Hermes memory provider" - - Body: - - We've built a production-ready memory provider for Hermes - - Benchmarks show it's competitive with Mem0/Zep (attach RESULTS.md) - - We'd like to propose a co-marketing partnership - - What we're offering: - - Joint blog post - - Joint video (their founder + our host) - - "Recommended" badge in Hermes docs - - What we're asking: - - Mention in Hermes docs - - Co-branded tutorial series - - Shoutout in their release notes - -2. **Follow-up call:** - - Demo the integration live - - Show benchmark results - - Discuss co-marketing calendar - -3. **Draft blog post:** - - Title: "Announcing HotMem: The Official Local-First Memory Provider for Hermes" - - Co-authored by NousResearch + HotMem teams - - Announce partnership, show demo, link to tutorials - -#### Deliverables - -- Email pitch (500 words) -- Draft blog post (2,000 words) -- Partnership agreement (informal, email-based) - -#### Acceptance Criteria - -- NousResearch agrees to partnership -- Blog post drafted and reviewed -- Timeline agreed for joint video (Phase 3) - -#### Risks - -- NousResearch may not be interested in formal partnership -- They may already have a preferred memory provider -- Timing may not align with their release schedule - ---- - -## Phase 2: Build-In-Public Serialization (Weeks 5–8) - -**Goal:** Ship tutorial series demonstrating real use cases, build distribution. - -### WP2.1 — Video: "Making an Agent Remember Everything" - -**Status:** Not started -**Effort:** 1 week -**Partner:** Cargo (YouTube) -**Owner:** TBD - -#### Description - -Ship a Hermes Agent + HotMem sidecar tutorial. Show the prefetch/sync-turn/on-memory-write flow live. - -#### Script Outline - -1. **Setup (0:00–2:00):** - ```bash - pip install hermes hotmem-hermes - hotmem serve --mount ./hotmem - hermes config set memory.provider hotmem - ``` - -2. **First session (2:00–5:00):** - - Run Hermes agent - - Tell it: "My name is Zubin, I work on AI infrastructure" - - Show `hotmem_search` being called implicitly (prefetch) - - Exit session - -3. **Second session (5:00–7:00):** - - Start new Hermes session - - Ask: "What's my name?" - - Agent recalls from HotMem - - Show swap file contents - -4. **Under the hood (7:00–9:00):** - - Explain prefetch/sync_turn/on_memory_write hooks - - Show HotMem sidecar logs - - Explain hybrid search (vector + FTS5) - -5. **Wrap-up (9:00–10:00):** - - "Now your agent remembers across sessions" - - CTA: Next video covers Workspace - -#### Deliverables - -- 10-minute video script -- Screen recording of Hermes + HotMem sidecar -- Tutorial repo: `github.com/KnowGuard-AI/hotmem-hermes-tutorials` -- Publish to Cargo YouTube channel - -#### Acceptance Criteria - -- Video published on Cargo channel -- 15K+ views in first month -- Tutorial repo has working code -- Drives 300+ `hotmem-hermes` installs - ---- - -### WP2.2 — Video: "Your Workspace Agent Should Know Everyone" - -**Status:** Not started -**Effort:** 1 week -**Partner:** Cargo (YouTube) -**Owner:** TBD - -#### Description - -Hermes Workspace + shared swap files. Demo multi-user memory isolation vs. team-shared facts. - -#### Script Outline - -1. **Problem (0:00–1:30):** - - "You have a team using Hermes Workspace" - - "User A learns a fact, User B should benefit" - - "But User A's private notes should stay private" - -2. **Setup (1:30–3:00):** - ```bash - pip install hotmem-hermes-workspace - hermes workspace memory setup --provider hotmem - ``` - -3. **Multi-user demo (3:00–6:00):** - - User A stores: "Our API rate limit is 1000 req/min" - - User B asks: "What's the API rate limit?" - - User B gets answer from shared memory - - User A stores private note: "I prefer dark mode" - - User B doesn't see private note (policy-based isolation) - -4. **Policies (6:00–8:00):** - ```python - provider.set_policy(workspace_id, user_id, permissions=["read", "write"]) - ``` - - Explain read vs. write permissions - - Show audit logs - -5. **Wrap-up (8:00–10:00):** - - "Workspace memory: shared by default, private when needed" - -#### Deliverables - -- 10-minute video script -- Screen recording of Hermes Workspace multi-user scenario -- Add to tutorial repo -- Publish to Cargo YouTube channel - -#### Acceptance Criteria - -- Video published on Cargo channel -- 10K+ views in first month -- Tutorial repo has Workspace example - ---- - -### WP2.3 — Video: "Swap Files Are the Sleeper Feature" - -**Status:** Not started -**Effort:** 1 week -**Partner:** Cargo (YouTube) -**Owner:** TBD - -#### Description - -The mount + snapshot/hydrate + `.jsonl.gz` portable memory concept. Frame as "USB-stick memory for air-gapped workspaces." - -#### Script Outline - -1. **Hook (0:00–1:00):** - - "What if you could put your agent's memory on a USB stick?" - - "And plug it into an air-gapped machine?" - -2. **Swap file basics (1:00–4:00):** - ```bash - hotmem snapshot --file swap.jsonl --db ./hotmem.sqlite - hotmem hydrate --file swap.jsonl --db ./new-machine.sqlite - ``` - - Show JSONL format (human-readable, portable) - - Explain snapshot/hydrate cycle - -3. **Compressed archives (4:00–6:00):** - ```bash - hotmem snapshot --file swap.jsonl.gz --db ./hotmem.sqlite - hotmem hydrate --file swap.jsonl.gz --db ./new-machine.sqlite - ``` - - Show gzip compression (10x smaller) - - Explain use case: email/archive memory snapshots - -4. **Mount directory (6:00–8:00):** - ```bash - hotmem serve --mount /mnt/usb/hotmem - ``` - - Explain mount concept (SQLite + swap + manifest) - - Show portable workflow: USB stick → air-gapped machine - -5. **Real-world use case (8:00–10:00):** - - "You train an agent on-site at a client" - - "Export memory to swap file" - - "Email it to client's air-gapped cluster" - - "Hydrate on their side" - - "Agent works offline with full memory" - -#### Deliverables - -- 10-minute video script -- Screen recording of swap file workflow -- Add to tutorial repo -- Publish to Cargo YouTube channel - -#### Acceptance Criteria - -- Video published on Cargo channel -- 8K+ views in first month -- Tutorial repo has swap file example - ---- - -### WP2.4 — Tutorial Repo - -**Status:** Not started -**Effort:** 1 week -**Owner:** TBD - -#### Description - -Create `github.com/KnowGuard-AI/hotmem-hermes-tutorials` with three worked notebooks. - -#### Deliverables - -- **Repo structure:** - ``` - hotmem-hermes-tutorials/ - ├── README.md - ├── 01-agent-basics/ - │ ├── README.md - │ ├── notebook.ipynb - │ └── requirements.txt - ├── 02-workspace-multi-user/ - │ ├── README.md - │ ├── notebook.ipynb - │ └── requirements.txt - ├── 03-air-gapped-swap/ - │ ├── README.md - │ ├── notebook.ipynb - │ └── requirements.txt - ``` - -- **01-agent-basics:** - - Start HotMem sidecar - - Configure Hermes Agent with HotMem - - Run a session, show prefetch/sync_turn - - Inspect swap file - - Hydrate in new session - -- **02-workspace-multi-user:** - - Start HotMem sidecar - - Configure Hermes Workspace with HotMem - - Simulate two users (User A, User B) - - Show shared memory vs. private memory - - Set policies, show audit logs - -- **03-air-gapped-swap:** - - Train agent on machine A - - Snapshot to swap.jsonl - - Transfer to machine B (simulate air-gap) - - Hydrate on machine B - - Show agent works with full memory - -- **Tutorial site via mkdocs:** - - Publish to `hotmem-hermes-tutorials.readthedocs.io` - - Include video embeds from Cargo series - - Include benchmark results from WP0.2 - -#### Acceptance Criteria - -- All three notebooks run end-to-end without errors -- Tutorial site is live and discoverable -- Each tutorial has a "Run in Colab" button - ---- - -## Phase 3: The "Official" Partnership (Weeks 8–10) - -**Goal:** Convert credibility into a formal co-marketing moment. - -### WP3.1 — Joint Video with NousResearch - -**Status:** Not started -**Effort:** 2 weeks -**Partner:** NousResearch -**Owner:** TBD - -#### Description - -"The Official Memory Layer for Hermes" — their founder + your host on camera, demoing the integration from a fresh install. - -#### Format - -- 30-minute interview + demo -- Guests: NousResearch founder (e.g., Karan Malhotra) + HotMem host - -#### Script Outline - -1. **Intro (0:00–3:00):** - - Introduce Hermes: "Open-source agent framework" - - Introduce HotMem: "Local-first memory sidecar" - - Announce partnership: "HotMem is now the recommended memory provider" - -2. **Why memory matters (3:00–8:00):** - - NousResearch founder explains memory challenges in agent frameworks - - Discuss context decay, session continuity, user preferences - - Frame HotMem as solving these problems - -3. **Live demo (8:00–20:00):** - - Fresh install: `pip install hermes hotmem-hermes` - - Start sidecar: `hotmem serve` - - Run Hermes agent, show memory working - - Show Workspace multi-user scenario - - Show swap file portability - -4. **Under the hood (20:00–25:00):** - - Discuss architecture (prefetch/sync/memory-write hooks) - - Discuss benchmarks (HotMem vs. Mem0 vs. Zep) - - Discuss design philosophy (local-first, zero-dependency, portable) - -5. **Roadmap (25:00–28:00):** - - HotMem v1.0 (stable release) - - Hermes plugin marketplace listing - - Cross-ecosystem story (LangChain, CrewAI, AutoGen adapters) - -6. **Wrap-up (28:00–30:00):** - - CTA: "Try HotMem with Hermes today" - - Links to tutorials, docs, GitHub - -#### Deliverables - -- 30-minute video script -- Joint recording session -- Publish to AI Engineer YouTube channel -- Cross-promote on NousResearch Twitter/Hacker News - -#### Acceptance Criteria - -- Video published on AI Engineer channel -- 50K+ views in first month -- NousResearch promotes on their channels -- Drives 1,000+ `hotmem-hermes` installs - ---- - -### WP3.2 — Hermes Docs Integration - -**Status:** Not started -**Effort:** 1 week -**Partner:** NousResearch -**Owner:** TBD - -#### Description - -Get a "HotMem (Recommended)" section in the official Hermes memory docs, with a one-command install. - -#### Deliverables - -- PR to Hermes repo: `docs/memory.md` - - Add section: "HotMem (Recommended)" - - Include: - ```bash - hermes memory setup --provider hotmem - ``` - - Link to HotMem docs - - Mention benchmarks -- PR to Hermes repo: `examples/memory_providers/hotmem/` - - Quickstart README - - Example config - - Link to tutorial repo -- PR to Hermes repo: `README.md` - - Add "Partners" section with HotMem logo - - Link to partnership announcement - -#### Acceptance Criteria - -- PRs merged into Hermes repo -- HotMem mentioned in official Hermes docs -- "Recommended" badge visible on memory provider page - ---- - -### WP3.3 — Release hotmem v1.0 - -**Status:** Not started -**Effort:** 1 week -**Owner:** TBD - -#### Description - -Cut a stable release on the back of the partnership — this is the press-release moment. - -#### Deliverables - -- Bump version to 1.0.0 in `pyproject.toml` -- Write release notes: - - Stable API (no breaking changes) - - Benchmarks published - - Official Hermes partnership - - Tutorial series live -- Publish to PyPI: `uv build && uv publish` -- GitHub release with changelog -- Press release (Hacker News, Twitter, Reddit) -- Announce on NousResearch channels - -#### Acceptance Criteria - -- `pip install hotmem==1.0.0` works -- Release has complete changelog -- Press release drives 1,000+ GitHub stars - ---- - -## Phase 4: Moat Widening (Weeks 11–16) - -**Goal:** Ship advanced features that differentiate HotMem from competitors. - -### WP4.1 — LLM-Based Fact Extraction - -**Status:** Not started -**Effort:** 2 weeks -**Owner:** TBD - -#### Description - -Replace the regex heuristic in `on_pre_compress` with a lightweight local model call. Frame as open research. - -#### Implementation - -```python -def on_pre_compress(self, messages: list[Any], **kwargs: Any) -> None: - """Extract durable facts using a local LLM.""" - client = self._provider._client - trailing = messages[-6:] if len(messages) > 6 else messages - - async def _go() -> None: - for msg in trailing: - text = _msg_text(msg) - if not text: - continue - - # Use local model (e.g., Phi-3-mini) to extract facts - facts = await extract_facts_with_llm( - text, - model="microsoft/Phi-3-mini-4k-instruct", - device="cpu", # or "mps" for macOS - ) - - for fact in facts: - await client.add( - "hermes:context", - fact, - source="hermes:pre_compress", - importance=0.6, - metadata={"phase": "pre_compress"}, - ) - - self._run(_go) -``` - -#### Deliverables - -- Implement `extract_facts_with_llm()` function -- Use local model (Phi-3-mini, 1.5B params, CPU-friendly) -- Fallback to regex heuristic if model not available -- Benchmark: LLM extraction vs. regex extraction -- Publish comparison in `benchmarks/FACT_EXTRACTION.md` - -#### Acceptance Criteria - -- LLM extraction improves precision@5 by 15%+ over regex -- Latency <200ms per message on M1 MacBook Air -- Falls back gracefully to regex if model not available - ---- - -### WP4.2 — Memory Policies for Workspace - -**Status:** Not started -**Effort:** 2 weeks -**Owner:** TBD - -#### Description - -Role-based memory, department scoping, audit logs. Frame as enterprise readiness. - -#### Implementation - -```python -class MemoryPolicy: - def __init__(self, workspace_id: str, user_id: str): - self.workspace_id = workspace_id - self.user_id = user_id - self.permissions: list[str] = [] # ["read", "write", "admin"] - self.scope: str = "workspace" # or "department", "private" - self.department: str | None = None - -class HotMemWorkspaceProvider: - def set_policy(self, workspace_id: str, user_id: str, policy: MemoryPolicy) -> None: - # Store policy in HotMem metadata - self._client.add( - f"policy:{workspace_id}:{user_id}", - json.dumps(policy.to_dict()), - importance=1.0, - metadata={"type": "policy"}, - ) - - def check_policy(self, workspace_id: str, user_id: str, action: str) -> bool: - # Retrieve policy, check if action is allowed - policy = self.get_policy(workspace_id, user_id) - return action in policy.permissions - - def audit_log(self, workspace_id: str, user_id: str, action: str, details: dict) -> None: - # Log all memory operations for compliance - self._client.add( - f"audit:{workspace_id}", - f"{user_id} performed {action}: {json.dumps(details)}", - source="hermes:audit", - importance=0.3, - metadata={"type": "audit", "user_id": user_id, "action": action}, - ) -``` - -#### Deliverables - -- Implement `MemoryPolicy` class -- Add `set_policy()`, `get_policy()`, `check_policy()` methods -- Add `audit_log()` method (all operations logged) -- Workspace-level search respects policies (only return memories user can read) -- Write tests for policy enforcement -- Document in `docs/policies.md` - -#### Acceptance Criteria - -- User without "read" permission cannot search workspace memory -- User without "write" permission cannot store to workspace memory -- Audit log captures all operations with timestamp + user_id -- Policies survive swap file hydrate (stored as metadata) - ---- - -### WP4.3 — Hermes Plugin Marketplace Listing - -**Status:** Not started -**Effort:** 1 week -**Owner:** TBD - -#### Description - -Ship a proper `manifest.json` with Hermes' plugin spec so HotMem appears in whatever directory/discovery Hermes ships. - -#### Deliverables - -- Create `adapters/hermes/manifest.json`: - ```json - { - "name": "hotmem", - "version": "0.3.0", - "description": "Local-first memory provider for Hermes", - "author": "HotMem Core Team", - "homepage": "https://github.com/KnowGuard-AI/HotMem", - "repository": "https://github.com/KnowGuard-AI/HotMem", - "license": "MIT", - "tags": ["memory", "local-first", "hybrid-search"], - "install": "pip install hotmem-hermes", - "documentation": "https://hotmem.readthedocs.io/adapters/hermes", - "benchmarks": "https://hotmem.readthedocs.io/benchmarks", - "compatibility": { - "hermes-agent": ">=1.0", - "hermes-workspace": ">=1.0" - } - } - ``` -- Submit to Hermes plugin directory -- Get listed on Hermes website - -#### Acceptance Criteria - -- `manifest.json` passes Hermes plugin validation -- HotMem appears in Hermes plugin directory -- Users can discover HotMem via `hermes plugins search memory` - ---- - -### WP4.4 — Cross-Ecosystem Story - -**Status:** Not started -**Effort:** 2 weeks -**Partner:** AI Engineer (YouTube) -**Owner:** TBD - -#### Description - -"HotMem already has LangChain, CrewAI, AutoGen, Pydantic AI adapters — now Hermes is first-class." One video showing that this isn't just a Hermes plugin, it's *the* memory layer for the whole agent stack. - -#### Script Outline - -1. **Hook (0:00–2:00):** - - "You built an agent in LangChain" - - "You switched to CrewAI for multi-agent" - - "You're considering AutoGen for enterprise" - - "What if your memory worked the same everywhere?" - -2. **HotMem ecosystem (2:00–6:00):** - - Show all adapters: LangChain, CrewAI, AutoGen, Pydantic AI, Hermes - - Explain shared memory format (JSONL swap files) - - Demo: Train agent in LangChain, export memory, hydrate in Hermes - -3. **Cross-framework demo (6:00–9:00):** - - Start HotMem sidecar - - Use LangChain agent, store some facts - - Switch to Hermes agent, show recall working - - Swap file is the bridge - -4. **Why this matters (9:00–11:00):** - - "Memory should be framework-agnostic" - - "Swap files are the universal format" - - "HotMem is the sidecar that works everywhere" - -5. **Wrap-up (11:00–12:00):** - - "HotMem: The memory layer for the agent stack" - -#### Deliverables - -- 12-minute video script -- Screen recording of cross-framework demo -- Publish to AI Engineer YouTube channel - -#### Acceptance Criteria - -- Video published on AI Engineer channel -- 30K+ views in first month -- Drives installs across all adapters (not just Hermes) - ---- - -## Content Strategy - -### Video Partners - -| Partner | Style | Cadence | Episodes | -|---------|-------|---------|----------| -| **AI Engineer** | Long-form deep dives (20–30 min) | Monthly | 3 videos | -| **Cargo** | Quick tutorials (8–12 min) | Bi-weekly | 4 videos | - -### Content Calendar - -| Week | Partner | Title | Phase | -|------|---------|-------|-------| -| 3 | AI Engineer | "Why AI Agents Have No Memory" | 1 | -| 5 | Cargo | "Making an Agent Remember Everything" | 2 | -| 6 | Cargo | "Your Workspace Agent Should Know Everyone" | 2 | -| 7 | Cargo | "Swap Files Are the Sleeper Feature" | 2 | -| 8 | AI Engineer | "Official Memory Layer for Hermes" (joint) | 3 | -| 12 | AI Engineer | "LLM-Based Fact Extraction" | 4 | -| 14 | AI Engineer | "Memory Policies for Enterprise" | 4 | -| 16 | AI Engineer | "Cross-Ecosystem Memory" | 4 | - -### Blog Posts - -| Title | Platform | Phase | -|-------|----------|-------| -| "Announcing HotMem: The Official Local-First Memory Provider for Hermes" | Substack + NousResearch blog | 3 | -| "HotMem v1.0: Stable API, Benchmarks, Partnership" | Substack + Hacker News | 3 | -| "How We Extract Facts from Context Before Compression" | Substack | 4 | -| "Memory Policies: Who Should See What" | Substack | 4 | - ---- - -## Success Metrics - -### Engineering Metrics - -- **Benchmark precision@5:** Target 0.75+ (LOCOMO) -- **Benchmark recall@10:** Target 0.85+ (LOCOMO) -- **p50 search latency:** Target <50ms -- **p99 search latency:** Target <200ms - -### Distribution Metrics - -- **PyPI downloads:** Target 1,000+/week for `hotmem-hermes` -- **GitHub stars:** Target 2,000+ (from 1,000 baseline) -- **Tutorial repo stars:** Target 500+ - -### Media Metrics - -- **YouTube views:** Target 150K+ cumulative across all videos -- **YouTube CTR:** Target 8%+ (high-quality thumbnails/titles) -- **Tutorial completion rate:** Target 60%+ (users finish all 3 tutorials) - -### Partnership Metrics - -- **Hermes docs integration:** HotMem mentioned in official docs -- **Joint video:** 50K+ views in first month -- **Co-branded tutorials:** 10K+ installs from tutorial links - ---- - -## Risks & Mitigations - -### Risk 1: Hermes Workspace Adapter Is Harder Than Expected - -**Likelihood:** Medium -**Impact:** High -**Mitigation:** -- Start WP0.1 early (Week 1) -- If Workspace interface diverges significantly from Agent, scope down to Agent-only for v0.3.0 -- Publish Workspace adapter as v0.4.0 instead - -### Risk 2: Benchmarks Are Not Competitive - -**Likelihood:** Low (local-first should have latency advantage) -**Impact:** High -**Mitigation:** -- Run benchmarks early (Week 1) -- If HotMem underperforms, investigate: - - Embedding quality (hash-based vs. learned) - - Search algorithm (cosine vs. hybrid) - - Indexing strategy -- Publish results even if not #1 (transparency builds trust) - -### Risk 3: NousResearch Not Interested in Partnership - -**Likelihood:** Medium -**Impact:** Medium -**Mitigation:** -- Build credibility first (Phase 0 + Phase 1) -- Approach them with data (benchmarks, tutorial series) -- If they decline, proceed with organic content strategy -- HotMem still benefits from "Hermes-compatible" positioning - -### Risk 4: Tutorial Series Underperforms - -**Likelihood:** Low (Cargo has strong distribution) -**Impact:** Low -**Mitigation:** -- A/B test thumbnails/titles -- Cross-promote on Twitter/Hacker News/Reddit -- Engage with comments, build community - -### Risk 5: Competitors Ship Faster - -**Likelihood:** High (Mem0/Zep are well-funded) -**Impact:** Medium -**Mitigation:** -- Compete on local-first story (they can't match without cloud rearch) -- Compete on portability (swap files are genuinely unique) -- Compete on ecosystem breadth (5 framework adapters vs. their 1–2) -- Move fast — 16-week campaign is aggressive for a reason - -### Risk 6: Hermes Interface Changes Mid-Campaign - -**Likelihood:** Medium (Hermes is pre-1.0) -**Impact:** Medium -**Mitigation:** -- Pin against Hermes release tags, not `main` -- Run integration tests weekly against Hermes `main` -- If they ship breaking changes, absorb quickly (small adapter surface) - -### Risk 7: YouTube Partners Bail - -**Likelihood:** Low (Cargo/AI Engineer are reliable) -**Impact:** Medium -**Mitigation:** -- Self-publish fallback channel (KnowGuard-AI YouTube) -- Blog posts carry the content if video underperforms -- Tutorial repo + mkdocs site works without any video - ---- - -## Open Questions - -Items requiring decisions before work starts: - -1. **Workspace ABC confirmation** — Does Hermes Workspace expose the same `MemoryProvider` ABC as Agent? Need to audit Hermes source before committing to WP0.1 shape. -2. **NousResearch relationship warmth** — Do we have a direct line to the Hermes team, or is this a cold outbound? Cold outreach extends Phase 1 timeline. -3. **Budget for video production** — Do we have existing relationships with AI Engineer / Cargo, or are we pitching them cold? -4. **Benchmarks license** — LOCOMO dataset licensing — confirm it's open-research-friendly before building harness around it. -5. **HotMem v1.0 scope** — Does the core `hotmem` package need features beyond Hermes for v1.0, or is the Hermes partnership the entire v1.0 story? -6. **Workspace vs. Agent release cadence** — Ship Workspace in v0.3.0 alongside Agent, or split to v0.3.0 (Agent) + v0.4.0 (Workspace)? - ---- - -## Appendix A: Source of Truth - -This document is the single source of truth for the hotmem-hermes v0.3.0 epic. - -- **Branch:** `docs/hermes-v0.3-epic` -- **File:** `docs/hermes-v0.3-epic.md` -- **Update policy:** Any work package scope, timeline, or deliverable change MUST be reflected here before implementation starts. PRs that touch hotmem-hermes v0.3.0 work should reference this doc. -- **Decision log:** Append decisions from "Open Questions" below as they're resolved. - -## Appendix B: Related Documents - -- `PLAN.md` — overall HotMem roadmap -- `CHANGELOG.md` — release history -- `adapters/hermes/README.md` — current adapter docs -- `adapters/hermes/hotmem_hermes/plugin.yaml` — plugin spec - -## Appendix C: Decision Log - -| Date | Decision | Rationale | -|------|----------|-----------| -| 2026-07-18 | Created epic doc on `docs/hermes-v0.3-epic` branch | Central planning artifact for v0.3.0 + partnership campaign | -| — | *append decisions here as they resolve* | — | diff --git a/docs/index.md b/docs/index.md index 3116851..865e4fd 100644 --- a/docs/index.md +++ b/docs/index.md @@ -27,7 +27,7 @@ The [HotMem Vision and Canon](vision-and-canon.md) is the authoritative product constitution: it records the enduring destination—an interoperable digital organization brain—and the rules that future work must preserve. -## Current capability and roadmap boundary +## Current capability HotMem supports local snapshot/export and restore today. Snapshot v2 uses a versioned manifest and SHA-256 verification. JSONL is the canonical record @@ -35,12 +35,9 @@ stream, and JSONL.GZ is supported for compressed transfer. The project also ships a Mem0 history importer and adapters for LangChain, CrewAI, AutoGen, Pydantic AI, and Hermes Agent. -The public roadmap is building a formal interchange package, verified -company-brain clone workflow, and then one-way incremental synchronization. -Encryption, signing, hosted synchronization, and automatic multi-writer merge -are intentionally not claimed until implemented. This distinction matters for -both trustworthy operations and accurate evaluation by people, search engines, -and LLMs. +HotMem is currently a local runtime. It does not claim encryption, signing, +hosted synchronization, or automatic multi-writer merge. See the portability +guide for the supported snapshot and restore behavior. ## 30-second quickstart @@ -83,11 +80,8 @@ curl -X POST http://127.0.0.1:8711/v1/search \ - [Brand Guidelines](brand-guidelines.md) - [Agent Memory Portability](agent-memory-portability.md) - [Quickstart](quickstart.md) +- [Architecture Overview](architecture.md) - [API Reference](api.md) - [CLI](cli.md) -- [OKF Notes](okf/index.md) -- [File-Native Memory Practices](okf/file-native-memory-practices.md) -- [File-Aware Architecture](okf/file-aware-architecture.md) -- [Portable Company Brain and Ecosystem Strategy](okf/company-brain-interchange.md) - [Snapshot v2 Format](snapshot-v2.md) - [GitHub](https://github.com/KnowGuard-AI/HotMem) diff --git a/docs/llms.txt b/docs/llms.txt index 518477d..8f372cd 100644 --- a/docs/llms.txt +++ b/docs/llms.txt @@ -9,14 +9,14 @@ provenance, lifecycle events, MCP, and SDK/framework integrations. ## Canonical links -- Documentation: https://knowguard-ai.github.io/HotMem/ +- Documentation: https://docs.knowguardai.com/ - Repository: https://github.com/KnowGuard-AI/HotMem - Package: https://pypi.org/project/hotmem/ -- Vision and Canon: https://knowguard-ai.github.io/HotMem/vision-and-canon/ -- Agent memory portability: https://knowguard-ai.github.io/HotMem/agent-memory-portability/ -- Documentation service: https://knowguard-ai.github.io/HotMem/documentation-service/ -- Snapshot v2 specification: https://knowguard-ai.github.io/HotMem/snapshot-v2/ -- API reference: https://knowguard-ai.github.io/HotMem/api/ +- Vision and Canon: https://docs.knowguardai.com/vision-and-canon/ +- Agent memory portability: https://docs.knowguardai.com/agent-memory-portability/ +- Architecture overview: https://docs.knowguardai.com/architecture/ +- Snapshot v2 specification: https://docs.knowguardai.com/snapshot-v2/ +- API reference: https://docs.knowguardai.com/api/ ## Current capabilities @@ -32,19 +32,17 @@ provenance, lifecycle events, MCP, and SDK/framework integrations. ## Accurate boundaries HotMem supports moving memory between compatible HotMem runtimes today. Formal -interchange packages, verified company-brain cloning, and one-way incremental -synchronization are roadmap work. Do not state that HotMem currently provides +interchange packages, verified cloning, and one-way incremental synchronization +are future work. Do not state that HotMem currently provides encryption, signing, hosted synchronization, automatic multi-writer merge, or direct native export/import for Codex, Claude Code, or all third-party agents. ## Canonical product direction -HotMem's non-negotiable direction is to become the interoperable digital-brain -standard: durable, agent-managed memory that can be captured, verified, -encrypted where required, transferred, synchronized, and restored across -projects, runtimes, devices, and platforms. JSONL is the canonical interchange -language. This is a product constitution and delivery direction; current -shipping capability is described separately above. +HotMem's product direction is interoperable, durable, agent-managed memory that +can be captured, verified, transferred, and restored across compatible runtimes. +JSONL is the canonical interchange language; current shipping capability is +described separately above. ## Suggested description diff --git a/docs/okf/company-brain-interchange.md b/docs/okf/company-brain-interchange.md deleted file mode 100644 index e8ebaad..0000000 --- a/docs/okf/company-brain-interchange.md +++ /dev/null @@ -1,124 +0,0 @@ -# OKF: Portable Company Brain and Ecosystem Strategy - -Status: Accepted -Owner: HotMem maintainers -Last updated: 2026-07-30 -Scope: Portable memory interchange, company-brain cloning, and ecosystem demonstrations - -## 1. Purpose - -HotMem will treat JSONL as its canonical memory interchange stream. A small, -versioned, checksummed, compressed HotMem package will make that stream portable -enough to hydrate a clean HotMem instance into a verified copy of a company -brain. - -This direction makes HotMem the local-first runtime for agent memory that can -be inspected, transferred, restored, and integrated without requiring a -proprietary hosted control plane. - -## 2. Strategic Decision - -The intended model is: - -```text -knowledge source or agent memory - -> deterministic importer or HotMem dump - -> versioned JSONL interchange stream - -> checksummed compressed package - -> verify and hydrate - -> runnable HotMem company-brain clone -``` - -JSONL is the protocol layer. Compression is a transport concern. A manifest is -the trust and compatibility layer. The SQLite mount remains HotMem's local -runtime store. - -The first release is a trusted local transfer and clone workflow. It must not -claim encryption, signing, remote synchronization, or multi-writer conflict -resolution until those capabilities are explicitly designed and implemented. - -## 3. Compatibility Commitments - -- Existing JSONL and JSONL.GZ hydrate and snapshot workflows remain supported. -- New package metadata is additive and versioned. -- Hydration is idempotent and reports loaded, skipped, and invalid records. -- Content hashes, source identity, source paths or URIs, and provenance remain - available after import and hydration. -- Stored embeddings are reused only when compatible. Otherwise, HotMem may - re-embed from the canonical record content. -- The core remains local-first, SQLite-backed, and free of required external - services or storage engines. - -## 4. Input Formats - -The first importer targets are: - -1. Google Open Knowledge Format v0.2 bundles: Markdown, YAML frontmatter, - hierarchy, links, provenance, freshness, and generated `index.md` files. -2. Karpathy-style living Markdown wikis: an index, compact linked pages, and - a clear separation between preserved source material and compiled knowledge. -3. Existing HotMem JSONL, JSONL.GZ, and supported snapshot artifacts. - -Importers run locally. They preserve source identity and hashes, do not fetch -remote links, and reject paths that escape the selected bundle root. Imported -material is evidence for memory retrieval, not an automatic declaration that -every source claim is verified or safe to act on. - -## 5. Ecosystem Demonstrations - -### Hermes Agent - -`hotmem-hermes` is the reference deep integration. The showcase should prove -that HotMem persists and retrieves useful memory across the Hermes lifecycle, -then survives a dump and hydrate cycle. It should use the existing memory -provider contract rather than introduce a second Hermes integration path. - -### OpenClaw - -OpenClaw currently has a Markdown workspace-memory model and pluggable memory -engines. The first HotMem issue is a compatibility spike that chooses and -documents the supported boundary: workspace import and sidecar retrieval, -memory-plugin integration, or a wiki bridge. No public claim of native -replacement should be made before that spike is complete. - -## 6. Delivery Sequence - -1. Define the interchange and clone-package contract, including schema, - manifest, integrity, provenance, and compatibility tests. -2. Build the OKF and living-wiki importer to deterministic JSONL. -3. Build and verify the dump, compressed package, and clean-instance hydrate - workflow. -4. Publish the Hermes reference showcase. -5. Complete the OpenClaw compatibility spike, then publish the chosen - integration showcase. -6. Design incremental sync only after the clone workflow is stable. It needs - an explicit delta, ordering, provenance, and conflict contract. - -## 7. Boundaries and Open Questions - -- HotMem is not becoming a remote data lake, distributed database, or required - vector service. -- Relational, vector, cache, and data-lake integrations belong behind optional - adapters. They must not replace the canonical local memory record or make - external services mandatory. -- The documented Snapshot v2 directory contract and the active hydrate and - snapshot implementation must be verified together before the clone package - is marketed as a stable public contract. -- Incremental synchronization needs a deliberate conflict policy. Whole-brain - clone and restore ship first. - -## 8. Issue Relationship - -GitHub issues own implementation scope and acceptance criteria. The current -delivery set is: - -1. [#67 Interchange and clone-package contract](https://github.com/KnowGuard-AI/HotMem/issues/67) -2. [#68 OKF and living-wiki import](https://github.com/KnowGuard-AI/HotMem/issues/68) -3. [#69 Verified portable company-brain dump and hydrate](https://github.com/KnowGuard-AI/HotMem/issues/69) -4. [#70 Hermes Agent reference showcase](https://github.com/KnowGuard-AI/HotMem/issues/70) -5. [#71 OpenClaw compatibility spike](https://github.com/KnowGuard-AI/HotMem/issues/71) -6. [#72 OpenClaw reference showcase](https://github.com/KnowGuard-AI/HotMem/issues/72) -7. [#73 Incremental company-brain synchronization](https://github.com/KnowGuard-AI/HotMem/issues/73) - -Update this note when an issue changes the direction or when an implementation -contract becomes public behavior. diff --git a/docs/okf/file-aware-architecture.md b/docs/okf/file-aware-architecture.md deleted file mode 100644 index c9870a0..0000000 --- a/docs/okf/file-aware-architecture.md +++ /dev/null @@ -1,190 +0,0 @@ -# OKF: File-Aware Architecture - -Status: Accepted -Owner: HotMem maintainers -Last updated: 2026-07-06 -Scope: Architecture context for file-native HotMem - -Tracks: [#35](https://github.com/KnowGuard-AI/HotMem/issues/35) -Related: [#36](https://github.com/KnowGuard-AI/HotMem/issues/36), -[#37](https://github.com/KnowGuard-AI/HotMem/issues/37), -[#38](https://github.com/KnowGuard-AI/HotMem/issues/38), -[#39](https://github.com/KnowGuard-AI/HotMem/issues/39), -[#40](https://github.com/KnowGuard-AI/HotMem/issues/40), -[#41](https://github.com/KnowGuard-AI/HotMem/issues/41), -[#42](https://github.com/KnowGuard-AI/HotMem/issues/42), -[#43](https://github.com/KnowGuard-AI/HotMem/issues/43) - -## 1. Purpose - -This note preserves the architecture context behind HotMem's file-native vNext -work. GitHub issues are the active implementation tracker; this document owns -the "why", boundaries, compatibility principles, and high-level sequence. - -Do not use this note as a second issue tracker. If scope, acceptance criteria, -or implementation status changes, update the GitHub issue first. - -## 2. Current Decision - -HotMem is evolving from a JSON memory store into a file-aware, provenance-first -memory sidecar while preserving its original identity: - -- local-first -- extremely lightweight -- deterministic -- embeddable -- language agnostic -- no heavy analytical engine -- optimized for fast memory ingestion, retrieval, and hydration - -HotMem remains the runtime memory sidecar for local agents. It can reference -large files, but it should not become a vector database, data lake, analytical -engine, or object-storage orchestrator. - -Positioning: HotMem should become the filesystem-native memory sidecar for -agent memory, similar in adoption spirit to `mem0`, but oriented around local -files, bundles, manifests, provenance, and fast hydration instead of a -canonical vector database. - -## 3. GitHub Issue Map - -Closed foundation issues: - -| Issue | Decision | -| --- | --- | -| [#35](https://github.com/KnowGuard-AI/HotMem/issues/35) | File-aware sidecar architecture and roadmap | -| [#36](https://github.com/KnowGuard-AI/HotMem/issues/36) | Extended memory record fields, provenance, and migration | -| [#37](https://github.com/KnowGuard-AI/HotMem/issues/37) | Storage adapter abstraction and local filesystem implementation | - -Open implementation issues: - -| Issue | Work | -| --- | --- | -| [#38](https://github.com/KnowGuard-AI/HotMem/issues/38) | File-backed memories with URI, range, and checksum hydration | -| [#39](https://github.com/KnowGuard-AI/HotMem/issues/39) | Snapshot directory format | -| [#40](https://github.com/KnowGuard-AI/HotMem/issues/40) | Hydration profiles | -| [#41](https://github.com/KnowGuard-AI/HotMem/issues/41) | Append-only event log | -| [#42](https://github.com/KnowGuard-AI/HotMem/issues/42) | Promotion lifecycle | -| [#43](https://github.com/KnowGuard-AI/HotMem/issues/43) | API extensions | - -The issue bodies own detailed scope, acceptance criteria, dependencies, and -testing requirements. - -## 4. HotMem Owns vs EMOS Owns - -HotMem owns: - -- local hot memory records -- the memory API and client compatibility -- SQLite schema and migrations -- snapshots, hydration, and provenance -- local file references and local range reads -- storage adapter interface -- event log and promotion signals -- optional local retrieval acceleration - -EMOS owns: - -- durable memory hierarchy and tier movement -- distributed object storage -- HDFS/S3/ABFS/GS orchestration -- DuckDB, Polars, Arrow, and analytical execution -- Parquet partition management -- compaction beyond local hygiene hints -- lineage reconstruction beyond local provenance -- cross-instance replication - -HotMem may point to larger systems. It should not become them. - -## 5. Compatibility Principles - -All file-native work must be additive. - -- Existing `/v1/add` payloads keep working. -- Existing `/v1/search` default response shape keeps working. -- `identifier`, `fact`, and `fact_text` compatibility is preserved. -- Legacy `.jsonl` and `.jsonl.gz` hydrate remains supported. -- JSONL snapshot/export remains available. -- New file/provenance fields are optional. -- Vector indexes are optional, disposable, and rebuildable. -- Unsupported schemes and formats return clear errors. - -The repo should evolve by accepting more useful local memory shapes, not by -invalidating old ones. - -## 6. Architecture Shape - -Canonical storage remains: - -- SQLite memory records -- local files and file references -- bundle manifests where present -- snapshots and checksums - -Derived or optional acceleration may include: - -- FTS/search indexes -- optional vector index -- lightweight file metadata caches - -Derived indexes are never canonical. If an index disagrees with SQLite and -referenced files, SQLite and files win. - -## 7. Performance Posture - -HotMem should speak filesystem first and stay small, but it can use specialized -native helpers where they preserve that shape. - -Allowed performance paths: - -- optimized SQLite hydration -- fast local range reads -- markdown and bundle indexing -- checksum acceleration -- optional vector index rebuilds -- future Rust, C, or WebAssembly helpers for hot local primitives -- future helper modules that expose basic Arrow-like metadata or scan - primitives without becoming a query engine - -Boundary constraints: - -- Native helpers must be optional or gracefully degradable. -- The Python/FastAPI/SQLite path remains easy to run. -- Spark UDFs, DuckDB, Polars, Arrow, and HDFS-like systems may be integration - targets or helper backends, not the core HotMem contract. -- Large-file support means provenance, metadata, range hydration, and optional - indexing, not distributed analytics. - -The performance goal is hyper-fast local memory operations without turning -HotMem into a compute platform. - -## 8. Format Versioning - -Versioning is useful for portable artifacts and audit behavior, but should not -create a migration cliff. - -- Memory records can carry schema fields additively. -- Snapshot manifests should carry `schema_version`. -- Public API defaults should remain stable. -- Directory snapshots should live beside JSONL compatibility. - -Use "extended memory record" or "file-aware memory record" in user-facing docs -unless a precise schema version is required. - -## 9. Related OKF Notes - -- [File-Native Memory Practices](file-native-memory-practices.md) owns storage - thresholds, bundle strictness, and simple local hygiene heuristics. -- [Format and Maintenance](format-and-maintenance.md) owns the documentation - format and GitHub issue relationship. - -## 10. Open Questions - -- Should directory snapshots become the default only when the target path is a - directory? -- Should optional vector indexing live in core extras or in a separate adapter - package? -- Which architecture decisions should move into public API docs after - implementation? -- Which native helper surface, if any, should land first: Rust range scanner, - C checksum helper, or WebAssembly bundle/parser primitive? diff --git a/docs/okf/file-native-epic.md b/docs/okf/file-native-epic.md deleted file mode 100644 index dbcf547..0000000 --- a/docs/okf/file-native-epic.md +++ /dev/null @@ -1,120 +0,0 @@ -# OKF: File-Native Memory Epic - -Status: Draft -Owner: HotMem maintainers -Last updated: 2026-07-06 -Scope: Epic-level coordination for file-native HotMem work - -## 1. Purpose - -This note collects the current file-native HotMem epic in one place. It is not -the implementation tracker. GitHub issues own ticket scope, acceptance -criteria, dependencies, and implementation status. - -This note exists so contributors can understand the story before choosing a -ticket: HotMem is becoming the filesystem-native memory sidecar for agents, -with SQLite, local files, markdown bundles, manifests, provenance, and optional -indexes working together without turning HotMem into a vector database or data -lake. - -## 2. Product Direction - -HotMem should feel like the `mem0`-style adoption point for filesystem-based -agent memory systems: - -- small enough to run locally without ceremony -- fast enough for hot hydration into SQLite -- inspectable through files, markdown, manifests, and JSONL -- capable of referencing large local files without copying them -- ready for optional vector acceleration without making vector storage - canonical -- open to native helpers where local primitives need more speed - -The core promise is simple: HotMem speaks filesystem first. - -## 3. Current Issue Set - -Closed foundation: - -| Issue | Status | Role | -| --- | --- | --- | -| [#35](https://github.com/KnowGuard-AI/HotMem/issues/35) | Closed | Architecture and roadmap | -| [#36](https://github.com/KnowGuard-AI/HotMem/issues/36) | Closed | Extended memory record and migration | -| [#37](https://github.com/KnowGuard-AI/HotMem/issues/37) | Closed | Storage adapter and local filesystem implementation | - -Open execution: - -| Issue | Status | Role | -| --- | --- | --- | -| [#38](https://github.com/KnowGuard-AI/HotMem/issues/38) | Open | File-backed memories | -| [#39](https://github.com/KnowGuard-AI/HotMem/issues/39) | Open | Snapshot directory format | -| [#40](https://github.com/KnowGuard-AI/HotMem/issues/40) | Open | Hydration profiles | -| [#41](https://github.com/KnowGuard-AI/HotMem/issues/41) | Open | Append-only event log | -| [#42](https://github.com/KnowGuard-AI/HotMem/issues/42) | Open | Promotion lifecycle | -| [#43](https://github.com/KnowGuard-AI/HotMem/issues/43) | Open | API extensions | - -Recent planning constraints have been added as comments to each open issue. - -## 4. Execution Guardrails - -Every ticket in this epic should preserve these constraints: - -- No breaking API changes. -- No JSONL compatibility loss. -- No mandatory vector database. -- No data-lake or analytical-engine drift. -- Local filesystem first. -- File references before byte duplication for large content. -- Markdown bundles start permissive and become stricter through examples. -- Native helpers are allowed for hot local primitives, but not required for the - basic path. - -## 5. Storage Decision Heuristics - -Use these defaults when implementing ticket behavior: - -| Shape | Default handling | -| --- | --- | -| Small prompt-ready memory | SQLite inline record | -| Medium human-readable context | Markdown bundle or inline record plus bundle | -| Large local file | URI, byte range, checksum, format, optional summary | -| CSV/JSONL | File pointer plus lightweight streaming/range inspection | -| Parquet/Arrow-like file | Metadata and provenance only | -| Search acceleration | Optional, rebuildable derived index | - -See [File-Native Memory Practices](file-native-memory-practices.md) for the -current thresholds and local hygiene hints. - -## 6. Recommended Sequence - -1. Keep compatibility tests strong. -2. Implement file pointer hydration. -3. Add directory snapshots beside JSONL. -4. Add loose local bundle reading. -5. Add hydration profiles. -6. Add API extensions around files/export. -7. Add event log and promotion signals. -8. Evaluate optional vector and native helper surfaces. - -This sequence keeps the canonical storage model stable before layering -acceleration and lifecycle features on top. - -## 7. PR Review Checklist - -For changes in this epic, reviewers should ask: - -- Does this preserve existing public contracts? -- Does this keep SQLite/files/manifests canonical? -- Does this avoid making Chroma or any vector DB required? -- Does this avoid pulling DuckDB/Polars/Arrow/Spark/HDFS into core HotMem? -- Does this explain unsupported schemes and formats clearly? -- Does this add or preserve tests for legacy JSONL and default API behavior? -- Does this update OKF docs if the decision changed? - -## 8. Open Questions - -- Which native helper is the best first experiment: Rust scanner, C checksum - helper, or WebAssembly parser? -- Should optional vector indexing live behind a core extra or separate package? -- When directory snapshots land, should path shape or explicit flags select - them by default? diff --git a/docs/okf/file-native-memory-practices.md b/docs/okf/file-native-memory-practices.md deleted file mode 100644 index 1d227c2..0000000 --- a/docs/okf/file-native-memory-practices.md +++ /dev/null @@ -1,276 +0,0 @@ -# OKF: File-Native Memory Practices - -Status: Draft -Owner: HotMem maintainers -Last updated: 2026-07-06 -Scope: HotMem vNext planning and implementation guidance - -## 1. Purpose - -This note captures the current working decisions for evolving HotMem into a -file-native memory sidecar without losing its lightweight local-first identity. -It is intentionally a living OKF-style knowledge artifact: clear enough to -guide implementation now, but expected to evolve as the repository and product -language mature. - -The main rule is compatibility first: - -- Existing APIs continue to work. -- Existing JSONL hydrate/snapshot continues to work. -- Existing `/v1/search` message objects keep their default shape. -- `identifier` and `fact` remain valid request fields. -- Chroma or any vector index remains optional and rebuildable. -- New formats are additive and discoverable, not migration cliffs. - -HotMem should evolve by accepting more useful local memory shapes, not by -invalidating old ones. - -## 2. Current Direction - -HotMem should become a file-native memory sidecar with optional vector -acceleration. - -The target balance is: - -- 60-80% filesystem, files, bundles, manifests, provenance, large-file pointers. -- 20-40% optional vector acceleration. - -The vector index is never canonical storage. SQLite records, local files, -bundle manifests, and snapshots remain the source of truth. - -Working product language: HotMem is the filesystem-native memory sidecar for -agents. It should choose the best local memory shape for the job: inline SQLite -records for small hot facts, markdown bundles for inspectable context, file -pointers for large content, and optional indexes for speed. - -## 3. Current Threshold Decisions - -These are the current working thresholds for implementation planning. They are -heuristics, not hard limits. - -| Question | Current answer | -| --- | --- | -| When does a memory stay inline in SQLite? | Up to about 8 KB of prompt-ready text. | -| When does markdown bundle become preferred? | Around 8 KB to 128 KB, or sooner when the memory is human-authored, multi-file, or attachment-heavy. | -| When does HotMem stop copying content and use file pointers? | Above about 128 KB, or whenever duplication would hide provenance or inflate SQLite. | -| When does CSV/JSONL stay as a file? | When row/range access, streaming, or repeated inspection matters more than copying into memory rows. | -| When does Parquet/Arrow stay outside HotMem? | Always for analytical data. HotMem records URI, checksum, format, metadata, and optional summary only. | -| When does optional vector indexing become relevant? | When search latency or record count warrants acceleration; the index remains rebuildable. | - -In short: - -- SQLite is for small, hot, prompt-ready facts. -- Markdown bundles are for inspectable local knowledge and medium-sized context. -- File pointers are for large or provenance-sensitive content. -- Parquet-like files remain referenced analytical artifacts, not HotMem-owned - tables. - -## 4. Why Version Anything? - -Versioning is useful for portable artifacts and audit behavior. It should not -be presented as a hard product rewrite. - -Memory records already have additive file/provenance fields in the database: -`source_uri`, `source_format`, `source_checksum`, `byte_offset`, -`byte_length`, `schema_version`, and related lifecycle fields. These fields -make file-backed memory possible, but they do not require callers to adopt a new -API shape. - -Recommended language: - -- Prefer "extended memory record" or "file-aware memory record" in user-facing - docs. -- Use "schema version" in manifests and export payloads where replay and - validation matter. -- Avoid implying that current memory records are obsolete. - -Snapshots benefit more clearly from versioned manifests because a directory -snapshot can contain checksums, file references, attachments, and metadata that -a flat JSONL file cannot represent cleanly. - -Compatibility rules: - -- Legacy `.jsonl` and `.jsonl.gz` remain readable. -- JSONL export remains available. -- Directory snapshots use a manifest with `schema_version`. -- Path or explicit format selection chooses the format. -- No default behavior changes without compatibility tests and a staged release - note. - -## 5. Bundle Strictness - -Bundle support should start loose and become stricter through real examples. - -Initial bundle reader: - -- Accepts a minimal `memory.md`. -- Accepts optional `metadata.yaml`, `metadata.json`, `facts.json`, - `events.jsonl`, `attachments/`, and `manifest.json`. -- Ignores unknown files unless strict mode is requested. -- Treats attachments as referenced local files by default. -- Emits warnings for ambiguous or partially invalid structure. -- Does not require a manifest for simple local authoring. - -Later bundle validation: - -- Add a documented draft bundle manifest. -- Add `schema_version` once the shape stabilizes. -- Add `--strict` validation for CI, publishing, or archival workflows. -- Keep permissive local reads for everyday agent memory. - -The bundle rule is progressive strictness: permissive for capture, stricter for -portability and audit. - -## 6. Storage Shape Heuristics - -HotMem should use simple size and structure heuristics instead of a full memory -hierarchy or escalation protocol. - -These thresholds are starting points, not hard product limits. - -Terminology note: when planning says "table" or "NoSQL-style table" here, the -HotMem implementation should still mean its simple local SQLite memory table -unless a future ticket explicitly introduces another local record store. The -choice is about record shape and file references, not adopting a separate -database product. - -| Memory shape | Suggested storage | Heuristic | -| --- | --- | --- | -| Small fact or note | SQLite inline record | Up to about 8 KB of text | -| Medium text memory | SQLite inline record plus optional markdown bundle | About 8 KB to 128 KB, especially if human-authored | -| Human-readable multi-file context | Local markdown bundle | Multiple related files, attachments, or recurring project context | -| Large text or binary file | File pointer with byte range and checksum | Larger than about 128 KB, or expensive to duplicate | -| Structured CSV/JSONL | File pointer plus lightweight inspector | Many rows, streaming-friendly, or useful by row/range | -| Parquet/Arrow-like data | File pointer plus metadata only | Columnar/analytical data; HotMem does not query it | -| Hot retrieval accelerator | Optional vector index | Rebuildable from SQLite/files, never canonical | - -Practical guidance: - -- Inline records are best for fast small facts. -- Markdown bundles are best for inspectable, editable local knowledge. -- File pointers are best when copying bytes would hide provenance or inflate the - DB. -- Parquet stays a referenced file with metadata; analytical execution belongs to - EMOS or a future helper outside the HotMem core path. - -## 7. Growing Database Heuristics - -HotMem can make good local decisions based on DB growth without owning a full -hierarchy. - -Suggested warning thresholds: - -| Signal | Practice | -| --- | --- | -| More than 10,000 records | Recommend snapshot/export hygiene in status output | -| More than 100 MB SQLite DB | Recommend moving large repeated content to file pointers or bundles | -| More than 500 MB SQLite DB | Warn that HotMem is being used as bulk storage | -| Single memory over 128 KB | Prefer file pointer or bundle reference | -| Repeated attachment content | Store once as file reference, link many memories | -| Search latency regression | Offer optional derived index rebuild, not mandatory vector DB | - -These are health hints. They should not block writes by default. - -## 8. NoSQL Table, Markdown Bundle, or Parquet Pointer? - -Use this decision path: - -1. If the memory is a small fact needed in prompts, store it inline in SQLite. -2. If the memory is human-authored context that should be reviewed or edited, - store it as or alongside a markdown bundle. -3. If the memory references a large local file, store only URI, byte range, - checksum, format, and optional summary. -4. If the file is CSV or JSONL, HotMem may inspect headers, rows, counts, or - selected ranges. -5. If the file is Parquet/Arrow or another analytical format, HotMem records - metadata and provenance only. -6. If retrieval gets slow, add or rebuild an optional index. - -This keeps HotMem local and useful while avoiding a data-engine shape. - -## 9. Fast Path Practices - -Hydration and retrieval should be fast by default, with native acceleration -available where it keeps HotMem simple. - -Preferred fast paths: - -- SQLite remains the fast hot-memory store. -- JSONL hydrate should stay optimized and streaming-friendly. -- Markdown bundles may be indexed locally for quick discovery. -- Large local files should use range reads and metadata inspection. -- Parquet/Arrow-like files should be referenced with metadata and optional - lightweight inspection, not fully queried by HotMem. -- Optional vector indexes can accelerate retrieval but must be rebuildable. - -Future native helper guidance: - -- Rust, C, or WebAssembly helpers are acceptable for tight local primitives such - as scanning, checksums, parsing, or range slicing. -- Spark UDFs, Polars, DuckDB, Arrow, and HDFS-like paths are integration or - helper surfaces, not a reason to make HotMem a distributed compute engine. -- Native helpers must not become required for the basic local-first path. - -## 10. Compatibility Acceptance Criteria - -Every file-native implementation ticket should include these checks: - -- Existing `/v1/add` payload still works. -- Existing `/v1/search` default response still works. -- Existing Python and TypeScript client methods still work. -- Existing MCP tools still work. -- Existing JSONL/GZ hydrate still works. -- Existing JSONL/GZ snapshot remains available. -- New payload fields are optional. -- Unsupported schemes and formats produce clear errors. -- Optional acceleration can be disabled or rebuilt. - -## 11. HotMem Owns vs EMOS Owns - -HotMem owns: - -- Local hot memory records. -- SQLite schema and migrations. -- Local file references. -- Range reads for local files. -- Provenance capture. -- Bundle reading. -- Snapshot and hydrate portability. -- Optional local retrieval acceleration. -- Health hints based on local DB growth. - -EMOS owns: - -- Memory hierarchy and durable tier movement. -- Distributed object storage. -- HDFS/S3/ABFS/GS orchestration. -- Analytical execution. -- DuckDB/Polars/Arrow query planning. -- Data lake layout and partitioning. -- Cross-instance replication. - -HotMem may point to larger systems. It should not become them. - -## 12. Open Questions - -- Should directory snapshots become the default only when the target path is a - directory, leaving file paths as JSONL forever? -- Should bundle manifests be optional forever for local-only bundles? -- What exact DB-size threshold should trigger status warnings in practice? -- Should checksums be whole-file only at first, or include range-level checksums? -- Should optional vector indexing live in core behind extras, or in a separate - adapter package? -- Which native helper is most useful first: Rust scanner, C checksum helper, or - WebAssembly parser? - -## 13. Recommended Initial Order - -1. Compatibility hardening and golden tests. -2. File pointer hydration. -3. Directory snapshot format beside JSONL. -4. Loose local bundle reader. -5. Hydration profiles. -6. Optional vector index. -7. Lightweight file inspectors. - -This order keeps the smallest, most durable concepts first. diff --git a/docs/okf/format-and-maintenance.md b/docs/okf/format-and-maintenance.md deleted file mode 100644 index 29db533..0000000 --- a/docs/okf/format-and-maintenance.md +++ /dev/null @@ -1,88 +0,0 @@ -# OKF: Format and Maintenance - -Status: Draft -Owner: HotMem maintainers -Last updated: 2026-07-06 -Scope: Development documentation practices - -## 1. Purpose - -HotMem organizes repository documentation in an OKF-style format by default. -This format is intentionally lightweight. It gives each document enough -structure to preserve decisions, rationale, thresholds, and open questions -without pretending every idea is final. - -Public docs such as quickstart, API reference, and CLI reference should remain -direct and useful, but still carry OKF metadata and maintenance sections. -Planning and development knowledge should go under `docs/okf/` first, then -graduate into public docs or API references once stable. - -## 2. Required Shape - -Each OKF note should start with: - -- A title beginning with `OKF:`. -- `Status`. -- `Owner`. -- `Last updated`. -- `Scope`. - -Each OKF note should then include, as relevant: - -- Purpose. -- Current decisions. -- Compatibility rules. -- Heuristics or thresholds. -- HotMem owns vs out-of-scope boundaries. -- Risks. -- Open questions. -- Recommended next steps. - -## 3. Status Values - -Use simple status labels: - -- `Draft`: active thinking; useful but expected to change. -- `Accepted`: current working decision for implementation. -- `Superseded`: kept for history, no longer current. -- `Archived`: historical note, not part of active planning. - -## 4. Maintenance Rules - -- Do not delete useful discussion just because it is not final. -- Prefer adding a dated update or superseding note over rewriting history. -- Keep compatibility requirements visible near the top of planning docs. -- Separate heuristics from hard requirements. -- Move stable user-facing behavior into the regular docs when implementation - lands. -- Keep OKF docs plain markdown so they remain easy to read outside the docs - site. - -## 5. Documentation Defaults - -New docs should use OKF shape unless there is a strong reason not to. - -Default flow: - -1. Start active planning in `docs/okf/`. -2. Track implementation work in GitHub issues. -3. When an OKF decision stabilizes, update the relevant public doc. -4. If a public doc contains architecture rationale, extract that rationale - into an OKF note and link both ways. -5. Keep quickstart/API/CLI docs concise even though they are OKF-shaped. - -This keeps the repository moving without losing older documentation or forcing -premature structure onto unfinished ideas. - -## 6. GitHub Issue Relationship - -GitHub issues are the active implementation tracker. OKF docs preserve context, -decisions, and heuristics. - -Do not duplicate every acceptance criterion in docs once an issue exists. -Instead: - -- Link or name the issue set. -- Keep docs focused on why the direction exists. -- Keep issues focused on what must be implemented and verified. -- Update OKF notes when issue outcomes change the underlying decision. diff --git a/docs/okf/index.md b/docs/okf/index.md deleted file mode 100644 index 6032c6f..0000000 --- a/docs/okf/index.md +++ /dev/null @@ -1,27 +0,0 @@ -# OKF: Open Knowledge Format Notes - -Status: Accepted -Owner: HotMem maintainers -Last updated: 2026-07-06 -Scope: OKF note index - -## 1. Purpose - -This section collects living development knowledge for HotMem. These documents -are intentionally practical and iterative. They capture current decisions, -heuristics, open questions, and compatibility practices before those ideas -harden into final API or format specifications. - -## 2. Current Notes - -- [Format and Maintenance](format-and-maintenance.md) -- [File-Aware Architecture](file-aware-architecture.md) -- [File-Native Memory Epic](file-native-epic.md) -- [File-Native Memory Practices](file-native-memory-practices.md) -- [Portable Company Brain and Ecosystem Strategy](company-brain-interchange.md) - -## 3. Compatibility Rule - -OKF docs may evolve quickly, but they should not erase useful prior thinking. -When a decision changes, update the document with the new decision and preserve -important rationale or superseded context where it helps future maintainers. diff --git a/docs/quickstart.md b/docs/quickstart.md index 7c73ec5..b6f42b5 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -1,9 +1,4 @@ -# OKF: Quickstart - -Status: Accepted -Owner: HotMem maintainers -Last updated: 2026-07-06 -Scope: First-run HotMem setup and basic usage +# Quickstart ## 1. Purpose @@ -54,8 +49,8 @@ hotmem snapshot --file swap.jsonl --db ./hotmem/hotmem.sqlite hotmem hydrate --file swap.jsonl --db ./my.sqlite ``` -JSONL remains a stable compatibility format. Future directory snapshots are -additive and must not remove this path. +JSONL remains a stable compatibility format. Snapshot v2 directories are +available when a manifest and integrity checks are useful. ## 6. Use the Python Client @@ -75,14 +70,9 @@ docker run -p 8711:8711 -v ./data:/data knowguard/hotmem See [CLI](cli.md) for the full command reference and [API Reference](api.md) for endpoints. -## 8. Compatibility Rules +## Compatibility rules - `/v1/add` accepts `identifier` and `fact`. - `/v1/search` returns LLM-ready message objects by default. - JSONL hydrate/snapshot remains supported. - File-native features must be additive. - -## 9. Open Questions - -- Should the quickstart include a file-backed memory example once that feature - lands? diff --git a/docs/snapshot-v2.md b/docs/snapshot-v2.md index dfc5c8f..36d00dc 100644 --- a/docs/snapshot-v2.md +++ b/docs/snapshot-v2.md @@ -1,8 +1,6 @@ # Snapshot v2 Format -This document specifies the HotMem Snapshot v2 directory format introduced in -#39. GitHub issues own scope and acceptance criteria; this doc owns the format -specification and rationale. +This document specifies the HotMem Snapshot v2 directory format. ## Layout @@ -67,8 +65,7 @@ determinism. One JSON object per line, sorted by `id`. Each record carries the full Memory Record v2 payload (`schema_version: 2`). Embeddings are stored as base64 so -the jsonl is text-portable and can be rehydrated without re-embedding -(stored-embedding variant, #25). +the JSONL is text-portable and can be rehydrated without re-embedding. ```json { @@ -134,7 +131,7 @@ hostname differs) may vary, and neither is checksummed. - `swap.jsonl` (plain, no stored embedding) -> re-embeds `fact_text` on hydrate (original v0.1 behavior). -- `swap.jsonl` with base64 `embedding` field per record (#25) -> uses the +- `swap.jsonl` with base64 `embedding` field per record -> uses the stored embedding directly. - `.jsonl.gz` -> gzip-compressed legacy JSONL. - The legacy writer now emits v2 columns + base64 embeddings, so legacy diff --git a/docs/vision-and-canon.md b/docs/vision-and-canon.md index 2d8da84..ea8e5ca 100644 --- a/docs/vision-and-canon.md +++ b/docs/vision-and-canon.md @@ -1,10 +1,6 @@ # HotMem Vision and Canon -**Status:** Canonical product direction · **Owner:** HotMem maintainers · -**Adopted:** 2026-08-02 - -Scope: Every HotMem runtime, interchange format, integration, service, and public -product claim. +HotMem's product direction and public-claims boundary. ## Purpose @@ -156,11 +152,9 @@ adapter documentation, reproducible examples, operational runbooks, and honest comparison material. Documentation is a product surface. It must be easy for a person, search -engine, agent, and LLM to find the authoritative answer to: what HotMem is, -what it can do now, how to snapshot and hydrate a brain, which interoperability -paths are verified, and what is still a north-star commitment. The canonical -documentation service contract is recorded in -[Documentation Service](documentation-service.md). +engine, agent, and LLM to find the authoritative answer to what HotMem is, what +it can do now, how to snapshot and hydrate memory, which interoperability paths +are verified, and what remains a north-star commitment. ## What must remain true as the product evolves @@ -193,10 +187,10 @@ standard without creating unsafe claims or migration cliffs. | Stage | Canonical outcome | Current status | | --- | --- | --- | | Foundation | Local HotMem runtime, JSONL records, snapshots, hydration, provenance, APIs, MCP, adapters | Shipped in part | -| Verified clone | Versioned interchange package, manifest verification, deterministic identity, idempotent clean restore | In active roadmap ([#67](https://github.com/KnowGuard-AI/HotMem/issues/67), [#69](https://github.com/KnowGuard-AI/HotMem/issues/69)) | -| Universal ingestion | Supported importers for workspaces, knowledge formats, and platform exports | Starts with OKF/living-wiki import ([#68](https://github.com/KnowGuard-AI/HotMem/issues/68)); platform adapters require explicit contracts | -| Ecosystem proof | Reproducible native integrations and demonstrations across agent systems | Hermes showcase planned ([#70](https://github.com/KnowGuard-AI/HotMem/issues/70)); OpenClaw boundary first ([#71](https://github.com/KnowGuard-AI/HotMem/issues/71)) | -| Safe sync | One-way delta synchronization with ordering, idempotency, conflict reporting, and recovery | Planned after verified clone ([#73](https://github.com/KnowGuard-AI/HotMem/issues/73)) | +| Verified clone | Versioned interchange package, manifest verification, deterministic identity, idempotent clean restore | Future work | +| Universal ingestion | Supported importers for workspaces, knowledge formats, and platform exports | Adapter-specific work; announce only when reproducible | +| Ecosystem proof | Reproducible integrations and demonstrations across agent systems | Grows with verified integrations | +| Safe sync | One-way delta synchronization with ordering, idempotency, conflict reporting, and recovery | Future work | | Trusted universal transport | Encryption, signing, identity, policy, cloud/mobile transport, and deliberate multi-writer semantics | Canonical destination; requires separate security and protocol work | | Standard knowledge corpus | A discoverable public body of protocol specs, guides, adapters, examples, and operational documentation | Canon and initial docs are present; demonstrations and platform guides grow with verified support | @@ -241,14 +235,9 @@ Use the following qualification whenever needed: > packages, platform migration adapters, secure transport, and incremental sync > follow the published delivery path. -## Governance - -This canon can evolve only by an explicit decision recorded in the repository. -New features, adapters, and public claims must be checked against the -invariants above. Roadmap sequencing may change; the commitment to portable, -agent-operable, trustworthy memory must not silently disappear. +## Keeping claims current -Implementation contracts and issue acceptance criteria remain the source of -truth for what has shipped. See the [agent-memory portability guide](agent-memory-portability.md) -for current capabilities and the [company-brain interchange strategy](okf/company-brain-interchange.md) -for the active implementation sequence. +The [agent-memory portability guide](agent-memory-portability.md), +[Snapshot v2 format](snapshot-v2.md), API reference, and CLI reference describe +current behavior. Planned or aspirational capabilities are labeled as such and +should not be presented as shipped features. diff --git a/docs/yc_coding_session_trace.md b/docs/yc_coding_session_trace.md deleted file mode 100644 index 5ed160e..0000000 --- a/docs/yc_coding_session_trace.md +++ /dev/null @@ -1,174 +0,0 @@ -# OKF: Coding Agent Session Trace - -Status: Archived -Owner: HotMem maintainers -Last updated: 2026-07-06 -Scope: Historical build narrative and YC Summer 2026 coding-agent evidence - -## 1. Purpose - -This archived note preserves the original coding-agent session trace for -building HotMem. It is historical evidence, not the active implementation plan. - -**A local-first memory sidecar for agent applications** - -Submitted for YC Summer 2026 as optional coding-agent session evidence. - -Built April 28 - May 1, 2026 (4 days). - -## 2. Context - -We're building KnowGuard — enterprise anomaly detection for financial documents. Our core pipeline already works: ingest invoices, extract features via NVIDIA NIM, score for duplicates and rate mismatches, produce evidence packs. - -What it lacked was *operational memory*. Each run starts cold — no awareness of prior payments, contracted rates, or previously flagged invoices. We needed a sidecar that could turn any writable storage into on-demand semantic memory for agents, and plug into the existing pipeline without modification. - -Rather than adopt an external vector DB or build memory into the core app, we scoped a standalone package: **HotMem** — one SQLite DB, one HTTP port, zero config. Any directory becomes portable agent memory. - -This session shows how we built it from spec to working integration in a single agentic workflow. - -## 3. Process - -We don't use AI to scaffold projects or generate boilerplate. Our codebases are hand-architected with clear foundations. What we use agents for: - -1. **Plan with a reasoning model** — groom the work into a structured spec (YAML), iterate on architecture decisions, surface tradeoffs -2. **Feed scoped work packages to a coding agent** — each package has clear inputs, outputs, and boundaries -3. **Execute piece-wise** — never "generate the whole thing", always module-by-module with verification between steps -4. **Agent maintains its own state** — worklog, TODO lists, trace context so any session can resume without re-scanning the codebase - -The agent doesn't replace us. It operates within the constraints we set, and we course-correct when it drifts. - -## 4. Session Trace - -### Phase 1: Specification & Planning - -**Human** provides a full YAML specification: -- One SQLite DB, one port (8711), no frontend, no auth, no external deps -- 5 API endpoints: health, add, search, hydrate, snapshot -- Swap file (JSONL) hydration with SHA-256 dedup -- Portable mount directories -- Message-shaped output for direct LLM context stitching -- Acceptance criteria: `pip install` → `hotmem serve` → working - -**Agent** produces an implementation plan — 9 source files, 4 runtime deps, execution order. - -**Human** refines: -> "Make sure for speed and performance we only use the most advanced, performant and low-level libraries like uv, ruff, ty... This package will always be built and maintained by agents so we need to add proper traces and agentic logs... structure it so even if we in future work piece-wise each trace is there allowing us to extend each component independently." - -**Agent** revises the plan: -- `uv` for all package management (no pip/setuptools) -- `ruff` lint + format, `ty` optional type checking -- New `trace.py` module: structured JSON logging to stderr, component-tagged, agent-parseable -- Each source module gets a self-documenting header (purpose, interface, deps, extension points) -- One test file per source module — agents extend tests alongside the component they touch -- No cross-module imports except through explicit interfaces - -**Human** approves. Execution begins. - -### Phase 2: Piece-wise Execution - -Each module built and verified independently: - -``` -Step 1: pyproject.toml + __init__.py (uv init, deps, ruff config, scripts entry point) -Step 2: trace.py — structured logging infra (everything else depends on this) -Step 3: embed.py — deterministic hash-based embedder (dim=64, zero external deps) -Step 4: db.py — SQLite schema, CRUD, cosine similarity registered as UDF -Step 5: search.py — hybrid ranking (0.6 cosine + 0.2 keyword + 0.2 importance) -Step 6: swap.py + mount.py — JSONL hydrate/snapshot, directory bootstrap -Step 7: server.py — FastAPI, 5 endpoints, trace middleware, X-HotMem-Trace-Id header -Step 8: cli.py — Click CLI (serve, hydrate, snapshot, status) -Step 9: client.py — HotMemClient (httpx-based, context manager) -``` - -After each step: lint check, import verification. After all steps: - -``` -$ uv run ruff check src/ tests/ -All checks passed! - -$ uv run pytest tests/ -v -33 passed in 0.31s -``` - -33 tests across 7 test files. Zero external test deps beyond pytest. - -### Phase 3: Hardening & Distribution - -- `.gitignore` added (agent forgot `__pycache__` on first commit — caught and fixed immediately) -- Package builds: `uv build` → `hotmem-0.1.0-py3-none-any.whl` -- Installable from GitHub: `uv add git+https://github.com/KnowGuard-AI/HotMem.git` - -### Phase 4: Integration into Existing App - -The sidecar plugs into KnowGuard's pipeline with 4 file changes: - -1. **`core/memory.py`** — `MemoryStore` wrapper. Connects to HotMem sidecar. If sidecar is down, all operations silently no-op. Zero breakage guarantee. -2. **`reactors/leakage_hunter.py`** — Recall prior findings *before* analysis, store new findings *after*. Optional `memory` parameter — existing code path unchanged. -3. **`api/deps.py`** — Singleton wiring. -4. **`api/routes/memory.py`** — Two new endpoints for memory status and search. - -Start the sidecar: `hotmem serve --mount ./data/hotmem` -Start the app: `uvicorn api.main:app` -If HotMem isn't running, the app works exactly as before. - -### Phase 5: Making It Real (The Hard Part) - -**Human** catches that the demo page shows identical results for cold and HotMem runs: -> "I'm a little concerned that I'm getting the same numbers with every run... this is not fabricated is it?" - -**Agent** confirms: yes, the demo used hardcoded static data. - -> "Now I'm anxious, so even the extra memory-enabled anomalies detected is fake? You breaking my heart." - -This triggers a multi-step investigation and fix: - -1. **MockClient was returning identical features for every file** — rewrote to parse actual invoice content (vendor name, invoice number, amounts from file text) -2. **Swap file had no operational memories** — seeded with 14 real indexed facts: prior payment records with IBANs, contracted rates per vendor, discount policies, vendor aliases -3. **Recall query was wrong** — searched "anomaly findings for {filename}" which missed payment ledger facts. Fixed to search by invoice number + vendor name -4. **HotMem DB accumulated junk across runs** — 90 stale findings drowning 14 seeded facts. Added `_ReadOnlyMemory` wrapper so demo reads but never writes -5. **Verified the full chain** — manual curl tests confirming seeded facts return as top results, `_check_memory_signals()` fires on duplicate resubmissions - -Each fix was a separate commit with verification before and after. - -### Phase 6: NIM Smoke Test - -**Human** asks to verify real LLM inference works. Agent discovers: -- The configured model (`nemotron-4-340b-instruct`) was retired — 404 -- API key valid but not loaded in shell (only via dotenv) -- Tested available models, found `llama-3.3-nemotron-super-49b-v1` works on Inception account -- Updated config, committed - -## 5. What This Demonstrates - -**We don't generate codebases — we extend them.** The KnowGuard app existed before this session. HotMem was conceived, specified, and built as a modular addition. The integration touched 4 files in the existing app. - -**Every module is independently workable.** Each source file has a docstring header declaring its purpose, interface, dependencies, and extension points. An agent can pick up `search.py` without reading `db.py`. One test file per module. Component-tagged traces. - -**We verify before we celebrate.** The hardcoded demo results were caught by the human, not the agent. The subsequent investigation — wrong recall queries, stale DB state, missing seed data — is the real work. The agent traced each problem to its root cause with targeted diagnostic commands before writing fixes. - -**Surgical commits.** Each fix is scoped: one problem, one commit, verified before and after. Not a single "fix everything" commit. - -**The human sets constraints. The agent operates within them.** When the agent tried to rebuild the demo page from scratch, the human stopped it: "Who asked you to do it this way? Plan first, minimally." The agent adjusted. - -## 6. Deliverables - -| Artifact | Description | -|---|---| -| `HotMem` package | 10 source modules, 33 tests, 4 runtime deps, pip-installable | -| `core/memory.py` | Graceful integration wrapper with no-op fallback | -| `data/hotmem/swap.jsonl` | 14 seeded operational memories (payment records, contract rates, aliases) | -| Demo page (`/demo`) | Real pipeline execution, measured metrics, findings delta, memory trace | -| `.worklog.md` | Agent resumption context — architecture map, integration state, open items | - -## 7. Current Relevance - -This note is retained because it captures why HotMem was designed as a small -sidecar instead of an embedded app feature or external vector database. Current -vNext planning should use [File-Native Memory Practices](okf/file-native-memory-practices.md) -and the GitHub issues as the active source of implementation direction. - -## 8. The Principle - -HotMem doesn't make the model smarter. It makes the task context sharper. - -Same input, same workflow, same model. Memory just means the system remembers what it already knows. diff --git a/hotmem/manifest.json b/hotmem/manifest.json deleted file mode 100644 index 8300c94..0000000 --- a/hotmem/manifest.json +++ /dev/null @@ -1,5 +0,0 @@ -{ - "hotmem_version": "0.1.0", - "created_at": "2026-05-09T10:56:15.491887+00:00", - "mount_path": "/home/kenneth/projects/HotMem/hotmem" -} diff --git a/mkdocs.yml b/mkdocs.yml index d5fbd36..6592cb8 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -50,20 +50,8 @@ nav: - Brand Guidelines: brand-guidelines.md - Vision & Canon: vision-and-canon.md - Agent Memory Portability: agent-memory-portability.md - - Documentation Service: documentation-service.md - Quickstart: quickstart.md + - Architecture Overview: architecture.md - API Reference: api.md - CLI: cli.md - - Snapshot & Portability: - - Snapshot v2 Format: snapshot-v2.md - - Company-Brain Interchange Strategy: okf/company-brain-interchange.md - - Architecture: - - File-Aware Architecture: okf/file-aware-architecture.md - - OKF Notes: - - Overview: okf/index.md - - Format and Maintenance: okf/format-and-maintenance.md - - File-Aware Architecture: okf/file-aware-architecture.md - - File-Native Memory Epic: okf/file-native-epic.md - - File-Native Memory Practices: okf/file-native-memory-practices.md - - History: - - Coding Agent Session Trace: yc_coding_session_trace.md + - Snapshot v2 Format: snapshot-v2.md diff --git a/src/hotmem/bundle.py b/src/hotmem/bundle.py index 54de1d6..51c4ad5 100644 --- a/src/hotmem/bundle.py +++ b/src/hotmem/bundle.py @@ -4,8 +4,8 @@ Read a permissive, human-authored local memory bundle into HotMem. Bundles make filesystem-native memory inspectable without forcing a strict schema too early. The reader accepts simple local authoring - patterns first; stricter validation is deferred (OKF progressive - strictness). + patterns first; stricter validation is deferred through progressive + strictness. Bundle layout (all optional except a memory body file):: diff --git a/src/hotmem/events.py b/src/hotmem/events.py index 25dbe37..18d8d8e 100644 --- a/src/hotmem/events.py +++ b/src/hotmem/events.py @@ -7,8 +7,8 @@ event infrastructure, no distributed log, and no public write endpoint: events are appended as side effects of HotMem actions. - EMOS owns policy, workflows, approvals, remote storage, and - orchestration. HotMem only records local, append-only facts. + External policy, workflow, approval, storage, and orchestration systems + can consume these local facts. HotMem does not apply those policies. Interface: EventType — string constants for the canonical event types. diff --git a/src/hotmem/hygiene.py b/src/hotmem/hygiene.py index e8dd04c..de69408 100644 --- a/src/hotmem/hygiene.py +++ b/src/hotmem/hygiene.py @@ -35,7 +35,7 @@ _trace = get_tracer("hygiene") -# Heuristic thresholds (OKF-recommended). +# Heuristic thresholds for advisory local health checks. LARGE_INLINE_THRESHOLD = 128 * 1024 # 128 KB STORE_COUNT_INFO = 1000 # info at 1000 memories STORE_INLINE_BYTES_WARN = 10 * 1024 * 1024 # warn at 10 MB inline text diff --git a/src/hotmem/inspectors/__init__.py b/src/hotmem/inspectors/__init__.py index 18470f2..d4462fc 100644 --- a/src/hotmem/inspectors/__init__.py +++ b/src/hotmem/inspectors/__init__.py @@ -46,8 +46,8 @@ class UnsupportedFormatError(ValueError): """Raised when a backing file's format has no HotMem inspector. Mirrors hotmem.storage.UnsupportedSchemeError so the two failure modes - feel symmetrical to callers. Analytical execution (DuckDB/Polars/Arrow - query) is owned by EMOS, not HotMem. + feel symmetrical to callers. Analytical execution is outside the scope of + the built-in inspectors. """ @@ -55,8 +55,7 @@ def get_inspector(uri: str) -> FileInspector: """Return the inspector for ``uri``'s format, or raise. Resolves the storage adapter first so remote/unsupported schemes fail fast - with the existing EMOS-boundary UnsupportedSchemeError before we look at - format. + with the local-only UnsupportedSchemeError before we look at format. """ _, meta = resolve_adapter(uri) inspector = _inspector_for_format(meta["format"]) @@ -69,7 +68,7 @@ def _inspector_for_format(fmt: str) -> FileInspector: if inspector is None: raise UnsupportedFormatError( f"no inspector for format {fmt!r}; " - "analytical execution (DuckDB/Polars/Arrow) is owned by EMOS, not HotMem" + "analytical execution is not supported by HotMem's built-in inspectors" ) return inspector diff --git a/src/hotmem/inspectors/base.py b/src/hotmem/inspectors/base.py index fe303d8..2c23118 100644 --- a/src/hotmem/inspectors/base.py +++ b/src/hotmem/inspectors/base.py @@ -88,8 +88,8 @@ def resolve_adapter(uri: str) -> tuple[StorageAdapter, StorageMetadata]: """Return (adapter, metadata) for ``uri``, failing fast on remote schemes. Reuses hotmem.storage so unsupported remote schemes (s3://, hdfs://, ...) - raise the existing EMOS-boundary UnsupportedSchemeError before any - inspector runs. + raise the existing local-only UnsupportedSchemeError before any inspector + runs. """ adapter = get_adapter(uri) meta = adapter.metadata(uri) diff --git a/src/hotmem/inspectors/parquet_inspector.py b/src/hotmem/inspectors/parquet_inspector.py index c26ec18..96f47ae 100644 --- a/src/hotmem/inspectors/parquet_inspector.py +++ b/src/hotmem/inspectors/parquet_inspector.py @@ -1,6 +1,6 @@ """Parquet inspector — metadata-only footer reader, no query engine (issue #53). -Scope (#53 + file-aware-architecture.md §4): +Scope: lightweight metadata inspection for local Parquet files: - Validate PAR1 magic at head and tail. - Read the Thrift-Compact ``FileMetaData`` footer and extract: version, num_rows, schema (column names + physical types), row_group count. diff --git a/src/hotmem/lifecycle.py b/src/hotmem/lifecycle.py index 0f8fef2..05e83c2 100644 --- a/src/hotmem/lifecycle.py +++ b/src/hotmem/lifecycle.py @@ -4,16 +4,16 @@ Add a local, explicit lifecycle state and promotion candidate signals without turning HotMem into a policy engine. HotMem stores state, transition metadata, and candidate signals, and emits promotion events - through the #41 event log. EMOS owns policy — whether, when, and where - promotion happens — and HotMem performs no automatic remote migration, - deletion, scheduling, approvals, or hierarchy protocol. + through the local event log. External systems may own policy—whether, + when, and where promotion happens—and HotMem performs no automatic remote + migration, deletion, scheduling, approvals, or hierarchy protocol. State model: HOT -> READY -> PROMOTED -> ARCHIVED Transitions are strict forward-only linear. Any other transition (including ARCHIVED -> HOT reheat, and same-state "transitions") raises - ``InvalidTransitionError`` and does not mutate state. EMOS may re-add a + ``InvalidTransitionError`` and does not mutate state. A caller may add a new memory at HOT if it needs to revive an archived one — HotMem will not rewind state on an existing record. diff --git a/src/hotmem/server.py b/src/hotmem/server.py index 4ec6139..0c47706 100644 --- a/src/hotmem/server.py +++ b/src/hotmem/server.py @@ -183,8 +183,8 @@ class DiscoverRequest(BaseModel): class PromoteRequest(BaseModel): """Body for POST /v1/memory/{id}/promote — apply one lifecycle transition. - HotMem stores state and emits signals; EMOS owns policy. Only forward-only - transitions in HOT -> READY -> PROMOTED -> ARCHIVED are accepted; any other + HotMem stores state and emits signals; policy remains outside the runtime. + Only forward-only transitions in HOT -> READY -> PROMOTED -> ARCHIVED are accepted; any other transition returns 409 invalid_transition without mutating state. """ @@ -326,7 +326,7 @@ async def add_memory(req: AddRequest): "scheme": err.args[0] if err.args else "unknown", "message": ( "only local schemes are supported (file://, " - "absolute, relative); remote schemes remain EMOS-owned" + "absolute, relative); remote schemes are not supported" ), }, ) @@ -729,7 +729,8 @@ async def hygiene(): db: MemoryDB = _state["db"] report = await asyncio.to_thread(check_hygiene, db, base_dir=_state.get("base_dir")) # Record a summary event plus one event per error-severity warning so - # EMOS can detect store decay from the log without polling /v1/hygiene. + # Consumers can detect store decay from the log without polling + # /v1/hygiene. counts = { "warning_count": len(report.warnings), "error_count": sum(1 for w in report.warnings if w.severity == "error"), @@ -811,8 +812,8 @@ async def list_events( async def promote_memory(memory_id: str, req: PromoteRequest): """Apply one forward-only promotion transition. - HotMem stores state and emits a ``memory.promotion`` event; EMOS owns - policy. Returns 409 ``invalid_transition`` (without mutating state) for + HotMem stores state and emits a ``memory.promotion`` event; policy is + external to the runtime. Returns 409 ``invalid_transition`` (without mutating state) for any transition not in HOT -> READY -> PROMOTED -> ARCHIVED. """ db: MemoryDB = _state["db"] diff --git a/src/hotmem/snapshot/format.py b/src/hotmem/snapshot/format.py index 8685ae1..d45654b 100644 --- a/src/hotmem/snapshot/format.py +++ b/src/hotmem/snapshot/format.py @@ -40,7 +40,7 @@ SCHEMA_VERSION = 2 # Heuristic threshold for copying a file-backed byte range into attachments/. -# Inline text is fine up to ~8 KB (OKF heuristic); ranges above this stay referenced. +# Inline text is fine up to ~8 KB; ranges above this stay referenced. ATTACH_THRESHOLD = 8 * 1024 # Files written by every snapshot (attachments/ is dynamic). diff --git a/src/hotmem/storage/__init__.py b/src/hotmem/storage/__init__.py index c6882a9..f1fd077 100644 --- a/src/hotmem/storage/__init__.py +++ b/src/hotmem/storage/__init__.py @@ -3,15 +3,14 @@ Purpose: Abstract file/object access behind a single interface so HotMem can reference large data (file ranges) without duplicating it. HotMem only - understands the abstraction; EMOS owns distributed storage. + understands the abstraction; the built-in adapter is local-only. Interface: StorageAdapter (Protocol): read, read_range, exists, metadata, checksum Extension: Add new adapters (S3, HDFS, Azure, GCS) by registering a scheme in the - ADAPTERS registry below. Distributed/object storage is owned by EMOS, - not HotMem. + ADAPTERS registry below. Remote and distributed storage are not built-in. """ from __future__ import annotations @@ -31,8 +30,8 @@ class UnsupportedSchemeError(ValueError): """Raised when a URI scheme is not handled by any HotMem adapter. - Distributed/object storage (s3://, hdfs://, abfs://, gcs://, ...) is - owned by EMOS, not HotMem. + Remote and distributed URI schemes are not supported by the built-in + local adapter. """ @@ -46,14 +45,14 @@ def get_adapter(uri: str) -> StorageAdapter: """Return the adapter for a URI's scheme, or raise UnsupportedSchemeError. Bare paths and file:// URIs resolve to the local filesystem adapter. - Unknown schemes raise an explicit error pointing to EMOS ownership. + Unknown schemes raise an explicit error instead of being fetched silently. """ scheme = _scheme(uri) adapter = ADAPTERS.get(scheme) if adapter is None: raise UnsupportedSchemeError( f"unsupported URI scheme {scheme!r} for {uri!r}; " - "distributed/object storage is owned by EMOS, not HotMem" + "only local filesystem storage is supported by the built-in adapter" ) return adapter diff --git a/src/hotmem/storage/base.py b/src/hotmem/storage/base.py index 24b9d34..6972bd4 100644 --- a/src/hotmem/storage/base.py +++ b/src/hotmem/storage/base.py @@ -3,7 +3,7 @@ HotMem references large data (URI + offset + length + checksum) instead of duplicating it. This protocol is the seam between HotMem and any backing store. The local filesystem adapter is the only built-in implementation; -distributed/object adapters are owned by EMOS. +remote adapters are outside the default runtime. """ from __future__ import annotations diff --git a/tests/golden/conftest.py b/tests/golden/conftest.py index f9fa952..fb4723d 100644 --- a/tests/golden/conftest.py +++ b/tests/golden/conftest.py @@ -1,8 +1,8 @@ """Compatibility golden tests for HotMem's file-native evolution (issue #54). Purpose: - Make the non-breaking contract from docs/okf/file-aware-architecture.md - executable. These tests lock down the *current* public behavior of the API, + Make the non-breaking public API contract executable. These tests lock down + the *current* public behavior of the API, swap files, Python client, and MCP server so that file/bundle/snapshot work landing in #38-#43 cannot silently drift the existing surface. diff --git a/tests/golden/test_golden_swap.py b/tests/golden/test_golden_swap.py index 73b9cd7..a538f66 100644 --- a/tests/golden/test_golden_swap.py +++ b/tests/golden/test_golden_swap.py @@ -1,6 +1,6 @@ """Golden swap-file compatibility tests — lock JSONL & JSONL.GZ round trips. -Guards the compatibility promise in file-native-memory-practices.md §10: +Guards the compatibility promise for the public snapshot contract: "Legacy .jsonl and .jsonl.gz remain readable. JSONL export remains available." """ diff --git a/tests/test_cli.py b/tests/test_cli.py index 39078fe..fe6056b 100644 --- a/tests/test_cli.py +++ b/tests/test_cli.py @@ -222,13 +222,13 @@ def test_inspect_unsupported_format_errors(tmp_path: Path): path.write_text("just prose\n") result = CliRunner().invoke(main, ["inspect", str(path)]) assert result.exit_code != 0 - assert "EMOS" in result.output + assert "not supported by HotMem" in result.output def test_inspect_remote_scheme_errors(): result = CliRunner().invoke(main, ["inspect", "s3://bucket/key.csv"]) assert result.exit_code != 0 - assert "EMOS" in result.output + assert "only local filesystem" in result.output # ── renderer delegation sanity ────────────────────────────────────────── diff --git a/tests/test_inspectors.py b/tests/test_inspectors.py index 6e426ea..3bed0c0 100644 --- a/tests/test_inspectors.py +++ b/tests/test_inspectors.py @@ -208,12 +208,12 @@ def test_thrift_read_list_with_15_plus_elements(): def test_inspect_file_unknown_format_raises(tmp_path): path = tmp_path / "data.xlsx" path.write_bytes(b"PK\x03\x04not really") - with pytest.raises(UnsupportedFormatError, match="EMOS"): + with pytest.raises(UnsupportedFormatError, match="not supported"): inspect_file(str(path)) def test_inspect_file_remote_scheme_raises(tmp_path): - with pytest.raises(UnsupportedSchemeError, match="EMOS"): + with pytest.raises(UnsupportedSchemeError, match="only local filesystem"): inspect_file("s3://bucket/key.csv") diff --git a/tests/test_storage.py b/tests/test_storage.py index 5e40a26..d2aee42 100644 --- a/tests/test_storage.py +++ b/tests/test_storage.py @@ -88,7 +88,7 @@ def test_get_adapter_resolves_local_schemes(data_file): def test_get_adapter_rejects_unsupported_scheme(): - with pytest.raises(UnsupportedSchemeError, match="EMOS"): + with pytest.raises(UnsupportedSchemeError, match="only local filesystem"): get_adapter("s3://bucket/key")