Skip to content

About

Constellation by ProgreTech: animated Ubuntu GNOME agent-memory galaxy wallpaper

Topics

Resources

Stars

3 stars

Watchers

0 watching

Forks

Latest commit

 

History

34 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Constellation by ProgreTech

Set native_harness: true in the source JSON to include native Harness session owners and their project folders. This reads bounded harness ps metadata, never conversations. Stopped/unknown sessions remain labeled as such; project context targets do not become write events. Reviewed file-change receipts still come from the configured shared memory source. Avalon reuses this collector.

Version 13 combines the recovered appearance, folder, agent and memory controls with the native Hindsight API source. Asteroid and satellite modes, independent solar rotation, recorded-write lights and the 30 FPS renderer work with the configured activity backend. Agent and memory display choices preserve that backend. On Wayland, log out and back in after updating the extension.

Click the Hindsight solar system to open its configured Control Plane; click a memory planet to review that exact record in the local read-only viewer. For the native API source, planets come from the same explicitly shared, reviewed records as file activity, including records that name no existing files. The planet count is a maximum: one eligible shared record produces one planet. The agent scan also reads OpenClaw's local roster and named Hermes profiles when gateway executables are absent from the desktop PATH. These are configured roles, not a claim that every role is currently running.

Set the UI link with python3 configure.py --hindsight-ui http://127.0.0.1:9999. Use your Control Plane URL when it is hosted elsewhere; API and UI URLs are separate settings. Agent configurations, sessions and memory backends are not modified by scanning.

Constellation turns reviewed agent-memory activity into a rotating, luminous map on an Ubuntu GNOME wallpaper. Your workstation is the central star; agents orbit it, configured directory roots become solar systems, and files mentioned in memory become stars. Agent-to-file links keep their bouncing lights as the galaxy turns counterclockwise. Progre watches the sky from the bundled rooftop foreground. The lower-right Constellation by ProgreTech · © 2026 ProgreTech LLC attribution is rendered by the official wallpaper in both live and empty-data states.

Constellation running on the ProgreTech workstation

Live workstation preview supplied by Edwin. Progre and this preview are ProgreTech visual assets; see the asset terms.

The preview captures an earlier roster and layout. The current factory configuration uses MS-S1 Max as the host star, with PT-CONTEXT as its central directory and selected child folders as solar systems.

The map is an interpretation of remembered activity, not a file monitor or an access-control tool. Only existing files inside configured roots can become file stars. The renderer never scans an entire disk to invent activity. Paths that look like credentials or private configuration are filtered. For Hindsight, Constellation calls the supplied CLI under your own authorized identity and reads shared structured activities; it does not open the database or another role's private memory. A JSON-directory adapter lets other memory systems export the same small activity shape.

How updates appear

The user timer rebuilds the memory scene every two minutes. The GNOME extension checks for an updated scene every two seconds and targets about 30 animation frames per second (33 ms ticks; actual throughput depends on display resolution and rendering load). A new activity record can add a file star on the next scene build when it names an existing file inside one of your configured roots. An agent touching a file already shown adds another agent-to-file link. The moving light travels back and forth along each visible link continuously; it is a recent-memory cue, not a one-time file-transfer event. The seven most recent visible file links per agent are drawn, then older links fall away as newer ones take priority.

The default display holds up to 160 remembered files and 48 remembered directories. When full, newer eligible files may replace older ones; the number on screen need not increase. Set "max_files" and "max_directories" in sources.json to change those limits (maximum 1,000 and 200). Missing files, paths outside configured roots, and sensitive-looking paths do not appear. If memory retrieval fails, the last scene remains in place; the wallpaper marks it stale after six minutes. The Bokeh inspection page reads configured memory when opened or refreshed (its local served page defaults to a 120-second refresh).

Ubuntu GNOME install

Tested with Ubuntu GNOME Shell 50 on Wayland. Python 3.10+ and a user systemd session are required. This GNOME Shell extension has no macOS or Windows release.

git clone https://github.com/progretech-llc/constellation.git constellation
cd constellation
./install-ubuntu.sh

