knowledge-base-cache

name	knowledge-base-cache
description	Use when managing large knowledge bases, reducing API costs, or implementing multi-tier caching for frequent queries
version	1

Knowledge Base Cache Skill

Overview

A layered knowledge base system with hot/cold/warm cache tiers and intelligent Working Memory for context management. Reduces API costs through multi-tier caching while supporting unlimited knowledge scale.

When to Use

Use this skill when:

• Managing large knowledge bases that exceed context window limits
• Reducing API costs for frequent knowledge queries
• Implementing multi-tier caching (hot/cold/warm) for knowledge retrieval
• Needing intelligent context assembly with token budget management
• Requiring automatic caching with semantic retrieval capabilities

Do NOT use when:

• Simple, small knowledge bases that fit in a single context window
• One-off queries where caching overhead exceeds savings
• Only basic file storage without caching tiers is needed

Create a structured knowledge repository with layered architecture (hot/cold/warm) and intelligent context management.

Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│                  Application Layer                  │
│                    Agent Core                               │
└──────────────────────────┬──────────────────────────────────┘
                           │
┌──────────────────────────▼──────────────────────────────────┐
│              Working Memory Layer                      │
│  • Context Assembly        • Token Budget Management        │
│  • Multi-Source Coordination • LRU Cache                    │
└─────────────┬───────────────────────────────────────────────┘
              │ Standard Interface KnowledgeSource
    ┌─────────┼─────────┐
    ▼         ▼         ▼ (Reserved)
┌───────┐ ┌───────┐ ┌───────┐
│  Hot  │ │  Cold │ │ Warm  │
│ Cache │ │Storage│ │Vector │
│ Layer │ │ Layer │ │ Layer │
└───┬───┘ └───┬───┘ └───┬───┘
    │         │         │
Context   Repository  Vector DB
 Cache     Files     (Future)

Three-Tier Architecture

Tier	Technology	Use Case	Status
🔥 Hot	Context Cache (API)	Full document retrieval, 90% cost savings	✅ Available
❄️ Cold	Repository Files	Keyword search, browsing, discovery	✅ Available
🌡️ Warm	Vector DB	Semantic search, precise Q&A	🔮 Planned

What This Skill Does

1. Layered Knowledge Storage

   repository/
   ├── core/                    # Core components
   │   ├── __init__.py          # Standard interfaces
   │   └── working_memory.py    # Working Memory layer
   ├── adapters/                # Layer adapters
   │   ├── __init__.py
   │   ├── hot_cache_adapter.py
   │   ├── cold_storage_adapter.py
   │   └── warm_cache_adapter.py (reserved)
   ├── index.json               # Knowledge index
   ├── cache-state.json         # Cache status
   ├── skills/                  # Skill knowledge
   ├── docs/                    # Document knowledge
   └── scripts/
       ├── cache_manager.py     # Cache management
       └── cache_helper.py      # Helper utilities
   

2. Working Memory Layer

   • Unified interface for all knowledge sources
   • Automatic context assembly with token budgeting
   • LRU cache for repeated queries
   • Cross-tier result ranking

3. Context Caching (Hot Layer)

   • Full document caching via API
   • 90% cost reduction
   • 83% latency improvement

4. File-Based Storage (Cold Layer)

   • Keyword-based retrieval
   • Excerpt generation
   • No API costs

5. Auto-Refresh

   • Configures cron job for daily refresh
   • Keeps caches fresh without manual intervention

Quick Start

Step 1: Initialize Repository

# The repository structure is already created
# If not, run:
python scripts/init_knowledge_base.py

Step 2: Add Knowledge

Add markdown files to appropriate directories:

• repository/skills/ - Skill documentation
• repository/docs/ - General documentation
• repository/projects/ - Project-specific knowledge

Step 3: Build Cache

cd repository

# Initialize index
python scripts/cache_manager.py init

# Build hot cache (Context Caching)
python scripts/cache_manager.py build

# Test the system
python test_phase1.py

Step 4: Use in Your Agent

Modern Approach (Recommended):

from repository.core.working_memory import WorkingMemoryManager

# Initialize once
wm = WorkingMemoryManager({
    'max_tokens': 6000,
    'allocation': {
        'system_prompt': 0.15,      # 15%
        'conversation': 0.25,        # 25%
        'retrieved_knowledge': 0.60  # 60%
    }
})

# Use in conversations
context = wm.query(
    user_query="How do I deploy?",
    system_prompt="You are an assistant...",
    conversation=history_messages
)

Legacy Approach:

from scripts.cache_helper import get_cache_headers, load_knowledge_context

# Get cache headers for API calls
headers = get_cache_headers()

