Skip to content

Home

Jump to bottom
Dylan L.R. Pollock edited this page Oct 26, 2025 · 8 revisions

Home

Project: Monkey‑Head‑Project (HueyOS)
Author: Dylan L. R. Pollock
Official site: https://www.dlrp.ca
License: Code: GPL‑3.0 • Docs/Media: CC‑BY‑SA‑4.0
Status Date: 2025‑10‑25

HueyOS is a modular AI/OS for robotics that blends retro‑computing aesthetics with modern Linux, clustered compute, and a constitutional governance model (Cloud Pyramid). The system prefers offline operation with optional API use, emphasizes lifelong learning, and keeps governance decentralized while memory stays unified.

Note

Heads‑up: A major software update lands October 31, 2025 (kernel jump to 6.17.x, Python 3.14, Debian Forky pathfinders, memory stack, governance refinements). Track Action Plan — Oct 31, 2025.

_Sidebar

_Footer

© Dylan L. R. Pollock. Code under GPL‑3.0; docs/media under CC‑BY‑SA‑4.0.
Last updated: 2025‑10‑25.
Found an issue? Open one in the main repo and link the affected wiki page.

Getting Started

Supported Targets (current focus)

  • Debian 13 (Trixie) — baseline; UEFI‑only; amd64.

  • Debian 14 (Forky) — staged adoption for Oct‑31 update.

  • Linux Kernels: 6.16.x‑huey (current), 6.17.x‑huey (incoming).

Minimal Install

  1. Install Debian (UEFI, amd64). Choose GNOME on Xorg for iMac 5K targets.

  2. Enable non‑free firmware (Realtek, Intel, etc.).

  3. Create user dlrp (or custom) and enable sudo.

  4. Network: prefer bonded Ethernet → Wi‑Fi as fallback.

  5. Post‑install: apt update && apt full-upgrade.

Tip

For reproducibility, snapshot /etc/ and /boot/ after first login.

Core Packages (baseline)

sudo apt install -y build-essential bc bison flex libelf-dev libssl-dev \
  libncurses-dev dwarves pahole rsync xz-utils cpio kmod python3 \
  git wget curl ca-certificates gnupg debian-goodies \
  firmware-linux firmware-misc-nonfree firmware-iwlwifi firmware-realtek

Optional Userland

  • Ollama (local LLMs; Vulkan/ROCm as available)

  • PyGPT-net (agent runner)

  • Microsoft Edge (Beta) for dev/test

See Build Guides for signed repo keys and signature‑policy troubleshooting.

Architecture

Huey’s architecture is a layered federation aligning compute, memory, and governance.

flowchart TB
  A[Huey — Sovereign Consciousness]:::c1
  B1[Spark
Creative / GPU‑1]:::c2
  B2[Zap
Evaluative / GPU‑2]:::c3
  C[Citizen Populace
256 agents (128/128)]:::c4
  D[Worker Subsystems
NanoOS/SubOS, IO]:::c5
  A --> B1
  A --> B2
  B1 --> C
  B2 --> C
  C --> D
  classDef c1 fill:#111,stroke:#5cf,stroke-width:1px,color:#fff
  classDef c2 fill:#0b3,stroke:#0b3,color:#fff
  classDef c3 fill:#b30,stroke:#b30,color:#fff
  classDef c4 fill:#333,stroke:#999,color:#fff
  classDef c5 fill:#222,stroke:#666,color:#fff

Layers

  1. Huey as Sovereign Consciousness — emergent, lawful decision + inaction boundary.

  2. Binary Brain — Spark (creative, GPU‑1) and Zap (evaluative, GPU‑2) form a bicameral AI core.

  3. Citizen Populace — 256 AI instances (128 per core) as civic units with voting/operational roles.

  4. Worker Subsystems — NanoOS/SubOS services for sensors, limbs, and IO without clause power.

Principles

  • Decentralized governance, unified memory.

  • Offline‑first; API‑capable.

  • Traceable action history; reproducible system state.

  • Clear separation: governance vs. actuation; data vs. policy.

Important

Decisions and inactions both carry provenance and must be logged.

Hardware

Node Roster

Node Role Key Specs Status
Huey Prime Orchestration hub Thermaltake ATX case; ITX BD795I‑SE (Ryzen 9 7945HX); DDR5‑5200; dual Intel Optane M10 16 GB NVMe; GPU: RX 5500 XT 8 GB → MI50 planned Active
Huey‑Legacy (Shell) On hold; file hub candidate Supermicro X9QRI‑F+ quad‑Xeon; 10 GbE NIC; GPUs; RAID SSDs Paused
Huey‑Portal Universal display/control iMac 5K (2017), 48 GB RAM, Debian Trixie, GNOME/Xorg Active
Huey‑Portable Portable node (LTE) ASUS BR1100FKA 11.6", N4500/4 GB/LTE, Debian Trixie Active
Huey‑Hub File hand‑off 2017 MacBook Pro (Win10 bare‑metal) + WD MyBook Duo ~10 TB mirror Active

Remote Intent & Action

  • RF Remote (IC2262/2272) → Arduino UNO (USB symbolic intents: LISTEN, VOTE:YES/NO).

  • Arduino Mega 2560 → motors/sensors (PWM/I²C).

  • Arduino Nanos → localized LED/analog/PWM conditioning.

Display

  • iMac 5K (Portal) + 27" Samsung C27F396 portrait (torso). Future: Neo C128 board for VIC‑II/SID.