install-ubuntu.sh installs Ubuntu packages (python3-venv, python3-gi, GTK 4 bindings and gjs), creates a Python environment for Bokeh, installs the bundled Progre image, registers the control app and user refresh timer, and installs/enables the GNOME extension. It does not copy your memory or file contents. On Wayland, log out and back in after an install or code update so GNOME Shell loads the new extension JavaScript. If the packages already exist, ./install-user.sh performs only the user-level installation.

Open Constellation by ProgreTech from the app menu to control rotation, glow, rays, density, foreground, links and labels. The wallpaper keeps running without the control window. gnome-extensions disable factory-observatory@progretech.com turns it off; systemctl --user disable --now factory-observatory-scene.timer stops memory refreshes. The static GNOME wallpaper setting is untouched.

Folders, recommendations and agent movement

The native controls have five tabs:

The Galaxy wallpaper on/off switch stays above all five tabs. Turn it off to hide the animated wallpaper and stop its motion; turn it on to restore it. The installed extension picks up the setting within about two seconds, without a logout. Your folder selections, appearance settings and ordinary desktop background are retained.

  • Folders: add up to 12 solar-system folders, edit their display names, remove them from the draft, and set the remembered-file and subfolder limits. Apply folder changes saves the draft and refreshes the scene without blocking the window. Removing a folder never deletes it or its files. Reload folders discards unapplied folder edits. Source identity and unrelated configuration keys are preserved; conflicting edits are rejected.
  • Agents: check which agent nodes and connections to show, then Apply agent selection. Select none hides every agent while retaining file/folder nodes. Automatic restores the configured roster plus active memory authors. Scan for gateways combines the local OpenClaw roster, user gateway-service status, explicit factory-memory MCP identities in Hermes/Goose/OpenCode/Codex/Claude Code client configuration, and authors in the configured shared activity source. Services, configured clients and historical authors are labelled separately; installed does not mean running. Clients sharing a memory identity appear once. New discoveries are unchecked. Discovery never executes a configured MCP command, connects to gateways, changes credentials, starts agents or reads private role memory. Unknown adapters/profiles are not exhaustively discovered. YAML client discovery requires python3-yaml (included by the Ubuntu installer); unavailable metadata produces a warning rather than inventing identities.
  • Memory Node: Scan for memory systems, select one radio option, then Apply memory node. Hindsight is the default on Hindsight configurations. Discovery checks known user/system service names, commands and user directories for Hindsight, Mem0, Zep, Chroma, Qdrant and Letta; it is a metadata scan, not a database search or connection-health test. One selected system replaces the legacy Hindsight/MemPalace display slot. Hindsight supports recent shared record planets through the existing identity-bound reader. Other systems currently display a named system node only, with no record ingestion or migration. The configured memory provider, project and author identity remain unchanged. A selected system missing from a later scan remains labelled as not detected until the user changes it.
  • Recommendations: Scan for recommended folders reads a bounded snapshot of the configured reviewed activity source and ranks its top five existing folders by distinct activity count, then agent count and recency. Referenced paths inside a repository are grouped at that repository; other paths use the first child of the configured galaxy or home folder, falling back to the containing directory. Sensitive and missing paths are excluded. The scan does not walk drives, read file contents, change memory identity or automatically add folders. Add to draft, then apply on the Folders tab. These are recommendations from recorded activity, not an OS-wide usage census; fewer than five may qualify.
  • Appearance: choose Agent movement as well as the existing visual controls. Orbiting retains the original named-agent positions, links and bouncing lights when write lights are off. Asteroid moves each agent among its seven most recent visible remembered file targets: approach the containing folder's orbit, circle nearby, touch the target, then travel on. Agent connection lines and bouncing lights are hidden. Satellite orbits the system with that agent's latest visible creation/modification, with static lines to its recent written files and their containing folders in that system. Read-only activity does not displace its latest written system. Agents without qualifying targets retain their original host orbit.

