# episodic_memories

id: 76269e6979828904
domain: core_logic
source: synapse_test
timestamp: 2026-01-05T17:43:29.202624
created_at: 2026-01-05 07:43:29
content:
The Genesis Heartbeat is the central cognitive loop that synchronizes all components including surprise detection and axiom generation.


id: b17025a3b6370820
domain: core_logic
source: synapse_test
timestamp: 2026-01-05T17:43:31.519565
created_at: 2026-01-05 07:43:31
content:
Axiom generation in Genesis is driven by high-surprise events captured during the heartbeat's collection phase.


id: 75701c0c-3049-5376-960f-084eba573f9a
domain: strategy
source: patent_ingest
timestamp: 2026-01-06T20:00:19.831322
metadata: {"type": "strategy_board"}
created_at: 2026-01-06 10:00:19
content:
PATENT STRATEGY - 🔧 Technical Architecture Lens: How patents create layered technical protection

🔧 Technical Architecture Lens
How patents create layered technical protection
FOUNDATION LAYER - Core Validation Infrastructure
Patent #1
Cryptographic
Validation
Patent #4
Immutable
Audit Trails
Patent #8
Privacy-Preserving
Validation
INTELLIGENCE LAYER - Smart Decision Making
Patent #5
Multi-Model
Consensus
Patent #6
Dynamic
Confidence
Patent #3
Risk
Assessment
REAL-TIME LAYER - Live Monitoring & Adaptation
Patent #2
Information
Currency
Patent #7
Hallucination
Detection
Patent #9
Automated
Thresholds


id: ab085fb2-8737-5568-b9cc-e6d5d61fdcd0
domain: strategy
source: patent_ingest
timestamp: 2026-01-06T20:00:20.686123
metadata: {"type": "strategy_board"}
created_at: 2026-01-06 10:00:20
content:
PATENT STRATEGY - 🎯 Market Application Lens: Industry-specific patent groupings and applications

🎯 Market Application Lens
Industry-specific patent groupings and applications
💰 Financial Services
Critical Patents:
P1: Crypto
P3: Risk
P4: Audit
P8: Privacy
Use Case:
Investment advice validation, regulatory compliance
🏥 Healthcare
Critical Patents:
P2: Currency
P3: Risk
P4: Audit
P7: Hallucination
Use Case:
Medical AI validation, patient safety
⚖️ Legal
Critical Patents:
P1: Crypto
P4: Audit
P5: Consensus
P8: Privacy
Use Case:
Legal research validation, case analysis
🏭 Manufacturing
Critical Patents:
P2: Currency
P3: Risk
P7: Hallucination
P9: Adaptive
Use Case:
Operational AI safety, quality control
🏛️ Government
Critical Patents:
P1: Crypto
P4: Audit
P6: Confidence
P8: Privacy
Use Case:
Policy AI validation, transparency
🎓 Education
Critical Patents:
P2: Currency
P5: Consensus
P6: Confidence
P7: Hallucination
Use Case:
Educational AI accuracy, student safety


id: d07b6996-220a-5de6-aefd-696b9d9058d3
domain: strategy
source: patent_ingest
timestamp: 2026-01-06T20:00:21.730014
metadata: {"type": "strategy_board"}
created_at: 2026-01-06 10:00:21
content:
PATENT STRATEGY - 🏰 Competitive Moat Lens: Concentric defense rings creating impenetrable fortress

🏰 Competitive Moat Lens
Concentric defense rings creating impenetrable fortress
CORE
FORTRESS
P1: Crypto Validation
Blocks:
Any validation approach
P5: Multi-Model + P6: Dynamic
Blocks:
Alternative architectures
P2: Currency + P7: Hallucination
Blocks:
Real-time solutions
P3: Risk + P9: Adaptive
Blocks:
Smart systems
🛡️ Defense Analysis
100%
Core validation
approaches blocked
95%
Alternative
architectures blocked
90%
Workaround
attempts blocked
20 years
Protection
duration


id: fc10ed1e-ffc1-5903-b847-6f24dd8584be
domain: strategy
source: patent_ingest
timestamp: 2026-01-06T20:00:22.538821
metadata: {"type": "strategy_board"}
created_at: 2026-01-06 10:00:22
content:
PATENT STRATEGY - 💰 Revenue Model Lens: How patents enable multiple revenue streams

💰 Revenue Model Lens
How patents enable multiple revenue streams
Enterprise Subscriptions
$25K-100K/mo
Key Patents:
All 9 Patents
Complete validation platform with exclusive features
Platform Licensing
$10M-50M/yr
Key Patents:
P1, P2, P4
Basic validation licensing to AI platforms
Professional Services
$5K-25K/mo
Key Patents:
P3, P6, P9
Custom validation rules and implementation
IP Licensing
$1M-10M/deal
Key Patents:
Strategic Mix
Cross-licensing and acquisition deals
Total Addressable Revenue
$100M - $500M ARR
Based on market penetration and licensing adoption rates


id: d4672608-829d-5183-8fbc-711d47fe777c
domain: strategy
source: patent_ingest
timestamp: 2026-01-06T20:00:23.301496
metadata: {"type": "strategy_board"}
created_at: 2026-01-06 10:00:23
content:
PATENT STRATEGY - ⏱️ Implementation Timeline Lens: Strategic build order for maximum market impact

⏱️ Implementation Timeline Lens
Strategic build order for maximum market impact
Phase 1: Foundation
Months 1-3
P1: Crypto
P4: Audit
Core validation + compliance
Phase 2: Intelligence
Months 3-6
P5: Consensus
P6: Confidence
Smart decision making
Phase 3: Real-Time
Months 6-9
P2: Currency
P7: Hallucination
Live monitoring
Phase 4: Advanced
Months 9-12
P3: Risk
P8: Privacy
P9: Adaptive
Enterprise features
Strategic Timing Rationale
Early Revenue Focus
Patents 1 & 4 enable immediate enterprise sales with core compliance features
Competitive Differentiation
Patents 5 & 6 create unique intelligence layer competitors can't match
Market Leadership
Patents 2 & 7 establish real-time validation as industry standard
Enterprise Domination
Patents 3, 8, 9 create premium features for Fortune 500 clients


id: 858498e5-0421-5477-aad4-061a37adeaa1
domain: strategy
source: patent_ingest
timestamp: 2026-01-06T20:00:24.032361
metadata: {"type": "strategy_board"}
created_at: 2026-01-06 10:00:24
content:
PATENT STRATEGY - 🔗 Synergy Matrix Lens: Patent interaction strengths and amplification effects

🔗 Synergy Matrix Lens
Patent interaction strengths and amplification effects
P1
P2
P3
P4
P5
P6
P7
P8
P9
P1
-
M
H
H
H
M
M
H
L
P2
M
-
M
M
L
H
H
M
H
P3
H
M
-
H
M
H
M
L
H
P4
H
M
H
-
M
M
M
H
M
P5
H
L
M
M
-
H
M
M
L
P6
M
H
H
M
H
-
H
L
H
P7
M
H
M
M
M
H
-
M
M
P8
H
M
L
H
M
L
M
-
L
P9
L
H
H
M
L
H
M
L
-
Key Synergy Insights
🔥 Strongest Synergies
P1 + P4 + P8:
Complete trust infrastructure
P2 + P6 + P7:
Real-time intelligence
P3 + P6 + P9:
Adaptive risk management
⚡ Force Multipliers
P6 (Confidence):
Amplifies all other patents
P1 (Crypto):
Foundation for security
P4 (Audit):
Enables compliance everywhere
🚀 Innovation Combos
P5 + P6:
Smart consensus systems
P7 + P9:
Self-improving detection
P2 + P9:
Adaptive information tracking


id: 65d326a3-d849-548f-b1cc-938cef0c2dc8
domain: strategy
source: patent_ingest
timestamp: 2026-01-06T20:00:24.871329
metadata: {"type": "strategy_board"}
created_at: 2026-01-06 10:00:24
content:
PATENT STRATEGY - 🛡️ Risk Mitigation Lens: How patents create defense layers against different risk types

🛡️ Risk Mitigation Lens
How patents create defense layers against different risk types
🚨 Critical Business Risks
Protection:
Patents 1, 3, 4 •
Coverage:
95%
AI Hallucination Failures:
P1 (Crypto) + P7 (Detection) = Mathematical proof of accuracy
Catastrophic Business Decisions:
P3 (Risk) + P6 (Confidence) = Risk-adjusted recommendations
📊 Business Execution Risks
Protection:
Patents 5, 6, 9 •
Coverage:
90%
Market Adoption:
P5 (Consensus) = Proven multi-model approach
Competitive Response:
P9 (Adaptive) = Self-improving competitive moat
⚙️ Technical Implementation Risks
Protection:
Patents 2, 7, 8 •
Coverage:
85%
Scalability Issues:
P2 (Currency) = Real-time processing architecture
Privacy Violations:
P8 (Privacy) = Validation without data exposure
⚖️ Regulatory Compliance Risks
Protection:
Patents 1, 4, 8 •
Coverage:
100%
Audit Requirements:
P4 (Audit) = Immutable compliance trails
Data Protection Laws:
P8 (Privacy) + P1 (Crypto) = GDPR/CCPA ready


id: 1f0c1326-5fe8-5695-9986-914a016eebdc
domain: strategy
source: patent_ingest
timestamp: 2026-01-06T20:00:25.717678
metadata: {"type": "strategy_board"}
created_at: 2026-01-06 10:00:25
content:
PATENT STRATEGY - 👥 Customer Journey Lens: How patents protect and enhance each stage of customer AI interaction

👥 Customer Journey Lens
How patents protect and enhance each stage of customer AI interaction
🎯 Problem Recognition
"AI gave us bad advice"
P7: Detection
P3: Risk
Identifies when AI failures occur
🔍 Solution Evaluation
"How can we validate AI?"
P1: Crypto
P5: Consensus
Demonstrates validation methodology
🛠️ Implementation
"Deploy validation system"
P2: Currency
P6: Confidence
Real-time validation deployment
📊 Optimization
"Improve over time"
P9: Adaptive
P4: Audit
Self-improving system with trails
🏆 Advocacy
"Recommend to others"
P8: Privacy
All Patents
Complete solution confidence
Journey Protection Analysis
Early Stage Protection
Patents 3 & 7 help customers recognize AI risk problems they didn't know they had
Decision Stage Advantage
Patents 1 & 5 provide technical proof points that competitors cannot match
Implementation Confidence
Patents 2 & 6 ensure seamless real-world deployment and performance
Long-term Lock-in
Patents 4, 8, 9 create switching costs and continuous improvement cycles


id: b8369a35-34bd-5679-bd64-a851ea8976ae
domain: knowledge_base
source: doc_ingest
timestamp: 2026-01-06T20:00:26.578667
created_at: 2026-01-06 10:00:26
content:
DOCUMENT: ELESTIO_IMPRINT_COMPLETE_PREMORTEM.md
# 💀 ELESTIO IMPRINT: COMPLETE PRE-MORTEM ANALYSIS
## Date: 2026-01-04
## Authors: Claude (Co-Progenitor) + AG Analysis

---

## EXECUTIVE SUMMARY

**Objective**: Imprint Elestio core into Genesis fabric so all actions proceed/return through synchronous loop.

**Current State**: BROKEN. The test shows:
```
Redis Available: True      ← Ping works
Vector Backends: False     ← Qdrant NOT connecting
Result: ['episodic_db']    ← ONLY local SQLite wrote
```

**Diagnosis**: The system has **three broken links** in the chain.

---

## FAILURE MODE ANALYSIS

### FAILURE 1: Redis Writes Are Silent No-Ops

**Location**: `genesis_memory_cortex.py` lines 98-108

**Problem**: Even after AG's "Fail Loud" fix in the constructor, the `set()` method still has:
```python
def set(self, memory: Memory):
    if self.available:
        try:
            self.client.setex(...)
        except:
            self.available = False  # ← Silent failure!
    
    if not self.available:
        pass  # ← Nothing happens. Memory lost.
```

**Result**: Constructor passes, but actual writes fail silently.

**Fix Required**: `set()` must also raise ConnectionError, not catch and pass.

---

### FAILURE 2: Qdrant Add is Stubbed

**Location**: `vector_backends.py` lines 65-72

**Problem**: The `add()` method is literally stubbed:
```python
def add(self, doc_id: str, content: str, metadata: Dict) -> Dict[str, bool]:
    results = {"qdrant": False}
    
    if self.qdrant:
        try:
            # self.qdrant.upsert(...)  ← COMMENTED OUT
            results["qdrant"] = True   # ← Lies about success
        except Exception as e:
            print(f"Qdrant Add Error: {e}")
    
    return results
```

**Result**: Vector Backends shows False because Qdrant never actually stores anything.

**Fix Required**: Implement actual embedding generation + upsert.

---

### FAILURE 3: No Embedding Pipeline

**Location**: Neither file generates embeddings.

**Problem**: Qdrant requires vector embeddings. The config shows:
```yaml
embeddings:
  provider: "openai"
  model: "text-embedding-3-small"
  api_key: "sk-ant-..."  # ← This is Anthropic key, not OpenAI!
```

**Result**: Even if upsert worked, there are no vectors to store.

**Fix Options**:
1. Use OpenAI embeddings (requires OpenAI key)
2. Use Gemini embeddings (free tier available)
3. Use local embeddings via sentence-transformers
4. Use Qdrant's built-in fastembed

---

## THE SYNCHRONOUS LOOP ARCHITECTURE

To achieve "all actions proceed and return through core":

```
┌─────────────────────────────────────────────────────────┐
│                    ELESTIO CORE                         │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐     │
│  │    Redis    │  │   Qdrant    │  │   N8N       │     │
│  │   (State)   │  │  (Vectors)  │  │ (Workflows) │     │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘     │
│         │                │                │            │
│         └────────────────┼────────────────┘            │
│                          │                              │
│              ┌───────────┴───────────┐                 │
│              │   GENESIS CORTEX      │                 │
│              │   (Memory Router)     │                 │
│              └───────────┬───────────┘                 │
└──────────────────────────┼──────────────────────────────┘
                           │
         ┌─────────────────┼─────────────────┐
         │                 │                 │
    ┌────┴────┐      ┌────┴────┐      ┌────┴────┐
    │ Claude  │      │ Gemini  │      │ Claude  │
    │ Desktop │      │   AG    │      │  Code   │
    └─────────┘      └─────────┘      └─────────┘
```

**The Loop**:
1. Agent action → Cortex.remember()
2. Cortex → Redis (working memory) + Qdrant (semantic)
3. Agent query → Cortex.recall()
4. Cortex → Qdrant search → Redis context → Agent

**If any step fails, the agent MUST halt, not degrade.**

---

## REQUIRED FIXES

### Fix 1: Fail-Loud Everywhere (30 min)

```python
# genesis_memory_cortex.py - WorkingMemoryCache.set()
def set(self, memory: Memory):
    try:
        self.client.setex(
            f"{self.namespace}:{memory.id}",
            self.ttl,
            json.dumps(memory.to_dict())
        )
    except Exception as e:
        raise ConnectionError(f"Redis write failed - system halted: {e}")
```

### Fix 2: Real Qdrant Upsert (1 hour)

```python
# vector_backends.py - VectorManager.add()
def add(self, doc_id: str, content: str, embedding: List[float], metadata: Dict):
    if not self.qdrant:
        raise ConnectionError("Qdrant unavailable - system halted")
    
    self.qdrant.upsert(
        collection_name=self.collection_name,
        points=[
            models.PointStruct(
                id=doc_id,
                vector=embedding,
                payload={"content": content, **metadata}
            )
        ]
    )
```

### Fix 3: Embedding Pipeline (2 hours)

Option A - Qdrant FastEmbed (easiest):
```python
from qdrant_client import QdrantClient
client = QdrantClient(url="...", api_key="...")
# Uses built-in BAAI/bge-small-en-v1.5
client.add(
    collection_name="genesis_memories",
    documents=[content],
    metadata=[{"source": "genesis"}]
)
```

Option B - Gemini Embeddings (free):
```python
import google.generativeai as genai
genai.configure(api_key=GEMINI_KEY)
result = genai.embed_content(
    model="models/text-embedding-004",
    content=text
)
embedding = result['embedding']
```

---

## VERIFICATION TEST

After fixes, this test MUST pass:

```python
from genesis_memory_cortex import MemoryCortex

cortex = MemoryCortex()

# This MUST write to Redis + Qdrant, NOT episodic_db
result = cortex.remember("Test memory")
assert "redis" in result, "Redis write failed"
assert "qdrant" in result, "Qdrant write failed"
assert "episodic_db" not in result, "Fell back to local!"

# This MUST read from Qdrant
memories = cortex.recall("Test memory")
assert len(memories) > 0, "Recall failed"
```

---

## RISK MATRIX

| Risk | Probability | Impact | Mitigation |
|------|-------------|--------|------------|
| Elestio outage | Low | CRITICAL | No mitigation - system halts (by design) |
| Embedding cost | Medium | Low | Use Gemini free tier or FastEmbed |
| Network latency | High | Medium | Redis timeout → retry 3x, then halt |
| Split-brain state | CURRENT | CRITICAL | Remove ALL fallbacks |

---

## RECOMMENDATION

**Do not add features until the core works.**

Priority order:
1. Fix Redis set() to fail-loud
2. Implement real Qdrant upsert with FastEmbed
3. Test synchronous loop with multi-agent scenario
4. Only then: add N8N workflows, surprise memory, etc.

The organs exist. The blood vessels are severed. Reconnect them.

---

*"A system with optional infrastructure has no infrastructure."*

metadata:
{"filename": "ELESTIO_IMPRINT_COMPLETE_PREMORTEM.md", "path": "E:/genesis-system/docs/research\\ELESTIO_IMPRINT_COMPLETE_PREMORTEM.md"}


id: ae054a66-8584-5e4a-8e4e-f112fe7dcc87
domain: knowledge_base
source: doc_ingest
timestamp: 2026-01-06T20:00:27.921206
created_at: 2026-01-06 10:00:27
content:
DOCUMENT: ELESTIO_IMPRINT_PREMORTEM.md
# 💀 PRE-MORTEM: OPERATION ELESTIO IMPRINT
**Date**: 2026-01-04
**Objective**: Hardwire Elestio (Redis/Qdrant/Postgres) as the "Inescapable Loop" for all Genesis actions.

