memory-journal-mcp 8.0.1 → 9.1.0

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

@@ -1,148 +0,0 @@
-# KV Configuration
-
-## Create Namespace
-
-```bash
-wrangler kv namespace create MY_NAMESPACE
-# Output: { binding = "MY_NAMESPACE", id = "abc123..." }
-
-wrangler kv namespace create MY_NAMESPACE --preview  # For local dev
-```
-
-## Workers Binding
-
-**wrangler.jsonc:**
-
-```jsonc
-{
-  "kv_namespaces": [
-    {
-      "binding": "MY_KV",
-      "id": "abc123xyz789",
-    },
-    // Optional: Different namespace for preview/development
-    {
-      "binding": "MY_KV",
-      "preview_id": "preview-abc123",
-    },
-  ],
-}
-```
-
-## TypeScript Types
-
-**env.d.ts:**
-
-```typescript
-interface Env {
-  MY_KV: KVNamespace
-  SESSIONS: KVNamespace
-  CACHE: KVNamespace
-}
-```
-
-**worker.ts:**
-
-```typescript
-export default {
-  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
-    // env.MY_KV is now typed as KVNamespace
-    const value = await env.MY_KV.get('key')
-    return new Response(value || 'Not found')
-  },
-} satisfies ExportedHandler<Env>
-```
-
-**Type-safe JSON operations:**
-
-```typescript
-interface UserProfile {
-  name: string
-  email: string
-  role: 'admin' | 'user'
-}
-
-const profile = await env.USERS.get<UserProfile>('user:123', 'json')
-// profile: UserProfile | null (type-safe!)
-if (profile) {
-  console.log(profile.name) // TypeScript knows this is a string
-}
-```
-
-## CLI Operations
-
-```bash
-# Put
-wrangler kv key put --binding=MY_KV "key" "value"
-wrangler kv key put --binding=MY_KV "key" --path=./file.json --ttl=3600
-
-# Get
-wrangler kv key get --binding=MY_KV "key"
-
-# Delete
-wrangler kv key delete --binding=MY_KV "key"
-
-# List
-wrangler kv key list --binding=MY_KV --prefix="user:"
-
-# Bulk operations (max 10,000 keys per file)
-wrangler kv bulk put data.json --binding=MY_KV
-wrangler kv bulk get keys.json --binding=MY_KV
-wrangler kv bulk delete keys.json --binding=MY_KV --force
-```
-
-## Local Development
-
-```bash
-wrangler dev                # Local KV (isolated)
-wrangler dev --remote       # Remote KV (production)
-
-# Or in wrangler.jsonc:
-# "kv_namespaces": [{ "binding": "MY_KV", "id": "...", "remote": true }]
-```
-
-## REST API
-
-### Single Operations
-
-```typescript
-import Cloudflare from 'cloudflare'
-
-const client = new Cloudflare({
-  apiEmail: process.env.CLOUDFLARE_EMAIL,
-  apiKey: process.env.CLOUDFLARE_API_KEY,
-})
-
-// Single key operations
-await client.kv.namespaces.values.update(namespaceId, 'key', {
-  account_id: accountId,
-  value: 'value',
-  expiration_ttl: 3600,
-})
-```
-
-### Bulk Operations
-
-```typescript
-// Bulk update (up to 10,000 keys, max 100MB total)
-await client.kv.namespaces.bulkUpdate(namespaceId, {
-  account_id: accountId,
-  body: [
-    { key: 'key1', value: 'value1', expiration_ttl: 3600 },
-    { key: 'key2', value: 'value2', metadata: { version: 1 } },
-    { key: 'key3', value: 'value3' },
-  ],
-})
-
-// Bulk get (up to 100 keys)
-const results = await client.kv.namespaces.bulkGet(namespaceId, {
-  account_id: accountId,
-  keys: ['key1', 'key2', 'key3'],
-})
-
-// Bulk delete (up to 10,000 keys)
-await client.kv.namespaces.bulkDelete(namespaceId, {
-  account_id: accountId,
-  keys: ['key1', 'key2', 'key3'],
-})
-```

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

