Skip to content
Sparky4567Public

About

Incrementally Learning ELIZA-Style CLI LLM Bot built with Bun and TypeScript

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

ELIZA-AI: Incrementally Learning LLM Bot in Bun (CLI + Web + Telegram + WhatsApp)

A modular, incrementally learning conversational AI built with Bun and TypeScript. It combines the predictable, reflective empathy of classic ELIZA with a persistent cognitive layer, long-term memory, versioned knowledge base, and local LLM integration via Ollama (with real-time streaming). Talk to it in the terminal (bun start), in the browser (bun run web), or from your phone via Telegram and WhatsApp — every channel shares the same bot, memory, and learning pipeline, with isolated per-chat sessions.


🌟 Key Features

  • Automatic Model Discovery: Queries Ollama's API on startup, listing local models and defaulting automatically to the first available model.
  • Model Representation: Clearly identifies the active engine with (ELIZA:model_name) in the CLI prompt and diagnostics (e.g. (ELIZA:llama3.2) or (ELIZA:rules) when offline).
  • Classic ELIZA Pattern Engine: Deterministic pattern matching with wildcards (*), priority ranking, template interpolation ({0}, {1}), and single-pass pronoun reflection (I ⇄ you, my ⇄ your, am ⇄ are, mine ⇄ yours, myself ⇄ yourself).
  • Real-Time Ollama Token Streaming: Connects directly to local Ollama instances (/api/chat), streaming tokens dynamically to standard output as they generate.
  • Graceful Offline Fallback: If Ollama is offline or unavailable, seamlessly falls back to the deterministic ELIZA rule engine and reflective responses without crashing.
  • Persistent SQLite Storage: Built natively on bun:sqlite with WAL mode for high-performance storage of sessions, conversation turns, memories, knowledge, and learning events.
  • Long-Term Memory & Contradiction Resolution: Classifies memories (facts, preferences, goals, projects, instructions, corrections). When beliefs or project parameters change, previous memories are linked as superseded_by rather than silently deleted.
  • Neuromorphic Cognitive Memory (plasticity layer): Memories carry an activation level that spikes on retrieval, decays over time (forgetting curve), strengthens via Hebbian links between co-retrieved memories, and is weighted by importance/confidence/type. Retrieval is re-ranked by activation; consolidation promotes hot traces (short → long term) and pruning forgets decayed, idle traces. Enabled automatically; inspect with /neuromorphic.
  • Versioned Knowledge Base: Records general concepts, definitions, and technical knowledge with full provenance chains (version, previous_version_id, change_reason).
  • Post-Turn Incremental Learning: Automatically extracts durable facts, user preferences, and explicit corrections after every turn using a hybrid heuristic + LLM extraction pipeline.
  • Response Evaluation & Strategy Statistics: Evaluates response quality (relevance, hallucination risk, memory utilization) and tracks success metrics across strategies (ask_followup, explain_directly, eliza_rule, llm_contextual).
  • Observability & Diagnostics: Interactive inspection via /trace, /model, /stats, /memory, /knowledge, /rules, and /approve.
  • Web UI + API (--web): Browser chat with live token streaming over WebSocket, command buttons, and a context/trace side panel — plus a REST API (/api/chat, /api/stats, /api/trace, /api/model, …) with full CLI parity.
  • Telegram bridge (--telegram): Zero-dependency Bot API long-polling (src/channels/telegram.ts, ported from llama). Each Telegram chat gets an isolated session; @cmd works like /cmd; replies over 4000 chars are auto-split.
  • WhatsApp bridge (--whatsapp): Localhost HTTP bridge (:8765/chat) + Baileys socket process (whatsapp_bridge/, QR login on :8766, ported from llama). Each contact gets an isolated session.
  • Channels panel in the web UI: Side-panel card showing Telegram/WhatsApp status, the WhatsApp pairing QR inline, runtime Telegram connect (paste a token, no restart), auth reset, and outbound test-message senders (/api/channels*).
  • Adjustable dashboard font size: A side-panel slider scales all dashboard text and is persisted in the browser (localStorage).
  • Voice responses in the dashboard: Optional read-aloud of AI replies via browser TTS, plus microphone dictation with a confirm-before-send toggle (/api not required — runs entirely client-side).
  • Update & sync helpers: update.sh/update.bat (safe fetch + pull --rebase) and git.sh/git.bat (stage, commit, pull --rebase, push) with guards against detached HEAD and invalid JSON.
  • Persistent settings (model + Telegram token):" oldString="
  • Channels panel in the web UI: Side-panel card showing Telegram/WhatsApp status, the WhatsApp pairing QR inline, runtime Telegram connect (paste a token, no restart), auth reset, and outbound test-message senders (/api/channels*).
  • Persistent settings (model + Telegram token):" path="/home/myusername/github/eliza/README.md" The last-picked Ollama model and the Telegram bot token are saved in the SQLite settings table, survive restarts, and can be edited or deleted from the web UI (Model panel + Channels panel), via the API, or via /model / --telegram-token.
  • Editable system template / persona: The system prompt is now an editable template stored in the settings table; change ELIZA's persona on demand from the CLI (/system …), web API (/api/system), Telegram/WhatsApp, or MCP, and it persists across restarts on every surface.
  • Lively, creative persona presets: The default persona is now a warm, lively, creative companion (less mirroring/psychoanalyst) instead of a purely reflective analyst. Switch voices instantly with /system preset <name> (analyst, lively, creative, companion) or /system <name>, or set a fully custom template; the seeded ELIZA rules were also reworded to be more engaging and interactive.
  • Command prefix flexibility: Slash commands can be invoked with either / or @ (e.g. /help or @help) on all surfaces.
  • Continuous evolution pass: /evolve (and /learn, /auto-learn, …) runs a consolidation pass over neuromorphic memory, auto-approves matured candidate rules, and reinforces recent learning on demand.
  • Resilient LLM Layer: Clear timeout errors (no more cryptic The operation was aborted), best-effort background learning that never breaks a reply, graceful ELIZA fallback, and a Ctrl+C-safe CLI loop.
  • Smart Writing / Smart Notes (Ollama-only): /smart-writing start … opens a co-writing session — type multi-sentence / multi-line drafts and the bot continues or improves them until the story is done, then /smart-writing save persists it as a story memory + writing knowledge entry with 🔗 memory_links associations to related memories/knowledge.