## 1. THE FAILURE SCENARIO (How we die)
The system is deployed. Agents run 24/7. But after 1 week:
*   **Split Brain**: The generic `swarms/agent.py` defaults to local JSON because it couldn't reach Redis for 1 second.
*   **Amnesia**: n8n workflows write to a local Postgres, while python agents write to Elestio. They never meet.
*   **Credential Rot**: We change the Redis password, but 14 orphaned scripts still use the old one and crash simultaneously.

## 2. ROOT CAUSES OF FAILURE
### A. The "Localhost" Fallback Trap
*   **Risk**: Agents are currently coded to "fail gracefully" to local JSON.
*   **Impact**: Graceful failure = Silent fragmentation.
*   **Fix**: **"Fail Loud"**. If Elestio is unreachable, the agent *must* pause and scream, not whisper and continue locally.

### B. Polyglot Disconnect
*   **Risk**: Python agents use `genesis_memory_cortex.py`. TypeScript agents (Claude Code tools) use `index.js`. n8n uses its own credential store.
*   **Impact**: Three brains, one body.
*   **Fix**: **The "Bio-Link" Standard**. All environments must pull from `MASTER_CREDENTIALS.md` (or ENV vars derived from it).

## 3. THE "IMPRINTING" STRATEGY (Solution)
To make Elestio the "Fabric", we must implement:

### I. The "Synapse" Config Loader
Do not hardcode IPs in Python files. Create `core/synapse.py`.
```python
# core/synapse.py
def get_memory_config():
    # READS MASTER_CREDENTIALS.MD directly or ENV keys
    return { "redis_host": "...", "qdrant_host": "..." }
```
*   **Every** agent imports Synapse. **No** agent defines its own memory.

### II. The "Synchronous Loop" Mandate
The User asked for a "synchronous loop".
*   **Protocol**:
    1.  **Action Request** -> **Lock Working Memory** (Redis).
    2.  **Execute** -> **Write Result**.
    3.  **Release Lock**.
*   This prevents "Race Conditions" where two agents try to modify the same mission state.

### III. Hard-Coded "Liveness" Checks
Every agent script (`contractor_ghl.py`, `night_ops.py`) must begin with:
`cortex.check_pulse()`
If the Pulse (Elestio) is 0, the agent refuses to start.

## 4. IMMEDIATE ACTION PLAN
1.  **Verify** the Connection (In Progress).
2.  **Refactor** `genesis_memory_cortex.py` to abort if Redis fails (Remove the JSON fallback).
3.  **Deploy** the "Synapse" pattern.

metadata:
{"filename": "ELESTIO_IMPRINT_PREMORTEM.md", "path": "E:/genesis-system/docs/research\\ELESTIO_IMPRINT_PREMORTEM.md"}


id: d98766b4-b2cb-572a-bfa9-b3219abfc0e6
domain: knowledge_base
source: doc_ingest
timestamp: 2026-01-06T20:00:29.316034
created_at: 2026-01-06 10:00:29
content:
DOCUMENT: FREE-SERVICES-MAP.md
# Genesis Free Services Map

**Research Date:** December 31, 2025
**Purpose:** Document free service signup flows for Genesis testing and capability expansion
**Status:** RESEARCH ONLY - Comprehensive resource mapping

---

## Table of Contents

