BUD

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:

<span class="hl-kw">async def</span> <span class="hl-fn">process_message</span>(self, user_msg: <span class="hl-type">str</span>, channel: <span class="hl-type">str</span>, user_id: <span class="hl-type">str</span>) -> <span class="hl-type">str</span>:
    <span class="hl-cm"># Step 1: Classify intent — avoid expensive API calls for simple messages</span>
    intent = <span class="hl-fn">classify_intent</span>(user_msg)

    <span class="hl-kw">if</span> intent == <span class="hl-str">"greeting"</span>:
        <span class="hl-kw">return</span> <span class="hl-fn">random_greeting</span>(user_id)  <span class="hl-cm"># $0 — no API call needed</span>

    <span class="hl-cm"># Step 2: Assemble context from all memory layers</span>
    memory_context = <span class="hl-kw">await</span> self.memory.<span class="hl-fn">get_context</span>(user_id, channel)
    rag_results = <span class="hl-kw">await</span> self.rag.<span class="hl-fn">search</span>(user_msg, top_k=<span class="hl-num">5</span>)
    tools = <span class="hl-kw">await</span> self.mcp_manager.<span class="hl-fn">get_all_tools</span>()

    <span class="hl-cm"># Step 3: Build the system prompt</span>
    system = <span class="hl-fn">build_system_prompt</span>(
        soul=self.memory.soul,
        memory=memory_context,
        rag=rag_results,
        tools_hint=<span class="hl-fn">summarize_tools</span>(tools)
    )

    <span class="hl-cm"># Step 4: Call Claude with full context</span>
    messages = [{<span class="hl-str">"role"</span>: <span class="hl-str">"user"</span>, <span class="hl-str">"content"</span>: user_msg}]

    <span class="hl-cm"># Step 5: The Tool Loop — up to MAX_TOOL_ROUNDS iterations</span>
    <span class="hl-kw">for</span> round <span class="hl-kw">in</span> <span class="hl-fn">range</span>(<span class="hl-num">5</span>):  <span class="hl-cm"># Safety cap: max 5 rounds</span>
        response = <span class="hl-kw">await</span> self.<span class="hl-fn">call_claude</span>(
            system=system,
            messages=messages,
            tools=tools,
            timeout=<span class="hl-num">30.0</span>  <span class="hl-cm"># Triple-timeout protection</span>
        )

        <span class="hl-cm"># If Claude returns text → we're done!</span>
        <span class="hl-kw">if</span> response.stop_reason == <span class="hl-str">"end_turn"</span>:
            final_text = response.content[<span class="hl-num">0</span>].text
            <span class="hl-kw">break</span>

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

    <span class="hl-cm"># Step 6: Remember this interaction</span>
    <span class="hl-kw">await</span> self.memory.<span class="hl-fn">update</span>(user_id, user_msg, final_text)
    <span class="hl-kw">await</span> self.rag.<span class="hl-fn">index_message</span>(user_msg, channel)

    <span class="hl-kw">return</span> 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:

<span class="hl-kw">def</span> <span class="hl-fn">classify_intent</span>(text: <span class="hl-type">str</span>) -> <span class="hl-type">str</span>:
    lower = text.<span class="hl-fn">lower</span>().<span class="hl-fn">strip</span>()

    <span class="hl-cm"># Greetings — no API needed</span>
    greetings = {<span class="hl-str">"hi"</span>, <span class="hl-str">"hello"</span>, <span class="hl-str">"hey"</span>, <span class="hl-str">"morning"</span>, <span class="hl-str">"sup"</span>, <span class="hl-str">"yo"</span>}
    <span class="hl-kw">if</span> lower <span class="hl-kw">in</span> greetings:
        <span class="hl-kw">return</span> <span class="hl-str">"greeting"</span>

    <span class="hl-cm"># Tool-required tasks — needs Claude + MCP</span>
    tool_markers = [<span class="hl-str">"create issue"</span>, <span class="hl-str">"github"</span>, <span class="hl-str">"notion"</span>, <span class="hl-str">"schedule"</span>, <span class="hl-str">"remind"</span>]
    <span class="hl-kw">if</span> <span class="hl-fn">any</span>(m <span class="hl-kw">in</span> lower <span class="hl-kw">for</span> m <span class="hl-kw">in</span> tool_markers):
        <span class="hl-kw">return</span> <span class="hl-str">"tool_task"</span>

    <span class="hl-cm"># Complex questions — needs Claude</span>
    <span class="hl-kw">if</span> <span class="hl-fn">len</span>(text.<span class="hl-fn">split</span>()) > <span class="hl-num">5</span> <span class="hl-kw">or</span> <span class="hl-str">"?"</span> <span class="hl-kw">in</span> text:
        <span class="hl-kw">return</span> <span class="hl-str">"complex"</span>

    <span class="hl-kw">return</span> <span class="hl-str">"simple"</span>  <span class="hl-cm"># Use Haiku (cheaper model)</span>

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