📐 System Architecture

                ┌────────────────────┐  ┌────────────────────┐  ┌────────────────────┐
                │   Terminal User    │  │   Browser User     │  │ Telegram / WhatsApp│
                │   (bun start)      │  │   (bun run web)    │  │  (--telegram/--wa) │
                └─────────┬──────────┘  └─────────┬──────────┘  └─────────┬──────────┘
                           │                       ▼                       ▼
                           │              ┌────────────────────┐  ┌────────────────────┐
                           │              │  Web Server + WS   │  │ Channel Bridges    │ ◄── /api/channels* + QR
                           │              └─────────┬──────────┘  └─────────┬──────────┘
                           ▼                       ▼                       ▼
                          ┌────────────────────┐
                          │ Conversation Loop  │ ◄── Slash Commands (/trace, /stats, etc.)
                          └─────────┬──────────┘         ▲ isolated per-chat sessions
                                    │                   (telegram_<id>, whatsapp_<jid>)
                                    ▼
                         ┌────────────────────┐
                         │  Context Builder   │
                         └─────────┬──────────┘
                                   │
                ┌──────────────────┼──────────────────┐
                │                  │                  │
                ▼                  ▼                  ▼
        ┌──────────────┐   ┌──────────────┐   ┌──────────────┐
        │   Memories   │   │  Knowledge   │   │ ELIZA Rules  │
        │    Store     │   │     Base     │   │  / Matcher   │
        └──────────────┘   └──────────────┘   └──────────────┘
                │                  │                  │
                └──────────────────┼──────────────────┘
                                   ▼
                         ┌────────────────────┐
                         │     Local LLM      │ (Streaming HTTP)
                         │      Ollama        │
                         └─────────┬──────────┘
                                   │
                                   ▼
                         ┌────────────────────┐
                         │ Response Evaluator │
                         └─────────┬──────────┘
                                   │
                    ┌──────────────┼──────────────┐
                    ▼              ▼              ▼
               Bot Response     New Memory     New Knowledge
           (Stream to CLI/Web) (Consolidation)  (Versioned)

🚀 Getting Started

Quick install (Linux & macOS)

./install.sh
# non-interactive with defaults (Bun check, Ollama, deps, gemma2 model, tests):
./install.sh --yes
# offline-only install (skip Ollama — bot falls back to ELIZA rules):
./install.sh --no-ollama
# also install the WhatsApp bridge dependencies (needs Node 18+):
./install.sh --with-whatsapp

