\n\n## User-requested home automations for Node-RED\n\nCerebrum Ultimate turns occupants' requests into editable JavaScript routines. It retrieves installation details, asks focused questions when needed and runs schedules and event handlers locally. KNX Ultimate, Home Assistant, HUE, Matter, UniFi Protect and TTS Ultimate are optional integrations. It does not infer household habits or review the house in the background.\n\n \n\n[![NPM version][npm-version-image]][npm-url]\n[![Node.js version][node-version-image]][npm-url]\n[![Node-RED Flow Library][flows-image]][flows-url]\n[![NPM downloads per month][npm-downloads-month-image]][npm-url]\n[![NPM downloads total][npm-downloads-total-image]][npm-url]\n[![MIT License][license-image]][license-url]\n[![JavaScript Style Guide][standard-image]][standard-url]\n[![YouTube][youtube-image]][youtube-url]\n\n
\n\n## IMPORTANT NOTICE\n\n> When Cerebrum Ultimate is set to use cloud AI Models, the AI Models will receive data that are read from your local Node-RED. If you wish to maintain all data private, please use a local provider, like Ollama, LM Studio etc., that are natively supported by Cerebrum Ultimate.\n\n## DEV POWERED BY GPT6-ASTRA\n\n> The development of Cerebrum Ultimate is enhanced by OpenAI GPT6-ASTRA.\n\n## What you can do\n\n- Talk to your smart home in natural language.\n- Ask for summaries, current states and recent events.\n- Describe a routine and clarify missing details in conversation.\n- Review, edit, pause and resume the resulting JavaScript.\n- Define explicit conditions for notifications or permitted actions.\n- Create reminders and scheduled checks.\n- Use cameras and voice when compatible nodes are available.\n- Generate reviewable Node-RED flows with the **Node-RED Flow Builder**.\n- Write and revise JavaScript from a prompt in **Cerebrum Function**, based on the native Node-RED Function.\n- Back up and restore the Cerebrum configuration from the Web interface.\n\n## Cerebrum Function (BETA)\n\n**Cerebrum Function** combines the native Node-RED Function editor and runtime with prompt-based JavaScript authoring. It preserves **On Start**, **On Message**, **On Stop**, outputs, context, timers, async messaging, timeout, the Function library and configured external modules. The original Function node remains available.\n\n1. Configure and deploy a **Cerebrum** node with its AI provider and model enabled.\n2. Drag **cerebrum function (BETA)** from the **function** palette category. In **Setup**, check the selected Cerebrum and configure outputs, timeout or modules as needed. The first deployed Cerebrum with AI enabled is selected automatically; saved selections are preserved.\n3. Open the **Cerebrum** tab, enter your request and optionally add an example `msg` JSON object. For example: “Double the numeric payload, preserving the other message fields,” with `{\"payload\": 21}`. The selected Cerebrum supplies its AI configuration and authorized ETS catalog automatically.\n4. Click **Generate proposal**. An animated icon shows progress; the request and example fields are hidden until generation finishes or is cancelled. Review the proposed code using the code-section selector. Only the proposal is displayed, initially showing the first changed section.\n5. Click the light green **Apply to editors** button to insert the proposal and open the corresponding code tab. The light red **Discard proposal** button removes the proposal. Use **Done** and **Deploy** to activate accepted code.\n\nTo revise a Function, reopen it and describe the change in the **Cerebrum** tab. Existing code is supplied to the model, including the lifecycle sections. Proposals are syntax-checked without execution and cannot overwrite code, outputs or module selections changed during generation. Check wiring if the proposed output count changes. **Cancel generation** stops waiting for a proposal; a model request already sent may still finish. **Cancel** in the node dialog discards editor changes.\n\nIncoming messages execute the saved JavaScript locally with **no AI call**. You can also write code manually without an AI-enabled Cerebrum. Data access through `cerebrum` requires the selected Cerebrum to be deployed, but does not require its model to be enabled. Device operations use the downstream nodes wired into the flow. Prompts and example messages are saved with the flow; complete authoring requests and model responses are retained in Cerebrum's common archive.\n\nIn **On Message**, type `cerebrum.` to discover the read-only API. Inside `cerebrum.knx.get(\"…\")` or `cerebrum.knx.state(\"…\")`, completion shows authorized group addresses with names, DPTs and read-only flags. Search by address or name. State keys and saved automation names are suggested in their respective `get` calls. Completion works in Monaco and Ace, including the expanded editor. Use the refresh icon next to the expand button to reload the catalog after imports or configuration changes.\n\n| API | Returned data |\n| --- | --- |\n| `cerebrum.available`, `cerebrum.info()` | Availability and identity of the selected Cerebrum |\n| `cerebrum.knx.list()`, `.find(query)`, `.get(address)` | Authorized group addresses with name, DPT, area, aliases, read-only flag and observed state |\n| `cerebrum.knx.state(address)` | Latest observed state for an authorized KNX address, or `null` |\n| `cerebrum.states.list()`, `.get(key)` | Observed integration states, including keys such as `knx:1/2/3` |\n| `cerebrum.functions.list()`, `.get(name)` | Managed JavaScript automation metadata; `get` also includes its `code` |\n\nChoose an address from your catalog and use its observed value:\n\n```javascript\nif (!cerebrum.available) return null;\nconst sensor = cerebrum.knx.get(\"1/2/3\"); // Replace using your catalog suggestions.\nif (!sensor?.state?.fresh) return null;\nmsg.payload = sensor.state.value;\nmsg.topic = sensor.name;\nreturn msg;\n```\n\nThe API is synchronous, returns independent copies and is also available in **On Start** and **On Stop**. It follows the selected Cerebrum across redeployments and access changes. Methods throw when Cerebrum is unavailable; unknown or unauthorized objects return `null`. Observed states include `verifiedAt`, `ageMs` and `fresh`: reading does not query the bus or guarantee the current physical state. `cerebrum.functions` inspects saved automations without running them.\n\nFor a working Inject → Function → Debug flow, import [16 - Cerebrum Function](examples/16%20-%20Cerebrum%20Function.json). It doubles a payload of `21` to `42` without requiring AI at runtime.\n\nBased on the official [Node-RED 5.0.7 Function](https://github.com/node-red/node-red/tree/5.0.7/packages/node_modules/@node-red/nodes/core/function), with [upstream attribution and license](nodes/vendor/node-red-function/README.md). Supported Node-RED versions start at 3.1.1; `node.linkcall` requires Node-RED 5 or later.\n\n## Routine authoring and working context\n\nThe **Cerebrum** Web menu offers five sections: Conversation, JavaScript automations, Saved instructions, Device data and Operations. The neural map and sidebar use the same definitions; decorative connections are navigation, not live AI activity.\n\nDescribe the behavior you want in chat. Cerebrum retrieves exact device identities and capabilities locally. When a material detail is missing, it asks a specific question and waits for your answer before creating source or issuing actions. The original request and answers remain in the shared conversation memory across restarts. Clear requests proceed directly. The result is a real `.js` file with its actual activation status, visible in **JavaScript automations**.\n\nCurrent device states, semantic device bindings and factual observations remain available. Similar names or rooms alone never merge devices, and a state change does not establish who caused it or what an occupant prefers. Habit inference, correlated behavioral episodes, comfort goals, proactive research and periodic LLM house reviews have been retired. Their old files remain archival data; restart and restore do not reactivate them.\n\nIn the node editor, **AI Assistant → Maximum managed context (KB)** controls the application context ceiling. Leave it at `0` to use the selected model's known or detected maximum automatically; enter a positive value to set a lower ceiling. For an otherwise unknown OpenAI-compatible model, the value declares the endpoint's effective context limit. Cerebrum never uses it to exceed a known or locally detected physical model window.\n\n### Shared conversation and situational context\n\nWeb chat and Telegram use the same household memory. Every incoming message and outgoing reply is written in full to `cerebrumultimatestorage/cerebrum/memory/shared/cerebrum-memory.jsonl`, together with KNX and integration observations, model/tool results, catalog records and explicit saved context. Writes are durably batched; records expire according to the configured history retention. It is included as a streamed file in full ZIP backups.\n\nRecent conversations and explicit memories are shared across channels. The model can search the complete archive and read individual records, including messages outside the recent prompt. V3 chat records still present on disk migrate before the working view is bounded; records already discarded by older versions cannot be reconstructed. The editable `.knxctx` V4 file is a bounded working view, not the complete archive. Clearing one chat or reinitializing that view does not erase the historical archive.\n\nAn explicit request to save actuator positions uses shared memory, with the scene name, observed values, device references and time. Restoring a scene consults current ETS details and follows the configured command validation and confirmation. ETS, shared-memory and KNX-history lookups have no fixed number of useful passes. The model can follow search → related objects → exact details, paginate results and revisit earlier evidence; unchanged query cycles terminate with an explicit uncertainty prompt. Working context is sized to the active model window, and ETS details are no longer capped at 24 acquired objects. Complete query results are recorded in the common file archive. New requests in the same chat and node shutdown cancel ongoing reasoning between calls. Historical values and assistant replies are not treated as live device state or proof of execution.\n\nLocal **LM Studio** and **Ollama** chat uses native tool calls and ordinary final text, with a compact working context and history retrieved when needed. The default reasoning selection now requests reasoning off for local conversation; selecting an explicit effort preserves it. Models that explicitly reject native tools use a compact JSON fallback. See [local chat design and reproducible LAN benchmark](docs/local-llm-chat.md). Restart Node-RED after installing the updated package; no memory migration is required.\n\nCurrent KNX capabilities are supplied separately from conversation history: gateway/link state, catalog availability, selected readable/writable objects and the configured command policy. Missing ETS details trigger retrieval; an empty or unconfigured selection is reported as a node configuration issue. Earlier chat claims about unavailable commands do not override newly saved ETS access.\n\nZIP backups include the current saved GA selection and read-only permissions in both the Cerebrum configuration file and the portable Node-RED flow. Restoring maps them to the destination node and refreshes the ETS selection screen immediately. Permissions remain on disk across node/gateway changes and restarts, even while the destination catalog is unavailable; only matching catalog objects can be used. Older backups recover access from their source flow when the configuration has no selection. If neither contains it, existing destination permissions are preserved; an explicitly empty selection remains empty.\n\n### Persistence across Node-RED restarts\n\nCerebrum restores conversation memory, current device data and user-created routines from files. No Node-RED context-storage setting is required.\n\n| File under `cerebrumultimatestorage/cerebrum/` | Retained data |\n| --- | --- |\n| `automations//*.js` and the adjacent runtime JSON | Authoritative routine source, statuses, schedules, timers and durable script memory. |\n| `memory/cerebrum-runtime-state-NODEID.json` | Model context limits, Web reservations and explicit camera-watch cooldowns. |\n| `memory/cerebrum-chat-context.knxctx` | Shared saved instructions, recent conversations and camera watches. |\n| `memory/cerebrum-home-memory.md` | Current device state, factual observations, device metadata and existing legacy records. |\n| `operations/`, `history/`, `adapter-history/`, `memory/shared/` | Retained activity and conversation archives. |\n\nChat memory saves promptly; frequent device updates share a fixed save deadline. Shutdown waits for pending archive writes. Atomic replacement protects checkpoints. Old habit-learning checkpoints, world models and observation journals are included in backups when present, but no longer produced, replayed or used to initiate work.\n\n### Saved instructions and device data\n\n**AI Education** remains an explicit user-managed file at `cerebrumultimatestorage/cerebrum/config/cerebrum-ai-education-.md`. Press **Done** in the node editor to save it; **Cancel** discards edits. Existing flow text migrates only if the file is absent. Saving education does not generate routines automatically. Ask in chat to create a routine from specific saved instructions so missing details can be clarified in that conversation.\n\n| View | What you can inspect |\n| --- | --- |\n| Conversation | Requests, clarification questions and answers. |\n| JavaScript automations | Actual routines, source, status, last execution and editing/pause/resume/delete controls. |\n| Saved instructions | Explicit saved preferences, conversations and camera watches. |\n| Device data | Latest observed device states. Historical observations remain in the archives and advanced files. |\n| Cerebrum Operations | Retained KNX, model and tool activity with recorded outcomes. |\n\nRead-only logs keep one record per line. Advanced file editors and complete backups remain available, including legacy records. The old `world-model/:nodeId` read-only API now projects current observed entities only; inferred collections are empty and autonomous status is disabled. Reading these views never starts model work.\n\n## Example flows\n\nThe package includes 15 ready-to-import flows for conversations, summaries, independent sessions, reminders, Web research, Home Assistant, Telegram, TTS and supervised KNX use. Cerebrum reads RED only to inventory compatible installed `-ultimate` packages; it never scans deployed flows and does not attach a global message observer.\n\nOpen **Node-RED → Menu → Import → Examples → node-red-contrib-cerebrum-ultimate** and start with **01 - First Conversation**. Each flow contains a short instruction directly in the workspace; integrations that require another package are clearly marked and never include credentials or gateway addresses.\n\n## Messages from Node-RED flows\n\nTo tell Cerebrum about an important household event while a Telegram adapter is selected, connect a Function node to Cerebrum's input and send:\n\n```javascript\nmsg.bypassAdapter = { payload: 'The garage thermal camera is reporting a fault.' };\nreturn msg;\n```\n\n`msg.bypassAdapter.payload` must be a non-empty string. It bypasses the input adapter and is recorded as a household report, with its source, in the shared archive. The AI evaluates its importance using the household context and can notify you about significant faults or other important events. Routine updates and repeated reports can remain silent. With AI disabled, the report is archived without an assessment.\n\nNotifications leave output 3 (**AI Assistant**). With the **windkh** or **RedBot Telegram** preset selected, they use the last chat ID received from a real Telegram message by this Cerebrum node; that destination survives restarts. Send the bot an initial message and connect output 3 to the corresponding Telegram sender. Without a known Telegram destination, an important alert still leaves output 3 as plain text in `msg.payload`, with `msg.cerebrum.telegramStatus = \"no_recipient\"`; Cerebrum does not invent a recipient. Without a Telegram preset, alerts use plain text on output 3.\n\nThese reports provide information, not permission to issue commands or control devices. Ordinary Telegram conversations continue to use the selected adapter.\n\n## Compatible nodes detected\n\nOpen the Cerebrum node and use **Compatible nodes detected**. Cerebrum shows the integrations available in the current Node-RED project.\n\nFor integrations such as KNX Ultimate and UniFi Protect, the same field lets you select an existing configuration, edit it or create a new one. Nothing is required if you do not use that integration.\n\n## KNX: ETS Access, Areas, Tests and Test Results\n\nThe KNX test workspace is designed for commissioning and troubleshooting. It helps answer practical questions such as:\n\n- Is the correct command group address being used?\n- Does the actuator publish its new status after a command?\n- Does the status address answer an explicit read request?\n- Does the returned value match the requested value?\n\nThis is useful when checking a new installation, after changing an ETS project, or when a light, shutter, HVAC function or other actuator does not behave as expected.\n\nInstall KNX Ultimate, select or create its gateway under **Compatible nodes detected**, and make sure the gateway contains your ETS group addresses. Cerebrum then provides this guided path:\n\n`ETS Access → Areas → Test plans → Test Results`\n\nOpen **KNX → ETS Access** in the Cerebrum Web UI to choose the group addresses Cerebrum may use. Selected addresses are readable; selected addresses not marked **Read only** are writable after the normal local validation and, when enabled, user confirmation. Existing selections stored in the Node-RED flow are migrated automatically when this page is first saved.\n\n### 1. Areas\n\nAn area limits the test to a clear part of the installation, such as the living room, the first floor, the lighting system or the HVAC system. This makes it easier to select the correct addresses and avoids testing unrelated devices.\n\nOpen **KNX → Areas** to:\n\n- Select an area suggested from the ETS structure, or create one.\n- Give it a clear name and choose the group addresses that belong to it.\n- If AI is enabled, Cerebrum can help suggest the most relevant addresses.\n\nAn area must contain at least one group address before it can be used in a test.\n\n### 2. Tests\n\nCerebrum can perform two kinds of checks.\n\n#### Read-only diagnosis\n\nA read-only diagnosis does not operate any actuator. It examines the KNX traffic already observed for the selected area and reports:\n\n- which group addresses have recently been active;\n- which addresses have remained silent;\n- whether recent anomalies belong to that area;\n- whether the observed activity matches the selected diagnostic profile.\n\nThis is the safest first check. A silent address is not automatically faulty: the related device may simply have had no reason to transmit during the observation period.\n\n#### Active functional test\n\nAn active test checks the complete command-and-feedback path. For each configured step, Cerebrum can:\n\n1. Send the requested value to the command address.\n2. Wait for the status address to publish a spontaneous update.\n3. Read the same status address and wait for its response.\n4. Compare both feedback values with the value that was expected.\n\nIn KNX terms, this means sending a command telegram, observing the status `GroupValue_Write`, then sending a `GroupValue_Read` and checking the returned `GroupValue_Response`.\n\nFor example, when testing a living-room light, Cerebrum sends **On** to its command address, waits for the status address to report **On**, reads that status once more and checks that the response is still **On**. This verifies much more than simply seeing the light switch.\n\nThese two feedback checks help distinguish common problems. For example, an actuator may update its status spontaneously but not answer reads, answer reads but not publish changes, return an unexpected value, or provide no feedback at all.\n\nOpen **KNX → Tests**, select an area and start a new plan. Standard templates are available for lights, shading, HVAC and the main actuators. Before running the test you can:\n\n- review and change every command and status address;\n- check the DPT (KNX data type) and expected value;\n- add pauses between operations;\n- save the plan for later use;\n- run it once or repeat it until you stop it.\n\n> Active tests send real telegrams to the KNX bus. Cerebrum always shows a confirmation before starting: review the plan and make sure the installation is safe to operate.\n\nThe tests verify KNX communication and configured feedback. They do not replace electrical, mechanical or on-site safety checks.\n\n### 3. Test Results\n\nOpen **KNX → Test Results** to follow a running test or inspect a saved report:\n\n- **Pass** means all configured checks for that step succeeded.\n- **Warning** means a possible issue needs attention; in an active test, this usually means that only one of the two feedback checks succeeded.\n- **Fail** means feedback was missing, arrived too late or contained a different value.\n\nIf a step has no status address, Cerebrum can confirm only that the command telegram was sent. A successful write-only step does **not** prove that the physical actuator moved or that the load switched.\n\nEach report contains the command used, the received feedback, timing details and practical suggestions. You can reopen the source plan, delete an old result or export the report as a PDF for commissioning records.\n\n## Home Assistant\n\nConnect Cerebrum's dedicated **Home Assistant** output to a Home Assistant `ha-api` node, then return the API output to Cerebrum's input:\n\n```text\nCerebrum output 6 (Home Assistant) → API (ha-api) → Cerebrum input\n```\n\nSelect the Home Assistant server in `ha-api` and deploy the flow. If Cerebrum reports a missing connection, check the output 6 → `ha-api` → Cerebrum input wiring. Cerebrum correlates API responses internally; no additional bridge node is required.\n\n## Safety and privacy\n\nCerebrum creates routines from explicit user intent and keeps observation separate from execution authority. Device writes require the existing integration command permissions. KNX group addresses marked read-only cannot receive writes.\n\nHome data used in chat or background reasoning is sent to the configured AI provider. For a fully local setup, use a compatible local provider such as Ollama or LM Studio.\n\n### Autonomous KNX history queries\n\nThe conversational model has a read-only `historyActions` tool for the daily KNX archive. It can autonomously query a precise ISO 8601 time range, filter by destination or source address, event type, DPT and free text, optionally request raw hex, and receive both decoded telegrams and aggregate counts in a following reasoning pass. Empty dates query the latest 20 minutes. Requests are clamped to the configured archive retention (30 days by default) and never expose a general filesystem API.\n\nEach pass accepts up to two queries with at most 200 returned telegrams per query, and the model can continue with additional, narrower history queries whenever the evidence requires them. There is no fixed number of history passes; unchanged query cycles trigger an uncertainty prompt. Results are bounded to the active model context and, like other prompt data, are sent to the configured AI provider.\n\n### Recorded camera events and snapshots\n\nCamera providers may expose `queryEvents()` and `takeEventSnapshot()` in addition to the existing live-event and current-snapshot operations. During an authorized chat, Cerebrum can search recorded events by camera, event/object type and ISO 8601 range, inspect an explicit continuation offset when more controller pages exist, then request the JPEG attached to an exact returned event. A request such as “show me the snapshot of the last detected movement” therefore performs recorded-event query → exact event selection → event snapshot; it never substitutes a current camera image.\n\nWith `node-red-contrib-unifi-ultimate`, enter a dedicated local UniFi OS username and password directly below **Protect controller** in each Cerebrum node. Node-RED keeps them as that Cerebrum node's credentials. For an on-demand recorded-event query or exact event snapshot, Cerebrum passes them separately to the selected provider for that operation only; the UniFi config node neither stores nor returns them. The official Protect Integration API key continues to support live events and current snapshots. Cerebrum receives only normalized event evidence and image bytes; cookies, private endpoints and raw controller responses remain inside the provider. Other camera packages can implement the same vendor-neutral methods.\n\nUniFi Protect remains the source of truth for this high-volume stream. Cerebrum queries recorded events only on demand and keeps each returned page only for the active reasoning turn. It does not copy unsolicited Protect messages into adapter history, observations, episodes or world memory; it also omits raw event payloads, queried event pages and JPEG bytes from conversation archives, prompt-debug files and backups. Live camera watches and local automations still consume the provider's bounded in-memory event stream.\n\n### Local JavaScript automations\n\nModel calls are allowed only during actual user chat or an explicit `assistant.run` inside a user-requested JavaScript routine. Incoming events, saved education, startup and open Web pages do not authorize model work. Legacy interval settings are ignored, including after restart and backup restore.\n\nAsk Cerebrum in chat what to automate, or use **Create a routine in chat** from **JavaScript automations**. It retrieves installation details, asks focused questions about unresolved behavior and waits before authoring. Saving AI Education does not queue another model request. The resulting function appears with its purpose, active/paused/error status and last invocation; no example files are created automatically.\n\nOpen a function to inspect, edit or download its JavaScript. **Pause** stops future callbacks and cancels pending named timers; **Resume** validates the current source and permissions. Saving an active function applies the new code; saving a paused function leaves it paused. **Delete automation** stops the function, removes its `.js` file and retains its source in the common archive. Background planning cannot overwrite, resume or recreate an existing/deleted filename. Unsaved edits survive section navigation, and stale saves are rejected. An external source edit stops execution until you review and resume it.\n\nSources live under `cerebrumultimatestorage/cerebrum/automations//`. A single `.runtime.json` file beside that directory holds statuses, revisions, durable memory and timer checkpoints. Source revisions and execution records are retained in shared memory; ZIP backups include both sources and runtime metadata. Restored functions start paused for review. Existing local files are retained and start paused when no runtime registration exists.\n\nFunctions run in a supervised QuickJS WebAssembly worker without access to Node, RED, files or the network. Supported triggers are KNX/integration state changes, incoming plugin events, daily/interval/one-time schedules and named timers. Effects are notifications and currently supported KNX/HA writes. Current command permissions, ETS selection, read-only access and DPT checks still apply; per-command confirmation prevents unattended writes. HA writes currently support lights, switches and input booleans. The interpreter has CPU, memory and output limits and stops a function on an error. Missed jobs are skipped, and uncertain deliveries are not automatically retried.\n\nDeterministic local executions do not invoke the LLM. A function can explicitly use `assistant.run` at its deadline for fresh Web research, sensor reads and a generated reply or TTS announcement. A daily weather announcement therefore has a visible `.js` schedule and uses the model only when the task fires. `speak` sends prepared text directly to the existing TTS output. The model is also used to author/revise functions; the authoring API is only added to its context when needed. Legacy semantic schedules are preserved for inspection/cancellation but suspended; create their replacements as real `.js` functions. After updating this package, restart Node-RED and reload the Web page to load the new runtime and assets.\n\n### Isolated installed-package inventory\n\nThe advanced **Allow the AI to inspect the local Node-RED runtime with JavaScript** option is off by default. Its scope is now deliberately narrower than its legacy label: Cerebrum calls only `RED.nodes.getNodeList()` and retains only compatible installed `-ultimate` node sets and types. Dedicated integration registries separately contribute sanitized provider readiness and supported operations. Deployed nodes, wiring, tabs, Function source and messages are never inspected. When enabled, model-generated JavaScript can query only the immutable copies exposed through `runtime`, `RED.nodes.listTypes()`, `RED.nodes.listNodeSets()`, `RED.integrations`, `question` and `sessionId`; `node`, `eachNode`, `getNode` and `getType` are unavailable.\n\nThe JavaScript runs with a short timeout and without host references. Its input and bounded result are still model context, so prefer a local model when even the sanitized runtime inventory must remain local. The option is intended for ad-hoc filtering and correlation of the capability snapshot; ordinary integration discovery is added to Cerebrum's context automatically and does not require model-generated JavaScript.\n\nExecution is synchronous and bounded to one action per model pass, at most two execution passes, 12,000 source characters, 500 ms per script and a 64 KB serialized result. These limits protect responsiveness and context size; the available `RED` methods are restricted to the two inventory-copy methods listed above.\n\n## Local memory and backup\n\nCerebrum saves conversations, explicit instructions and device data automatically. Requested routines remain available in **JavaScript automations** across restarts. **Settings → Import / Export** provides an easy way to create and restore backups.\n\nSet **History retention (days)** in the node editor under **AI Assistant** (`historyRetentionDays`, default **30**, valid range 1–36500). Existing flows without this property also use 30 days. After deploy (with a 60-second startup delay for the shared archive), after restore and once a day, Cerebrum removes expired records from the shared conversation/observation/context/operation archive and deletes old daily KNX, adapter and operation files. Daily files are also checked hourly when new events arrive. Daily files covering the cutoff date remain until the following day; queries use the exact retention window. Cleanup also runs when the AI is disabled or idle. Deletion is permanent; increasing the value later cannot recover deleted history. Saved instructions, AI Education, JavaScript routines, current state and legacy memory files are kept separately and are not expired by this option.\n\nWeb, Telegram and nodes using the same storage directory share one archive. The shortest retention configured on any live node applies to this common archive, including when the AI is disabled. A partial deploy that changes a follower requests cleanup through the shared leader after the same startup delay; it does not wait for the leader's next daily check. Each node's daily files follow its own retention. Shared-archive compaction streams into a temporary file, preserves retained record IDs and replaces the original atomically; it needs temporary free space for retained data. Existing archives and backups remain readable; newly compacted shared archives require a Cerebrum version supporting history retention. Backups made before deletion retain their original contents; restored archives are cleaned according to the live destination policies.\n\nThe **Download ZIP** button prepares a compressed `.zip` archive on disk and starts a native browser download. **Restore ZIP** lets you select that archive directly, without extracting it. The enclosed `cerebrum-backup.json` uses backup format **3**, with daily archives stored separately under `archives/` inside the ZIP. Keep the complete ZIP: its JSON manifest alone cannot restore the histories. The backup includes the selected node's AI configuration (areas, GA roles, ETS access, profiles, tests and results), shared conversations/instructions/camera watches, device memory and runtime state, plus legacy learning/world checkpoints and journals when present, scheduled tasks, all retained KNX and adapter event archives, the operations archive, the last prompt diagnostic and any legacy area file. World-model restoration uses the destination node's local filename and participates in backup validation and rollback. Pending archive writes finish before the snapshot is taken. History already deleted by the normal retention policy cannot be recovered by a backup.\n\nThe ZIP includes `cerebrum-backup.json`, `cerebrum-flows.json`, `required-packages.json`, `README.txt` and the daily archive files. Export does not enumerate the deployed Node-RED runtime. The legacy-named `cerebrum-flows.json` contains only a sanitized snapshot of the selected Cerebrum node's saved settings: it contains no tab, position, wiring, referenced configuration node, credentials, ETS source text or runtime ETS catalog. `required-packages.json` is built only from one `RED.nodes.getNodeList()` inventory, filtered to installed packages whose module name contains `-ultimate`, plus Cerebrum itself. No API keys or integration credentials are included; nevertheless, keep the backup private because memories and archives may contain sensitive household information. Export requires the Node-RED `flows.write` permission. Browser downloads use a single-use link that expires after ten minutes.\n\nThe manifest's `files.aiEducation` entry contains the complete user-managed AI Education file, including its size and SHA-256 digest. The sanitized node snapshot omits the old `aiEducation` property. Restore validates the education file before changing data and restores the previous instructions if a later write fails.\n\nTo move Cerebrum to another installation:\n\n1. Click **Download ZIP** in the source node’s Web settings.\n2. Unzip the archive and install Cerebrum and the compatible integration packages listed in `required-packages.json` on the destination.\n3. Create a Cerebrum node, or import the sanitized node settings from `cerebrum-flows.json`. Select the destination integration configuration nodes, reconnect the six outputs as required and deploy. No existing flow topology is reconstructed by the backup.\n4. Open the destination Cerebrum node's Web settings and choose **Restore ZIP** with the original ZIP archive. This restores its data and archives, remapping storage filenames to the destination node ID, and replaces the shared learning/memory used by other Cerebrum nodes on that storage.\n5. Re-enter all required credentials and verify external service addresses. The data survives subsequent Node-RED restarts.\n\nImporting Cerebrum data does not deploy or overwrite Node-RED flows. Flow wiring, integration configuration nodes and credentials must be configured separately on the destination. Each backup covers one selected Cerebrum node plus the shared memory; export each Cerebrum node separately if you have several. Custom context stores, external certificates/files/modules, environment variables, installed AI models and the external services themselves belong to the surrounding Node-RED installation and must be provisioned there as well. The backup is not an operating-system or whole-Node-RED disk image.\n\nPrevious version 1 and 2 JSON backups and earlier ZIP backups remain importable. Version 1 backups cannot recover the archives and flow settings they never contained. Versions 2 and 3 check file sizes and SHA-256 digests before changing data, reject unsafe filenames, replace destination archives instead of merging stale history, and roll back on write errors. ZIP imports also validate CRC-32 checksums. ZIP size and total archive size have no fixed byte limit: export snapshots, uploads, decompressed daily archives and rollback copies use temporary files rather than accumulating history in RAM. Imports arrive in small chunks. Archive paths are mapped to private temporary filenames, then to the selected node's known storage directories. Temporary files are removed after completion or failure; abandoned uploads and pending downloads expire after ten minutes. The system temporary directory needs enough free disk space for these files. Only the JSON metadata and legacy JSON uploads retain the 256 MiB memory bound; it does not include the separately stored daily archives. New ZIP backups require a Cerebrum version supporting format 3.\n\nThe adjacent **Cerebrum Operations** view provides a compact activity log for the configured retention window (30 days by default). It combines the existing daily KNX traffic archive with LLM requests, catalog/history/Web/JavaScript tools, KNX reads and writes, schedules, camera/TTS/memory actions and local routine executions and state reconciliation. Each line shows the recorded time, activity text and outcome. Complete direction and diagnostic metadata remain in the archive. The node-operation archive is stored per Cerebrum node under `cerebrumultimatestorage/cerebrum/operations/`; credentials and obvious secret fields are redacted, and expired daily files are removed automatically.\n\n## Adapter API\n\nOptional packages can register an adapter and one or more providers without importing KNX Ultimate:\n\n```js\nconst { getAdapterRegistry } = require(\"node-red-contrib-cerebrum-ultimate\");\n\nconst registry = getAdapterRegistry();\nregistry.registerAdapter({\n id: \"my-adapter\",\n title: \"My adapter\",\n kind: \"home-automation\",\n capabilities: [\"states\", \"events\"],\n operations: [\"events\", \"list-entities\", \"read-entity\"],\n access: \"observe\",\n});\nregistry.registerProvider({\n id: \"my-controller\",\n adapterId: \"my-adapter\",\n title: \"My controller\",\n capabilities: [\"states\"],\n connected: true,\n isReady: () => true,\n subscribe: (listener) => {\n // Return an unsubscribe function.\n return () => {};\n },\n});\n```\n\nThe versioned capability contract distinguishes an installed adapter from a deployed, connected, ready and actually usable provider. Standard operations are `events`, `list-entities`, `read-entity`, `list-services`, `write-entity`, `list-cameras`, `camera-snapshot`, `query-camera-events` and `camera-event-snapshot`; provider methods are detected from the corresponding `subscribe`, `listEntities`, `getEntity`, `listServices`, `callService`, `listCameras`, `takeSnapshot`, `queryEvents` and `takeEventSnapshot` functions. Write operations remain subject to Cerebrum authorization and confirmation rules: declaring an operation never grants permission to control a device.\n\nProvider callbacks must catch their own I/O errors. Providers should expose `connected`, `isReady()` and, when useful, a data-only `health` status. Cerebrum isolates provider, flow-hook, timer, storage and output failures so an adapter cannot terminate Node-RED. The runtime capability snapshot passed to reasoning contains only sanitized metadata and never exposes RED, node instances or provider functions.\n\n## License\n\nReleased under the [MIT License][license-url].\n\n[npm-url]: https://www.npmjs.com/package/node-red-contrib-cerebrum-ultimate\n[npm-version-image]: https://img.shields.io/npm/v/node-red-contrib-cerebrum-ultimate.svg\n[node-version-image]: https://img.shields.io/node/v/node-red-contrib-cerebrum-ultimate?logo=node.js&logoColor=white\n[npm-downloads-month-image]: https://img.shields.io/npm/dm/node-red-contrib-cerebrum-ultimate.svg\n[npm-downloads-total-image]: https://img.shields.io/npm/dt/node-red-contrib-cerebrum-ultimate.svg\n[flows-image]: https://img.shields.io/badge/Node--RED-Flow%20Library-white?logo=nodered&logoColor=8F0000\n[flows-url]: https://flows.nodered.org/node/node-red-contrib-cerebrum-ultimate\n[license-image]: https://img.shields.io/badge/license-MIT-blue.svg\n[license-url]: https://github.com/Supergiovane/node-red-contrib-cerebrum-ultimate/blob/main/LICENSE\n[standard-image]: https://img.shields.io/badge/code_style-standard-brightgreen.svg\n[standard-url]: https://standardjs.com\n[youtube-image]: https://img.shields.io/badge/YouTube-Max%20Supervibe-red?logo=youtube&logoColor=white\n[youtube-url]: https://www.youtube.com/channel/UCA9RsLps1IthT7fDSeUbRZw/playlists\n","readmeFilename":"README.md"}
![\"Max](\"img/logo-supervibe.png\"){kind=logo}
\n![\"Cerebrum](\"img/cerebrum-ultimate-logo.png\"){kind=logo}
\n![\"Max](\"img/max-supervibe-youtube.png\")
\n \n