node-red-contrib-cerebrum-ultimate 1.0.4

Cerebrum Ultimate creates editable JavaScript home automations from user requests, with conversational clarification and local execution for Node-RED.

npm install node-red-contrib-cerebrum-ultimate

User-requested home automations for Node-RED

Cerebrum 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.

IMPORTANT NOTICE

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.

DEV POWERED BY GPT6-ASTRA

The development of Cerebrum Ultimate is enhanced by OpenAI GPT6-ASTRA.

What you can do

• Talk to your smart home in natural language.
• Ask for summaries, current states and recent events.
• Describe a routine and clarify missing details in conversation.
• Review, edit, pause and resume the resulting JavaScript.
• Define explicit conditions for notifications or permitted actions.
• Create reminders and scheduled checks.
• Use cameras and voice when compatible nodes are available.
• Generate reviewable Node-RED flows with the Node-RED Flow Builder.
• Write and revise JavaScript from a prompt in Cerebrum Function, based on the native Node-RED Function.
• Back up and restore the Cerebrum configuration from the Web interface.

Cerebrum Function (BETA)

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.

1. Configure and deploy a Cerebrum node with its AI provider and model enabled.
2. 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.
3. 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.
4. 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.
5. 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.

To 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.

Incoming 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.

In 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.

API	Returned data
cerebrum.available, cerebrum.info()	Availability and identity of the selected Cerebrum
cerebrum.knx.list(), .find(query), .get(address)	Authorized group addresses with name, DPT, area, aliases, read-only flag and observed state
cerebrum.knx.state(address)	Latest observed state for an authorized KNX address, or null
cerebrum.states.list(), .get(key)	Observed integration states, including keys such as knx:1/2/3
cerebrum.functions.list(), .get(name)	Managed JavaScript automation metadata; get also includes its code

Choose an address from your catalog and use its observed value:

if (!cerebrum.available) return null;
const sensor = cerebrum.knx.get("1/2/3"); // Replace using your catalog suggestions.
if (!sensor?.state?.fresh) return null;
msg.payload = sensor.state.value;
msg.topic = sensor.name;
return msg;

The 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.

For a working Inject → Function → Debug flow, import 16 - Cerebrum Function. It doubles a payload of 21 to 42 without requiring AI at runtime.

Based on the official Node-RED 5.0.7 Function, with upstream attribution and license. Supported Node-RED versions start at 3.1.1; node.linkcall requires Node-RED 5 or later.

Routine authoring and working context

The 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.

Describe 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.

Current 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.

In 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.

Shared conversation and situational context

Web 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.

Recent 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.

An 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.

Local 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. Restart Node-RED after installing the updated package; no memory migration is required.

Current 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.

ZIP 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.

Persistence across Node-RED restarts

Cerebrum restores conversation memory, current device data and user-created routines from files. No Node-RED context-storage setting is required.

