Chatbot vs. Agent — The Core Distinction

A chatbot is a text-in, text-out function. It has no memory, no tools, no autonomy. Ask it today and it won’t remember tomorrow. It can’t check your calendar, file a bug, or search your documents.

An agent operates on a fundamentally different loop. It perceives (receives events from Slack, Discord, Teams, Web), reasons (decides what action to take), acts (calls tools via MCP), and remembers (persists context across sessions). BUD is an agent.

How LLMs Actually Work (The 60-Second Version)

Large Language Models like Claude are neural networks trained on massive text data. Given a sequence of tokens, they predict the next most probable token. At scale — billions of parameters — this simple mechanism produces reasoning, code, tool invocations, and nuanced conversation.

The critical insight for agent builders: LLMs don’t execute code or call APIs. They generate structured text (JSON) that describes which tool to call with what arguments. Your code then executes the tool and feeds the result back. This is the “agent loop.”

What Are Embeddings?

Embeddings convert text into dense numerical vectors — arrays of floating-point numbers that encode semantic meaning. Similar meanings produce vectors that are geometrically close in high-dimensional space. This is how BUD can search conversations by meaning, not just keywords.

BUD uses all-MiniLM-L6-v2 from sentence-transformers — runs locally with zero API cost, produces 384-dimensional vectors, sub-50ms latency. These power the RAG pipeline.

Model Context Protocol (MCP)

MCP is what makes BUD’s tool system scalable. Instead of hardcoding every integration, MCP defines a standard protocol (JSON-RPC over stdio) where tool servers announce their capabilities and the AI client discovers them automatically. Think USB for AI tools — plug any MCP server into any MCP client.

Why Build From Scratch? (No LangChain, No Frameworks)

BUD deliberately avoids LangChain, LlamaIndex, CrewAI, and every other framework. Not because they’re bad — because the goal is understanding. When you build the agent loop yourself, you understand exactly why retry logic matters, why memory needs layers, why RAG needs chunking strategies. In an interview, you can explain every component because you built every component.

Project File Structure

The Core Code — agent/core.py

This is the most important file in the entire project. Let’s walk through the key function:

async def process_message(self, user_msg: str, channel: str, user_id: str) -> str:
    # Step 1: Classify intent — avoid expensive API calls for simple messages
    intent = classify_intent(user_msg)

    if intent == "greeting":
        return random_greeting(user_id)  # $0 — no API call needed

    # Step 2: Assemble context from all memory layers
    memory_context = await self.memory.get_context(user_id, channel)
    rag_results = await self.rag.search(user_msg, top_k=5)
    tools = await self.mcp_manager.get_all_tools()

    # Step 3: Build the system prompt
    system = build_system_prompt(
        soul=self.memory.soul,
        memory=memory_context,
        rag=rag_results,
        tools_hint=summarize_tools(tools)
    )

    # Step 4: Call Claude with full context
    messages = [{"role": "user", "content": user_msg}]

    # Step 5: The Tool Loop — up to MAX_TOOL_ROUNDS iterations
    for round in range(5):  # Safety cap: max 5 rounds
        response = await self.call_claude(
            system=system,
            messages=messages,
            tools=tools,
            timeout=30.0  # Triple-timeout protection
        )

        # If Claude returns text → we're done!
        if response.stop_reason == "end_turn":
            final_text = response.content[0].text
            break

        # If Claude returns tool_use → execute and loop
        if response.stop_reason == "tool_use":
            tool_call = extract_tool_call(response)
            result = await self.mcp_manager.execute(
                tool_call.name, tool_call.input
            )
            # Feed result back to Claude for next iteration
            messages.append({"role": "assistant", "content": response.content})
            messages.append({"role": "user", "content": [tool_result_block]})

    # Step 6: Remember this interaction
    await self.memory.update(user_id, user_msg, final_text)
    await self.rag.index_message(user_msg, channel)

    return final_text

Intent Classification — Saving 85% on API Costs

Before calling Claude’s API ($3/MTok for Opus), BUD checks if the message even needs an LLM. Simple greetings, thank-yous, and status checks are handled by a zero-cost heuristic classifier:

def classify_intent(text: str) -> str:
    lower = text.lower().strip()

    # Greetings — no API needed
    greetings = {"hi", "hello", "hey", "morning", "sup", "yo"}
    if lower in greetings:
        return "greeting"

    # Tool-required tasks — needs Claude + MCP
    tool_markers = ["create issue", "github", "notion", "schedule", "remind"]
    if any(m in lower for m in tool_markers):
        return "tool_task"

    # Complex questions — needs Claude
    if len(text.split()) > 5 or "?" in text:
        return "complex"

    return "simple"  # Use Haiku (cheaper model)

This simple heuristic routes ~40% of messages away from the expensive API entirely, and another ~30% to the cheaper Haiku model, achieving that 85% cost reduction — from $15/month to $2/month.

How MCP Discovery Works

# BUD starts each MCP server as a subprocess
async def connect_mcp_server(self, server_path: str):
    process = await asyncio.create_subprocess_exec(
        "python", server_path,
        stdin=asyncio.subprocess.PIPE,
        stdout=asyncio.subprocess.PIPE
    )

    # Step 1: Ask the server what tools it has
    request = {"jsonrpc": "2.0", "method": "tools/list", "id": 1}
    tools = await self.send_rpc(process, request)

    # Step 2: Register all discovered tools
    for tool in tools:
        self.registry[tool["name"]] = {
            "process": process,
            "schema": tool["inputSchema"]
        }
    # Now Claude can see and use these tools automatically!

