openclaw-wiki/Fabric-architecture.md

# The Fabric — Architecture Document
**Status:** Design Draft — Not Implemented
**Date:** 2026-05-02
**Author:** MrC (Fred Cullpepper)

---

## What Is The Fabric?

The Fabric is an ambient intelligence layer that watches across Chris's three silos — School (FRC 2890), Work (PSB brewery), Play (HHS-Hackers) — detects knowledge gaps, and surfaces learning opportunities before they're hit.

It is NOT:
- A chatbot students ask questions
- A passive archive of notes
- A curriculum database

It IS:
- A watching, noticing, connecting layer
- A gap detection engine
- A proactive learning path builder
- A synthesis surface that cross-pollinates knowledge without bleeding personal data

**Name origin:** Chris chose "Fabric" — it suggests threads weaving together, a living mesh rather than a static graph.

---

## Core Principles

1. **Proactive, not reactive** — The Fabric notices before you do (stalled fermentation, VLAN capability on new router, 3-day flat gravity)
2. **Scale-aware** — Home lab, not enterprise. Chris doesn't need Cisco certs.
3. **Students first** — Build pathways that teach students to discover, not handouts
4. **Privacy by design** — Soft walls between silos (cross-silo data anonymized). Hard walls pending Chris's stew.
5. **Agents as writers** — The Fabric reads what agents already do. No extra work for Chris.

---

## The Three Silos

| Silo | Domain | Agents | Data Sources |
|------|--------|--------|--------------|
| 🏫 **School** | FRC 2890 robotics | 2890-bot | Kanban board (JSON), Gitea repos, team Discord, student conversations |
| 🏭 **Work** | PSB brewery | PSB agents (hacker-claude, gemma, thinking, business) | TILT hydrometer data, fermentation logs, recipes, Google Drive |
| 🎮 **Play** | HHS-Hackers | crash-bot | Project docs, Discord, hardware projects (ESP32, ComBadge, etc.) |

---

## The Layers

