AgentTwin

Your Digital Twin That Never Forgets What Matters

A personal AI orchestrator with biologically-inspired memory that learns you,
anticipates your needs, and delegates to AI agents on your behalf.

Why AgentTwin • Features • Quick Start • Architecture • Advantages

---

Why AgentTwin?

Most AI memory systems have a fundamental flaw: they never forget.

This sounds great until you realize:

• Old preferences override new ones
• Irrelevant context pollutes every query
• Token costs explode as memory grows
• The AI becomes less useful over time

AgentTwin is different. Built on FadeMem + EchoMem, it uses biologically-inspired memory:

Human Brain	AgentTwin
Important memories strengthen over time	EchoMem multi-modal encoding
Unused memories fade naturally	FadeMem decay algorithm
We rehearse to remember	Echo depth (shallow → deep)
Context-dependent recall	Category-based retrieval

The result? An AI that stays relevant, not one that drowns in its own history.

---

Features

Memory That Works Like Yours

┌─────────────────────────────────────────────────────────┐
│                     EchoMem                              │
│  ┌──────────┐   ┌──────────┐   ┌──────────────────┐    │
│  │ Keywords │ → │Paraphrase│ → │ Implications     │    │
│  │ (shallow)│   │ (medium) │   │ (deep encoding)  │    │
│  └──────────┘   └──────────┘   └──────────────────┘    │
│         ↓             ↓               ↓                 │
│    1.0x strength  1.3x strength   1.6x strength        │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│                     FadeMem                              │
│  Short-term (SML) ←──decay──→ Long-term (LML)          │
│  • Recent context           • Core preferences          │
│  • Active tasks             • Learned patterns          │
│  • Fades quickly            • Persists longer           │
└─────────────────────────────────────────────────────────┘

Proactive Intelligence

AgentTwin doesn't wait for commands—it anticipates needs:

• Pattern Detection: "You usually deploy on Fridays at 3pm"
• Predictive Context: Pre-fetches relevant memories before you ask
• Smart Suggestions: "Ready for your weekly code review?"

Visual Task Management

Integrates with vibe-kanban for beautiful task visualization:

# Run with visual kanban board
agenttwin-vibe

Multi-Agent Orchestration

• Claude Code: Coding, git, file operations, deployments
• Extensible: Add your own agents (Codex, CLI, custom)
• Parallel Execution: Multiple agents, one interface

Mobile-First via Telegram

Your AI lives in your pocket:

• Natural conversation in personal chat
• Task-specific group chats for visibility
• Pause/intervene anytime with /pause
• Works from anywhere

---

Quick Start

1. Prerequisites

• Python 3.10+
• Telegram account
• Gemini API key

2. Get Your Tokens

Telegram Bot:

1. Message @BotFather
2. Send /newbot, follow prompts
3. Copy the token

Your Telegram ID:

1. Message @userinfobot
2. Copy your user ID

Gemini API Key:

1. Visit Google AI Studio
2. Create an API key

3. Install

git clone https://github.com/yourusername/agenttwin.git
cd agenttwin
pip install -e .

4. Configure

cp .env.example .env

Edit .env:

TELEGRAM_BOT_TOKEN=your_bot_token
TELEGRAM_OWNER_ID=your_user_id
GEMINI_API_KEY=your_gemini_key

5. Run

# Basic mode
agenttwin

# With vibe-kanban visual board
agenttwin-vibe

---

Usage

Chat Naturally

You: Hey, remember I prefer TypeScript over JavaScript
Twin: Got it! I'll remember your preference for TypeScript.

You: Fix the login bug in the auth module
Twin: 🔄 Planning task...
      📋 Task: Fix Login Bug
      Agent: claude_code
      Proceed? (yes/no)

Commands

Command	Description
/pause	Pause current task, talk privately
/resume	Resume paused task
/cancel	Cancel current task
/status	Check task progress
/memory <query>	Search your memories
/setgroup	Use current group for tasks

Task Flow

