claude-code-langcache 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OpenClaw Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,124 @@
+# claude-code-langcache
+
+Semantic caching skill for [Claude Code](https://claude.ai/code) using [Redis LangCache](https://redis.io/langcache/).
+
+Reduce LLM costs and latency by caching responses for semantically similar queries, with built-in privacy and security guardrails.
+
+> **For OpenClaw users:** See [openclaw-langcache](https://www.npmjs.com/package/openclaw-langcache)
+
+## Features
+
+- **Semantic similarity matching** - Cache hits for similar (not just identical) queries
+- **Hard block enforcement** - Automatically blocks caching of sensitive data:
+  - Temporal info (today, tomorrow, deadlines, appointments)
+  - Credentials (API keys, passwords, tokens, OTP)
+  - Identifiers (emails, phone numbers, account IDs)
+  - Personal context (relationships, private conversations)
+- **Category-aware thresholds** - Different similarity thresholds for factual Q&A vs style transforms
+- **CLI and Python integration** - Use from shell scripts or embed in Python agents
+
+## Installation
+
+```bash
+npm install -g claude-code-langcache
+```
+
+The skill will be automatically installed to `~/.claude/skills/langcache/`
+
+## Configuration
+
+Set your Redis LangCache credentials:
+
+```bash
+export LANGCACHE_HOST=your-instance.redis.cloud
+export LANGCACHE_CACHE_ID=your-cache-id
+export LANGCACHE_API_KEY=your-api-key
+```
+
+Get these from [Redis Cloud Console](https://app.redislabs.com/) after creating a LangCache instance.
+
+## Usage
+
+### Automatic (via Claude Code)
+
+The skill triggers automatically when you mention:
+- "cache LLM responses"
+- "semantic caching"
+- "reduce API costs"
+- "configure LangCache"
+
+Or invoke manually with `/langcache`
+
+### CLI
+
+```bash
+# Search for cached response
+~/.claude/skills/langcache/scripts/langcache.sh search "What is Redis?"
+
+# With similarity threshold
+~/.claude/skills/langcache/scripts/langcache.sh search "What is Redis?" --threshold 0.9
+
+# Store a response
+~/.claude/skills/langcache/scripts/langcache.sh store "What is Redis?" "Redis is an in-memory data store..."
+
+# Check if content would be blocked
+~/.claude/skills/langcache/scripts/langcache.sh check "What's on my calendar today?"
+# Output: BLOCKED: temporal_info
+```
+
+## Caching Policy
+
+### Cacheable (white-list)
+
+| Category | Examples | Threshold |
+|----------|----------|-----------|
+| Factual Q&A | "What is X?", "How does Y work?" | 0.90 |
+| Definitions / docs | API docs, command help | 0.90 |
+| Command explanations | "What does `git rebase` do?" | 0.92 |
+| Reply templates | "polite no", "follow-up", "intro" | 0.88 |
+| Style transforms | "make this warmer/shorter" | 0.85 |
+
+### Never Cached (hard blocks)
+
+| Category | Examples |
+|----------|----------|
+| Temporal | today, tomorrow, deadline, ETA, "in 20 minutes" |
+| Credentials | API keys, passwords, tokens, OTP/2FA |
+| Identifiers | emails, phone numbers, account IDs, UUIDs |
+| Personal | "my wife said", private conversations, relationships |
+
+## File Structure
+
+```
+~/.claude/skills/langcache/
+├── SKILL.md              # Skill definition and instructions
+├── scripts/
+│   └── langcache.sh      # CLI wrapper with policy enforcement
+├── references/
+│   ├── api-reference.md  # Complete REST API documentation
+│   └── best-practices.md # Optimization techniques
+└── examples/
+    ├── basic-caching.sh      # Simple cache workflow
+    └── agent-integration.py  # Python integration pattern
+```
+
+## Requirements
+
+- Claude Code
+- Redis Cloud account with LangCache enabled
+- Node.js 18+ (for npm installation)
+- `jq` and `curl` (for CLI usage)
+
+## Related Packages
+
+- [openclaw-langcache](https://www.npmjs.com/package/openclaw-langcache) - For OpenClaw users
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## Resources
+
+- [Redis LangCache Documentation](https://redis.io/docs/latest/develop/ai/langcache/)
+- [Claude Code Documentation](https://docs.anthropic.com/claude-code)
+- [Semantic Caching Guide](https://redis.io/blog/what-is-semantic-caching/)

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "claude-code-langcache",
+  "version": "1.0.0",
+  "description": "Semantic caching skill for Claude Code using Redis LangCache",
+  "keywords": [
+    "claude-code",
+    "claude",
+    "skill",
+    "langcache",
+    "redis",
+    "semantic-caching",
+    "llm",
+    "ai",
+    "cache"
+  ],
+  "homepage": "https://github.com/manvinder01/claude-code-langcache#readme",
+  "bugs": {
+    "url": "https://github.com/manvinder01/claude-code-langcache/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/manvinder01/claude-code-langcache.git"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "Manvinder Singh"
+  },
+  "files": [
+    "skills/",
+    "scripts/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "postinstall": "node scripts/postinstall.js"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "claude-code": {
+    "type": "skill",
+    "skills": ["langcache"],
+    "installPath": "skills/"
+  }
+}

package/scripts/postinstall.js

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+/**
+ * Postinstall script for claude-code-langcache
+ * Installs the skill to Claude Code workspace
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const SKILL_NAME = 'langcache';
+
+function getClaudePath() {
+  const home = os.homedir();
+  return path.join(
+    process.env.CLAUDE_HOME || path.join(home, '.claude'),
+    'skills'
+  );
+}
+
+function copyDir(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+
+    if (entry.isDirectory()) {
+      copyDir(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+      if (entry.name.endsWith('.sh') || entry.name.endsWith('.py')) {
+        fs.chmodSync(destPath, 0o755);
+      }
+    }
+  }
+}
+
+function main() {
+  console.log('\n📦 Installing langcache skill for Claude Code...\n');
+
+  try {
+    const skillsPath = getClaudePath();
+    const destPath = path.join(skillsPath, SKILL_NAME);
+    const packageRoot = path.dirname(__dirname);
+    const srcPath = path.join(packageRoot, 'skills', SKILL_NAME);
+
+    if (!fs.existsSync(srcPath)) {
+      console.log('Source skill not found, skipping');
+      return;
+    }
+
+    fs.mkdirSync(skillsPath, { recursive: true });
+
+    if (fs.existsSync(destPath)) {
+      console.log(`⚠ Skill already exists at ${destPath}`);
+      console.log('  To update: rm -rf ~/.claude/skills/langcache && npm install -g claude-code-langcache');
+      return;
+    }
+
+    copyDir(srcPath, destPath);
+
+    console.log(`✓ Installed to ${destPath}\n`);
+    console.log('Next steps:');
+    console.log('1. Set your Redis LangCache credentials:');
+    console.log('   export LANGCACHE_HOST=your-instance.redis.cloud');
+    console.log('   export LANGCACHE_CACHE_ID=your-cache-id');
+    console.log('   export LANGCACHE_API_KEY=your-api-key');
+    console.log('');
+    console.log('2. The skill auto-activates when you mention "semantic caching"');
+    console.log('   or invoke manually with /langcache\n');
+
+  } catch (err) {
+    console.warn(`⚠ Warning: ${err.message}`);
+    console.warn('Manually copy from node_modules/claude-code-langcache/skills/');
+  }
+}
+
+main();

package/skills/langcache/SKILL.md

@@ -0,0 +1,173 @@
+---
+name: langcache
+description: This skill should be used when the user asks to "enable semantic caching", "cache LLM responses", "reduce API costs", "speed up AI responses", "configure LangCache", "check the cache", or mentions Redis LangCache, semantic similarity caching, or LLM response caching. Provides integration with Redis LangCache managed service for semantic caching of prompts and responses.
+version: 1.0.0
+tools: Read, Bash, WebFetch
+---
+
+# Redis LangCache Semantic Caching
+
+Integrate [Redis LangCache](https://redis.io/langcache/) for semantic caching of LLM prompts and responses. Reduces costs and latency by returning cached results for semantically similar queries.
+
+## Prerequisites
+
+Set credentials in environment or `~/.claude/settings.local.json`:
+
+```bash
+export LANGCACHE_HOST=your-instance.redis.cloud
+export LANGCACHE_CACHE_ID=your-cache-id
+export LANGCACHE_API_KEY=your-api-key
+```
+
+## Quick Reference
+
+| Operation | Command |
+|-----------|---------|
+| Search cache | `./scripts/langcache.sh search "query"` |
+| Store response | `./scripts/langcache.sh store "prompt" "response"` |
+| Check if blocked | `./scripts/langcache.sh check "text"` |
+| Delete entry | `./scripts/langcache.sh delete --id <id>` |
+| Flush cache | `./scripts/langcache.sh flush` |
+
+## Default Caching Policy
+
+This policy is **enforced automatically** by the CLI and integration code.
+
+### CACHEABLE (white-list)
+
+| Category | Examples | Threshold |
+|----------|----------|-----------|
+| Factual Q&A | "What is X?", "How does Y work?" | 0.90 |
+| Definitions / docs | API docs, command help | 0.90 |
+| Command explanations | "What does `git rebase` do?" | 0.92 |
+| Reply templates | "polite no", "follow-up", "intro" | 0.88 |
+| Style transforms | "make this warmer/shorter" | 0.85 |
+
+### NEVER CACHE (hard blocks)
+
+| Category | Patterns | Reason |
+|----------|----------|--------|
+| **Temporal** | today, tomorrow, deadline, ETA, "in 20 min" | Stale immediately |
+| **Credentials** | API keys, passwords, tokens, OTP/2FA | Security |
+| **Identifiers** | emails, phones, account IDs, UUIDs | Privacy/PII |
+| **Personal** | "my wife said", relationships, private chats | Privacy |
+
+## Core Operations
+
+### Search for Cached Response
+
+Before calling an LLM, check for semantically similar cached response:
+
+```bash
+# Basic search
+./scripts/langcache.sh search "What is semantic caching?"
+
+# With similarity threshold (0.0-1.0, higher = stricter)
+./scripts/langcache.sh search "What is semantic caching?" --threshold 0.95
+
+# With attribute filtering
+./scripts/langcache.sh search "query" --attr "model=gpt-5"
+```
+
+**Response (hit):**
+```json
+{"hit": true, "response": "...", "similarity": 0.94, "entryId": "abc123"}
+```
+
+**Response (miss):**
+```json
+{"hit": false}
+```
+
+**Response (blocked):**
+```json
+{"hit": false, "blocked": true, "reason": "temporal_info"}
+```
+
+### Store New Response
+
+After LLM call, cache for future use:
+
+```bash
+# Basic store
+./scripts/langcache.sh store "What is Redis?" "Redis is an in-memory data store..."
+
+# With attributes for organization/filtering
+./scripts/langcache.sh store "prompt" "response" --attr "model=gpt-5" --attr "category=factual"
+```
+
+### Check Policy Compliance
+
+Test if content would be blocked:
+
+```bash
+./scripts/langcache.sh check "What's on my calendar today?"
+# Output: BLOCKED: temporal_info
+
+./scripts/langcache.sh check "What is Redis?"
+# Output: ALLOWED: Content can be cached
+```
+
+### Delete Entries
+
+```bash
+# By ID
+./scripts/langcache.sh delete --id "abc123"
+
+# By attributes (bulk)
+./scripts/langcache.sh delete --attr "model=gpt-4"
+```
+
+### Flush Cache
+
+```bash
+./scripts/langcache.sh flush  # Interactive confirmation
+```
+
+## Integration Pattern
+
+Recommended cache-aside pattern for agent workflows:
+
+```
+1. Receive user prompt
+2. Check policy: is it cacheable?
+   - If blocked → skip cache, call LLM
+3. Search LangCache for similar cached response
+   - If hit (similarity ≥ threshold) → return cached
+4. Call LLM API
+5. Store prompt + response in LangCache
+6. Return response
+```
+
+## Search Strategies
+
+| Strategy | Description |
+|----------|-------------|
+| `semantic` (default) | Vector similarity matching |
+| `exact` | Case-insensitive exact match |
+| `exact,semantic` | Try exact first, fall back to semantic |
+
+```bash
+./scripts/langcache.sh search "query" --strategy "exact,semantic"
+```
+
+## Attributes for Cache Partitioning
+
+Use attributes to organize and filter cache entries:
+
+| Attribute | Purpose |
+|-----------|---------|
+| `model` | Separate caches per LLM model |
+| `category` | `factual`, `template`, `style`, `command` |
+| `version` | Invalidate when prompts change |
+| `user_id` | Per-user isolation (if needed) |
+
+## References
+
+- [API Reference](references/api-reference.md) - Complete REST API documentation
+- [Best Practices](references/best-practices.md) - Optimization techniques
+
+## Examples
+
+- [examples/basic-caching.sh](examples/basic-caching.sh) - Shell workflow
+- [examples/agent-integration.py](examples/agent-integration.py) - Python pattern with policy enforcement