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.
- 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:sqlitewith 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_byrather 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;@cmdworks 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 (
/apinot required — runs entirely client-side). - Update & sync helpers:
update.sh/update.bat(safe fetch + pull --rebase) andgit.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
settingstable, 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
settingstable; 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./helpor@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 savepersists it as astorymemory +writingknowledge entry with 🔗memory_linksassociations to related memories/knowledge.
┌────────────────────┐ ┌────────────────────┐ ┌────────────────────┐
│ 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)
./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-whatsappThe 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.
bun installMake 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 servebun start
# or
bun run src/index.tsbun run web
# or
bun run src/index.ts --web --port 3000Opens 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).
# 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 panelNotes:
- Telegram auto-starts whenever a token is present (
--telegram-tokenflag →TELEGRAM_TOKEN/TELEGRAM_BOT_TOKENenv →telegram.tokenconfig);--no-telegramforces it off. WhatsApp starts on--whatsapporWHATSAPP_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./clearin a remote chat clears only that chat. - Llama-style
@helpworks like/helpin remote chats. Voice notes get a polite text-mode notice (ELIZA has no STT/TTS pipeline).
bun test=======================================================
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.
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+Enterfor a newline (Entersends, up to 4000 chars per message, 8000 viaPOST /api/writing). savestores astorymemory + a versionedwritingknowledge entry and links them to related memories/knowledge in thememory_linkstable — inspect with/smart-writing links <story_id>.- Aliases:
/smart-write,/write,/story. Full reference:/smart-writing help. Web parity: same commands over WS/REST plusGET|POST /api/writing.
| 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. |
| 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). |
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.
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
Run all 60 automated tests (11 files):
bun testExpected output: 60 pass, 0 fail (244 expect() calls).
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 12345Port 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.
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.jsonships 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).
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).
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_PORTto change the port. - Set
MCP_TOKENorsettings.mcp_server_tokento requireAuthorization: Bearer <token>. - Use
--mcp-stdio-onlyfor pure stdio mode (local desktop assistants).
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:
- Start eliza in MCP (HTTP) mode:
MCP_PORT=8790 MCP_TOKEN=some-secret bun run src/index.ts --mcp
- Expose it to the internet (ChatGPT runs in the cloud, so
localhostwon't work):You'll get a publiccloudflared tunnel --url http://localhost:8790 # or: ngrok http 8790https://...URL. - Add that URL as an MCP connector in your assistant, pointing at
https://<tunnel>/mcp, and use the sameMCP_TOKENas the bearer token. - The assistant will discover the tools (
tools/list) and call them (tools/call) — e.g.eliza_chatto 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 througheliza_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.
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).
MIT — see LICENSE.