The script checks/installs Bun (≥1.0, required) and Ollama (optional), runs bun install, pulls the default model, and finishes with bun test as a smoke test. Flags: --model NAME (default gemma2, empty string skips the pull), --no-ollama, --with-whatsapp, --skip-tests, -y/--yes (non-interactive). Then jump straight to step 3 below.

Prerequisites (manual setup)

  • Bun (v1.0 or higher)
  • (Optional) Ollama running locally for LLM-powered context generation.

1. Install Dependencies (skip if you used install.sh)

bun install

2. (Optional) Start Ollama

Make sure Ollama is running and pull your preferred model:

# Pull model (e.g., gemma2, llama3.2, or qwen2.5)
ollama pull gemma2

# Start Ollama service (if not already running as a daemon)
ollama serve

3. Run the Bot

bun start
# or
bun run src/index.ts

3b. Run the Web UI (zap-style --web mode)

bun run web
# or
bun run src/index.ts --web --port 3000

Opens a browser chat UI at http://localhost:3000 with live token streaming over WebSocket, the same slash commands as the CLI (/help, /stats, /trace, /memory, …, /smart-writing …), plus a context/trace side panel. REST + WS API below. Port fallback: --port flag, else ELIZA_WEB_PORT / WEB_PORT / PORT env. Composer: Enter sends, Shift+Enter inserts a newline (multi-line stories).

3c. Connect Telegram and/or WhatsApp (ported from llama)

# Telegram: set a BotFather token, then run (CLI or --web — bridges start in both modes)
TELEGRAM_TOKEN=<token> bun start
# or: bun run src/index.ts --web --telegram --telegram-token <token>

# WhatsApp: install the Baileys bridge deps once, then run
bun run whatsapp:install
bun run src/index.ts --web --whatsapp
# scan the QR printed in the terminal — or right in the web UI Channels panel

Notes:

  • Telegram auto-starts whenever a token is present (--telegram-token flag → TELEGRAM_TOKEN / TELEGRAM_BOT_TOKEN env → telegram.token config); --no-telegram forces it off. WhatsApp starts on --whatsapp or WHATSAPP_ENABLED=true.
  • Remote chats reuse the full CLI stack (ELIZA rules, memory/knowledge retrieval, Ollama, learning) with isolated per-chat sessions (telegram_<chatId>, whatsapp_<jid>) — the CLI session is untouched. /clear in a remote chat clears only that chat.
  • Llama-style @help works like /help in remote chats. Voice notes get a polite text-mode notice (ELIZA has no STT/TTS pipeline).

4. Run the Test Suite

bun test

💡 Example Conversation Walkthrough

=======================================================
       ELIZA-AI: Incrementally Learning CLI Bot        
=======================================================
Type your message or /help for commands, /quit to exit.

You: I am building a Bun CLI chatbot.
Bot: What kind of chatbot are you building?

You: A CLI bot inspired by ELIZA using SQLite.
Bot: That sounds like a great architecture. SQLite provides fast, persistent structured storage.

You: /stats
=== Bot Statistics ===
Sessions:           1
Messages:           4
Active Memories:    2
Superseded Memories:0
Active Knowledge:   0
Corrections:        0
Active ELIZA Rules: 21
Candidate Rules:    0

You: Actually, I changed it. I'm using PostgreSQL now.
Bot: Got it. I've updated my memory: the project database has changed from SQLite to PostgreSQL.

You: /trace
=== Response Trace ===
Input:             Actually, I changed it. I'm using PostgreSQL now.
Strategy:          llm_contextual
Model:             gemma2
Matched Rule:      None

Retrieved Memories (2):
  - [project] User is building a Bun CLI chatbot. (Score: 2.10, Conf: 0.95)
  - [correction] User updated: Actually, I changed it. I'm using PostgreSQL now. (Score: 3.45, Conf: 0.98)

Retrieved Knowledge (0):
  (none)

Evaluation:
  Score:           0.90
  Used Memory:     true
  Hallucination:   false
  Notes:           Response accurately acknowledged database update.

You: /memory
=== Recent Memories ===
[mem_17236501] (correction) (Conf: 0.98)
  User updated: Actually, I changed it. I'm using PostgreSQL now.
