Skip to content

Local memory-plane setup: native/Docker/endpoint recommendations, honest degradation - #255

Merged
TheGreatAxios merged 3 commits into
mainfrom
cl-local-setup
Aug 21, 2026
Merged

TheGreatAxios merged 3 commits into
mainfrom
cl-local-setup

Conversation

@TheGreatAxios

Copy link
Copy Markdown
Contributor

Summary

  • bun run setup:memory (scripts/setup-memory.ts) probes this machine and recommends how to turn on the memory plane's embedding and reranking, in the platform's preferred order: native Ollama first, Docker for the pieces with no good native story (the TEI reranker, Gotenberg), a remote endpoint always available as a third option.
  • mountMemory now fails loudly at boot when only one of RERANK_BASE_URL/RERANK_MODEL is set, instead of a half-configured reranker surfacing as a confusing runtime failure later — matches the existing OAuth-pair pattern in apps/hub/src/config.ts.
  • .env.example, README.md, and docs/local-dev.md spell out what degrades and how visibly: no embedding configured means memory tools answer "not set up" and search finds nothing, and setting EMBED_BASE_URL later does not retroactively embed rows written before — no automatic backfill. No reranker means search still works, just less well-ordered.
  • Added GOTENBERG_URL to .env.example, matching the same native/Docker/endpoint story (Docker or remote endpoint; no native path).

What this deliberately does NOT change

  • The memory plane already shares DATABASE_URL with the rest of the hub (its own memory Postgres schema) — no separate KNOWLEDGE_DATABASE_URL was introduced; that would have contradicted the existing convention in apps/hub/src/memory-mount.ts.
  • No second setup path: this extends the existing @corbits/memory mount and .env.example rather than inventing a parallel one.

Test plan

  • bun test apps/hub/src/memory-mount.test.ts — 5 pass, 2 DB-gated skipped
  • bun test scripts/setup-memory.test.ts — 6 pass
  • bun run scripts/setup-memory.ts run manually against this machine (native Ollama found, Docker unreachable) — printed the expected native-embedding + endpoint-reranker recommendation and exited promptly

…ions

Covers the RERANK_BASE_URL/RERANK_MODEL boot-time pairing check and the
native/Docker/endpoint decision logic setup-memory.ts will implement.
mountMemory now fails loudly at boot when only one of RERANK_BASE_URL/
RERANK_MODEL is set, instead of letting a half-configured reranker surface
as a confusing runtime failure later.

bun run setup:memory (scripts/setup-memory.ts) recommends how to turn on
embedding and reranking for this machine: native Ollama first, Docker for
the reranker and Gotenberg (no good native story for either), a remote
endpoint always available as a third option.
Documents bun run setup:memory in the README and docs/local-dev.md,
spells out what degrades (and how visibly) with no embedding or no
reranker configured, and adds GOTENBERG_URL to .env.example alongside
the same native/Docker/endpoint story.
@TheGreatAxios
TheGreatAxios merged commit 7f0b84b into main Aug 21, 2026
2 checks passed
@TheGreatAxios
TheGreatAxios deleted the cl-local-setup branch August 25, 2026 15:29
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant