From 0a65415cdfbd15743608e239d97e6f75d9e97106 Mon Sep 17 00:00:00 2001 From: Roomote Date: Thu, 27 Aug 2026 03:21:58 +0000 Subject: [PATCH] docs: sync public guides with recent product changes --- .env.production.example | 7 ++- apps/docs/fast-sessions.mdx | 9 ++++ apps/docs/file-attachments.mdx | 4 +- apps/docs/memory.mdx | 51 ++++++++++++++----- apps/docs/models.mdx | 4 ++ apps/docs/providers/source-control/github.mdx | 14 +++-- apps/docs/self-hosting.mdx | 3 +- 7 files changed, 68 insertions(+), 24 deletions(-) diff --git a/.env.production.example b/.env.production.example index eed5f73b3..2d020e89a 100644 --- a/.env.production.example +++ b/.env.production.example @@ -149,15 +149,14 @@ DEFAULT_COMPUTE_PROVIDER=docker # serves, and the embedding pair is create-time: set everything BEFORE the # Brain's first boot. gbrain's defaults (text-embedding-3-small, 1536) name # models the bundled server does not serve, so the URLs alone are not a -# working configuration. The openrouter: prefix on the reranker routes it -# through this deployment's gateway, which strips the prefix before -# forwarding. +# working configuration. Self-run model names pass through unchanged, so +# they must exactly match the names served by the inference upstream. # R_BRAIN_EMBEDDINGS_UPSTREAM_URL=http://infinity:7997 # R_BRAIN_RERANK_UPSTREAM_URL=http://infinity:7997 # R_BRAIN_INFERENCE_UPSTREAM_API_KEY= # R_BRAIN_EMBEDDING_MODEL=BAAI/bge-m3 # R_BRAIN_EMBEDDING_DIMENSIONS=1024 -# R_BRAIN_RERANKER_MODEL=openrouter:BAAI/bge-reranker-v2-m3 +# R_BRAIN_RERANKER_MODEL=BAAI/bge-reranker-v2-m3 # R_GITHUB_APP_ID= # Raw GitHub App private-key PEM with newlines escaped as \n; do not base64 it. # R_GITHUB_APP_PRIVATE_KEY= diff --git a/apps/docs/fast-sessions.mdx b/apps/docs/fast-sessions.mdx index 9fbfd2b5e..6b5a49e3d 100644 --- a/apps/docs/fast-sessions.mdx +++ b/apps/docs/fast-sessions.mdx @@ -16,6 +16,10 @@ On the home page, open the workspace selector next to the prompt box and choose Roomote takes you straight to the session view, where the response streams in as it is produced. +You can attach images to a Fast prompt, including sending an image without +accompanying text. Other document attachments continue through normal Roomote +tasks. + Use Fast when you want an answer, a decision, or a delegation rather than a full sandbox run. Fast can still launch tasks on your behalf; delegated tasks appear in the transcript with links to their task pages. @@ -47,3 +51,8 @@ messages also continue the same session after Roomote verifies the tenant, installation, conversation, and linked user. Telegram currently uses the session view for Fast follow-ups because its inbound webhook route does not yet carry Fast session identity. + +For longer delegated work, Fast posts concise findings, blockers, meaningful +milestones, and requests for input, including a brief update after roughly ten +minutes without a message. New instructions for an active task are forwarded +before Fast posts its confirmation. diff --git a/apps/docs/file-attachments.mdx b/apps/docs/file-attachments.mdx index c45cff231..ea7ad2f50 100644 --- a/apps/docs/file-attachments.mdx +++ b/apps/docs/file-attachments.mdx @@ -5,7 +5,9 @@ description: Attach files that Roomote can read directly in chat and the web app --- Roomote can read supported file attachments from the web app and from chat -threads where you start or continue a Roomote task. +threads where you start or continue a Roomote task. Fast sessions in the web +app also accept images, with or without accompanying text; use a normal task for +the other file types below. Support varies by chat provider. The web app, Slack, and Telegram can read the formats below. Discord supports images and a smaller text and code subset, but diff --git a/apps/docs/memory.mdx b/apps/docs/memory.mdx index 71b23c927..1086acefe 100644 --- a/apps/docs/memory.mdx +++ b/apps/docs/memory.mdx @@ -89,8 +89,8 @@ embeddings and synthesis, and Roomote forwards them under the Memory key. Changing that key later takes effect on Memory's next request, with no redeploy. -OpenRouter and OpenAI both support Memory's embedding and synthesis calls, -but search reranking requires OpenRouter. +OpenRouter and OpenAI both support Memory's embedding and synthesis calls. +Search reranking requires OpenRouter or a configured self-run rerank upstream. Without a Memory key, Memory stays inert. Agents are not told it exists, and nothing is ingested. @@ -172,6 +172,10 @@ a slug it controls, after scrubbing credential-shaped strings. An agent can therefore contribute what only it knows without being able to touch any other page. +The save tool result shows the structured memory the agent submitted after +credential-shaped values are redacted, so task reviewers can inspect what was +recorded from the transcript. + Fast sessions use the same pipeline. Ask Fast to remember something — or state a durable preference, decision, or correction — and it saves the fact to the session's own memory entry, which the platform redacts and files just @@ -196,16 +200,17 @@ Three settings pick Memory's models: | ----------------------------- | ----------------- | --------------------------------- | --------------------- | | `R_BRAIN_MODEL` | Sourced synthesis | your provider's naming | any time | | `R_BRAIN_EMBEDDING_MODEL` | Semantic recall | a plain model id | before the first boot | -| `R_BRAIN_RERANKER_MODEL` | Search precision | `openrouter:/` | after a restart | +| `R_BRAIN_RERANKER_MODEL` | Search precision | provider or upstream model id | after a restart | Leave the first two unset and Memory uses OpenAI's `gpt-5.6-luna` and `text-embedding-3-small` through whichever provider you configured. The reranker defaults to OpenRouter's `voyageai/rerank-2.5-lite`. Set `R_BRAIN_RERANKER_MODEL` to choose another model from -OpenRouter's reranker catalog. Reranking requires an OpenRouter key; with only -OpenAI configured, gbrain keeps the unreranked results instead of failing the -search. +OpenRouter's reranker catalog, using the +`openrouter:/` format. Reranking requires an OpenRouter key; +with only OpenAI configured, gbrain keeps the unreranked results instead of +failing the search. The synthesis model is applied by Roomote when it forwards the call and passed to the provider as written, so use that provider's naming @@ -228,6 +233,26 @@ it takes effect on the next request with nothing to restart. the whole corpus with `gbrain migrate embeddings`. +### Self-run embeddings and reranking + +Production Compose deployments can keep Memory embeddings and reranking on +their own hardware while synthesis continues through the configured Memory +provider. Enable the `brain,local-inference` Compose profiles and configure: + +```sh +R_BRAIN_EMBEDDINGS_UPSTREAM_URL=http://infinity:7997 +R_BRAIN_RERANK_UPSTREAM_URL=http://infinity:7997 +R_BRAIN_EMBEDDING_MODEL=BAAI/bge-m3 +R_BRAIN_EMBEDDING_DIMENSIONS=1024 +R_BRAIN_RERANKER_MODEL=BAAI/bge-reranker-v2-m3 +``` + +The bundled service defaults to these multilingual models so recall can cross +language boundaries. Set the embedding model and dimensions before Memory's +first boot. Self-run model names pass through unchanged, so use the exact ids +served by the upstream. Set `R_BRAIN_INFERENCE_UPSTREAM_API_KEY` as well when +the upstream requires bearer authentication. + ## If you turned Memory on later Memory that first boots without a provider key is created with semantic @@ -243,13 +268,13 @@ matching on keywords alone. ## Operating it -- **Back up the Memory volume.** The Railway template schedules daily and - weekly backups for it. On other platforms, include `/data/brain` in the - deployment's normal volume backups. That directory is the Markdown corpus, - including pages produced by nightly synthesis. Postgres holds the searchable - index, extracted facts, and durable maintenance jobs; keeping it in the - normal database backup makes restores faster, but it is not the only copy of - the source pages. +- **Back up both Memory stores together.** `roomote backup` includes the + `gbrain_data` volume and the `gbrain` Postgres database. The volume holds the + Markdown corpus, while the database holds the searchable index, extracted + facts, and durable maintenance jobs. For platform-managed backups, preserve + both at the same consistency point; restoring only the volume can leave its + storage-layout marker paired with an empty index that is not rebuilt + automatically. - **Losing Memory is recoverable but not free.** If the volume or isolated `gbrain` database is recreated, Roomote re-registers its clients, resets its ingestion checkpoints, and backfills task history and integration sources. diff --git a/apps/docs/models.mdx b/apps/docs/models.mdx index 067c749fb..eb31cf246 100644 --- a/apps/docs/models.mdx +++ b/apps/docs/models.mdx @@ -117,6 +117,10 @@ off, and they cannot be deleted while their provider stays connected — turn a model off to stop using it. To go beyond the recommended set, add any model by its slug from the add-model field. +The current curated GLM set includes GLM 5.3 and GLM 5.3 Flash through +OpenRouter, Vercel AI Gateway, Requesty, OpenCode Go, Z.AI, and Z.AI Coding +Plan. New direct Z.AI connections default to GLM 5.3. + ### Recommended default models Providers also carry recommended defaults for the model roles below — for diff --git a/apps/docs/providers/source-control/github.mdx b/apps/docs/providers/source-control/github.mdx index 38f668e17..db9c97ba4 100644 --- a/apps/docs/providers/source-control/github.mdx +++ b/apps/docs/providers/source-control/github.mdx @@ -219,11 +219,15 @@ Once the app is installed and an environment maps the repository: Issue mentions use the environment mapped to the repository. Map the repository to an environment before mentioning Roomote on issues. -When a task delegated from a Fast session in Slack or Discord opens a pull -request, actionable review feedback returns to that same session. Use -**Resolve these issues** to address the current feedback, **Auto-resolve on this -PR** to handle later actionable feedback automatically, or **Dismiss** to take -no action. +When a task delegated from a Fast session opens a pull request, actionable +review feedback returns to that same session on the web or in Slack, Discord, +Microsoft Teams, or Telegram. Slack, Discord, and Telegram offer **Resolve +these issues** to address the current feedback, **Auto-resolve on this PR** to +handle later actionable feedback automatically, and **Dismiss** to take no +action; Teams receives the feedback without those action controls. Handled or +superseded controls are retired so only current feedback remains actionable. If +Roomote's final review summary is delayed, provisional inline findings are +delivered after five minutes rather than being hidden indefinitely. Failed GitHub checks also return to every Roomote task linked to the pull request and to the conversation that started the work. Roomote consolidates a diff --git a/apps/docs/self-hosting.mdx b/apps/docs/self-hosting.mdx index 678e0ff43..4c13f58e3 100644 --- a/apps/docs/self-hosting.mdx +++ b/apps/docs/self-hosting.mdx @@ -96,7 +96,8 @@ roomote logs # tail service logs `roomote backup` prompts for a passphrase and writes a versioned `.roomote` bundle under `/opt/roomote/backups`. The bundle contains PostgreSQL, the deployment configuration and encryption/signing keys, local MinIO artifacts, -schema metadata, and the exact deployed image identities. Store the passphrase +the Memory Markdown volume and index database when Memory is enabled, schema +metadata, and the exact deployed image identities. Store the passphrase separately in your secret manager; the backup cannot be restored without it. Use `roomote backup --include-redis` when queued work, BullMQ schedules,