ECHELON — self-learning consumer-spending intelligence engine

A quantitative-analyst / actuary for global consumer spending. It answers, in one pass: how does the world spend money in/around a space, where are the best opportunities, and how would you actually capture each one? — and it gets smarter every run because it saves and reuses everything it learns.

Two brains under the MKUltra program. MOCKINGBIRD mines customer language to decide what to say; ECHELON mines macro spend + live demand to decide what market to play in and how to enter it. ECHELON picks the market; MOCKINGBIRD picks the message.

Honest scope (read this first)

ECHELON is decision support, not a crystal ball. What's real:

• Macro spend is synthesised from authoritative datasets I know + refreshed by

web search (BLS Consumer Expenditure Survey, Census, Eurostat/COICOP, Statista, eMarketer, McKinsey / Nielsen / Bain / BCG). Every material figure is cited to a source + year; stale figures are flagged.

• Live demand is pulled bottom-up via paid Apify actors (engine/demand.py) —

search-interest direction, active-ad saturation, marketplace best-sellers, TikTok momentum. This is real ground-truth on the specific niche, but it costs per run, and the field maps are confirmed by --dry-run + a small run first.

• The score (engine/score.py) is a transparent weighted model — it makes

trade-offs explicit and comparisons consistent; it does not predict revenue.

• Self-learning = a growing file-based knowledge base it reads before and

writes after every run (knowledge/). It is NOT model-weight learning — it's persistent memory, the same mechanism that lets it compound honestly.

• Autonomy: runs on demand and can scan proactively locally. True

runs-while-the-PC-is-off scheduling is blocked because cloud agents can't read the local .env keys — note this; don't pretend otherwise.

It replaces a gut feeling with a sourced, scored, demand-validated, channel-mapped read. That's the promise — no more.

The brain (read before reasoning)

Reference frameworks — MKUltra/Echelon-research/reference/:

• spending-taxonomy.md — the global consumer-spend atlas (where money goes).
• spend-drivers.md — why people spend (10 drivers + life-stage triggers + elasticity).
• decision-makers.md — who controls the money (gender / cohort / role).
• channels.md — the channel-activation playbook brain.

Knowledge base (the memory) — MKUltra/Echelon-research/knowledge/:

• index.md — map of everything known (regenerate with kb.py index).
• learnings.md — cross-niche priors it has noticed. Read this every run and

apply as a starting lean.

• markets/, niches/, signals/, sources/, inputs/ — accumulated research.
• See knowledge/README.md for the schema + _templates/.

The pipeline

0. SCOPE     lock query: space, geo, lens, constraints
1. RECALL    kb.py recall "<niche>"  — what do we already know? what's stale?      (code)
2. ATLAS     locate in the taxonomy + apply learnings.md priors                    (reference)
3. RESEARCH  size/growth/drivers/decision-makers, cited; reuse fresh KB, fill gaps (knowledge + web)
4. DEMAND    demand.py — live signals on the niche (optional, paid)                (code/Apify)
5. CANDIDATES enumerate concrete niches + score every factor 0-10 from the evidence
6. SCORE     score.py ranks them deterministically                                 (code)
7. PLAYBOOK  per top niche: decision-maker + channel-activation plan + economics
8. SAVE      write markets/niches/inputs entries; append any new learning          (compounding)
9. REPORT    write the dated report; reindex (kb.py index); surface the verdict

Steps 1, 4, 6, 9 are code (the dumb pipes). Everything else is Claude reasoning over the brain + evidence. Never skip RECALL and SAVE — they are what make it learn.

Step 0 — Scope

Pin space / geo / lens (business-agnostic vs anchored) / constraints. Default global with a US-EU-AU lens. Fold constraints into factor weights (e.g. low capital → raise the capital weight via a weights override).

Step 1 — Recall (mandatory)

python3 "MKUltra/Echelon-research/engine/kb.py" recall "<niche or space>"

Reuse anything fresh as the starting point; only research the gaps. Refresh anything flagged STALE (>120 days) before trusting it. Also read learnings.md.

Step 2 — Atlas

Locate the space in spending-taxonomy.md; inherit its decision-maker / driver / recurrence / margin / ad-risk priors; layer the relevant learnings.md patterns.

