Repository navigation
Milvus + local-Postgres documentation gaps from tire-kick session #1238
Description
Docs follow-ups from the Milvus tire-kick session (#1235)
Verified gaps in docs/semantic-search.md (and adjacent), all observed hands-on:
- No local-Postgres user quickstart. Everything Postgres in the repo is framed as
test infrastructure; a user enabling Milvus must reverse-engineer
docker-compose-postgres.yml+BASIC_MEMORY_DATABASE_BACKEND/DATABASE_URLfrom the
justfile. One short "run Postgres locally" section would unblock the whole Milvus path. - Fresh-switch step is undocumented: flipping
semantic_vector_indexrequires
bm reindex --embeddings(incremental suffices — verified: 8,689 chunks re-owned in
~3 min); the docs only mention reindex in the migration-cleanup narrative. - The pre-reindex degraded window is undocumented (see Vector search silently degrades when configured index has no ready manifest rows #1236): vector returns
nothing and hybrid quietly serves FTS-only until the reindex runs. - Milvus Lite
.dbreality: pymilvus hard-requires the.dbsuffix and an existing
parent directory, and what it creates is a directory tree (collections/, databases/,
LOCK), not a file. Errors for bad shapes are raw pymilvus exceptions with no pointer to
themilvus_urisetting. -
milvus_databaseis ignored by Milvus Lite (no named-database support); it's
passed unconditionally asdb_name. - Stale rows after pgvector→milvus: the old pgvector projection
(search_vector_embeddings, 8,689 rows in the session) remains on disk indefinitely;
document the manual cleanup or note the disk cost until a cleanup command exists.
Positive findings worth stating in docs while editing: identical vector rankings and
scores (4-decimal agreement) across sqlite-vec/pgvector/Milvus Lite on a 222-entity
corpus; dimension-mismatch refusal message is excellent; missing-extra error is excellent;
30s timeout honored on unreachable servers; collections reload across processes (#1185).
Activity
claude commentedon Aug 11, 2026
Claude finished @phernandez's task in 35s —— View job
Triage
Type: Documentation — this is a docs-gap report, not a code defect. All items are follow-ups from hands-on Milvus/local-Postgres testing during the #1235 tire-kick session, targeting
docs/semantic-search.mdand adjacent pages.Component: None of the repo-labeled components apply directly (not Cloud-specific). In prose: touches semantic search / vector index docs, Milvus Lite (
milvus_uri,milvus_database), and local Postgres setup (docker-compose-postgres.yml,BASIC_MEMORY_DATABASE_BACKEND/DATABASE_URL).Priority: Medium. Nothing is broken — these are usability/onboarding gaps that would block or confuse a user enabling Milvus or local Postgres, particularly the missing quickstart and the undocumented degraded-search window (which overlaps with the bug in #1236).
Complexity: Simple–Medium. Most items are additive documentation (a local-Postgres quickstart section, a
bm reindex --embeddingsnote, Milvus Lite.dbpath/directory-shape caveats, a note thatmilvus_databaseis a no-op for Milvus Lite, and either a stale pgvector-rows cleanup note or pointer to a future cleanup command). No code changes required for the checklist as written.Duplicates: None found. This is a distinct, docs-scoped sub-issue of the #1235 tracking issue, and calls out #1236 (degraded-search window) as the related root-cause bug rather than duplicating it.
No missing-info follow-ups needed — the report already includes concrete verification detail (chunk counts, timings, exact behaviors) for each gap.
phernandez commentedon Aug 12, 2026
Docs-site coverage for every item on this list has landed on the
docs/v0.23branch of docs.basicmemory.com (pushed, NOT merged — main auto-deploys, so it holds until release day): local-Postgres setup inside the new Milvus vector-index guide, the fresh-switchbm reindex --embeddingsrequirement + the degraded pre-reindex window,.db-is-a-directory and parent-dir requirements, the Litemilvus_databasecaveat, stale pgvector row cost, plus the full 28-key configuration reference and a v0.23 upgrade guide. The main-repodocs/semantic-search.mdtuning/table updates went in via #1245. Remaining before this closes: merge the docs branch at release. Site build +npm run check:docsboth pass on the branch.phernandez commentedon Aug 24, 2026
Closing: the v0.23 docs shipped with the release — Milvus + local-Postgres guide, 28-key config reference, upgrade guide with known issues, retrieval inspector reference, Team WebDAV corrections. Merged via docs.basicmemory.com#42 and live in production (verified: /whats-new/v0-23 serving).