MultiverseNote v2

Introduction

MultiverseNote is an open-source terminal-based application that transforms AI chatbot interactions into structured knowledge management workflows. It introduces a branch management system where users can discuss topics on a main branch and create new branches for in-depth exploration, enabling systematic and continuous knowledge development.

Each conversation is organized into branches with numbered references (e.g. #1, #2), allowing you to fork discussions, load context from other branches, and tag conversation pairs for easy retrieval.

Core Architecture

Every component (UI, LLM, context management) runs as an isolated process node, communicating exclusively through Redis Pub/Sub. This ensures modularity and allows components to be developed, tested, and scaled independently.

flowchart LR
    UI["Terminal UI\n(Textual)"]
    CTX["ContextNode\n(Branch & Context)"]
    LLM["LLMNode\n(litellm)"]
    R[(Redis)]

    UI -- "ch:user_input" --> R
    R -- "ch:user_input" --> CTX
    CTX -- "store user node\n+ assemble context" --> R
    CTX -- "ch:llm_request" --> R
    R -- "ch:llm_request" --> LLM
    LLM -- "ch:llm_response" --> R
    R -- "ch:llm_response" --> UI

    style R fill:#dc382c,color:#fff
    style UI fill:#1a8cff,color:#fff
    style CTX fill:#2b8a3e,color:#fff
    style LLM fill:#7c3aed,color:#fff

Loading

---

Features

gitGraph
    commit id: "user: What is Rust?"
    commit id: "assistant: Rust is a..."
    branch deep-dive
    commit id: "user: Explain ownership"
    commit id: "assistant: Ownership in Rust..."
    branch ownership-examples
    commit id: "user: Show me borrowing"
    commit id: "assistant: Here is an example..."
    checkout deep-dive
    commit id: "user: What about lifetimes?"
    commit id: "assistant: Lifetimes ensure..."
    checkout main
    commit id: "user: Compare Rust vs Go"
    commit id: "assistant: Both are systems..."

Loading

• Branch Management — Create, switch, and navigate conversation branches with parent-child relationships
• Context References — New branches can reference existing branches, loading their conversation history as context for the LLM
• Tag System — Tag conversation pairs with colored labels for organization and retrieval
• Multi-Provider LLM — Supports OpenAI, Anthropic, and local models via litellm
• Terminal UI — Full keyboard-navigable TUI built with Textual
• Isolated Nodes — Each component runs as a separate process communicating via Redis
• File-based Logging — All logs written to rotating files, no terminal output clutter

---

Prerequisites

• Python >= 3.11
• Redis server running locally (default: localhost:6379)
• uv package manager
• An LLM API key (e.g. OPENAI_API_KEY for the default OpenAI provider)

---

Installation

# Clone the repository
git clone https://github.com/AhmadCodes/MultiverseNoteV2.git
cd MultiverseNoteV2

# Install dependencies
uv sync

---

Usage

Start Redis

redis-server

Set your API key

export OPENAI_API_KEY="sk-..."

Launch the application

uv run multiverse

Keyboard Shortcuts

Key	Action
Enter	Send message
Ctrl+B	Open branch tree
Ctrl+Q	Quit
Escape	Close modal / Go back
N	New branch (in branch tree)

---

Configuration

Configuration is managed via Hydra with composable YAML files in src/multiverse_note/conf/.

LLM Provider

Default is OpenAI. To use Anthropic:

uv run multiverse llm=anthropic

Or override individual settings:

uv run multiverse llm.model=openai/gpt-4o-mini llm.temperature=0.5

Redis

uv run multiverse redis.host=myhost redis.port=6380 redis.db=1

Config Files

src/multiverse_note/conf/
├── config.yaml            # Main config (composes all groups)
├── redis/default.yaml     # host, port, db, password
├── llm/
│   ├── default.yaml       # Default provider (OpenAI)
│   ├── openai.yaml
│   └── anthropic.yaml
├── ui/default.yaml        # Theme, layout preferences
└── logging/default.yaml   # Log level, file path, rotation

---

Process Model

flowchart TB
    MAIN["main.py\n@hydra.main"]

    MAIN -->|"multiprocessing.Process\n(daemon)"| CTX_PROC["ContextNode Process"]
    MAIN -->|"multiprocessing.Process\n(daemon)"| LLM_PROC["LLMNode Process"]
    MAIN -->|"runs in main process\n(needs terminal)"| UI_PROC["MultiverseApp (Textual)"]

    CTX_PROC -. "Redis Pub/Sub" .- REDIS[(Redis)]
    LLM_PROC -. "Redis Pub/Sub" .- REDIS
    UI_PROC -. "Redis Pub/Sub" .- REDIS

    MAIN -->|"SIGINT / Ctrl+Q"| SHUTDOWN["Graceful Shutdown"]
    SHUTDOWN -->|"ch:system → shutdown"| REDIS

    style REDIS fill:#dc382c,color:#fff
    style MAIN fill:#333,color:#fff
    style SHUTDOWN fill:#e67700,color:#fff

Loading

---

Project Structure

MultiverseNoteV2/
├── pyproject.toml                  # UV-managed dependencies
├── src/
│   └── multiverse_note/
│       ├── conf/                   # Hydra configuration (bundled in package)
│       ├── main.py                 # Entry point: launches all nodes
│       ├── models/                 # Data models (dataclasses)
│       │   ├── branch.py           # Branch model
│       │   ├── node.py             # ConversationNode model
│       │   └── tag.py              # Tag model
│       ├── store/                  # Redis storage layer
│       │   ├── redis_client.py     # Redis connection wrapper
│       │   ├── branch_store.py     # Branch CRUD operations
│       │   ├── node_store.py       # ConversationNode CRUD
│       │   └── tag_store.py        # Tag CRUD operations
│       ├── nodes/                  # Isolated process nodes
│       │   ├── base.py             # Abstract BaseNode class
│       │   ├── llm_node.py         # LLM processing node
│       │   └── context_node.py     # Context & branch management node
│       ├── ui/                     # Terminal UI (Textual)
│       │   ├── app.py              # Main Textual App
│       │   ├── screens/
│       │   │   ├── conversation.py # Active conversation screen
│       │   │   ├── branch_tree.py  # Branch navigation/overview
│       │   │   └── tag_select.py   # Tag selection modal
│       │   └── widgets/
│       │       ├── message_view.py # Renders conversation messages
│       │       ├── context_bar.py  # Shows loaded context refs
│       │       └── tag_badge.py    # Colored tag display
│       └── utils/
│           └── logging.py          # File-based logging utility
├── tests/                          # Test suite (51 tests)
│   ├── conftest.py                 # fakeredis fixtures
│   ├── test_models/
│   ├── test_store/
│   └── test_nodes/
└── logs/                           # Git-ignored log output

---

Redis Schema

erDiagram
    BRANCH {
        int id PK
        string name
        string created_at
        int parent_branch_id FK
        string status
    }
    BRANCH ||--o{ NODE : "branch:id:nodes"
    BRANCH ||--o{ BRANCH : "branch:id:context_refs"

    NODE {
        int id PK
        int branch_id FK
        string role
        string content
        string title
        string summary
        string timestamp
    }
    NODE ||--o{ TAG : "node:id:tags"

    TAG {
        int id PK
        string name
        string color
        string created_at
    }

Loading

Key Patterns

Key	Type	Description
counter:branch	int	Auto-increment ID for branches
counter:node	int	Auto-increment ID for nodes
counter:tag	int	Auto-increment ID for tags
branch:{id}	Hash	Branch metadata
branch:{id}:nodes	List	Ordered node IDs in a branch
branch:{id}:context_refs	Set	Referenced branch IDs as context
node:{id}	Hash	Conversation node data
node:{id}:tags	Set	Tag IDs assigned to a node
tag:{id}	Hash	Tag metadata
tags:all	Set	All tag IDs

Pub/Sub Channels

flowchart TB
    subgraph Channels
        direction LR
        ui_in["ch:user_input"]
        llm_req["ch:llm_request"]
        llm_res["ch:llm_response"]
        br_ev["ch:branch_event"]
        tag_ev["ch:tag_event"]
        sys["ch:system"]
    end

    UI(["Terminal UI"]) -->|user text| ui_in
    ui_in -->|consumed by| CTX(["ContextNode"])
    CTX -->|assembled context| llm_req
    llm_req -->|consumed by| LLM(["LLMNode"])
    LLM -->|response| llm_res
    llm_res -->|displayed by| UI

    UI -->|create/switch| br_ev
    br_ev -->|handled by| CTX
    UI -->|create/assign| tag_ev
    tag_ev -->|handled by| CTX

    MAIN(["main.py"]) -->|shutdown| sys
    sys -->|stops| CTX
    sys -->|stops| LLM
    sys -->|stops| UI

Loading

---

Testing

Tests use fakeredis to simulate Redis without a running server.

# Run all 51 tests
PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 uv run pytest tests/ -v

Test coverage includes:

• Model tests — Serialization roundtrips for Branch, ConversationNode, Tag
• Store tests — Full CRUD operations with fakeredis
• Node tests — BaseNode lifecycle, ContextNode branch/context/tag management, LLMNode with mocked litellm

---

Key Libraries

Purpose	Library
Terminal UI	textual
Redis	redis-py with hiredis
LLM Integration	litellm
Configuration	hydra-core
Package Management	uv
Testing	pytest + fakeredis

---

License

This project is released under the Apache License 2.0. See the LICENSE file for details.