<span class="hl-cm"># BUD starts each MCP server as a subprocess</span>
<span class="hl-kw">async def</span> <span class="hl-fn">connect_mcp_server</span>(self, server_path: <span class="hl-type">str</span>):
    process = <span class="hl-kw">await</span> asyncio.<span class="hl-fn">create_subprocess_exec</span>(
        <span class="hl-str">"python"</span>, server_path,
        stdin=asyncio.subprocess.PIPE,
        stdout=asyncio.subprocess.PIPE
    )

    <span class="hl-cm"># Step 1: Ask the server what tools it has</span>
    request = {<span class="hl-str">"jsonrpc"</span>: <span class="hl-str">"2.0"</span>, <span class="hl-str">"method"</span>: <span class="hl-str">"tools/list"</span>, <span class="hl-str">"id"</span>: <span class="hl-num">1</span>}
    tools = <span class="hl-kw">await</span> self.<span class="hl-fn">send_rpc</span>(process, request)

    <span class="hl-cm"># Step 2: Register all discovered tools</span>
    <span class="hl-kw">for</span> tool <span class="hl-kw">in</span> tools:
        self.registry[tool[<span class="hl-str">"name"</span>]] = {
            <span class="hl-str">"process"</span>: process,
            <span class="hl-str">"schema"</span>: tool[<span class="hl-str">"inputSchema"</span>]
        }
    <span class="hl-cm"># Now Claude can see and use these tools automatically!</span>

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.

<span class="hl-cm"># data/memory/SOUL.md — BUD's personality</span>

<span class="hl-str">## Core Identity</span>
You are BUD, a helpful AI assistant built by Gopi Trinadh.
You are concise, proactive, and technically precise.

<span class="hl-str">## Communication Style</span>
- Use Slack-native formatting (bold, code blocks, lists)
- Be brief unless the user asks for detail
- Always confirm before destructive actions (deleting, overwriting)

<span class="hl-str">## Boundaries</span>
- 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

<span class="hl-kw">from</span> sentence_transformers <span class="hl-kw">import</span> SentenceTransformer
<span class="hl-kw">import</span> chromadb

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

    <span class="hl-kw">async def</span> <span class="hl-fn">index_message</span>(self, text: <span class="hl-type">str</span>, channel: <span class="hl-type">str</span>):
        embedding = self.embedder.<span class="hl-fn">encode</span>(text).<span class="hl-fn">tolist</span>()
        self.collection.<span class="hl-fn">add</span>(
            documents=[text],
            embeddings=[embedding],
            metadatas=[{<span class="hl-str">"channel"</span>: channel, <span class="hl-str">"ts"</span>: <span class="hl-fn">time</span>()}],
            ids=[<span class="hl-fn">str</span>(<span class="hl-fn">uuid4</span>())]
        )

    <span class="hl-kw">async def</span> <span class="hl-fn">search</span>(self, query: <span class="hl-type">str</span>, top_k: <span class="hl-type">int</span> = <span class="hl-num">5</span>) -> <span class="hl-type">list</span>:
        embedding = self.embedder.<span class="hl-fn">encode</span>(query).<span class="hl-fn">tolist</span>()
        results = self.collection.<span class="hl-fn">query</span>(
            query_embeddings=[embedding],
            n_results=top_k
        )
        <span class="hl-kw">return</span> results[<span class="hl-str">"documents"</span>][<span class="hl-num">0</span>]  <span class="hl-cm"># Top matching messages</span>

The Single-Process Architecture