@@ -1,133 +0,0 @@
-# KV Gotchas & Troubleshooting
-
-## Common Errors
-
-### "Stale Read After Write"
-
-**Cause:** Eventual consistency means writes may not be immediately visible in other regions  
-**Solution:** Don't read immediately after write; return confirmation without reading or use the local value you just wrote. Writes visible immediately in same location, ≤60s globally
-
-```typescript
-// ❌ BAD: Read immediately after write
-await env.KV.put('key', 'value')
-const value = await env.KV.get('key') // May be null in other regions!
-
-// ✅ GOOD: Use the value you just wrote
-const newValue = 'value'
-await env.KV.put('key', newValue)
-return new Response(newValue) // Don't re-read
-```
-
-### "429 Rate Limit on Concurrent Writes"
-
-**Cause:** Multiple concurrent writes to same key exceeding 1 write/second limit  
-**Solution:** Use sequential writes, unique keys for concurrent operations, or implement retry with exponential backoff
-
-```typescript
-async function putWithRetry(
-  kv: KVNamespace,
-  key: string,
-  value: string,
-  maxAttempts = 5
-): Promise<void> {
-  let delay = 1000
-  for (let i = 0; i < maxAttempts; i++) {
-    try {
-      await kv.put(key, value)
-      return
-    } catch (err) {
-      if (err instanceof Error && err.message.includes('429')) {
-        if (i === maxAttempts - 1) throw err
-        await new Promise((r) => setTimeout(r, delay))
-        delay *= 2 // Exponential backoff
-      } else {
-        throw err
-      }
-    }
-  }
-}
-```
-
-### "Inefficient Multiple Gets"
-
-**Cause:** Making multiple individual get() calls instead of bulk operation  
-**Solution:** Use bulk get with array of keys: `env.USERS.get(["user:1", "user:2", "user:3"])` to reduce to 1 operation
-
-### "Null Reference Error"
-
-**Cause:** Attempting to use value without checking for null when key doesn't exist  
-**Solution:** Always handle null returns - KV returns `null` for missing keys, not undefined
-
-```typescript
-// ❌ BAD: Assumes value exists
-const config = await env.KV.get('config', 'json')
-return config.theme // TypeError if null!
-
-// ✅ GOOD: Null checks
-const config = await env.KV.get('config', 'json')
-return config?.theme ?? 'default'
-
-// ✅ GOOD: Early return
-const config = await env.KV.get('config', 'json')
-if (!config) return new Response('Not found', { status: 404 })
-return new Response(config.theme)
-```
-
-### "Negative Lookup Caching"
-
-**Cause:** Keys that don't exist are cached as "not found" for up to 60s  
-**Solution:** Creating a key after checking won't be visible until cache expires
-
-```typescript
-// Check → create pattern has race condition
-const exists = await env.KV.get('key') // null, cached as "not found"
-if (!exists) {
-  await env.KV.put('key', 'value')
-  // Next get() may still return null for ~60s due to negative cache
-}
-
-// Alternative: Always assume key may not exist, use defaults
-const value = (await env.KV.get('key')) ?? 'default-value'
-```
-
-## Performance Tips
-
-| Scenario            | Recommendation                | Why                                         |
-| ------------------- | ----------------------------- | ------------------------------------------- |
-| Large values (>1MB) | Use `stream` type             | Avoids buffering entire value in memory     |
-| Many small keys     | Coalesce into one JSON object | Reduces operations, improves cache hit rate |
-| High write volume   | Spread across different keys  | Avoid 1 write/second per-key limit          |
-| Cold reads          | Increase `cacheTtl` parameter | Reduces latency for frequently-read data    |
-| Bulk operations     | Use array form of get()       | Single operation, better performance        |
-
-## Cost Examples
-
-**Free tier:**
-
-- 100K reads/day = 3M/month ✅
-- 1K writes/day = 30K/month ✅
-- 1GB storage ✅
-
-**Example paid workload:**
-
-- 10M reads/month = $5.00
-- 100K writes/month = $0.50
-- 1GB storage = $0.50
-- **Total: ~$6/month**
-
-## Limits
-
-| Limit                 | Value              | Notes                                |
-| --------------------- | ------------------ | ------------------------------------ |
-| Key size              | 512 bytes          | Maximum key length                   |
-| Value size            | 25 MiB             | Maximum value; 413 error if exceeded |
-| Metadata size         | 1024 bytes         | Maximum metadata per key             |
-| cacheTtl minimum      | 60s                | Minimum cache TTL                    |
-| Write rate per key    | 1 write/second     | All plans; 429 error if exceeded     |
-| Propagation time      | ≤60s               | Global propagation time              |
-| Bulk get max          | 100 keys           | Maximum keys per bulk operation      |
-| Operations per Worker | 1,000              | Per request (bulk counts as 1)       |
-| Reads pricing         | $0.50 per 10M      | Per million reads                    |
-| Writes pricing        | $5.00 per 1M       | Per million writes                   |
-| Deletes pricing       | $5.00 per 1M       | Per million deletes                  |
-| Storage pricing       | $0.50 per GB-month | Per GB per month                     |

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

@@ -1,195 +0,0 @@
-# KV Patterns & Best Practices
-
-## Multi-Tier Caching
-
-```typescript
-// Memory → KV → Origin (3-tier cache)
-const memoryCache = new Map<string, { data: any; expires: number }>()
-
-async function getCached(env: Env, key: string): Promise<any> {
-  const now = Date.now()
-
-  // L1: Memory cache (fastest)
-  const cached = memoryCache.get(key)
-  if (cached && cached.expires > now) {
-    return cached.data
-  }
-
-  // L2: KV cache (fast)
-  const kvValue = await env.CACHE.get(key, 'json')
-  if (kvValue) {
-    memoryCache.set(key, { data: kvValue, expires: now + 60000 }) // 1min in memory
-    return kvValue
-  }
-
-  // L3: Origin (slow)
-  const origin = await fetch(`https://api.example.com/${key}`).then((r) => r.json())
-
-  // Backfill caches
-  await env.CACHE.put(key, JSON.stringify(origin), { expirationTtl: 300 }) // 5min in KV
-  memoryCache.set(key, { data: origin, expires: now + 60000 })
-
-  return origin
-}
-```
-
-## API Response Caching
-
-```typescript
-async function getCachedData(env: Env, key: string, fetcher: () => Promise<any>): Promise<any> {
-  const cached = await env.MY_KV.get(key, 'json')
-  if (cached) return cached
-
-  const data = await fetcher()
-  await env.MY_KV.put(key, JSON.stringify(data), { expirationTtl: 300 })
-  return data
-}
-
-const apiData = await getCachedData(env, 'cache:users', () =>
-  fetch('https://api.example.com/users').then((r) => r.json())
-)
-```
-
-## Session Management
-
-```typescript
-interface Session {
-  userId: string
-  expiresAt: number
-}
-
-async function createSession(env: Env, userId: string): Promise<string> {
-  const sessionId = crypto.randomUUID()
-  const expiresAt = Date.now() + 24 * 60 * 60 * 1000
-
-  await env.SESSIONS.put(`session:${sessionId}`, JSON.stringify({ userId, expiresAt }), {
-    expirationTtl: 86400,
-    metadata: { createdAt: Date.now() },
-  })
-
-  return sessionId
-}
-
-async function getSession(env: Env, sessionId: string): Promise<Session | null> {
-  const data = await env.SESSIONS.get<Session>(`session:${sessionId}`, 'json')
-  if (!data || data.expiresAt < Date.now()) return null
-  return data
-}
-```
-
-## Coalesce Cold Keys
-
-```typescript
-// ❌ BAD: Many individual keys
-await env.KV.put('user:123:name', 'John')
-await env.KV.put('user:123:email', 'john@example.com')
-
-// ✅ GOOD: Single coalesced object
-await env.USERS.put(
-  'user:123:profile',
-  JSON.stringify({
-    name: 'John',
-    email: 'john@example.com',
-    role: 'admin',
-  })
-)
-
-// Benefits: Hot key cache, single read, reduced operations
-// Trade-off: Harder to update individual fields
-```
-
-## Prefix-Based Namespacing
-
-```typescript
-// Logical partitioning within single namespace
-const PREFIXES = {
-  users: 'user:',
-  sessions: 'session:',
-  cache: 'cache:',
-  features: 'feature:',
-} as const
-
-// Write with prefix
-async function setUser(env: Env, id: string, data: any) {
-  await env.KV.put(`${PREFIXES.users}${id}`, JSON.stringify(data))
-}
-
-// Read with prefix
-async function getUser(env: Env, id: string) {
-  return await env.KV.get(`${PREFIXES.users}${id}`, 'json')
-}
-
-// List by prefix
-async function listUserIds(env: Env): Promise<string[]> {
-  const result = await env.KV.list({ prefix: PREFIXES.users })
-  return result.keys.map((k) => k.name.replace(PREFIXES.users, ''))
-}
-
-// Example hierarchy
-;('user:123:profile')
-;('user:123:settings')
-;('cache:api:users')
-;('session:abc-def')
-;('feature:flags:beta')
-```
-
-## Metadata Versioning
-
-```typescript
-interface VersionedData {
-  version: number
-  data: any
-}
-
-async function migrateIfNeeded(env: Env, key: string) {
-  const result = await env.DATA.getWithMetadata(key, 'json')
-
-  if (!result.value) return null
-
-  const currentVersion = result.metadata?.version || 1
-  const targetVersion = 2
-
-  if (currentVersion < targetVersion) {
-    // Migrate data format
-    const migrated = migrate(result.value, currentVersion, targetVersion)
-
-    // Store with new version
-    await env.DATA.put(key, JSON.stringify(migrated), {
-      metadata: { version: targetVersion, migratedAt: Date.now() },
-    })
-
-    return migrated
-  }
-
-  return result.value
-}
-
-function migrate(data: any, from: number, to: number): any {
-  if (from === 1 && to === 2) {
-    // V1 → V2: Rename field
-    return { ...data, userName: data.name }
-  }
-  return data
-}
-```
-
-## Error Boundary Pattern
-
-```typescript
-// Resilient get with fallback
-async function resilientGet<T>(env: Env, key: string, fallback: T): Promise<T> {
-  try {
-    const value = await env.KV.get<T>(key, 'json')
-    return value ?? fallback
-  } catch (err) {
-    console.error(`KV error for ${key}:`, err)
-    return fallback
-  }
-}
-
-// Usage
-const config = await resilientGet(env, 'config:app', {
-  theme: 'light',
-  maxItems: 10,
-})
-```

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

@@ -1,113 +0,0 @@
-# Miniflare
-
-Local simulator for Cloudflare Workers development/testing. Runs Workers in workerd sandbox implementing runtime APIs - no internet required.
-
-## Features
-
-- Full-featured: KV, Durable Objects, R2, D1, WebSockets, Queues
-- Fully-local: test without internet, instant reload
-- TypeScript-native: detailed logging, source maps
-- Advanced testing: dispatch events without HTTP, simulate Worker connections
-
-## When to Use
-
-**Decision tree for testing Workers:**
-
-```
-Need to test Workers?
-│
-├─ Unit tests for business logic only?
-│  └─ getPlatformProxy (Vitest/Jest) → [patterns.md](./patterns.md#getplatformproxy)
-│     Fast, no HTTP, direct binding access
-│
-├─ Integration tests with full runtime?
-│  ├─ Single Worker?
-│  │  └─ Miniflare API → [Quick Start](#quick-start)
-│  │     Full control, programmatic access
-│  │
-│  ├─ Multiple Workers + service bindings?
-│  │  └─ Miniflare workers array → [configuration.md](./configuration.md#multiple-workers)
-│  │     Shared storage, inter-worker calls
-│  │
-│  └─ Vitest test runner integration?
-│     └─ vitest-pool-workers → [patterns.md](./patterns.md#vitest-pool-workers)
-│        Full Workers env in Vitest
-│
-└─ Local dev server?
-   └─ wrangler dev (not Miniflare)
-      Hot reload, automatic config
-```
-
-**Use Miniflare for:**
-
-- Integration tests with full Worker runtime
-- Testing bindings/storage locally
-- Multiple Workers with service bindings
-- Programmatic event dispatch (fetch, queue, scheduled)
-
-**Use getPlatformProxy for:**
-
-- Fast unit tests of business logic
-- Testing without HTTP overhead
-- Vitest/Jest environments
-
-**Use Wrangler for:**
-
-- Local development workflow
-- Production deployments
-
-## Setup
-
-```bash
-npm i -D miniflare
-```
-
-Requires ES modules in `package.json`:
-
-```json
-{ "type": "module" }
-```
-
-## Quick Start
-
-```js
-import { Miniflare } from 'miniflare'
-
-const mf = new Miniflare({
-  modules: true,
-  script: `
-    export default {
-      async fetch(request, env, ctx) {
-        return new Response("Hello Miniflare!");
-      }
-    }
-  `,
-})
-
-const res = await mf.dispatchFetch('http://localhost:8787/')
-console.log(await res.text()) // Hello Miniflare!
-await mf.dispose()
-```
-
-## Reading Order
-
-**New to Miniflare?** Start here:
-
-1. [Quick Start](#quick-start) - Running in 2 minutes
-2. [When to Use](#when-to-use) - Choose your testing approach
-3. [patterns.md](./patterns.md) - Testing patterns (getPlatformProxy, Vitest, node:test)
-4. [configuration.md](./configuration.md) - Configure bindings, storage, multiple workers
-
-**Troubleshooting:**
-
-- [gotchas.md](./gotchas.md) - Common errors and debugging
-
-**API reference:**
-
-- [api.md](./api.md) - Complete method reference
-
-## See Also
-
-- [wrangler](../wrangler/) - CLI tool that embeds Miniflare for `wrangler dev`
-- [workerd](../workerd/) - Runtime that powers Miniflare
-- [workers](../workers/) - Workers runtime API documentation