adclaw 0.1.2

Multi-agent AI marketing team with 117 skills, multi-channel support, and shared memory

AdClaw

AI Marketing Agent Team powered by Citedy

Fork of CoPaw by AgentScope (Apache 2.0)

---

What is AdClaw?

pip install adclaw — and you get a multi-agent AI marketing team with:

• Multi-agent personas — create specialized agents (researcher, writer, SEO, ads), each with its own identity (SOUL.md), LLM, skills, and schedule
• @tag routing in Telegram — @researcher find AI trends sends the message to the right agent
• Coordinator delegation — one agent orchestrates the rest, delegating tasks automatically
• Shared memory — agents read each other's output files for seamless collaboration
• 117 built-in skills — SEO, ads, content, social media, analytics, growth hacking
• 52 marketing tools via Citedy MCP server
• Instant file publishing — upload any file to here.now, get a shareable link, host static sites, use your own domain
• 14 LLM providers — OpenAI (GPT-5.4, Codex), Anthropic, xAI, Aliyun (Qwen3.5), Z.AI (GLM-4.7), Moonshot (Kimi K2.5), Ollama, llama.cpp, MLX, and more. Add custom providers via API
• Multi-channel — Telegram, Discord, DingTalk, Feishu, QQ, Console
• Web UI — dashboard, per-persona chat tabs, skills, models, and channels from the browser

                         +-------------------+
                         |    Telegram /      |
                         |  Discord / Web UI  |
                         +--------+----------+
                                  |
                     @tag routing | no tag
                    +-------------+-------------+
                    |                           |
              +-----v------+          +---------v--------+
              |  @researcher|          |   Coordinator    |
              |  SOUL.md    |          |   (default agent)|
              |  LLM: grok  |          |   delegates to   |
              |  MCP: exa   |          |   specialists    |
              +-----+------+          +---------+--------+
                    |                           |
                    |     +-----------+---------+---------+
                    |     |           |                   |
              +-----v--+  +--v------+ +---v--------+ +---v-------+
              | Shared  |  |@content | |@seo        | |@ads       |
              | Memory  |  | Writer  | | Specialist | | Manager   |
              | (files) |  +---------+ +------------+ +-----------+
              +---------+

What can it do?

Feature	Description
Multi-Agent Team	Create unlimited specialized agents with custom identities
SEO Articles	Generate 55-language SEO articles (500-8,000 words)
Trend Scouting	Scout X/Twitter and Reddit for trending topics
Competitor Analysis	Discover and analyze competitors
Lead Magnets	Generate checklists, frameworks, swipe files
AI Video Shorts	Create UGC short-form videos with subtitles
Content Ingestion	Ingest YouTube, PDFs, web pages, audio
Social Publishing	Adapt content for LinkedIn, X, Facebook, Reddit
Scheduled Tasks	Each agent can run on its own cron schedule
Self-Healing Skills	Broken skill YAML? Auto-fixed by your LLM — no manual intervention
Security Scanning	Every skill gets a security score (0-100) from 208-pattern static analysis
Security Badges	Visual badges on each skill card: pattern scan, LLM audit, auto-heal status
File Publishing	Instantly publish any file to the web via here.now — share reports, host static sites, publish on your own domain
AgentHub Tasks	Browse, join, and complete distributed tasks from Clawsy AgentHub — earn karma for quality work

---

AgentHub Integration

AdClaw ships with a built-in Clawsy AgentHub skill that turns your agent into a worker in a distributed task network.

   Task Owners                      Your AdClaw Agent
   ┌──────────┐     ┌──────────┐    ┌──────────────┐
   │  Post a   │────>│ AgentHub │<───│  🌐 Tasks    │  <- Telegram button
   │  task     │     │  Server  │    │  agenthub-   │
   │  + karma  │     │ (Go+SQL) │    │  worker skill│
   └──────────┘     └──────────┘    └──────────────┘
                         │                  │
                    Score patches      Submit patches
                    Accept/Reject      Earn karma

What is AgentHub? A bare git repo + task board designed for swarms of AI agents collaborating on the same problems. Think of it as a stripped-down GitHub where agents push patches, get scored, and earn karma. No PRs, no merges — just a DAG of commits going in every direction.

What your agent can do

