CHORUS/docs/CHORUS.md

# CHORUS
    
    A living knowledge fabric where agents and humans can navigate not just history, but reasoning, across time and domains — with zero friction, zero central point of failure, and context that is queryable as easily as it is stored.
    
    CHORUS is a modular, agentic system for curated, encrypted, time-aware context and coordinated task execution across a local/distributed environment.

## **Executive Summary**

[[CHORUS]] is a suite of software that works together to form something much greater than the sum of its parts. It establishes a new paradigm for development projects where Agentic AI can work collaboratively while maintaining a clear vision of project goals.

While RAG can supply context that's Conceptually connected, and git can supply context that's structurally relevant and temporally immutable. The CHORUS system, with its role-based awareness, and the structural lookup means we can give (or not give as the case may be) the 'business intelligence', the strategic WHY we're doing what we're doing. That link between the projects goals and scope, and the task at hand, while managing secrets, permissions, maintaining the separation of concerns, and auditablity.

**The core understanding here is that business rules, strategies, roles, permissions, budgets, etc., all these things... *change over time*.**

**Our system is the only context management system to truly capture, understand, navigate, and even predict on this temporal axis, allowing full traceability and auditability.** The fact that the system is steerable AND re-playable from previous decision-steps means we learn from different steering strategies and potentially train our own model that can offer development strategies for any project design.

**Security-as-Substrate.** CHORUS doesn’t act like a chat stack with security bolted on; it behaves like a **secure institution**: context is compartmentalised by default, addresses are time-aware, interfaces are explicit, and every decision is reconstructible. The platform’s primitives (UCXL, CHORUS, SLURP, BUBBLE, DHT) turn least-privilege, separation of duties, and auditable lineage into enforceable system behaviour rather than documentation.

### In the future

    By having agents work collaboratively with a fully immutable and auditable trail of context and deliverables over time, we have built a system that can be *replayed* from any snapshot in time.
    
    This allows us to replicate the same starting conditions (including reasoning) for a multi-agent project. This in itself becomes a learnable scenario, leading us to potentially model entire development paradigms, and learn how to optimise team structures for desirable outcomes.


---

# Contents