Write lights · no connecting lines is optional in Orbiting and Asteroid. It replays each agent's recent recorded creations/modifications as one-way light particles to the existing tiny file planets, with a brief arrival glow. It excludes read-only references, does not duplicate file nodes, and is not a live filesystem event feed. In Orbiting it replaces legacy lines and bouncing lights while enabled; disabling it restores their saved setting. Satellite retains its existing lines. Pause freezes these effects too.

Shared worker · black hole is the factory-worker logical identity used by clients without a named role, not a single named colleague or proof of a running process. Its recorded actions may include recent work as well as history. It stays fixed in the upper-right corner in every movement mode, labelled “Shared worker / RECORDED ACTIVITY”. Up to three shrinking light circles travel from its recently touched files into the black hole, with no outgoing lines or return lights. Files remain in their solar systems. Rename it in Appearance → Black-hole display name → Save name (or press Enter). Up to 32 characters; blank restores “Shared worker”. The renderer fits long names with an ellipsis while keeping the full saved name. This changes the visible name only; factory-worker, selection and activity authors remain unchanged. Hide it through Agents if desired; focus shows it only for related visible file activity. Other agents keep their existing behavior.

Appearance also offers Rotate solar systems independently and Solar-system spin (0–10 degrees per second). When enabled, this controls each system's contents around its own center, independently of Galaxy rotation. Spin clockwise defaults off (counterclockwise); toggling it reverses from the current angle without resetting. Local speed and direction replace the inherited local orbit while enabled, so galaxy rotation cannot overwhelm a slow clockwise spin. It defaults off to preserve the original presentation. Speed changes keep the accumulated angle; zero holds it steady. Pause all motion freezes galaxy rotation, local spin and agents. Folder focus and click targets follow the rotating contents.

Motion uses per-agent activity order, rather than another agent's newer reference to the same file. Selection is bounded by the visible catalog and the configured memory source. Switching back to Orbiting restores the original agent presentation. These movement choices apply to the GNOME wallpaper; the separate Bokeh inspection map retains its existing behavior. After upgrading the extension, log out and back in once to load the new JavaScript on Wayland; subsequent setting changes apply live.

Agent selection uses a separate display_agents field: missing/null preserves the automatic roster, a list is an explicit selection, and [] intentionally shows no agents. It does not overwrite configured agents, aliases, memory identity or the activity store. Explicitly selected identities remain distinct from the unlisted-author display fallback. memory_node stores only the chosen display provider and optional local path. Both selections are applied through scene refresh, so these controls themselves require no GNOME Shell restart. Changes affect the wallpaper; the Bokeh inspector continues to inspect the configured source.

Navigate from the wallpaper

On an exposed part of the desktop, click a solar system or remembered directory to open it in the default file manager. Hold Ctrl over a file star to see its containing folder; Ctrl-click opens that folder. With a Hindsight source, Ctrl+Shift-click the file star opens its newest remembered entry in a read-only window, using the configured Hindsight CLI and your configured identity. The viewer resolves the full entry ID through the authorized CLI; it never reads the database directly. If a source entry is no longer available, the viewer reports that instead of opening a different record. JSON memory sources currently support folder navigation but have no Hindsight entry viewer.

Alt-click a solar system or remembered directory to focus and enlarge its remembered files, subfolders and connected agents. Alt-click the same node or an empty part of the sky to return to the full map. Folder and memory actions are available only where the desktop is visible; they do not intercept clicks through application windows.

On Ubuntu Wayland, Desktop Icons NG owns the desktop pointer surface. Constellation places a small Shell click target only under the currently hovered actionable star. Pause over a star until its path tooltip appears, then click or use the modifier shown there. The target follows the pointer on the wallpaper's 33 ms animation cycle; ordinary desktop icons remain clickable away from stars. If Alt-clicking empty sky does not reset a focused view, Alt-click the host star instead. After installing an extension code update, the current Wayland Shell keeps its cached JavaScript until the next login; no logout is needed for scene-data refreshes.

A small lower-right legend keeps these shortcuts, the remembered-file count, and the ProgreTech credit together on the wallpaper. The Hindsight shortcut appears only when Hindsight is the configured source.

