memory-journal-mcp 8.0.1 → 9.1.0

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

@@ -1,215 +0,0 @@
-# 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

@@ -1,176 +0,0 @@
-# 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

@@ -1,117 +0,0 @@
-# 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

@@ -1,88 +0,0 @@
-# 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

@@ -1,96 +0,0 @@
-# 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