[mem_17236500] (project) [SUPERSEDED by mem_17236501] (Conf: 0.90)
  User is building a Bun CLI chatbot using SQLite.

✍️ Smart Writing (Ollama-only co-writing + smart notes)

Requires a local Ollama model (ollama serve + a pulled model, OLLAMA_ENABLED=true). Without it, /smart-writing start|continue|improve explain that Ollama is needed; drafting commands (show, status, list, save) keep working offline.

You: /smart-writing start Mara kept the lighthouse burning through the storm.
Bot: ✍️ Smart-writing session started… Draft so far (8 words)…

You: She heard a knock at the iron door. The sea was angry and black.
Bot: <continuation streamed token-by-token, then appended to the draft>

You: /smart-writing improve make it more atmospheric
Bot: <polished rewrite of the full draft>

You: /smart-writing save The Lighthouse
Bot: 💾 Saved story "The Lighthouse" as [mem_…] (…words).
     Knowledge: [kn_…] "Story: The Lighthouse" (v1)
     🔗 Formed 2 new association(s):
       - (related) → [memory] [fact] Mara is the lighthouse keeper…
       - (related) → [knowledge] 📚 Storm…

You: /smart-writing list
     📚 Saved stories (1): [mem_…] Story "The Lighthouse"…

You: /smart-writing done

Notes:

  • While a session is ACTIVE, plain chat text is story input (appended, then continued automatically). Use /smart-writing add <text> to append silently.
  • Multi-line works: paste paragraphs in the CLI; in the web composer use Shift+Enter for a newline (Enter sends, up to 4000 chars per message, 8000 via POST /api/writing).
  • save stores a story memory + a versioned writing knowledge entry and links them to related memories/knowledge in the memory_links table — inspect with /smart-writing links <story_id>.
  • Aliases: /smart-write, /write, /story. Full reference: /smart-writing help. Web parity: same commands over WS/REST plus GET|POST /api/writing.

💬 Slash Commands

Command Arguments Description
/help — Displays the interactive help menu. Aliases: /commands, /get-commands (also @help, @commands).
/mcp status | list | tools [server] | call <server__tool> [json] | reconnect [server] | enable <server> | disable <server> Inspect and manage MCP (Model Context Protocol) servers/tools. Aliases: /mcp-status, /mcp-list, /mcp-tools, /mcp-call, /mcp-reconnect, /mcp-enable, /mcp-disable, /mcp-servers (also @mcp).
/model [name] Shows available local models or switches the active model on the fly (e.g. /model llama3.2). The pick is saved in the DB and restored on restart.
/trace — Displays detailed diagnostics on how the most recent response was constructed (matched patterns, retrieved memories, knowledge items, strategy, model, evaluation score, and notes).
/stats — Shows database metrics (sessions, messages, active/superseded memories, knowledge, candidate rules, strategy scores).
/memory [query] Lists recent memories or searches active memories using TF-IDF token scoring.
/neuromorphic [status|toggle|on|off|consolidate|prune|spikes] Inspects and controls the neuromorphic cognitive memory layer (plasticity re-ranking, consolidation, pruning). Alias: /nc-mem.
/knowledge [query] Lists knowledge base entries or searches concepts and definitions.
/remember <text> Explicitly adds a durable fact or preference to persistent memory.
/forget <id> Deactivates/forgets a specific memory by its ID.
/teach <title: content> Explicitly adds a concept to the versioned knowledge base.
/correct <text> Explicitly submits a correction; links and supersedes older conflicting memories.
/rules [status] Lists ELIZA rules (approved, candidate, rejected, all).
/approve <id> Approves a learned candidate rule and activates it in the ELIZA engine.
/reload — Reloads rule definitions from data/rules.json and database.
/system [text | reset | preset <name>] View, replace, or reset the editable system template / persona. Apply a named preset (analyst, lively, creative, companion) via /system preset <name> or /system <name> (aliases: /persona, /template, /prompt, /system-prompt, /system-template; also @system).
/evolve — Run a continuous-learning evolution pass: consolidate/prune neuromorphic memory and auto-approve matured candidate rules (aliases: /learn, /auto-learn, /continuous-learning, /evolve-memory, /learn-from-history; also @evolve).
/smart-writing start · add · continue · improve · show · save · list · links · done Ollama-only co-writing session: iterative continuation/improvement + persistent save with memory linking (aliases: /smart-write, /write, /story).
/clear — Clears current conversation history and starts a new session.
/quit, /exit — Exits the conversation cleanly.