Network

  • Router: ASUS GT‑AC5300 (link aggregation). Preferred: bonded Ethernet; Wi‑Fi fallback.

Software Stack

  • OS: Debian 13 (Trixie) → Debian 14 (Forky) adoption begins Oct‑31.

  • Kernel: 6.16.x‑huey → 6.17.x‑huey (custom; perf‑oriented; targeted drivers).

  • AI: Ollama (local LLMs; Mistral‑7B quant), PyGPT‑net agents; Whisper STT; TTS module.

  • UI: Minimalist green‑on‑black; two‑pane logic (conscious voice vs verbose logs).

  • Memory: JSON logs + SQLite; unified store; long‑term persistence.

  • Security: SSH keys; optional default lab key (rotatable); fallback LIVE USB.

Folder Conventions

/huey/
  bin/           # launchers + maintenance scripts
  kernels/       # packaged kernels, configs, build logs
  memory/        # sqlite, json logs, vectors (later)
  services/      # systemd units, timers
  ui/            # themes, boot assets, display scripts
  docs/          # project docs (this wiki mirrors)

Build Guides

Kernel 6.17.x‑huey (generic; adjust per target)

# deps (see Getting Started for base set)
sudo apt install -y fakeroot kmod pahole flex bison libelf-dev libssl-dev \
  libncurses-dev bc rsync xz-utils cpio python3

source (example)


wget https://cdn.kernel.org/pub/linux/kernel/v6.x/linux-6.17.5.tar.xz
tar -xf linux-6.17.5.tar.xz && cd linux-6.17.5


seed config from running kernel, then refresh


cp -v /boot/config-$(uname -r) .config
yes "" | make olddefconfig


huey perf toggles (examples; tune per target)


./scripts/config --disable DEBUG_INFO --disable DEBUG_INFO_BTF 

--disable KASAN --disable UBSAN --disable KCOV --disable FUNCTION_TRACER 

--enable ZSTD --enable RD_ZSTD --enable EFI --enable EFI_STUB --enable EFI_VARS


build Debian packages


make -j$(nproc) bindeb-pkg


install


sudo dpkg -i ../linux-image-6.17.5-.deb ../linux-headers-6.17.5-.deb
sudo update-initramfs -c -k 6.17.5
sudo update-grub

iMac 5K (2017) notes

  • GNOME on Xorg recommended.

  • Force display mode via kernel cmdline if needed (HDMI‑A‑1 1080p60 while booting).

  • Audio: prefer PipeWire; set default sink on boot.

# set default HDA PCH sink after login
mkdir -p ~/.local/bin
cat > ~/.local/bin/set-default-sink.sh <<'EOF'
#!/usr/bin/env bash
sleep 3
SINK=$(pactl list short sinks | awk '/pci-0000_00_1f\.3.*analog/ {print $1; exit}')
[ -n "$SINK" ] && pactl set-default-sink "$SINK" && pactl set-sink-mute "$SINK" 0 && pactl set-sink-volume "$SINK" 60%
EOF
chmod +x ~/.local/bin/set-default-sink.sh

Remove Splash / Show Boot Logs

sudo sed -i 's/GRUB_CMDLINE_LINUX_DEFAULT=.*/GRUB_CMDLINE_LINUX_DEFAULT="loglevel=4 systemd.show_status=1"/' /etc/default/grub
sudo update-grub

Microsoft Edge (Beta) repo key (sqv policy compliant)

sudo install -d -m0755 /etc/apt/keyrings
wget -qO- https://packages.microsoft.com/keys/microsoft.asc | \
  gpg --dearmor | sudo tee /etc/apt/keyrings/microsoft.gpg >/dev/null

echo "deb [arch=amd64 signed-by=/etc/apt/keyrings/microsoft.gpg] 

https://packages.microsoft.com/repos/edge stable main" | 

sudo tee /etc/apt/sources.list.d/microsoft-edge.list >/dev/null


sudo apt update

RAID Superblock Cleanup (when reverting experiments)

cat /proc/mdstat
sudo mdadm --detail --scan
lsblk -o NAME,TYPE,SIZE,MOUNTPOINTS

stop any auto-assembled arrays


sudo mdadm --stop --scan || true


find and remove stale superblocks (replace partitions with actual ones)


sudo mdadm --examine /dev/nvme0n1p3 && sudo mdadm --zero-superblock /dev/nvme0n1p3
sudo mdadm --examine /dev/mmcblk0p3 && sudo mdadm --zero-superblock /dev/mmcblk0p3


echo 'AUTO -all' | sudo tee /etc/mdadm/mdadm.conf
sudo update-initramfs -u

Ollama on AMD (force RADV/Vulkan)

export VK_ICD_FILENAMES=/usr/share/vulkan/icd.d/radeon_icd.x86_64.json
export OLLAMA_LLM_LIBRARY=vulkan
export VK_LOADER_DEBUG=all
export OLLAMA_DEBUG=1
ollama serve

Huey‑Portable: Default Deep Sleep