# Load knowledge context
context = load_knowledge_context()

Step 5: Configure Auto-Refresh

# Add cron job for daily refresh
# Configure in your agent's cron system

Layer Details

🔥 Hot Cache Layer

Purpose: Store frequently accessed complete documents

When to Use:

• Reading full skill documentation
• API reference lookup
• Deployment guides

Implementation: adapters/hot_cache_adapter.py

from adapters.hot_cache_adapter import HotCacheAdapter
from core import RetrievalQuery

hot = HotCacheAdapter()
result = hot.retrieve(RetrievalQuery(
    query="Docker deployment",
    context_budget=2000,
    top_k=3
))

❄️ Cold Storage Layer

Purpose: Keyword-based file retrieval with excerpt generation

When to Use:

• Browsing knowledge base
• Finding relevant files
• Low-cost retrieval

Implementation: adapters/cold_storage_adapter.py

from adapters.cold_storage_adapter import ColdStorageAdapter
from core import RetrievalQuery

cold = ColdStorageAdapter()
result = cold.retrieve(RetrievalQuery(
    query="Docker deployment",
    context_budget=2000,
    top_k=5
))

🌡️ Warm Cache Layer (Planned)

Purpose: Semantic search with vector embeddings

When to Use:

• Precise Q&A
• Semantic similarity matching
• Large knowledge bases

Implementation: Reserved interface in adapters/warm_cache_adapter.py

Working Memory Configuration

Token Budget Allocation

Default allocation (customizable):

Component	Percentage	Tokens (6K total)
System Prompt	15%	900
Conversation	25%	1,500
Retrieved Knowledge	60%	3,600

Configuration Options

from repository.core.working_memory import WorkingMemoryManager
from repository.core import MemoryAllocation

wm = WorkingMemoryManager({
    'max_tokens': 8000,                    # Total context window
    'lru_cache_size': 10,                  # LRU cache size
    'allocation': {
        'system_prompt': 0.20,             # 20%
        'conversation': 0.20,              # 20%
        'retrieved_knowledge': 0.60        # 60%
    },
    'repo_path': 'repository'              # Repository path
})

Cache Management Commands

Command	Description
cache_manager.py init	Scan repository and update index
cache_manager.py build	Create/update hot caches
cache_manager.py status	Show cache status
cache_manager.py refresh	Refresh expired caches
cache_manager.py stats	Show statistics

Testing Commands

# Run Phase 1 integration tests
cd repository
python test_phase1.py

# Test individual layers
python -c "from adapters.hot_cache_adapter import HotCacheAdapter; print(HotCacheAdapter().get_stats())"
python -c "from adapters.cold_storage_adapter import ColdStorageAdapter; print(ColdStorageAdapter().get_stats())"

Cost Benefits

Hot Layer (Context Cache)

Metric	Without Cache	With Cache	Savings
Cost per 1000 queries	~¥150	~¥15	90%
First token latency	~30s	~5s	83%
Monthly cost (daily 50 queries)	~¥450	~¥45	¥405

Cold Layer (File Storage)

Metric	Value
API Cost	¥0 (no API calls)
Latency	~10-50ms (local files)
Best For	Browsing, discovery, keyword search

Working Memory Layer

Metric	Value
Context Assembly	Automatic
Token Budget	Enforced
Multi-Source	Hot + Cold (+ Warm in future)
LRU Cache	Reduces repeated queries

Troubleshooting

Cache Not Working

# Check if caches are active
python scripts/cache_manager.py status

# Rebuild if needed
python scripts/cache_manager.py build

# Verify hot layer
python -c "from adapters.hot_cache_adapter import HotCacheAdapter; print(HotCacheAdapter().is_available())"

Working Memory Not Finding Knowledge

# Debug: Check registered sources
from repository.core.working_memory import WorkingMemoryManager

wm = WorkingMemoryManager()
print(wm.get_stats())

# Debug: Test individual layers
from adapters.hot_cache_adapter import HotCacheAdapter
from adapters.cold_storage_adapter import ColdStorageAdapter
from core import RetrievalQuery

hot = HotCacheAdapter()
cold = ColdStorageAdapter()

query = RetrievalQuery(query="test", context_budget=2000)
print("Hot:", hot.retrieve(query))
print("Cold:", cold.retrieve(query))

API Key Issues

Ensure API key is set in environment or config for hot layer. Cold layer works without API keys.

Path Issues

All paths in generated files are relative (workspace-relative) for portability.

Migration from v1

If you were using the old cache system:

1. Old way still works: cache_helper.py functions unchanged
2. New way recommended: Use WorkingMemoryManager for better control
3. Same repository structure: No migration needed

References

• Context Caching documentation
• Component architecture design