A personal memory agent that captures ideas, remembers things, and connects knowledge across time.

Limbo is a second brain with a conversational interface. It stores atomic notes in a local vault, searches them semantically, and maintains Maps of Content (MOCs) to keep knowledge navigable. Runs in a Docker container, accessible via Telegram or the ZeroClaw gateway.

Install

Limbo is designed to run on a VPS (always-on, accessible from anywhere). A $5/month Ubuntu server is all you need.

1. Provision a server

Any Ubuntu/Debian VPS with 1 GB+ RAM.

2. Run the installer

curl -fsSL https://raw.githubusercontent.com/TomasWard1/limbo/main/scripts/install.sh | bash

This installs Docker, Node.js, and the Limbo CLI.

3. Start Limbo

limbo start

The setup wizard walks you through:

Choose a language (English / Español)
Select a provider (Anthropic, OpenAI, OpenRouter)
Authenticate (API key or Claude/ChatGPT subscription)
Pick a model
Connect Telegram (optional but recommended)
Enable voice messages and web search (optional)
Review and confirm

Once complete, Limbo restarts and is ready to use.

4. Update

limbo update

Pulls the latest image and restarts. Vault data is persisted and not affected.

Local Install (macOS/Linux)

If you prefer running locally instead of a VPS:

npx limbo-ai start

Requires Docker Desktop and Node.js 18+. Binds to 127.0.0.1:18789.

Commands

limbo start                  # Install and start (enters wizard on first run)
limbo stop                   # Stop the container
limbo update                 # Pull latest image and restart
limbo status                 # Show container status
limbo logs                   # Tail container logs
limbo start --reconfigure    # Re-run the setup wizard
limbo config voice --enable --api-key gsk_xxx   # Enable voice transcription
limbo config web-search --enable --api-key BSA_xxx  # Enable web search

Connecting

Telegram (recommended)

The setup wizard walks you through creating a Telegram bot and pairing it. Message your bot and Limbo responds — full agent with personality, memory logic, and vault tools.

ZeroClaw gateway

Any ZeroClaw-compatible client can connect via WebSocket:

ws://localhost:18789

MCP (for other AI agents)

Add Limbo as an MCP server to give another agent direct vault access:

{
  "mcpServers": {
    "limbo": {
      "url": "ws://localhost:18789"
    }
  }
}

This exposes 4 vault tools (vault_search, vault_read, vault_write_note, vault_update_map). The connecting agent operates on the vault directly — Limbo's LLM is not involved.

Optional Features

Enable during the setup wizard or anytime via CLI.

Voice Messages

Transcribe Telegram voice notes using Groq Whisper.

limbo config voice --enable --api-key gsk_xxx
limbo config voice --disable

Web Search

Real-time web search via Brave Search API.

limbo config web-search --enable --api-key BSAxxx
limbo config web-search --disable

Hardware Requirements

Tier	RAM	vCPU	Disk
Minimum	512 MB	1	1 GB
Recommended	1 GB	1	5 GB
With other services	2 GB	1	10 GB

Limbo uses ~35 MB at rest, peaks ~70 MB during cold starts. CPU usage is negligible.

Architecture

┌─────────────────────────────────────────┐
│              Docker Container           │
│                                         │
│  ┌─────────────┐    ┌────────────────┐  │
│  │  ZeroClaw   │◄──►│  LLM (Claude   │  │
│  │  daemon     │    │  or OpenAI)    │  │
│  │  :18789     │    └────────┬───────┘  │
│  └──────┬──────┘             │          │
│         │           ┌────────▼───────┐  │
│  Telegram Bot       │  MCP Server    │  │
│         │           │  limbo-vault   │  │
│         │           └────────┬───────┘  │
│         └────────────────────┤          │
│                              ▼          │
│                      /data/vault/       │
│                      (markdown notes)   │
└─────────────────────────────────────────┘

ZeroClaw — Rust runtime (~5 MB RAM) handling connections, LLM routing, Telegram, and MCP tools
MCP server — Node.js vault read/write tools, spawned by ZeroClaw
Vault — plain markdown with YAML frontmatter, persisted in a Docker volume

Agent Installation (headless)

For CI/CD or automated provisioning:

npx limbo-ai start --provider anthropic --api-key sk-ant-xxx --model claude-sonnet-4-6

Flag	Required	Default	Description
`--provider`	yes	—	`anthropic`, `openai`, or `openrouter`
`--api-key`	yes	—	Provider API key
`--model`	no	Provider default	Model name
`--language`	no	`en`	`en` or `es`

Headless mode skips Telegram. Add it later with limbo start --reconfigure.

Subscription auth (Claude Code, ChatGPT Plus) requires the interactive wizard.

Environment Variables

Managed by limbo start, stored in ~/.limbo/.env.

Variable	Default	Description
`AUTH_MODE`	`api-key`	`api-key` or `subscription`
`MODEL_PROVIDER`	`anthropic`	`anthropic`, `openai`, `openai-codex`, or `openrouter`
`MODEL_NAME`	`claude-sonnet-4-6`	Model to use
`RUNTIME_REASONING_EFFORT`	`medium`	ZeroClaw `runtime.reasoning_effort` override
`TELEGRAM_ENABLED`	`false`	Enable Telegram integration
`VOICE_ENABLED`	`false`	Enable Groq voice transcription
`WEB_SEARCH_ENABLED`	`false`	Enable Brave web search

Development

# Run MCP server locally
cd mcp-server && npm install && VAULT_PATH=./dev-vault node index.js

# Build image locally
docker build -t limbo:dev . && docker compose up -d

# Run tests
npm test

See CONTRIBUTING.md for release and deployment process.