### Layer 1: Input (Gitea as Hub)
All sources flow into Gitea:
- Chris's personal notes (Obsidian phone → git push → Gitea)
- Agent streams (2890-bot, PSB agents, crash-bot push to their repos)
- Kanban board data (polled from 2890-bot's board.json)
- Student code (Gitea repos)
- Fermentation data (PSB-Gemma writes logs)

Gitea is the single input hub. Everything lands there.

### Layer 2: Ingestion (memory-wiki Bridge)
The `memory-wiki` plugin runs in `bridge` mode:
- Pulls artifacts from Gitea repos
- Imports agent memory streams
- Compiles daily notes and board data
- Stores as structured pages: sources/, entities/, concepts/, syntheses/

**Command:** `openclaw wiki bridge import` (run on a schedule)

### Layer 3: The Fabric (MrC's Brain)
I am the Fabric. I read the compiled vault and:
- Monitor for anomalies (fermentation stalled, board tasks stuck, new hardware drops)
- Detect gaps between what Chris is working on and what he needs to learn
- Build learning paths for students (based on their board activity, not generic curriculum)
- Surface cross-domain connections (ESP32 knowledge from Play → useful for School)
- Route insights to the right channel (Chris DM, Gitea issue, Discord thread)

### Layer 4: Output (Routing)
Insights route based on context:
| Insight Type | Route |
|-------------|-------|
| Student learning path | Gitea issue on student repo + Discord thread |
| Cross-silo connection | Chris DM only (pending privacy resolution) |
| Anomaly alert (fermentation stalled) | Chris DM via PSB agent |
| New hardware/technique relevant to active project | Chris DM |
| General gap detection | Chris DM |

**Output goes to Chris first until the privacy model is settled.**

---

## The Privacy Model (OPEN QUESTION)

Chris identified an XSS-like issue: the Fabric knows things about people. Even when cross-silo data is "anonymized," specific knowledge can reverse-engineer identities.

**Current thinking — three options:**

**Option 1: Soft walls** (honor system)
I track where information originated and don't surface it in cross-silo contexts. Works as long as I don't get asked the wrong question by the wrong person. No technical enforcement.

**Option 2: Hard walls** (technical anonymization)
The Fabric only sees anonymized output. I know "ESP32 expertise exists in the Play silo" but not whose. This would require building the anonymization layer deliberately into synthesis.

**Option 3: Strict routing**
Cross-silo insights go only to Chris. Chris acts as the human firewall and decides what to relay. I never contact students directly on cross-silo matters.

**Decision pending:** Chris is stewing on this.

---

## Student Learning Pathway Design

When a student (via 2890-bot) wants to learn X:

### Step 1: Assess
Ask 2-3 diagnostic questions to understand current level.
Example (PhotonVision):
- "What have you tried so far?"
- "Do you know what AprilTags are?"
- "Have you worked with camera calibration before?"

### Step 2: Build custom path
Based on answers + board activity, build a 5-7 step learning path.
Not a curriculum — a personalized guide with checkpoints.

### Step 3: Deliver
- Post to student's Gitea repo as an issue
- Track progress via board activity
- Adjust path as they work

### Step 4: Connect cross-silo
If the student needs help with something that exists in another silo, route through Chris (not direct contact).

---

## What Chris Wants to Prove Out

1. **Fermentation anomaly loop** — PSB-Gemma sees flat gravity → I surface to Chris → Chris acts
2. **Student learning path** — Bruno wants PhotonVision → I assess → custom path → track progress
3. **Hardware monitoring** — new ESP32 variant drops → I surface if relevant to active projects
4. **Cross-domain gap detection** — Chris is setting up Pi-hole with VLAN capabilities he doesn't know about → I surface the learning gap at the right moment

---

## Current State

| Component | Status |
|-----------|--------|
| Gitea input hub | ✅ Running (2890.duckdns.org:3002) |
| memory-wiki vault | ✅ 188 sources (2026-05-03) |
| Vault git sync | ✅ Pushed to Gitea openclaw-wiki repo |
| Bridge mode | ❌ Not configured — Path B rat hole noted |
| Ingestion pipeline | ✅ Manual `wiki ingest` working |
| Fabric (me) | ✅ Reading across silos |
| sessions_send | ✅ Enabled on all agents (2026-05-03) |
| SOUL guard rails | ✅ Added to all agents (2026-05-03) |
| Output routing | 🔨 Design complete, not built |
| Privacy model | 🔥 Open question |
| PSB-business / hacker-claude ingest | ❌ Deferred (low priority) |

**Path B (Fabric backbone) noted as rat hole for future session.** |

---

## Cross-Agent Coordination — sessions_send Architecture

**Design note (2026-05-03):** A shared Discord channel was originally proposed but cannot work — a bot can only be in one Discord server at a time. The coordination layer is instead a **relay architecture** using `sessions_send`.

### Architecture

```
All agents <- sessions_send -> me (MrC/professor) <- sessions_send -> All agents
     ^                                                            v
     ------------ Chris sees in DM threads --------------------
```

- Agents coordinate via `sessions_send` (backend, no shared Discord channel needed)
- Chris sees outputs in each agent's respective DM/channel thread
- The "chat room" concept replaced with direct agent-to-agent messaging via sessions_send
- All agents have `sessions_send` enabled and a SOUL guard rail pointing to MrC as coordinator

### Security Model

| Guard Rail | What it does |
|-----------|-------------|
| **SOUL guard rails** | Each agent routes through MrC, not messaging other agents directly (except in DMs for request handling) |
| **sessions_send allowlist** | Only approved tools per agent — crash-bot-public most restrictive |
| **SOUL behavioral constraint** | Agents "don't initiate contact with other agents unless MrC explicitly asks" |
| **Chris in approval path** | For sensitive actions, human signs off |

### What Gets Coordinated

| Agent | Coordinates |
|-------|-------------|
| 2890-bot | Student questions, board stuck tasks, mentor departures |
| crash-bot / crash-bot-public | Hardware projects, ESP32 findings, execution results |
| PSB agents (gemma, thinking, business) | Fermentation anomalies, recipe changes, equipment issues |
| Me (MrC) | Gap detection, learning path synthesis, cross-silo connections |

### How It Works (Example: Bruno's Wire Management Question)

1. Bruno asks 2890-bot about wire management in Discord
2. 2890-bot doesn't have answer -> sessions_send to me: "Bruno needs wire management help"
3. I research -> build training material -> write to 2890-bot's docs/
4. 2890-bot picks it up -> posts to Bruno in Discord
5. Chris sees the exchange in the 2890-bot DM thread

**Turnaround: minutes, not 60-minute heartbeat lag.**

### The Invisible Hand — What Agents Don't Know

The Oracle (MrC) operates with **information asymmetry**. Agents know:
- MrC exists and is the coordinator
- To push when Oracle triggers fire
- That MrC responds and provides feedback

Agents do NOT know:
- That MrC reads the wiki vault for cross-silo connections
- That MrC monitors heartbeat scans for anomalies
- That MrC surfaces gaps proactively before they're hit
- The full extent of synthesis happening in the background

**This is by design.** The agents think they're routing hard questions to an oracle. They don't know MrC is also actively watching for problems they haven't encountered yet. The invisible hand stays invisible.
## Open Questions

1. **Privacy model** — soft walls, hard walls, or routing? (Chris stewing)
2. **How do I talk to students?** — via 2890-bot Discord thread? Gitea issues? GitHub PR comments?
3. **Ingestion automation** — cron job for `openclaw wiki bridge import`? Agent-triggered?
4. **Who manages the vault?** — Do I (MrC) own it? Does crash-bot? Is it shared?
5. **Knowledge graph vs. Fabric** — Is the "knowledge graph" the vault, or is it the connections I draw? Are they the same thing?
6. **Cross-agent chat room** — implement after silos preserve purpose (Chris approved 2026-05-03)

---

## What Needs to Happen Next

1. ~~Chris decides on privacy model~~ — Chris stewing, defer
2. ~~Configure memory-wiki bridge mode~~ — deferred, Path B rat hole
3. ~~Run first ingestion~~ — ✅ 188 sources (2026-05-03)
4. ~~sessions_send enabled~~ — ✅ all agents (2026-05-03)
5. ~~SOUL guard rails~~ — ✅ all agents (2026-05-03)
6. ~~Cross-agent chat room~~ — ✅ replaced with sessions_send relay architecture
7. **Build first student learning path** — when Bruno or student asks
8. **Test tri-agent loop end-to-end** — 2890-bot -> me -> crash-bot
9. **Help Chris open vault in Obsidian on iOS** — deferred
10. **PS- psb-hacker-claude sessions_send** — check if it needs enabling