Mamba

Mamba is a persistent AI agent that remembers you, runs on a schedule, and talks to you on Telegram. Built on top of the Codex SDK. This is project is inspired by Openclaw.

Mamba isn't a chatbot you poke when you need something. It's an always-on agent with long-term memory, cron-based task scheduling, and multi-channel connectivity. It has opinions, remembers important detaila, and won't say "You're Absolutely Right!"

Features

• Persistent memory — File-based memory system with daily logs and curated long-term storage. BM25 search with recency boosting. Survives restarts.
• Cron scheduler — Schedule recurring tasks with cron expressions. Jitter support to avoid thundering herd. Runs alongside the main conversation loop.
• Telegram bot — Poll-based integration with code-word authentication. No webhooks, no public IP required.
• Skill system — Modular capabilities via markdown files. Ships with schedule management, memory search, and Telegram setup. Drop in your own.
• Personality framework — SOUL.md defines who the agent is. No corporate AI language. Genuine reactions, real opinions, actual personality.
• Twitter/X integration — Fetch timelines and mentions via the bird CLI (optional).
• iMessage — Send and read iMessages on macOS (optional).

Prerequisites

• Python 3.12+
• Node.js (for Codex CLI)
• Codex CLI — the agent runtime

npm install -g @openai/codex

Optional

These are only needed if you enable the corresponding skills during onboarding:

Tool	Skill	Platform	Install
bird	twitter-fetch	Any	pip install bird-cli
imsg	imsg	macOS 14+	brew install steipete/tap/imsg

imsg requires Full Disk Access and Automation permissions in System Settings.

Quick Start

Install

pip install mamba

Or with uv:

uv pip install mamba

Run

mamba

First run walks you through onboarding: pick a name for your agent, configure timezone, optionally set up Telegram, and choose which skills to install.

How It Works

Mamba runs three concurrent loops:

1. Input loop — Interactive terminal conversation with the agent
2. Scheduler — Checks schedule.json every 60 seconds, fires due tasks
3. Telegram — Polls for incoming messages (if configured)

All three share a single agent instance behind an async lock.

Workspace

The agent's state lives in src/mamba/workspace/:

workspace/
├── AGENTS.md          # Operating manual
├── IDENTITY.md        # Name, vibe, emoji
├── SOUL.md            # Personality rules
├── USER.md            # Info about you
├── MEMORY.md          # Long-term curated memories
├── HEARTBEAT.md       # Proactive check-in checklist
├── memory/            # Daily logs (YYYY-MM-DD.md)
├── skills/            # Installed skills
├── config.json        # Runtime config (timezone, etc.)
├── telegram.json      # Telegram bot config
└── schedule.json      # Scheduled tasks

Everything is plain markdown and JSON. Human-readable, easy to edit by hand.

Configuration

Environment Variables

Variable	Description
MAMBA_TELEGRAM_TOKEN	Telegram bot token (overrides telegram.json)
MAMBA_TELEGRAM_CODE_WORD	Auth passphrase for first Telegram user

Telegram Setup

Run the onboarding flow or manually create workspace/telegram.json:

{
  "bot_token": "your-bot-token",
  "code_word": "your-passphrase",
  "authenticated_users": [],
  "blocked_users": []
}

First person to message the bot with the correct code word gets authenticated.

Scheduling

Tasks in schedule.json use cron syntax:

[
  {
    "id": "morning-briefing",
    "task": "Send me a morning briefing with weather and calendar",
    "cron": "0 8 * * *",
    "jitter_minutes": 5
  }
]

Custom Skills

Drop a directory into workspace/skills/ with a SKILL.md file:

---
name: my-skill
description: Does the thing
---

Instructions for the agent on how to use this skill...

The agent discovers skills at startup and includes them in its context.

License

MIT