Step 3 — Research (cited)

Establish, with sources + year: market size + growth, dominant driver(s) + elasticity, decision-maker (gender/cohort/role/life-stage trigger), margin + AOV + repeat, competitive intensity, regulatory/ad risk. In an interactive session use built-in web search; for headless/autonomous runs use:

python3 "MKUltra/Echelon-research/engine/research.py" "<query>" --save <slug>

Never invent a number — if unknown, say so and score conservatively.

Step 4 — Demand (live, optional, paid)

For a specific-product viability question, or to validate a shortlist, pull live signals. Always `--dry-run` first ($0), then a small `--limit` run. Flag the spend before running.

python3 "MKUltra/Echelon-research/engine/demand.py" --niche "<niche>" --geo US --dry-run
python3 "MKUltra/Echelon-research/engine/demand.py" --niche "<niche>" --geo US --sources google_trends,meta_ads --limit 30

Map results: search direction → demand_capturability/momentum; ad saturation → competition; marketplace presence → market_size sanity check.

Step 5 — Candidates + factor scoring

Enumerate concrete niches (not "pets" but "senior-dog joint-health supplements, subscription"). Score all 11 factors 0-10 (rubric below) from Step 2-4 evidence; write a JSON matching sample-opportunities.json.

Factor rubric (0 = worst, 10 = best for the operator):

Step 6 — Score (code)

python3 "MKUltra/Echelon-research/engine/score.py" <candidates>.json        # ranked table
python3 "MKUltra/Echelon-research/engine/score.py" <candidates>.json -o ranked.json --json

A/B/C/D tiers; pass a weights override in the input to reflect constraints.

Step 7 — Playbook (per top 3-5)

Using channels.md: decision-maker to target; demand type (existing/latent/owned) → lead channel; per-channel role + fit + why; validate→scale→capture-owned→compound sequence; illustrative CAC-vs-margin sanity check (label it a model, hand real unit economics to /ecom-data-analyst); ad-risk warning if reg_risk is low.

Step 8 — Save (mandatory — this is the learning)

• Write/update knowledge/markets/<cat>.md and knowledge/niches/<niche>.md from

the templates, with last_updated, sources, and (niches) score/tier/verdict.

• If Will proposed the product, log knowledge/inputs/<date>-<slug>.md with the verdict.
• If a pattern showed up across niches, append a dated line to knowledge/learnings.md.

Step 9 — Report + reindex

Save to MKUltra/Echelon-research/outputs/[YYYY-MM-DD]-[query-slug]/: report.md, opportunities.json, ranked.json. Then:

python3 "MKUltra/Echelon-research/engine/kb.py" index

Display the ranking table + verdict in chat. Slugs lowercase-hyphen; reruns increment.

Modes

• Viability check (e.g. "is men's quarter-zips worth selling?"): scope one niche →

recall → research → DEMAND (live) → score it alone → verdict + playbook → save.

• Opportunity scan ("find me the best niches in pets"): enumerate many candidates →

score → deep-dive the top 3-5 → save all.

• Proactive scan (self-directed): walk the taxonomy / a chosen space, score

candidates from KB + light research, surface anything that newly clears Tier A/B, save. Local-only (see autonomy caveat).

Report structure (template)

# ECHELON — <space>, <geo>  (<date>)
## Scope            space / geo / lens / constraints / sources
## What it already knew   (recall hits reused)
## How the world spends here   (atlas slice + priors)
## Live demand read   (demand.py signals, if pulled)
## Opportunity ranking   [score.py table] + read on the spread
## Top opportunities (top 3-5): why it scores · the spend (sourced) · the buyer · channel playbook · the catch
## Verdict   the one or two to pursue + the single next action
## Saved   what was written to the knowledge base this run

Relationship to the stack

• MOCKINGBIRD (sibling under the MKUltra program) → mines the chosen audience's language into creative briefs.
• /ecom-data-analyst → real unit economics / BEROAS / cashflow on a chosen niche.
• /copy-writing, /static-ads, /virality → execute + rank the creative.

ECHELON is the front of the funnel: decide where to play, with evidence, before anything else fires.