Sanitize public documentation surface

.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

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.

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.

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
 

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?

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.

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?