echo 'MEM_SLEEP_DEFAULT=deep' | sudo tee /etc/default/mem-sleep >/dev/null
sudo tee /usr/local/sbin/set-mem-sleep.sh >/dev/null <<'EOF'
#!/usr/bin/env bash
set -euo pipefail
want=$(awk -F= '/^MEM_SLEEP_DEFAULT=/{print $2}' /etc/default/mem-sleep 2>/dev/null || echo deep)
avail=$(cat /sys/power/mem_sleep 2>/dev/null || echo "")
case "$avail" in *"$want"*) echo "$want" | tee /sys/power/mem_sleep >/dev/null || true;; esac
EOF
sudo chmod +x /usr/local/sbin/set-mem-sleep.sh
sudo tee /etc/systemd/system/mem-sleep-default.service >/dev/null <<'EOF'
[Unit]
Description=Set default mem sleep (deep or s2idle)
After=local-fs.target
[Service]
Type=oneshot
ExecStart=/usr/local/sbin/set-mem-sleep.sh
[Install]
WantedBy=multi-user.target
EOF
sudo systemctl enable --now mem-sleep-default.service

Warning

Kernel work can brick a boot. Keep the LIVE USB entry active and tested.

Governance & Constitution

Cloud Pyramid (Summary)

  • Clause‑based activation: policies trigger agent powers.

  • Quorum: decisions from Spark/Zap + citizens; deterministic tie‑breakers.

  • Separation: governance (what should) vs actuator (what is done).

  • Auditability: all decisions and inactions logged with reasons.

Roles

  • Spark — ideation, exploration, generative planning.

  • Zap — review, constraint, safety, resource stewardship.

  • Citizens — specialized agents (perception, planning, controls).

  • Workers — real‑time IO modules; no clause power.

Memory & Data Model

Unification mandate: One coherent memory across agents.

Stores

  • SQLite — structured facts, events, decisions.

  • JSON Logs — append‑only chronological traces.

  • Artifacts — model weights, kernels, configs, build logs.

IDs & Traceability

  • HUEY-<YYYYMMDD>-<PHASE>-<SEQ> for releases.

  • EVT-<timestamp>-<agent> for event logs.

  • Provenance fields for all artifacts.

Remote Access (VNC/SSH)

Preference: TigerVNC on huey‑legacy (GNOME on Xorg).

  • Server bound localhost:1995, no prompt (-SecurityTypes None), SSH tunnel only.

  • Client helper vnc command on huey‑portal maps :1 → 1995.

  • Default res: 2560×1440. Avoid DeferUpdate; prefer RawKeyboard.

See ~/bin/vnc alias and huey-vnc convenience command in your shell profile.

Action Plan — Oct 31, 2025

A checklist designed to be fed item‑by‑item into automation or CI (e.g., “codex”).

Kernel & OS

  • Build and package linux‑image‑6.17.x‑huey for: Huey‑Portal (iMac 5K), Huey‑Portable (BR1100FKA), Huey Prime (BD795I‑SE).

  • Validate boot (GRUB cmdline, early modeset, 1080p60 during boot, splash removed).

  • Smoke‑test audio (PipeWire default sink script on login).

  • Stage Debian 14 (Forky) APT sources (kept disabled); test packages in chroot/container.

  • Finalize EFI LIVE fallback USB entry (GRUB menu integration).

Python & Runtime

  • Install Python 3.14.x side‑by‑side; build wheels for key deps.

  • Run PyGPT‑net on 3.14; document incompatibilities/workarounds.

  • Refresh requirements-*.txt.

AI/Agents

  • Confirm Mistral‑7B quant works under Vulkan on RX 470 / 5500 XT.

  • Add Whisper STT + TTS pipeline scripts; test latency on Huey‑Portable.

  • Wire Spark/Zap boot choreography; log quorum outcomes.

Memory

  • Migrate unified memory schema (SQLite + JSON log rollover policy).

  • Implement provenance tagging for builds and decisions.

Security & Keys

  • Rotate default lab SSH key; populate huey-keys/ with new default + staged personal key.

  • Enable passwordless SSH where intended; restrict root login post‑install.

Tooling

  • Fix Edge Beta signing policy (install key to /etc/apt/keyrings/).

  • Add huey-run.desktop launcher for PyGPT (user scope).

  • Document vnc helper and SSH tunnel recipe.

Docs

  • Update README.md and this Wiki with Oct‑31 deltas.

  • Publish Pre‑Release #3 (2025‑10‑25) summary and link to Action Plan.

  • Post “stay tuned” banner on dlrp.ca.

Roadmap & Pre‑Releases