⚙️ Configuration & Environment Variables

Variable Default Description
BOT_DB_PATH data/bot.db Path to the SQLite database file (:memory: supported for testing).
BOT_RULES_PATH data/rules.json Path to the ELIZA pattern rules JSON file.
OLLAMA_HOST http://localhost:11434 Ollama API endpoint.
OLLAMA_MODEL (auto-detect) Ollama model for generation/extraction; empty means use the saved last-picked model, else the first available local model.
OLLAMA_ENABLED true Set to false to disable LLM and run strictly in deterministic ELIZA mode.
OLLAMA_TIMEOUT_MS 60000 Timeout in milliseconds for Ollama requests.
OLLAMA_STREAM true Set to false to disable token streaming (return full replies at once).
BOT_AUTO_EXTRACTION true Enables post-turn extraction of memories and corrections.
BOT_AUTO_EVALUATION true Enables post-turn response evaluation and strategy scoring.
BOT_AUTO_RULES true Enables candidate rule proposals from conversational patterns.
ELIZA_WEB_PORT 3000 Port for --web mode (WEB_PORT / PORT also honored, --port wins).
TELEGRAM_TOKEN (unset) Telegram bot token (TELEGRAM_BOT_TOKEN also honored, --telegram-token wins). Presence auto-starts the bridge. A token entered via CLI flag or web UI is saved in the DB and reused on restart (editable/deletable in the web UI).
TELEGRAM_ENABLED true Set to false to keep the Telegram bridge off even with a token (--no-telegram also works).
WHATSAPP_ENABLED false Set to true (or pass --whatsapp) to start the WhatsApp bridge.
WHATSAPP_PHONE (unset) Default phone number passed to the Baileys bridge process (--whatsapp-phone wins).
WHATSAPP_PORT 8765 Localhost HTTP bridge port (/chat, --whatsapp-port wins).
WHATSAPP_STATUS_PORT 8766 Baileys status/QR port (/status, /send).

🌐 Web UI & API (--web)

Same bot, browser-hosted — modeled on zap's Bun.serve + WebSocket server:

Piece Endpoint Notes
UI GET / Chat log, composer, command buttons, context/trace panel
Health GET /api/health Ollama reachability, active (ELIZA:model), available models
Chat POST /api/chat {"message"} Full turn incl. slash commands → {reply, isCommand, trace}
Command POST /api/command {"command":"/stats"} Explicit slash-command dispatch → {output}
Stats / Trace GET /api/stats, GET /api/trace Same data as CLI /stats, /trace
Model GET /api/model, POST /api/model {"name"}, DELETE /api/model Inspect / switch the active Ollama model (POST persists the pick as savedModel); DELETE forgets the saved pick (falls back to auto-detect / rules)
System template / Persona GET /api/system, POST /api/system {"prompt"|"template"|"persona"}, DELETE /api/system View, replace, or reset the editable system template / persona (persisted in the settings table); also available as /system in the CLI and as get_system_prompt / set_system_prompt over MCP
Memory / Knowledge GET /api/memory?q=, GET /api/knowledge?q= Same output as CLI /memory, /knowledge
Writing GET /api/writing?action=status|show|list|links, POST /api/writing {"action","text"} Smart-writing session state, saved-story library, and association graph
Channels GET /api/channels Telegram/WhatsApp summary (configured/persisted/preview/running/username, ports — only a masked ••••abcd preview, never the full token)
WhatsApp status GET /api/channels/whatsapp/status Baileys bridge proxy: connection, linked phone, last chat, QR image (503 bridge down, 502 node down)
WhatsApp send/reset POST /api/channels/whatsapp/send {"to","text"}, POST /api/channels/whatsapp/reset Send via bridge /send; clear stale auth keys to re-pair
Telegram send/start POST /api/channels/telegram/send {"chat_id","text"}, POST /api/channels/telegram/start {"token"} Send via polling runner; save/edit a bot token and connect at runtime (empty token reuses the saved one; persisted only after Telegram accepts it). DELETE /api/channels/telegram/start disconnects but keeps the token; GET|DELETE /api/channels/telegram/token inspects (masked) / forgets it