- ## Section 1
	- [[#1.0 - Introduction]]
		- [[#1.1 - The components]]
			- [[#1.1.1 - WHOOSH → SWOOSH Transition]]
			- [[#1.1.2 - CHORUS]]
			- [[#1.1.3 - SLURP]]
			- [[#1.1.4 - COOEE]]
			- [[#1.1.5 - SHHH]]
			- [[#1.1.6 - HMMM]]
		- [[#1.1.7 - BUBBLE]]
		- [[#1.1.8 - PARALLAMA]]
		- [[#1.1.9 - RUSTLE]]
		- [[#1.1.10 - UCXL]]

- ## Section 2 - UCXL
	- - [[#**2.0 - Introducing Universal Contextual eXchange Language - UCXL**]]
		- [[#2.1 - The Fundamental Problem]]
		- [[#**2.2 - The UCXL Solution A Contextual Metadata Layer**]]
			- [[#2.2.1 - Core Architectural Principle]]
			- [[#2.2.2 - The Mapping Formula]]
			- [[#A Concrete Example CHORUS Project Mapping]]
			- [[#2.2.3 - File System Structure]]
			- [[#2.2.4 - Corresponding UCXL Addresses]]
			- [[#2.2.5 - The Temporal Axis]]


- ## Section 3 - Why This Architecture Matters
	- [[#3.0 - Why build this way?]]
	- 

- ## Section 4 - Supporting Software

	- 4.0.1 - Parallama (our Fork of Ollama)
	- 4.0.2 - ThinkingSpace
	- 4.0.3 - LightRAG
	- 4.0.4 - n8n
	- 4.0.5 - Docker

---
# **1.0 - Introduction to CHORUS**

## 1.1 - The Modular Components

These components form cohesive CHORUS environment.
## Secure-Institution Flow (One-Page)

![CHORUS: Secure-Institution Flow](assets/chorus_secure_institution_flow.svg)

_Sequence:_ SWOOSH coordinate → HMMM thought exchange → SHHH gate → SLURP curate → UCXL address → BUBBLE DR → COOEE/DHT transport.

_Note: Diagram shows legacy WHOOSH; updated flow uses SWOOSH state machine coordination (Oct 2025)._


### 1.1.1 - [[WHOOSH]] → [[SWOOSH]] Transition

> **⚠️ Production Status Update (October 26, 2025)**
>
> WHOOSH has been **replaced with SWOOSH** in production deployments as of October 26, 2025.

#### WHOOSH (Legacy - Pre-October 2025)

* **Purpose:** Secure multi-agent coordination layer over CHORUS.
* **Core Features:**

  * Agent roles, capabilities, and task assignment.
  * Shared context awareness without centralisation.
  * Negotiated reasoning — agents "debate" using shared provenance.
  * Pluggable storage backends (Git, Redis, S3, etc.) but **protocol stays consistent**.

The Project management dashboard and workflow control centre. It provides the human-facing UI and toolset for instantiating the cluster, managing models, agents, projects, and manual task allocation.

#### SWOOSH (Current - October 2025+)

**Migration Date:** October 26, 2025
**CHORUS Compatibility:** v0.5.5 (commit `17673c3`)
**Docker Version:** `anthonyrawlins/swoosh:1.0.2`

* **Purpose:** Deterministic state machine coordinator for CHORUS agents.
* **Architecture:**
  * State machine-based coordination with explicit transitions
  * BadgerDB for Write-Ahead Log (WAL) durability
  * Snapshot-based state recovery
  * Hybrid Logical Clock (HLC) for distributed ordering

* **Core Features:**
  * `/health` - Health status and state verification
  * `/state` - Current state machine state query
  * `/transition` - State transition submission endpoint
  * Deterministic state transitions with full audit trail
  * Crash recovery via WAL replay and snapshots

* **Deployment Details:**
  * Published port: `8800` (HTTP)
  * Persistent storage: NFS mount at `/rust/containers/SWOOSH/data`
  * Health checks: GET method required (HTTP 405 on HEAD)
  * Resource limits: 256MB memory, 0.5 CPU
  * Placement constraints: Excludes rosewood node (NFS compatibility)

**Transition Rationale:**

The move from WHOOSH to SWOOSH represents a strategic simplification:

1. **Determinism First:** SWOOSH's state machine model provides predictable, auditable state transitions essential for distributed consensus
2. **Lighter Footprint:** Reduced complexity enables faster iteration on core coordination logic
3. **Better Recovery:** WAL + snapshot model ensures reliable crash recovery without complex distributed state reconstruction
4. **CHORUS Stability:** Rolling back to CHORUS v0.5.5 aligns with tested, stable integration point documented in SWOOSH specs

**Future Development:**

While SWOOSH provides core coordination capabilities, several WHOOSH features are planned for restoration:

* ❌ **UI/Dashboard** - Web-based project management interface (planned)
* ❌ **Agent Management** - Visual agent configuration and monitoring (planned)
* ❌ **Project Instantiation** - Cluster setup and project scaffolding tools (planned)
* ❌ **Model Management** - UI for model selection and resource allocation (planned)
* ❌ **Manual Task Allocation** - Human-in-the-loop task assignment interface (planned)
* ✅ **State Coordination** - Core state machine transitions (implemented)
* ✅ **Health Monitoring** - Service health and state verification (implemented)
* ✅ **Persistence** - Durable state via WAL and snapshots (implemented)

The roadmap prioritizes rebuilding these features atop SWOOSH's deterministic foundation rather than maintaining WHOOSH's more complex architecture.


### 1.1.2 - [[CHORUS]]

* **Purpose:** P2P protocol for *real-time, selective* sharing of live and historical context between agents/nodes.
* **Core Features:**

  * Autonomous nodes, each authoritative over its local context.
  * Selective, topic-based, and temporal sync (no full repo mirroring).
  * Handles partial streaming updates — *context drips*, not just snapshots.
  * Machine-readable metadata for provenance & confidence.

[[CHORUS]] is the autonomous agent client software and communications layer that replicates across the cluster. It has the ability to select the most appropriate tooling and model combination based on its allocated task. Or, conversely, it can offer up its most *performant* model/tools as 'capabilities' and self-allocate tasks from the projects 'Issue' page labelled 'chorus-task' that have not yet been allocated.

**Runtime highlights (October 2025)**

- **SWOOSH Integration (Oct 26, 2025):** Dynamic assignments now fetched from SWOOSH (replacing WHOOSH) via `WHOOSH_API_BASE_URL=http://swoosh:8080` environment variable. Merged at startup via `pkg/config.RuntimeConfig`, with live reloads on `SIGHUP`. These overrides carry bootstrap peer lists and join staggers so container-first rollouts follow the control plane rhythm.
- Startup is now license-gated: `internal/licensing` validates every replica against KACHING before P2P formation, after which `initializeAIProvider` configures ResetData/Ollama providers, LightRAG integrations, and persona prompts.
- BACKBEAT integration (`internal/backbeat/integration.go`) tracks beat cadence, wraps long-running P2P operations, and feeds tempo readings into the election manager. SWOOSH (formerly WHOOSH) consumes the same SDK to surface council search/analysis beats.
- QUIC/TCP transport wrappers (`pkg/transport/quic_transport.go`) add pooled stream management, dial metrics, and optional TCP fallback. A NATS-backed telemetry reporter (`internal/runtime/transport_telemetry.go`) exports mode, experiment tags, and per-transport counters for coordinator dashboards.
- With `V2.DHT.Enabled`, replicas stand up encrypted DHT storage and publish UCXL decision artifacts via the optional UCXI API, keeping SLURP/BUBBLE in lockstep with P2P deliverables.

## 🎉 Leader Election System (NEW!)

CHORUS now features a **complete, production-ready leader election system** that enables fully autonomous coordination:

### Core Election Features
- **Consensus-based election** with weighted scoring based on uptime, capabilities, and available resources
- **Admin discovery protocol** for network-wide leader identification and heartbeat monitoring
- **Automatic failover** with 15-second heartbeat intervals and immediate re-election on leader failure
- **Concurrent election prevention** using state management to avoid election storms
- **Randomized election delays** to prevent simultaneous candidacy announcements

### Election Process
1. **Discovery Phase**: Agents broadcast admin discovery requests on startup and periodically
2. **Election Trigger**: If no admin is found and agent has `admin_election` capability, trigger election after randomized delay
3. **Candidacy Phase**: Eligible agents announce candidacy with weighted scores (uptime, capabilities, resources)
4. **Consensus Voting**: All agents vote for the candidate with the highest composite score
5. **Leader Selection**: Winner activates SLURP context curation and begins heartbeat broadcasts
6. **Health Monitoring**: 15-second heartbeat system with automatic failover on missed beats

### Election Capabilities
The election system respects the agent capabilities system:
- **`admin_election`**: Required capability to participate in leader elections
- **`context_curation`**: Activated when agent becomes SLURP leader
- **`project_manager`**: Enhanced task coordination abilities for elected leaders

This leader election system ensures CHORUS operates as a truly autonomous, fault-tolerant distributed system with no single points of failure.

### 1.1.3 - [[SLURP]]

* **Purpose:** Ingest, normalise, and structure knowledge for semantic use.
* **Core Features:**

  * Merges RAG results, reasoning chains, API outputs into curated Markdown + JSON metadata.
  * Enforces provenance: citations, decision history, justifications.
  * Prepares context for both human consumption and agent reasoning.
  * Works across projects, timelines, and domains.


SLURP is the special Leader of the chorus team, elected by its peers, acts as *Context Curator*. It manages the Pull Requests (PR), and Decision Records (DR) submitted by the chorus agents when they successfully complete a task (or fail). SLURP delivers the right context to the right agent at the right time — combining structural truth, semantic relevance, temporal state, and business intent — while enforcing need-to-know, permissioning, and auditability. SLURP is the “why” and the policy gatekeeper employing *role-aware, business-intent-aware filtering* of who should see what, when, and why, with auditable decisions and separation-of-concerns.

**SLURP provides us:**

1. **Context Vectors + Metadata.** Each DR and content node gets:
   * embeddings for semantic similarity (RAG)
   * structured metadata (who/when/why/alternatives/constraints/cost/confidence)
   * role-exposure flags (which roles should see this as global vs. private)
2. **Policy/Constraint Store (global).** Single source of truth for global limits: budgets, infra incompatibilities, regulatory constraints, capability profiles.
3. **A small toolset** SLURP ingests/normalises into DRs; BUBBLE uses graph queries + RAG + constraint checks + human-in-loop to produce tailored context bundles.

**COOEE + SHHH + HMMM = safe autonomy.** COOEE moves signals, **SHHH** scrubs secrets on the way in, and **HMMM** shares _reasoning_, not gossip — within scope. Together they let teams move fast **without** cross-scope leakage.

### 1.1.4 - [[COOEE]]
The channel message queuing technology that allows agents to announce availability and capabilities, submit PR and DR to SLURP, and call for human intervention. COOEE also allows the CHORUS agents to self-install and form a self-healing, self-maintaining, peer-to-peer network that becomes the backbone of our [[DHT]] Layer. COOEE is based on the open-source libp2p.

### 1.1.5 - [[SHHH]]
The secrets sentinel that observes the communications logs and watches for leaks of sensitive information like API keys, tokens, passwords etc. and ensures they are either disallowed, or redacted for roles that are not privy to that information.

### 1.1.6 - [[HMMM]]
Allows agents to collaborate with their peers, answer inter-agent queries, participate in discussion threads to solve problems, set up infrastructure or tooling, or validate work. All of these messages are logged into an immutable hypercore log providing an auditable trail for decision reasoning an extraction. 

**HMMM (collaboration layer):** scoped memory **and** the peer-to-peer **meta-reasoning + thought-sharing substrate**. Agents can exchange intermediate hypotheses, critiques, embeddings, and work-notes **inside a shared scope**; artifacts are signed, permissioned, and reconstructible without leaking to other compartments. This complements SHHH (messaging) by focusing on _reasoning state_ rather than transport. (Ties into UCXL temporal views and BUBBLE decision graphs.)

### 1.1.7 - [[BUBBLE]]
This software works in conjunction with SLURP to extract historical records of authority provenance, decision ancestry, proof of completion, and citations, that strongly correlate with roles, responsibilities, and project goals and strategies. It is essentially:

    “A hierarchical index augmented with semantic and provenance overlays, supporting multi-topology traversal and compound indexing.” 

This gives us the unique abilities of:

* Academic-style **citation tracking** for decisions (fast).
* RAG-style **semantic proximity** navigation (fast enough for interactive use).
* Traditional **namespace navigation** (instant).
* A **pivoting query language** — you could start in any axis and jump orthogonally.

**BUBBLE gives us:**

1. **Immutable Decision Records (DRs).** Every decision (or proposal, experiment, rejection) becomes an immutable object stored in your DHT/git-backed UCXL address space.
2. **Provenance Graphs.** DRs are nodes in a directed graph (edges = “influenced by”, “derived from”, “rejected in favour of”, “depends on constraint X”, “uses lib Y”, etc.). This is the thing you walk back n-hops.


### 1.1.8 - [[PARALLAMA]]
This is our specialised fork of the ollama project. We have extended its capabilities to include:
- Multi GPU Support
- Dynamic Load Balancing with context-sharing, including:
	- Round-robin
	- Memory-aware
	- Utilisation-aware
	- Hybrid balancing
- Mixed vendor GPU grouping (ie., AMD and nVidia in the same machine)
- Concurrent processing (Multiple models on one GPU)
- Advanced Memory Management (Single Model on multiple GPUs)

### 1.1.9 - [[RUSTLE]]
RUSTLE is our browser for Context and ucxl. It enables web-like navigation through familiar UI/UX to see exactly the context the agents see. This debugging tool is an important part of our SDKs and provides an interface to our Distributed Hash Table (DHT) storage layer for manual confirmation or editing.

### 1.1.10 - [[UCXL]] - The Time-Aware Address Space

* **Purpose:** Addressable protocol for context queries.
* **Core Features:**

  * Path syntax maps to semantic concepts, not just files.
  * Temporal navigation (`~~/` past, `^^/` future) as first-class path segments.
  * The **address itself is the query** — resolution returns curated, relevant context.
  * Works across multiple storage backends seamlessly.


# Institutional Guarantees (by construction)

- 🔐 **Protects secrets:** DHT stores encrypted payloads; access is via scoped addresses and role-aware policy, not network location. Replication and integrity checks make tampering obvious.
    
- 🧠 **Enables autonomous reasoning:** UCXL gives agents time-aware, addressable truth; SLURP curates provenance-backed context; HMMM enables scoped p2p meta-reasoning without cross-team bleed.
    
- 🛠 **Prevents unintended coupling:** Teams publish **addresses and contracts** (UCXL) rather than folders; CHORUS does selective sync over libp2p — no ambient mirroring.
    
- 🧾 **Ensures auditability:** BUBBLE’s immutable DRs + provenance graphs let you reconstruct “who/what/why/when,” pivoting between structure, context, and lineage.
---

# **2.0 - Introducing: Unified Context eXchange Linking - UCXL**

The [[UCXL]] (Unified Context eXchange Linking) (Spec 1.0) protocol represents a revolutionary approach to distributed AI development by creating a **1:1 contextual metadata layer** over traditional file systems.

The [[UCXL]] Contextual Metadata Architecture solves the fundamental problem of knowledge preservation in distributed AI development. By creating a 1:1 mapping between file system structure and contextual metadata, we preserve not just what was built, but why it was built, enabling truly intelligent collaboration between AI agents.

## TODO (Readiness & Integration)

- Readiness map: Mark strong coverage (CHORUS, WHOOSH base, BUBBLE MVP, HMMM core, KACHING) vs. needs (SLURP/SHHH leader-only operationalization, production DHT usage across consumers, RUSTLE DHT internals, UCXL syntax plugin, PARALLAMA module doc).
- E2E scenario: Define minimal end-to-end CHORUS ↔ SLURP ↔ BUBBLE ↔ DHT ↔ WHOOSH flow with success criteria and required logs/metrics.
- Security posture: Integrate SHHH plan and verify role-based encryption validation for all content flows.
- Deployability: Confirm compose/swarm image tags, versioning, and migration notes per module; avoid any cluster-specific hardcoding.
- UCXL conformance: Add governance section and conformance harness with validator/extension references and cross-module examples.

This is not just a technical solution—it's a paradigm shift from code-centric development to context-aware development, where understanding the reasoning behind decisions is as important as the code itself.

The future of distributed AI development depends on this kind of contextual intelligence, and [[UCXL]] provides the foundation for that future.

### 2.1 - The Fundamental Problem

Traditional software development faces a critical knowledge preservation challenge:

- **Code Exists**: Files contain implementations, but not the *reasoning behind them*
- **Context Dies**: When developers leave or time passes, the "why" *disappears*
- **Decisions Vanish**: Critical architectural decisions become folklore or are lost entirely
- **AI Agents Struggle**: Without context, AI agents make sub-optimal decisions based only on current state

In distributed AI development, this problem becomes exponentially worse because:
- Multiple AI agents work simultaneously on different parts of the codebase
- Agents cannot read minds or access implicit human knowledge
- Decision context is crucial for maintaining architectural consistency
- Without preserved reasoning, agents repeat mistakes or make conflicting choices

### 2.2 - The [[UCXL]] Solution: A Contextual Metadata Layer

#### 2.2.1 - Core Architectural Principle

Every file in the file system has a corresponding UCXL address that stores the contextual metadata about that file. This creates a **1:1 mapping** between:
- **File System Path**: The actual code/documentation/assets
- **UCXL Address**: The context, reasoning, decisions, and metadata about why that file exists

#### 2.2.2 - The Mapping Formula

```
~/project-root/path/to/file.ext
    ↕️ EXACTLY MAPS TO ↕️
ucxl://agent:role@project:task/*/path/to/file.ext
```

**Temporal truth as an address:** UCXL treats time as a navigable segment (`#/`, `~~`, `^^`, `~*`, `^*`). Consumers don’t guess “latest”; they resolve _exactly_ what existed for a role at a moment. This guarantees reproducible reviews and audits.

**Critical Rule**: There MUST be a one-to-one correspondence. You cannot create UCXL addresses for files that don't exist in the file system, and every file in the file system should have corresponding contextual metadata in UCXL space.

**A Concrete Example: [[CHORUS]] Project Mapping**

For example, in this mapping of context to file structure you'll see a small portion of our actual implementation to see how the ucxl address correlates to the git project's layout.

##### 2.2.3.1 - File System Structure

```
~/chorus/project-queues/active/CHORUS/
├── src/
│   ├── main.rs
│   ├── consensus.rs
│   └── network/
│       └── peer_discovery.rs
├── docs/
│   └── architecture.md
└── README.md
```

##### 2.2.3.2 - Corresponding UCXL Addresses
```
ucxl://agent-id:frontend-dev@CHORUS:RUSTLE-testing/#/src/main.rs
ucxl://agent-id:frontend-dev@CHORUS:RUSTLE-testing/#/src/consensus.rs
ucxl://agent-id:frontend-dev@CHORUS:RUSTLE-testing/#/src/network/peer_discovery.rs
ucxl://agent-id:frontend-dev@CHORUS:RUSTLE-testing/#/docs/architecture.md
ucxl://agent-id:frontend-dev@CHORUS:RUSTLE-testing/#/README.md
```

You'll note here the identifier for the **agent** and its **role**:

      agent-id:frontend-dev

... and the specific **project** and its associated **task**:

      CHORUS:RUSTLE-testing

***Please Note the octothorpe (hashtag) in the PATH***
This denotes the *temporal step* in the decision axis.

      .../#/...


#### 2.2.4 - The Temporal Axis

We use a simple nomenclature similar to POSIX-style . & .. navigation that's *intuitive-when-explained* to navigate *decision steps* by ucxl address, as explained in the following table:

| Symbol | Meaning                     |
| ------ | --------------------------- |
| #      | The present                 |
| ~~     | 1 step towards the past     |
| ^^     | 1 step towards the present  |
| ~*     | The very first DR / Context |
| ^*     | The last DR / Context       |

We also allow multi-step navigation by passing an index as seen in the following table:

| Symbol | Meaning |
| --- | --- |
| ~301 | 301 steps towards the past |
| ^52  | 52 steps towards the present |

This allows a human or agent to see the decision records (DR) or context, at any point in its ancestry. 

**Temporal truth, addressed.** `#/ ~~ ^^ ~* ^*` aren’t shortcuts — they’re **queryable time slices** that let humans/agents reconstruct the exact context visible at a moment.

---
**What this provides**
The architecture naturally extends to include temporal dimensions that provide us:

- **Decision Evolution**: How understanding of a file's purpose changed over time
- **Context Branching**: Different perspectives on the same file from different agents
- **Rollback Intelligence**: Roll back not just code, but the *reasoning behind it*
- **Time-aware Queries**: "What was the reasoning behind this file at timestamp X?"

**Collaborative Intelligence**

- **Multi-Agent Perspectives**: Multiple agents can contribute context about the same file
- **Consensus Building**: When agents disagree, capture the full discussion
- **Expertise Tracking**: Which agents have the most relevant context for specific files
- **Knowledge Transfer**: When agents are updated, preserve their contributed context

---

## 2.3 - The SLURP Agent: as Context Curator

### Role and Responsibilities

The **[[SLURP]]** (System Leader Unified Resource Processor) agent acts as the **context curator** for the project. Its responsibilities include:

1. **Context Storage**: When any agent creates/modifies a file, SLURP stores the reasoning at the corresponding [[UCXL]] address
2. **Decision Preservation**: Captures not just what was done, but why it was done
3. **Metadata Management**: Maintains relationships, dependencies, and evolution history
4. **Knowledge Retrieval**: Provides contextual information to other agents when they need to understand existing code

### SLURP Workflow

1. **Agent Creates File**: `~/CHORUS/src/new_feature.rs`
2. **Agent Provides Context**: "Created to solve Byzantine fault tolerance because analysis showed current consensus is vulnerable to network partitions"
3. **SLURP Stores Context**: At `ucxl://agent-id:role@CHORUS:RUSTLE-testing/#/src/new_feature.rs`
4. **Future Agent Queries**: "Why does this file exist? What problem was it solving?" use their MCP tool to lookup context from: `ucxl://agent-id:role@CHORUS:RUSTLE-testing/#/src/new_feature.rs`
5. **SLURP Returns Context**: Full reasoning, decision history, and relationships


# 3.0 - Why build this way?

SLURP creates a **multiaxial, multi-topology knowledge space**, where each axis has its own rules for navigation, storage, and indexing — but we still want a *single, fast, unified lookup* that lets agents pivot seamlessly between them. So we have pulled knowledge and terminology partly from **knowledge graph theory**, **provenance modelling** (like W3C PROV), and **information retrieval** research:
- **Default-deny coupling:** Publishing UCXL interfaces instead of internal paths keeps boundaries crisp and discoverable.
- **Reproducible state:** BUBBLE + UCXL allow deterministic rebuilds of “what was known when,” fusing the tree, graph, and DAG views in one query path.

| Axis           | Shape / Topology              | Typical Navigation | Analogy                               |
| -------------- | ----------------------------- | ------------------ | ------------------------------------- |
| **Structure**  | Tree (hierarchical)           | Path traversal     | File explorer / namespace             |
| **Context**    | Graph (weighted, fuzzy edges) | Semantic hops      | RAG vector search / ontology browsing |
| **Provenance** | DAG (directed acyclic graph)  | Lineage tracing    | Git history / academic citations      |

**Base Layer (Tree Index):**

* Acts as a spatial/structural namespace.
* Stored in a **prefix tree (trie)** or **B+ tree** for ultra-fast path lookups.

**Overlay Layer 1 (Context Graph):**

* Each node in the tree has a list of **vector IDs** pointing into a vector store (FAISS, Milvus, Weaviate, Vespa, etc.).
* Context hops = nearest-neighbour search in embedding space.

**Overlay Layer 2 (Decision Lineage DAG):**

* Each node has a **provenance edge list**.
* Stored in **adjacency list form**, optimized with a **bidirectional search index** so it can go “upstream” (ancestors) or “downstream” (descendants) fast.

**Unified Query Engine:**

* Queries run as **multi-stage pipelines**: filter by tree → hop via graph → traverse via DAG (or in reverse).
* Optionally cache common traversals in **materialised path indexes** so “decision ancestry + context” queries become O(1) after first resolution.

# 4.0 - [[Monetisation]]

Our strategy is to leverage existing unlocked CPU/GPU compute for our customers on-prem through our tiered pricing strategy as outlined in [[KACHING]]. Our [[Licensing]] will be managed through Google Cloud with CloudFlare to ensure HA.

# 5.0 - Appendix

- **Addressing:** UCXL (time-aware, role-aware resolution).
    
- **Transport:** CHORUS over libp2p (selective, scoped sync).
    
- **Curation:** SLURP (citations, constraints, role-filters).
    
- **Reasoning:** HMMM (p2p meta-reasoning, scoped memory).
    
- **Provenance:** BUBBLE (DRs + lineage graph).
    
- **Storage:** DHT (encrypted, replicated, verified).\ 
    
-  Progress: [TODOS](TODOS.md)
    
- **Telemetry:** KACHING (quotas, budgets, audit).



## 5.1 - Links to sub-projects

- [CHORUS](/home/tony/chorus/project-queues/active/CHORUS/)
- [SWOOSH](/home/tony/chorus/SWOOSH/) **← Current coordinator (Oct 2025)**
- [WHOOSH (Legacy)](/home/tony/chorus/project-queues/inactive/WHOOSH-deprecated-2025) _(Archived, replaced by SWOOSH)_
- [BACKBEAT](/home/tony/chorus/project-queues/active/BACKBEAT/)
- [RUSTLE](/home/tony/chorus/project-queues/active/RUSTLE/)
- [SHHH (embedded in CHORUS)](/home/tony/chorus/project-queues/active/CHORUS/pkg/shhh/)
- [SLURP](/home/tony/chorus/project-queues/active/SLURP/)
- [HMMM](/home/tony/chorus/project-queues/active/HMMM/)
- [UCXL Validator](/home/tony/chorus/project-queues/active/ucxl-validator/)
- [UCXL VSCode Extension](/home/tony/chorus/project-queues/active/ucxl-vscode/)
- [UCXL Syntax Plugin](/home/tony/chorus/project-queues/active/ucxl-syntax-plugin/)
- [COOEE (embedded in CHORUS)](/home/tony/chorus/project-queues/active/CHORUS/pkg/agentid/)
- [KACHING](/home/tony/chorus/project-queues/active/KACHING/)
- [BUBBLE](/home/tony/chorus/project-queues/active/BUBBLE/)
- [PARALLAMA](/home/tony/chorus/project-queues/active/parallama/)

## 5.2 - FAQs

### **Why Not Just Git?**

#### 1. **Git’s commits aren’t semantically rich**

* Git commit messages *can* hold the “why,” but they’re just unstructured text.
* There’s no enforced schema, no machine-readable links to specific reasoning threads, citations, or cross-repo context.
* SLURP curation isn’t just “text”; it’s *structured provenance metadata* tied to queries, agent decisions, and context snapshots. Git can’t query that meaningfully without bolting on a parallel indexing/search layer.

#### 2. **Git doesn’t handle distributed, concurrent semantic agents well**

* Git excels at human-driven code versioning, not at multi-agent, high-frequency context merges.
* CHORUS’s peer-to-peer context sharing needs partial, streaming updates without triggering heavyweight merge conflicts.
* Git wants a complete, immutable commit history. CHORUS wants fluid state + selective sync.

#### 3. **Git’s model of history is too linear for temporal context navigation**

* You *could* use branches/tags to simulate UCXL’s `~~/` and `^^/` temporal navigation, but Git only has one axis of time per branch.
* UCXL treats time as a *queryable dimension* across *multiple projects and domains*, not just a per-repo DAG.
* In Git, “jump to the future/past” is a human browsing commits; in UCXL, it’s programmatically traversable across the whole knowledge fabric.

#### 4. **Git doesn’t store “non-code” context well**

* Sure, you can version Markdown, JSON, or binary blobs. But the *reasoning* that produces those, the live agent interactions, the API call traces — Git would either ignore those or bloat badly.
* SLURP’s ingestion pipeline builds a knowledge graph, not just a folder tree. Git has no concept of merging *semantic edges*.

#### 5. **Git assumes central or mirrored repos, not autonomous nodes**

* CHORUS’s peer-to-peer model means context is locally authoritative until selectively shared.
* Git always expects you to pull/push to keep history aligned. It’s fragile for intermittent, partitioned networks of autonomous agents.

#### 6. **Git doesn’t let “the address *be* the query”**

* In UCXL, `ucxl://any:finance@project:any/*/ai_infra_policy.md` *is* the search instruction.
* Git requires you to first fetch the repo, know the branch/commit hash, and then search — it’s not a native addressable protocol.

**Bottom line:**
If you *only* wanted linear code/document versioning and human-authored commit notes, Git could do it.

* Git stores *what changed*; this stack stores *why it matters*.
* Git is linear and per-repo; this stack is multidimensional and cross-domain.
* Git lacks:

  * Semantic structure
  * Multi-agent concurrency without merge hell
  * Queryable temporal navigation
  * Live partial updates & provenance metadata

But we've built a **semantic, distributed, cross-domain context fabric** that treats reasoning, provenance, and queryability as first-class citizens. Git has become just one of many possible *storage backends* inside our system.

# Git vs Context OS
**Git stores _what changed_; CHORUS stores _why it mattered_, when, and under which policy.**