intentkit-cache

Redis cache adapter for IntentKit. Provides a CacheClient via the IntentKit provider system, backed by ioredis.

Install

npm install intentkit-cache ioredis

Quick Start

import { IntentRegistry, createContext, serve } from 'intentkit';
import { createCacheProvider } from 'intentkit-cache';

const registry = new IntentRegistry();
// ... register your functions

const context = createContext();

await serve({
  registry,
  context,
  providers: [
    createCacheProvider({
      host: '127.0.0.1',
      port: 6379,
    }),
  ],
});

Inside any function handler:

import { defineFunction } from 'intentkit';
import { z } from 'zod';
import type { CacheClient } from 'intentkit-cache';

export const getUser = defineFunction({
  name: 'get_user',
  intent: 'Look up a user, checking the cache first.',
  permissions: ['user:read'],
  requires: ['cache'],
  input: z.object({ id: z.string() }),
  output: z.object({ name: z.string() }),
  execute: async (input, ctx) => {
    const cache = ctx.providers.cache as CacheClient;

    const cached = await cache.get(`user:${input.id}`);
    if (cached) return JSON.parse(cached);

    const user = await ctx.db.get<{ name: string }>('SELECT name FROM users WHERE id = ?', [input.id]);
    if (user) {
      await cache.set(`user:${input.id}`, JSON.stringify(user), { ttl: 300 });
    }
    return user ?? { name: 'unknown' };
  },
});

Configuration

| Option | Type | Default | Description | |---|---|---|---| | name | string | 'cache' | Provider name (key in ctx.providers) | | host | string | '127.0.0.1' | Redis host | | port | number | 6379 | Redis port | | password | string | — | Redis AUTH password | | db | number | 0 | Redis database index | | keyPrefix | string | '' | Prefix prepended to all keys | | tls | boolean | false | Enable TLS connection | | connectTimeout | number | 10000 | Connection timeout (ms) | | url | string | — | Redis URL (overrides host/port/password/db) |

Configuration Examples

Local Redis:

createCacheProvider({ host: '127.0.0.1', port: 6379 })

Redis Cloud:

createCacheProvider({
  host: 'redis-12345.c1.us-east-1-2.ec2.cloud.redislabs.com',
  port: 12345,
  password: process.env.REDIS_PASSWORD,
  tls: true,
})

Upstash:

createCacheProvider({
  url: process.env.UPSTASH_REDIS_URL,
  tls: true,
})

Docker Redis:

createCacheProvider({ host: 'redis', port: 6379 })

Example Functions

The package ships with ready-to-use example functions:

import { cacheGet, cacheSet, cacheDelete, cacheListKeys } from 'intentkit-cache/functions';

| Function | Permission | Description | |---|---|---| | cache_get | cache:read | Retrieve a cached value by key | | cache_set | cache:write | Store a value with optional TTL | | cache_delete | cache:write | Delete one or more keys | | cache_list_keys | cache:read | List keys matching a glob pattern |

CacheClient API

| Method | Signature | Description | |---|---|---| | get | (key: string) => Promise<string \| null> | Get value by key | | set | (key: string, value: string, options?: { ttl?: number }) => Promise<void> | Set value with optional TTL (seconds) | | del | (...keys: string[]) => Promise<number> | Delete keys, returns count removed | | exists | (...keys: string[]) => Promise<number> | Count how many keys exist | | expire | (key: string, seconds: number) => Promise<boolean> | Set TTL on existing key | | keys | (pattern: string) => Promise<string[]> | Find keys by glob pattern | | flush | () => Promise<void> | Flush the current database | | ping | () => Promise<boolean> | Health check | | disconnect | () => Promise<void> | Close the connection |

Architecture

Agent (Claude / OpenClaw / custom)
    |
    | calls MCP tool
    v
IntentKit (serve)
    |
    | ctx.providers.cache
    v
intentkit-cache (CacheClient)
    |
    | ioredis
    v
Redis Server

License

MIT