CaroAI Mate

Your personal AI teammate — with memory, capabilities, and multi-model support. Runs on your own Mac. Connects via Telegram or WhatsApp. Messages and memory stay on your machine.

Version: 0.10.0

What is CaroAI?

CaroAI Mate is a self-hosted AI product that turns your Mac into a personal AI teammate. You chat via Telegram or WhatsApp. Your teammate has persistent memory, grows its capabilities over time, and you choose which model powers it.

Unlike cloud AI assistants:

• Your data stays on your Mac. Messages, memory, capability files — all local. Model queries and voice transcription go to your chosen provider's API.
• You choose the model. Anthropic, OpenAI, DeepSeek, Groq, MiniMax, Kimi, or any compatible endpoint.
• Your teammate grows. It learns from interactions, building skills and knowledge automatically.

Core Features

Three-layer teammate architecture

Every teammate is defined by three files:

| File | Role | What it contains | |------|------|------------------| | IDENTITY.md | Who | Identity, principles, boundaries | | MEMORY.md | What | Context index (stays ≤ 200 lines; auto-splits into memory/{topic}.md) | | SKILLS.md | How | Capability directory — skills, modules, and guides |

Your teammate reads all three before every task, so it always knows who it is, what it knows, and what it can do.

Capability modules (new in V0.8)

Three types of capabilities, loaded progressively:

• Skill — a single procedure with clear trigger and steps (Anthropic SKILL.md format)
• Module — a capability domain: MODULE.md index + guides/ folder with practical experience
• Guide — a standalone practical guide (one .md file)

SKILLS.md is the single index. Capabilities are loaded on demand — your teammate only reads the full content when a task requires it, keeping context lean.

17 pre-built modules ship with V0.8, covering areas from content creation to industry monitoring.

Growth cycles (automatic, transparent)

Three scheduled cycles:

• Micro-reflection — runs 60s after each idle session; captures small insights
• Daily reflection — runs at 04:00; consolidates the day's memory
• Full growth cycle — runs every 3 days; extracts capability candidates into skills/

Everything is markdown. You can read, edit, or delete any file any time.

Multi-model support

Configure your teammate with any model:

{
  "name": "Coach",
  "provider": "anthropic",
  "model": "claude-opus-4-6"
}

Supported out of the box:

• Anthropic (Claude Opus/Sonnet/Haiku)
• OpenAI (GPT-4o, o-series)
• DeepSeek (DeepSeek Chat)
• Groq (Llama, Mixtral — fast inference)
• MiniMax (M series)
• Kimi / Moonshot (K series)
• Any compatible API (set base_url + auth_token_env)

You only need API keys for the providers you use.

Telegram & WhatsApp

Connects through Telegram (recommended — no extra phone number needed) or WhatsApp. @ mention to trigger, or set to respond to every message.

Security

• sudo and system directory writes blocked via command blocklist
• Dangerous shell commands (rm -rf /, mkfs, etc.) blocked at guardrail level (not a full sandbox — defense in depth, not isolation)
• Secrets loaded from .env at runtime, never stored in environment variables
• External content (web search, URL reads, MCP tools) wrapped with injection defense
• File operations restricted to workspace + explicitly granted directories via path validation
• Symlink escape prevention with ancestor path verification
• Every tool call logged

Install

# 1. Install globally from npm
npm install -g caroai

# 2. Run the setup wizard (opens a browser page to configure keys + channel)
caroai setup

# 3. Start
caroai start

See INSTALL.md for details.

CLI commands

| Command | What it does | |---------|-------------| | caroai setup | Interactive web-based setup wizard (API keys, channel, first teammate) | | caroai start | Start the assistant | | caroai autostart | Register as a system service (launchd on macOS, systemd on Linux) | | caroai status | Show running status and channel info |

Project structure

caroai-v0/
├── src/                    # TypeScript source
├── modules/                # Pre-built capability modules (17 domains)
├── groups-template/        # Template for new teammates
├── skills-template/        # Starter skills (safety, memory-slim, neat-freak)
├── prompts/                # System prompt templates
├── scripts/                # Setup + install helpers
├── docs/                   # Specs and design docs
└── dist/                   # Compiled JS (after npm run build)

After installation, your workspace becomes:

~/caroai/
├── groups/
│   ├── main/               # Your teammate
│   │   ├── IDENTITY.md     # Who — identity
│   │   ├── MEMORY.md       # What — knowledge index
│   │   ├── SKILLS.md       # How — capability directory
│   │   ├── memory/         # Memory subtopics
│   │   ├── skills/         # Skills and guides
│   │   └── modules/        # Capability modules (symlinked from package)
│   └── ...
├── store/                  # SQLite + auth state
└── logs/

Credit

CaroAI builds on:

• Anthropic SKILL.md format for skill definitions
• grammY for Telegram
• Baileys for WhatsApp
• Ideas informed by NanoClaw, Hermes, Claude Code, and the broader agent-harness ecosystem

CaroAI's growth concept draws on agent memory research including GEPA (Stanford) and Evolver (EvoMap). Our contribution is the product: a consumer-ready, local-first AI teammate with automatic memory, capability curation, and multi-model support.

License

See LICENSE for terms.