Update from code changes: document QiForge oracle latency knobs

build-an-oracle/reference/bundled-plugins/memory.mdx

@@ -51,14 +51,16 @@
 5. `relationships` — people and organizations mentioned in past conversations
 6. `recent` — notable things from the last few sessions
 
-**When it runs:** at agent-compile time, before turn 1. The fetcher runs once per session and caches the result for **5 minutes** (keyed by `sessionId`). Subsequent turns within the same session reuse the cached context — the Memory Engine is not called again unless the cache expires.
+**When it runs:** at agent-compile time, before turn 1. The fetcher caches the result for **5 minutes**, keyed by `roomId`. Subsequent turns within the same room reuse the cached context — including a fresh session for the same room — and the Memory Engine is not called again unless the cache expires.
 
 **What appears in the prompt:** if at least one slot is non-empty, the runtime inserts a `## What you know about the user` block into the system prompt containing all populated slots. If every slot is empty (no prior memory for this user), the block is omitted entirely.
 
+The block is deduped and budgeted before it reaches the model: entities are collapsed by name (keeping the richest summary), facts / episodes / communities are collapsed by normalized text so exact repeats across the six slots don't render 4-5 times, and per-entity and whole-block caps are applied. If either cap trims content, the block ends with a `_(More remembered — ask me to recall.)_` footer — trimmed detail is still reachable via the memory tool. No unique fact is dropped, and paraphrases survive.
+
 **Implication for oracle authors:** you do not need to instruct the agent to "look up the user's context" or "recall memory before responding" in `config.prompt.opening` or anywhere else. The context is already in the system prompt when the agent sees the user's first message. Adding such instructions is redundant and wastes tokens.
 
 <Note>
-The 5-minute session cache means very-recent memory writes (e.g. the agent just called `memory-engine__add_memory` in the same session) may not appear in the fetched context until the next session or cache expiry. This is intentional — the fetcher is optimised for read latency, not write-through consistency.
+The 5-minute room-keyed cache means very-recent memory writes (e.g. the agent just called `memory-engine__add_memory` in the current turn) may not appear in the fetched context until the cache expires. This is intentional — the fetcher is optimised for read latency, not write-through consistency.
 </Note>
 
 ## Adding global oracle knowledge
@@ -127,7 +129,7 @@
   </Step>
 
   <Step title="Drop in content and ask the oracle to save it as global knowledge">
     In the chat, drag and drop files (PDFs, markdown, text), paste links, or paste raw text — anything you want the oracle to know going forward. Then tell the oracle in plain language:
 
     > Save this into the global oracle knowledge.
 

build-an-oracle/reference/environment-variables.mdx

@@ -1,12 +1,12 @@
 ---
 title: "Environment variables"
 description: "Tier-0 (core) vars the runtime always requires, plus per-plugin vars contributed by each bundled plugin's configSchema."
 icon: "key"
 ---
 
 ## How env validation works
 
 The runtime composes one big Zod schema at boot: the **Tier-0 base schema** (always required) plus every loaded plugin's **`configSchema`**. `process.env` is validated against the merged schema. Missing required vars fail boot with `[boot-error] Plugin '<name>' env validation failed for '<field>'`.
 
 Disabling a plugin (via `features` or `autoDetect`) removes its env requirements automatically.
 
@@ -43,7 +43,7 @@
 | --- | --- | --- | --- |
 | `SQLITE_DATABASE_PATH` | string | — | Required. Must persist across restarts. |
 
 ### Blocksync / chain
 
 | Variable | Type | Default | Notes |
 | --- | --- | --- | --- |
@@ -71,8 +71,21 @@
 | `OPEN_ROUTER_API_KEY` | string | — | Required if `LLM_PROVIDER=openrouter`. |
 | `NEBIUS_API_KEY` | string | — | Required if `LLM_PROVIDER=nebius`. |
 
 Cross-field check (`validateLlmProviderKey`): the API key for the selected `LLM_PROVIDER` must be present — `OPEN_ROUTER_API_KEY` when `LLM_PROVIDER=openrouter` (the default), `NEBIUS_API_KEY` when `LLM_PROVIDER=nebius`. A missing key fails boot with a named-field error (e.g. `OPEN_ROUTER_API_KEY` / `NEBIUS_API_KEY`) rather than a generic upstream 401 at request time. The per-role model ids are hardcoded per provider — there is no env var to swap the main model id (use the `resolveModel` hook for that).
 