File under cerebrumultimatestorage/cerebrum/	Retained data
automations/<node-id>/*.js and the adjacent runtime JSON	Authoritative routine source, statuses, schedules, timers and durable script memory.
memory/cerebrum-runtime-state-NODEID.json	Model context limits, Web reservations and explicit camera-watch cooldowns.
memory/cerebrum-chat-context.knxctx	Shared saved instructions, recent conversations and camera watches.
memory/cerebrum-home-memory.md	Current device state, factual observations, device metadata and existing legacy records.
operations/, history/, adapter-history/, memory/shared/	Retained activity and conversation archives.

Chat 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.

Saved instructions and device data

AI Education remains an explicit user-managed file at cerebrumultimatestorage/cerebrum/config/cerebrum-ai-education-<node-id>.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.

View	What you can inspect
Conversation	Requests, clarification questions and answers.
JavaScript automations	Actual routines, source, status, last execution and editing/pause/resume/delete controls.
Saved instructions	Explicit saved preferences, conversations and camera watches.
Device data	Latest observed device states. Historical observations remain in the archives and advanced files.
Cerebrum Operations	Retained KNX, model and tool activity with recorded outcomes.

Read-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.

Example flows

The 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.

Open 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.

Messages from Node-RED flows

To tell Cerebrum about an important household event while a Telegram adapter is selected, connect a Function node to Cerebrum's input and send:

msg.bypassAdapter = { payload: 'The garage thermal camera is reporting a fault.' };
return msg;

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.

Notifications 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.

These reports provide information, not permission to issue commands or control devices. Ordinary Telegram conversations continue to use the selected adapter.

Compatible nodes detected

Open the Cerebrum node and use Compatible nodes detected. Cerebrum shows the integrations available in the current Node-RED project.

For 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.

KNX: ETS Access, Areas, Tests and Test Results

The KNX test workspace is designed for commissioning and troubleshooting. It helps answer practical questions such as:

• Is the correct command group address being used?
• Does the actuator publish its new status after a command?
• Does the status address answer an explicit read request?
• Does the returned value match the requested value?

This 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.

Install 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:

ETS Access → Areas → Test plans → Test Results

Open 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.

1. Areas

An 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.

Open KNX → Areas to:

• Select an area suggested from the ETS structure, or create one.
• Give it a clear name and choose the group addresses that belong to it.
• If AI is enabled, Cerebrum can help suggest the most relevant addresses.

An area must contain at least one group address before it can be used in a test.

2. Tests

Cerebrum can perform two kinds of checks.

Read-only diagnosis

A read-only diagnosis does not operate any actuator. It examines the KNX traffic already observed for the selected area and reports:

• which group addresses have recently been active;
• which addresses have remained silent;
• whether recent anomalies belong to that area;
• whether the observed activity matches the selected diagnostic profile.

This 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.

Active functional test

An active test checks the complete command-and-feedback path. For each configured step, Cerebrum can:

1. Send the requested value to the command address.
2. Wait for the status address to publish a spontaneous update.
3. Read the same status address and wait for its response.
4. Compare both feedback values with the value that was expected.

In KNX terms, this means sending a command telegram, observing the status GroupValue_Write, then sending a GroupValue_Read and checking the returned GroupValue_Response.

For 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.

These 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.

Open 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:

• review and change every command and status address;
• check the DPT (KNX data type) and expected value;
• add pauses between operations;
• save the plan for later use;
• run it once or repeat it until you stop it.

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.

The tests verify KNX communication and configured feedback. They do not replace electrical, mechanical or on-site safety checks.

3. Test Results

Open KNX → Test Results to follow a running test or inspect a saved report:

• Pass means all configured checks for that step succeeded.
• Warning means a possible issue needs attention; in an active test, this usually means that only one of the two feedback checks succeeded.
• Fail means feedback was missing, arrived too late or contained a different value.

If 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.

Each 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.

Home Assistant

Connect Cerebrum's dedicated Home Assistant output to a Home Assistant ha-api node, then return the API output to Cerebrum's input:

Cerebrum output 6 (Home Assistant) → API (ha-api) → Cerebrum input

Select 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.

Safety and privacy

Cerebrum 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.

Home 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.

Autonomous KNX history queries

The 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.

Each 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.

Recorded camera events and snapshots

Camera 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.

With 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.

UniFi 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.

Local JavaScript automations

Model 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.

Ask 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.

Open 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.

Sources live under cerebrumultimatestorage/cerebrum/automations/<node-id>/. A single <node-id>.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.

Functions 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.

Deterministic 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.

Isolated installed-package inventory

The 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.

The 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.

Execution 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.

Local memory and backup

Cerebrum 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.

Set 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.

Web, 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.

The 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.

The 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.

The 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.

To move Cerebrum to another installation:

1. Click Download ZIP in the source node’s Web settings.
2. Unzip the archive and install Cerebrum and the compatible integration packages listed in required-packages.json on the destination.
3. 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.
4. 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.
5. Re-enter all required credentials and verify external service addresses. The data survives subsequent Node-RED restarts.

Importing 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.

Previous 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.

The 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.

Adapter API

Optional packages can register an adapter and one or more providers without importing KNX Ultimate:

const { getAdapterRegistry } = require("node-red-contrib-cerebrum-ultimate");

const registry = getAdapterRegistry();
registry.registerAdapter({
  id: "my-adapter",
  title: "My adapter",
  kind: "home-automation",
  capabilities: ["states", "events"],
  operations: ["events", "list-entities", "read-entity"],
  access: "observe",
});
registry.registerProvider({
  id: "my-controller",
  adapterId: "my-adapter",
  title: "My controller",
  capabilities: ["states"],
  connected: true,
  isReady: () => true,
  subscribe: (listener) => {
    // Return an unsubscribe function.
    return () => {};
  },
});

The 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.

Provider 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.

License

Released under the MIT License.