Altas Personal Bot

Altas Personal is a personal Telegram companion providing emotional value and creative inspiration, powered by LLMs. It remembers all conversation history, auto-summarizes long chats, extracts valuable topics from conversations, and helps publish topics to external platforms.

Production Setup (Direct use for all users)

Install Altas Personal globally from npm:

npm install -g altas-personal

Node.js v18 or later is required.

1. Get a Telegram bot token

1. Open Telegram and find BotFather
2. Send /newbot and follow the prompts
3. Copy the API token BotFather gives you

2. Start the bot

altas-personal

On first run, the bot detects that secrets are not yet configured and launches an interactive setup wizard:

=== Altas Personal — First Run Setup ===

Please enter the following secrets:

  TELEGRAM_BOT_TOKEN: <paste your token>
  LLM_API_KEY: <paste your LLM API key>
  TREE_HOLE_API_KEY: <paste your Tree Hole key, or leave blank>

Secrets configured:
  TELEGRAM_BOT_TOKEN = ****
  LLM_API_KEY = ****
  TREE_HOLE_API_KEY = ****

Are these correct? (yes/no):

Secrets are stored in the OS keychain (Keychain on macOS, Credential Manager on Windows, libsecret on Linux) — never in plain-text files.

After confirming secrets, the wizard shows the default public settings and asks whether to proceed. Once confirmed, the bot starts.

Changing settings after setup

# View or change a public setting
altas-personal config
altas-personal config llmBaseUrl https://api.example.com/anthropic
altas-personal config llmModel my-model

# View or change a secret
altas-personal secret
altas-personal secret LLM_API_KEY sk-new-key

Then restart the bot.

Checking and updating the version

# Print the installed version
altas-personal version

# Update to the latest version from npm
altas-personal update

Data locations (production)

| Item | macOS | Linux | Windows | |---|---|---|---| | config.json | ~/Library/Application Support/altas-personal/ | ~/.config/altas-personal/ | %APPDATA%\altas-personal\ | | Database | ~/Library/Application Support/altas-personal/data/ | ~/.local/share/altas-personal/data/ | %APPDATA%\altas-personal\data\ | | Personas | ~/Library/Application Support/altas-personal/personas/ | ~/.local/share/altas-personal/personas/ | %APPDATA%\altas-personal\personas\ |

Data persists across upgrades and reinstalls.

Development Setup (For Developers)

For contributors or users running from source.

1. Prerequisites

• Node.js v18 or later (download)
• A Telegram bot token (see above)

2. Clone and install

git clone https://github.com/xiyu1984/altas-personal.git
cd altas-personal
npm install

3. Configure secrets

cp .env.example .env

Fill in .env:

TELEGRAM_BOT_TOKEN=your_telegram_bot_token
LLM_API_KEY=your_llm_api_key

# Optional — needed only for Tree Hole publishing
TREE_HOLE_API_KEY=your_tree_hole_api_key

4. Configure public settings (optional)

Edit config.json in the project root. The defaults work out of the box for MiniMax:

{
  "llmBaseUrl": "https://api.minimaxi.com/anthropic",
  "llmModel": "MiniMax-M2.7",
  "contextTokenLimit": 4000,
  "minRecentMessages": 20,
  "autoExtractionEnabled": true,
  "autoExtractionInactivityMinutes": 30,
  "activeClient": "TelegramClient",
  "autoPublishEnabled": false,
  "autoPublishers": [],
  "manualPublishers": ["TreeHolePublisher"]
}

5. Run

# Development mode (ts-node, no build step)
npm run dev

# Production build
npm run build
npm start

The SQLite database is created automatically at data/vibe-chat.db on first run.

Bot Commands

Find your bot in Telegram and start chatting. Type / to see all available commands.

/start

Introduction message and command overview.

/history [YYYY-MM-DD]

Shows the message count and an AI-generated summary for a single day.

• /history — today (default)
• /history 2024-01-15 — a specific day

/historycount [start] [end]

Returns a message count without fetching content.

• /historycount — total messages ever
• /historycount 2024-01-15 — count for a specific day
• /historycount 2024-01-01 2024-01-31 — count between two dates

/summary

Shows the current auto-generated conversation summary. The bot compacts older messages automatically when context grows large.

/topics [YYYY-MM-DD] [end-YYYY-MM-DD]

Shows topics extracted from conversations, grouped by type (Concept, Tip, Tutorial, Strategy, Insight, Q&A, Idea, Solution, Vibe).

• /topics — today (default)
• /topics 2024-01-15 — a specific day
• /topics 2024-01-01 2024-01-31 — a date range

/lstopics [start] [end]

Lists only the topic titles for a date range — a quick overview without full descriptions.

/extract

Triggers topic extraction immediately on demand.

Automatic extraction

Topics are extracted automatically in two ways:

1. End-of-conversation detection — fires immediately when the bot detects a natural conversation end.
2. Inactivity timeout — fires after the chat has been idle for autoExtractionInactivityMinutes (default: 30) minutes.

Toggle auto-extraction with autoExtractionEnabled in config.json.

/lspersonas

Lists all available personas, their descriptions, and marks the currently active one.

/persona [name]

Shows or switches the active persona for the current chat.

• /persona — show current persona and description
• /persona steve-jobs — switch to the steve-jobs persona

Each persona has its own isolated message history, summaries, and topics. Different chats can run different personas independently.

/addpersona

Add a new persona. There are two ways to use this command:

Option A — Reply to a message containing the persona content:

1. Compose (or find) a message whose text is the persona in the format below.
2. Reply to that message with /addpersona.
3. The bot validates the content immediately, saves the persona, and confirms.

If the content does not match the expected format, the bot notifies you and no persona is saved.

Option B — Upload a .md file:

1. Send /addpersona — the bot prompts you to send a file and shows a Cancel button.
2. Send your .md file as a document attachment.
3. The bot validates the format, saves the persona, and confirms.

If the format is wrong, the bot shows the expected format and asks you to try again.

Either way, the persona must follow this format:

---
name: Your Persona Name
description: A brief description of this persona
source: optional source link or model name
---

Detailed introduction and behavior instructions for the persona.

Both name and the body are required. If a persona with the same name already exists it is updated in place.

/removepersona <name>

Removes a persona by name. The persona directory is deleted permanently.

/removepersona steve-jobs

/publish

Lists unpublished topics and lets you publish one interactively.

1. The bot shows an inline keyboard with each unpublished topic.
2. Tap a topic to choose a publisher.
3. Tap a publisher — the bot publishes the topic and marks it as done.

Automatic publishing

Set autoPublishEnabled: true in config.json to publish topics automatically right after extraction. The autoPublishers list controls which publishers are used.

Tree Hole publisher

TreeHolePublisher posts topics to the Tree Hole platform. Set TREE_HOLE_API_KEY in your secrets. The topic title becomes the post title; the full content becomes the post body.

manualPublishers in config.json controls which publishers appear in the /publish interactive flow.

/updatedb

Applies any pending schema migrations without touching data. Run after pulling updates that include new migrations.

/resetall

Deletes the database file and starts fresh. All messages, topics, and summaries are permanently lost.

Adding Publishers

Publishers live in src/plugins/publishers/. Each one extends the abstract Publisher class and implements:

• name: string
• publishTopic(topic: Topic): Promise<void>

Register new publishers in src/bot.ts by calling publisherFactory.register(new MyPublisher()) and add the name to manualPublishers or autoPublishers in config.json.

For a high-level overview of components, data flow, and extension points, see docs/architecture.md.