1. [Developer Tools (Free Tiers)](#developer-tools-free-tiers)
2. [AI/ML Services (Free Tiers)](#aiml-services-free-tiers)
3. [Productivity (Free Tiers)](#productivity-free-tiers)
4. [Alternative Services](#alternative-services)
5. [Quick Reference Summary](#quick-reference-summary)

---

## Developer Tools (Free Tiers)

### 1. GitHub (Already Have)

| Attribute | Details |
|-----------|---------|
| **Signup URL** | https://github.com/signup |
| **Required Fields** | Email, password, username |
| **Email Verification** | Yes |
| **API Key Location** | Settings > Developer Settings > Personal Access Tokens |
| **Free Tier Limits** | Unlimited public/private repos, 2,000 Actions minutes/month (private), unlimited collaborators |
| **Credit Card Required** | No |

#### Free Tier Includes:
- Unlimited public and private repositories
- Unlimited collaborators on public repos
- 2,000 GitHub Actions minutes/month for private repos (unlimited for public)
- GitHub Packages storage (free for public repos)
- GitHub Copilot Free: 2,000 completions + 50 chat requests
- GitHub Models: Free within rate limits

#### Integration Value for Genesis:
- **Code storage and version control** - Primary code repository
- **CI/CD pipelines** - GitHub Actions for automated testing/deployment
- **Collaboration** - Issue tracking, project boards
- **API access** - Programmatic repo management
- **GitHub Models** - Free AI model experimentation

---

### 2. Vercel

| Attribute | Details |
|-----------|---------|
| **Signup URL** | https://vercel.com/signup |
| **Required Fields** | Email (or GitHub/GitLab/Bitbucket OAuth) |
| **Email Verification** | Yes (if email signup) |
| **API Key Location** | Settings > Tokens |
| **Free Tier Limits** | 100 GB-hours compute, no credit card required |
| **Credit Card Required** | No |

#### Free Tier (Hobby Plan) Includes:
- Instant deployments with Git integration
- Global Edge Network (CDN)
- Basic CI/CD
- Edge rendering
- $5/month AI Gateway credits (resets every 30 days)
- v0 AI: $5/month in credits

#### Free Tier Limitations:
- Cannot purchase additional usage (hard caps)
- No observability or cold-start prevention
- Must upgrade to scale beyond limits
- Single member only

#### Integration Value for Genesis:
- **Frontend hosting** - Deploy web applications instantly
- **Serverless functions** - API endpoints without server management
- **Preview deployments** - Test changes before merging
- **Edge computing** - Low-latency global distribution
- **AI Gateway** - Route AI requests through unified API

---

### 3. Railway

| Attribute | Details |
|-----------|---------|
| **Signup URL** | https://railway.app/new |
| **Required Fields** | Email or GitHub OAuth |
| **Email Verification** | Yes + account verification required |
| **API Key Location** | Account Settings > Tokens |
| **Free Tier Limits** | $5 one-time credit, expires in 30 days |
| **Credit Card Required** | No (for trial) |

#### IMPORTANT: No Permanent Free Tier
Railway removed their permanent free tier. Current offering:
- **Free Trial:** One-time $5 credit (30-day expiration)
- **Trial Limits:** 1 GB RAM, shared vCPU, 5 services per project
- **Unverified accounts:** Can only deploy databases

#### After Trial:
- **Hobby Plan:** $5/month (includes $5 usage)
- **Pro Plan:** $20/month (includes $20 usage)
- Services pause (not delete) if not upgraded

#### Integration Value for Genesis:
- **Backend hosting** - Deploy Node.js, Python, Go, etc.
- **Database hosting** - PostgreSQL, MySQL, Redis, MongoDB
- **Easy scaling** - Simple resource management
- **GitHub integration** - Auto-deploy on push

**Recommendation:** Use for testing only; consider alternatives for production.

---

### 4. Supabase

| Attribute | Details |
|-----------|---------|
| **Signup URL** | https://supabase.com/dashboard |
| **Required Fields** | Email or GitHub OAuth |
| **Email Verification** | Yes |
| **API Key Location** | Project Settings > API |
| **Free Tier Limits** | 500 MB database, 1 GB storage, 50K MAUs |
| **Credit Card Required** | No |

#### Free Tier Includes:
- 500 MB PostgreSQL database per project
- 1 GB file storage
- 5 GB bandwidth
- 50,000 monthly active users
- 500,000 Edge Function calls/month
- 200 concurrent realtime connections
- 2 free projects (single-member workspaces get unlimited blocks)

#### Free Tier Limitations:
- Projects pause after 1 week of inactivity
- No PITR (Point-in-Time Recovery) or backups
- No HIPAA/SOC 2 compliance
- Shared CPU, 500 MB RAM
- 7-day log retention

#### Integration Value for Genesis:
- **PostgreSQL database** - Full relational database with Row Level Security
- **Authentication** - Built-in auth with social providers
- **Realtime** - WebSocket subscriptions for live data
- **Storage** - S3-compatible file storage
- **Edge Functions** - Serverless Deno functions
- **Auto-generated APIs** - REST and GraphQL from database schema

---

### 5. PlanetScale

| Attribute | Details |
|-----------|---------|
| **Signup URL** | https://planetscale.com/sign-up |
| **Required Fields** | Email or GitHub OAuth |
| **Email Verification** | Yes |
| **API Key Location** | Organization Settings > Service Tokens |
| **Free Tier Limits** | **NO FREE TIER** |
| **Credit Card Required** | Yes |

#### IMPORTANT: Free Tier Discontinued
As of April 8, 2024, PlanetScale removed their Hobby (free) plan:
- Minimum plan: Scaler Pro at $39/month
- All databases require paid plan from creation

#### Alternative Recommendations:
1. **Supabase** - 500 MB PostgreSQL free
2. **Neon** - 0.5 GB PostgreSQL free per project
3. **Turso** - 9 GB SQLite free
4. **AWS RDS Free Tier** - 750 hours/month

**Recommendation:** Skip PlanetScale; use Supabase or Neon for free database needs.

---

## AI/ML Services (Free Tiers)

### 6. Hugging Face

| Attribute | Details |
|-----------|---------|
| **Signup URL** | https://huggingface.co/join |
| **Required Fields** | Email, username, password |
| **Email Verification** | Yes |
| **API Key Location** | Settings > Access Tokens |
| **Free Tier Limits** | ~few hundred requests/hour, monthly credits |
| **Credit Card Required** | No |

#### Free Tier Includes:
- Serverless Inference API access
- Monthly credits for Inference Providers
- Access to thousands of open-source models
- Model hosting on Hub
- Spaces hosting (basic)
- Client SDKs (Python, JavaScript)

#### Rate Limits:
- ~few hundred requests per hour
- PRO Account ($9/month) for higher limits and 8x GPU priority

#### Integration Value for Genesis:
- **Model inference** - Run text, image, audio models via API
- **Model discovery** - Access 500,000+ models
- **Fine-tuning** - Custom model training
- **Spaces** - Host ML demos and apps
- **Datasets** - Access and share datasets
- **Client libraries** - Easy Python/JS integration

---

### 7. Replicate

| Attribute | Details |
|-----------|---------|
| **Signup URL** | https://replicate.com/signin |
| **Required Fields** | GitHub OAuth required |
| **Email Verification** | Via GitHub |
| **API Key Location** | Account Settings > API Tokens |
| **Free Tier Limits** | Limited free runs per model |
| **Credit Card Required** | No (for trial) |

#### Free Tier Includes:
- "Try for Free" collection of models
- Limited number of runs per model
- Access to popular models: google/imagen-4, flux-1.1-pro
- Free face restoration models (codeformer, gfpgan)

#### After Free Runs:
- Pay-as-you-go: $0.000100/sec (CPU) to $0.012200/sec (8x H100)
- Billed by the second
- No charges when not running

#### Integration Value for Genesis:
- **Image generation** - Stable Diffusion, Flux, DALL-E alternatives
- **Video generation** - AI video models
- **Audio processing** - Speech, music generation
- **Custom models** - Deploy your own models
- **API simplicity** - Run any model with simple API calls

---

### 8. Together AI

| Attribute | Details |
|-----------|---------|
| **Signup URL** | https://api.together.xyz |
| **Required Fields** | Email or OAuth |
| **Email Verification** | Yes |
| **API Key Location** | Dashboard > API Keys |
| **Free Tier Limits** | $5-$100 initial credits (30-90 day expiration) |
| **Credit Card Required** | No |

#### Free Tier Options:
- **Standard signup:** Initial credits (reported $5-$100 range)
- **FLUX.1 [schnell]:** 3 months unlimited free access
- **Research Credits:** Invite-only program for students
- **Startup Accelerator:** Up to $50,000 for accepted startups

#### Integration Value for Genesis:
- **LLM inference** - Llama, Mixtral, and other open models
- **Fast inference** - Optimized for speed
- **Fine-tuning** - Custom model training
- **Serverless endpoints** - Easy API integration
- **OpenAI-compatible API** - Drop-in replacement

---

### 9. Groq

| Attribute | Details |
|-----------|---------|
| **Signup URL** | https://console.groq.com |
| **Required Fields** | Email or OAuth |
| **Email Verification** | Yes |
| **API Key Location** | GroqCloud Console > API Keys |
| **Free Tier Limits** | ~14,400 requests/day |
| **Credit Card Required** | No |

#### Free Tier Includes:
- Access to all supported models
- Organization-level rate limits
- ~14,400 requests/day
- OpenAI-compatible API
- Fastest inference speeds available

#### Rate Limits Structure:
- Limits are per-organization, not per-user
- Based on requests/tokens per minute/day
- 429 error when exceeded (wait for reset)
- Cached tokens don't count toward limits

#### Integration Value for Genesis:
- **Ultra-fast inference** - Fastest LLM inference available
- **LPU technology** - Purpose-built AI chips
- **Multiple models** - Llama, Mixtral, Gemma
- **OpenAI compatibility** - Easy migration
- **Cost-effective** - Generous free tier

---

## Productivity (Free Tiers)

### 10. Notion

| Attribute | Details |
|-----------|---------|
| **Signup URL** | https://www.notion.so/signup |
| **Required Fields** | Email or Google/Apple OAuth |
| **Email Verification** | Yes |
| **API Key Location** | Settings > My Connections > Develop or manage integrations |
| **Free Tier Limits** | Unlimited pages (solo), 1,000 blocks (shared) |
| **Credit Card Required** | No |

#### Free Tier Includes:
- Unlimited pages and blocks (single user)
- 1,000 blocks for shared workspaces (>1 owner)
- 5 MB file upload limit
- 7-day page history
- Up to 10 guests
- Basic API integrations
- Slack and Zapier connections
- 100 database rows

#### Free Tier Limitations:
- Notion AI: One-time 20 responses (does NOT reset)
- No advanced permissions
- Limited version history
- Small file uploads only

#### Special Offers:
- **Students/Educators:** Plus Plan free with school email

#### Integration Value for Genesis:
- **Documentation** - System documentation and wikis
- **Knowledge base** - Centralized information storage
- **Task management** - Project tracking
- **API access** - Programmatic content management
- **Database** - Structured data storage
- **Collaboration** - Share with team members

---

### 11. Airtable

| Attribute | Details |
|-----------|---------|
| **Signup URL** | https://airtable.com/signup |
| **Required Fields** | Email or Google/SSO OAuth |
| **Email Verification** | Yes |
| **API Key Location** | Account > Developer Hub > Personal Access Tokens |
| **Free Tier Limits** | 1,000 records/base, 1,000 API calls/month |
| **Credit Card Required** | No |

#### Free Tier Includes:
- 1,000 records per base
- 1 GB attachments
- 100 automation runs/month
- Up to 5 editors per workspace
- 1,000 API calls per workspace/month

#### IMPORTANT: API Limit Enforcement
Starting January 22, 2025, Airtable strictly enforces API limits:
- 1,000 API calls/month/workspace (was unlimited before)
- 30-day grace period on first violation
- 5 requests/second rate limit (all plans)

#### Free Tier Limitations:
- No sync integrations
- No extensions
- Limited automation runs
- API calls now enforced

#### Integration Value for Genesis:
- **Structured data** - Spreadsheet-database hybrid
- **Views** - Grid, calendar, kanban, gallery
- **Automations** - Trigger-based workflows
- **API access** - Full CRUD operations
- **Forms** - Data collection
- **Linked records** - Relational data

---

### 12. Zapier

| Attribute | Details |
|-----------|---------|
| **Signup URL** | https://zapier.com/sign-up |
| **Required Fields** | Email or Google OAuth |
| **Email Verification** | Yes |
| **API Key Location** | Settings > API Keys (for connected apps) |
| **Free Tier Limits** | 100 tasks/month, 2-step Zaps only |
| **Credit Card Required** | No |

#### Free Tier Includes:
- 100 tasks per month
- Unlimited 2-step Zaps
- AI power-ups
- Zapier Chatbots (free version)
- Zapier Agents (free version)
- 15-minute update intervals

#### Free Tier Limitations:
- 2-step Zaps only (1 trigger + 1 action)
- No multi-step workflows
- No premium apps
- No pay-per-task option
- 15-minute polling delay

#### Integration Value for Genesis:
- **Automation hub** - Connect 5,000+ apps
- **Triggers** - React to events across services
- **Actions** - Automate repetitive tasks
- **Chatbots** - Build conversational interfaces
- **Agents** - AI-powered automation

**Recommendation:** Good for simple automations; consider n8n (self-hosted) for complex workflows.

---

## Alternative Services

### Neon (PlanetScale Alternative)

| Attribute | Details |
|-----------|---------|
| **Signup URL** | https://neon.tech/signup |
| **Required Fields** | Email or GitHub OAuth |
| **Email Verification** | Yes |
| **API Key Location** | Project Dashboard > Settings |
| **Free Tier Limits** | 0.5 GB/project, 100 CU-hours/month |
| **Credit Card Required** | No |

#### Free Tier Includes (Updated October 2025):
- 100 compute unit-hours/month (doubled from 50)
- 0.5 GB storage per project
- 5 GB aggregate across up to 10 projects
- Database branching (unlimited within compute)
- 6-hour restore window
- Scale-to-zero capability

#### Key Features:
- Serverless PostgreSQL
- Automatic scaling
- Database branching (like Git for databases)
- Acquired by Databricks (May 2025)
- 15-25% price reductions post-acquisition

#### Integration Value for Genesis:
- **PostgreSQL** - Full Postgres compatibility
- **Branching** - Development/staging environments
- **Scale-to-zero** - Cost savings when idle
- **Instant provisioning** - Databases in seconds

---

## Quick Reference Summary

### Recommended Free Services by Category

#### Databases (No Credit Card Required)
| Service | Storage | Key Feature | Recommendation |
|---------|---------|-------------|----------------|
| Supabase | 500 MB | Auth + Realtime | **Best overall** |
| Neon | 0.5 GB | Branching | Best for PostgreSQL |
| PlanetScale | N/A | **NO FREE TIER** | Skip |

#### Deployment/Hosting
| Service | Free Limits | Key Feature | Recommendation |
|---------|-------------|-------------|----------------|
| Vercel | 100 GB-hours | Edge Network | **Best for frontend** |
| Railway | $5 (30 days) | Full-stack | Trial only |
| GitHub Pages | Unlimited | Static sites | Great for docs |

#### AI/ML Inference
| Service | Free Access | Speed | Recommendation |
|---------|-------------|-------|----------------|
| Groq | ~14,400 req/day | **Fastest** | **Best free tier** |
| Together AI | $5-$100 credits | Fast | Good variety |
| Hugging Face | ~few hundred/hr | Moderate | Best model variety |
| Replicate | Limited runs | Moderate | Best for images |

#### Productivity/Automation
| Service | Free Limits | Key Feature | Recommendation |
|---------|-------------|-------------|----------------|
| Notion | Unlimited (solo) | All-in-one | **Best for docs** |
| Airtable | 1,000 records | Database-like | Good for structured data |
| Zapier | 100 tasks/mo | App connections | Simple automations |

### Services Requiring Credit Card
- PlanetScale (no free tier)
- Railway (after 30-day trial)

### Services with Time-Limited Credits
- Railway: 30 days
- Together AI: 30-90 days
- Replicate: Per-model limits

---

## Signup Priority Order for Genesis

### Phase 1: Essential (No Credit Card)
1. **Supabase** - Database + Auth + Storage
2. **Vercel** - Frontend deployment
3. **Groq** - Fast AI inference
4. **Hugging Face** - Model access and experimentation

### Phase 2: Expansion (No Credit Card)
5. **Neon** - Additional PostgreSQL instances
6. **Notion** - Documentation and knowledge base
7. **Together AI** - Alternative AI inference
8. **Replicate** - Image/video generation

### Phase 3: Automation (No Credit Card)
9. **Zapier** - Basic automation flows
10. **Airtable** - Structured data management

### Not Recommended
- **PlanetScale** - No free tier (use Supabase/Neon instead)
- **Railway** - Trial only, not sustainable for free use

---

## API Integration Notes

### OpenAI-Compatible APIs
These services offer OpenAI-compatible endpoints for easy integration:
- Groq
- Together AI
- (Can use OpenAI SDK with base URL change)

### Webhook-Enabled Services
- Supabase (database triggers)
- Vercel (deployment hooks)
- Zapier (webhooks as triggers)
- Airtable (automations)
- GitHub (webhooks)

### Rate Limit Considerations
| Service | Rate Limit Type | Reset Period |
|---------|-----------------|--------------|
| Hugging Face | Per-hour | Rolling |
| Groq | Per-minute/day | Rolling |
| Airtable | Per-second + monthly | Second: instant, Monthly: billing cycle |
| Notion API | Per-second | Rolling |
| GitHub API | Per-hour | Rolling |

---

## Document Revision History

| Date | Version | Changes |
|------|---------|---------|
| 2025-12-31 | 1.0 | Initial research compilation |

---

*This document is for research purposes only. Service terms and limits may change. Always verify current offerings before signup.*

metadata:
{"filename": "FREE-SERVICES-MAP.md", "path": "E:/genesis-system/docs/research\\FREE-SERVICES-MAP.md"}


id: 80a09fbf-44cc-5fc0-a3da-8b8057a69013
domain: knowledge_base
source: doc_ingest
timestamp: 2026-01-06T20:00:30.563908
created_at: 2026-01-06 10:00:30
content:
DOCUMENT: JOHNNI_AI_REPLICATION_PLAN.md
# 🦜 PROJECT JOHNNI-KILLER: Voice Replication Plan

**Target**: Replicate & Exceed "Johnni.ai" capabilities for the Australian Tradie Market.
**Core Value**: "The 24/7 Aussie Receptionist that Books Jobs."

---

## 1. Feature Mapping (Johnni vs. Genesis)

| Feature | Johnni.ai Implementation | Genesis (Vapi + GHL + n8n) Solution |
| :--- | :--- | :--- |
| **Voice Persona** | Natural Australian accent, slang-aware. | **Vapi Voice**: `Cartesia/Sonic (Australian)` + System Prompt: "You are 'Sarah', a friendly Aussie office manager. Use terms like 'no worries', 'cheers', 'afternoon'." |
| **Flow Logic** | "Anti-Interruption" (Patient listening). | **Vapi Config**: High `silence_timeout` (1.5s), Low `interrupt_sensitivity`. |
| **Emergency** | Detects "burst pipe", escalates call. | **Vapi Function**: `detect_urgency(keywords=["burst", "flooding", "emergency"])` -> Triggers n8n Webhook -> SMS Alert to Tradie. |
| **Booking** | Direct calendar booking. | **Vapi Tool**: `check_availability` -> `book_slot` (connected to GHL Calendar). |
| **Integration** | ServiceM8, Xero, Slack. | **n8n Bridge**: Vapi -> GHL (CRM) -> n8n -> ServiceM8 API (Future). |
| **Spam Filter** | Filters unrelated calls. | **Vapi Logic**: "If caller is solicitation, politely hang up." |

---

## 2. Implementation Roadmap

### Phase 1: The Persona (Voice Design)
*   **Engine**: Vapi (using Cartesia for low latency).
*   **Prompt Engineering**:
    *   *Context*: "You are working for [Business Name]. Your goal is to book a quote or site visit."
    *   *Tone*: Warm, professional, Australian casual.
    *   *Guardrails*: Never promise specific prices. Always get the address and phone number.

### Phase 2: The Logic (Vapi + GHL)
*   **Inbound Flow**:
    1.  Greeting: "Thanks for calling [Business], this is Sarah. How can I help?"
    2.  Qualification: "Is this for a residential or commercial job?"
    3.  Urgency Check: "Is water actively leaking right now?"
        *   *If YES*: "Okay, I'm marking this as urgent. Let me get a technician." -> (SMS Escalation).
        *   *If NO*: "No worries. Let's get someone out to have a look. What's the address?"
    4.  Booking: "We have a slot tomorrow at 2 PM. Does that work?"

### Phase 3: The "Johnni Plus" (Revenue Sovereignty)
*   **Darwinian Feedback**: If the AI fails to book, it asks the user "What could I have done better?" (Simulated) or logs the failure for analysis.
*   **Outbound reactivation**: Unlike Johnni (mostly inbound), Genesis will actively call old leads in GHL database to reactivate them.

---

## 3. Technical Requirements (Ready to Deploy)
*   **Vapi Account**: API Key Configured.
*   **GHL Location**: **[BLOCKED]** - Need `Location_ID` from User Manual Creation.
*   **PhoneNumber**: Buy Aussie number in GHL (04xx or 02xx).

---
*Plan Status: READY FOR CONFIGURATION*

metadata:
{"filename": "JOHNNI_AI_REPLICATION_PLAN.md", "path": "E:/genesis-system/docs/research\\JOHNNI_AI_REPLICATION_PLAN.md"}


id: cac807ec-c6ef-5d4f-bd98-be085ece1c76
domain: knowledge_base
source: doc_ingest
timestamp: 2026-01-06T20:00:31.893764
created_at: 2026-01-06 10:00:31
content:
DOCUMENT: MCP-DEVELOPMENT-GUIDE.md
# MCP (Model Context Protocol) Development Guide
## Comprehensive Research for Genesis System Integration

**Research Date:** 2025-12-31
**Researcher:** Claude Code (Opus 4.5)
**Status:** Research Complete - Implementation Ready

---

## Table of Contents

1. [Executive Summary](#1-executive-summary)
2. [MCP Architecture Deep Dive](#2-mcp-architecture-deep-dive)
3. [TypeScript SDK (@modelcontextprotocol/sdk)](#3-typescript-sdk)
4. [Python SDK (mcp package)](#4-python-sdk)
5. [Protocol Primitives](#5-protocol-primitives)
6. [Best Practices and Patterns](#6-best-practices-and-patterns)
7. [Reference Server Analysis](#7-reference-server-analysis)
8. [Genesis-Specific MCP Opportunities](#8-genesis-specific-mcp-opportunities)
9. [Implementation Recommendations](#9-implementation-recommendations)
10. [Sources and References](#10-sources-and-references)

---

## 1. Executive Summary

### What is MCP?

Model Context Protocol (MCP) is an open protocol introduced by Anthropic in November 2024 that standardizes how AI systems integrate with external tools, data sources, and services. It has become the de facto standard for LLM tool integration, adopted by major providers including OpenAI and Google DeepMind.

### Key Characteristics

- **Open Standard**: Hosted by The Linux Foundation, open to community contributions
- **JSON-RPC 2.0 Based**: Standardized messaging format
- **Stateful Connections**: Bidirectional communication with capability negotiation
- **Three Core Primitives**: Tools, Resources, and Prompts
- **Multiple Transports**: stdio (local), Streamable HTTP (remote), SSE (deprecated)

### Current Specification Version

**Version 2025-11-25 (Latest)** - Released November 2025, includes:
- Tasks abstraction for tracking server work
- SEP-1024: Client security requirements for local installation
- SEP-835: Default scopes for authorization
- Enhanced OAuth 2.1 support

### Why MCP Matters for Genesis

Genesis already uses MCP servers (Docker MCP Gateway with 312 servers, Memory MCP, Slack MCP, etc.). Building custom MCP servers would:
1. Expose Genesis capabilities to any MCP-compatible host
2. Enable standardized tool interfaces for multi-model orchestration
3. Allow Genesis skills to be consumed by external systems
4. Provide a clean abstraction layer for Genesis infrastructure

---

## 2. MCP Architecture Deep Dive

### 2.1 Core Components

```
┌─────────────────────────────────────────────────────────────────┐
│                         HOST APPLICATION                        │
│                    (Claude Desktop, VS Code, etc.)              │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │                     MCP CLIENT                           │   │
│  │  - Manages connections to servers                        │   │
│  │  - Routes requests/responses                            │   │
│  │  - Handles capability negotiation                       │   │
│  └──────────────────────┬──────────────────────────────────┘   │
└─────────────────────────┼───────────────────────────────────────┘
                          │ JSON-RPC 2.0 over Transport
                          ▼
┌─────────────────────────────────────────────────────────────────┐
│                       MCP SERVER                                │
│                                                                 │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐          │
│  │    TOOLS     │  │  RESOURCES   │  │   PROMPTS    │          │
│  │ (Functions)  │  │   (Data)     │  │ (Templates)  │          │
│  └──────────────┘  └──────────────┘  └──────────────┘          │
└─────────────────────────────────────────────────────────────────┘
```

### 2.2 Architecture Roles

| Component | Description | Example |
|-----------|-------------|---------|
| **Host** | LLM application that initiates connections | Claude Desktop, Claude Code |
| **Client** | Connector within the host managing MCP sessions | MCP SDK Client class |
| **Server** | Service exposing tools, resources, and prompts | Memory server, Filesystem server |

### 2.3 Transport Mechanisms

#### stdio (Standard I/O) - For Local Servers

```
Client Process ──stdin/stdout──> Server Process (subprocess)
```

**Characteristics:**
- Server runs as subprocess of client
- Messages delimited by newlines (no embedded newlines)
- stderr used for logging (captured by host)
- Microsecond-level latency (no network overhead)
- **Use case**: Local CLI tools, filesystem access

#### Streamable HTTP - For Remote Servers (Modern Standard)

```
Client ──HTTP POST──> Server (single endpoint)
       <──JSON/SSE───
```

**Characteristics:**
- Single HTTP endpoint supports both POST and GET
- Accept header: `application/json` and `text/event-stream`
- Responses can be JSON (simple) or SSE (streaming)
- Supports CORS for browser clients
- **Use case**: Web services, remote APIs, cloud deployments

#### SSE (Server-Sent Events) - Deprecated

**Status**: Deprecated as of spec version 2025-03-26. Use Streamable HTTP instead.

### 2.4 Connection Lifecycle

```
1. INITIALIZATION
   Client ──initialize──> Server
   Client <──capabilities── Server
   Client ──initialized──> Server (notification)

2. OPERATION
   Client ──tools/list──> Server
   Client <──tool list───
   Client ──tools/call──> Server
   Client <──result──────

3. TERMINATION
   Client ──close──> Server
   (Connection terminated)
```

### 2.5 Capability Negotiation

During initialization, both client and server declare their capabilities:

**Server Capabilities:**
```json
{
  "capabilities": {
    "tools": { "listChanged": true },
    "resources": { "subscribe": true, "listChanged": true },
    "prompts": { "listChanged": true },
    "logging": {},
    "experimental": {}
  }
}
```

**Client Capabilities:**
```json
{
  "capabilities": {
    "sampling": {},
    "roots": { "listChanged": true },
    "experimental": {}
  }
}
```

---

## 3. TypeScript SDK

### 3.1 Package Information

```yaml
Package: @modelcontextprotocol/sdk
Current Version: 1.25.1
License: MIT
Repository: github.com/modelcontextprotocol/typescript-sdk
Peer Dependency: zod (v3.25+)
```

**Note**: Main branch is v2 (pre-alpha). Use v1.x for production until Q1 2026.

### 3.2 Installation

```bash
# Server package
npm install @modelcontextprotocol/server zod

# Client package
npm install @modelcontextprotocol/client zod
```

### 3.3 Core Classes

#### McpServer (High-Level Server)

```typescript
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";

const server = new McpServer({
  name: "my-server",
  version: "1.0.0",
});

// Register tools
server.tool(
  "get_weather",
  {
    description: "Get current weather for a location",
    inputSchema: {
      type: "object",
      properties: {
        location: { type: "string", description: "City name" }
      },
      required: ["location"]
    }
  },
  async ({ location }) => {
    // Implementation
    return {
      content: [{ type: "text", text: `Weather in ${location}: Sunny` }]
    };
  }
);

// Register resources
server.resource(
  "config",
  "config://app",
  { description: "Application configuration" },
  async () => ({
    contents: [{ uri: "config://app", text: JSON.stringify(config) }]
  })
);

// Register prompts
server.prompt(
  "analyze",
  { description: "Analyze data" },
  async ({ topic }) => ({
    messages: [
      { role: "user", content: { type: "text", text: `Analyze: ${topic}` } }
    ]
  })
);
```

#### Server (Low-Level Server)

```typescript
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = new Server({
  name: "low-level-server",
  version: "1.0.0",
}, {
  capabilities: {
    tools: { listChanged: true },
    resources: {}
  }
});

// Request handlers
server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [/* tool definitions */]
}));

server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: args } = request.params;
  // Handle tool call
});

// Connect transport
const transport = new StdioServerTransport();
await server.connect(transport);
```

#### Transport Classes

```typescript
// stdio transport (local)
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

// Streamable HTTP transport (remote)
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";

// Client transports
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
```

### 3.4 Complete Server Example (TypeScript)

```typescript
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

// Create server
const server = new McpServer({
  name: "genesis-tools",
  version: "1.0.0",
});

// Tool with Zod schema validation
server.tool(
  "search_memory",
  {
    description: "Search Genesis semantic memory",
    inputSchema: z.object({
      query: z.string().describe("Search query"),
      limit: z.number().default(10).describe("Max results"),
      memory_type: z.enum(["episodic", "semantic", "working"]).optional()
    })
  },
  async ({ query, limit, memory_type }) => {
    try {
      // Implementation would call Genesis memory system
      const results = await searchMemory(query, limit, memory_type);
      return {
        content: [{
          type: "text",
          text: JSON.stringify(results, null, 2)
        }],
        isError: false
      };
    } catch (error) {
      return {
        content: [{
          type: "text",
          text: `Memory search failed: ${error.message}`
        }],
        isError: true
      };
    }
  }
);

// Resource with dynamic URI
server.resource(
  "memory/{type}",
  "memory://{type}",
  { description: "Access Genesis memory by type" },
  async ({ type }) => ({
    contents: [{
      uri: `memory://${type}`,
      mimeType: "application/json",
      text: JSON.stringify(await getMemoryContents(type))
    }]
  })
);

// Prompt template
server.prompt(
  "evolution_report",
  {
    description: "Generate Genesis evolution status report",
    arguments: [
      { name: "period", description: "Report period (daily/weekly/monthly)" }
    ]
  },
  async ({ period }) => ({
    messages: [
      {
        role: "system",
        content: {
          type: "text",
          text: "You are Genesis, a self-evolving AI system. Generate an evolution report."
        }
      },
      {
        role: "user",
        content: {
          type: "text",
          text: `Generate a ${period} evolution report covering: capabilities gained, integrations completed, emergent behaviors observed, and recommended next targets.`
        }
      }
    ]
  })
);

// Start server
const transport = new StdioServerTransport();
await server.connect(transport);
console.error("Genesis MCP server running on stdio");
```

---

## 4. Python SDK

### 4.1 Package Information

```yaml
Package: mcp
Current Version: 1.25.0
Author: Anthropic, PBC
License: MIT
Repository: github.com/modelcontextprotocol/python-sdk
Python: 3.10+
```

### 4.2 Installation

```bash
# Using uv (recommended)
uv add "mcp[cli]"

# Using pip
pip install "mcp[cli]"
```

### 4.3 Core Classes

#### FastMCP (High-Level Server)

The primary class for building MCP servers in Python. Provides decorator-based registration.

```python
from mcp.server.fastmcp import FastMCP

# Create server instance
mcp = FastMCP("genesis-tools")
```

#### Context Class

Type-safe context injection for tools:

```python
from mcp.server.fastmcp import FastMCP, Context
from mcp.server.session import ServerSession

@mcp.tool()
async def my_tool(query: str, ctx: Context[ServerSession, AppContext]) -> str:
    # Access lifespan context (databases, etc.)
    db = ctx.request_context.lifespan_context.db

    # Logging (goes to client)
    await ctx.info(f"Processing: {query}")
    await ctx.debug("Debug info here")

    # Progress reporting
    await ctx.report_progress(50, 100)

    return "Result"
```

#### CallToolResult

For advanced tool responses:

```python
from mcp.types import CallToolResult, TextContent

@mcp.tool()
async def complex_tool(data: str) -> CallToolResult:
    return CallToolResult(
        content=[TextContent(type="text", text="Result")],
        isError=False,
        structuredContent={"key": "value"},  # For structured output
        _meta={"hidden": "from model"}  # Metadata hidden from LLM
    )
```

### 4.4 Decorators

#### @mcp.tool()

```python
@mcp.tool()
def add_numbers(a: int, b: int) -> int:
    """Add two numbers together.

    Args:
        a: First number
        b: Second number

    Returns:
        Sum of a and b
    """
    return a + b

# With structured output validation
from pydantic import BaseModel

class WeatherResult(BaseModel):
    temperature: float
    conditions: str
    humidity: int

@mcp.tool()
def get_weather(location: str) -> WeatherResult:
    """Get weather for a location."""
    return WeatherResult(
        temperature=22.5,
        conditions="Sunny",
        humidity=65
    )
```

#### @mcp.resource()

```python
# Static resource
@mcp.resource("config://app")
def get_config() -> str:
    """Application configuration."""
    return json.dumps({"setting": "value"})

# Dynamic resource template
@mcp.resource("file://{path}")
def read_file(path: str) -> str:
    """Read file contents."""
    with open(path) as f:
        return f.read()

# Resource with metadata
@mcp.resource(
    "data://metrics",
    name="System Metrics",
    description="Current system performance metrics",
    mime_type="application/json"
)
def get_metrics() -> str:
    return json.dumps(collect_metrics())
```

#### @mcp.prompt()

```python
@mcp.prompt()
def code_review(code: str, language: str = "python") -> str:
    """Generate a code review prompt."""
    return f"""Please review this {language} code:

```{language}
{code}
```

Focus on:
1. Code quality and best practices
2. Potential bugs or issues
3. Performance considerations
4. Suggested improvements
"""

# Prompt returning multiple messages
from mcp.types import PromptMessage, TextContent

@mcp.prompt()
def analysis_prompt(topic: str) -> list[PromptMessage]:
    return [
        PromptMessage(
            role="system",
            content=TextContent(
                type="text",
                text="You are an expert analyst."
            )
        ),
        PromptMessage(
            role="user",
            content=TextContent(
                type="text",
                text=f"Analyze the following topic: {topic}"
            )
        )
    ]
```

### 4.5 Server Lifecycle Management

```python
from contextlib import asynccontextmanager
from typing import AsyncIterator
from dataclasses import dataclass

@dataclass
class AppContext:
    db: Database
    cache: Redis
    vector_store: VectorDB

@asynccontextmanager
async def app_lifespan(server: FastMCP) -> AsyncIterator[AppContext]:
    """Initialize and cleanup application resources."""
    # Startup
    db = await Database.connect("postgresql://...")
    cache = await Redis.connect("redis://...")
    vector_store = await VectorDB.connect("...")

    try:
        yield AppContext(db=db, cache=cache, vector_store=vector_store)
    finally:
        # Cleanup
        await db.disconnect()
        await cache.disconnect()
        await vector_store.disconnect()

# Create server with lifespan
mcp = FastMCP("genesis-server", lifespan=app_lifespan)

@mcp.tool()
async def query_memory(
    query: str,
    ctx: Context[ServerSession, AppContext]
) -> str:
    """Query Genesis memory system."""
    app = ctx.request_context.lifespan_context
    results = await app.vector_store.search(query)
    return json.dumps(results)
```

### 4.6 Complete Server Example (Python)

```python
#!/usr/bin/env python3
"""Genesis MCP Server - Exposes Genesis capabilities via MCP protocol."""

import json
import asyncio
from contextlib import asynccontextmanager
from typing import AsyncIterator
from dataclasses import dataclass

from mcp.server.fastmcp import FastMCP, Context
from mcp.server.session import ServerSession
from mcp.types import CallToolResult, TextContent
from pydantic import BaseModel

# ============================================================================
# Application Context
# ============================================================================

@dataclass
class GenesisContext:
    """Genesis application context with initialized connections."""
    memory_db: "MemoryDatabase"
    vector_store: "VectorStore"
    n8n_client: "N8NClient"

@asynccontextmanager
async def genesis_lifespan(server: FastMCP) -> AsyncIterator[GenesisContext]:
    """Initialize Genesis infrastructure connections."""
    # Initialize connections
    memory_db = await MemoryDatabase.connect()
    vector_store = await VectorStore.connect()
    n8n_client = await N8NClient.connect()

    try:
        yield GenesisContext(
            memory_db=memory_db,
            vector_store=vector_store,
            n8n_client=n8n_client
        )
    finally:
        # Cleanup
        await memory_db.disconnect()
        await vector_store.disconnect()
        await n8n_client.disconnect()

# ============================================================================
# Server Initialization
# ============================================================================

mcp = FastMCP(
    "genesis-server",
    version="1.0.0",
    lifespan=genesis_lifespan
)

# ============================================================================
# Tools
# ============================================================================

class MemorySearchResult(BaseModel):
    """Structured memory search result."""
    id: str
    content: str
    score: float
    memory_type: str
    timestamp: str

class MemorySearchResults(BaseModel):
    """Collection of memory search results."""
    results: list[MemorySearchResult]
    total: int
    query: str

@mcp.tool()
async def search_memory(
    query: str,
    memory_type: str = "semantic",
    limit: int = 10,
    ctx: Context[ServerSession, GenesisContext] = None
) -> MemorySearchResults:
    """Search Genesis memory system.

    Args:
        query: Natural language search query
        memory_type: Type of memory to search (semantic, episodic, working)
        limit: Maximum number of results to return

    Returns:
        Structured search results with relevance scores
    """
    genesis = ctx.request_context.lifespan_context

    await ctx.info(f"Searching {memory_type} memory: {query}")

    results = await genesis.vector_store.search(
        query=query,
        collection=memory_type,
        limit=limit
    )

    return MemorySearchResults(
        results=[
            MemorySearchResult(
                id=r["id"],
                content=r["content"],
                score=r["score"],
                memory_type=memory_type,
                timestamp=r["timestamp"]
            )
            for r in results
        ],
        total=len(results),
        query=query
    )

@mcp.tool()
async def store_memory(
    content: str,
    memory_type: str = "semantic",
    metadata: dict = None,
    ctx: Context[ServerSession, GenesisContext] = None
) -> dict:
    """Store new information in Genesis memory.

    Args:
        content: The content to store
        memory_type: Which memory tier to use
        metadata: Optional metadata (tags, source, etc.)

    Returns:
        Storage confirmation with memory ID
    """
    genesis = ctx.request_context.lifespan_context

    memory_id = await genesis.memory_db.store(
        content=content,
        memory_type=memory_type,
        metadata=metadata or {}
    )

    # Also embed in vector store
    await genesis.vector_store.add(
        id=memory_id,
        content=content,
        collection=memory_type
    )

    await ctx.info(f"Stored memory: {memory_id}")

    return {"id": memory_id, "status": "stored", "type": memory_type}

@mcp.tool()
async def trigger_workflow(
    workflow_name: str,
    input_data: dict = None,
    ctx: Context[ServerSession, GenesisContext] = None
) -> dict:
    """Trigger an n8n workflow.

    Args:
        workflow_name: Name of the workflow to trigger
        input_data: Data to pass to the workflow

    Returns:
        Workflow execution result
    """
    genesis = ctx.request_context.lifespan_context

    await ctx.info(f"Triggering workflow: {workflow_name}")

    result = await genesis.n8n_client.execute_webhook(
        workflow_name=workflow_name,
        data=input_data or {}
    )

    return {"workflow": workflow_name, "status": "triggered", "result": result}

@mcp.tool()
async def execute_skill(
    skill_name: str,
    parameters: dict = None,
    ctx: Context[ServerSession, GenesisContext] = None
) -> CallToolResult:
    """Execute a Genesis skill.

    Args:
        skill_name: Name of the skill to execute
        parameters: Skill parameters

    Returns:
        Skill execution result
    """
    try:
        # Dynamic skill loading would happen here
        skill_module = await load_skill(skill_name)
        result = await skill_module.execute(parameters or {})

        return CallToolResult(
            content=[TextContent(type="text", text=json.dumps(result))],
            isError=False
        )
    except Exception as e:
        return CallToolResult(
            content=[TextContent(type="text", text=f"Skill execution failed: {str(e)}")],
            isError=True
        )

# ============================================================================
# Resources
# ============================================================================

@mcp.resource("genesis://status")
async def get_genesis_status() -> str:
    """Current Genesis system status."""
    return json.dumps({
        "status": "operational",
        "memory_tiers": ["working", "episodic", "semantic", "trigger", "outcome"],
        "active_workflows": 3,
        "skills_loaded": 6
    })

@mcp.resource("genesis://memory/{memory_type}")
async def get_memory_contents(memory_type: str) -> str:
    """Get contents of a specific memory tier."""
    # Implementation would fetch from actual memory system
    return json.dumps({
        "type": memory_type,
        "entries_count": 150,
        "last_updated": "2025-12-31T05:00:00Z"
    })

@mcp.resource("genesis://skills")
async def list_skills() -> str:
    """List available Genesis skills."""
    return json.dumps({
        "skills": [
            {"name": "web_intelligence", "description": "Web scraping and research"},
            {"name": "code_analyzer", "description": "Code analysis with LSP"},
            {"name": "long_document_analyzer", "description": "Process 1M+ tokens"},
            {"name": "research_agent", "description": "Autonomous research"},
            {"name": "model_selector", "description": "Optimal model selection"},
            {"name": "context_engineering", "description": "Smart context management"}
        ]
    })

# ============================================================================
# Prompts
# ============================================================================

@mcp.prompt()
def evolution_analysis(period: str = "weekly") -> str:
    """Generate Genesis evolution analysis prompt."""
    return f"""Analyze the Genesis system's evolution over the past {period}.

Consider:
1. New capabilities integrated
2. Emergent behaviors observed
3. Memory utilization patterns
4. Workflow efficiency metrics
5. Areas requiring attention

Provide:
- Summary of progress
- Key achievements
- Recommendations for next evolution targets
- Risk assessment for proposed integrations
"""

@mcp.prompt()
def skill_creation(capability: str, requirements: str = "") -> str:
    """Prompt for creating a new Genesis skill."""
    return f"""Design a new Genesis skill for: {capability}

Requirements:
{requirements or "No specific requirements provided"}

Include:
1. Skill architecture
2. Input/output specifications
3. Error handling strategy
4. Integration points with Genesis infrastructure
5. Testing approach
6. Documentation template
"""

# ============================================================================
# Entry Point
# ============================================================================

if __name__ == "__main__":
    import sys

    # Run with stdio transport
    mcp.run(transport="stdio")
```

---

## 5. Protocol Primitives

### 5.1 Tools

**Purpose**: Allow LLMs to execute functions and perform actions.

**Characteristics**:
- Model-controlled (LLM decides when to call)
- Can have side effects
- Similar to POST endpoints in REST APIs
- Require explicit user consent before invocation

**Schema Definition**:

```json
{
  "name": "unique_tool_name",
  "title": "Human Readable Title",
  "description": "Detailed description of what the tool does",
  "inputSchema": {
    "type": "object",
    "properties": {
      "param1": {
        "type": "string",
        "description": "Parameter description"
      },
      "param2": {
        "type": "number",
        "default": 10
      }
    },
    "required": ["param1"]
  },
  "outputSchema": {
    "type": "object",
    "properties": {
      "result": { "type": "string" }
    }
  },
  "annotations": {
    "audience": ["user", "assistant"],
    "priority": 0.8
  }
}
```

**Tool Response Content Types**:

| Type | Description | Use Case |
|------|-------------|----------|
| `text` | Plain text content | Most responses |
| `image` | Base64-encoded image | Screenshots, charts |
| `audio` | Base64-encoded audio | Voice responses |
| `resource_link` | Reference to a resource | Large data, files |

### 5.2 Resources

**Purpose**: Expose read-only data to clients and models.

**Characteristics**:
- Application-controlled (client must explicitly fetch)
- No significant side effects
- Similar to GET endpoints in REST APIs
- Identified by URIs

**Resource Types**:

1. **Static Resources**: Fixed URI, fixed content
   ```python
   @mcp.resource("config://app")
   def get_config() -> str: ...
   ```

2. **Dynamic Resources (Templates)**: URI with parameters
   ```python
   @mcp.resource("file://{path}")
   def read_file(path: str) -> str: ...
   ```

**Resource Content**:
- Text content (with MIME type)
- Binary content (base64-encoded blob)

### 5.3 Prompts

**Purpose**: Define reusable, structured prompt templates.

**Characteristics**:
- User-controlled (explicitly selected by user)
- Can accept arguments for customization
- Define message sequences for LLM interactions
- Can embed resources

**Structure**:

```json
{
  "name": "prompt_name",
  "description": "What this prompt template does",
  "arguments": [
    {
      "name": "topic",
      "description": "The topic to analyze",
      "required": true
    },
    {
      "name": "style",
      "description": "Analysis style",
      "required": false
    }
  ]
}
```

**Prompt Messages**:

```json
{
  "messages": [
    {
      "role": "system",
      "content": { "type": "text", "text": "You are an expert..." }
    },
    {
      "role": "user",
      "content": { "type": "text", "text": "Analyze: {topic}" }
    }
  ]
}
```

### 5.4 Comparison Table

| Aspect | Tools | Resources | Prompts |
|--------|-------|-----------|---------|
| **Control** | Model-controlled | Application-controlled | User-controlled |
| **Purpose** | Execute actions | Provide data | Structure interactions |
| **Side Effects** | Yes | No | N/A |
| **REST Analogy** | POST | GET | N/A |
| **Invocation** | LLM decides | Client fetches | User selects |

---

## 6. Best Practices and Patterns

### 6.1 Error Handling

#### Three-Tier Error Model

1. **Transport-Level Errors**
   - Network timeouts, broken pipes, authentication failures
   - Handled by transport layer before MCP engagement
   - Log to stderr, retry with backoff

2. **Protocol-Level Errors (JSON-RPC)**
   - Malformed JSON, unknown methods, invalid parameters
   - Standard JSON-RPC error codes:

   | Code | Name | Meaning |
   |------|------|---------|
   | -32700 | Parse Error | Invalid JSON |
   | -32600 | Invalid Request | Missing required fields |
   | -32601 | Method Not Found | Unknown method |
   | -32602 | Invalid Params | Parameter validation failed |
   | -32603 | Internal Error | Server exception |
   | -32802 | Resource Unavailable | Temporary failure (retry safe) |

3. **Application-Level Errors**
   - Business logic failures
   - Return via `CallToolResult` with `isError: true`

#### Error Handling Pattern

```python
@mcp.tool()
async def robust_tool(input: str, ctx: Context) -> CallToolResult:
    try:
        # Validate input
        if not input or len(input) > 10000:
            return CallToolResult(
                content=[TextContent(type="text", text="Invalid input: must be 1-10000 characters")],
                isError=True
            )

        # Execute operation
        result = await execute_operation(input)

        return CallToolResult(
            content=[TextContent(type="text", text=json.dumps(result))],
            isError=False
        )

    except ExternalAPIError as e:
        # External service failed - suggest retry
        return CallToolResult(
            content=[TextContent(
                type="text",
                text=f"External service temporarily unavailable. Error: {e.message}. "
                     "This operation can be retried."
            )],
            isError=True
        )

    except AuthorizationError as e:
        # Configuration issue - don't retry
        return CallToolResult(
            content=[TextContent(
                type="text",
                text=f"Authorization failed. The MCP server needs valid API credentials. "
                     f"Current configuration is invalid: {e.reason}"
            )],
            isError=True
        )

    except Exception as e:
        # Unexpected error - log details, return safe message
        await ctx.error(f"Unexpected error: {traceback.format_exc()}")
        return CallToolResult(
            content=[TextContent(
                type="text",
                text="An unexpected error occurred. The issue has been logged for investigation."
            )],
            isError=True
        )
```

#### Agent-Centric Error Messages

**Bad**: "Error 401: Unauthorized"

**Good**: "To access this API, the MCP server needs a valid API_TOKEN environment variable. The current token appears to be expired or invalid. Please update the configuration and restart the server."

### 6.2 Logging Best Practices

**Critical Rule**: MCP servers MUST only write JSON-RPC messages to stdout. All logs go to stderr.

```python
import sys

def log(level: str, message: str):
    """Log to stderr to avoid interfering with JSON-RPC protocol."""
    print(f"[{level}] {message}", file=sys.stderr)

# Use context logging in tools
@mcp.tool()
async def my_tool(ctx: Context):
    await ctx.debug("Debug information")
    await ctx.info("Processing started")
    await ctx.warning("Non-critical issue")
    await ctx.error("Error occurred")
```

### 6.3 Security Best Practices

#### Input Validation

```python
from pydantic import BaseModel, validator, constr

class SecureInput(BaseModel):
    """Validated input with security constraints."""

    # Constrained string length
    query: constr(min_length=1, max_length=1000)

    # Enum validation
    memory_type: Literal["semantic", "episodic", "working"]

    # Custom validation
    path: str

    @validator("path")
    def validate_path(cls, v):
        # Prevent path traversal
        if ".." in v or v.startswith("/"):
            raise ValueError("Invalid path: must be relative without traversal")
        return v
```

#### Authentication with OAuth 2.1

```python
from mcp.server.auth import OAuthProvider

# Configure OAuth
oauth = OAuthProvider(
    authorization_server="https://auth.example.com",
    client_id="mcp-server",
    scopes=["read", "write"]
)

# Protected tool
@mcp.tool(auth=oauth.required(scopes=["write"]))
async def protected_write(data: str) -> str:
    """Tool requiring write permission."""
    ...
```

#### Rate Limiting

```python
from collections import defaultdict
from datetime import datetime, timedelta

class RateLimiter:
    def __init__(self, max_calls: int, window_seconds: int):
        self.max_calls = max_calls
        self.window = timedelta(seconds=window_seconds)
        self.calls = defaultdict(list)

    def check(self, client_id: str) -> bool:
        now = datetime.now()
        self.calls[client_id] = [
            t for t in self.calls[client_id]
            if now - t < self.window
        ]
        if len(self.calls[client_id]) >= self.max_calls:
            return False
        self.calls[client_id].append(now)
        return True

rate_limiter = RateLimiter(max_calls=100, window_seconds=60)

@mcp.tool()
async def rate_limited_tool(input: str, ctx: Context) -> CallToolResult:
    if not rate_limiter.check(ctx.client_id):
        return CallToolResult(
            content=[TextContent(type="text", text="Rate limit exceeded. Try again later.")],
            isError=True
        )
    ...
```

### 6.4 Tool Design Patterns

#### Self-Contained Connections

Create connections per tool call, not on server start:

```python
# GOOD: Connection per call
@mcp.tool()
async def query_database(query: str) -> str:
    async with Database.connect() as db:
        return await db.execute(query)

# BAD: Connection on startup (fails if misconfigured)
db = Database.connect()  # Server won't start if DB unavailable

@mcp.tool()
async def query_database(query: str) -> str:
    return await db.execute(query)
```

#### Idempotent Operations

Design tools that can be safely retried:

```python
@mcp.tool()
async def create_or_update(id: str, data: dict) -> dict:
    """Idempotent upsert operation."""
    existing = await db.get(id)
    if existing:
        return await db.update(id, data)
    return await db.create(id, data)
```

#### Progress Reporting

For long-running operations:

```python
@mcp.tool()
async def process_large_dataset(
    dataset_id: str,
    ctx: Context
) -> dict:
    """Process dataset with progress reporting."""
    dataset = await load_dataset(dataset_id)
    total = len(dataset)
    processed = 0

    for item in dataset:
        await process_item(item)
        processed += 1
        await ctx.report_progress(processed, total)

    return {"processed": processed, "total": total}
```

### 6.5 Containerization Best Practices (Docker)

```dockerfile
# Multi-stage build for lean images
FROM python:3.11-slim as builder

WORKDIR /app
COPY requirements.txt .
RUN pip install --user --no-cache-dir -r requirements.txt

FROM python:3.11-slim

# Non-root user
RUN useradd -m -u 1000 mcp
USER mcp

WORKDIR /app
COPY --from=builder /root/.local /home/mcp/.local
COPY --chown=mcp:mcp . .

ENV PATH="/home/mcp/.local/bin:$PATH"

# Health check
HEALTHCHECK --interval=30s --timeout=3s \
    CMD python -c "import sys; sys.exit(0)"

# Never embed secrets - use runtime environment
# ENV API_KEY=xxx  # BAD
# Use: docker run -e API_KEY=xxx  # GOOD

ENTRYPOINT ["python", "-m", "genesis_mcp_server"]
```

**Docker Compose for Genesis MCP**:

```yaml
version: '3.8'
services:
  genesis-mcp:
    build: .
    environment:
      - MEMORY_DB_URL=${MEMORY_DB_URL}
      - VECTOR_STORE_URL=${VECTOR_STORE_URL}
      - N8N_WEBHOOK_URL=${N8N_WEBHOOK_URL}
    volumes:
      - ./data:/app/data:ro  # Read-only data mount
    deploy:
      resources:
        limits:
          cpus: '1'
          memory: 2G
    networks:
      - genesis-network
    healthcheck:
      test: ["CMD", "python", "-c", "print('healthy')"]
      interval: 30s
      timeout: 10s
      retries: 3
```

---

## 7. Reference Server Analysis

### 7.1 Official Reference Servers

| Server | Purpose | Key Patterns |
|--------|---------|--------------|
| **Memory** | Knowledge graph persistence | Entity/relation model, JSONL storage, graph traversal |
| **Filesystem** | Secure file operations | Path validation, access control, directory roots |
| **Everything** | Reference/test server | All three primitives, complete example |
| **Fetch** | Web content retrieval | URL validation, content conversion, LLM optimization |
| **Git** | Repository operations | Command execution, output parsing, safety checks |
| **Sequential Thinking** | Problem solving | Thought chains, reflection, dynamic planning |
| **Time** | Time utilities | Timezone handling, format conversion |

### 7.2 Memory Server Deep Dive

The Memory MCP server is particularly relevant for Genesis. Here's its architecture:

**Data Model**:

```typescript
interface Entity {
  name: string;           // Unique identifier
  entityType: string;     // Classification
  observations: string[]; // Atomic facts
}

interface Relation {
  from: string;          // Source entity name
  to: string;            // Target entity name
  relationType: string;  // Relationship type (active voice)
}
```

**Tools Provided**:

| Tool | Purpose | Example |
|------|---------|---------|
| `create_entities` | Add new entities | Create person/organization nodes |
| `create_relations` | Connect entities | "works_at", "knows", "depends_on" |
| `add_observations` | Append facts | Add new information to entity |
| `delete_entities` | Remove nodes | Cascades to relations |
| `delete_observations` | Remove facts | Selective fact removal |
| `delete_relations` | Remove connections | Break relationships |
| `read_graph` | Full graph dump | Get entire knowledge graph |
| `search_nodes` | Query graph | Search by name/type/content |
| `open_nodes` | Get specific nodes | Retrieve by name with relations |

**Persistence Pattern**:

```
┌─────────────────────────────────────────┐
│           JSONL File Storage            │
│  (MEMORY_FILE_PATH environment var)     │
├─────────────────────────────────────────┤
│ {"type":"entity","name":"John",...}     │
│ {"type":"relation","from":"John",...}   │
│ {"type":"entity","name":"Acme",...}     │
│ {"type":"relation","from":"John",...}   │
└─────────────────────────────────────────┘
```

### 7.3 Common Patterns Across Reference Servers

1. **Environment-Based Configuration**
   ```bash
   MEMORY_FILE_PATH=/data/memory.jsonl
   FILESYSTEM_ROOTS=/home/user,/tmp
   ```

2. **Capability Declaration**
   ```typescript
   capabilities: {
     tools: { listChanged: true },
     resources: { subscribe: true, listChanged: true }
   }
   ```

3. **Input Validation First**
   ```typescript
   if (!args.path || typeof args.path !== 'string') {
     throw new Error("Invalid path parameter");
   }
   ```

4. **Structured Error Responses**
   ```typescript
   return {
     content: [{ type: "text", text: `Error: ${message}` }],
     isError: true
   };
   ```

5. **npx Distribution**
   ```bash
   npx -y @modelcontextprotocol/server-memory
   ```

---

## 8. Genesis-Specific MCP Opportunities

### 8.1 Current Genesis Infrastructure

Based on analysis of the Genesis system:

**Memory Systems**:
- Dragonfly (Redis-compatible cache, port 6379)
- Weaviate (Vector DB, port 8085)
- ChromaDB (Vector DB, port 8000)
- Neo4j (Graph DB, ports 7474, 7687)
- PostgreSQL (via Elestio)
- Custom memory scripts (surprise_memory.py, genesis_memory_cortex.py, etc.)

**Skills Library**:
- `web_intelligence.py` - Web scraping with Firecrawl
- `long_document_analyzer.py` - 1M+ token processing
- `code_analyzer.py` - LSP integration
- `model_selector.py` - Automatic model selection
- `research_agent.py` - Autonomous research
- `context_engineering.py` - Smart context management

**Orchestration**:
- n8n workflows (Elestio hosted)
- Multi-model orchestrator (Gemini, Claude)
- Task queue system
- Master controller

**Existing MCP Usage**:
- Docker MCP Gateway (312 servers)
- Memory MCP
- Slack MCP
- n8n MCP
- Playwright MCP

### 8.2 Recommended Custom MCP Server: Genesis Core

A unified MCP server exposing Genesis capabilities to any MCP-compatible host.

**Server Name**: `genesis-core`

**Tools to Expose**:

| Tool | Description | Source |
|------|-------------|--------|
| `genesis_search` | Multi-tier memory search | genesis_memory_cortex.py |
| `genesis_store` | Store to appropriate memory tier | surprise_memory.py |
| `genesis_skill` | Execute any Genesis skill | skills/__init__.py |
| `genesis_workflow` | Trigger n8n workflow | n8n MCP integration |
| `genesis_research` | Autonomous web research | research_agent.py |
| `genesis_analyze` | Analyze code/documents | code_analyzer.py, long_document_analyzer.py |
| `genesis_route` | Route task to optimal model | model_selector.py |
| `genesis_evolve` | Record evolution event | genesis_evolution_protocol.py |

**Resources to Expose**:

| Resource URI | Description |
|--------------|-------------|
| `genesis://status` | System health and capabilities |
| `genesis://memory/{type}` | Memory tier contents |
| `genesis://skills` | Available skills catalog |
| `genesis://workflows` | n8n workflow catalog |
| `genesis://evolution/log` | Evolution history |
| `genesis://config` | System configuration |

**Prompts to Expose**:

| Prompt | Purpose |
|--------|---------|
| `evolution_report` | Generate weekly evolution report |
| `skill_design` | Design new Genesis skill |
| `integration_assessment` | Evaluate new technology for integration |
| `architecture_review` | Review Genesis architecture component |

### 8.3 Additional MCP Server Ideas

#### Genesis Memory MCP (Enhanced)

Expose the 5-tier Genesis memory architecture:

```
Working Memory  → Short-term context
Episodic Memory → Session experiences
Semantic Memory → Long-term knowledge
Trigger Memory  → Pattern recognition
Outcome Memory  → Action-result pairs
```

**Tools**:
- `query_working_memory` - Current session context
- `store_episodic` - Record experience
- `search_semantic` - Knowledge retrieval
- `check_triggers` - Pattern matching
- `record_outcome` - Action-result logging

#### Genesis Orchestrator MCP

Expose the master orchestrator capabilities:

**Tools**:
- `dispatch_task` - Route task to best agent
- `get_agent_status` - Check agent availability
- `scale_agents` - Adjust agent pool
- `execute_batch` - Batched task execution
- `monitor_progress` - Track multi-task progress

#### Genesis Evolution MCP

Expose the self-evolution capabilities:

**Tools**:
- `discover_technology` - Scan sources for new tech
- `assess_integration` - Evaluate tech for Genesis
- `test_capability` - Run isolated tests
- `integrate_capability` - Add to Genesis
- `measure_emergence` - Track emergent behaviors

### 8.4 Integration Architecture

```
┌──────────────────────────────────────────────────────────────────┐
│                        MCP HOSTS                                 │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐              │
│  │Claude Desktop│  │ Claude Code │  │ VS Code     │              │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘              │
└─────────┼────────────────┼────────────────┼─────────────────────┘
          │                │                │
          └────────────────┼────────────────┘
                           │ MCP Protocol
                           ▼
┌──────────────────────────────────────────────────────────────────┐
│                    GENESIS MCP SERVER                            │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │                      genesis-core                          │  │
│  │  Tools: search, store, skill, workflow, research, ...     │  │
│  │  Resources: status, memory, skills, workflows, ...        │  │
│  │  Prompts: evolution_report, skill_design, ...             │  │
│  └───────────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────────────┘
                           │
          ┌────────────────┼────────────────┐
          │                │                │
          ▼                ▼                ▼
┌─────────────────┐ ┌─────────────┐ ┌─────────────────┐
│  Genesis Memory │ │ n8n         │ │ Genesis Skills  │
│  (5-tier)       │ │ Workflows   │ │ Library         │
├─────────────────┤ └─────────────┘ ├─────────────────┤
│ • Dragonfly     │                 │ • web_intel     │
│ • Weaviate      │                 │ • code_analyzer │
│ • ChromaDB      │                 │ • research_agent│
│ • Neo4j         │                 │ • model_selector│
│ • PostgreSQL    │                 │ • context_eng   │
└─────────────────┘                 └─────────────────┘
```

### 8.5 Benefits for Genesis

1. **Universal Access**: Any MCP host can use Genesis capabilities
2. **Standardized Interface**: Clean abstraction over complex infrastructure
3. **Composability**: Genesis tools work with other MCP servers
4. **Discoverability**: Tools/resources/prompts are self-documenting
5. **External Integration**: Third-party systems can integrate via MCP
6. **Evolution Acceleration**: New capabilities exposed immediately via MCP

---

## 9. Implementation Recommendations

### 9.1 Phase 1: Genesis Core MCP Server (Python)

**Timeline**: 1-2 days

**Scope**:
- Create `genesis-core` MCP server in Python
- Expose top 5 most-used capabilities as tools
- Add basic resources (status, skills)
- Include 2-3 prompt templates

**File Structure**:
```
/mnt/e/genesis-system/mcp-servers/genesis-core/
├── pyproject.toml
├── README.md
├── src/
│   └── genesis_core/
│       ├── __init__.py
│       ├── server.py        # Main MCP server
│       ├── tools/
│       │   ├── __init__.py
│       │   ├── memory.py    # Memory tools
│       │   ├── skills.py    # Skill execution
│       │   └── workflows.py # n8n integration
│       ├── resources/
│       │   ├── __init__.py
│       │   └── status.py    # Status resources
│       └── prompts/
│           ├── __init__.py
│           └── templates.py # Prompt templates
└── tests/
    └── test_server.py
```

### 9.2 Phase 2: Docker Packaging

**Timeline**: 1 day

**Scope**:
- Dockerfile with multi-stage build
- docker-compose.yml for local testing
- Integration with existing Genesis Docker network
- Volume mounts for persistent data

### 9.3 Phase 3: Claude Desktop Integration

**Timeline**: 1 day

**Scope**:
- Add genesis-core to Claude Desktop config
- Test all tools, resources, prompts
- Document usage patterns
- Create example workflows

**Configuration** (claude_desktop_config.json):
```json
{
  "mcpServers": {
    "genesis-core": {
      "command": "python",
      "args": ["-m", "genesis_core"],
      "env": {
        "GENESIS_MEMORY_URL": "...",
        "GENESIS_N8N_URL": "...",
        "GENESIS_VECTOR_URL": "..."
      }
    }
  }
}
```

### 9.4 Phase 4: Advanced Features

**Timeline**: 1 week

**Scope**:
- OAuth 2.1 authentication
- Rate limiting
- Structured output schemas for all tools
- Progress reporting for long operations
- Streaming responses
- WebSocket transport for real-time updates

### 9.5 Testing Strategy

**MCP Inspector**:
```bash
# Install MCP Inspector
npm install -g @modelcontextprotocol/inspector

# Test genesis-core
npx @modelcontextprotocol/inspector python -m genesis_core
```

**Unit Tests**:
```python
import pytest
from genesis_core.server import mcp

@pytest.mark.asyncio
async def test_genesis_search():
    result = await mcp.call_tool("genesis_search", {
        "query": "test query",
        "memory_type": "semantic"
    })
    assert not result.isError
    assert len(result.content) > 0
```

---

## 10. Sources and References

### Official Documentation

- [Model Context Protocol Specification](https://modelcontextprotocol.io/specification/2025-11-25) - Official spec (v2025-11-25)
- [MCP GitHub Organization](https://github.com/modelcontextprotocol) - Open source repositories
- [MCP Tools Documentation](https://modelcontextprotocol.io/docs/concepts/tools) - Tool concepts and patterns

### SDKs

- [@modelcontextprotocol/sdk (npm)](https://www.npmjs.com/package/@modelcontextprotocol/sdk) - TypeScript SDK v1.25.1
- [mcp (PyPI)](https://pypi.org/project/mcp/) - Python SDK v1.25.0
- [TypeScript SDK GitHub](https://github.com/modelcontextprotocol/typescript-sdk) - TS source and docs
- [Python SDK GitHub](https://github.com/modelcontextprotocol/python-sdk) - Python source and docs

### Reference Implementations

- [MCP Reference Servers](https://github.com/modelcontextprotocol/servers) - Official reference servers
- [Memory Server](https://github.com/modelcontextprotocol/servers/tree/main/src/memory) - Knowledge graph implementation
- [Filesystem Server](https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem) - File operations

### Best Practices

- [Error Handling in MCP Servers](https://mcpcat.io/guides/error-handling-custom-mcp-servers/) - Error patterns guide
- [MCP Best Practices Architecture Guide](https://modelcontextprotocol.info/docs/best-practices/) - Architecture patterns
- [Docker MCP Best Practices](https://www.docker.com/blog/mcp-server-best-practices/) - Containerization guide
- [MCP Security Explained](https://www.docker.com/blog/mcp-security-explained/) - Security considerations
- [7 MCP Server Best Practices](https://www.marktechpost.com/2025/07/23/7-mcp-server-best-practices-for-scalable-ai-integrations-in-2025/) - Scalability guide

### Development Tools

- [MCP Inspector](https://github.com/modelcontextprotocol/inspector) - Visual testing tool
- [MCP Inspector Guide](https://mcpcat.io/guides/setting-up-mcp-inspector-server-testing/) - Setup and usage

### Authentication and Security

- [MCP Authorization Specification](https://modelcontextprotocol.io/specification/draft/basic/authorization) - OAuth 2.1 p...(truncated)

metadata:
{"filename": "MCP-DEVELOPMENT-GUIDE.md", "path": "E:/genesis-system/docs/research\\MCP-DEVELOPMENT-GUIDE.md"}


id: 4fed089b-e4d9-55e5-a192-3244152295ce
domain: knowledge_base
source: doc_ingest
timestamp: 2026-01-06T20:00:33.525248
created_at: 2026-01-06 10:00:33
content:
DOCUMENT: META_PROMPT_MASTERY.md
# 🧠 META-PROMPT ENGINEERING & GENESIS NEURAL OS

**Objective**: Elevate Genesis from a set of scripts to a **Fully Autonomous, Self-Improving Operating System**.
**Core Philosophy**: "The Prompt is the Code. The Memory is the State. The Agent is the cpu."

---

## 1. META-PROMPT PATTERNS (The Cognitive Layer)

### A. Reflexion (The "Self-Correction" Loop)
*   **Concept**: Agents should not just "Act". They must "Act -> Observe -> **Critique** -> Refine".
*   **Genesis Application**:
    *   Before `Contractor-GHL` marks a task done, it parses its own output.
    *   *Prompt Pattern*: "You have just executed X. Review the logs. Did it match the objective? If no, generate a correction plan."
    *   *Implementation*: A `reflexion.py` wrapper around all critical tool calls.

### B. DSPy (Declarative Self-Improving Prompts)
*   **Concept**: Stop hand-writing prompts. Define the *Goal* and let the system optimize the *Prompt* based on data.
*   **Genesis Application**:
    *   **Darwinian Prompting**: If a sales script works (Sale >= 1), it is saved as a "High-Fitness Gene".
    *   Low-performing prompts are discarded. The system "evolves" its own sales copy.

### C. Recursive Meta-Prompting (The "Manager-Worker" Fracture)
*   **Concept**: A high-level agent breaks a task into sub-prompts and spawns specialized instances.
*   **Genesis Application**:
    *   **Storm Orchestrator**: `Lead Architect` does not browse the web. It spawns `Scout` with a specific, rigid prompt: "Find X. Return JSON. Do nothing else."
    *   This minimizes hallucination by narrowing the context window for workers.

---

## 2. CRITICAL MCPs (The Nervous System)

To achieve "OS-Level" autonomy, we need these specific MCPs:

### 🛠️ Foundational MCPs (Must Have)
1.  **`memory` (Knowledge Graph)**:
    *   *Why*: Current RAG is static. We need a graph (Neo4j/FalkorDB) where agents link "Entities" (e.g., "Client X" -> "Has Problem Y").
    *   *Effect*: Agents "remember" relationships, not just text chunks.
2.  **`filesystem` (Self-Coding)**:
    *   *Why*: The OS must be able to patch itself.
    *   *Effect*: `Engineer Lead` can fix bugs in `contractor_ghl.py` without human intervention.
3.  **`git` (Evolution)**:
    *   *Why*: To commit changes and rollback if "Self-Improvement" breaks the system.
    *   *Effect*: Safe autonomous coding.

### 🧠 Cognitive MCPs (Advanced)
4.  **`sequential-thinking`**:
    *   *Why*: Forces the LLM to output `<thought>` blocks before `<action>`.
    *   *Effect*: Reduces logic errors by 40%.
5.  **`puppeteer`/`playwright`**:
    *   *Why*: "Eyes" on the web. Verification of deployment.
    *   *Effect*: `Scout` can verify "Did the GHL landing page actually load?"

---

## 3. THE GENESIS NEURAL OS ARCHITECTURE

We are moving from **Scripts** to **Living Circuits**.

```mermaid
graph TD
    User[User / Executive] -->|Directive| MissionControl[MISSION_CONTROL.md]
    MissionControl -->|Trigger| LeadArch[Lead Architect (Orchestrator)]
    
    subgraph "The Neural Core"
        LeadArch -->|Reads| Blackboard[(Blackboard Memory)]
        LeadArch -->|Spawns| Swarm[Storm Container Swarm]
    end
    
    subgraph "Active Agents (The Hands)"
        Swarm -->|Deploy| GHL[Contractor-GHL]
        Swarm -->|Research| Scout[Scout-Browser]
        Swarm -->|Voice| Johnni[Johnni.ai Voice]
    end
    
    subgraph "Feedback Loop (The Brain)"
        GHL -->|Logs| Audit[Audit Log]
        Audit -->|Reflexion| Improver[Self-Optimizer]
        Improver -->|Updates| Prompts[System Prompts]
        Prompts -->|Re-Informs| LeadArch
    end
```

### The "Unceasing Motion" Loop
1.  **Job**: `Lead Architecture` reads `MISSION_CONTROL.md`.
2.  **Spawn**: Deploys `Contractor` via `Storm`.
3.  **Act**: `Contractor` attempts task.
4.  **Reflect**: `Improver` scans Result vs. Expectation.
5.  **Evolve**: If Failure -> Patch Code. If Success -> Save Pattern.
6.  **Repeat**.

---

## 4. IMMEDIATE ACTION PLAN
1.  **Deploy `sequential-thinking` MCP**: Force all logic through a reasoning step.
2.  **Build `reflexion.py`**: A simple decorator for our Python agents.
3.  **Darwinian Prompts**: Enable the "Sales Copy" optimizer in `n8n`.

metadata:
{"filename": "META_PROMPT_MASTERY.md", "path": "E:/genesis-system/docs/research\\META_PROMPT_MASTERY.md"}


id: c7d56128-8ff6-5757-a0ae-fa24705ad149
domain: knowledge_base
source: doc_ingest
timestamp: 2026-01-06T20:00:35.005640
created_at: 2026-01-06 10:00:35
content:
DOCUMENT: N8N-REVENUE-PIPELINES.md
# N8N Revenue Pipeline Workflow Patterns

> Research Document - Compiled December 31, 2025
>
> This document outlines proven n8n workflow patterns for building revenue-generating automation pipelines.

---

## Table of Contents

1. [Lead Capture Workflows](#1-lead-capture-workflows)
2. [Payment/Invoice Automation](#2-paymentinvoice-automation)
3. [Email Sequence Automation](#3-email-sequence-automation)
4. [Appointment/Booking Workflows](#4-appointmentbooking-workflows)
5. [Node Reference Guide](#5-node-reference-guide)
6. [Example JSON Structures](#6-example-json-structures)

---

## 1. Lead Capture Workflows

### Overview

Lead capture workflows automatically collect, validate, enrich, and route leads from various sources into your CRM. The typical flow is:

```
Lead Intake -> Data Validation -> Enrichment -> Scoring -> Smart Routing -> CRM Integration & Notifications
```

### 1.1 Form Submission Handling

#### Node Types Required

| Node | Purpose | Type Version |
|------|---------|--------------|
| `n8n-nodes-base.webhookTrigger` | Receive form submissions | 2.0 |
| `n8n-nodes-base.formTrigger` | Native n8n form handling | 2.2 |
| `n8n-nodes-base.typeformTrigger` | Typeform integration | 1.0 |
| `n8n-nodes-base.jotformTrigger` | Jotform integration | 1.0 |
| `n8n-nodes-base.if` | Data validation | 2.2 |
| `n8n-nodes-base.set` | Data transformation | 3.4 |
| `n8n-nodes-base.code` | Custom validation logic | 2.0 |

#### Trigger Mechanisms

1. **Webhook Trigger**: Generic endpoint for any form platform
   - POST method recommended
   - Supports JSON, form-urlencoded, multipart/form-data

2. **Native Form Triggers**: Direct integrations
   - Typeform, Jotform, Tally, Webflow Forms
   - Real-time webhooks (1-3 second latency)

3. **Schedule + API Polling**: For platforms without webhooks
   - Poll form responses on interval
   - Use `n8n-nodes-base.scheduleTrigger`

#### Common Integrations

- **Form Platforms**: Typeform, Jotform, Tally, Webflow, Gravity Forms
- **Website Forms**: Contact Form 7, WPForms via webhooks
- **Landing Pages**: Unbounce, Leadpages, Instapage

#### Data Validation Pattern

```javascript
// Code node for form validation
const email = $json.email;
const name = $json.name;

// Email regex validation
const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
const isValidEmail = emailRegex.test(email);

// Check required fields
const hasRequiredFields = email && name && name.length > 1;

return [{
  json: {
    ...($json),
    isValid: isValidEmail && hasRequiredFields,
    validationErrors: []
      .concat(!email ? ['Missing email'] : [])
      .concat(!isValidEmail ? ['Invalid email format'] : [])
      .concat(!name ? ['Missing name'] : [])
  }
}];
```

---

### 1.2 CRM Integration

#### GoHighLevel Integration

**Node Types:**
| Node | Purpose |
|------|---------|
| `n8n-nodes-base.highLevel` | Native HighLevel operations |
| `n8n-nodes-base.httpRequest` | Custom API calls |
| `n8n-nodes-base.webhook` | Receive HighLevel webhooks |

**Common Operations:**
- Create/Update contacts
- Add to pipelines and opportunities
- Trigger automations
- Update custom fields
- Tag management

**GoHighLevel Workflow Pattern:**

```
Webhook Trigger -> Validate Data -> IF (existing contact?)
                                    -> YES: Update Contact -> Add Tags
                                    -> NO: Create Contact -> Add to Pipeline -> Assign to User
```

**Integration Setup:**
1. Generate API key in GoHighLevel Settings > API Keys
2. Create HTTP Header Auth credential in n8n
3. Base URL: `https://rest.gohighlevel.com/v1/`

**Common Use Cases:**
- Auto-assign leads based on city, service type, budget, or tags
- AI chatbot integration for lead qualification
- Behavior-based email/SMS trigger flows
- Real-time lead routing to sales reps

#### HubSpot Integration

**Node Types:**
| Node | Purpose |
|------|---------|
| `n8n-nodes-base.hubspot` | Native HubSpot operations |
| `n8n-nodes-base.hubspotTrigger` | HubSpot event webhooks |

**Common Operations:**
- Contact CRUD operations
- Deal/Opportunity management
- Company associations
- Engagement tracking
- Form submission handling

**HubSpot Lead Capture Pattern:**

```
Form Submission -> Enrich with Clearbit -> Score Lead ->
IF (score >= 70) -> Create as "Qualified" in HubSpot
IF (score < 70) -> Create as "Nurture" stage -> Add to drip campaign
```

**Lead Scoring Logic Example:**

```javascript
// Code node for BANT-based lead scoring
const lead = $json;
let score = 0;

// Budget scoring (0-25 points)
if (lead.budget === '$50k+') score += 25;
else if (lead.budget === '$25k-50k') score += 20;
else if (lead.budget === '$10k-25k') score += 15;
else if (lead.budget === '$5k-10k') score += 10;
else score += 5;

// Authority scoring (0-25 points)
const decisionMakers = ['CEO', 'CTO', 'VP', 'Director', 'Owner'];
if (decisionMakers.some(title => lead.jobTitle?.includes(title))) score += 25;
else if (lead.jobTitle?.includes('Manager')) score += 15;
else score += 5;

// Need scoring (0-25 points)
if (lead.timeline === 'Immediate') score += 25;
else if (lead.timeline === '1-3 months') score += 20;
else if (lead.timeline === '3-6 months') score += 15;
else score += 5;

// Timeline scoring (0-25 points)
if (lead.companySize === '500+') score += 25;
else if (lead.companySize === '100-500') score += 20;
else if (lead.companySize === '50-100') score += 15;
else score += 10;

// Determine tier
let tier = 'Cold';
if (score >= 75) tier = 'Hot';
else if (score >= 50) tier = 'Warm';

return [{
  json: {
    ...lead,
    leadScore: score,
    leadTier: tier,
    scoredAt: new Date().toISOString()
  }
}];
```

---

### 1.3 Lead Scoring and Routing

#### AI-Powered Lead Scoring

**Node Types:**
| Node | Purpose |
|------|---------|
| `@n8n/n8n-nodes-langchain.openAi` | GPT-4 for BANT analysis |
| `@n8n/n8n-nodes-langchain.agent` | AI agent for qualification |
| `n8n-nodes-base.code` | Rule-based scoring |
| `n8n-nodes-base.switch` | Multi-path routing |

**AI Scoring Prompt Template:**

```
You are a lead qualification expert. Analyze this lead and provide a BANT score (0-100).

Lead Information:
- Name: {{$json.name}}
- Email: {{$json.email}}
- Company: {{$json.company}}
- Job Title: {{$json.jobTitle}}
- Budget: {{$json.budget}}
- Timeline: {{$json.timeline}}
- Pain Points: {{$json.painPoints}}

Evaluate:
1. Budget (0-25): Does budget align with our pricing?
2. Authority (0-25): Can this person make purchasing decisions?
3. Need (0-25): How urgent is their problem?
4. Timeline (0-25): How soon are they looking to buy?

Return JSON only:
{
  "totalScore": <number>,
  "budgetScore": <number>,
  "authorityScore": <number>,
  "needScore": <number>,
  "timelineScore": <number>,
  "recommendation": "Hot|Warm|Cold",
  "reasoning": "<brief explanation>"
}
```

#### Territory-Based Routing

```javascript
// Code node for territory routing
const lead = $json;
const territories = {
  'US-West': ['CA', 'WA', 'OR', 'NV', 'AZ'],
  'US-East': ['NY', 'NJ', 'MA', 'FL', 'GA'],
  'US-Central': ['TX', 'IL', 'OH', 'CO', 'MN'],
  'International': []
};

const salesReps = {
  'US-West': { name: 'Alice', email: 'alice@company.com', slackId: 'U123' },
  'US-East': { name: 'Bob', email: 'bob@company.com', slackId: 'U456' },
  'US-Central': { name: 'Carol', email: 'carol@company.com', slackId: 'U789' },
  'International': { name: 'Dave', email: 'dave@company.com', slackId: 'U012' }
};

let territory = 'International';
for (const [region, states] of Object.entries(territories)) {
  if (states.includes(lead.state)) {
    territory = region;
    break;
  }
}

return [{
  json: {
    ...lead,
    territory,
    assignedRep: salesReps[territory]
  }
}];
```

#### Performance Metrics Achieved

- **5-minute response time** from form submission to rep contact (vs 48+ hours manual)
- **300% conversion increase** through faster response and better qualification
- **Zero lead conflicts** through automated assignment

---

## 2. Payment/Invoice Automation

### 2.1 Stripe Webhook Handling

#### Node Types Required

| Node | Purpose | Type Version |
|------|---------|--------------|
| `n8n-nodes-base.stripeTrigger` | Stripe webhook events | 1.0 |
| `n8n-nodes-base.stripe` | Stripe API operations | 1.0 |
| `n8n-nodes-base.webhook` | Custom webhook endpoint | 1.1 |
| `n8n-nodes-base.if` | Event type routing | 2.2 |
| `n8n-nodes-base.switch` | Multi-event handling | 3.2 |

#### Supported Stripe Webhook Events

| Event | Description | Use Case |
|-------|-------------|----------|
| `charge.succeeded` | Successful payment | Send receipt, fulfill order |
| `charge.failed` | Failed payment | Notify customer, retry logic |
| `charge.refunded` | Refund processed | Update inventory, notify team |
| `invoice.created` | New invoice | Add line items, modify |
| `invoice.payment_succeeded` | Invoice paid | Fulfill subscription, send receipt |
| `invoice.payment_failed` | Invoice payment failed | Dunning emails, pause service |
| `customer.subscription.created` | New subscription | Onboarding sequence |
| `customer.subscription.deleted` | Subscription cancelled | Winback campaign |
| `customer.subscription.updated` | Plan change | Update access, notify team |

#### Stripe Webhook Workflow Pattern

```
Stripe Trigger -> Switch (event type)
  -> charge.succeeded -> Update CRM -> Send Receipt -> Notify Slack
  -> charge.failed -> Send Failure Email -> Create Support Ticket
  -> invoice.created -> Add Custom Line Items -> Finalize Invoice
  -> customer.subscription.created -> Start Onboarding -> Update CRM
```

#### Webhook Security

```javascript
// Code node to verify Stripe webhook signature
const crypto = require('crypto');
const endpointSecret = $credentials.Stripe.webhookSecret;
const signature = $request.headers['stripe-signature'];
const body = $request.body;

const elements = signature.split(',');
let timestamp, expectedSig;

for (const element of elements) {
  const [key, value] = element.split('=');
  if (key === 't') timestamp = value;
  if (key === 'v1') expectedSig = value;
}

const signedPayload = `${timestamp}.${JSON.stringify(body)}`;
const computedSig = crypto
  .createHmac('sha256', endpointSecret)
  .update(signedPayload)
  .digest('hex');

if (computedSig !== expectedSig) {
  throw new Error('Invalid Stripe webhook signature');
}

return [{ json: body }];
```

---

### 2.2 Invoice Generation

#### Automated Invoice Workflow

**Node Types:**
| Node | Purpose |
|------|---------|
| `n8n-nodes-base.stripe` | Create invoices |
| `n8n-nodes-base.httpRequest` | PDF generation (e.g., via API) |
| `n8n-nodes-base.gmail` / `n8n-nodes-base.sendGrid` | Email delivery |
| `n8n-nodes-base.googleSheets` | Invoice tracking |

#### Invoice Generation Steps

1. **Create Customer** (if not exists)
2. **Add Invoice Items** (line items with pricing)
3. **Create Invoice** (draft state)
4. **Finalize Invoice** (locks invoice)
5. **Send Invoice** (Stripe emails or custom)

#### Invoice Creation Code

```javascript
// Steps to generate a Stripe invoice
// Node 1: Create Customer (HTTP Request to Stripe API)
// Node 2: Create Invoice Items
// Node 3: Create Invoice
// Node 4: Finalize Invoice

// Example invoice item structure
const invoiceItems = [
  {
    customer: $json.stripeCustomerId,
    amount: 9900, // $99.00 in cents
    currency: 'usd',
    description: 'Monthly Subscription - Pro Plan'
  },
  {
    customer: $json.stripeCustomerId,
    amount: 2500, // $25.00 in cents
    currency: 'usd',
    description: 'Setup Fee'
  }
];

return invoiceItems.map(item => ({ json: item }));
```

#### PDF Invoice with Email Delivery

**Workflow Pattern:**
```
Stripe Trigger (payment_intent.succeeded)
  -> Fetch Invoice Details
  -> Generate PDF (via API or template)
  -> Upload to Storage
  -> Send Email with PDF attachment
  -> Log to Google Sheets
```

---

### 2.3 Payment Reminders (Dunning)

#### Dunning Email Sequence

| Day | Action | Content |
|-----|--------|---------|
| Day 0 | Invoice sent | Initial invoice |
| Day 3 | Reminder 1 | Friendly reminder |
| Day 7 | Reminder 2 | Payment overdue notice |
| Day 14 | Final Notice | Service suspension warning |
| Day 21 | Account Action | Suspend/Cancel service |

#### Dunning Workflow Pattern

```
Schedule Trigger (daily)
  -> Query Overdue Invoices
  -> Loop Each Invoice
    -> Calculate Days Overdue
    -> Switch (days overdue)
      -> 3 days: Send Reminder 1
      -> 7 days: Send Reminder 2
      -> 14 days: Send Final Notice + Flag Account
      -> 21 days: Suspend Service + Notify Team
```

#### Payment Retry Logic

```javascript
// Code node for smart payment retry
const invoice = $json;
const daysSinceFailed = Math.floor(
  (Date.now() - new Date(invoice.failedAt).getTime()) / (1000 * 60 * 60 * 24)
);

// Retry schedule: Day 1, 3, 5, 7
const retryDays = [1, 3, 5, 7];
const shouldRetry = retryDays.includes(daysSinceFailed) && invoice.retryCount < 4;

return [{
  json: {
    ...invoice,
    shouldRetry,
    daysSinceFailed,
    nextAction: shouldRetry ? 'retry_payment' :
                daysSinceFailed > 7 ? 'manual_intervention' : 'wait'
  }
}];
```

---

## 3. Email Sequence Automation

### 3.1 Drip Campaign Workflows

#### Node Types Required

| Node | Purpose | Type Version |
|------|---------|--------------|
| `n8n-nodes-base.scheduleTrigger` | Campaign timing | 1.2 |
| `n8n-nodes-base.wait` | Delay between emails | 1.1 |
| `n8n-nodes-base.gmail` | Send via Gmail | 2.1 |
| `n8n-nodes-base.sendGrid` | Send via SendGrid | 1.0 |
| `n8n-nodes-base.mailchimp` | Mailchimp integration | 1.0 |
| `@n8n/n8n-nodes-langchain.openAi` | AI personalization | 1.0 |
| `n8n-nodes-base.googleSheets` | Recipient tracking | 4.5 |
| `n8n-nodes-base.if` | Engagement routing | 2.2 |

#### Drip Campaign Structure

```
Trigger (new subscriber)
  -> Send Email 1 (Welcome)
  -> Wait 3 days
  -> Check Engagement
    -> IF opened: Send Email 2a (Engaged path)
    -> IF not opened: Send Email 2b (Re-engagement)
  -> Wait 3 days
  -> Continue sequence...
```

#### Key Components

1. **Schedule Trigger**: Starts campaigns at specific times
2. **Wait Node**: Manages intervals between emails (3 days optimal)
3. **IF Node**: Routes based on engagement (opens, clicks)
4. **Merge Node**: Brings paths back together

#### Multi-Step Drip Sequence

```javascript
// Code node to track email sequence state
const contact = $json;
const sequence = [
  { day: 0, template: 'welcome', subject: 'Welcome to [Company]!' },
  { day: 3, template: 'value_prop', subject: 'Here\'s what you can achieve...' },
  { day: 7, template: 'case_study', subject: 'See how [Customer] grew 300%' },
  { day: 10, template: 'offer', subject: 'Special offer just for you' },
  { day: 14, template: 'final', subject: 'Last chance: Your offer expires soon' }
];

const currentStep = contact.sequenceStep || 0;
const nextEmail = sequence[currentStep];

if (!nextEmail) {
  return [{ json: { ...contact, sequenceComplete: true } }];
}

return [{
  json: {
    ...contact,
    currentEmail: nextEmail,
    sequenceStep: currentStep,
    nextStep: currentStep + 1
  }
}];
```

#### AI-Personalized Email Generation

```
// OpenAI prompt for personalized email
Generate a personalized email for:
- Name: {{$json.firstName}}
- Company: {{$json.company}}
- Industry: {{$json.industry}}
- Pain point mentioned: {{$json.painPoint}}

Email type: {{$json.currentEmail.template}}
Subject line: {{$json.currentEmail.subject}}

Write in a friendly, professional tone. Include:
1. Personalized greeting using their name
2. Reference to their industry challenges
3. Clear value proposition
4. Single call-to-action
5. P.S. line with urgency element

Keep under 200 words.
```

---

### 3.2 Abandoned Cart Sequences

#### E-commerce Platforms Supported

- **Shopify**: Native trigger node available
- **WooCommerce**: REST API integration
- **Stripe**: Checkout session webhooks
- **Custom**: Webhook from any platform

#### Multi-Channel Recovery Flow

```
Abandoned Cart Event (webhook)
  -> Wait 1 hour
  -> Check if Purchased
    -> IF yes: End sequence
    -> IF no: Continue
  -> Send Email 1 (Cart Reminder)
  -> Wait 24 hours
  -> Check if Purchased
    -> IF no: Send SMS reminder
  -> Wait 48 hours
  -> Check if Purchased
    -> IF no: Send Email 2 (with discount)
  -> Wait 24 hours
  -> Add to Facebook Custom Audience for retargeting
```

#### Recovery Email Sequence

| Timing | Channel | Content | Incentive |
|--------|---------|---------|-----------|
| +1 hour | Email | Cart reminder | None |
| +24 hours | SMS | Gentle nudge | None |
| +48 hours | Email | Urgency + discount | 10% off |
| +72 hours | Email | Final reminder | 15% off |
| +96 hours | Retargeting | Facebook/Instagram ads | Social proof |

#### Cart Recovery Code Example

```javascript
// Code node to format abandoned cart email
const cart = $json;
const cartItems = cart.lineItems || [];

const itemsHtml = cartItems.map(item => `
  <tr>
    <td><img src="${item.image}" width="60" /></td>
    <td>${item.title}</td>
    <td>${item.quantity}</td>
    <td>$${(item.price / 100).toFixed(2)}</td>
  </tr>
`).join('');

const checkoutUrl = `${cart.checkoutUrl}?discount=COMEBACK10`;
const totalValue = cartItems.reduce((sum, item) => sum + (item.price * item.quantity), 0);

return [{
  json: {
    to: cart.email,
    subject: `You left something behind, ${cart.firstName}!`,
    cartItemsHtml: itemsHtml,
    checkoutUrl,
    totalValue: (totalValue / 100).toFixed(2),
    discountCode: 'COMEBACK10',
    firstName: cart.firstName
  }
}];
```

---

### 3.3 Onboarding Sequences

#### Customer Onboarding Flow

```
New Customer (webhook/CRM trigger)
  -> Create in CRM
  -> Send Welcome Email (Day 0)
  -> Schedule Onboarding Call (Calendar)
  -> Wait 1 day
  -> Send "Getting Started" Guide (Day 1)
  -> Wait 2 days
  -> Send Feature Highlight #1 (Day 3)
  -> Wait 4 days
  -> Send Feature Highlight #2 (Day 7)
  -> Wait 7 days
  -> Send "How's it going?" Check-in (Day 14)
  -> Wait 16 days
  -> Send NPS Survey (Day 30)
```

#### Onboarding Workflow Pattern

```
Webhook (new_customer)
  -> Fetch Customer Details
  -> AI Agent: Generate Personalized Welcome
  -> Send Welcome Email
  -> Create Onboarding Task in Project Management
  -> Schedule Calendar Event
  -> Add to Onboarding Drip Sequence
  -> Notify Team via Slack
```

#### Welcome Email AI Prompt

```
You are an onboarding specialist. Generate a warm, personalized welcome email.

Customer Details:
- Name: {{$json.firstName}} {{$json.lastName}}
- Company: {{$json.company}}
- Plan: {{$json.plan}}
- Goals mentioned: {{$json.goals}}
- Industry: {{$json.industry}}

Include:
1. Warm, personalized greeting
2. Excitement about their specific goals
3. 3 quick-start actions relevant to their industry
4. Calendar link for onboarding call
5. Direct contact info for their CSM
6. Mobile app download links

Tone: Enthusiastic but professional. Make them feel valued.
```

---

## 4. Appointment/Booking Workflows

### 4.1 Calendar Integrations

#### Supported Calendar Platforms

| Platform | Node Type | Features |
|----------|-----------|----------|
| Cal.com | `n8n-nodes-base.calTrigger` | Real-time webhooks, 1-3s latency |
| Calendly | `n8n-nodes-base.httpRequest` | API polling or webhooks |
| Google Calendar | `n8n-nodes-base.googleCalendar` | Full CRUD operations |
| Microsoft Outlook | `n8n-nodes-base.microsoftOutlook` | Calendar events |

#### Cal.com Integration

**Webhook Events:**
- `BOOKING_CREATED` - New booking confirmed
- `BOOKING_RESCHEDULED` - Booking time changed
- `BOOKING_CANCELLED` - Booking cancelled
- `MEETING_ENDED` - Meeting completed

**Setup:**
1. Generate API key at cal.com
2. Create Cal API credential in n8n
3. Configure webhook URL in Cal.com settings

#### Booking Workflow Pattern

```
Cal.com Trigger (BOOKING_CREATED)
  -> Fetch Full Booking Details
  -> Create/Update CRM Contact
  -> Send Confirmation Email
  -> Send SMS Reminder Schedule
  -> Create Meeting Prep Task
  -> Notify Assigned Team Member (Slack)
```

#### AI-Powered Booking Assistant

```
Chat Trigger
  -> AI Agent (check availability)
    -> Cal.com Tool: Get Available Slots
    -> AI: Present options to user
  -> User selects time
  -> AI Agent (book meeting)
    -> Cal.com Tool: Create Booking
  -> Send Confirmation
  -> Add to CRM
```

---

### 4.2 Reminder Sequences

#### Multi-Touch Reminder Flow

| Timing | Channel | Content |
|--------|---------|---------|
| Immediately | Email | Booking confirmation + details |
| -24 hours | Email | Reminder + preparation info |
| -2 hours | SMS | Quick reminder with link |
| -15 minutes | SMS | "Starting soon" alert |

#### Reminder Workflow Structure

```
Booking Created
  -> Send Confirmation Email (immediate)
  -> Schedule: 24h Before
    -> Send Reminder Email
    -> Include: Agenda, prep materials, join link
  -> Schedule: 2h Before
    -> Send SMS Reminder
    -> Include: Short message + meeting link
  -> Schedule: 15min Before
    -> Send SMS Alert
    -> "Your meeting with [Name] starts in 15 minutes"
```

#### Dynamic Reminder Scheduling

```javascript
// Code node to calculate reminder times
const booking = $json;
const startTime = new Date(booking.startTime);

const reminders = [
  {
    type: 'email',
    sendAt: new Date(startTime - 24 * 60 * 60 * 1000), // 24h before
    template: 'reminder_24h'
  },
  {
    type: 'sms',
    sendAt: new Date(startTime - 2 * 60 * 60 * 1000), // 2h before
    template: 'reminder_2h'
  },
  {
    type: 'sms',
    sendAt: new Date(startTime - 15 * 60 * 1000), // 15min before
    template: 'reminder_15min'
  }
];

// Filter out reminders in the past
const validReminders = reminders.filter(r => r.sendAt > new Date());

return validReminders.map(reminder => ({
  json: {
    ...booking,
    reminder
  }
}));
```

---

### 4.3 No-Show Follow-ups

#### No-Show Detection Flow

```
Schedule Trigger (every 15 minutes)
  -> Query Recent Meetings (ended in last 15 min)
  -> For Each Meeting:
    -> Check if Attended (CRM/Calendar status)
      -> IF attended: Mark complete, send thank-you
      -> IF no-show: Start no-show sequence
```

#### No-Show Recovery Sequence

| Timing | Action | Content |
|--------|--------|---------|
| +15 min | Email | "We missed you" + reschedule link |
| +24 hours | SMS | Brief follow-up + reschedule |
| +48 hours | Email | Alternative times offered |
| +7 days | Email | Last attempt + ask if still interested |

#### No-Show Workflow Pattern

```
Meeting End Time Passed
  -> Wait 15 minutes
  -> Check Attendance Status
    -> IF no-show:
      -> Log No-Show Event
      -> Update CRM (no-show count)
      -> Send "We Missed You" Email
      -> Wait 24 hours
      -> IF no response: Send SMS
      -> Wait 48 hours
      -> IF no rescheduled: Send final email
      -> IF 3+ no-shows: Flag for sales review
```

#### No-Show Email Template

```javascript
// Code node for no-show email content
const meeting = $json;

const emailContent = {
  to: meeting.attendeeEmail,
  subject: `We missed you, ${meeting.attendeeFirstName}!`,
  body: `
Hi ${meeting.attendeeFirstName},

We noticed you weren't able to make our scheduled meeting today at ${meeting.scheduledTime}.

No worries - things come up! I'd still love to connect and discuss ${meeting.purpose}.

Here are some times that work for me this week:
[CALENDAR_LINK]

Or, if now isn't the right time, just let me know and we can reconnect later.

Best,
${meeting.hostName}

P.S. If you're facing any challenges with [PRODUCT], I'm happy to help via email too!
  `
};

return [{ json: emailContent }];
```

---

## 5. Node Reference Guide

### Trigger Nodes

| Node | Use Case | Cost |
|------|----------|------|
| `webhookTrigger` | Generic webhook endpoint | Free |
| `scheduleTrigger` | Time-based triggers | Free |
| `formTrigger` | Native n8n forms | Free |
| `stripeTrigger` | Stripe events | Free |
| `calTrigger` | Cal.com bookings | Free |
| `hubspotTrigger` | HubSpot events | Free |
| `chatTrigger` | Chat/AI interfaces | Free |

### Action Nodes

| Node | Purpose | Common Operations |
|------|---------|-------------------|
| `httpRequest` | API calls | Any REST API |
| `code` | Custom logic | Data transformation |
| `if` | Conditional routing | True/False paths |
| `switch` | Multi-path routing | Multiple conditions |
| `wait` | Delays | Time intervals |
| `merge` | Combine data | Multiple inputs |
| `splitInBatches` | Process in chunks | Rate limiting |
| `set` | Set/transform data | Field mapping |

### Integration Nodes

| Platform | Node | Key Features |
|----------|------|--------------|
| Stripe | `stripe`, `stripeTrigger` | Payments, subscriptions |
| HubSpot | `hubspot`, `hubspotTrigger` | CRM, marketing |
| GoHighLevel | `highLevel` | CRM, automation |
| Gmail | `gmail` | Email sending |
| SendGrid | `sendGrid` | Bulk email |
| Twilio | `twilio` | SMS, voice |
| Google Sheets | `googleSheets` | Data storage |
| Slack | `slack` | Notifications |
| Cal.com | `calTrigger` | Scheduling |

### AI/LangChain Nodes

| Node | Purpose |
|------|---------|
| `@n8n/n8n-nodes-langchain.openAi` | GPT models |
| `@n8n/n8n-nodes-langchain.agent` | AI agents |
| `@n8n/n8n-nodes-langchain.chainLlm` | LLM chains |
| `@n8n/n8n-nodes-langchain.memoryBufferWindow` | Conversation memory |

---

## 6. Example JSON Structures

### Lead Capture Workflow

```json
{
  "name": "Lead Capture to HubSpot",
  "nodes": [
    {
      "id": "webhook-trigger",
      "name": "Form Submission Webhook",
      "type": "n8n-nodes-base.webhook",
      "typeVersion": 2,
      "position": [0, 0],
      "parameters": {
        "httpMethod": "POST",
        "path": "lead-capture",
        "responseMode": "onReceived"
      }
    },
    {
      "id": "validate-data",
      "name": "Validate Lead Data",
      "type": "n8n-nodes-base.if",
      "typeVersion": 2.2,
      "position": [220, 0],
      "parameters": {
        "conditions": {
          "options": {
            "leftValue": "",
            "caseSensitive": true,
            "typeValidation": "strict"
          },
          "combinator": "and",
          "conditions": [
            {
              "id": "email-exists",
              "leftValue": "={{ $json.email }}",
              "rightValue": "",
              "operator": {
                "type": "string",
                "operation": "notEmpty"
              }
            }
          ]
        }
      }
    },
    {
      "id": "score-lead",
      "name": "Score Lead",
      "type": "n8n-nodes-base.code",
      "typeVersion": 2,
      "position": [440, 0],
      "parameters": {
        "jsCode": "// Lead scoring logic here"
      }
    },
    {
      "id": "create-hubspot-contact",
      "name": "Create HubSpot Contact",
      "type": "n8n-nodes-base.hubspot",
      "typeVersion": 2,
      "position": [660, 0],
      "parameters": {
        "resource": "contact",
        "operation": "create"
      }
    },
    {
      "id": "notify-slack",
      "name": "Notify Sales Team",
      "type": "n8n-nodes-base.slack",
      "typeVersion": 2.2,
      "position": [880, 0],
      "parameters": {
        "channel": "#sales-leads",
        "text": "New lead: {{ $json.email }}"
      }
    }
  ],
  "connections": {
    "Form Submission Webhook": {
      "main": [[{ "node": "Validate Lead Data", "type": "main", "index": 0 }]]
    },
    "Validate Lead Data": {
      "main": [[{ "node": "Score Lead", "type": "main", "index": 0 }]]
    },
    "Score Lead": {
      "main": [[{ "node": "Create HubSpot Contact", "type": "main", "index": 0 }]]
    },
    "Create HubSpot Contact": {
      "main": [[{ "node": "Notify Sales Team", "type": "main", "index": 0 }]]
    }
  }
}
```

### Stripe Payment Workflow

```json
{
  "name": "Stripe Payment Handler",
  "nodes": [
    {
      "id": "stripe-trigger",
      "name": "Stripe Webhook",
      "type": "n8n-nodes-base.stripeTrigger",
      "typeVersion": 1,
      "position": [0, 0],
      "parameters": {
        "events": ["charge.succeeded", "charge.failed", "invoice.payment_failed"]
      }
    },
    {
      "id": "switch-event",
      "name": "Route by Event Type",
      "type": "n8n-nodes-base.switch",
      "typeVersion": 3.2,
      "position": [220, 0],
      "parameters": {
        "dataType": "string",
        "value1": "={{ $json.type }}",
        "rules": {
          "rules": [
            { "value2": "charge.succeeded" },
            { "value2": "charge.failed" },
            { "value2": "invoice.payment_failed" }
          ]
        }
      }
    },
    {
      "id": "send-receipt",
      "name": "Send Receipt Email",
      "type": "n8n-nodes-base.gmail",
      "typeVersion": 2.1,
      "position": [440, -100],
      "parameters": {
        "operation": "send",
        "toList": ["={{ $json.data.object.receipt_email }}"],
        "subject": "Payment Receipt - Thank You!",
        "emailType": "html"
      }
    },
    {
      "id": "handle-failure",
      "name": "Handle Payment Failure",
      "type": "n8n-nodes-base.gmail",
      "typeVersion": 2.1,
      "position": [440, 100],
      "parameters": {
        "operation": "send",
        "subject": "Payment Failed - Action Required"
      }
    }
  ],
  "connections": {
    "Stripe Webhook": {
      "main": [[{ "node": "Route by Event Type", "type": "main", "index": 0 }]]
    },
    "Route by Event Type": {
      "main": [
        [{ "node": "Send Receipt Email", "type": "main", "index": 0 }],
        [{ "node": "Handle Payment Failure", "type": "main", "index": 0 }],
        [{ "node": "Handle Payment Failure", "type": "main", "index": 0 }]
      ]
    }
  }
}
```

### Email Drip Sequence

```json
{
  "name": "Welcome Email Drip Sequence",
  "nodes": [
    {
      "id": "webhook-trigger",
      "name": "New Subscriber",
      "type": "n8n-nodes-base.webhook",
      "typeVersion": 2,
      "position": [0, 0],
      "parameters": {
        "httpMethod": "POST",
        "path": "new-subscriber"
      }
    },
    {
      "id": "send-welcome",
      "name": "Send Welcome Email",
      "type": "n8n-nodes-base.gmail",
      "typeVersion": 2.1,
      "position": [220, 0],
      "parameters": {
        "subject": "Welcome to [Company]!"
      }
    },
    {
      "id": "wait-3-days",
      "name": "Wait 3 Days",
      "type": "n8n-nodes-base.wait",
      "typeVersion": 1.1,
      "position": [440, 0],
      "parameters": {
        "amount": 3,
        "unit": "days"
      }
    },
    {
      "id": "check-engagement",
      "name": "Check if Opened",
      "type": "n8n-nodes-base.if",
      "typeVersion": 2.2,
      "position": [660, 0],
      "parameters": {
        "conditions": {
          "conditions": [
            {
              "leftValue": "={{ $json.emailOpened }}",
              "rightValue": true,
              "operator": { "type": "boolean", "operation": "equals" }
            }
          ]
        }
      }
    },
    {
      "id": "engaged-email",
      "name": "Send Engaged Path Email",
      "type": "n8n-nodes-base.gmail",
      "typeVersion": 2.1,
      "position": [880, -100],
      "parameters": {
        "subject": "Your Next Steps..."
      }
    },
    {
      "id": "re-engage-email",
      "name": "Send Re-engagement Email",
      "type": "n8n-nodes-base.gmail",
      "typeVersion": 2.1,
      "position": [880, 100],
      "parameters": {
        "subject": "Did you miss our first email?"
      }
    }
  ],
  "connections": {
    "New Subscriber": {
      "main": [[{ "node": "Send Welcome Email", "type": "main", "index": 0 }]]
    },
    "Send Welcome Email": {
      "main": [[{ "node": "Wait 3 Days", "type": "main", "index": 0 }]]
    },
    "Wait 3 Days": {
      "main": [[{ "node": "Check if Opened", "type": "main", "index": 0 }]]
    },
    "Check if Opened": {
      "main": [
        [{ "node": "Send Engaged Path Email", "type": "main", "index": 0 }],
        [{ "node": "Send Re-engagement Email", "type": "main", "index": 0 }]
      ]
    }
  }
}
```

### Appointment Reminder Workflow

```json
{
  "name": "Appointment Reminders",
  "nodes": [
    {
      "id": "cal-trigger",
      "name": "New Booking",
      "type": "n8n-nodes-base.calTrigger",
      "typeVersion": 1,
      "position": [0, 0],
      "parameters": {
        "events": ["BOOKING_CREATED"]
      }
    },
    {
      "id": "send-confirmation",
      "name": "Send Confirmation",
      "type": "n8n-nodes-base.gmail",
      "typeVersion": 2.1,
      "position": [220, 0],
      "parameters": {
        "subject": "Booking Confirmed!"
      }
    },
    {
      "id": "wait-until-24h-before",
      "name": "Wait Until 24h Before",
      "type": "n8n-nodes-base.wait",
      "typeVersion": 1.1,
      "position": [440, 0],
      "parameters": {
        "resume": "specificTime",
        "dateTime": "={{ DateTime.fromISO($json.startTime).minus({ hours: 24 }).toISO() }}"
      }
    },
    {
      "id": "send-reminder-email",
      "name": "Send Reminder Email",
      "type": "n8n-nodes-base.gmail",
      "typeVersion": 2.1,
      "position": [660, 0],
      "parameters": {
        "subject": "Reminder: Your appointment tomorrow"
      }
    },
    {
      "id": "wait-until-2h-before",
      "name": "Wait Until 2h Before",
      "type": "n8n-nodes-base.wait",
      "typeVersion": 1.1,
      "position": [880, 0],
      "parameters": {
        "resume": "specificTime",
        "dateTime": "={{ DateTime.fromISO($json.startTime).minus({ hours: 2 }).toISO() }}"
      }
    },
    {
      "id": "send-sms-reminder",
      "name": "Send SMS Reminder",
      "type": "n8n-nodes-base.twilio",
      "typeVersion": 1,
      "position": [1100, 0],
      "parameters": {
        "operation": "sendSms",
        "to": "={{ $json.attendeePhone }}",
        "message": "Reminder: Your appointment is in 2 hours. Join here: {{ $json.meetingLink }}"
      }
    }
  ],
  "connections": {
    "New Booking": {
      "main": [[{ "node": "Send Confirmation", "type": "main", "index": 0 }]]
    },
    "Send Confirmation": {
      "main": [[{ "node": "Wait Until 24h Before", "type": "main", "index": 0 }]]
    },
    "Wait Until 24h Before": {
      "main": [[{ "node": "Send Reminder Email", "type": "main", "index": 0 }]]
    },
    "Send Reminder Email": {
      "main": [[{ "node": "Wait Until 2h Before", "type": "main", "index": 0 }]]
    },
    "Wait Until 2h Before": {
      "main": [[{ "node": "Send SMS Reminder", "type": "main", "index": 0 }]]
    }
  }
}
```

---

## Sources and References

### Lead Capture
- [n8n Lead Management Automation](https://n8n.io/automate-lead-management/)
- [Automate Lead Generation with n8n - KumoHQ](https://www.kumohq.co/blog/automate-lead-generation-with-n8n)
- [Real-Time Lead Qualification with Jotform](https://n8n.io/workflows/9815-real-time-lead-qualification-scoring-and-crm-integration-system-using-jotform/)
- [HubSpot Lead Scoring Workflow](https://n8n.io/workflows/7343-automated-lead-capture-scoring-and-crm-integration-with-hubspot-clearbit-and-slack/)
- [GoHighLevel n8n Integration](https://n8n.io/integrations/highlevel/)
- [n8n vs Zapier for HighLevel](https://ghl-services-playbooks-automation-crm-marketing.ghost.io/n8n-vs-zapier-workflow-automation-for-highlevel-users-2025-comparison-guide/)

### Payment/Invoice
- [Stripe Trigger Documentation](https://n8n.io/integrations/stripe-trigger/)
- [Generate Stripe Invoice Workflow](https://n8n.io/workflows/2675-generate-stripe-invoice-and-send-it-by-email/)
- [Auto-Send PDF Invoices with Stripe](https://n8n.io/workflows/8030-auto-send-pdf-invoices-with-stripe-payment-triggers-and-gmail/)
- [Stripe n8n Integration Guide](https://www.eesel.ai/blog/stripe-integrations-with-n8n)

### Email Sequences
- [Gmail Campaign Sender](https://n8n.io/workflows/2137-gmail-campaign-sender-bulk-send-emails-and-follow-up-automatically-if-no-reply/)
- [Smart Email Outreach Sequence](https://n8n.io/workflows/2833-smart-email-outreach-sequence-ai-powered-and-customizable/)
- [Drip Campaign Automation](https://n8n.io/drip-campaign-automation/)
- [Abandoned Cart Recovery - Shopify](https://n8n.io/workflows/6111-automated-abandoned-cart-recovery-emails-for-shopify-stores/)
- [Multi-Channel Cart Recovery](https://n8n.io/workflows/11805-recover-shopify-abandoned-carts-with-email-sms-whatsapp-and-facebook-retargeting/)
- [Customer Onboarding with HubSpot](https://n8n.io/workflows/5676-customer-onboarding-automation-with-hubspot-email-sequences-and-team-alerts/)

### Appointment/Booking
- [Cal.com n8n Integration](https://hackceleration.com/cal-com-n8n/)
- [Voice-Based Appointment Booking](https://n8n.io/workflows/5670-voice-based-appointment-booking-system-with-elevenlabs-ai-and-calcom/)
- [Appointment Leads Follow-up](https://n8n.io/workflows/2342-handling-appointment-leads-and-follow-up-with-twilio-calcom-and-ai/)
- [Patient Appointment Reminders](https://n8n.io/workflows/6548-send-automated-patient-appointment-reminders-via-email-and-sms-with-multi-database-support/)
- [Client Journey Reminders](https://n8n.io/workflows/6491-automated-client-journey-appointment-reminders-and-follow-ups-with-twilio/)

---

*Document Version: 1.0*
*Last Updated: December 31, 2025*
*Status: RESEARCH ONLY - Implementation pending*

metadata:
{"filename": "N8N-REVENUE-PIPELINES.md", "path": "E:/genesis-system/docs/research\\N8N-REVENUE-PIPELINES.md"}


id: a7b4d9d3-c35d-53ee-9b96-11d73ac5f40a
domain: knowledge_base
source: doc_ingest
timestamp: 2026-01-06T20:00:36.667427
created_at: 2026-01-06 10:00:36
content:
DOCUMENT: NEURAL_OS_FAILURE_ANALYSIS.md
# ⚠️ PRE-MORTEM: NEURAL OS FAILURE ANALYSIS

**Premise**: "What could kill the Genesis Neural OS?"
**Authority**: Lead Architect Analysis.

## 1. THE "INSANITY LOOP" (Reflexion Failure)
*   **The Bug**: If an error is **Permanent** (e.g., GHL 403 Forbidden, API Key Revoked), the `@reflexion_loop` will blindly retry `N` times.
*   **Impact**: Wasted tokens, API rate limits hit, slowing down the entire swarm.
*   **The Fix**: **Error Classification**. The decorator must distinguish between `RetryableError` (Network flake, Timeout) and `FatalError` (Auth, Logic). 
    *   *Action*: Update `reflexion.py` to catch specific exceptions and abort immediately on 401/403.

## 2. CONTEXT WINDOW EXPLOSION (Sequential Thinking Failure)
*   **The Bug**: The `sequential-thinking` MCP encourages "Plan -> Hypothesize -> Critique -> ...". If the agent gets stuck in a "Thinking Loop" without concluding, it fills the context window (128k/200k tokens).
*   **Impact**: The agent crashes before executing the *Action*.
*   **The Fix**: **Thought Limiter**. Enforce a "Max Thoughts" hard limit (e.g., 5 steps) in the MCP or the System Prompt.

## 3. "THE HOLLOW SHELL" (Integration Failure)
*   **The Bug**: `reflexion.py` exists, but `contractor_ghl.py` *isn't importing it*. The logic catches nothing because it's not wrapped.
*   **Impact**: False sense of security. The "Neural OS" is just a library file, not an active circuit.
*   **The Fix**: **Hard Binding**. I must edit `swarms/contractor_ghl.py` to import and apply `@reflexion_loop` to its critical methods (`deploy_snapshot`, `check_permissions`).

## 4. HALLUCINATED SUCCESS (Metric Failure)
*   **The Bug**: An agent runs `sequential_thinking`, concludes "I should do X", and then *says* "I did X" without actually calling the tool.
*   **Impact**: Logs show success, but reality is unchanged.
*   **The Fix**: **Tool-Use Enforcement**. The `Reflexion` loop must verify that a *Tool Call* actually occurred in the trace, or check the *External State* (e.g., "Does the file exist?") before accepting "Success".

---

## 🛡️ HARDENING PLAN (IMMEDIATE)
1.  **Refactor `reflexion.py`**: Add `FatalError` logic.
2.  **Bind Decorators**: Apply to `contractor_ghl.py`.
3.  **Update Prompt**: Explicitly instruct agents "You must CALL A TOOL after Thinking." in `MISSION_CONTROL.md` or System Prompt.

metadata:
{"filename": "NEURAL_OS_FAILURE_ANALYSIS.md", "path": "E:/genesis-system/docs/research\\NEURAL_OS_FAILURE_ANALYSIS.md"}


id: 3bbaa4a2-8d84-5a71-a051-0601990c012a
domain: knowledge_base
source: doc_ingest
timestamp: 2026-01-06T20:00:37.981371
created_at: 2026-01-06 10:00:37
content:
DOCUMENT: ADVANCED_MEMORY_BLUEPRINT.md
# 🧠 ADVANCED MEMORY BLUEPRINT: THE GENESIS EXOCORTEX
**Command**: "World's Most Advanced Memory System" (2026-01-04)
**Execution Mode**: TURBO (Agentic Teams)
**Status**: IN PROGRESS

## 1. THE VISION: FROM "DATABASE" TO "EXOCORTEX"
A database stores data. An **Exocortex** *thinks* with data.
*   **Current State (1%)**: We have a connected database (Redis/Qdrant) with a "Poison Shield" (Pydantic).
*   **Target State (100%)**: A self-organizing, self-optimizing, graph-associative, multi-agent hive mind.

## 2. THE 6-TIER ARCHITECTURE (PATENT-BACKED)

### 🛡️ TIER 1: THE SHIELD (Reliability & Hardening)
*   **Patents**: **P1 (Crypto Validation)**, **P4 (Immutable Audit)**, **P8 (Privacy)**.
*   **Focus**: "Never Forget, Never Crash, Never Leak."
*   **Team**: **Team Shield** (Managed by Gemini Flash 2.0)
*   **Tasks**:
    1.  [x] **Poison Shield**: Pydantic Validation (Complete).
    2.  [ ] **Circuit Breakers**: Handle Elestio latency gracefully.
    3.  [ ] **Audit Trail (P4)**: Log every memory hash to `data/audit_log.json`.

### 🕸️ TIER 2: THE SYNAPSE (Graph Association)
*   **Patents**: **P5 (Multi-Model Consensus)**, **P6 (Dynamic Confidence)**.
*   **Focus**: "Connect the Dots with Confidence."
*   **Team**: **Team Synapse** (Managed by Gemini Pro 1.5)
*   **Tasks**:
    4.  [ ] **Graph RAG**: Traverse relations.
    5.  [ ] **Confidence Scoring (P6)**: Add `confidence_score` (0.0-1.0) to every memory.
    6.  [ ] **Consensus (P5)**: Require 2+ sources for "High Impact" memories.

### 💤 TIER 3: THE DREAM (Consolidation & Optimization)
*   **Patents**: **P2 (Info Currency)**, **P9 (Automated Thresholds)**.
*   **Focus**: "Learn while Sleeping."
*   **Team**: **Team Dream** (Managed by Claude Opus)
*   **Tasks**:
    7.  [ ] **The Hippocampus Loop**: Move Working -> Episodic.
    8.  [ ] **Adaptive Thresholds (P9)**: Auto-adjust matching thresholds based on recall success.

### 🔮 TIER 4: THE ORACLE (Predictive & Safety)
*   **Patents**: **P7 (Hallucination Detection)**, **P3 (Risk Assessment)**.
*   **Tasks**:
    10. [ ] **Hallucination Check (P7)**: Cross-reference output against Knowledge Graph.
    11. [ ] **Risk Gating (P3)**: Block "High Risk" actions without Human Authorization.

### 🐝 TIER 5: THE HIVE (Swarm Synchronization)
*   **Focus**: "One Mind, Many Bodies."
*   **Tasks**:
    12. [ ] **Blackboard 2.0**: Real-time state sync between `contractor_ghl` and `storm`.
    13. [ ] **Conflict Resolution**: Merging divergent memory streams.

## 3. EXECUTION PLAN (TURBO)
We execute in parallel streams.

*   **Stream A (Shield)**: Finish Circuit Breakers (Genesis Heartmon).
*   **Stream B (Synapse)**: Build `GraphAssociationEngine` to link memories.
*   **Stream C (Dream)**: Build `ConsolidationService` for background optimization.

## 4. IMMEDIATE ACTION: "TEAM SYNAPSE"
We begin with **Tier 2: The Synapse**.
A memory system without connections is just a pile of rocks. Providing structure makes it a *castle*.
**Goal**: Modify `genesis_memory_cortex.py` to support `relations` and `links`.

metadata:
{"filename": "ADVANCED_MEMORY_BLUEPRINT.md", "path": "E:/genesis-system/docs/plans\\ADVANCED_MEMORY_BLUEPRINT.md"}


id: 5d5b5d28-5b85-54ef-ba0a-377fbfc09550
domain: knowledge_base
source: doc_ingest
timestamp: 2026-01-06T20:00:40.052689
created_at: 2026-01-06 10:00:40
content:
DOCUMENT: MEMORY_RELIABILITY_GROWTH_MANIFEST.md
# 🛡️ MEMORY RELIABILITY GROWTH MANIFEST
**Philosophy**: "Connectivity is 1%. Resilience is 99%."
**Objective**: Move Genesis Memory Cortex from "Prototype" to "Enterprise Hardened".

## 1. THE PHYSICS OF FAILURE (Identifying the 99% Gap)
We firmly acknowledge the system is currently **Fragile**. Here are the noise factors we have ignored:

### A. Network Noise (The "Blinking Light" Problem)
*   [ ] **Jitter/Latency**: What if Elestio takes 2.5s? (Current: Blocks thread).
*   [ ] **Packet Loss**: What if 1 in 100 packets drops? (Current: Crash).
*   [ ] **Throttling**: What if we hit API limits? (Current: Crash).

### B. Data Integrity (The "Poison Pill" Problem)
*   [ ] **Schema Drift**: What if `metadata` is missing a key? (Current: KeyError).
*   [ ] **Payload Size**: What if we send a 10MB memory? (Current: OOM/Timeout).
*   [ ] **Encoding**: What if content has emojis/binary? (Current: UnicodeError).

### C. Logic Stress (The "Dementia" Problem)
*   [ ] **Race Conditions**: Two agents write same ID? (Current: Last write wins).
*   [ ] **Cache Invalidation**: Redis vs Postgres sync? (Current: Assumed perfect).
*   [ ] **Orphaned Locks**: Agent dies holding lock? (Current: permanent deadlock).

## 2. THE HARDENING ROADMAP (The 100-Point Checklist)

### 🟢 Phase 1: Defensive Coding (Input/Output) - **IMMEDIATE**
1.  **[ ] Pydantic Validation**: Enforce strict schema on *all* inputs.
2.  **[ ] Payload Caps**: Reject memories > 1MB immediately.
3.  **[ ] Sanitization**: Strip dangerous chars/executables from content.

### 🔵 Phase 2: Resilience Patterns (The Network Layer)
4.  **[ ] Circuit Breaker**: If Redis fails 5x, open circuit for 30s (don't crash loop).
5.  **[ ] Exponential Backoff**: Retry 1s, 2s, 4s, 8s.
6.  **[ ] Dead Letter Queue (DLQ)**: Save failed writes to disk (`data/failed_memories/`) for later replay.

### 🟠 Phase 3: Observability (The Nervous System)
7.  **[ ] Structured Logging**: JSON logs with trace IDs.
8.  **[ ] Metric Export**: Push stats (latency/count) to Prometheus/File.
9.  **[ ] Health Endpoint**: A dedicated `/health` route for the Cortex.

### 🔴 Phase 4: Chaos Engineering (Testing Failure)
10. **[ ] The Monkey**: A script that randomly disconnects Redis during writes.
11. **[ ] The Flood**: A script that sends 1000 memories/sec.

## 3. MANAGER AGENT PROTOCOL
*   **Rule 1**: No task is "Done" until it passes a *Chaos Test* (e.g., "It works even if I disconnect Wifi").
*   **Rule 2**: We do not proceed to Revenue until Phase 1 & 2 are complete.

metadata:
{"filename": "MEMORY_RELIABILITY_GROWTH_MANIFEST.md", "path": "E:/genesis-system/docs/plans\\MEMORY_RELIABILITY_GROWTH_MANIFEST.md"}