WS protocol (/ws, JSON): client→server text {text} · stop; server→client ready · llm-token · llm-done {text, isCommand, trace} · turn-end · interrupted · error. One turn per connection; a new text cancels the previous turn (best-effort — the LLM HTTP call itself has no abort signal, so stale tokens are dropped and its result discarded). Typing /help etc. in the composer works like the CLI.

📂 Project Structure

index.ts                   # Root re-export + Bun entrypoint (delegates to src/index.ts)
src/
├── index.ts                # Application entrypoint, createBot() factory, --web/--port/--telegram/--whatsapp parsing, startChannels()
├── config.ts               # Configuration settings and environment defaults (incl. telegram/whatsapp)
├── channels/
│   ├── telegram.ts         # Telegram Bot API long-polling runner (zero-dep, llama port)
│   └── whatsapp.ts         # WhatsApp localhost HTTP bridge + Baileys spawner (llama port)
├── web/
│   └── server.ts           # Bun.serve web UI + REST + /ws streaming (zap-style) + /api/channels*
whatsapp_bridge/           # Baileys socket process: QR login (:8766), forwards to :8765/chat (llama port)
│   ├── index.js            # (Node) socket, QR render, /status + /send
│   └── auth/               # Phone-linked credentials (gitignored — never commit)
├── db/
│   ├── database.ts         # High-performance bun:sqlite database wrapper
│   └── schema.ts           # Database tables, relations, and indexes
├── eliza/
│   ├── reflection.ts       # Pronoun reflection engine
│   ├── patterns.ts         # Rule registry & candidate rule manager
│   └── matcher.ts          # Pattern matcher, wildcard capture & interpolation
├── memory/
│   ├── models.ts           # Memory types, statuses & interfaces
│   ├── store.ts            # Memory CRUD, deduplication & superseding
│   └── retrieval.ts        # Memory retriever with TF-IDF and relevance ranking
├── knowledge/
│   ├── models.ts           # Knowledge entry models & categories
│   ├── store.ts            # Versioned knowledge store & provenance tracking
│   ├── retrieval.ts        # Knowledge relevance search
│   └── learning.ts         # Heuristic and LLM-powered extraction pipeline
├── llm/
│   ├── ollama.ts           # Streaming HTTP client for Ollama
│   └── prompts.ts          # Persona, extraction, evaluation, rule & smart-writing prompts
├── writing/
│   └── smart-writing.ts    # Ollama-gated co-writing sessions + story save with memory_links
├── bot/
│   ├── context.ts          # Context builder assembling memories, knowledge & history
│   ├── evaluator.ts        # Response evaluator & strategy performance tracker
│   ├── response.ts         # Response engine orchestrating ELIZA rules vs. LLM streaming
│   └── conversation.ts     # CLI REPL loop & slash command dispatcher
tests/
├── eliza.test.ts           # Pattern matching, reflection & candidate rules tests
├── memory.test.ts          # Memory storage, deduplication & contradiction tests
├── knowledge.test.ts       # Knowledge versioning and provenance tests
├── learning.test.ts        # Extraction pipeline tests
├── context.test.ts         # Context assembly tests
├── conversation.test.ts    # End-to-end bot interaction and acceptance tests
├── integration.test.ts     # Edge cases, life-cycle, and statistics tests
├── markdown.test.ts        # XSS-safe markdown + emoji renderer tests
├── web.test.ts             # Web server: flags, REST parity, WS streaming
└── writing.test.ts         # Smart-writing: Ollama gating, draft/save/links, web parity
data/
├── rules.json              # 21 seeded ELIZA pattern rules (priority-ranked)
└── bot.db*                 # Local SQLite DB (gitignored — created on first run)
public/
├── index.html              # Web chat UI shell
├── app.ts                  # WS streaming client, command buttons, trace panel
└── markdown.ts             # Zero-dep XSS-safe markdown + :emoji: renderer

🧪 Testing

Run all 60 automated tests (11 files):

bun test

Expected output: 60 pass, 0 fail (244 expect() calls).


🖥️ CLI Flags

bun start                          # CLI REPL (default)
bun run web                        # Web UI on default port (3000)
bun run telegram                   # CLI + Telegram bridge (needs TELEGRAM_TOKEN)
bun run whatsapp                   # CLI + WhatsApp bridge (needs whatsapp:install + pairing)
bun run src/index.ts --web --port 3000        # Explicit port
bun run src/index.ts --web --port=3000        # Alternate form
bun run src/index.ts --web --telegram --whatsapp --whatsapp-phone 12345

