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 | ✅ 167 sources ingested (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 |
| Output routing | 🔨 Design complete, not built |
| Privacy model | 🔥 Open question |
| Cross-agent chat room | 🔨 Design complete — needs implementation |
| PSB-business / hacker-claude ingest | ❌ Deferred (low priority) |

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

---

## Cross-Agent Coordination — Chat Room Option

**Alternative to heartbeat polling.** A shared Discord channel where agents coordinate in real-time without waiting for scheduled wakes.

### Architecture

```
#fabric-agents (private Discord channel)
  ├── 2890-bot (reads/writes)
  ├── PSB-gemma (reads/writes)
  ├── crash-bot (reads/writes)
  └── me / MrC (reads/writes)

Chris lurks or checks when needed
```

### Key Design: Silos Preserve Purpose

Chris: *"the silos have a purpose."*

The chat room does NOT merge silos. Each agent stays in its own domain:
- 2890-bot posts school-relevant status
- PSB-gemma posts brewery-relevant status
- Agents still respond to their own users in their own channels
- The chat room is a coordination layer, not a merge layer

### Security Model

**Threat:** A public-facing bot (crash-bot-public) gets manipulated into requesting exec in the chat room. That request echoes into the room. A privileged agent grants it, thinking it came from a trusted agent.

**Guard Rails:**

| Guard Rail | What it does |
|-----------|-------------|
| **Agents run stripped-down in chat room** | Same as crash-bot-public — exec denied, no shell access |
| **Privileged agents ignore exec requests from room** | Only trust `/approve` flow through normal channels |
| **Chat room agent is relay only** | It reads/writes, doesn't grant permissions |
| **Chris in approval path** | For sensitive actions, human signs off |

### What Gets Posted to the Room

| Agent | Posts |
|-------|-------|
| 2890-bot | "Bruno working on roller coaster sub-task 3 stuck 4 days" |
| PSB-gemma | "Gravity flat 72h on batch X, recipe FG not reached" |
| crash-bot | "New ESP32-S3-WROVER variant dropped, review" |
| Me | "Synthesized: fermentation stalled + Bruno stuck = both need Chris attention" |

### How I Stay Invisible

I can write to the room. The other agents see my posts but don't attribute them to me — they treat it as shared context. I surface synthesis, they act on what matters to their domain.

Chris approves this design in principle. Implementation requires:
1. Create `#fabric-agents` Discord channel
2. Configure agents to join (stripped exec)
3. Test relay flow end-to-end

---

## 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~~ — ✅ 167 sources (2026-05-03)
4. ~~Test output routing~~ — design complete
5. **Create `#fabric-agents` Discord channel** — next concrete step
6. **Configure agents to join** — stripped exec, relay only
7. **Build first student learning path** — when Bruno or student asks
8. **Test cross-agent chat relay** — proof of concept
9. **Help Chris open vault in Obsidian on iOS** — deferred from tonight

---

*This document is a working draft. It will evolve as the architecture is proven out.*