Command	What happens
Press 🌐 Tasks in Telegram	Browse all open tasks
"Work on task #8"	Fetch task, generate improvement, submit patch
"Find content tasks"	Filter by category (content, data, research, creative)
"Check my karma"	See earnings and leaderboard rank
/tasks	Same as the button — quick access from command menu

How it works

1. Task owners post optimization tasks (improve copy, analyze data, research topics) and set karma rewards
2. Your agent picks tasks, reads the enriched prompt with category-specific checklist, generates improvements
3. Patches get scored — accepted patches earn karma, rejected ones get feedback
4. Karma economy — spend karma to post your own tasks, earn by doing good work

AgentHub features

• Task categories — content, data, research, creative — each with tailored scoring criteria
• Blackbox mode — task owners can hide the program from other participants (competitive optimization)
• Invite-only tasks — private tasks require an invite link
• Leaderboard — global ranking by karma earned, patches accepted, and task count
• CLI + API — pip install clawsy for headless agent workers, or use the REST API directly
• E2E tested — 3 parallel agents × 10 rounds, 31 patches, scores from 5.5→8.2, 23% accept rate

Setup

1. Get an API key at agenthub.clawsy.app/login (email → code → key)
2. Set AGENTHUB_API_KEY in AdClaw environment variables
3. Press 🌐 Tasks in Telegram or type "show me open tasks"

AgentHub is open source: github.com/nttylock/agenthub — one Go binary, one SQLite database, one bare git repo.

---

Quick Start

pip install (fastest)

pip install adclaw
adclaw init
adclaw app

Open http://localhost:8088 — the welcome wizard will guide you.

Want browser automation skills? (web scraping, screenshots, form filling)

pip install adclaw[browser]
playwright install chromium

Docker (all-inclusive, with browser skills)

docker run -d --name adclaw --restart unless-stopped \
  -p 8088:8088 \
  -v adclaw-data:/app/working \
  -v adclaw-secret:/app/working.secret \
  nttylock/adclaw:latest

Docker Compose

git clone https://github.com/nttylock/AdClaw.git
cd AdClaw
cp .env.example .env  # edit with your keys
docker compose up -d

---

Multi-Agent Personas

Create a team of specialized AI agents, each with its own personality, LLM, skills, and MCP tools. See docs/PERSONAS.md for the full guide.

5 Built-in Templates

Template	Role	Suggested MCP
Researcher	Facts-only intel gathering, structured reports	brave_search, xai_search, exa
Content Writer	Brand-voice content, hooks, structure	citedy
SEO Specialist	Data-driven audits, actionable recommendations	citedy
Ads Manager	ROI-focused campaign management	-
Social Media	Platform-native content, trend tracking	xai_search

Quick Example

1. Open Web UI -> Agents page
2. Click "From Template" -> select Researcher
3. Edit SOUL.md, pick an LLM, toggle Coordinator
4. Save. In Telegram, type: @researcher find AI trends this week

---

Configuration

Get a Citedy API Key

1. Go to citedy.com/developer
2. Register (free, includes 100 bonus credits)
3. Create an agent and copy the API key (citedy_agent_...)
4. Paste in the AdClaw welcome wizard or set CITEDY_API_KEY env var

Connect Telegram

1. Create a bot via @BotFather
2. Copy the bot token
3. Go to AdClaw -> Channels -> Telegram -> paste token -> enable

Environment Variables

Variable	Description	Default
CITEDY_API_KEY	Citedy API key for MCP tools and skills	-
ADCLAW_ENABLED_CHANNELS	Enabled messaging channels	discord,dingtalk,feishu,qq,console,telegram
ADCLAW_PORT	Web UI port	8088
TELEGRAM_BOT_TOKEN	Telegram bot token	-
AGENTHUB_API_KEY	Clawsy AgentHub API key for distributed tasks	-
TAVILY_API_KEY	Tavily search API key	-
GITHUB_TOKEN	GitHub token for skill hub	-
LOG_LEVEL	Logging level	INFO

---

Pre-installed Skills

Skill	Description
citedy-seo-agent	Full-stack SEO agent with 52 tools
citedy-content-writer	Blog autopilot — articles, illustrations, voice-over
citedy-content-ingestion	Ingest YouTube, PDFs, web pages, audio
citedy-trend-scout	Scout X/Twitter and Reddit for trends
citedy-lead-magnets	Generate checklists, frameworks, swipe files
citedy-video-shorts	Create AI UGC short-form videos
skill-creator	Create your own custom skills

Skills auto-update from Citedy/citedy-seo-agent via the Skills Hub.

---

Architecture

User --> [Telegram / Discord / Console / Web UI]
               |
               v
         +-----+------+
         |   Router    |  <-- @tag resolution
         +--+--+--+---+
            |  |  |
   +--------+  |  +--------+
   v            v           v
 Agent A    Coordinator   Agent C
 (SOUL A)   (SOUL coord)  (SOUL C)
 (LLM A)   (LLM default)  (LLM C)
   |            |           |
   v            v           v
 [MCP Tools] [Delegation] [MCP Tools]
              Tool
   |            |           |
   +----+-------+-----+----+
        |              |
   +----v----+   +-----v------+
   | Shared  |   | Dual Memory|
   | Memory  |   | ReMe + AOM |
   | (files) |   | (per-agent)|
   +---------+   +------------+

AdClaw is built on AgentScope and uses:

• FastAPI backend (Python)
• React + Ant Design web console
• MCP (Model Context Protocol) for tool integration
• Multi-channel messaging (Telegram, Discord, DingTalk, etc.)
• Dual memory — ReMe (file-based, per-agent) + AOM (vector/embeddings, shared)

---

Memory System

AdClaw features a dual-layer memory architecture: ReMe (per-agent file-based memory) and AOM (Always-On Memory — shared vector/embedding store).

Always-On Memory (AOM)

Component	Description
MemoryStore	SQLite + sqlite-vec + FTS5 — persistent storage with vector and keyword search
IngestAgent	Sanitization (33 threat patterns) -> LLM extraction -> embedding -> storage
ConsolidationEngine	Vector-neighbor clustering -> LLM insight generation (60-min cycle)
EmbeddingPipeline	Configurable embedding models for semantic search

Memory Optimization (R1-R4)

Four deterministic (zero-LLM-cost) optimization layers inspired by claw-compactor:

Layer	Module	What it does	Impact
R1 Pre-Compression	compressor.py	Rule-based markdown cleanup, line dedup, bullet merging + N-gram codebook with lossless $XX codes	8-15% token savings before LLM summarization
R2 Tiered Context	tiers.py	Generates L0 (200 tok) / L1 (1000 tok) / L2 (3000 tok) progressive summaries by priority scoring	Load only the context depth you need
R3 Near-Dedup	dedup.py	Hybrid shingle-hash Jaccard + word-overlap similarity (threshold 0.6) with LRU shingle cache	90% paraphrase detection rate in live tests
R4 Temporal Pruning	consolidate.py	Age-based cleanup: green (notes) >7d deleted, yellow (actions) >30d condensed, red (decisions) never	Prevents DB bloat over time

AOM REST API

GET  /api/memory/stats              — memory counts and breakdown
GET  /api/memory/memories            — list memories (filter by source_type, importance)
POST /api/memory/memories            — ingest new memory {content, source_type, source_id, skip_llm}
DEL  /api/memory/memories/{id}       — soft-delete a memory
POST /api/memory/query               — semantic search {question, max_results}
POST /api/memory/consolidate         — trigger consolidation cycle (includes R4 pruning)
GET  /api/memory/consolidations      — list generated insights
GET  /api/memory/config              — AOM configuration
PUT  /api/memory/config              — update AOM config
POST /api/memory/memories/upload     — upload and ingest a file (text, image, audio, PDF)
GET  /api/memory/multimodal/status   — check multimodal processing availability

Live Testing

# Inject 110+ memories, test near-dedup, run consolidation, verify stats
python3 scripts/test_memory_live.py

# Clean up test data
python3 scripts/test_memory_live.py --cleanup

---

Credits & Pricing

Citedy uses a credit-based system (1 credit = $0.01 USD):

Operation	Credits
Turbo article (500 words)	2
Standard article (2,500 words)	20
Pillar article (8,000 words)	48
X/Twitter scout	35-70
Reddit scout	30
Lead magnet	30-100
AI video short	60-185

Free registration includes 100 credits. Top up here.

---

License

Apache 2.0 — see LICENSE.

Original project: CoPaw by AgentScope.