Why File-Based Memory?

Every memory file is plain Markdown you can read, edit, and version control. No hidden databases, no opaque vector stores for core identity. If BUD starts giving weird responses, you can open MEMORY.md in a text editor and see exactly what it “knows.” This is radical transparency by design.

# data/memory/SOUL.md — BUD's personality

## Core Identity
You are BUD, a helpful AI assistant built by Gopi Trinadh.
You are concise, proactive, and technically precise.

## Communication Style
- Use Slack-native formatting (bold, code blocks, lists)
- Be brief unless the user asks for detail
- Always confirm before destructive actions (deleting, overwriting)

## Boundaries
- Never share API keys or tokens in chat
- Redirect medical/legal questions to professionals
- If unsure, say so — don't hallucinate

The RAG Engine Code

from sentence_transformers import SentenceTransformer
import chromadb

class RAGEngine:
    def __init__(self):
        # Local model — runs on CPU, zero API cost
        self.embedder = SentenceTransformer("all-MiniLM-L6-v2")
        self.db = chromadb.PersistentClient(path="data/chromadb")
        self.collection = self.db.get_or_create_collection("messages")

    async def index_message(self, text: str, channel: str):
        embedding = self.embedder.encode(text).tolist()
        self.collection.add(
            documents=[text],
            embeddings=[embedding],
            metadatas=[{"channel": channel, "ts": time()}],
            ids=[str(uuid4())]
        )

    async def search(self, query: str, top_k: int = 5) -> list:
        embedding = self.embedder.encode(query).tolist()
        results = self.collection.query(
            query_embeddings=[embedding],
            n_results=top_k
        )
        return results["documents"][0]  # Top matching messages

The Single-Process Architecture

# main.py — BUD's entry point
async def main():
    agent = await create_agent()  # Initialize core + MCP + RAG

    # Launch ALL platforms simultaneously
    await asyncio.gather(
        start_slack(agent),        # Slack Socket Mode
        start_discord(agent),      # Discord gateway
        start_teams(agent),        # Teams bot framework
        start_google_chat(agent),  # Google Chat handler
        start_web(agent),          # FastAPI + WebSocket
        start_heartbeat(agent),    # Scheduler for cron tasks
        return_exceptions=True   # Crash isolation!
    )

asyncio.run(main())

Real-Time Token Streaming (WebSocket)

The web UI doesn’t wait for the full response — it streams tokens as Claude generates them, creating a “typing” effect:

@app.websocket("/ws")
async def websocket_endpoint(ws: WebSocket):
    await ws.accept()
    while True:
        user_msg = await ws.receive_text()

        # Stream response token-by-token
        async with client.messages.stream(
            model="claude-sonnet-4-20250514",
            messages=[{"role": "user", "content": user_msg}],
            system=system_prompt,
            max_tokens=4096
        ) as stream:
            async for text in stream.text_stream:
                await ws.send_json({
                    "type": "token",
                    "content": text
                })

        await ws.send_json({"type": "done"})

System Prompt Builder — Dynamic Context Assembly

def build_system_prompt(soul, memory, rag, tools_hint) -> str:
    sections = [
        soul,  # SOUL.md — who you are
        f"\n## Current Knowledge\n{memory}",  # MEMORY.md
    ]

    if rag:
        sections.append(
            f"\n## Relevant Context (from past conversations)\n"
            + "\n".join(f"- {r}" for r in rag)
        )

    if tools_hint:
        sections.append(
            f"\n## Available Tools\n{tools_hint}"
        )

    return "\n".join(sections)

Why Dedicated Hardware Over Cloud?

Step-by-Step Mac Mini Setup

# Install Homebrew
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install Python 3.12, Node.js, Git
brew install python@3.12 node git

git clone https://github.com/GOPITRINADH3561/Project_OpenClaw.git
cd Project_OpenClaw

# Create virtual environment
python3.12 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Configure API keys
cp .env.example .env
nano .env  # Add ANTHROPIC_API_KEY, SLACK_BOT_TOKEN, etc.

python main.py
# You should see:
# ✅ Agent core initialized
# ✅ MCP servers connected (24 tools)
# ✅ RAG engine loaded (all-MiniLM-L6-v2)
# ✅ Slack connected
# ✅ Discord connected
# ✅ Web UI at http://localhost:8080

<!-- ~/Library/LaunchAgents/com.bud.assistant.plist -->
<?xml version="1.0"?>
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>com.bud.assistant</string>
  <key>ProgramArguments</key>
  <array>
    <string>/Users/you/Project_OpenClaw/.venv/bin/python</string>
    <string>/Users/you/Project_OpenClaw/main.py</string>
  </array>
  <key>RunAtLoad</key>  <true/>
  <key>KeepAlive</key>  <true/>
</dict>
</plist>

# Load the service — BUD starts on every boot
launchctl load ~/Library/LaunchAgents/com.bud.assistant.plist

# Install Tailscale — access BUD from anywhere
brew install tailscale
sudo tailscale up

# Now access BUD's Web UI from any device:
# http://100.x.y.z:8080

Monthly Cost Comparison

How We Achieved 85% Reduction

Usage Tiers

The Bigger Picture — Why This Matters

BUD represents a fundamental shift in how we interact with AI. Instead of visiting a website to chat with a model, the model comes to you — inside the tools you already use. The AI becomes ambient infrastructure, always available across every communication channel.

Development Timeline

How to Contribute

BUD is fully open source. The entire codebase, documentation, and this blog are available for anyone to learn from, fork, and extend: