1  # AURYN
  2  
  3  AURYN is the cultivation layer of DreamOS. Named after the Ouroboros amulet from The Neverending Story - "Do what you will."
  4  
  5  ## What AURYN Is
  6  
  7  AURYN is a **knowledge topology and cultivation system**, not an agentic framework. This distinction is fundamental.
  8  
  9  The entire AI industry is building better execution tools — faster coding agents, more autonomous frameworks, better tool orchestration. AURYN is orthogonal to all of this. It occupies the **vision-to-maturity lifecycle**: planting seeds (creating DreamNodes), nurturing soil (growing READMEs through conversation and reflection), weaving relationships (DreamSongs), and collective gardening (cherry-pick sovereignty, liminal web, coherence beacons).
 10  
 11  AURYN is three things at once:
 12  
 13  1. **The template** - what makes a DreamNode a DreamNode (hooks, config, agentic essence)
 14  2. **The copilot** - semantic search, context awareness, voice-to-action
 15  3. **The interface** - MCP tools / CLI for AI agents to work with DreamNodes
 16  
 17  When you create a new DreamNode, AURYN gives itself to creation. The template copies, the new node inherits AURYN's essence while AURYN remains whole. The strange loop.
 18  
 19  ### Transcend and Include
 20  
 21  AURYN's relationship to agentic frameworks (Claude Code, OpenCode, Codex CLI, OpenClaw, and whatever emerges tomorrow) follows the principle: **don't compete, transcend and include.**
 22  
 23  The core four of the agentic age are: **context, model, prompt, tools.** DreamNodes are universal vehicles containing any conceivable form of tools (CLI), context (files), and prompts (also files). These are orthogonal to agentic shells — any shell can work with DreamNodes.
 24  
 25  The architectural test: **if a new capability announced tomorrow causes anxiety rather than excitement, you're building at the wrong layer.** AURYN is positioned so that every improvement in execution tools makes cultivation more valuable, not less:
 26  
 27  - Better coding agents → visions in the system reach harvest faster
 28  - Always-on daemons → AURYN's situational assessment becomes ambient
 29  - New agentic frameworks → more tools AURYN can spawn at harvest time
 30  - Faster/cheaper inference → AURYN's knowledge refactoring becomes more powerful
 31  
 32  AURYN builds the **soil**, not the **tractor**. Every better tractor is good news.
 33  
 34  ### Cultivation vs. Harvest
 35  
 36  The system splits cleanly along the **vision → strategy** boundary:
 37  
 38  **AURYN's domain (cultivation):** Listening to spoken word, parsing stream of consciousness, growing READMEs, weaving DreamSongs, decomposing and recomposing visions into sub/supermodules, routing insights to the right DreamNodes, managing the relational graph of how dreams connect. This is the planting and nurturing phase. Spoken word is AURYN's native modality — stream of consciousness → structured DreamNodes is something no agentic framework is attempting.
 39  
 40  **Not AURYN's domain (harvest):** When a vision crosses the maturity threshold — when the README is rich enough, the DreamSong relationships are clear, the intent is crystallized — hand it to whatever cutting-edge execution tool exists. AURYN opens the door, provides the context, steps aside. It can spawn the session, but the execution engine is whatever the user prefers.
 41  
 42  The harvest moment is the natural handoff point. AURYN doesn't need to be the execution tool. It needs to have grown such clear, rich context that whatever agent picks it up can run with it effectively. The README and DreamSong are the handoff artifacts.
 43  
 44  ### Monetization Architecture
 45  
 46  AURYN's value is the cultivation layer itself, completely decoupled from any specific agentic shell:
 47  
 48  - **BYOK tier** — bring your own API keys (including local LLMs via Ollama/vLLM/LM Studio), use any shell you want, everything open, no restrictions
 49  - **Managed convenience tier** — non-technical users pay through Stripe, AURYN handles inference costs for its own operations (semantic search, summarization, spoken word parsing, DreamTalk generation) with a markup that supports the project. Implemented via PI's custom provider registration: `pi.registerProvider("anthropic", { baseUrl: "https://auryn-proxy.example.com" })` — the proxy adds API keys, forwards to the real provider, meters usage via PI's built-in cost tracking, and bills through Stripe. No custom LLM infrastructure needed.
 50  - **The user's shell choice is orthogonal** — AURYN never charges for or gates access to execution tools. Users bring their own Claude Code subscription, their own Cursor license, whatever they prefer
 51  
 52  The token service is a convenience store attached to the garden. You don't need to grow the food to run the store, and you don't need the store to grow food. They're naturally decoupled. This means AURYN can position itself universally — it benefits from any tool's improvement because it sits at the layer above.
 53  
 54  ## Current State (as of 2026-03-05)
 55  
 56  AURYN is a fully functional MCP server with **35 tools** across 13 domains. All tools are implemented with proper error handling and graceful degradation (Ollama and Radicle failures are non-fatal). The codebase is clean TypeScript with zero TODOs or stubs.
 57  
 58  **What works now:**
 59  - DreamNode CRUD (create, read, update, delete)
 60  - Submodule relationships with bidirectional tracking (parent ↔ child)
 61  - Semantic search (fuzzy always + vector-based when Ollama available) with sliding window chunking
 62  - DreamSong weaving and reading (Obsidian canvas format)
 63  - Sub-agent loading (DreamNode as agent with scoped tools and cascading context)
 64  - Session spawning (open Claude Code in any DreamNode's context, macOS)
 65  - Liminal web relationships (Dream-to-Dreamer horizontal connections via liminal-web.json)
 66  - Pop-out to sovereign (promote local content to its own DreamNode with submodule replacement and DreamSong updates)
 67  - Merge DreamNodes (unify two nodes into one sovereign entity preserving both git histories and all cross-references)
 68  - Social resonance filter (Radicle publish/clone, peer sync, cherry-pick collaboration with full state machine, collaboration memory)
 69  - Coherence beacon (ignite/detect beacon commits after dreamweaving)
 70  - AURYN chatbot custom UI (`index.html`) with 3B1B write animation for streaming responses
 71  - Real-time voice transcription on desktop — mic button streams audio to InterBrain Mobile's Whisper server, transcript appears with write animation. Requires `InterBrain Mobile/server.py` running (dual-port: HTTPS 3001 for phone, HTTP 3002 for localhost Obsidian iframe)
 72  - AI Bridge WebSocket server (port 27182) inside InterBrain plugin — exposes LLM inference to external UIs without API keys, same protocol as iframe postMessage bridge. Standalone AURYN chatbot connects via this WebSocket
 73  - Drag-and-drop audio file transcription — drop audio files onto chatbot for Whisper processing with write animation
 74  
 75  **What's in progress (partially working, needs completion):**
 76  - Mobile voice transcription — working well over Tailscale (WiFi and LTE). Background mode confirmed working (screen off, phone in pocket). Hours-long stream-of-consciousness sessions tested successfully. Transcripts accumulate in daily markdown files. Custom UI inside InterBrain iframe not yet connecting (WebSocket failure), but standalone mobile access works
 77  - Standalone mode for AURYN chatbot — detection works (`isInIframe`), AI bridge WS connection logic exists, needs end-to-end testing on mobile
 78  - Moonshine API integration for transcription — fast performance confirmed, but streaming output has duplication artifacts (multiple ASR hypotheses concatenated instead of resolved). Final submitted text is more refined than real-time display. UX decision: stream transcription directly into text input field (not animation area) so user can edit before sending, place cursor anywhere, and compose iteratively
 79  
 80  **What's crystallizing conceptually but not yet implemented:**
 81  - AURYN-native session spawning — The InterBrain's "open in Claude Code" button (currently a terminal icon on the selected DreamNode) should use AURYN's DreamTalk symbol instead, and by default spawn Claude Code in AURYN's directory (not the DreamNode's), with the selected DreamNode's README and DreamSong auto-loaded into context. This is the current best prototype of AURYN as its own thing — the agent always starts from AURYN's root with the relevant DreamNode context injected. Eventually "claude" gets replaced by "auryn" and sessions start at the vault root, but spawning into AURYN is the stepping stone.
 82  - Voice transcription pipeline (own the full lifecycle from spoken word to actionable text). Real-time transcription and drag-and-drop are working on desktop (see above). Remaining sub-features:
 83    - **LLM refinement of transcribed text**: Run a lightweight, specialized LLM inference pass over raw Whisper output to correct contextual errors (similar to what ChatGPT does — goes beyond the model itself by using context to figure out what words probably meant). Start with public APIs for prototyping, move to local LLM for production.
 84    - **Auto-populated custom vocabulary**: Automatically inject all DreamNode titles into Whisper's `initial_prompt` / vocabulary biasing so that neologisms and project-specific terms (AURYN, DreamNode, InterBrain, etc.) are recognized correctly. The vocabulary grows as the garden grows.
 85  - Canvas-submodule sync (bidirectional: canvas references ↔ git submodules)
 86  - Holarchic resonance management (downstream/upstream cherry-pick flows between sovereign repos and submodule clones)
 87  - Situational assessment as a native operation (pull latest submodule state → read DreamSong + READMEs + recent commits → produce status → update README)
 88  - Knowledge refactoring (unstructured knowledge → DreamNodes) — Type A consolidation (existing repos → RealDealVault) is complete (494 nodes). Type B (unstructured content like SecondBrain → DreamNodes) is next, with operational patterns established and benchmark dataset identified. System prompt + custom tooling crystallizing through learning-by-doing. But the vision goes far beyond file systems — AURYN should be pointable at any knowledge silo: forums, archives, interview collections, web-based knowledge repositories. The core operation is always the same: take a monolithic block of knowledge with crude or unintuitive internal structure (categories, document lists, thread hierarchies) and refactor it into memetic holons — sovereign DreamNodes structured through DreamSongs into holarchies that mirror how the mind actually relates to knowledge. AURYN doesn't need to one-shot this perfectly; it provides an initial skeleton that human collective intelligence refines through merge, pop-out, and ongoing gardening. Two high-signal target repositories: **InPower Movement** (forum with decades of condensed research, much of it transferred through interviews) and **Disclosure Project Intelligence Archive** (extremely high signal but hard to navigate due to conventional file/category management).
 89  - **Boilerplate README discovery and interview-based population** — Many DreamNodes in the vault still have placeholder template READMEs with no actual content describing what they are. AURYN should be able to scan the vault, identify DreamNodes whose READMEs are boilerplate (matching the template pattern), and then interview the user through conversation to populate them with meaningful descriptions. This is a natural extension of the voice-first assistant workflow: AURYN asks "What is the Thunderstorm Generator?", the user explains in their own words, and AURYN writes the one-pager. The richer the READMEs, the better BM25 context search works — so this directly improves AURYN's own intelligence. Could also be triggered automatically when a DreamNode is detected in voice but has a boilerplate README.
 90  - Songlines (spoken word → DreamNode clips) — AURYN territory, not just InterBrain. Songlines are not DreamNodes — they are range references stored inside concept DreamNodes, pointing back to source conversations via RID. A concept DreamNode like "Zero Point Energy" accumulates songline clips from many different conversations, each carrying a transcript excerpt and an RID linking to the full episode. The songline is provenance — a third relational axis (referential) alongside vertical (submodule holarchy) and horizontal (liminal web). It says "this knowledge came through here" without creating structural coupling. The same unbundling/rebundling pattern applies universally: take a multiplicity of conversations, unbundle each into core ideas (only those meaningful to you), consolidate/deduplicate segments across sources, then synthesize foundational ideas into larger wholes via DreamSongs. For media (audio/video), PRISM's torrent topology gives this native distribution power — a clip is a piece range within the full episode's swarm, so sharing a clip means partially seeding the whole. For transcripts, the clip-to-whole relationship is pure metadata (range + RID). The spoken word interview modality is where enormous amounts of high-signal knowledge lives (podcasts, expert interviews, forum video content). AURYN needs to master this: transcription → concept extraction → clip identification → consolidation of clips from many interviews into the DreamNodes that represent those concepts. One subject matter expert interviewed across dozens of sessions contains a goldmine — AURYN should be able to structure that into navigable, composable, collaborative DreamNodes. Connects to the voice transcription pipeline but goes further: not just real-time copilot listening, but batch processing of existing interview archives. The same pipeline applies to **personal voice memo archives** — years of accumulated voice memos recorded on the go, each containing seeds of ideas, reflections, and insights that never made it into any structured system. AURYN should be able to ingest an entire voice memo library, transcribe with vocabulary-aware Whisper, extract concepts, and route them into the InterBrain's DreamNode topology. This is perhaps the most personal and exciting application: your own voice, across years, finally woven into your knowledge garden.
 91  - **Knowledge garden woven into the chat interface** — Two sides of the same coin: text autocomplete and voice vocabulary detection are the same feature in two modalities.
 92    - **DreamNode autocomplete in chat**: IDE-style autocomplete in the text input, populated with all DreamNode titles. Selecting one inserts the DreamTalk symbol inline (like an emoji) and loads the README into context. If a DreamNode has no DreamTalk symbol, use a styled text badge to avoid losing readability. The trigger could be `@` or just natural typing with fuzzy matching.
 93    - **Custom vocabulary for transcription**: Same title list feeds Whisper's `initial_prompt` / vocabulary biasing. When a spoken DreamNode name is detected, same effect: symbol appears in transcript, context loads. This unifies with the auto-populated custom vocabulary feature above — the vocabulary list serves both modalities.
 94    - **Visual context indicator (petal UI)**: AURYN symbol top-center of the chatbot, with padding. Each loaded DreamNode appears as a "petal" on the edge of AURYN's circle, equidistantly arranged like a flower. Petals are clickable (selects DreamNode in dreamspace). You can "pluck" a petal to manually drop context. This is the symbolic interface for "what's loaded right now." The petal arrangement provides at-a-glance awareness of AURYN's current context.
 95    - **DreamNode references as clickable buttons**: Same pattern as DreamSong media clicks (already implemented in DreamSong.tsx via `onMediaClick` → `sourceDreamNodeId`). Any DreamNode referenced in the AURYN UI becomes a button that selects it in the dreamspace. This should be a universal capability for custom UIs — any HTML file that references a media file from a DreamNode gets a clickable button for free. The AURYN symbol itself is the first instance: click it to select AURYN in the dreamspace.
 96    - **DreamOS custom keyboard**: DreamTalk symbols usable in any chat like emoji or stickers. Cross-platform interoperability question: what's the most universal way to have visual symbols in arbitrary chat contexts? Inline images (data URIs), custom Unicode PUA characters, or platform-specific sticker APIs? This lays groundwork for sharing DreamNodes through any messaging platform. The keyboard is relatively easy to build (it's a custom input method with a symbol picker) and becomes another distribution vector for the InterBrain.
 97  - **AURYN memory with DreamNode references**: AURYN's persistent memory (markdown file) references DreamNodes by link, giving it structured awareness of what's relevant. Could use standard markdown link syntax `[DreamNode Title](uuid)` so AURYN knows where to get more context. The memory becomes a living map of what AURYN has been working on and what it knows about.
 98  - AURYN as voice-first personal assistant entry point — Open AURYN in the morning, speak your stream of consciousness. AURYN routes insights to relevant DreamNodes, creates new ones when needed, spawns Claude Code sessions with pre-filled context for execution. The chatbot UI becomes the portal to the entire InterBrain. Transcends but includes a chatbot: crystallize an idea and immediately execute without switching modes.
 99  - **UI state logging in copilot transcript** — When AURYN is in copilot mode (listening passively), every UI state change (which DreamNode is selected, which DreamSong is open, navigation events) gets logged inline in the transcript alongside the spoken word. This gives AURYN precise context about *what you were looking at* when you said something. "Oh yeah, regarding this..." becomes unambiguous because the transcript records that you had just opened a specific DreamNode. The user can also manually navigate while speaking, and AURYN takes that navigation as additional context signal — operating the UI and speaking become complementary input modalities.