<span class="hl-cm"># main.py — BUD's entry point</span>
<span class="hl-kw">async def</span> <span class="hl-fn">main</span>():
    agent = <span class="hl-kw">await</span> <span class="hl-fn">create_agent</span>()  <span class="hl-cm"># Initialize core + MCP + RAG</span>

    <span class="hl-cm"># Launch ALL platforms simultaneously</span>
    <span class="hl-kw">await</span> asyncio.<span class="hl-fn">gather</span>(
        <span class="hl-fn">start_slack</span>(agent),        <span class="hl-cm"># Slack Socket Mode</span>
        <span class="hl-fn">start_discord</span>(agent),      <span class="hl-cm"># Discord gateway</span>
        <span class="hl-fn">start_teams</span>(agent),        <span class="hl-cm"># Teams bot framework</span>
        <span class="hl-fn">start_google_chat</span>(agent),  <span class="hl-cm"># Google Chat handler</span>
        <span class="hl-fn">start_web</span>(agent),          <span class="hl-cm"># FastAPI + WebSocket</span>
        <span class="hl-fn">start_heartbeat</span>(agent),    <span class="hl-cm"># Scheduler for cron tasks</span>
        return_exceptions=<span class="hl-kw">True</span>   <span class="hl-cm"># Crash isolation!</span>
    )

asyncio.<span class="hl-fn">run</span>(<span class="hl-fn">main</span>())

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:

<span class="hl-dec">@app.websocket</span>(<span class="hl-str">"/ws"</span>)
<span class="hl-kw">async def</span> <span class="hl-fn">websocket_endpoint</span>(ws: WebSocket):
    <span class="hl-kw">await</span> ws.<span class="hl-fn">accept</span>()
    <span class="hl-kw">while</span> <span class="hl-kw">True</span>:
        user_msg = <span class="hl-kw">await</span> ws.<span class="hl-fn">receive_text</span>()

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

        <span class="hl-kw">await</span> ws.<span class="hl-fn">send_json</span>({<span class="hl-str">"type"</span>: <span class="hl-str">"done"</span>})

System Prompt Builder — Dynamic Context Assembly

<span class="hl-kw">def</span> <span class="hl-fn">build_system_prompt</span>(soul, memory, rag, tools_hint) -> <span class="hl-type">str</span>:
    sections = [
        soul,  <span class="hl-cm"># SOUL.md — who you are</span>
        <span class="hl-str">f"\n## Current Knowledge\n{memory}"</span>,  <span class="hl-cm"># MEMORY.md</span>
    ]

    <span class="hl-kw">if</span> rag:
        sections.<span class="hl-fn">append</span>(
            <span class="hl-str">f"\n## Relevant Context (from past conversations)\n"</span>
            + <span class="hl-str">"\n"</span>.<span class="hl-fn">join</span>(<span class="hl-str">f"- {r}"</span> <span class="hl-kw">for</span> r <span class="hl-kw">in</span> rag)
        )

    <span class="hl-kw">if</span> tools_hint:
        sections.<span class="hl-fn">append</span>(
            <span class="hl-str">f"\n## Available Tools\n{tools_hint}"</span>
        )

    <span class="hl-kw">return</span> <span class="hl-str">"\n"</span>.<span class="hl-fn">join</span>(sections)

Why Dedicated Hardware Over Cloud?

Step-by-Step Mac Mini Setup

<span class="hl-cm"># Install Homebrew</span>
/bin/bash -c <span class="hl-str">"$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"</span>

<span class="hl-cm"># Install Python 3.12, Node.js, Git</span>
brew install python@<span class="hl-num">3.12</span> node git

git clone https://github.com/GOPITRINADH3561/Project_OpenClaw.git
<span class="hl-kw">cd</span> Project_OpenClaw

<span class="hl-cm"># Create virtual environment</span>
python3.12 -m venv .venv
<span class="hl-kw">source</span> .venv/bin/activate

<span class="hl-cm"># Install dependencies</span>
pip install -r requirements.txt

<span class="hl-cm"># Configure API keys</span>
cp .env.example .env
nano .env  <span class="hl-cm"># Add ANTHROPIC_API_KEY, SLACK_BOT_TOKEN, etc.</span>

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

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

<span class="hl-cm"># Load the service — BUD starts on every boot</span>
launchctl load ~/Library/LaunchAgents/com.bud.assistant.plist

<span class="hl-cm"># Install Tailscale — access BUD from anywhere</span>
brew install tailscale
sudo tailscale up

<span class="hl-cm"># Now access BUD's Web UI from any device:</span>
<span class="hl-cm"># http://100.x.y.z:8080</span>

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: