memory-journal-mcp 7.7.0 → 8.0.0

package/skills/cloudflare/references/agents-sdk/patterns.md

@@ -0,0 +1,215 @@
+# Patterns & Use Cases
+
+## AI Chat w/Tools
+
+**Server (AIChatAgent):**
+
+```ts
+import { AIChatAgent } from 'agents'
+import { openai } from '@ai-sdk/openai'
+import { tool } from 'ai'
+import { z } from 'zod'
+
+export class ChatAgent extends AIChatAgent<Env> {
+  async onChatMessage(onFinish) {
+    return this.streamText({
+      model: openai('gpt-4'),
+      messages: this.messages, // Auto-managed
+      tools: {
+        getWeather: tool({
+          description: 'Get current weather',
+          parameters: z.object({ city: z.string() }),
+          execute: async ({ city }) => `Weather in ${city}: Sunny, 72°F`,
+        }),
+        searchDocs: tool({
+          description: 'Search documentation',
+          parameters: z.object({ query: z.string() }),
+          execute: async ({ query }) =>
+            JSON.stringify(
+              this.sql<{
+                title
+                content
+              }>`SELECT title, content FROM docs WHERE content LIKE ${'%' + query + '%'}`
+            ),
+        }),
+      },
+      onFinish,
+    })
+  }
+}
+```
+
+**Client (React):**
+
+```tsx
+import { useAgent } from 'agents/react'
+import { useAgentChat } from 'agents/ai-react'
+
+function ChatUI() {
+  const agent = useAgent({ agent: 'ChatAgent' })
+  const { messages, input, handleInputChange, handleSubmit, isLoading } = useAgentChat({ agent })
+
+  return (
+    <div>
+      {messages.map((m) => (
+        <div key={m.id}>
+          {m.role}: {m.content}
+        </div>
+      ))}
+      <form onSubmit={handleSubmit}>
+        <input value={input} onChange={handleInputChange} disabled={isLoading} />
+        <button disabled={isLoading}>Send</button>
+      </form>
+    </div>
+  )
+}
+```
+
+## Human-in-the-Loop (Client Tools)
+
+Server defines tool, client executes:
+
+```ts
+// Server
+export class ChatAgent extends AIChatAgent<Env> {
+  async onChatMessage(onFinish) {
+    return this.streamText({
+      model: openai('gpt-4'),
+      messages: this.messages,
+      tools: {
+        confirmAction: tool({
+          description: 'Ask user to confirm',
+          parameters: z.object({ action: z.string() }),
+          execute: 'client', // Client-side execution
+        }),
+      },
+      onFinish,
+    })
+  }
+}
+
+// Client
+const { messages } = useAgentChat({
+  agent,
+  onToolCall: async (toolCall) => {
+    if (toolCall.toolName === 'confirmAction') {
+      return { confirmed: window.confirm(`Confirm: ${toolCall.args.action}?`) }
+    }
+  },
+})
+```
+
+## Task Queue & Scheduled Processing
+
+```ts
+export class TaskAgent extends Agent<Env> {
+  onStart() {
+    this.schedule('*/5 * * * *', 'processQueue', {}) // Every 5 min
+    this.schedule('0 0 * * *', 'dailyCleanup', {}) // Daily
+  }
+
+  async onRequest(req: Request) {
+    await this.queue('processVideo', { videoId: (await req.json()).videoId })
+    return Response.json({ queued: true })
+  }
+
+  async processQueue() {
+    const tasks = await this.dequeue(10)
+    for (const task of tasks) {
+      if (task.name === 'processVideo') await this.processVideo(task.data.videoId)
+    }
+  }
+
+  async dailyCleanup() {
+    this.sql`DELETE FROM logs WHERE created_at < ${Date.now() - 86400000}`
+  }
+}
+```
+
+## Manual WebSocket Chat
+
+Custom protocols (non-AI):
+
+```ts
+export class ChatAgent extends Agent<Env> {
+  async onConnect(conn: Connection, ctx: ConnectionContext) {
+    conn.accept()
+    conn.setState({ userId: ctx.request.headers.get('X-User-ID') || 'anon' })
+    conn.send(JSON.stringify({ type: 'history', messages: this.state.messages }))
+  }
+
+  async onMessage(conn: Connection, msg: WSMessage) {
+    const newMsg = {
+      userId: conn.state.userId,
+      text: JSON.parse(msg as string).text,
+      timestamp: Date.now(),
+    }
+    this.setState({ messages: [...this.state.messages, newMsg] })
+    this.connections.forEach((c) => c.send(JSON.stringify(newMsg)))
+  }
+}
+```
+
+## Email Processing w/AI
+
+```ts
+export class EmailAgent extends Agent<Env> {
+  async onEmail(email: AgentEmail) {
+    const [text, from, subject] = [
+      await email.text(),
+      email.from,
+      email.headers.get('subject') || '',
+    ]
+    this.sql`INSERT INTO emails (from_addr, subject, body) VALUES (${from}, ${subject}, ${text})`
+
+    const { text: summary } = await generateText({
+      model: openai('gpt-4o-mini'),
+      prompt: `Summarize: ${subject}\n\n${text}`,
+    })
+
+    this.connections.forEach((c) => c.send(JSON.stringify({ type: 'new_email', from, summary })))
+    if (summary.includes('urgent')) await this.schedule(0, 'sendAutoReply', { to: from })
+  }
+}
+```
+
+## Real-time Collaboration
+
+```ts
+export class GameAgent extends Agent<Env> {
+  initialState = { players: [], gameStarted: false }
+
+  async onConnect(conn: Connection, ctx: ConnectionContext) {
+    conn.accept()
+    const playerId = ctx.request.headers.get('X-Player-ID') || crypto.randomUUID()
+    conn.setState({ playerId })
+
+    const newPlayer = { id: playerId, score: 0 }
+    this.setState({ ...this.state, players: [...this.state.players, newPlayer] })
+    this.connections.forEach((c) =>
+      c.send(JSON.stringify({ type: 'player_joined', player: newPlayer }))
+    )
+  }
+
+  async onMessage(conn: Connection, msg: WSMessage) {
+    const m = JSON.parse(msg as string)
+
+    if (m.type === 'move') {
+      this.setState({
+        ...this.state,
+        players: this.state.players.map((p) =>
+          p.id === conn.state.playerId ? { ...p, score: p.score + m.points } : p
+        ),
+      })
+      this.connections.forEach((c) =>
+        c.send(JSON.stringify({ type: 'player_moved', playerId: conn.state.playerId }))
+      )
+    }
+
+    if (m.type === 'start' && this.state.players.length >= 2) {
+      this.setState({ ...this.state, gameStarted: true })
+      this.connections.forEach((c) => c.send(JSON.stringify({ type: 'game_started' })))
+    }
+  }
+}
+```

package/skills/cloudflare/references/ai-gateway/README.md

@@ -0,0 +1,176 @@
+# Cloudflare AI Gateway
+
+Expert guidance for implementing Cloudflare AI Gateway - a universal gateway for AI model providers with analytics, caching, rate limiting, and routing capabilities.
+
+## When to Use This Reference
+
+- Setting up AI Gateway for any AI provider (OpenAI, Anthropic, Workers AI, etc.)
+- Implementing caching, rate limiting, or request retry/fallback
+- Configuring dynamic routing with A/B testing or model fallbacks
+- Managing provider API keys securely with BYOK
+- Adding security features (guardrails, DLP)
+- Setting up observability with logging and custom metadata
+- Debugging AI Gateway requests or optimizing configurations
+
+## Quick Start
+
+**What's your setup?**
+
+- **Using Vercel AI SDK** → Pattern 1 (recommended) - see [sdk-integration.md](./sdk-integration.md)
+- **Using OpenAI SDK** → Pattern 2 - see [sdk-integration.md](./sdk-integration.md)
+- **Cloudflare Worker + Workers AI** → Pattern 3 - see [sdk-integration.md](./sdk-integration.md)
+- **Direct HTTP (any language)** → Pattern 4 - see [configuration.md](./configuration.md)
+- **Framework (LangChain, etc.)** → See [sdk-integration.md](./sdk-integration.md)
+
+## Pattern 1: Vercel AI SDK (Recommended)
+
+Most modern pattern using official `ai-gateway-provider` package with automatic fallbacks.
+
+```typescript
+import { createAiGateway } from 'ai-gateway-provider'
+import { createOpenAI } from '@ai-sdk/openai'
+import { generateText } from 'ai'
+
+const gateway = createAiGateway({
+  accountId: process.env.CF_ACCOUNT_ID,
+  gateway: process.env.CF_GATEWAY_ID,
+})
+
+const openai = createOpenAI({
+  apiKey: process.env.OPENAI_API_KEY,
+})
+
+// Single model
+const { text } = await generateText({
+  model: gateway(openai('gpt-4o')),
+  prompt: 'Hello',
+})
+
+// Automatic fallback array
+const { text } = await generateText({
+  model: gateway([
+    openai('gpt-4o'), // Try first
+    anthropic('claude-sonnet-4-5'), // Fallback
+  ]),
+  prompt: 'Hello',
+})
+```
+
+**Install:** `npm install ai-gateway-provider ai @ai-sdk/openai @ai-sdk/anthropic`
+
+## Pattern 2: OpenAI SDK
+
+Drop-in replacement for OpenAI API with multi-provider support.
+
+```typescript
+import OpenAI from 'openai'
+
+const client = new OpenAI({
+  apiKey: process.env.OPENAI_API_KEY,
+  baseURL: `https://gateway.ai.cloudflare.com/v1/${accountId}/${gatewayId}/compat`,
+  defaultHeaders: {
+    'cf-aig-authorization': `Bearer ${cfToken}`, // For authenticated gateways
+  },
+})
+
+// Switch providers by changing model format: {provider}/{model}
+const response = await client.chat.completions.create({
+  model: 'openai/gpt-4o', // or 'anthropic/claude-sonnet-4-5'
+  messages: [{ role: 'user', content: 'Hello!' }],
+})
+```
+
+## Pattern 3: Workers AI Binding
+
+For Cloudflare Workers using Workers AI.
+
+```typescript
+export default {
+  async fetch(request, env, ctx) {
+    const response = await env.AI.run(
+      '@cf/meta/llama-3-8b-instruct',
+      { messages: [{ role: 'user', content: 'Hello!' }] },
+      {
+        gateway: {
+          id: 'my-gateway',
+          metadata: { userId: '123', team: 'engineering' },
+        },
+      }
+    )
+
+    return Response.json(response)
+  },
+}
+```
+
+## Headers Quick Reference
+
+| Header                 | Purpose          | Example          | Notes                                  |
+| ---------------------- | ---------------- | ---------------- | -------------------------------------- |
+| `cf-aig-authorization` | Gateway auth     | `Bearer {token}` | Required for authenticated gateways    |
+| `cf-aig-metadata`      | Tracking         | `{"userId":"x"}` | Max 5 entries, flat structure          |
+| `cf-aig-cache-ttl`     | Cache duration   | `3600`           | Seconds, min 60, max 2592000 (30 days) |
+| `cf-aig-skip-cache`    | Bypass cache     | `true`           | -                                      |
+| `cf-aig-cache-key`     | Custom cache key | `my-key`         | Must be unique per response            |
+| `cf-aig-collect-log`   | Skip logging     | `false`          | Default: true                          |
+| `cf-aig-cache-status`  | Cache hit/miss   | Response only    | `HIT` or `MISS`                        |
+
+## In This Reference
+
+| File                                       | Purpose                                                      |
+| ------------------------------------------ | ------------------------------------------------------------ |
+| [sdk-integration.md](./sdk-integration.md) | Vercel AI SDK, OpenAI SDK, Workers binding patterns          |
+| [configuration.md](./configuration.md)     | Dashboard setup, wrangler, API tokens                        |
+| [features.md](./features.md)               | Caching, rate limits, guardrails, DLP, BYOK, unified billing |
+| [dynamic-routing.md](./dynamic-routing.md) | Fallbacks, A/B testing, conditional routing                  |
+| [troubleshooting.md](./troubleshooting.md) | Debugging, errors, observability, gotchas                    |
+
+## Reading Order
+
+| Task             | Files                                               |
+| ---------------- | --------------------------------------------------- |
+| First-time setup | README + [configuration.md](./configuration.md)     |
+| SDK integration  | README + [sdk-integration.md](./sdk-integration.md) |
+| Enable caching   | README + [features.md](./features.md)               |
+| Setup fallbacks  | README + [dynamic-routing.md](./dynamic-routing.md) |
+| Debug errors     | README + [troubleshooting.md](./troubleshooting.md) |
+
+## Architecture
+
+AI Gateway acts as a proxy between your application and AI providers:
+
+```
+Your App → AI Gateway → AI Provider (OpenAI, Anthropic, etc.)
+         ↓
+    Analytics, Caching, Rate Limiting, Logging
+```
+
+**Key URL patterns:**
+
+- Unified API (OpenAI-compatible): `https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/compat/chat/completions`
+- Provider-specific: `https://gateway.ai.cloudflare.com/v1/{account_id}/{gateway_id}/{provider}/{endpoint}`
+- Dynamic routes: Use route name instead of model: `dynamic/{route-name}`
+
+## Gateway Types
+
+1. **Unauthenticated Gateway**: Open access (not recommended for production)
+2. **Authenticated Gateway**: Requires `cf-aig-authorization` header with Cloudflare API token (recommended)
+
+## Provider Authentication Options
+
+1. **Unified Billing**: Use AI Gateway billing to pay for inference (keyless mode - no provider API key needed)
+2. **BYOK (Store Keys)**: Store provider API keys in Cloudflare dashboard
+3. **Request Headers**: Include provider API key in each request
+
+## Related Skills
+
+- [Workers AI](../workers-ai/README.md) - For `env.AI.run()` details
+- [Agents SDK](../agents-sdk/README.md) - For stateful AI patterns
+- [Vectorize](../vectorize/README.md) - For RAG patterns with embeddings
+
+## Resources
+
+- [Official Docs](https://developers.cloudflare.com/ai-gateway/)
+- [API Reference](https://developers.cloudflare.com/api/resources/ai_gateway/)
+- [Provider Guides](https://developers.cloudflare.com/ai-gateway/usage/providers/)
+- [Discord Community](https://discord.cloudflare.com)

package/skills/cloudflare/references/ai-gateway/configuration.md

@@ -0,0 +1,117 @@
+# Configuration & Setup
+
+## Creating a Gateway
+
+### Dashboard
+
+AI > AI Gateway > Create Gateway > Configure (auth, caching, rate limiting, logging)
+
+### API
+
+```bash
+curl -X POST https://api.cloudflare.com/client/v4/accounts/{account_id}/ai-gateway/gateways \
+  -H "Authorization: Bearer $CF_API_TOKEN" -H "Content-Type: application/json" \
+  -d '{"id":"my-gateway","cache_ttl":3600,"rate_limiting_interval":60,"rate_limiting_limit":100,"collect_logs":true}'
+```
+
+**Naming:** lowercase alphanumeric + hyphens (e.g., `prod-api`, `dev-chat`)
+
+## Wrangler Integration
+
+```toml
+[ai]
+binding = "AI"
+
+[[ai.gateway]]
+id = "my-gateway"
+```
+
+```bash
+wrangler secret put CF_API_TOKEN
+wrangler secret put OPENAI_API_KEY  # If not using BYOK
+```
+
+## Authentication
+
+### Gateway Auth (protects gateway access)
+
+```typescript
+const client = new OpenAI({
+  baseURL: `https://gateway.ai.cloudflare.com/v1/${accountId}/${gatewayId}/openai`,
+  defaultHeaders: { 'cf-aig-authorization': `Bearer ${cfToken}` },
+})
+```
+
+### Provider Auth Options
+
+**1. Unified Billing (keyless)** - pay through Cloudflare, no provider key:
+
+```typescript
+const client = new OpenAI({
+  baseURL: `https://gateway.ai.cloudflare.com/v1/${accountId}/${gatewayId}/openai`,
+  defaultHeaders: { 'cf-aig-authorization': `Bearer ${cfToken}` },
+})
+```
+
+Supports: OpenAI, Anthropic, Google AI Studio
+
+**2. BYOK** - store keys in dashboard (Provider Keys > Add), no key in code
+
+**3. Request Headers** - pass provider key per request:
+
+```typescript
+const client = new OpenAI({
+  apiKey: process.env.OPENAI_API_KEY,
+  baseURL: `https://gateway.ai.cloudflare.com/v1/${accountId}/${gatewayId}/openai`,
+  defaultHeaders: { 'cf-aig-authorization': `Bearer ${cfToken}` },
+})
+```
+
+## API Token Permissions
+
+- **Gateway management:** AI Gateway - Read + Edit
+- **Gateway access:** AI Gateway - Read (minimum)
+
+## Gateway Management API
+
+```bash
+# List
+curl https://api.cloudflare.com/client/v4/accounts/{account_id}/ai-gateway/gateways \
+  -H "Authorization: Bearer $CF_API_TOKEN"
+
+# Get
+curl .../gateways/{gateway_id}
+
+# Update
+curl -X PUT .../gateways/{gateway_id} \
+  -d '{"cache_ttl":7200,"rate_limiting_limit":200}'
+
+# Delete
+curl -X DELETE .../gateways/{gateway_id}
+```
+
+## Getting IDs
+
+- **Account ID:** Dashboard > Overview > Copy
+- **Gateway ID:** AI Gateway > Gateway name column
+
+## Python Example
+
+```python
+from openai import OpenAI
+import os
+
+client = OpenAI(
+    api_key=os.environ.get("OPENAI_API_KEY"),
+    base_url=f"https://gateway.ai.cloudflare.com/v1/{os.environ['CF_ACCOUNT_ID']}/{os.environ['GATEWAY_ID']}/openai",
+    default_headers={"cf-aig-authorization": f"Bearer {os.environ['CF_API_TOKEN']}"}
+)
+```
+
+## Best Practices
+
+1. **Always authenticate gateways in production**
+2. **Use BYOK or unified billing** - secrets out of code
+3. **Environment-specific gateways** - separate dev/staging/prod
+4. **Set rate limits** - prevent runaway costs
+5. **Enable logging** - track usage, debug issues

package/skills/cloudflare/references/ai-gateway/dynamic-routing.md

@@ -0,0 +1,88 @@
+# Dynamic Routing
+
+Configure complex routing in dashboard without code changes. Use route names instead of model names.
+
+## Usage
+
+```typescript
+const response = await client.chat.completions.create({
+  model: 'dynamic/smart-chat', // Route name from dashboard
+  messages: [{ role: 'user', content: 'Hello!' }],
+})
+```
+
+## Node Types
+
+| Node             | Purpose            | Use Case                        |
+| ---------------- | ------------------ | ------------------------------- |
+| **Conditional**  | Branch on metadata | Paid vs free users, geo routing |
+| **Percentage**   | A/B split traffic  | Model testing, gradual rollouts |
+| **Rate Limit**   | Enforce quotas     | Per-user/team limits            |
+| **Budget Limit** | Cost quotas        | Per-user spending caps          |
+| **Model**        | Call provider      | Final destination               |
+
+## Metadata
+
+Pass via header (max 5 entries, flat only):
+
+```typescript
+headers: {
+  'cf-aig-metadata': JSON.stringify({
+    userId: 'user-123',
+    tier: 'pro',
+    region: 'us-east'
+  })
+}
+```
+
+## Common Patterns
+
+**Multi-model fallback:**
+
+```
+Start → GPT-4 → On error: Claude → On error: Llama
+```
+
+**Tiered access:**
+
+```
+Conditional: tier == 'enterprise' → GPT-4 (no limit)
+Conditional: tier == 'pro' → Rate Limit 1000/hr → GPT-4o
+Conditional: tier == 'free' → Rate Limit 10/hr → GPT-4o-mini
+```
+
+**Gradual rollout:**
+
+```
+Percentage: 10% → New model, 90% → Old model
+```
+
+**Cost-based fallback:**
+
+```
+Budget Limit: $100/day per teamId
+  < 80%: GPT-4
+  >= 80%: GPT-4o-mini
+  >= 100%: Error
+```
+
+## Version Management
+
+- Save changes as new version
+- Test with `model: 'dynamic/route@v2'`
+- Roll back by deploying previous version
+
+## Monitoring
+
+Dashboard → Gateway → Dynamic Routes:
+
+- Request count per path
+- Success/error rates
+- Latency/cost by path
+
+## Limitations
+
+- Max 5 metadata entries
+- Values: string/number/boolean/null only
+- No nested objects
+- Route names: alphanumeric + hyphens

package/skills/cloudflare/references/ai-gateway/features.md

@@ -0,0 +1,96 @@
+# Features & Capabilities
+
+## Caching
+
+Dashboard: Settings → Cache Responses → Enable
+
+```typescript
+// Custom TTL (1 hour)
+headers: { 'cf-aig-cache-ttl': '3600' }
+
+// Skip cache
+headers: { 'cf-aig-skip-cache': 'true' }
+
+// Custom cache key
+headers: { 'cf-aig-cache-key': 'greeting-en' }
+```
+
+**Limits:** TTL 60s - 30 days. **Does NOT work with streaming.**
+
+## Rate Limiting
+
+Dashboard: Settings → Rate-limiting → Enable
+
+- **Fixed window:** Resets at intervals
+- **Sliding window:** Rolling window (more accurate)
+- Returns `429` when exceeded
+
+## Guardrails
+
+Dashboard: Settings → Guardrails → Enable
+
+Filter prompts/responses for inappropriate content. Actions: Flag (log) or Block (reject).
+
+## Data Loss Prevention (DLP)
+
+Dashboard: Settings → DLP → Enable
+
+Detect PII (emails, SSNs, credit cards). Actions: Flag, Block, or Redact.
+
+## Billing Modes
+
+| Mode                | Description                              | Setup                                  |
+| ------------------- | ---------------------------------------- | -------------------------------------- |
+| **Unified Billing** | Pay through Cloudflare, no provider keys | Use `cf-aig-authorization` header only |
+| **BYOK**            | Store provider keys in dashboard         | Add keys in Provider Keys section      |
+| **Pass-through**    | Send provider key with each request      | Include provider's auth header         |
+
+## Zero Data Retention
+
+Dashboard: Settings → Privacy → Zero Data Retention
+
+No prompts/responses stored. Request counts and costs still tracked.
+
+## Logging
+
+Dashboard: Settings → Logs → Enable (up to 10M logs)
+
+Each entry: prompt, response, provider, model, tokens, cost, duration, cache status, metadata.
+
+```typescript
+// Skip logging for request
+headers: { 'cf-aig-collect-log': 'false' }
+```
+
+**Export:** Use Logpush to S3, GCS, Datadog, Splunk, etc.
+
+## Custom Cost Tracking
+
+For models not in Cloudflare's pricing database:
+
+Dashboard: Gateway → Settings → Custom Costs
+
+Or via API: set `model`, `input_cost`, `output_cost`.
+
+## Supported Providers (22+)
+
+| Provider                                             | Unified API                         | Notes            |
+| ---------------------------------------------------- | ----------------------------------- | ---------------- |
+| OpenAI                                               | `openai/gpt-4o`                     | Full support     |
+| Anthropic                                            | `anthropic/claude-sonnet-4-5`       | Full support     |
+| Google AI                                            | `google-ai-studio/gemini-2.0-flash` | Full support     |
+| Workers AI                                           | `workersai/@cf/meta/llama-3`        | Native           |
+| Azure OpenAI                                         | `azure-openai/*`                    | Deployment names |
+| AWS Bedrock                                          | Provider endpoint only              | `/bedrock/*`     |
+| Groq                                                 | `groq/*`                            | Fast inference   |
+| Mistral, Cohere, Perplexity, xAI, DeepSeek, Cerebras | Full support                        | -                |
+
+## Best Practices
+
+1. Enable caching for deterministic prompts
+2. Set rate limits to prevent abuse
+3. Use guardrails for user-facing AI
+4. Enable DLP for sensitive data
+5. Use unified billing or BYOK for simpler key management
+6. Enable logging for debugging
+7. Use zero data retention when privacy required