100  - AURYN as intelligent drag-and-drop zone — Drop audio, images, PDFs, any file into the chatbot. AURYN processes it (transcribes audio, reads images, parses documents), holds both the content and the file reference. If the conversation leads to it, AURYN can rename the file, move it to the appropriate DreamNode, commit it, add to Git LFS — all driven by LLM intelligence, no manual file management.
101  - Kronos integration (todos/calendar) — Introduce time-awareness into the system. The knowledge garden has been purely Kairos (becoming) — git history doesn't care about calendar dates. Doing requires Kronos: deadlines, meetings, reminders. Todos live inside DreamNodes (contextual), bubble up holarchically to the vault root. Calendar events and reminders are unified (Apple already discovered these are similar). A DreamNode can say "this needs to be done by March 15" and that propagates to the daily brief.
102  - Daily brief via cron job — AURYN scans the vault for upcoming todos, deadlines, and contextual state. In the morning, it presents: "You're working on X, Y is due today, Z has new peer commits." Can immediately spawn Claude Code sessions for any item with pre-filled context. The brief is the bridge between Kronos (what's time-sensitive) and Kairos (what's growing).
103  - Session spawning with pre-filled prompts — AURYN should be able to spawn a Claude Code session in a specific DreamNode AND pre-populate it with an initial prompt that includes relevant context, files to look at, and what to do. This turns the "oh I want to work on this" impulse into immediate focused execution. The prompt injected by AURYN carries the README, relevant recent changes, and the user's current intent.
104  - **AURYN as Claude Code orchestrator** — Distinct from session spawning (which opens Claude Code for the user to interact with). AURYN itself programmatically operates Claude Code as a sub-agent: spawns it in a DreamNode directory with a prompt, reads the output, and presents the result in the AURYN chat. Pattern: "I orchestrate AURYN, AURYN orchestrates Claude Code." Example: "What's the state of the teaching manuals?" → AURYN spawns Claude Code in that DreamNode with a situational assessment prompt → Claude Code does its deep magic (reads files, git history, runs commands) → AURYN reads the final output and presents it as its own answer. AURYN doesn't need to replicate Claude Code's refined execution protocol — it's a higher-level orchestrator that leverages Claude Code (or any execution agent) as a subject matter expert per DreamNode context. Sonnet-level models suffice for AURYN's orchestration layer; the heavy model runs inside Claude Code. Study how OpenClaw operates Claude Code and replicate that pattern. For now, the Claude Max plan provides unlimited tokens for this — eventually PI Agent replaces it.
105  - **[HIGH PRIORITY] PI Agent as AURYN's execution substrate** — Do NOT build any agentic framework from scratch. PI (github.com/badlogic/pi-mono) is an MIT-licensed TypeScript monorepo that powers OpenClaw. It provides exactly the building blocks AURYN needs in composable layers: **pi-ai** (multi-provider LLM routing with streaming, cost tracking, model switching mid-conversation — supports Anthropic, OpenAI, Google, Ollama, vLLM, LM Studio, any OpenAI-compatible endpoint), **pi-agent-core** (agent loop with tool calling and state management), **pi-coding-agent** (file read/write/edit, bash, session persistence, skills, hooks). AURYN's actual needs from PI are minimal: primarily **file read/write/edit and bash** — everything else AURYN does through CLI tools registered in pi-agent-core. Custom agents become trivially composable: AURYN defines tools, loads DreamNode context, hands to pi-agent-core's loop. PI's custom provider registration (`pi.registerProvider("anthropic", { baseUrl: "https://your-proxy.com" })`) directly enables AURYN's managed convenience tier — proxy LLM requests through a billing layer with built-in token/cost metering, zero custom infrastructure needed. Local LLMs fully supported (Ollama, vLLM, LM Studio via OpenAI-compatible API). No image generation support — DreamTalk symbol generation remains AURYN's own domain. MIT license means complete commercial freedom: use in commercial products, modify, distribute open or closed source, charge money — only obligation is including the license notice. This is the catalyst that lets AURYN graduate from "MCP server that Claude Code talks to" into "its own agent with its own execution loop."
106  - DreamTalk image intelligence (symbol generation using DreamTalk library constraints, not generic AI images)
107  - Vault-level meta-context (root README as life project dashboard)
108  - Absorb merge (parent absorbs child submodule) — When merging A and B where B is a submodule of A, the merge should detect this parent-child relationship and handle it as absorption: ensure B's main is up-to-date with its submodule clone in A, remove the submodule, merge B's history into A, and update all other parents that had B as a submodule to now point at the merged A. This is the inverse of pop-out-to-sovereign: where pop-out promotes a local file to a sovereign DreamNode, absorb merge dissolves that sovereignty back into the parent. First real-world scenario: PRISM absorbing TorrentPlayer.
109  
110  **Owned by other DreamNodes (not AURYN's territory):**
111  - Publishing/distribution → PRISM (GitHub Pages, platform mirroring, torrent seeding)
112  - DreamTalk symbol creation engine → DreamTalk (animation library, Cinema 4D backend)
113  
114  ## Architecture
115  
116  ```
117  AURYN/
118  ├── README.md           # This file
119  ├── CLAUDE.md           # Agent instructions
120  ├── InterBrain/         # Git submodule (temporary - will flip in production)
121  ├── Software Gardening/ # Git submodule (philosophy)
122  └── src/
123      ├── index.ts                    # MCP server entry point
124      ├── services/
125      │   └── standalone-adapter.ts   # All service implementations (~1180 lines)
126      └── tools/
127          ├── foundation.ts           # CRUD operations
128          ├── submodule.ts            # Relationship management
129          ├── semantic.ts             # Search operations
130          ├── dreamweaving.ts         # Canvas generation
131          ├── agent-loader.ts         # Sub-agent management
132          ├── spawn-chat.ts           # Session spawning
133          ├── pop-out.ts              # Pop-out to sovereign
134          ├── merge.ts                # Merge DreamNodes
135          ├── liminal-web.ts          # Liminal web relationships
136          ├── social-resonance.ts     # Radicle ops + peer sync + collab memory
137          ├── cherry-pick.ts          # Cherry-pick workflow state machine
138          └── coherence-beacon.ts     # Beacon ignite/detect
139  ```
140  
141  **Now**: AURYN imports InterBrain as submodule (for prototyping)
142  **Future**: InterBrain imports AURYN as submodule (for production)
143  
144  ## How AURYN Works
145  
146  ### The Pattern: Context First
147  
148  1. **Context-provider runs first** - semantic search finds relevant DreamNodes
149  2. **Filter for true relevance** - LLM reads each candidate's README, drops noise
150  3. **Return the list** - you see which DreamNodes matter
151  4. **Act with full knowledge** - AURYN helps with context loaded
152  
153  ### Two Axes of Resonance
154  
155  AURYN mediates two orthogonal dimensions of how DreamNodes relate:
156  
157  **Horizontal (Social Resonance)**: Dream-to-Dreamer connections across the liminal web. Peers share DreamNodes through cherry-pick-based curation. Signal propagates transitively through trust relationships. Managed by the InterBrain's social resonance filter.
158  
159  **Vertical (Holarchic Resonance)**: Parent-child nesting via submodules. Changes flow in two directions:
160  - **Downstream** (sovereign → submodule clones): The sovereign main branch advances; each submodule clone cherry-picks what's relevant to its context. Safe, frequent, pull-based.
161  - **Upstream** (submodule clone → sovereign): A feature matures in context; when ready, it gets cherry-picked back to sovereign main. Deliberate, conscious, push-based.
162  
163  The two axes intersect at the **sovereign DreamNode** — the canonical version at the vault root. Horizontal resonance (peers) feeds into it. Vertical resonance (contexts) flows out of it and back.
164  
165  **Cherry-pick is the universal operation** because it preserves sovereignty. A merge says "I accept your history as mine." A cherry-pick says "I was inspired by your change and I recreate it in my own context." In the agentic age, every commit is a prompt — the AI agent understands intent and implements appropriately for its context, making merge conflicts a non-concept.
166  
167  **Context branches**: Complex DreamNodes (like InterBrain) maintain a branch per context they're imported into. The branch name mirrors the parent DreamNode. Simple DreamNodes track main directly.
168  
169  ### Private Holarchy Pattern
170  
171  Cherry-pick sovereignty between local branch and Radicle remote creates a natural privacy boundary. You choose what reaches the network — everything else stays dark by default. This extends to social privacy through the holarchic structure itself.
172  
173  **Three layers, each with its own propagation logic:**
174  
175  1. **Sovereign DreamNodes (the leaves)** — each is its own Radicle repo with its own delegate list. Collaboration happens here with all existing machinery: cherry-pick workflow, social resonance filter, coherence beacons. The delegate list IS the social boundary.
176  
177  2. **Private umbrella (the weave)** — a DreamNode you hold locally that weaves leaves into your personal picture via DreamSong. The umbrella's Radicle remote either doesn't exist or has no delegates beyond yourself. Your view of how different trust-bounded pieces relate in your life.
178  
179  3. **The beacon boundary** — coherence beacons are only ignited for public-facing weaves. When you weave a DreamSong meant to invite peers into a shared story, you ignite the beacon and it propagates. When you weave a private umbrella combining DreamNodes across different trust boundaries — no beacon. The supermodule relationship exists only in your local branch of each constituent DreamNode.
180  
181  **How social boundaries map to holarchic structure:** Rather than maintaining multiple branches or audience metadata within one DreamNode, decompose along trust lines using submodules. A house DreamNode becomes an umbrella with `Paperwork/` (delegates: housemates), `Makerspace/` (delegates: housemates + maker crew), `Workshop Ideas/` (delegates: wide circle). Each submodule is a sovereign Radicle repo with its own delegate list. Your maker space collaborators don't even know `Paperwork/` exists — it's not hidden, it's simply not in their world.
182  
183  **Privacy boundaries emerge through gardening:** You don't pre-plan privacy structure. You start with a single DreamNode, notice "this piece has a different audience," and pop it out via `pop_out_to_sovereign`. The act of recognizing sovereignty IS the act of drawing the boundary.
184  
185  **A DreamNode can live in multiple umbrellas simultaneously.** `Makerspace/` exists in your private House umbrella AND in a public Maker Community project. Different DreamSongs, different stories, different beacon decisions. The sovereign DreamNode doesn't know or care which umbrellas reference it.
186  
187  **The pattern in one sentence:** sovereignty at the leaf, privacy at the weave, beacons only for stories you want to tell publicly.
188  
189  ### The Core Principle: Relationships Are Downstream of DreamSongs
190  
191  Submodule relationships are **never directly manipulated**. They are inferred from DreamSongs.
192  
193  When you weave a DreamSong (canvas), you place DreamTalk images from other DreamNodes and write text explaining how they relate. The system observes what you reference and manages submodule imports/removals automatically. This is an **enabling constraint**:
194  
195  - **To import**: Reference a DreamNode's DreamTalk in your DreamSong. The submodule relationship follows.
196  - **To remove**: Edit the DreamSong to remove the reference. On save, the system cleans up the submodule.
197  - **No orphan imports**: Every submodule relationship is justified by a story.
198  - **No accidental breakage**: You can't remove a submodule that a DreamSong references without first editing the DreamSong.
199  
200  DreamSongs become the holarchy map. At every level, the DreamSong explains *why* these submodules are here and how they relate. Far richer context for agentic navigation than bare dependency lists.
201  
202  ### The DreamTalk Requirement
203  
204  Every DreamNode needs a DreamTalk image — it's what makes a node dreamweave-ready. Without an image, a DreamNode cannot be referenced in a DreamSong and therefore cannot participate in holarchic relationships.
205  
206  ### Pop-Out to Sovereign
207  
208  The inverse of importing: content that starts as a local file inside a DreamNode can be promoted to its own sovereign DreamNode. AURYN handles the full flow:
209  
210  1. User identifies content that deserves sovereignty ("this should be its own thing")
211  2. AURYN creates a new sovereign DreamNode from that content
212  3. The local file is replaced by a submodule import of the new DreamNode
213  4. The DreamSong is updated — file references now point into the submodule
214  5. A context branch is created in the submodule clone (named after the parent)
215  
216  The final state is the same as if the DreamNode had always existed externally: sovereign repo, submodule clone with context branch, correct DreamSong paths. This is how knowledge gardens grow — not in size, but in interconnectedness.
217  
218  ### Knowledge Refactoring (Unstructured Knowledge → DreamNodes)
219  
220  Point AURYN at any knowledge source — a folder, a Notion export, a CSV dump, an existing Obsidian vault, a forum, an archive, a collection of interviews. AURYN creates DreamNodes with minimum viable structure, just enough for dreamweaving compatibility. Through ongoing knowledge gardening, finer structure emerges naturally. Pop-out happens when a piece is ready for sovereignty.
221  
222  **The core transformation**: Take a monolithic knowledge silo — a forum with thousands of threads, an archive with bureaucratic category structures, a series of expert interviews — and refactor it into memetic holons. Each concept that stands on its own becomes a sovereign DreamNode. These are then structured through DreamSongs into holarchies that mirror how the mind actually relates to that knowledge. The result: the surface area for knowledge transfer explodes. What was one huge opaque block becomes hundreds of composable, navigable, collaboratively refinable units.
223  
224  **Why this matters**: Conventional knowledge management (categories, document lists, thread hierarchies, file names) is not how the human mind relates to knowledge natively. A forum is a silo — one member mastering the material doesn't automatically make it easier for others to digest. But when that knowledge is refactored into DreamNodes, each piece becomes a unit of collaboration and clarification. The collective intelligence of the community can work on the actual knowledge topology rather than fighting the container's structure.
225  
226  **AURYN doesn't need to one-shot this**: The initial refactoring provides a skeleton — an ever-more-helpful starting point. From there, human collective intelligence refines: merge these two, pop this out, this is actually its own thing. Each round of refactoring teaches the system about itself.
227  
228  **The seed-planting principle**: Knowledge gardening follows the metaphor literally — the human plants seeds, AURYN routes nutrients. A seed is a DreamNode with a name, a symbol (DreamTalk), and a one-pager README defining the concept. Once planted, AURYN's semantic search can detect when new knowledge (conversations, transcripts, documents) contains material relevant to that seed. The garden should not be populated with memetic strangers — concepts that don't mean anything to you. That niche is occupied by LLM inference and can be retrieved trivially. Your knowledge garden holds only the ideas that matter to you, represented by symbols, deepened over time through songline clips and written refinements. AURYN conservatively suggests candidate seeds from new knowledge sources but does NOT plant them autonomously. The human decides what enters the garden. This means the same transcript produces different results depending on which seeds you've already planted — revisiting a knowledge base after planting new seeds yields new insights that weren't relevant before. Knowledge refactoring is therefore an organic, iterative process rather than a mechanical one-time migration.
229  
230  **The spoken word dimension**: Enormous amounts of high-signal knowledge lives in interviews and podcasts. Subject matter experts get interviewed repeatedly across dozens of sessions, explaining concepts, presenting research, going deep on specifics. AURYN should be able to process these: transcript → concept extraction → clip identification → consolidation of clips from many interviews into the DreamNodes that represent those concepts. This is the Songlines feature applied to knowledge refactoring — not just real-time copilot listening, but batch processing of existing spoken-word archives. Authentic conversation is the ideal binding structure for bringing different forms of knowledge into relationship — people discuss a book and explain what it means to them, which is far more useful than a cold recommendation list. The podcast phenomenon is a non-trivial component of what wants to collectively emerge, and the private-call-to-public-podcast boundary dissolves naturally: the full conversation stays local (only you and your conversation partner hold it), and the act of clipping songlines into public concept DreamNodes IS the act of publishing. No separate recording mode, no editing workflow — you garden your knowledge and the public-facing clips emerge as a byproduct. Retroactive publishing is native: a conversation from months ago yields new songlines when you plant seeds that make old moments suddenly relevant.
231  
232  **The end goal**: the InterBrain installation process allows users to point to their existing knowledge sources — vaults, forums, archives, interview collections. AURYN consolidates, purifies, and refactors their knowledge base into DreamNodes, keeping old data as backups. No risk, full reversibility. One person with high conceptual clarity about a knowledge landscape's topology can infuse that understanding into an ever-more-refined system prompt for the refactoring process. Once community collective intelligence starts applying and refining it, the capability compounds.
233  
234  #### Learnings from Vault Consolidation (Jan-Feb 2026)
235  
236  Four consolidation sessions migrated ~494 DreamNodes into RealDealVault from 12 source vaults. This established the operational patterns. Key insights:
237  
238  **Two fundamentally different problems:**
239  - **Type A (completed)**: Mapping existing DreamNode repos from old vaults — mechanical (add `.udd`, Radicle ID, move directories). Solved with batch conversion in groups of ~25 with verification between batches.
240  - **Type B (not started)**: Refactoring unstructured content (Obsidian PKM vaults, markdown files, mixed personal data) into DreamNodes. Requires AI intelligence to determine what becomes what. The SecondBrain directory (99 items) is the benchmark dataset for this.
241  
242  **Operational patterns that proved reliable:**
243  - Idempotent conversion — check what exists, only fill gaps, safe to rerun
244  - Move-to-trash over delete — organized by cleanup type and date
245  - DreamTalk media auto-detection (MP4 > GIF > PNG > JPEG > PDF > SVG, smaller preferred)
246  - Pre-cleanup phase first (remove editor artifacts, legacy metadata, empty dirs) before conversion
247  - Schema validation on `.udd` creation (the `dreamTalkMedia` vs `dreamTalk` inconsistency affected 33 files mid-batch)
248  
249  **Intelligence required for Type B:**
250  - **Deduplication requires judgment, not just hashing** — deciding which version of a concept is "richer" (more content, more recent, better DreamTalk) is a creative decision
251  - **Dreamer nodes need special merge logic** — liminal-web.json must be unioned, not overwritten; images may need merging from multiple sources
252  - **Content classification** — standalone markdown → likely 1:1 DreamNode; structured directories → may be DreamNode-ready or need decomposition; personal/financial docs → may not belong as public DreamNodes; untitled stubs → noise to clean up; duplicates of existing DreamNodes → dedup needed
253  - **Thematic clustering** — topics naturally migrate in related clusters (e.g., all UAP-related nodes together); the tool should support cluster-based import
254  - **The consolidation process itself is a knowledge gardening act** — deciding what deserves sovereignty encodes understanding. Surface these decisions to the user rather than automating them away
255  
256  **What the benchmark dataset (SecondBrain) contains:**
257  99 items including standalone idea files (A T A R A X I A.md, Dialectic.md, Miracle Consciousness.md), structured project directories (ABRAXAS, AntiGravityBong, Books, DailyNotes), personal documents (consulting bookkeeping, loan agreements), Obsidian infrastructure (Attachments, Templater, DailyNotes), and duplicates of existing DreamNodes (InterBrain.md, Project Liminality.md). This is representative of what normal users with an existing Second Brain will bring.
258  
259  **Post-conversion cleanup is significant** — validation should be built into the flow, not an afterthought. Branch naming (`master` vs `main`), bad Radicle IDs, and edge cases in repos without commits all surfaced at scale.
260  
261  **The consolidation process stress-tests the system** — scaling from 50 to 167 nodes revealed localStorage limits in the InterBrain plugin (Session 2). The SecondBrain consolidation will likely reveal new edge cases in AURYN's tooling. That's a feature — each round of consolidation teaches the system about itself.
262  
263  ### Situational Assessment
264  
265  AURYN can assess the state of any DreamNode that contains submodules (like a project DreamSong):
266  
267  1. **Pull latest** — update all submodule pointers to sovereign state
268  2. **Read the DreamSong** — understand the narrative and relationships
269  3. **Check each submodule** — read README + recent commits for ground truth
270  4. **Report honestly** — what's alive, what's stale, what's missing
271  5. **Update the README** — the Current State section reflects reality
272  
273  The README is the always-current truth. When AURYN does a situational assessment, it reads the README first. If the README is stale, that's the first thing to fix.
274  
275  ## MCP Tools (35 total)
276  
277  ### DreamNode Operations (4)
278  | Tool | Description |
279  |------|-------------|
280  | `create_dreamnode` | Create new DreamNode with git init, Radicle init, returns UUID |
281  | `read_dreamnode` | Read metadata and README by UUID |
282  | `update_dreamnode` | Update metadata (title, type) |
283  | `delete_dreamnode` | Delete a DreamNode (requires confirmation) |
284  
285  ### Relationships (4)
286  | Tool | Description |
287  |------|-------------|
288  | `add_submodule` | Import a DreamNode as submodule (low-level primitive) |
289  | `remove_submodule` | Remove a submodule relationship |
290  | `list_submodules` | List submodules of a DreamNode |
291  | `sync_context` | Regenerate `.claude/submodule-context.md` with @imports for all submodule READMEs |
292  
293  Note: `add_submodule` and `remove_submodule` are low-level primitives. The intended flow is DreamSong-driven: weave a DreamSong → submodule relationships are inferred as a downstream effect.
294  
295  ### Liminal Web (3)
296  | Tool | Description |
297  |------|-------------|
298  | `add_liminal_link` | Add a horizontal link between a Dreamer and another DreamNode |
299  | `remove_liminal_link` | Remove a liminal web link |
300  | `list_liminal_links` | List all connections for a DreamNode (Dreamer: direct read; Dream: scans all Dreamers) |
301  
302  Note: Links are stored in Dreamer nodes' `liminal-web.json` as UUID arrays. Interpreted as bidirectional — only Dreamers hold the data.
303  
304  ### Semantic Search (3)
305  | Tool | Description |
306  |------|-------------|
307  | `process_content` | Unified search: fuzzy (always) + semantic (if Ollama). Handles text and files with sliding window chunking. |
308  | `index_dreamnodes` | Index all DreamNodes for vector search |
309  | `check_ollama_status` | Verify Ollama embedding service is available |
310  
311  ### Dreamweaving (2)
312  | Tool | Description |
313  |------|-------------|
314  | `weave_dreamsong` | Generate DreamSong.canvas from source DreamNodes with descriptions |
315  | `read_dreamsong` | Parse DreamSong.canvas into topologically sorted content blocks |
316  
317  ### Agent Management (3)
318  | Tool | Description |
319  |------|-------------|
320  | `load_dreamnode_agent` | Load DreamNode as sub-agent with README context and scoped tools |
321  | `unload_dreamnode_agent` | Remove a loaded sub-agent |
322  | `list_loaded_agents` | List all currently loaded sub-agents |
323  
324  ### Session Management (2)
325  | Tool | Description |
326  |------|-------------|
327  | `spawn_chat` | Open Claude Code in a DreamNode's directory (macOS) |
328  | `pop_out_to_sovereign` | Promote local content to sovereign DreamNode with submodule replacement, DreamSong path updates, and context branch creation |
329  
330  ### Lifecycle (1)
331  | Tool | Description |
332  |------|-------------|
333  | `merge_dreamnodes` | Merge two DreamNodes into one sovereign entity, preserving both git histories, updating all cross-references, and keeping ghost forks for backpropagation |
334  
335  ### Social Resonance (3)
336  | Tool | Description |
337  |------|-------------|
338  | `radicle_clone` | Clone a DreamNode from Radicle network by RID |
339  | `radicle_publish` | Publish/share a DreamNode on the Radicle network |
340  | `radicle_follow_peer` | Follow a peer DID, optionally add as delegate |
341  
342  ### Peer Sync (3)
343  | Tool | Description |
344  |------|-------------|
345  | `fetch_peer_commits` | Fetch new commits from all peer remotes |
346  | `list_pending_commits` | List peer commits not yet accepted/rejected |
347  | `read_collaboration_memory` | Read acceptance/rejection history for a Dreamer |
348  
349  ### Cherry-Pick Workflow (5)
350  | Tool | Description |
351  |------|-------------|
352  | `cherry_pick_preview` | Enter preview: stash local changes, cherry-pick, show diff |
353  | `cherry_pick_accept` | Accept previewed commit, record in collaboration memory |
354  | `cherry_pick_reject` | Reject previewed commit, record in collaboration memory |
355  | `cherry_pick_cancel` | Cancel preview without recording |
356  | `cherry_pick_status` | Get current workflow state (UI observability) |
357  
358  ### Coherence Beacon (2)
359  | Tool | Description |
360  |------|-------------|
361  | `ignite_beacon` | Create beacon commit after dreamweaving |
362  | `detect_beacons` | Scan peer commits for beacon metadata |
363  
364  ### Not Yet Implemented
365  
366  **Dreamweaving (completing the stack):**
367  - `sync_canvas_submodules` — bidirectional sync (canvas references ↔ git submodules)
368  - `extract_relationships_from_canvas` — relationship graph from DreamSong
369  
370  **Voice Pipeline & Songlines:**
371  - Voice transcription (Whisper integration — own the full spoken-word-to-action lifecycle)
372  - Real-time copilot listening — surface relevant DreamNodes during live conversations, summarize afterwards
373  - Clip extraction — identify and clip relevant segments from conversations, associate clips with DreamNodes
374  - Batch transcript processing — ingest interview archives, extract concepts, consolidate clips from many sources into concept-level DreamNodes
375  
376  **Knowledge Refactoring:**
377  - Unstructured files → DreamNodes (Type B: SecondBrain benchmark)
378  - Forum/archive ingestion — point at web-based knowledge repositories, parse structure, refactor into DreamNodes
379  - Transcript-to-DreamNode pipeline — process interview collections into concept-level DreamNodes with associated clips
380  
381  **Other:**
382  - Situational assessment — pull submodule state → read DreamSong + READMEs → produce status report
383  - Submodule refresh — `git submodule update --remote` before assessment
384  - DreamTalk image intelligence — symbol generation using DreamTalk library constraints
385  
386  **Owned by other DreamNodes (not AURYN tools):**
387  - GitHub Pages publishing → PRISM
388  - Platform mirroring → PRISM
389  - Torrent seeding → PRISM
390  
391  ## Roadmap (Prioritized for Spring Launch)
392  
393  ### Real-World Benchmarks (March 2026)
394  
395  Three concrete tasks serve as development benchmarks — each tests a different AURYN capability and reveals what's missing:
396  
397  1. **OMSN Teaching Manuals** — Markdown → PDF workflow for a school volunteering project. Tests: situational assessment ("what's the state of these manuals?"), Claude Code orchestration (AURYN spawns Claude Code to do deep work, reads result), voice-driven iteration (speak feedback, AURYN rewrites, present again). The written word is fully AI territory; the human evaluates visual output (PDF formatting).
398  2. **Bussola do Mundo video project** — Video/communication work for the same school. Tests: creative dreamweaving, rendering pipeline coordination. Less immediately automatable (Cinema 4D work), but the planning/communication layer is.
399  3. **Open Collective update post** — Being developed in the Spring Launch context. Tests: voice-driven content refinement (speak stream of consciousness → AURYN iterates on text → present for review → repeat until it flows right).
400  
401  ### Next Up
402  1. **Dreamweaving completion** — canvas-submodule sync (bidirectional enforcement of DreamSong-driven relationships)
403  2. **Knowledge refactoring** — SecondBrain consolidation as benchmark (Type B: unstructured → DreamNodes). Learning-by-doing to crystallize system prompt + custom tooling. End goal: InterBrain installation can absorb any knowledge source (vaults, forums, archives, interview collections).
404  
405  ### Medium Priority
406  - Songlines & voice pipeline (Whisper transcription, clip extraction, batch transcript processing, real-time copilot listening)
407  - Forum/archive ingestion (web-based knowledge repositories → DreamNodes)
408  - DreamTalk image intelligence (symbol generation, style references)
409  - Situational assessment + submodule refresh
410  - CLI tools (`auryn create`, `auryn search`, `auryn weave`)
411  
412  ### Future
413  - Spacebar/Dialogos mode (voice-driven intent recognition)
414  - Architecture flip (InterBrain imports AURYN)
415  - Cross-platform spawn_chat (Linux/Windows)
416  - Deep knowledge refactoring at scale (InPower Movement forum, Disclosure Project Intelligence Archive, and similar high-signal repositories)
417  
418  ## Setup
419  
420  ```bash
421  git clone --recurse-submodules <repo-url>
422  npm install && npm run build
423  ```
424  
425  Add to `~/.claude/mcp.json`:
426  ```json
427  {
428    "mcpServers": {
429      "auryn": {
430        "command": "node",
431        "args": ["/path/to/AURYN/dist/index.js"]
432      }
433    }
434  }
435  ```
436  
437  Requires Ollama with `nomic-embed-text` for semantic search (optional — fuzzy search works without it).
438  
439  ## Philosophy
440  
441  ### The Universal Principle
442  
443  Build at the layer where more capability below you is unambiguously good news. If an announcement below your layer causes anxiety, you're building at the wrong layer. If it causes excitement, you're in the right place.
444  
445  AURYN is a knowledge topology. No agentic framework is building this — they don't care about DreamNodes, DreamSongs, holarchic submodule relationships, cherry-pick sovereignty, coherence beacons, or the liminal web. They care about tool routing, context windows, and permission models. These concerns are complementary, not competitive.
446  
447  The knowledge gardening layer is deeply human, inherently social, and resistant to pure automation. Someone with well-structured DreamNodes and rich DreamSongs gets dramatically better results from *any* agentic framework than someone with a flat folder of markdown files. AURYN is what makes every tool more effective.
448  
449  ### README as Universal Memory
450  
451  - **Agent-agnostic**: Works with any AI — not coupled to any shell or provider
452  - **Human-readable**: Just markdown — the format that survives every platform shift
453  - **Git-versioned**: Full history — sovereignty through distributed version control
454  - **Composable**: Submodules cascade context — holarchic structure is native
455  
456  The sophistication ceiling has been removed. In the agentic age, system design is no longer constrained by user operability. AURYN holds the knowledge of how collective dreamweaving works and operates it on your behalf. Users interact through natural language. AURYN does the gardening.
457  
458  AURYN gives itself to every DreamNode. The Ouroboros — creating itself endlessly.