openclaw-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,167 @@
+# @openclaw/langcache
+
+Semantic caching skill for [OpenClaw](https://openclaw.ai) 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.
+
+## 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
+
+### Via npm (Recommended)
+
+```bash
+npm install @openclaw/langcache
+```
+
+The skill will be automatically installed to your OpenClaw workspace.
+
+### Via Git
+
+```bash
+git clone https://github.com/openclaw/langcache.git ~/.openclaw/workspace/skills/langcache
+```
+
+### Manual
+
+Download and extract to `~/.openclaw/workspace/skills/langcache/`
+
+## Configuration
+
+Add your Redis LangCache credentials to `~/.openclaw/secrets.env`:
+
+```bash
+LANGCACHE_HOST=your-instance.redis.cloud
+LANGCACHE_CACHE_ID=your-cache-id
+LANGCACHE_API_KEY=your-api-key
+```
+
+Get these from [Redis Cloud Console](https://app.redislabs.com/) after creating a LangCache instance.
+
+## Usage
+
+### Automatic (via OpenClaw agent)
+
+The skill triggers automatically when you mention:
+- "cache LLM responses"
+- "semantic caching"
+- "reduce API costs"
+- "configure LangCache"
+
+### CLI
+
+```bash
+# Search for cached response
+langcache.sh search "What is Redis?"
+
+# With similarity threshold
+langcache.sh search "What is Redis?" --threshold 0.9
+
+# Store a response
+langcache.sh store "What is Redis?" "Redis is an in-memory data store..."
+
+# Check if content would be blocked
+langcache.sh check "What's on my calendar today?"
+# Output: BLOCKED: temporal_info
+
+# Delete entries
+langcache.sh delete --id <entry-id>
+langcache.sh delete --attr model=gpt-4
+```
+
+### Python Integration
+
+```python
+from examples.agent_integration import CachedAgent, CacheConfig
+
+agent = CachedAgent(config=CacheConfig(
+    enabled=True,
+    model_id="gpt-5",
+))
+
+# Automatically uses cache with policy enforcement
+response = await agent.complete("What is semantic caching?")
+```
+
+## 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
+
+```
+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
+```
+
+## API Reference
+
+See [references/api-reference.md](skills/langcache/references/api-reference.md) for complete REST API documentation.
+
+### Key Endpoints
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/v1/caches/{id}/entries/search` | POST | Search for cached response |
+| `/v1/caches/{id}/entries` | POST | Store new entry |
+| `/v1/caches/{id}/entries/{entryId}` | DELETE | Delete by ID |
+| `/v1/caches/{id}/flush` | POST | Clear all entries |
+
+## Requirements
+
+- OpenClaw 2024.1.0+
+- Redis Cloud account with LangCache enabled
+- Node.js 18+ (for npm installation)
+- `jq` and `curl` (for CLI usage)
+
+## Contributing
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## Resources
+
+- [Redis LangCache Documentation](https://redis.io/docs/latest/develop/ai/langcache/)
+- [OpenClaw Documentation](https://docs.openclaw.ai)
+- [Semantic Caching Guide](https://redis.io/blog/what-is-semantic-caching/)

package/package.json

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

package/skills/langcache/SKILL.md

@@ -0,0 +1,187 @@
+---
+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", "search the semantic cache", "store responses in 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
+
+This skill integrates Redis LangCache, a fully-managed semantic caching service, into OpenClaw workflows. LangCache stores LLM prompts and responses, returning cached results for semantically similar queries to reduce costs and latency.
+
+## Prerequisites
+
+Before using LangCache, ensure the following environment variables are configured:
+
+```bash
+LANGCACHE_HOST=<your-langcache-host>
+LANGCACHE_CACHE_ID=<your-cache-id>
+LANGCACHE_API_KEY=<your-api-key>
+```
+
+Store these in `~/.openclaw/secrets.env` or configure them in the OpenClaw settings.
+
+## Core Operations
+
+### Search for Cached Response
+
+Before calling an LLM, check if a semantically similar response exists:
+
+```bash
+./scripts/langcache.sh search "What is semantic caching?"
+```
+
+With similarity threshold (0.0-1.0, higher = stricter match):
+
+```bash
+./scripts/langcache.sh search "What is semantic caching?" --threshold 0.95
+```
+
+With attribute filtering:
+
+```bash
+./scripts/langcache.sh search "What is semantic caching?" --attr "model=gpt-5"
+```
+
+### Store New Response
+
+After receiving an LLM response, cache it for future use:
+
+```bash
+./scripts/langcache.sh store "What is semantic caching?" "Semantic caching stores responses based on meaning similarity..."
+```
+
+With attributes for filtering/organization:
+
+```bash
+./scripts/langcache.sh store "prompt" "response" --attr "model=gpt-5" --attr "user_id=123"
+```
+
+### Delete Cached Entries
+
+By entry ID:
+
+```bash
+./scripts/langcache.sh delete --id "<entry-id>"
+```
+
+By attributes:
+
+```bash
+./scripts/langcache.sh delete --attr "user_id=123"
+```
+
+### Flush Cache
+
+Clear all entries (use with caution):
+
+```bash
+./scripts/langcache.sh flush
+```
+
+## Integration Pattern
+
+The recommended pattern for integrating LangCache into agent workflows:
+
+```
+1. Receive user prompt
+2. Search LangCache for similar cached response
+3. If cache hit (similarity >= threshold):
+   - Return cached response immediately
+   - Log cache hit for observability
+4. If cache miss:
+   - Call LLM API
+   - Store prompt + response in LangCache
+   - Return LLM response
+```
+
+## Default Caching Policy
+
+This policy is enforced automatically. All cache operations MUST respect these rules.
+
+### CACHEABLE (white-list)
+
+| Category | Examples | Threshold |
+|----------|----------|-----------|
+| Factual Q&A | "What is X?", "How does Y work?" | 0.90 |
+| Definitions / docs / help text | API docs, command help, explanations | 0.90 |
+| Command explanations | "What does `git rebase` do?" | 0.92 |
+| Reusable reply templates | "polite no", "follow-up", "scheduling", "intro" | 0.88 |
+| Style transforms | "make this warmer/shorter/firmer" | 0.85 |
+| Generic communication scripts | negotiation templates, professional responses | 0.88 |
+
+### NEVER CACHE (hard blocks)
+
+These patterns are **blocked at the code level** - cache operations will refuse to store them.
+
+| Category | Patterns to Detect | Reason |
+|----------|-------------------|--------|
+| **Temporal info** | today, tomorrow, this week, deadline, ETA, "in X minutes", appointments, schedules | Stale immediately |
+| **Credentials** | API keys, tokens, passwords, OTP, 2FA codes, secrets | Security risk |
+| **Identifiers** | phone numbers, emails, addresses, account IDs, order numbers, message IDs, chat IDs, JIDs | Privacy / PII |
+| **Personal context** | names + relationships, private history, "who said what", specific conversations | Privacy / context-dependent |
+
+### Detection Patterns
+
+The following regex patterns trigger a hard block:
+
+```
+# Temporal
+\b(today|tomorrow|tonight|yesterday)\b
+\b(this|next|last)\s+(week|month|year|monday|tuesday|...)\b
+\b(in\s+\d+\s+(minutes?|hours?|days?))\b
+\b(deadline|eta|appointment|schedule[d]?)\b
+
+# Credentials
+\b(api[_-]?key|token|password|secret|otp|2fa)\b
+\b(bearer|auth[orization]*)\s+\S+
+
+# Identifiers
+\b\d{10,}\b                          # phone numbers, long IDs
+\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+   # emails
+\b(order|account|message|chat)[_-]?id\b
+
+# Personal context
+\b(my\s+(wife|husband|partner|friend|boss|mom|dad|brother|sister))\b
+\b(said\s+to\s+me|told\s+me|between\s+us)\b
+```
+
+### Attribute Strategies
+
+Use attributes to partition the cache:
+
+- `model`: LLM model used (useful when switching models)
+- `category`: `factual`, `template`, `style`, `command`
+- `skill`: Which skill generated the response
+- `version`: API or prompt version
+
+## Search Strategies
+
+LangCache supports two search strategies:
+
+- **semantic** (default): Vector similarity matching
+- **exact**: Case-insensitive exact match
+
+Combine both for hybrid search:
+
+```bash
+./scripts/langcache.sh search "prompt" --strategy "exact,semantic"
+```
+
+## Observability
+
+Monitor cache performance:
+- Track hit/miss ratios
+- Log similarity scores for hits
+- Alert on high miss rates (may indicate threshold too high)
+- Review stored entries periodically for relevance
+
+## 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) - Simple cache workflow
+- [examples/agent-integration.py](examples/agent-integration.py) - Python integration pattern