Summary
Documentation gaps and a batch of low-severity polish items collected during the review.
Documentation gaps
- Webhooks feature is undocumented —
HEXUS_WEBHOOK_URL/HEXUS_WEBHOOK_SECRET, payload schema, and a signature-verification recipe appear nowhere but a one-line ROADMAP mention. (Cross-ref the webhooks issue.)
- ~12 real env vars are undocumented (in code, absent from README/docs):
HEXUS_EMBED_LONG_TEXT_MODE, HEXUS_RERANK_LONG_DOC_MODE, HEXUS_EMBED_DEVICE, HEXUS_ENTITY_EXTRACTOR_ENABLED/_PATTERNS, HEXUS_DB_NAME/USER/PASS, MEMORY_PGVECTOR_DB_*, HEXUS_TRANSPORT, HEXUS_DEBUG, HEXUS_LOG_LEVEL, PG_TEST_*. The recently-added long-text chunking + long-doc rerank features have no user docs.
- Stale docs/comments:
compose.yml comments reference a non-existent /app/pgvector/migrations/ path; get_config_schema says embed_url required + "768-dim" (stale); bulk_upsert_md docstring says 768-dim.
Low-severity cleanup
mcp_server/cli.py:141 — _redact_dsn only redacts password= keyword DSNs; a URI-form DSN (postgres://user:pass@host) logs the password in cleartext (cli.py:75-80).hexus/ccr/cache.py:26-29 — CCRCache.set() raises StopIteration when maxsize<=0 (uncaught, under a lock on the write path).mcp_server/server.py:431-453 — cleanup daemon sleeps before its first run and has no jitter/backoff on repeated failure.mcp_server/server.py:225-229, 941-945 — writer-queue stats only read the first active writer (for … : break), under-counting queue depth when multiple writers are active.hexus/pipeline/router.py:88-90 — log-compression header claims "showing {N} errors" while displaying at most 20.hexus/__init__.py:786 — prefetch()'s session_id param is accepted and never used; :410 vs 861-871 — turn_min_chars comment promises exceptions _is_noise doesn't implement.store.py:2305-2319 — consolidate_low_confidence_memories has LIMIT 20 with no ORDER BY (nondeterministic selection); store.py:1092-1099 — DEBUG_SEARCH_RAW builds a full-content list unconditionally (PII into logs when DEBUG on).store.py:492-517 — adapt_vector_precision runs DDL (ACCESS EXCLUSIVE, HNSW rebuild) on startup with no advisory lock; two processes starting together race it.
Suggested direction
Add an env-var reference table to the README/docs, document the webhook + long-text/rerank features, refresh stale docstrings/comments, and knock out the small cleanups (several are one-liners).
Filed from the 2026-07 codebase review.
Summary
Documentation gaps and a batch of low-severity polish items collected during the review.
Documentation gaps
HEXUS_WEBHOOK_URL/HEXUS_WEBHOOK_SECRET, payload schema, and a signature-verification recipe appear nowhere but a one-line ROADMAP mention. (Cross-ref the webhooks issue.)HEXUS_EMBED_LONG_TEXT_MODE,HEXUS_RERANK_LONG_DOC_MODE,HEXUS_EMBED_DEVICE,HEXUS_ENTITY_EXTRACTOR_ENABLED/_PATTERNS,HEXUS_DB_NAME/USER/PASS,MEMORY_PGVECTOR_DB_*,HEXUS_TRANSPORT,HEXUS_DEBUG,HEXUS_LOG_LEVEL,PG_TEST_*. The recently-added long-text chunking + long-doc rerank features have no user docs.compose.ymlcomments reference a non-existent/app/pgvector/migrations/path;get_config_schemasaysembed_urlrequired + "768-dim" (stale);bulk_upsert_mddocstring says 768-dim.Low-severity cleanup
mcp_server/cli.py:141—_redact_dsnonly redactspassword=keyword DSNs; a URI-form DSN (postgres://user:pass@host) logs the password in cleartext (cli.py:75-80).hexus/ccr/cache.py:26-29—CCRCache.set()raisesStopIterationwhenmaxsize<=0(uncaught, under a lock on the write path).mcp_server/server.py:431-453— cleanup daemon sleeps before its first run and has no jitter/backoff on repeated failure.mcp_server/server.py:225-229, 941-945— writer-queue stats only read the first active writer (for … : break), under-counting queue depth when multiple writers are active.hexus/pipeline/router.py:88-90— log-compression header claims "showing {N} errors" while displaying at most 20.hexus/__init__.py:786—prefetch()'ssession_idparam is accepted and never used;:410vs861-871—turn_min_charscomment promises exceptions_is_noisedoesn't implement.store.py:2305-2319—consolidate_low_confidence_memorieshasLIMIT 20with noORDER BY(nondeterministic selection);store.py:1092-1099—DEBUG_SEARCH_RAWbuilds a full-content list unconditionally (PII into logs when DEBUG on).store.py:492-517—adapt_vector_precisionruns DDL (ACCESS EXCLUSIVE, HNSW rebuild) on startup with no advisory lock; two processes starting together race it.Suggested direction
Add an env-var reference table to the README/docs, document the webhook + long-text/rerank features, refresh stale docstrings/comments, and knock out the small cleanups (several are one-liners).
Filed from the 2026-07 codebase review.