memory-journal-mcp 7.7.1 → 8.0.0

package/skills/cloudflare/references/vectorize/configuration.md

@@ -0,0 +1,91 @@
+# Vectorize Configuration
+
+## Create Index
+
+```bash
+npx wrangler vectorize create my-index --dimensions=768 --metric=cosine
+```
+
+**⚠️ Dimensions and metric are immutable** - cannot change after creation.
+
+## Worker Binding
+
+```jsonc
+// wrangler.jsonc
+{
+  "vectorize": [{ "binding": "VECTORIZE", "index_name": "my-index" }],
+}
+```
+
+```typescript
+interface Env {
+  VECTORIZE: Vectorize
+}
+```
+
+## Metadata Indexes
+
+**Must create BEFORE inserting vectors** - existing vectors not retroactively indexed.
+
+```bash
+wrangler vectorize create-metadata-index my-index --property-name=category --type=string
+wrangler vectorize create-metadata-index my-index --property-name=price --type=number
+```
+
+| Type      | Use For                                   |
+| --------- | ----------------------------------------- |
+| `string`  | Categories, tags (first 64 bytes indexed) |
+| `number`  | Prices, timestamps                        |
+| `boolean` | Flags                                     |
+
+## CLI Commands
+
+```bash
+# Index management
+wrangler vectorize list
+wrangler vectorize info <index-name>
+wrangler vectorize delete <index-name>
+
+# Vector operations
+wrangler vectorize insert <index-name> --file=embeddings.ndjson
+wrangler vectorize get <index-name> --ids=id1,id2
+wrangler vectorize delete-by-ids <index-name> --ids=id1,id2
+
+# Metadata indexes
+wrangler vectorize list-metadata-index <index-name>
+wrangler vectorize delete-metadata-index <index-name> --property-name=field
+```
+
+## Bulk Upload (NDJSON)
+
+```json
+{"id": "1", "values": [0.1, 0.2, ...], "metadata": {"category": "docs"}}
+{"id": "2", "values": [0.4, 0.5, ...], "namespace": "tenant-abc"}
+```
+
+**Limits:** 5000 vectors per file, 100 MB max
+
+## Cardinality Best Practice
+
+Bucket high-cardinality data:
+
+```typescript
+// ❌ Millisecond timestamps
+metadata: {
+  timestamp: Date.now()
+}
+
+// ✅ 5-minute buckets
+metadata: {
+  timestamp_bucket: Math.floor(Date.now() / 300000) * 300000
+}
+```
+
+## Production Checklist
+
+1. Create index with correct dimensions
+2. Create metadata indexes FIRST
+3. Test bulk upload
+4. Configure bindings
+5. Deploy Worker
+6. Verify queries

package/skills/cloudflare/references/vectorize/gotchas.md

@@ -0,0 +1,83 @@
+# Vectorize Gotchas
+
+## Critical Warnings
+
+### Async Mutations
+
+Insert/upsert/delete return immediately but vectors aren't queryable for 5-10 seconds.
+
+### Batch Size Limit
+
+**Workers API: 500 vectors max per call** (undocumented, silently truncates)
+
+```typescript
+// ✅ Chunk into 500
+for (let i = 0; i < vectors.length; i += 500) {
+  await env.VECTORIZE.upsert(vectors.slice(i, i + 500))
+}
+```
+
+### Metadata Truncation
+
+`returnMetadata: "indexed"` returns only first 64 bytes of strings. Use `"all"` for complete metadata (but max topK drops to 20).
+
+### topK Limits
+
+| returnMetadata         | returnValues | Max topK |
+| ---------------------- | ------------ | -------- |
+| `"none"` / `"indexed"` | `false`      | 100      |
+| `"all"`                | any          | **20**   |
+| any                    | `true`       | **20**   |
+
+### Metadata Indexes First
+
+Create BEFORE inserting - existing vectors not retroactively indexed.
+
+```bash
+# ✅ Create index FIRST
+wrangler vectorize create-metadata-index my-index --property-name=category --type=string
+wrangler vectorize insert my-index --file=data.ndjson
+```
+
+### Index Config Immutable
+
+Cannot change dimensions/metric after creation. Must create new index and migrate.
+
+## Limits (V2)
+
+| Resource                | Limit                        |
+| ----------------------- | ---------------------------- |
+| Vectors per index       | 10,000,000                   |
+| Max dimensions          | 1536                         |
+| Batch upsert (Workers)  | **500**                      |
+| Indexed string metadata | **64 bytes**                 |
+| Metadata indexes        | 10                           |
+| Namespaces              | 50,000 (paid) / 1,000 (free) |
+
+## Common Mistakes
+
+1. **Wrong embedding shape:** Extract `result.data[0]` from Workers AI
+2. **Metadata index after data:** Re-upsert all vectors
+3. **Insert vs upsert:** `insert` ignores duplicates, `upsert` overwrites
+4. **Not batching:** Individual inserts ~1K/min, batched ~200K+/min
+
+## Troubleshooting
+
+**No results?**
+
+- Wait 5-10s after insert
+- Check namespace spelling (case-sensitive)
+- Verify metadata index exists
+- Check dimension mismatch
+
+**Metadata filter not working?**
+
+- Index must exist before data insert
+- Strings >64 bytes truncated
+- Use dot notation for nested: `"product.category"`
+
+## Model Dimensions
+
+- `@cf/baai/bge-small-en-v1.5`: 384
+- `@cf/baai/bge-base-en-v1.5`: 768
+- `@cf/baai/bge-large-en-v1.5`: 1024

package/skills/cloudflare/references/vectorize/patterns.md

@@ -0,0 +1,92 @@
+# Vectorize Patterns
+
+## Workers AI Integration
+
+```typescript
+// Generate embedding + query
+const result = await env.AI.run('@cf/baai/bge-base-en-v1.5', { text: [query] })
+const matches = await env.VECTORIZE.query(result.data[0], { topK: 5 }) // Pass data[0]!
+```
+
+| Model                        | Dimensions        |
+| ---------------------------- | ----------------- |
+| `@cf/baai/bge-small-en-v1.5` | 384               |
+| `@cf/baai/bge-base-en-v1.5`  | 768 (recommended) |
+| `@cf/baai/bge-large-en-v1.5` | 1024              |
+
+## OpenAI Integration
+
+```typescript
+const response = await openai.embeddings.create({ model: 'text-embedding-ada-002', input: query })
+const matches = await env.VECTORIZE.query(response.data[0].embedding, { topK: 5 })
+```
+
+## RAG Pattern
+
+```typescript
+// 1. Embed query
+const emb = await env.AI.run('@cf/baai/bge-base-en-v1.5', { text: [query] })
+
+// 2. Search vectors
+const matches = await env.VECTORIZE.query(emb.data[0], { topK: 5, returnMetadata: 'indexed' })
+
+// 3. Fetch full docs from R2/D1/KV
+const docs = await Promise.all(
+  matches.matches.map((m) => env.R2.get(m.metadata.key).then((o) => o?.text()))
+)
+
+// 4. Generate with context
+const answer = await env.AI.run('@cf/meta/llama-3-8b-instruct', {
+  prompt: `Context:\n${docs.filter(Boolean).join('\n\n')}\n\nQuestion: ${query}\n\nAnswer:`,
+})
+```
+
+## Multi-Tenant
+
+### Namespaces (< 50K tenants, fastest)
+
+```typescript
+await env.VECTORIZE.upsert([{ id: '1', values: emb, namespace: `tenant-${id}` }])
+await env.VECTORIZE.query(vec, { namespace: `tenant-${id}`, topK: 10 })
+```
+
+### Metadata Filter (> 50K tenants)
+
+```bash
+wrangler vectorize create-metadata-index my-index --property-name=tenantId --type=string
+```
+
+```typescript
+await env.VECTORIZE.upsert([{ id: '1', values: emb, metadata: { tenantId: id } }])
+await env.VECTORIZE.query(vec, { filter: { tenantId: id }, topK: 10 })
+```
+
+## Hybrid Search
+
+```typescript
+const matches = await env.VECTORIZE.query(vec, {
+  topK: 20,
+  filter: {
+    category: { $in: ['tech', 'science'] },
+    published: { $gte: lastMonthTimestamp },
+  },
+})
+```
+
+## Batch Ingestion
+
+```typescript
+const BATCH = 500
+for (let i = 0; i < vectors.length; i += BATCH) {
+  await env.VECTORIZE.upsert(vectors.slice(i, i + BATCH))
+}
+```
+
+## Best Practices
+
+1. **Pass `data[0]`** not `data` or full response
+2. **Batch 500** vectors per upsert
+3. **Create metadata indexes** before inserting
+4. **Use namespaces** for tenant isolation (faster than filters)
+5. **`returnMetadata: "indexed"`** for best speed/data balance
+6. **Handle 5-10s mutation delay** in async operations

package/skills/cloudflare/references/waf/README.md

@@ -0,0 +1,125 @@
+# Cloudflare WAF Expert Skill Reference
+
+**Expertise**: Cloudflare Web Application Firewall (WAF) configuration, custom rules, managed rulesets, rate limiting, attack detection, and API integration
+
+## Overview
+
+Cloudflare WAF protects web applications from attacks through managed rulesets and custom rules.
+
+**Detection (Managed Rulesets)**
+
+- Pre-configured rules maintained by Cloudflare
+- CVE-based rules, OWASP Top 10 coverage
+- Three main rulesets: Cloudflare Managed, OWASP CRS, Exposed Credentials
+- Actions: log, block, challenge, js_challenge, managed_challenge
+
+**Mitigation (Custom Rules & Rate Limiting)**
+
+- Custom expressions using Wirefilter syntax
+- Attack score-based blocking (`cf.waf.score`)
+- Rate limiting with per-IP, per-user, or custom characteristics
+- Actions: block, challenge, js_challenge, managed_challenge, log, skip
+
+## Quick Start
+
+### Deploy Cloudflare Managed Ruleset
+
+```typescript
+import Cloudflare from 'cloudflare'
+
+const client = new Cloudflare({ apiToken: process.env.CF_API_TOKEN })
+
+// Deploy managed ruleset to zone
+await client.rulesets.create({
+  zone_id: 'zone_id',
+  kind: 'zone',
+  phase: 'http_request_firewall_managed',
+  name: 'Deploy Cloudflare Managed Ruleset',
+  rules: [
+    {
+      action: 'execute',
+      action_parameters: {
+        id: 'efb7b8c949ac4650a09736fc376e9aee', // Cloudflare Managed Ruleset
+      },
+      expression: 'true',
+      enabled: true,
+    },
+  ],
+})
+```
+
+### Create Custom Rule
+
+```typescript
+// Block requests with attack score >= 40
+await client.rulesets.create({
+  zone_id: 'zone_id',
+  kind: 'zone',
+  phase: 'http_request_firewall_custom',
+  name: 'Custom WAF Rules',
+  rules: [
+    {
+      action: 'block',
+      expression: 'cf.waf.score gt 40',
+      description: 'Block high attack scores',
+      enabled: true,
+    },
+  ],
+})
+```
+
+### Create Rate Limit
+
+```typescript
+await client.rulesets.create({
+  zone_id: 'zone_id',
+  kind: 'zone',
+  phase: 'http_ratelimit',
+  name: 'API Rate Limits',
+  rules: [
+    {
+      action: 'block',
+      expression: 'http.request.uri.path eq "/api/login"',
+      action_parameters: {
+        ratelimit: {
+          characteristics: ['cf.colo.id', 'ip.src'],
+          period: 60,
+          requests_per_period: 10,
+          mitigation_timeout: 600,
+        },
+      },
+      enabled: true,
+    },
+  ],
+})
+```
+
+## Managed Ruleset Quick Reference
+
+| Ruleset Name              | ID                                 | Coverage              |
+| ------------------------- | ---------------------------------- | --------------------- |
+| Cloudflare Managed        | `efb7b8c949ac4650a09736fc376e9aee` | OWASP Top 10, CVEs    |
+| OWASP Core Ruleset        | `4814384a9e5d4991b9815dcfc25d2f1f` | OWASP ModSecurity CRS |
+| Exposed Credentials Check | `c2e184081120413c86c3ab7e14069605` | Credential stuffing   |
+
+## Phases
+
+WAF rules execute in specific phases:
+
+- `http_request_firewall_managed` - Managed rulesets
+- `http_request_firewall_custom` - Custom rules
+- `http_ratelimit` - Rate limiting rules
+- `http_request_sbfm` - Super Bot Fight Mode (Pro+)
+
+## Reading Order
+
+1. **[api.md](api.md)** - SDK methods, expressions, actions, parameters
+2. **[configuration.md](configuration.md)** - Setup with Wrangler, Terraform, Pulumi
+3. **[patterns.md](patterns.md)** - Common patterns: deploy managed, rate limiting, skip, override
+4. **[gotchas.md](gotchas.md)** - Execution order, limits, expression errors
+
+## See Also
+
+- [Cloudflare WAF Docs](https://developers.cloudflare.com/waf/)
+- [Ruleset Engine](https://developers.cloudflare.com/ruleset-engine/)
+- [Expression Reference](https://developers.cloudflare.com/ruleset-engine/rules-language/)

package/skills/cloudflare/references/waf/api.md

@@ -0,0 +1,203 @@
+# API Reference
+
+## SDK Setup
+
+```typescript
+import Cloudflare from 'cloudflare'
+
+const client = new Cloudflare({
+  apiToken: process.env.CF_API_TOKEN,
+})
+```
+
+## Core Methods
+
+```typescript
+// List rulesets
+await client.rulesets.list({ zone_id: 'zone_id', phase: 'http_request_firewall_managed' })
+
+// Get ruleset
+await client.rulesets.get({ zone_id: 'zone_id', ruleset_id: 'ruleset_id' })
+
+// Create ruleset
+await client.rulesets.create({
+  zone_id: 'zone_id',
+  kind: 'zone',
+  phase: 'http_request_firewall_custom',
+  name: 'Custom WAF Rules',
+  rules: [{ action: 'block', expression: 'cf.waf.score gt 40', enabled: true }],
+})
+
+// Update ruleset (include rule id to keep existing, omit id for new rules)
+await client.rulesets.update({
+  zone_id: 'zone_id',
+  ruleset_id: 'ruleset_id',
+  rules: [
+    { id: 'rule_id', action: 'block', expression: 'cf.waf.score gt 40', enabled: true },
+    { action: 'challenge', expression: 'http.request.uri.path contains "/admin"', enabled: true },
+  ],
+})
+
+// Delete ruleset
+await client.rulesets.delete({ zone_id: 'zone_id', ruleset_id: 'ruleset_id' })
+```
+
+## Actions & Phases
+
+### Actions by Phase
+
+| Action              | Custom | Managed | Rate Limit | Description                   |
+| ------------------- | ------ | ------- | ---------- | ----------------------------- |
+| `block`             | ✅     | ❌      | ✅         | Block request with 403        |
+| `challenge`         | ✅     | ❌      | ✅         | Show CAPTCHA challenge        |
+| `js_challenge`      | ✅     | ❌      | ✅         | JS-based challenge            |
+| `managed_challenge` | ✅     | ❌      | ✅         | Smart challenge (recommended) |
+| `log`               | ✅     | ❌      | ✅         | Log only, don't block         |
+| `skip`              | ✅     | ❌      | ❌         | Skip rule evaluation          |
+| `execute`           | ❌     | ✅      | ❌         | Deploy managed ruleset        |
+
+### Phases (Execution Order)
+
+1. `http_request_firewall_custom` - Custom rules (first line of defense)
+2. `http_request_firewall_managed` - Managed rulesets (pre-configured protection)
+3. `http_ratelimit` - Rate limiting (request throttling)
+4. `http_request_sbfm` - Super Bot Fight Mode (Pro+ only)
+
+## Expression Syntax
+
+### Fields
+
+```typescript
+// Request properties
+http.request.method // GET, POST, etc.
+http.request.uri.path // /api/users
+http.host // example.com
+
+// IP and Geolocation
+ip.src // 192.0.2.1
+ip.geoip.country // US, GB, etc.
+ip.geoip.continent // NA, EU, etc.
+
+// Attack detection
+cf.waf.score // 0-100 attack score
+cf.waf.score.sqli // SQL injection score
+cf.waf.score.xss // XSS score
+
+// Headers & Cookies
+http.request.headers['authorization'][0]
+http.request.cookies['session'][0]
+lower(http.user_agent) // Lowercase user agent
+```
+
+### Operators
+
+```typescript
+// Comparison
+eq // Equal
+ne // Not equal
+lt // Less than
+le // Less than or equal
+gt // Greater than
+ge // Greater than or equal
+
+// String matching
+contains // Substring match
+matches // Regex match (use carefully)
+starts_with // Prefix match
+ends_with in // Suffix match
+  // Value in list
+  // List operations
+  not // Logical NOT
+and // Logical AND
+or // Logical OR
+```
+
+### Expression Examples
+
+```typescript
+'cf.waf.score gt 40' // Attack score
+'http.request.uri.path eq "/api/login" and http.request.method eq "POST"' // Path + method
+'ip.src in {192.0.2.0/24 203.0.113.0/24}' // IP blocking
+'ip.geoip.country in {"CN" "RU" "KP"}' // Country blocking
+'http.user_agent contains "bot"' // User agent
+'not http.request.headers["authorization"][0]' // Header check
+'(cf.waf.score.sqli gt 20 or cf.waf.score.xss gt 20) and http.request.uri.path starts_with "/api"' // Complex
+```
+
+## Rate Limiting Configuration
+
+```typescript
+{
+  action: 'block',
+  expression: 'http.request.uri.path starts_with "/api"',
+  action_parameters: {
+    ratelimit: {
+      // Characteristics define uniqueness: 'ip.src', 'cf.colo.id',
+      // 'http.request.headers["key"][0]', 'http.request.cookies["session"][0]'
+      characteristics: ['cf.colo.id', 'ip.src'], // Recommended: per-IP per-datacenter
+      period: 60,                      // Time window in seconds
+      requests_per_period: 100,        // Max requests in period
+      mitigation_timeout: 600,         // Block duration in seconds
+      counting_expression: 'http.request.method ne "GET"', // Optional: filter counted requests
+      requests_to_origin: false,       // Count all requests (not just origin hits)
+    },
+  },
+  enabled: true,
+}
+```
+
+## Managed Ruleset Deployment
+
+```typescript
+{
+  action: 'execute',
+  action_parameters: {
+    id: 'efb7b8c949ac4650a09736fc376e9aee', // Cloudflare Managed
+    overrides: {
+      // Override specific rules
+      rules: [
+        { id: '5de7edfa648c4d6891dc3e7f84534ffa', action: 'log', enabled: true },
+      ],
+      // Override categories: 'wordpress', 'sqli', 'xss', 'rce', etc.
+      categories: [
+        { category: 'wordpress', enabled: false },
+        { category: 'sqli', action: 'log' },
+      ],
+    },
+  },
+  expression: 'true',
+  enabled: true,
+}
+```
+
+## Skip Rules
+
+Skip rules bypass subsequent rule evaluation. Two skip types:
+
+**Skip current ruleset**: Skip remaining rules in current phase only
+
+```typescript
+{
+  action: 'skip',
+  action_parameters: {
+    ruleset: 'current', // Skip rest of current ruleset
+  },
+  expression: 'http.request.uri.path ends_with ".jpg" or http.request.uri.path ends_with ".css"',
+  enabled: true,
+}
+```
+
+**Skip entire phases**: Skip one or more phases completely
+
+```typescript
+{
+  action: 'skip',
+  action_parameters: {
+    phases: ['http_request_firewall_managed', 'http_ratelimit'], // Skip multiple phases
+  },
+  expression: 'ip.src in {192.0.2.0/24 203.0.113.0/24}',
+  enabled: true,
+}
+```
+
+**Note**: Skip rules in custom phase can skip managed/ratelimit phases, but not vice versa (execution order).