+### Latency tuning
+
+| Variable | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `MAIN_REASONING_EFFORT` | `'low' \| 'medium' \| 'high'` | `'medium'` | Extended-thinking effort for the **main** agent role only. Sub-agent reasoning is unchanged. Lower values reduce time-to-first-token at some cost to hard multi-step reasoning; higher values do the reverse. `'medium'` preserves current behaviour, so leaving this unset is safe. |
+
+<Note>
+Two related latency wins ship **always-on** — there is no env var to disable them:
+
+- **Request-path caches.** Three wins ship together. The per-user `SqliteSaver` is reused across the two build-time hook calls per turn instead of being rebuilt on each call. The agent builder reads prior build-time checkpoints via a light path that skips the message-history join (O(1) instead of O(history)). The Memory Engine `userContext` cache is keyed by `roomId` instead of `sessionId`, so a fresh session for the same room reuses the cached context.
+- **Memory-context compaction.** The `## What you know about the user` prompt block is deduped across all six memory buckets (entities collapsed by name, keeping the richest summary; facts / episodes / communities collapsed by normalized text — lowercase, punctuation stripped, whitespace collapsed) and bounded by fixed internal caps (per-entity summary and whole-block budget). When either cap trims content, the block ends with a `_(More remembered — ask me to recall.)_` footer so trimmed detail stays reachable via the memory tool. No unique fact is dropped; paraphrases survive.
+</Note>
+
 ### Misc
 
 | Variable | Type | Default | Notes |
@@ -105,7 +118,7 @@
 | `composio` | `COMPOSIO_BASE_URL` | No | Defaults to `https://composio.ixo.earth`. |
 | `sandbox` | `SANDBOX_MCP_URL` | Yes | Must be a valid URL. |
 | `skills` | `SKILLS_CAPSULES_BASE_URL` | No | URL. Defaults to `https://capsules.skills.ixo.earth`. |
 | `slack` | `SLACK_BOT_OAUTH_TOKEN` | Yes | Triggers autoDetect. |
 | `slack` | `SLACK_APP_TOKEN` | No | |
 | `slack` | `SLACK_USE_SOCKET_MODE` | No | Defaults to `'true'`. |
 | `slack` | `SLACK_MAX_RECONNECT_ATTEMPTS` | No | Coerced to number; default `10`. |
@@ -113,14 +126,14 @@
 | `credits` | `SUBSCRIPTION_URL` | No | URL. |
 | `credits` | `SUBSCRIPTION_ORACLE_MCP_URL` | No | URL. |
 | `credits` | `DISABLE_CREDITS` | No | Enum — exactly `'true'` or `'false'` (any other value fails env validation). `'true'` disables the credit-enforcement middleware; the plugin's `autoDetect` also excludes the whole plugin when `DISABLE_CREDITS=true`. |
 | `tasks` | `REDIS_URL` | Yes (when loaded) | Triggers autoDetect. |
 | `tasks` | `TASKS_MAX_PER_USER` | No | Coerced positive int; default `50`. Max scheduled tasks per user. |
 | `tasks` | `TASKS_RUN_LOCK_TTL_SEC` | No | Coerced positive int; default `600`. Per-run lock TTL (seconds). |
 | `tasks` | `TASKS_MIN_CRON_INTERVAL_SEC` | No | Coerced positive int; default `300`. Minimum allowed cron interval (seconds). |
 | `matrix-group-chats` | `CHANNEL_MEMORY_SYNC_INTERVAL_MS` | No | Coerced int, min `1000`; default `60000`. Debounce window between a write and the Matrix snapshot upload. |
 | `matrix-group-chats` | `GROUP_CHAT_ACTIVE_THREAD_TTL_MS` | No | Coerced int, min `60000`; default `1800000`. How long a thread stays "active with the bot" after a reply. |
 | `matrix-group-chats` | `GROUP_CHAT_REQUIRE_POWER_LEVEL` | No | Coerced int, min `0`; default `0`. Extra minimum power level the bot must have before posting (`0` = use the room default). |
 | `matrix-group-chats` | `GROUP_CHAT_ROOM_INFO_TTL_MS` | No | Coerced int, min `60000`; default `1800000`. How long roomInfo (membership, DM flag) stays cached. |
 
 ## Variables read but not owned