/ README.md
README.md
1 # The InterBrain: From Personal Knowledge Management to Collective Knowledge Gardening 2 3  4 5 ## Introduction 6 7 The InterBrain is an innovative knowledge gardening system that aims to revolutionize the way we collectively relate to our ideas and stories. It transcends the traditional "Second Brain" paradigm, popularized by PKM tools like Obsidian, shifting to a dynamic, relational approach to organizing knowledge as opposed to static, top-down categorization. 8 9 ## 🚀 Ready to Install & Try 10 11 The InterBrain is work-in-progress software with basic functionality now installable as an Obsidian plugin. You can download and install the plugin to start building your liminal web using the existing features, while other capabilities are still in development and the full vision has yet to be comprehensively implemented. 12 13 **[→ Installation Guide](#installation--setup)** 14 15 ## Project Status & Roadmap 16 17 > ⚡️ **Current Status: 7 Foundation Epics Complete, Epic 8 In Progress** 18 Epics 1-7 are complete (plugin infrastructure, 3D visualization, DreamNode management, liminal web, semantic search, dreamweaving, conversational copilot). Epic 8 (Coherence Beacon System) is currently in development with automatic relationship discovery, bidirectional tracking, and Radicle network integration. 19 20 > 🔬 **Previous Exploration:** 21 Earlier exploration work including screenshots and recordings can be found at [**InterBrain-Prototype**](https://github.com/ProjectLiminality/InterBrain-Prototype). This repository contains the conceptual foundation and visual demonstrations that inform the current development approach. 22 23 > 🌱 **Beyond the Plugin:** 24 The InterBrain is designed as the foundation for **DreamOS** — a decentralized, AI-agent-powered operating system for collective sensemaking and human-computer symbiosis. 25 26 > 💡 **Development Roadmap:** 27 - ✅ Epics 1-7: Complete foundation (plugin infrastructure, 3D visualization, DreamNode management, liminal web, semantic search, dreamweaving, conversational copilot) 28 - 🚧 Epic 8: Coherence Beacon System (in progress) 29 - 🪐 DreamOS system (future evolution) 30 31 Current development progress is tracked through [**GitHub Issues**](https://github.com/ProjectLiminality/InterBrain/issues) and [**Project Board**](https://github.com/users/ProjectLiminality/projects/2). For detailed achievement history, see [CHANGELOG.md](CHANGELOG.md). 32 33 ## Installation & Setup 34 35 ### 🧪 Private Beta Status 36 37 InterBrain is currently in **private beta**. We're gathering feedback from early users before public release. 38 39 **What this means:** 40 - Core functionality works reliably across platforms 41 - You may encounter rough edges - please report issues! 42 - Your feedback directly shapes the product 43 44 ### Platform Support 45 46 InterBrain runs on **macOS, Linux, and Windows**. See [Platform Support Documentation](src/features/social-resonance-filter/docs/platform-support.md) for full details. 47 48 | Feature | macOS | Linux | Windows | 49 |---------|-------|-------|---------| 50 | Create & edit DreamNodes | ✅ | ✅ | ✅ | 51 | DreamSong canvas playback | ✅ | ✅ | ✅ | 52 | Submodule import (dreamweaving) | ✅ | ✅ | ✅ | 53 | Semantic search (Ollama) | ✅ | ✅ | ✅ | 54 | GitHub publishing | ✅ | ✅ | ✅ | 55 | **P2P collaboration (Radicle)** | ✅ | ✅ | 🔜 | 56 57 **Windows P2P Note**: Radicle's `git-remote-rad` and `radicle-node` are not yet available on Windows. Once Radicle ships these components, InterBrain will automatically enable full P2P collaboration. See [Platform Support](src/features/social-resonance-filter/docs/platform-support.md) for details on expressing interest to the Radicle team. 58 59 ### Quick Install 60 61 **macOS / Linux:** 62 ```bash 63 bash <(curl -fsSL https://raw.githubusercontent.com/ProjectLiminality/InterBrain/main/install.sh) 64 ``` 65 66 **Windows:** 67 ```powershell 68 irm https://raw.githubusercontent.com/ProjectLiminality/InterBrain/main/install.ps1 | iex 69 ``` 70 71 The install script will automatically install and configure all dependencies: 72 - Obsidian (if not already installed) 73 - Git (required for DreamNode versioning) 74 - Ollama (for semantic search with local AI) 75 - Radicle (for peer-to-peer sharing - macOS/Linux) 76 - InterBrain plugin and vault setup 77 78 > 💡 **Tip**: If the install script encounters issues, you can safely re-run it. It's designed to be idempotent and may resolve transient problems on subsequent runs. 79 80 --- 81 82 ## Getting Started 83 84 After successful installation, you'll see the **InterBrain DreamNode** itself in your DreamSpace. If you don't see it, press **Cmd+R** to refresh the plugin - this should reveal it and automatically select it. 85 86 > 💡 **Tip**: If you ever run into issues with the InterBrain, try pressing **Cmd+R** to refresh the plugin. This often resolves display or interaction problems. 87 88 ### Build Your First Liminal Web 89 90 **1. Add the people you care about:** 91 Think of 1-3 people you care about (who you'd like to have frequent video calls with is a good rule of thumb). Find image files representing them and name them appropriately: 92 - `Alice.png` 93 - `Bob.png` 94 - `Charlie.png` 95 96 Drag and drop these image files into the DreamSpace next to the InterBrain DreamNode. This automatically creates **Dreamer nodes** for these peers. 97 98 **2. Add shared ideas:** 99 Click on any person to select them. Now think of ideas, stories, or projects that connect you to them. Find image files representing these ideas, name them appropriately, and drag and drop them next to the selected person. 100 101 This automatically creates the initial relationships in your Liminal Web - connecting you to people through the ideas you share. 102 103 **3. Explore and grow:** 104 Continue this simple pattern - drag and drop image files to add people and ideas, click to navigate relationships. Your personal knowledge network emerges organically through these connections. 105 106 ### Important Notes 107 108 **Security & Development Status**: InterBrain is work-in-progress software under active development. All code is built transparently in public on GitHub where you can review the complete source code and development history. Users should exercise their own judgment when installing development software. As we approach a stable release, security, stability, and comprehensive testing will receive focused attention in line with production software standards. 109 110 --- 111 112 ## Core Concepts 113 114 ### Dream Nodes 115 116 The fundamental unit of Project Liminality is the "Dream Node," which is implemented as a Git repository. Dream Nodes can embody two primary concepts: 117 118 1. **Dreams**: Abstract ideas, concepts, or any form of knowledge. 119 2. **Dreamers**: Representations of people or peers. 120 121  122 123 This dual nature allows for a flexible and interconnected knowledge structure. 124 125 ### Dream Talk and Dream Song 126 127 Each Dream Node consists of two main components: 128 129 - **Dream Talk**: A concise, symbolic representation of the idea (like a thumbnail). 130 - **Dream Song**: A more elaborate explanation or exploration of the idea, containing multiple references to other Dream Talks. 131 132  133 134 ### The InterBrain 135 136 Project Liminality structures knowledge based on social relationships and interactions, creating an "InterBrain." This approach allows users to organize information along the lines of their actual relational fields, transcending static, top-down categorization. 137 Thus uniting the multiplicity of Second Brains into a singular, interconnected InterBrain structure. 138 139  140 141 ## Key Features 142 143 ### 🌱 DreamNode Creation 144 145 Creating a new DreamNode is as easy as dragging and dropping a visual representation (DreamTalk) onto the interface. This will automatically create a new DreamNode with the same name as the file, containing the file. 146 Using the Command-N keyboard shortcut you can also create an empty DreamNode with your name of choice. 147 148  149 150 ### 🕸️ Liminal Web 151 152 By linking the ideas you hold to the people you share them with, DreamNodes self-organize into your unique "Liminal Web." 153 154  155 156 This allows you to navigate your knowledge in an intuitive and organic fashion, transcending the need for contrived categorization or hierarchical management. 157 158  159 160 ### 🔍 Semantic Search 161 162 Finding relevant DreamNodes is made easy and intuitive through semantic search - no need to worry about typos or remembering the exact name of any given idea! 163 Just enter a search query that is close enough in meaning to what you're looking for and it will magically be revealed. 164 (This existing feature is the basis for a yet-to-be-implemented realtime conversational copilot that always has the most relevant knowledge at hand for sharing during free-flowing conversation.) 165 166  167 168 ### 🧬 DreamWeaving 169 170 Just like individual software modules can be combined into more sophisticated projects using git repositories, DreamNodes can be woven together into larger wholes. Using the Obsidian canvas, DreamTalk symbols can be woven together with text into DreamSongs. The resulting DreamSong can in turn again be distilled into a single DreamTalk symbol. This reciprocal and recursive many-to-one mapping between DreamSong and DreamTalk allows for the emergence of a vertical holarchy of DreamNodes. A universal pattern for performing the Hegelean Dialectic of ideas in the digital! 171 172  173 174 ### 🔆 Coherence Beacon 175 176 Every time any Dreamer weaves together DreamNodes into larger wholes, the Coherence Beacon is triggered. This mechanism automatically identifies the subset of peers with whom they share any of the input DreamNodes and offers them the higher order DreamNode (including all input DreamNodes they may or may not already hold). By accepting the invitation they extend the signal to all of their peers and so on. This way only coherent ideas spread based on how much they resonate with the network, solving the virality problem. 177 Freedom of speech bound by meritocratic reach! 178 179  180 181 ### 🤖 Integrated AI Assistant 182 183 Since DreamNodes are based on git repositories, prominent AI pair-programming solutions like aider or cursor, being optimized for git, integrate seamlessly with the system. And just like the InterBrain generalizes git repos from computer code to all of knowledge, the same can be done out of the box with AI pair-programmers, using them as universal magical co-creators! 184 With ever more powerful, local, multi-modal models on the horizon and deeper integrations through frameworks like Model Context Protocol (MCP) truly the sky is the limit in terms of what can be achieved collectively through the InterBrain! 185 186  187 188 ### 💬 Conversational Co-Pilot 189 190 An AI-powered conversation mode where you can invoke DreamNodes by name during natural dialogue. Type a message, and the copilot responds with context from your knowledge graph. Mention a DreamNode by name (e.g., "tell me about MyIdea") and it gets pulled into the conversation context. 191 192 The foundation for a future realtime transcription system that will filter relevant DreamNodes during live conversations - making knowledge readily available without interrupting the flow. 193 194  195 196 ### 🎵 Songlines (Future) 197 198 A vision for the future: every time an idea is shared during a conversation, the relevant audio clip is automatically added to the DreamNode. Each DreamNode remembers the path it travels in a unique set of conversation clips - its Songline. 199 200 Songlines would provide an organic, decentralized replacement for static definitions - community-generated data representing knowledge in the most effortless yet high-bandwidth way. With local multi-modal LLMs and infinite context windows, Songlines could become a game changer for leveraging collective wisdom. 201 202 *Foundation exists via realtime-transcription feature; full Songline capture is future work.* 203 204  205 206 ### 📱 Git Client Integration 207 208 Easily open any given DreamNode in your favorite git client of your choice. 209 210  211 212 ### 🌐 GitHub Publishing 213 214 Share your DreamNodes with the world via GitHub Pages. With one action, publish a DreamNode to GitHub - the system creates a repository, generates an interactive viewer bundle, and deploys it to GitHub Pages. Recipients can view the DreamTalk and DreamSong in their browser, and easily clone it into their own InterBrain. 215 216 *Complements the peer-to-peer Radicle sharing for cases where you want public, web-accessible sharing.* 217 218 ### 📊 Organic Content Visualization 219 220 The content within a DreamNode is visually accessible on the backside using the beautiful circle packing algorithm of D3. Instantly access files and folders directly from the InterBrain. 221 222  223 224 ## Real-World Applications & Project Synergy 225 226 The InterBrain system transforms how we share and organize knowledge, creating an organic ecosystem where ideas and initiatives can flourish together. 227 228 ### 🎙️ Enhanced Podcasting 229 - **Real-time knowledge access**: Conversational copilots filter relevant dream nodes based on discussion topics 230 - **Enriched show notes**: Share actual knowledge units rather than just superficial references 231 - **Depth in knowledge transfer**: Audience receives not just references but entire repositories of contextual information 232 233 ### 🔎 Collaborative Investigation 234 - **Emergent collective intelligence**: Investigators can effortlessly combine evidence and knowledge 235 - **Coherence Beacon in action**: Automatically invites collaborators who hold relevant knowledge 236 - **Scaling potential**: Enables millions of citizen journalists to work together on complex cases 237 238 ### 🎓 Future of Education 239 - **Dissolving artificial boundaries**: Between disciplines and between education and life itself 240 - **Living classroom**: Every conversation becomes an educational opportunity 241 - **Emergent curriculum**: Knowledge expands organically based on contextual relevance 242 - **Symbolic teaching**: Complex ideas transmitted through symbols backed by detailed dream nodes 243 244 ### 🎨 Co-Creation Renaissance 245 - **Source and product travel together**: Creative works remain connected to their source files 246 - **Open source everything**: Any digital creation becomes remixable and extensible 247 - **Infinite collaboration**: Weave different creations together through dream weaving 248 - **Context creation**: Shift from "content creators" to "context creators" with living, evolving works 249 250 ### 🕊️ End of Narrative Warfare 251 - **Signal amplification**: Filter out noise in competing narratives 252 - **Perspective integration**: Combine viewpoints to approach deeper truth 253 - **Social resonance filter**: Collective intuition helps identify coherent syntheses 254 - **Propaganda immunity**: System design makes manipulation difficult while healing divisive narratives 255 256 ### 🌐 Emergent Collaborative Networks 257 - **Dream nodes for all initiatives**: Any project can be represented as a dream node while maintaining independence 258 - **Cross-pollination**: Knowledge flows freely between initiatives while respecting autonomy 259 - **Resonance-based connections**: Projects naturally find their complementary partners 260 - **No central authority**: Collaboration emerges organically based on relevance and resonance 261 262 ### 🌿 Conscious Communities 263 - **Knowledge transfer across communities**: Solutions developed in one place effortlessly reach others 264 - **Contextual distribution**: Learning finds exactly where it's needed based on relevance 265 - **Social relationship propagation**: Knowledge travels through trusted connections 266 - **Emergent collective problem-solving**: Communities evolve together rather than in isolation 267 268 ### 🚀 From Incubation to Implementation 269 - **Project merging and spawning**: Smaller initiatives can unify or new ones can form from combinations 270 - **Solutions combine into higher-order solutions**: Building blocks of knowledge stack meaningfully 271 - **Universal pattern recognition**: Similar challenges across different domains find common solutions 272 - **Network of conversations**: All collaboration is rooted in human connection and meaning 273 274 ## Frequently Asked Questions 275 276 ### How does InterBrain prevent echo chambers while maintaining coherence filtering? 277 278 InterBrain addresses the echo chamber problem through a unique **holographic approach** that emphasizes connection over separation. Unlike traditional social media that amplifies differences and enables ideological bubbles, InterBrain's design makes separation literally invisible while highlighting what connects people. 279 280 **The Holographic Principle**: Stories contain people, and people hold stories - they contain each other in a holographic structure where each part contains the whole. This means you can "zoom in" from any relationship to discover the entire network of connections. 281 282 **How It Works**: 283 - **Focus on Connection**: The system only shows you what you share with others, never what separates you 284 - **Filter Bubble Dissolution**: When someone shares a monolithic idea (like "communism"), the system automatically breaks it into constituent sub-modules, creating multiple touchpoints for connection beyond the ideology 285 - **Contextual Perspective**: Ideas exist alongside grandma's recipes and childhood comics, naturally right-sizing ideological concepts 286 - **Dream Weaving**: You can "unweave" large concepts into smaller components, then re-weave them with different elements, creating bridges between seemingly opposed viewpoints 287 288 **The Result**: Instead of filter bubbles, you get an interconnected mycelium network where people constantly discover new relationships and deeper connections. Ideologies become "just one more thought form" among many, losing their disproportionate influence on human relationships. 289 290 **Social Resonance**: The Coherence Beacon system ensures that only genuinely coherent ideas spread, based on authentic resonance rather than viral manipulation. The network effect becomes heart-based rather than algorithm-driven. 291 292 ### What makes InterBrain different from existing knowledge management tools? 293 294 **Relational vs. Hierarchical**: Unlike traditional PKM tools that organize information in static categories, InterBrain organizes knowledge along the lines of your actual social relationships and interactions. 295 296 **Git-Native Architecture**: Every piece of knowledge is a git repository, enabling true version control, collaboration, and decentralized distribution of ideas. 297 298 **3D Spatial Interface**: Ideas exist in a 3D cosmos that reflects their relationships, moving beyond flat file structures to intuitive spatial navigation. 299 300 **Social Propagation**: Knowledge spreads through authentic social connections rather than algorithmic recommendation, creating trust-based rather than engagement-based distribution. 301 302 ### Why use git repositories for individual ideas? 303 304 **Version Control for Thoughts**: Ideas evolve over time - git tracks this evolution naturally while preserving the complete history of how your thinking developed. 305 306 **True Collaboration**: Multiple people can contribute to the same idea while maintaining clear attribution and merge capabilities. 307 308 **Decentralized Architecture**: No central server dependency - your knowledge remains yours while being shareable with your network. 309 310 **AI Integration**: Git-optimized AI tools (like Aider) work seamlessly with DreamNodes, turning AI assistants into universal co-creators for any type of knowledge. 311 312 **Future-Proofing**: As the system evolves toward DreamOS, the git foundation enables unprecedented composability between different applications and knowledge domains. 313 314 ## For Developers 315 316 Interested in contributing or understanding the technical architecture? 317 318 - **AI Development Guide**: See [CLAUDE.md](CLAUDE.md) for AI-first development patterns 319 - **Core Architecture**: See [src/core/README.md](src/core/README.md) for infrastructure and services 320 - **Feature Catalog**: See [src/features/README.md](src/features/README.md) for vertical slice architecture 321 - **Contributing**: See [CONTRIBUTING.md](CONTRIBUTING.md) 322 323 ## License 324 325 Project Liminality is released under the [GNU AFFERO GENERAL PUBLIC LICENSE](LICENSE). 326 327 ## Acknowledgements 328 329 Much of the philosophical foundation for this project has been created in conversation with my co-visionary and dear friend Anna Ziegler. Check out her one-of-a-kind work at https://goodfairy.gift