Port resolution order: --port flag → ELIZA_WEB_PORT → WEB_PORT → PORT → 3000. Database/rules paths can be overridden per-run, e.g. BOT_DB_PATH=:memory: bun test for an isolated in-memory DB.


📝 Notes

  • data/bot.db* (SQLite + WAL/SHM) is local runtime state and is gitignored — it is created on first run. Delete it to reset sessions, memories, knowledge, and saved settings (last-picked model, Telegram token).
  • data/rules.json ships 21 seeded ELIZA rules; learned candidates stay in the DB until approved via /approve <id>.
  • Offline-first: with Ollama down (or OLLAMA_ENABLED=false) the bot keeps working via the deterministic rule engine as (ELIZA:rules).


🔌 MCP (Model Context Protocol) support

eliza can both act as an MCP server (expose itself to other MCP-capable assistants) and act as an MCP client (connect to external MCP servers and use their tools).

MCP server mode

Run bun run mcp (or bun run src/index.ts --mcp) to expose eliza as an MCP server (stdio + HTTP/SSE) for any MCP-capable assistant.

  • HTTP Streamable endpoint: http://0.0.0.0:${MCP_PORT:-8790}/mcp
  • Legacy SSE endpoint: http://0.0.0.0:${MCP_PORT:-8790}/sse
  • Health: http://0.0.0.0:${MCP_PORT:-8790}/health
  • Set MCP_PORT to change the port.
  • Set MCP_TOKEN or settings.mcp_server_token to require Authorization: Bearer <token>.
  • Use --mcp-stdio-only for pure stdio mode (local desktop assistants).

Using from a remote / web assistant (e.g. ChatGPT web)

The server above binds to your machine, so a cloud-based assistant can only reach it if you expose it publicly and secure it with a token:

  1. Start eliza in MCP (HTTP) mode:
    MCP_PORT=8790 MCP_TOKEN=some-secret bun run src/index.ts --mcp
  2. Expose it to the internet (ChatGPT runs in the cloud, so localhost won't work):
    cloudflared tunnel --url http://localhost:8790   # or: ngrok http 8790
    You'll get a public https://... URL.
  3. Add that URL as an MCP connector in your assistant, pointing at https://<tunnel>/mcp, and use the same MCP_TOKEN as the bearer token.
  4. The assistant will discover the tools (tools/list) and call them (tools/call) — e.g. eliza_chat to talk to the assistant.

Caveats:

  • ChatGPT web MCP/connector support depends on your plan/version. If it isn't available, use a desktop MCP client instead.
  • Local desktop clients (Claude Desktop, Cursor, Windsurf, …) don't need a tunnel — use pure stdio mode:
    {
      "mcpServers": {
        "eliza": {
          "command": "bun",
          "args": ["run", "/path/to/eliza/src/index.ts", "--mcp-stdio-only"]
        }
      }
    }
  • In MCP mode only the curated tool set is exposed (ping, eliza_chat, list_sessions, get_memories, remember, web_search, web_fetch). The full assistant is reachable through eliza_chat (which runs the normal LLM flow with slash commands, memory, sessions, web search, etc.). Other surfaces (Telegram/WhatsApp/voice/web UI) are not started in MCP mode.

MCP client

eliza ships a zero-dependency MCP stdio client (src/mcp.ts) compatible with Claude-desktop style mcp_servers.json configs. On first run, mcp_servers.json is auto-created with the built-in local (offline ping / read_file / list_directory) and web (live web_search / web_fetch) servers.

Commands:

  • /mcp-status (or /mcp) — show enabled state, configured servers, and connection state.
  • /mcp-list (or /mcp-servers) — list configured MCP servers.
  • /mcp-tools [server] — list tools (addressed as <server>__<tool>).
  • /mcp-call <server__tool> [json_args] — call a tool directly.
  • /mcp-reconnect [server] — drop cached connections.
  • /mcp-enable <server> / /mcp-disable <server> — toggle a server.

Settings (persisted in the DB / env): mcp_enabled (default on), mcp_config_path, mcp_timeout_ms (default 15000).

📄 License

MIT — see LICENSE.

About

Incrementally Learning ELIZA-Style CLI LLM Bot built with Bun and TypeScript

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages