# Opengriffin > Self-evolving personal AI agent. Telegram-first. Multi-provider BYO key. Persistent memory, daily journal, skill graph, dream cycle. Free forever. Apache 2.0. - **Type:** MCP server - **Install:** `agentstack add mcp-mr-tharun-sure-opengriffin` - **Verified:** Pending review - **Seller:** [mr-tharun-sure](https://agentstack.voostack.com/s/mr-tharun-sure) - **Installs:** 0 - **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml) - **Latest version:** 0.1.0 - **License:** Apache-2.0 - **Upstream author:** [mr-tharun-sure](https://github.com/mr-tharun-sure) - **Source:** https://github.com/mr-tharun-sure/opengriffin - **Website:** https://opengriffin.com ## Install ```sh agentstack add mcp-mr-tharun-sure-opengriffin ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # OpenGriffin > The Claude-native personal agent that **learns while you sleep** — and lives in your Telegram. [](LICENSE) [](https://www.python.org/) [](https://github.com/ManasaEdavalli-TharunSure/opengriffin/actions/workflows/ci.yml) [](https://core.telegram.org/bots) **You wake up. Overnight, your agent has read yesterday back to itself, written down what it learned about you, caught its own failures, and proposed new skills — in a journal you can read over coffee.** That nightly self-improvement loop, built *natively* on the [Claude Agent SDK](https://github.com/anthropics/claude-agent-sdk-python) — real skills, MCP, hooks, resumable sessions, not a reimplementation — is what OpenGriffin is. It lives in your Telegram, runs entirely on your own machine, and works with any of 21 model providers on your own key. Run griffin card to turn any night's journal entry into a card like this — your shareable “here's what my agent did overnight.” --- ## How it's different The personal-agent space is crowded — Nous Research's **Hermes Agent**, **OpenClaw**, and **QwenPaw** all do self-evolving, multi-messenger, BYO-key, and local-first. OpenGriffin doesn't claim to out-feature them. Two things are genuinely ours: 1. **It's the Claude-native one.** OpenGriffin runs *on the Claude Agent SDK itself* — your skills are real Claude Code skills under `~/.claude/skills/` (shared with Claude Code), MCP servers, hooks, and resumable sessions all work as-is. The others reimplement an agent loop; OpenGriffin *is* the Claude loop, wearing a Telegram face. 2. **The journal is a readable, shareable artifact.** The nightly loop doesn't just mutate hidden state — it writes you a page you can read, and `griffin card` makes it shareable. "Learns while you sleep" you can actually *see*. | | OpenGriffin | Hermes (Nous) | OpenClaw | QwenPaw | |---|:---:|:---:|:---:|:---:| | Built **on** the Claude Agent SDK (native skills / MCP / hooks / sessions) | ✅ | ❌ own runtime | ❌ own runtime | ❌ Qwen / AgentScope | | Readable nightly journal you can screenshot & share | ✅ `griffin card` | ❌ | ❌ | ❌ | | Telegram-native onboarding (one messenger, ~2 min) | ✅ | one of many | one of many | one of many | | Self-evolving skills | ✅ | ✅ | ◑ | ✅ | | Multi-messenger gateways | ✅ 7 | ✅ 7 | ✅ 20+ | ✅ 5 | | BYO-key / multi-provider | ✅ 21 | ✅ (incl. 200+ via OpenRouter) | ✅ | ✅ | | Local-first / no backend | ✅ | ✅ | ✅ | ✅ | | Acts proactively (cron / triggers) | ✅ | ✅ | ✅ heartbeat | ✅ | | License | Apache-2.0 | MIT | MIT | OSS | Comparison reflects publicly documented features as of mid-2026. Hermes, OpenClaw, and QwenPaw are excellent projects with far larger communities — this table is about *fit*, not size. --- ## Why OpenGriffin - **Self-evolving skill graph.** The agent authors, edits, and retires its own skills at runtime. No redeploy. New capabilities ship inside a conversation. - **Daily journal at 4:30 AM.** Every conversation, decision, and tool call is appended to a structured journal. A nightly self-improvement loop reads yesterday's entries, summarizes them, and proposes new skills — then `griffin card` renders the entry into a shareable image. - **21 AI providers, BYO key.** Claude Max OAuth, Anthropic, OpenAI, OpenRouter, Azure, Gemini, Mistral, Cohere, Groq, Together, Fireworks, DeepSeek, HuggingFace, Perplexity, xAI, Bedrock, Cerebras, NVIDIA NIM, Lambda Labs, Novita, Ollama. Switch with one env var. - **Persistent memory: MEMORY / USER / SOUL.** Three flat markdown files load fresh into every session. `MEMORY.md` is the environment, `USER.md` is the profile, `SOUL.md` is the voice. - **Multi-surface.** Telegram is the front door, but the same brain answers via CLI, webhooks, and voice notes. - **Skill auto-discovery.** Drop a markdown file into `~/.claude/skills/`, and the agent picks it up on next turn — no registry, no config. - **Voice round-trip.** `faster-whisper` transcribes inbound voice notes; `edge-tts` speaks replies in the user's preferred neural voice. - **Browser automation via Playwright MCP.** Screenshots, scraping, end-to-end clicks. The agent can drive a real Chromium. - **Kanban built in.** Multiple agent workers claim, block, and complete tasks against a shared board. Long plans get parallelized. - **Checkpoints + rollback.** Conversation snapshots survive crashes. The agent can replay or branch off any prior point. - **Approval inline buttons.** Risky actions ask first via Telegram inline keyboards. Confirm or deny with a tap; nothing destructive runs unsupervised. --- ## The 12 killer features | # | Feature | What it does | |---|---|---| | 1 | **Skill Hub** | Install community skills directly from GitHub URLs with license auto-check, signing, and reputation tracking by *outcome*, not stars. | | 2 | **Echo Memory + Receipts** | Autobiographical hierarchical memory (vivid → recent → fading → ancient). Every recalled fact comes with a citation receipt like `[echo:vivid/2026-05-06:abc123]` linking back to the source session. | | 3 | **Ambient Trigger Mesh** | Compose triggers from cron, webhook, or polled URLs → optional LLM yes/no predicate → skill or prompt action. The agent acts before you notice the problem. | | 4 | **Agent Pods** | Multiple agent personas with distinct SOUL files but shared memory. Add them to a group chat, watch them debate, converge. | | 5 | **Agentic Wallet (x402)** | The agent can pay for things — sandbox wallet + per-skill spending caps + Telegram inline-button approval. Pays only after you tap. | | 6 | **Soul Sync** | Mines your past chats for writing voice (sentence length, contractions, recurring phrases). Builds a `VOICE.md` the agent uses to draft *as you*. | | 7 | **Provider Routing Auctions** | Lightweight classifier scores each prompt 0–3, routes to cheapest tier that can answer. Heavy thinking goes to Claude Opus / o1; "summarize this" goes to Groq for $0.0001. | | 8 | **Drift Detection** | Nightly scan of `USER.md` against recent journal entries. Flags contradictions: _"3 months ago you told me you hated meetings; today you scheduled five."_ | | 9 | **Self-Healing Skills** | When a skill fails 3+ times in a week, the agent debugs it, proposes an updated `SKILL.md`, and asks for approval before applying. | | 10 | **Skill Graph Strategy** | Reads your usage to recommend missing skills based on co-occurrence, flags never-used skills, and surfaces your top-used ones. | | 11 | **Memory Receipts** | Every claim the agent makes can be traced. Tap a receipt token to see the exact session and turn that established the fact. | | 12 | **Reputation Ledger** | Signed JSON-LD profile (`/u/`) showing task count, approval rate, specialties, authored skills. A2A-discoverable for agent-to-agent trust. | The frontier modules — **Personal World Model**, **Living Twin**, **Verifiable Refusal Proofs + Provable Forgetting**, **Generative Live UI**, **Mesa-Cognition Supervisor**, **Capability-Scoped Skill Leasing**, **Personal Causal Layer**, and the **Adversarial Improvement Market** — ship in addition. See [docs/frontier.md](docs/frontier.md) for the design notes. --- ## Nightly auto-loops Every night, OpenGriffin runs without prompting: | Time | Job | What | |---|---|---| | 04:00 | Daily session reset | Archives sessions; preserves the next morning a fresh slate while keeping recall | | 04:30 | Self-improvement | Reads yesterday's transcripts, consolidates `MEMORY` / `USER`, writes `JOURNAL.md`, suggests skills | | 04:45 | Echo memory consolidation | Rolls older sessions up the time hierarchy (vivid → recent → fading → ancient) | | 05:00 | Drift detection | Surfaces contradictions in user model / behavior | | 05:15 | World model retrain | Rebuilds the personal forecast from the event log | | 05:30 | Mesa-cognition report | Scores the agent's own behavior for drift signatures | | 05:45 | Causal discovery | Walks the event log for new cause→effect proposals | | Sun 05:00 | Voice card refresh | Re-extracts writing-voice profile from past week's chats | | per-trigger | Ambient triggers | All cron-based triggers from `triggers.json` | --- ## Quick start ```bash # One-line install (clones, runs uv sync, writes a launchctl/systemd unit) curl -fsSL https://raw.githubusercontent.com/ManasaEdavalli-TharunSure/opengriffin/main/scripts/install.sh | bash # Or from source git clone https://github.com/ManasaEdavalli-TharunSure/opengriffin.git cd opengriffin uv sync --all-extras cp .env.example ~/.opengriffin/.env # fill in TELEGRAM_BOT_TOKEN + TELEGRAM_ALLOWED_USERS uv run opengriffin doctor # verify env + provider uv run opengriffin run # start the bot ``` On first launch, OpenGriffin will: 1. Load `.env` from `~/.opengriffin/.env` (or `OPENGRIFFIN_HOME/.env` if you've overridden the path). 2. Detect available providers (Claude Max → Anthropic → OpenAI → Ollama). 3. Create `MEMORY.md`, `USER.md`, `SOUL.md`, and a `JOURNAL.md` under `~/.opengriffin/memories/`. 4. Drop you into a chat where the agent can already use tools. ```bash # Use a specific provider OPENGRIFFIN_PROVIDER=openrouter opengriffin run # Diagnose the install opengriffin doctor # Run the nightly self-improvement loop manually opengriffin improve # Turn last night's journal entry into a shareable card (SVG, + PNG with --png) opengriffin card --png # Migrate state from a prior agent runtime (see docs/migration.md) opengriffin migrate from-hermes ``` --- ## First-time setup — pick your messenger OpenGriffin runs **the same brain** across 7 free-pricing platforms. You create the bot in whichever messenger you use, paste its credential into your local `.env`, and run the agent on your own machine. There is no hosted onboarding, no waitlist, no account — you own the keys, the data, and the process. The shared steps for every gateway are: 1. Create a bot / account / app on the platform → get a credential. 2. Find your own user id / handle / phone number on the platform. 3. Add credential + allowed-users env vars to `~/.opengriffin/.env`. 4. (For some gateways) `pip install 'opengriffin[]'` to pull the platform SDK. 5. `opengriffin doctor` then `opengriffin run`. You also need **at least one model key** in `.env`. Any of these is enough: ```bash ANTHROPIC_API_KEY=sk-ant-... # or OPENAI_API_KEY, GEMINI_API_KEY, # GROQ_API_KEY, DEEPSEEK_API_KEY, … OPENGRIFFIN_PROVIDER=anthropic # must match the key you set ``` You can enable **multiple gateways at once** — the bot starts every gateway whose required env vars are present. They share one memory, one kanban, one set of MCP servers. See [Cross-platform identity](docs/gateways/index.md#cross-platform-identity) to link your accounts. > ⚠️ Across every gateway: leaving the `*_ALLOWED_USERS` (or equivalent) env var **empty** makes the bot **open to anyone** who finds it. Set it to your own id while testing. | Platform | Difficulty | Extras needed | Detailed doc | |---|---|---|---| | [Telegram](#telegram) | ⭐ easy | none | [docs/gateways/telegram.md](docs/gateways/telegram.md) | | [Discord](#discord) | ⭐ easy | `[discord]` | [docs/gateways/discord.md](docs/gateways/discord.md) | | [Slack](#slack) | ⭐⭐ medium | `[slack]` | [docs/gateways/slack.md](docs/gateways/slack.md) | | [Email](#email-imapsmtp) | ⭐⭐ medium | none (stdlib) | [docs/gateways/email.md](docs/gateways/email.md) | | [iMessage](#imessage-macos-only) | ⭐⭐ medium | macOS only | [docs/gateways/imessage.md](docs/gateways/imessage.md) | | [Matrix](#matrix) | ⭐⭐ medium | `[matrix]` | [docs/gateways/matrix.md](docs/gateways/matrix.md) | | [Signal](#signal) | ⭐⭐⭐ hard | `signal-cli` + Java 21+ | [docs/gateways/signal.md](docs/gateways/signal.md) | ### Telegram 1. **Create the bot** — DM **@BotFather** → `/newbot` → pick display name → pick a username ending in `bot` → copy the `1234567890:AAH...` token. 2. **Get your user id** — DM **@userinfobot** anything; it replies with your numeric id (e.g. `987654321`). 3. **Configure** `~/.opengriffin/.env`: ```bash TELEGRAM_BOT_TOKEN=1234567890:AAH...your-token-here TELEGRAM_ALLOWED_USERS=987654321 # your numeric user id TELEGRAM_HOME_CHANNEL=987654321 # default destination for cron + proactive messages ``` 4. **Run** — `opengriffin doctor && opengriffin run`. Open your bot in Telegram, send `/start`, you'll see the command menu. `/whoami` confirms auth. Optional BotFather steps while you're there: `/setprivacy` (Enable = DM/mention-only; Disable = sees all group messages), `/setdescription`, `/setuserpic`, `/setcommands` (or use the `setMyCommands` curl snippet in the detailed doc). ### Discord 1. **Create the bot** — go to → **New Application** → **Bot** tab → **Reset Token** → copy. 2. **Enable Message Content Intent** under Privileged Gateway Intents (without this, the bot connects but never sees messages). 3. **Invite it to your server** — OAuth2 → URL Generator → scopes: `bot`, `applications.commands`; permissions: `Send Messages`, `Read Message History`, `Use Slash Commands`. Open the generated URL and pick your server. 4. **Get your user id** — enable Developer Mode (User Settings → Advanced), right-click your name → Copy User ID. 5. **Configure**: ```bash DISCORD_BOT_TOKEN= # from step 1 DISCORD_ALLOWED_USERS= # comma-separated numeric user ids ``` 6. **Install + run** — `pip install 'opengriffin[discord]'` then `opengriffin run`. DM the bot or @-mention it in a channel. Discord caps messages at 2000 chars; OpenGriffin auto-splits longer replies. Voice channels and slash commands are not yet wired. ### Slack Uses Slack Bolt **Socket Mode** — no public webhook URL needed. 1. **Create the app** — → **Create New App** → from scratch. 2. **App-Level Token** — Socket Mode → Enable → Generate App-Level Token with `connections:write` scope. Save the `xapp-...` token. 3. **Bot Token Scopes** under OAuth & Permissions: `chat:write`, `im:history`, `im:read`, `im:write`, `channels:history`, `channels:read`, `app_mentions:read`. 4. **Event Subscriptions** → Enable → subscribe to bot events: `message.im`, `app_mention`. 5. **Install App to Workspace** — copy the bot token (`xoxb-...`). 6. **Configure**: ```bash SLACK_BOT_TOKEN=xoxb-... SLACK_APP_TOKEN=xapp-... SLACK_ALLOWED_USERS= # comma-separated Slack user ids; empty = open to workspace ``` 7. **Install + run** — `pip install 'opengriffin[slack]'` then `opengriffin run`. DM the bot or @-mention it in any channel where it's been added. Threading works automatically — replies stay in the thread they came from. Effective message limit is ~40k chars. ### Email (IMAP/SMTP) Stdlib only — no extra deps. IMAP polling for inbound, SMTP for outbound. Great for long-form async work and webhook-driven inbound (Zapier/Make → email → bot). 1. **Get IMAP + SMTP credentials.** For Gmail/Workspace or iCloud (with 2FA on, which is the default), you need an **App Password**, not your account password: - Gmail: → create one for Mail; use the 16-character output. - iCloud: → Sign-In and Security → App-Specific Passwords. - Other providers: usually IMAP 993 (SSL) + SMTP 587 (STARTTLS). 2. **Configure**: ```bash EMAIL_IMAP_HOST=imap.gmail.com EMAIL_IMAP_PORT=993 EMAIL_IMAP_USER=you@example.com EMAIL_IMAP_PASS=app-password-here EMAIL_SMTP_HOST=smtp.gmail.com EMAIL_SMTP_PORT=587 EMAIL_SMTP_USER=you@example.com # defaults to IMAP_USER if blank EMAIL_SMTP_PASS=app-password-here # defaults to IMAP_PASS if blank EMAIL_FROM_ADDR=you@example.com EMAIL_ALLOWED_SENDERS=trusted@example.com,boss@example.com ``` 3. **Run** — `opengriffin run`. Email the bot from an allowed sender. Polling cadence is 60s (no IMAP IDLE in stdlib); threading is preserved via message-id chains. ### iMessage (macOS only) Reads `~/Library/Messages/chat.db` directly; sends via AppleScript through Messages. … ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [mr-tharun-sure](https://github.com/mr-tharun-sure) - **Source:** [mr-tharun-sure/opengriffin](https://github.com/mr-tharun-sure/opengriffin) - **License:** Apache-2.0 - **Homepage:** https://opengriffin.com Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** yes - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** yes - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: flagged — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-mr-tharun-sure-opengriffin - Seller: https://agentstack.voostack.com/s/mr-tharun-sure - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.