Skip to main content

​
Prerequisites

Before you start, make sure you have:
  • Node.js 18+ (Node.js 22+ required for Discord’s zero-dependency WebSocket support)
  • At least one AI backend:
    • Pi — full tool use, memory, and scheduling
    • Codex CLI — Codex-powered sessions
    • A local OpenAI-compatible server (Ollama, MLX, or similar)
  • Credentials for at least one messaging channel (Telegram, WhatsApp, or Discord)

​
Set up Nuggets

1

Clone the repository

git clone https://github.com/moonmidas/nuggets.git
cd nuggets
npm install
2

Run the interactive setup wizard

npm run setup
The wizard walks you through:
  • Choosing your messaging channels (Telegram, WhatsApp, Discord)
  • Selecting your AI backend (Pi, Codex, or local model)
  • Entering API keys and channel credentials
When it finishes, a .env file is created in the project root.
3

Review your .env file

Open .env and confirm the variables look correct. A minimal Telegram + Pi setup looks like:
.env
# Telegram
TELEGRAM_BOT_TOKEN=123456:ABC-DEF...
TELEGRAM_ALLOWLIST=123456789

# Agent backend
AGENT_BACKEND=pi
AGENT_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-...
Leave TELEGRAM_ALLOWLIST empty to allow all users. Set it to your chat ID to restrict access to yourself only.
4

Start the gateway

npm run dev
You should see log output confirming the gateway started and your chosen channels are listening.WhatsApp users: A QR code appears in the terminal. Scan it with your phone using Linked Devices in WhatsApp Settings.
5

Send your first message

Open your Telegram, WhatsApp, or Discord client and send a message to your bot:
Hello! What can you remember?
The assistant replies using your configured AI backend. It has no memories yet — let’s fix that.
6

Store your first memory

Ask the assistant to remember something:
Please remember that my preferred language is TypeScript.
Or use the CLI directly:
nuggets remember project "preferred language" "TypeScript"
Then recall it:
nuggets recall "preferred language"
You should see the fact returned with a confidence score.

​
Verify everything works

Run the type checker and tests to confirm your install is healthy: 
npm run typecheck
npm test
Tests cover FHRR math, fact memory, graph sync, shelf reflection, and gateway routing.

​
Next steps

Setup reference

Complete environment variable reference for all channels and backends.

Memory overview

Understand the three-layer memory system and the recall-first pattern.

Gateway channels

Configure Telegram, WhatsApp, and Discord in detail.

Backend modes

Compare Pi, Codex, and local model backends.

Build docs developers (and LLMs) love

Get started for freeTalk to us