Subfolders orbit their nearest visible parent folder (or their solar system), and remembered files orbit their containing folder. These local orbits continue in the focused view, where the selected folder stays centered.

Point it at your memory and solar systems

The installer creates ~/.config/constellation/sources.json, initially with a local JSON memory directory and your home directory as one root. Use configure.py to replace those values; every --root replaces the whole root list. Paths must be absolute or start with ~ in the JSON file. Up to 12 roots are supported. A root appears as a solar system even when it has no remembered files. The host star defaults to the system hostname; set --host-name for a friendly name. --galaxy LABEL=PATH names the parent directory at the center and makes the host star open that directory when clicked. Configure its child folders as solar systems, not the parent again. External roots such as Pictures or a remote mount can also be included.

For any agent memory that can export reviewed activity as JSON:

python3 configure.py \
  --memory-dir "$HOME/agent-memory/constellation-events" \
  --host-name "My Workstation" --galaxy "Home=$HOME" \
  --root "Projects=$HOME/Projects" \
  --root "Documents=$HOME/Documents" \
  --agents my-orchestrator worker-a worker-b

Put one JSON object or an array of objects in each *.json file in that directory. A minimal object is:

{
  "memory_id": "example-001",
  "author": "worker-a",
  "project": "MyProject",
  "technical_steps": ["Created /home/USER/Projects/demo/report.md"],
  "evidence": ["/home/USER/Projects/demo/report.md"]
}

Replace USER with your actual login; the file must already exist inside a configured root. created, modified, and accessed are inferred from step wording; all other references show as referenced. The exporter should supply reviewed summaries, not secrets or full conversations. JSON files stay local and are never uploaded by Constellation.

For Hindsight, point to its CLI executable, your identity and project; do not point Constellation at the database directory:

python3 configure.py \
  --hindsight-cli "$HOME/Rend/bin/hindsight" \
  --agent YOUR_OWN_ID --project YOUR_PROJECT \
  --host-name "My Workstation" --galaxy "Home=$HOME" \
  --root "Repositories=$HOME/Projects" \
  --root "Documents=$HOME/Documents" \
  --agents YOUR_OWN_ID worker-a worker-b

The CLI path above is an example only. Use the path on your workstation and the identity you are authorized to use. The reader accepts Hindsight's reviewed structured-agent-activity records in the selected project. Other authors' shared project records retain their attribution. Use sources.json to add "include_subprojects": true inside memory if intended. After editing sources or dropping new JSON summaries, refresh immediately with systemctl --user start factory-observatory-scene.service. The timer refreshes every two minutes. Check failures with journalctl --user -u factory-observatory-scene.service -n 30.

To keep a current roster while showing older memories, configure display-only author aliases. For example, python3 configure.py --agents codex rend lyra mak progre imagen moxy --alias architect=rend --alias reviewer=rend --alias fast=rend --alias designer=rend --alias factory-worker=rend --unlisted-agent rend groups those older authors, and any other unlisted authors, under Rend. Configured agent names remain visible when they have no current file links; all agents orbit the host star. These choices change scene nodes and links only; the source memory records and their original authors remain unchanged. Omit --unlisted-agent if you want unlisted authors to receive their own nodes. Older center_agent settings are accepted but no longer place an agent at the center.

Choose roots at the level you want to see as solar systems. For instance, --host-name "MS-S1 Max" --galaxy "PT-CONTEXT=/mnt/pt-context" --root "Repositories=/mnt/pt-context/projects" --root "Deliverables=/mnt/pt-context/deliverables" gives the host and the parent directory distinct labels, while its children orbit as systems. Subfolders orbit their nearest visible parent and remembered files orbit their containing folder when focused. Files named through a symlinked root still belong to that root as long as they resolve within it. On Wayland, changing extension JavaScript requires logout/login to load the new code; scene and configuration refreshes alone do not.

Vectorize Hindsight API

The native API source reads one explicitly configured bank, without a database connection or a compatibility CLI:

python3 configure.py --hindsight-api http://127.0.0.1:8888 --bank-id progretech-shared-activity
systemctl --user start factory-observatory-scene.service

For an authenticated server, add --api-key-env HINDSIGHT_API_KEY and make that environment variable available to the scene service and memory inspector. Keys are not stored in source configuration or the wallpaper scene. Plain HTTP is restricted to loopback; remote servers require HTTPS. Redirects are refused.

Publish only reviewed activity summaries to this bank using Hindsight's normal retain API. Each source document must have both constellation:shared and structured-agent-activity tags. Its retained text must be a JSON object such as:

{
  "scope": "project",
  "reviewed": true,
  "provenance_type": "structured-agent-activity",
  "author": "codex",
  "project": "Example",
  "title": "Reviewed report update",
  "technical_steps": ["Updated the reviewed report"],
  "evidence": ["/path/to/projects/report.md"]
}

The source checks tags before fetching document content, then checks scope, review status and structure again. It does not enumerate banks or read private conversation banks. Only the most recent 100 matching documents are fetched, with response-size and timeout limits; retrieval failure preserves the previous scene. Existing root and sensitive-path filters still apply. Exact evidence paths may contain spaces. The memory inspector uses these same shared records.

Update the GNOME extension with ./install-user.sh after changing extension code. On Wayland, the new inspector controls load at the next logout/login; scene content continues to refresh through the existing timer.

Inspect and extend

The native app's Open interactive map button launches a Bokeh view bound to 127.0.0.1:8765; hover to inspect remembered paths. Run .venv/bin/python app.py --no-open to save a local HTML snapshot. Run gjs -m gnome-extension/render-preview.js ~/.local/state/factory-observatory/scene.json /tmp/constellation.png 1920 1080 assets/progre-foreground.png to preview the exact Cairo composition. The GNOME background group is an internal Shell integration point and should be rechecked after Shell upgrades.

The code is MIT licensed. The bundled Progre foreground, preview, and brand identifiers have separate, rights-reserved terms; they are not MIT licensed. See LICENSING.md for the exact file scope. You can reuse the galaxy code for another project and supply your own foreground. The official release retains its lower-right ProgreTech credit. GitHub's licensing guide explains why repositories with separately licensed material need an explicit scope statement. This release does not include private factory memory, scene JSON, or credentials.

Avalon wallpaper handover

The GNOME extension shares a synchronous ownership guard with Project Avalon. Enabling either wallpaper stops the previous renderer before the next starts, including direct GNOME enables and concurrent requests. Only the two wallpaper extensions participate; unrelated agent processes are untouched. The native Galaxy wallpaper switch now enables/disables the extension and follows external handovers. Enabling the extension directly restores its wallpaper power setting while preserving appearance settings.

After updating extension code on Wayland, log out/in to load it. gnome-extensions enable factory-observatory@progretech.com returns ownership to Constellation. The shared ownership-core.js and ownership.js copies must stay identical to Avalon's files. Avalon carries the isolated-GNOME integration qualification; run native controls tests with /usr/bin/python3 -m unittest discover -s tests/native -v.

The wallpaper off switch now also clears the known legacy static Constellation background URI to Ubuntu’s schema default. This migration touches only */Constellation/data/progretech-constellation.png; unrelated user wallpapers remain unchanged. With Avalon selected, the shared guard performs the same migration. Updated extension JavaScript loads after the next logout/login.

Installed agent roster

Set discover_agents: true in the user sources JSON to derive agent nodes from current local Hermes profiles, OpenClaw agents and configured installed Codex/Claude/OpenCode clients. Refreshes recheck native metadata; saved names and past memory authors cannot recreate a removed agent. Explicit display selections are intersected with that current roster. Discovery reports configured availability, not running work. Historical files and memory provenance remain intact. With this option disabled, standalone offline/custom memory datasets retain their explicitly configured roster behavior.

About

Constellation by ProgreTech: animated Ubuntu GNOME agent-memory galaxy wallpaper

Topics

Resources

Stars

3 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages