MOCKINGBIRD — voice-of-customer → creative-brief engine

The message brain of the MKUltra program. ECHELON picks the market; MOCKINGBIRD picks the message. It scrapes where customers actually talk, mines their real language, and turns it into creative briefs that tell you what to say — grounded in evidence, not gut feel or mood boards.

Lives in MKUltra/Mockingbird-messaging/. Sibling to /echelon.

Honest scope (read first)

• Builds evidence-based briefs from real customer language — ranks angles by

resonance (how strongly + how often an insight shows up in the corpus).

• It does not predict ad performance before launch (nobody can). It hands

rendered creatives to /virality for a hook-strength read.

• The scrape is paid (Apify, per actor run). Always smoke one source at a small

--limit before a wide pull.

• Synthesis is grounded: do NOT invent — every claim must trace to the corpus.

The pipeline

0. RECALL     (code)         kb.py recall "<brand>" — reuse known intelligence + proven angles
1. RESEARCH   (code, paid)   targets/<t>.json --Apify--> outputs/<t>/corpus.jsonl  (gaps/stale only)
2. SYNTHESIZE (Claude)       corpus.jsonl + prompts/synthesize.md --> customer-intelligence.md
3. BRIEF      (Claude)       customer-intelligence.md + prompts/brief.md --> briefs/*.json + _ranking.md
4. SAVE       (compounding)  write knowledge/{intelligence,language-bank,angles}; append learnings; kb.py index
5. RENDER     (static-templates)  feed a brief to the static-template engine
6. RANK       (/virality)    rank variants; write the score back into the angle library

Steps 0 and 1 plus the kb index are code (dumb pipes). Never skip RECALL (step 0) and SAVE (step 4) — they make it self-learning; see knowledge/README.md. Steps 2–3 are Claude reasoning over the corpus. 4–5 are existing tools.

Step 0 — Target

A target pins brand / category / audience / competitors + per-source config (search terms or URLs). targets/ExampleBrand-watches.json is the first one. For a new brand, create targets/<slug>.json in the same shape before running.

Step 0.5 — Recall (mandatory, the self-learning entry point)

python3 "MKUltra/Mockingbird-messaging/engine/kb.py" recall "<brand or audience>"

Reuse fresh intelligence + proven angles as priors; only scrape the gaps. Re-scrape anything flagged STALE (>120 days). Also read knowledge/learnings.md. If the audience is cold (nothing known), scrape from scratch.

Step 3.5 — Save & learn (mandatory, the compounding step)

After briefing, write back what was learned so the next run starts ahead (templates in knowledge/_templates/):

• knowledge/intelligence/<brand>.md — accumulated customer intelligence.
• knowledge/language-bank/<brand>.md — the customer's verbatim words/phrases.
• knowledge/angles/<brand>.md — the angle library (resonance + template; add the

/virality score once a rendered variant is ranked, so future briefs start from proven winners).

• If a pattern repeats across brands, append a dated line to knowledge/learnings.md.
• Reindex: python3 "MKUltra/Mockingbird-messaging/engine/kb.py" index.

Step 1 — Research (the scrape, paid)

Run from inside the tool folder so the engine package is importable:

cd "MKUltra/Mockingbird-messaging"
# smoke ONE source small first:
python3 -m engine research --target ExampleBrand-watches --sources reddit --limit 50
# then widen:
python3 -m engine research --target ExampleBrand-watches --sources reddit,trustpilot,youtube --limit 200

Sources (engine/sources.py): reddit (search-term driven, richest), trustpilot (competitor company URLs), youtube (review/competitor video URLs). Token resolves from APIFY_API_TOKEN / APIFY_TOKEN in the project-root .env. Output → outputs/<target>/corpus.jsonl (one normalized snippet per line).

Step 2 — Synthesize (Claude)

Read outputs/<target>/corpus.jsonl + prompts/synthesize.md, write outputs/<target>/customer-intelligence.md — grounded analysis of awareness level, pains, desires, insecurities, objections, triggers, a language bank (the customer's own words), and segments. Every claim cites the corpus; invent nothing.

Step 3 — Brief (Claude)

Read customer-intelligence.md + prompts/brief.md, write outputs/<target>/briefs/<slug>.json per angle (insight, evidence, awareness_level, template, content) plus briefs/_ranking.md ranking angles by resonance (strength × frequency in the corpus). Brief JSON must be valid input for the static-template engine. Templates: strikethrough, listicle, annotated_callout, pov_overlay.

Step 4–5 — Render + rank

Feed a brief to the static-template engine to render on-brand creatives (Meta/Google sizes), then rank the variants with /virality for a hook-strength read.

Relationship to the stack

• `/echelon` (sibling under MKUltra) → picks the market first; MOCKINGBIRD then

mines that audience's language into the message.

• Static-template engine → renders the briefs.
• `/virality` → ranks the rendered variants.
• `/copy-writing` → can draft long-form copy off the same intelligence.

MOCKINGBIRD decides what to say; the rest render and rank it. Research → intelligence → brief → render → rank.