1. You describe a task
2. Twin plans and shows steps
3. Confirmation for destructive actions
4. Task executes with live updates
5. /pause anytime to intervene
6. Summary when complete

---

Architecture

┌─────────────────────────────────────────────────────────────┐
│                        AgentTwin                             │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐  │
│  │   Telegram   │    │  Twin Core   │    │ Vibe-Kanban  │  │
│  │     Bot      │◄──►│   (Gemini)   │◄──►│   Bridge     │  │
│  └──────────────┘    └──────────────┘    └──────────────┘  │
│         │                   │                    │          │
│         ▼                   ▼                    ▼          │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐  │
│  │    Group     │    │   Proactive  │    │    Visual    │  │
│  │   Manager    │    │    Engine    │    │    Board     │  │
│  └──────────────┘    └──────────────┘    └──────────────┘  │
│                             │                               │
│                             ▼                               │
│  ┌──────────────────────────────────────────────────────┐  │
│  │              Memory System                            │  │
│  │  ┌─────────────┐              ┌─────────────┐        │  │
│  │  │   EchoMem   │──────────────│   FadeMem   │        │  │
│  │  │ Multi-modal │              │ Bio-decay   │        │  │
│  │  │  Encoding   │              │  (SML/LML)  │        │  │
│  │  └─────────────┘              └─────────────┘        │  │
│  │         │                            │               │  │
│  │         ▼                            ▼               │  │
│  │  ┌─────────────┐              ┌─────────────┐        │  │
│  │  │  Category   │              │   Qdrant    │        │  │
│  │  │  Manager    │              │   Vectors   │        │  │
│  │  └─────────────┘              └─────────────┘        │  │
│  └──────────────────────────────────────────────────────┘  │
│                                                              │
│  ┌──────────────────────────────────────────────────────┐  │
│  │              Agent Adapters                           │  │
│  │  ┌─────────────┐   ┌─────────────┐   ┌───────────┐   │  │
│  │  │ Claude Code │   │    Codex    │   │    CLI    │   │  │
│  │  │    (SDK)    │   │   (Future)  │   │  (Future) │   │  │
│  │  └─────────────┘   └─────────────┘   └───────────┘   │  │
│  └──────────────────────────────────────────────────────┘  │
│                                                              │
└─────────────────────────────────────────────────────────────┘

---

Advantages

Traditional Memory	AgentTwin
Never forgets (noise accumulates)	Biologically-inspired decay
Single embedding	Multi-modal encoding (EchoMem)
Basic patterns	Pattern + Prediction + Context
API/Cloud only	Telegram (mobile-first)
No visualization	Vibe-kanban integration
Cloud dependency	Runs on your machine
Single-agent	Claude Code, Codex, extensible
Cloud pricing	Self-hosted, your API keys
Data on servers	Your data stays local

Why does forgetting matter?

Traditional approach: Store everything forever

• Context grows unbounded
• Old preferences conflict with new ones
• More tokens = higher cost
• Retrieval quality degrades

AgentTwin's approach: Forget like humans do

• Irrelevant memories fade naturally
• Important things get reinforced
• Context stays fresh and relevant
• Retrieval quality improves over time

---

Environment Variables

Variable	Description	Required
TELEGRAM_BOT_TOKEN	Bot token from BotFather	Yes
TELEGRAM_OWNER_ID	Your Telegram user ID	Yes
GEMINI_API_KEY	Google Gemini API key	Yes
GEMINI_MODEL	Model (default: gemini-3-flash-preview)	No
DATA_DIR	Data directory	No
VIBE_KANBAN_URL	Vibe-kanban URL if running	No

---

Roadmap

• Voice messages in Telegram
• Codex agent adapter
• Web dashboard
• iOS/Android native apps
• Team collaboration mode
• Plugin system for custom agents

---

Contributing

Contributions welcome! See CONTRIBUTING.md for guidelines.

---

License

MIT License - see LICENSE for details.

---

Built with FadeMem + EchoMem
Memory that works like yours