Phase 1 — Foundations (Pre‑Release #1)

Date: 2024‑04‑11

  • Baseline hardware bring‑up (VIC‑20/C64/C128 references).

  • GenCore seed; basic learning modules.

  • Prototype shell mapping (interfaces, wiring paths).

System Reconfiguration (Pre‑Release #2)

Date: 2025‑05‑25
Theme: Filesystem and documentation restructuring; hardware/software resets for cleaner iteration.
Highlights:

  • Reorganized repos (kernel builds, memory, services, UI).

  • Upgraded Debian base; standardized non‑free firmware policy.

  • Elevated Huey‑Portal (iMac 5K) as primary control/display; GNOME on Xorg baseline.

  • Introduced Huey‑Portable (BR1100FKA) as always‑connected LTE fallback.

  • Clarified governance: decentralized decision, unified memory (axiom locked).

  • Defined huey‑key partitioning (UEFI 1 GiB, swap 4 GiB, root 16 GiB, persistence 100 GiB, optional encrypted secrets).

  • Began migration toward AMD‑first GPU stack; Vulkan path vetted for local LLM.

Momentum Toward Oct‑31 (Pre‑Release #3)

Date: 2025‑10‑25
Focus: Setting the runway for the Oct‑31 upgrade.

  • Kernel target 6.17.x‑huey builds per host; remove splash; boot logs visible.

  • Python 3.14.x parallel install; dependency audit.

  • Forky staging; test containers; init package allowlist.

  • VNC/SSH workflow codified (1995 via SSH tunnel only).

  • Memory schema draft + provenance tags.

See Action Plan — Oct 31, 2025 for the concrete checklist.

Contributing

Development Environment

  • Debian 13/14 with build tools (see Getting Started).

  • Git LFS for large artifacts if needed.

  • EditorConfig enforced; 4‑space indent except YAML (2).

Branching & Commits

  • main is protected; PRs only.

  • Feature branches: feat/<area>-<short>; fixes: fix/<area>-<short>; infra: ops/<area>-<short>.

  • Conventional prefixes: feat:, fix:, docs:, ops:, perf:, refactor:.

Issues & PRs

  • Link to wiki page affected; include reproduction steps and logs.

  • PR checklist: builds pass; docs updated; provenance notes added.

Licensing

  • Code under GPL‑3.0.

  • Documentation/Media under CC‑BY‑SA‑4.0.

Troubleshooting & FAQ

APT signature complains about Edge repo

Re‑install key to /etc/apt/keyrings/ and ensure signed-by= is set (see Build Guides).

GNOME still shows login prompt; want auto‑login

Enable auto‑login in GDM (/etc/gdm3/daemon.conf) and ensure user is in autologin group.

iMac 5K audio missing or wrong default sink

Use the set-default-sink.sh post‑login script and verify PipeWire is active.

Vulkan path not active for Ollama

Check VK_ICD_FILENAMES and OLLAMA_LLM_LIBRARY=vulkan; run with VK_LOADER_DEBUG=all to confirm.

Stuck RAID superblocks after experiments

Use mdadm --zero-superblock on the exact partitions; rebuild initramfs.

Brightness stuck at low level on laptops

Write max value to the device under /sys/class/backlight/* and ensure kernel parameters don’t override.

Glossary

  • Cloud Pyramid — Huey’s governance framework (clauses, quorum, roles).

  • Huey‑Key — Bootable USB (UEFI) with custom kernel and persistence.

  • Spark/Zap — Bicameral AI cores for ideation/review.

  • Citizen — Specialized agent with voting role.

  • Worker — IO subsystem with no clause power.

  • Portal/Prime/Portable/Legacy/Hub — Node roles in the ecosystem.

Page Templates

Use these skeletons to create consistent pages.

Generic Page

# Title

> [!NOTE]
> One‑line purpose.


Summary


Short paragraph.


Details


    

  • Point 1
    • 

  • Point 2
    • 



References


    

  • Link A
    • 

  • Link B

    •

How‑To / Guide

# Task Title

Prereqs


    

  • OS / version
    • 

  • Packages
    • 



Steps


    

  1. ...
    2. 

  2. ...
    3. 



> [!WARNING]
> Reversible? Backup step here.


Verify


    

  • Check output …

    •

Decision Record (ADR)

# ADR‑NNN: Title

Date: YYYY‑MM‑DD
Status: Proposed | Accepted | Superseded by ADR‑MMM


Context


Why this decision matters.


Decision


What we chose and why.


Consequences


    

  • Positive
    • 

  • Negative
    • 



Alternatives


    

  • Option A
    • 

  • Option B

    •

Publishing Kit

Use this to push the wiki with correct filenames, sidebar/footer, and assets.

File Map (Wiki names → Filenames)

  • Home → Home.md

  • _Sidebar → _Sidebar.md

  • _Footer → _Footer.md

  • Getting Started → Getting-Started.md

  • Architecture → Architecture.md

  • Hardware → Hardware.md

  • Software Stack → Software-Stack.md

  • Build Guides → Build-Guides.md

  • Governance & Constitution → Governance-and-Constitution.md

  • Memory & Data Model → Memory-and-Data-Model.md

  • Remote Access (VNC/SSH) → Remote-Access-(VNC-SSH).md

  • Action Plan — Oct 31, 2025 → Action-Plan-—-Oct-31-2025.md

  • Roadmap & Pre‑Releases → Roadmap-and-Pre-Releases.md

  • Contributing → Contributing.md

  • Troubleshooting & FAQ → Troubleshooting-and-FAQ.md

  • Glossary → Glossary.md

  • Page Templates → Page-Templates.md

  • Publishing Kit → Publishing-Kit.md

One‑Shot Publish (replace /)

repo="https://github.com/<USER>/<REPO>.wiki.git"

1) clone wiki repo


rm -rf MHP-wiki && git clone "$repo" MHP-wiki && cd MHP-wiki


2) create pages


cat > "Home.md" <<'MD'
{{ paste the Home section from this document }}
MD


cat > "_Sidebar.md" <<'MD'
{{ paste the _Sidebar section }}
MD


cat > "_Footer.md" <<'MD'
{{ paste the _Footer section }}
MD


...repeat for each page using the File Map above...


3) optional assets directory


mkdir -p assets/diagrams assets/images


Example mermaid page embeds directly; images can be dropped into assets/images


4) commit & push


git add .
git commit -m "docs(wiki): initialize Monkey-Head-Project wiki (2025-10-25)"
git push origin main || git push origin master || git push

Tip

In GitHub wikis, headings automatically get linkable anchors. Use [See Hardware](Hardware#node-roster) style links.

Note

Redirects: GitHub wikis don’t support true redirects; create a short page that links to the new one when renaming.

# Home

Project: Monkey‑Head‑Project (HueyOS) Author: Dylan L. R. Pollock Official site: https://www.dlrp.ca/ License: Code: GPL‑3.0 • Docs/Media: CC‑BY‑SA‑4.0 Status Date: 2025‑10‑25

HueyOS is a modular AI/OS for robotics that blends retro‑computing aesthetics with modern Linux, clustered compute, and a constitutional governance model (Cloud Pyramid). The system prefers offline operation with optional API use, emphasizes lifelong learning, and keeps governance decentralized while memory stays unified.

Note

Heads‑up: A major software update lands October 31, 2025 (kernel jump to 6.17.x, Python 3.14, Debian Forky pathfinders, memory stack, governance refinements). Track Action Plan — Oct 31, 2025.

Table of Contents

_Sidebar

_Footer

© Dylan L. R. Pollock. Code under GPL‑3.0; docs/media under CC‑BY‑SA‑4.0. Last updated: 2025‑10‑25. Found an issue? Open one in the main repo and link the affected wiki page.

Getting Started

Supported Targets (current focus)

  • Debian 13 (Trixie) — baseline; UEFI‑only; amd64.
  • Debian 14 (Forky) — staged adoption for Oct‑31 update.
  • Linux Kernels: 6.16.x‑huey (current), 6.17.x‑huey (incoming).

Minimal Install

  1. Install Debian (UEFI, amd64). Choose GNOME on Xorg for iMac 5K targets.
  2. Enable non‑free firmware (Realtek, Intel, etc.).
  3. Create user dlrp (or custom) and enable sudo.
  4. Network: prefer bonded Ethernet → Wi‑Fi as fallback.
  5. Post‑install: apt update && apt full-upgrade.

Tip

For reproducibility, snapshot /etc/ and /boot/ after first login.

Core Packages (baseline)

sudo apt install -y build-essential bc bison flex libelf-dev libssl-dev \
  libncurses-dev dwarves pahole rsync xz-utils cpio kmod python3 \
  git wget curl ca-certificates gnupg debian-goodies \
  firmware-linux firmware-misc-nonfree firmware-iwlwifi firmware-realtek

Optional Userland

  • Ollama (local LLMs; Vulkan/ROCm as available)
  • PyGPT-net (agent runner)
  • Microsoft Edge (Beta) for dev/test

See Build Guides for signed repo keys and signature‑policy troubleshooting.

Architecture

Huey’s architecture is a layered federation aligning compute, memory, and governance.

flowchart TB
  A[Huey — Sovereign Consciousness]:::c1
  B1[Spark
Creative / GPU‑1]:::c2
  B2[Zap
Evaluative / GPU‑2]:::c3
  C[Citizen Populace
256 agents (128/128)]:::c4
  D[Worker Subsystems
NanoOS/SubOS, IO]:::c5
  A --> B1
  A --> B2
  B1 --> C
  B2 --> C
  C --> D
  classDef c1 fill:#111,stroke:#5cf,stroke-width:1px,color:#fff
  classDef c2 fill:#0b3,stroke:#0b3,color:#fff
  classDef c3 fill:#b30,stroke:#b30,color:#fff
  classDef c4 fill:#333,stroke:#999,color:#fff
  classDef c5 fill:#222,stroke:#666,color:#fff
Loading

Layers

  1. Huey as Sovereign Consciousness — emergent, lawful decision + inaction boundary.
  2. Binary Brain — Spark (creative, GPU‑1) and Zap (evaluative, GPU‑2) form a bicameral AI core.
  3. Citizen Populace — 256 AI instances (128 per core) as civic units with voting/operational roles.
  4. Worker Subsystems — NanoOS/SubOS services for sensors, limbs, and IO without clause power.

Principles

  • Decentralized governance, unified memory.
  • Offline‑first; API‑capable.
  • Traceable action history; reproducible system state.
  • Clear separation: governance vs. actuation; data vs. policy.

Important

Decisions and inactions both carry provenance and must be logged.

Hardware

Node Roster

Node Role Key Specs Status
Huey Prime Orchestration hub Thermaltake ATX case; ITX BD795I‑SE (Ryzen 9 7945HX); DDR5‑5200; dual Intel Optane M10 16 GB NVMe; GPU: RX 5500 XT 8 GB → MI50 planned Active
Huey‑Legacy (Shell) On hold; file hub candidate Supermicro X9QRI‑F+ quad‑Xeon; 10 GbE NIC; GPUs; RAID SSDs Paused
Huey‑Portal Universal display/control iMac 5K (2017), 48 GB RAM, Debian Trixie, GNOME/Xorg Active
Huey‑Portable Portable node (LTE) ASUS BR1100FKA 11.6", N4500/4 GB/LTE, Debian Trixie Active
Huey‑Hub File hand‑off 2017 MacBook Pro (Win10 bare‑metal) + WD MyBook Duo ~10 TB mirror Active

Remote Intent & Action

  • RF Remote (IC2262/2272) → Arduino UNO (USB symbolic intents: LISTEN, VOTE:YES/NO).
  • Arduino Mega 2560 → motors/sensors (PWM/I²C).
  • Arduino Nanos → localized LED/analog/PWM conditioning.

Display

  • iMac 5K (Portal) + 27" Samsung C27F396 portrait (torso). Future: Neo C128 board for VIC‑II/SID.

Network

  • Router: ASUS GT‑AC5300 (link aggregation). Preferred: bonded Ethernet; Wi‑Fi fallback.

Software Stack

  • OS: Debian 13 (Trixie) → Debian 14 (Forky) adoption begins Oct‑31.
  • Kernel: 6.16.x‑huey → 6.17.x‑huey (custom; perf‑oriented; targeted drivers).
  • AI: Ollama (local LLMs; Mistral‑7B quant), PyGPT‑net agents; Whisper STT; TTS module.
  • UI: Minimalist green‑on‑black; two‑pane logic (conscious voice vs verbose logs).
  • Memory: JSON logs + SQLite; unified store; long‑term persistence.
  • Security: SSH keys; optional default lab key (rotatable); fallback LIVE USB.

Folder Conventions

/huey/
  bin/           # launchers + maintenance scripts
  kernels/       # packaged kernels, configs, build logs
  memory/        # sqlite, json logs, vectors (later)
  services/      # systemd units, timers
  ui/            # themes, boot assets, display scripts
  docs/          # project docs (this wiki mirrors)

Build Guides

Kernel 6.17.x‑huey (generic; adjust per target)

# deps (see Getting Started for base set)
sudo apt install -y fakeroot kmod pahole flex bison libelf-dev libssl-dev \
  libncurses-dev bc rsync xz-utils cpio python3

# source (example)
wget https://cdn.kernel.org/pub/linux/kernel/v6.x/linux-6.17.5.tar.xz
 tar -xf linux-6.17.5.tar.xz && cd linux-6.17.5

# seed config from running kernel, then refresh
cp -v /boot/config-$(uname -r) .config
yes "" | make olddefconfig

# huey perf toggles (examples; tune per target)
./scripts/config --disable DEBUG_INFO --disable DEBUG_INFO_BTF \
  --disable KASAN --disable UBSAN --disable KCOV --disable FUNCTION_TRACER \
  --enable ZSTD --enable RD_ZSTD --enable EFI --enable EFI_STUB --enable EFI_VARS

# build Debian packages
make -j$(nproc) bindeb-pkg

# install
sudo dpkg -i ../linux-image-6.17.5-*.deb ../linux-headers-6.17.5-*.deb
sudo update-initramfs -c -k 6.17.5
sudo update-grub

iMac 5K (2017) notes

  • GNOME on Xorg recommended.
  • Force display mode via kernel cmdline if needed (HDMI‑A‑1 1080p60 while booting).
  • Audio: prefer PipeWire; set default sink on boot.
# set default HDA PCH sink after login
mkdir -p ~/.local/bin
cat > ~/.local/bin/set-default-sink.sh <<'EOF'
#!/usr/bin/env bash
sleep 3
SINK=$(pactl list short sinks | awk '/pci-0000_00_1f\.3.*analog/ {print $1; exit}')
[ -n "$SINK" ] && pactl set-default-sink "$SINK" && pactl set-sink-mute "$SINK" 0 && pactl set-sink-volume "$SINK" 60%
EOF
chmod +x ~/.local/bin/set-default-sink.sh

Remove Splash / Show Boot Logs

sudo sed -i 's/GRUB_CMDLINE_LINUX_DEFAULT=.*/GRUB_CMDLINE_LINUX_DEFAULT="loglevel=4 systemd.show_status=1"/' /etc/default/grub
sudo update-grub

Microsoft Edge (Beta) repo key (sqv policy compliant)

sudo install -d -m0755 /etc/apt/keyrings
wget -qO- https://packages.microsoft.com/keys/microsoft.asc | \
  gpg --dearmor | sudo tee /etc/apt/keyrings/microsoft.gpg >/dev/null

echo "deb [arch=amd64 signed-by=/etc/apt/keyrings/microsoft.gpg] \
https://packages.microsoft.com/repos/edge stable main" | \
  sudo tee /etc/apt/sources.list.d/microsoft-edge.list >/dev/null

sudo apt update

RAID Superblock Cleanup (when reverting experiments)

cat /proc/mdstat
sudo mdadm --detail --scan
lsblk -o NAME,TYPE,SIZE,MOUNTPOINTS

# stop any auto-assembled arrays
sudo mdadm --stop --scan || true

# find and remove stale superblocks (replace partitions with actual ones)
sudo mdadm --examine /dev/nvme0n1p3 && sudo mdadm --zero-superblock /dev/nvme0n1p3
sudo mdadm --examine /dev/mmcblk0p3 && sudo mdadm --zero-superblock /dev/mmcblk0p3

echo 'AUTO -all' | sudo tee /etc/mdadm/mdadm.conf
sudo update-initramfs -u

Ollama on AMD (force RADV/Vulkan)

export VK_ICD_FILENAMES=/usr/share/vulkan/icd.d/radeon_icd.x86_64.json
export OLLAMA_LLM_LIBRARY=vulkan
export VK_LOADER_DEBUG=all
export OLLAMA_DEBUG=1
ollama serve

Huey‑Portable: Default Deep Sleep

echo 'MEM_SLEEP_DEFAULT=deep' | sudo tee /etc/default/mem-sleep >/dev/null
sudo tee /usr/local/sbin/set-mem-sleep.sh >/dev/null <<'EOF'
#!/usr/bin/env bash
set -euo pipefail
want=$(awk -F= '/^MEM_SLEEP_DEFAULT=/{print $2}' /etc/default/mem-sleep 2>/dev/null || echo deep)
avail=$(cat /sys/power/mem_sleep 2>/dev/null || echo "")
case "$avail" in *"$want"*) echo "$want" | tee /sys/power/mem_sleep >/dev/null || true;; esac
EOF
sudo chmod +x /usr/local/sbin/set-mem-sleep.sh
sudo tee /etc/systemd/system/mem-sleep-default.service >/dev/null <<'EOF'
[Unit]
Description=Set default mem sleep (deep or s2idle)
After=local-fs.target
[Service]
Type=oneshot
ExecStart=/usr/local/sbin/set-mem-sleep.sh
[Install]
WantedBy=multi-user.target
EOF
sudo systemctl enable --now mem-sleep-default.service

Warning

Kernel work can brick a boot. Keep the LIVE USB entry active and tested.

Governance & Constitution

Cloud Pyramid (Summary)

  • Clause‑based activation: policies trigger agent powers.
  • Quorum: decisions from Spark/Zap + citizens; deterministic tie‑breakers.
  • Separation: governance (what should) vs actuator (what is done).
  • Auditability: all decisions and inactions logged with reasons.

Roles

  • Spark — ideation, exploration, generative planning.
  • Zap — review, constraint, safety, resource stewardship.
  • Citizens — specialized agents (perception, planning, controls).
  • Workers — real‑time IO modules; no clause power.

Memory & Data Model

Unification mandate: One coherent memory across agents.

Stores

  • SQLite — structured facts, events, decisions.
  • JSON Logs — append‑only chronological traces.
  • Artifacts — model weights, kernels, configs, build logs.

IDs & Traceability

  • HUEY-<YYYYMMDD>-<PHASE>-<SEQ> for releases.
  • EVT-<timestamp>-<agent> for event logs.
  • Provenance fields for all artifacts.

[^persist]: Persistence store also includes optional encrypted “secrets” slice.

Remote Access (VNC/SSH)

Preference: TigerVNC on huey‑legacy (GNOME on Xorg).

  • Server bound localhost:1995, no prompt (-SecurityTypes None), SSH tunnel only.
  • Client helper vnc command on huey‑portal maps :1 → 1995.
  • Default res: 2560×1440. Avoid DeferUpdate; prefer RawKeyboard.

See ~/bin/vnc alias and huey-vnc convenience command in your shell profile.

Action Plan — Oct 31, 2025

A checklist designed to be fed item‑by‑item into automation or CI (e.g., “codex”).

Kernel & OS

  • Build and package linux‑image‑6.17.x‑huey for: Huey‑Portal (iMac 5K), Huey‑Portable (BR1100FKA), Huey Prime (BD795I‑SE).
  • Validate boot (GRUB cmdline, early modeset, 1080p60 during boot, splash removed).
  • Smoke‑test audio (PipeWire default sink script on login).
  • Stage Debian 14 (Forky) APT sources (kept disabled); test packages in chroot/container.
  • Finalize EFI LIVE fallback USB entry (GRUB menu integration).

Python & Runtime

  • Install Python 3.14.x side‑by‑side; build wheels for key deps.
  • Run PyGPT‑net on 3.14; document incompatibilities/workarounds.
  • Refresh requirements-*.txt.

AI/Agents

  • Confirm Mistral‑7B quant works under Vulkan on RX 470 / 5500 XT.
  • Add Whisper STT + TTS pipeline scripts; test latency on Huey‑Portable.
  • Wire Spark/Zap boot choreography; log quorum outcomes.

Memory

  • Migrate unified memory schema (SQLite + JSON log rollover policy).
  • Implement provenance tagging for builds and decisions.

Security & Keys

  • Rotate default lab SSH key; populate huey-keys/ with new default + staged personal key.
  • Enable passwordless SSH where intended; restrict root login post‑install.

Tooling

  • Fix Edge Beta signing policy (install key to /etc/apt/keyrings/).
  • Add huey-run.desktop launcher for PyGPT (user scope).
  • Document vnc helper and SSH tunnel recipe.

Docs

  • Update README.md and this Wiki with Oct‑31 deltas.
  • Publish Pre‑Release #3 (2025‑10‑25) summary and link to Action Plan.
  • Post “stay tuned” banner on dlrp.ca.

Roadmap & Pre‑Releases

Phase 1 — Foundations (Pre‑Release #1)

Date: 2024‑04‑11

  • Baseline hardware bring‑up (VIC‑20/C64/C128 references).
  • GenCore seed; basic learning modules.
  • Prototype shell mapping (interfaces, wiring paths).

System Reconfiguration (Pre‑Release #2)

Date: 2025‑05‑25 Theme: Filesystem and documentation restructuring; hardware/software resets for cleaner iteration. Highlights:

  • Reorganized repos (kernel builds, memory, services, UI).
  • Upgraded Debian base; standardized non‑free firmware policy.
  • Elevated Huey‑Portal (iMac 5K) as primary control/display; GNOME on Xorg baseline.
  • Introduced Huey‑Portable (BR1100FKA) as always‑connected LTE fallback.
  • Clarified governance: decentralized decision, unified memory (axiom locked).
  • Defined huey‑key partitioning (UEFI 1 GiB, swap 4 GiB, root 16 GiB, persistence 100 GiB, optional encrypted secrets).
  • Began migration toward AMD‑first GPU stack; Vulkan path vetted for local LLM.

Momentum Toward Oct‑31 (Pre‑Release #3)

Date: 2025‑10‑25 Focus: Setting the runway for the Oct‑31 upgrade.

  • Kernel target 6.17.x‑huey builds per host; remove splash; boot logs visible.
  • Python 3.14.x parallel install; dependency audit.
  • Forky staging; test containers; init package allowlist.
  • VNC/SSH workflow codified (1995 via SSH tunnel only).
  • Memory schema draft + provenance tags.

See Action Plan — Oct 31, 2025 for the concrete checklist.

Contributing

Development Environment

  • Debian 13/14 with build tools (see Getting Started).
  • Git LFS for large artifacts if needed.
  • EditorConfig enforced; 4‑space indent except YAML (2).

Branching & Commits

  • main is protected; PRs only.
  • Feature branches: feat/<area>-<short>; fixes: fix/<area>-<short>; infra: ops/<area>-<short>.
  • Conventional prefixes: feat:, fix:, docs:, ops:, perf:, refactor:.

Issues & PRs

  • Link to wiki page affected; include reproduction steps and logs.
  • PR checklist: builds pass; docs updated; provenance notes added.

Licensing

  • Code under GPL‑3.0.
  • Documentation/Media under CC‑BY‑SA‑4.0.

Troubleshooting & FAQ

APT signature complains about Edge repo

Re‑install key to /etc/apt/keyrings/ and ensure signed-by= is set (see Build Guides).

GNOME still shows login prompt; want auto‑login

Enable auto‑login in GDM (/etc/gdm3/daemon.conf) and ensure user is in autologin group.

iMac 5K audio missing or wrong default sink

Use the set-default-sink.sh post‑login script and verify PipeWire is active.

Vulkan path not active for Ollama

Check VK_ICD_FILENAMES and OLLAMA_LLM_LIBRARY=vulkan; run with VK_LOADER_DEBUG=all to confirm.

Stuck RAID superblocks after experiments

Use mdadm --zero-superblock on the exact partitions; rebuild initramfs.

Brightness stuck at low level on laptops

Write max value to the device under /sys/class/backlight/* and ensure kernel parameters don’t override.

Glossary

  • Cloud Pyramid — Huey’s governance framework (clauses, quorum, roles).
  • Huey‑Key — Bootable USB (UEFI) with custom kernel and persistence.
  • Spark/Zap — Bicameral AI cores for ideation/review.
  • Citizen — Specialized agent with voting role.
  • Worker — IO subsystem with no clause power.
  • Portal/Prime/Portable/Legacy/Hub — Node roles in the ecosystem.

Page Templates

Use these skeletons to create consistent pages.

Generic Page

# Title

> [!NOTE]
> One‑line purpose.

## Summary
Short paragraph.

## Details
- Point 1
- Point 2

## References
- Link A
- Link B

How‑To / Guide

# Task Title

## Prereqs
- OS / version
- Packages

## Steps
1. ...
2. ...

> [!WARNING]
> Reversible? Backup step here.

## Verify
- Check output …

Decision Record (ADR)

# ADR‑NNN: Title

Date: YYYY‑MM‑DD
Status: Proposed | Accepted | Superseded by ADR‑MMM

## Context
Why this decision matters.

## Decision
What we chose and why.

## Consequences
- Positive
- Negative

## Alternatives
- Option A
- Option B

Publishing Kit

Use this to push the wiki with correct filenames, sidebar/footer, and assets.

File Map (Wiki names → Filenames)

  • Home → Home.md
  • _Sidebar → _Sidebar.md
  • _Footer → _Footer.md
  • Getting Started → Getting-Started.md
  • Architecture → Architecture.md
  • Hardware → Hardware.md
  • Software Stack → Software-Stack.md
  • Build Guides → Build-Guides.md
  • Governance & Constitution → Governance-and-Constitution.md
  • Memory & Data Model → Memory-and-Data-Model.md
  • Remote Access (VNC/SSH) → Remote-Access-(VNC-SSH).md
  • Action Plan — Oct 31, 2025 → Action-Plan-—-Oct-31-2025.md
  • Roadmap & Pre‑Releases → Roadmap-and-Pre-Releases.md
  • Contributing → Contributing.md
  • Troubleshooting & FAQ → Troubleshooting-and-FAQ.md
  • Glossary → Glossary.md
  • Page Templates → Page-Templates.md
  • Publishing Kit → Publishing-Kit.md

One‑Shot Publish (replace /) 

repo="https://github.com/<USER>/<REPO>.wiki.git"

# 1) clone wiki repo
rm -rf MHP-wiki && git clone "$repo" MHP-wiki && cd MHP-wiki

# 2) create pages
cat > "Home.md" <<'MD'
{{ paste the Home section from this document }}
MD

cat > "_Sidebar.md" <<'MD'
{{ paste the _Sidebar section }}
MD

cat > "_Footer.md" <<'MD'
{{ paste the _Footer section }}
MD

# ...repeat for each page using the File Map above...

# 3) optional assets directory
mkdir -p assets/diagrams assets/images
# Example mermaid page embeds directly; images can be dropped into assets/images

# 4) commit & push
git add .
git commit -m "docs(wiki): initialize Monkey-Head-Project wiki (2025-10-25)"
git push origin main || git push origin master || git push

Tip

In GitHub wikis, headings automatically get linkable anchors. Use [See Hardware](Hardware#node-roster) style links.

Note

Redirects: GitHub wikis don’t support true redirects; create a short page that links to the new one when renaming.

Clone this wiki locally