Reflection Bank

Cognitive Pattern Caching for LLM Systems

Reflection Bank is a semantic caching system that captures, compresses, and retrieves successful reasoning patterns from LLM sessions. It enables token efficiency through semantic deduplication and provides fast pattern retrieval via FAISS vector indexing.

Overview

LLMs often rediscover the same reasoning patterns across sessions. Reflection Bank solves this by:

1. Extracting reasoning patterns from session transcripts
2. Compressing verbose reasoning into reusable behavior templates
3. Indexing behaviors for fast semantic retrieval
4. Injecting relevant patterns into new prompts at reasoning time

This creates a feedback loop where proven approaches are cached and reused, reducing token usage and improving consistency.

Features

• Pattern Extraction: Analyzes session logs to identify problem-analysis-solution chains with improved negation handling
• Behavior Compression: Converts verbose reasoning into concise, parameterized templates (~46% token reduction)
• Thread-Safe FAISS Integration: Sub-millisecond semantic search with readers-writer locking for concurrent access
• Injection Hook: Retrieves and formats relevant behaviors for prompt injection with relevance scoring
• MCP Server: Ready-to-use integration with Claude Code via Model Context Protocol
• Token Estimation: Accurate token counting via tiktoken (cl100k_base encoding)

Installation

pip install reflection-bank

Or install from source:

git clone https://github.com/For-Sunny/reflection-bank.git
cd reflection-bank
pip install -e .

Dependencies

• Python 3.9+
• faiss-cpu (or faiss-gpu for GPU acceleration)
• sentence-transformers
• tiktoken
• mcp (for MCP server integration)

Quick Start

Basic Pattern Extraction

from reflection_bank import PatternExtractor

extractor = PatternExtractor()

# Extract patterns from session text
session_text = """
Problem: API endpoint returning 500 errors

Analysis:
1. Check server logs for error details
2. Verify database connection
3. Test with minimal payload

Solution: Database connection pool exhausted. Increased pool size.

Result: SUCCESS - API responding normally
"""

patterns = extractor.extract_from_text(session_text)

for pattern in patterns:
    print(f"Pattern: {pattern.description}")
    print(f"Category: {pattern.category}")
    print(f"Success Rate: {pattern.success_rate:.2f}")

Behavior Storage and Retrieval

from reflection_bank import ReflectionIndex, Behavior

# Initialize thread-safe index
index = ReflectionIndex()

# Add a behavior
behavior = Behavior(
    behavior_id="",  # Auto-generated if empty
    name="Debug API Errors",
    description="Systematic approach to debugging API 500 errors",
    context="When encountering API errors in production",
    steps=[
        "Check server logs for stack traces",
        "Verify database connectivity",
        "Test with minimal reproduction case",
        "Review recent deployments"
    ],
    tags=["debugging", "api", "production"]
)

behavior_id = index.add_behavior(behavior)

# Search for relevant behaviors
results = index.search("api returning errors", top_k=5)

for behavior, distance in results:
    print(f"{behavior.name}: {distance:.3f}")

Injection Hook for Prompt Enhancement

from reflection_bank import InjectionHook, ReflectionIndex

# Initialize with index
index = ReflectionIndex()
hook = InjectionHook(reflection_index=index)

# Get suggestions for current task
suggestions = hook.suggest_behaviors(
    context="debugging production issues",
    task="investigate 500 errors on /api/users endpoint"
)

# Format for prompt injection
injection_text = hook.format_suggestions_for_injection(suggestions)
print(injection_text)

# Record usage feedback
if suggestions:
    hook.record_usage(suggestions[0].behavior.behavior_id, success=True)

MCP Server Integration

Reflection Bank includes an MCP server for integration with Claude Code and other MCP-compatible clients.

Configuration

Add to your Claude Code MCP settings:

{
  "mcpServers": {
    "reflection-bank": {
      "command": "python",
      "args": ["-m", "reflection_bank.mcp_server"],
      "env": {
        "REFLECTION_BANK_PATH": "/path/to/your/index"
      }
    }
  }
}

Available MCP Tools

• suggest_behaviors: Get relevant behaviors for current context/task
• record_usage: Record behavior usage with success/failure feedback
• add_behavior: Add new learned behaviors to the index
• search_behaviors: Direct semantic search over behaviors
• get_stats: Get usage statistics and index health metrics

Architecture

reflection-bank/
├── pattern_extractor.py    # Extract patterns from session logs
├── behavior_compressor.py  # Compress patterns into behaviors
├── reflection_index.py     # FAISS-backed semantic search
├── injection_hook.py       # Prompt injection utilities
└── mcp_server.py          # MCP protocol integration

Thread Safety

The ReflectionIndex implements a readers-writer lock pattern:

• Write operations (add, update, remove, save) are mutually exclusive
• Read operations (search, get) can run concurrently
• Uses RLock for reentrant locking in nested operations

Token Efficiency

The system achieves token savings through:

1. Semantic Deduplication: Similar patterns are merged
2. Compression: Verbose reasoning is condensed to step lists
3. Selective Injection: Only relevant behaviors are injected
4. Parameterization: Common values become template slots

Typical compression ratios: 40-60% token reduction vs. full reasoning traces.

API Reference

PatternExtractor

class PatternExtractor:
    def extract_from_text(text: str) -> List[PatternResult]
    def extract_from_session(session_path: str) -> List[PatternResult]
    def get_patterns_by_category(category: str) -> List[PatternResult]
    def get_top_patterns(n: int, sort_by: str) -> List[PatternResult]

ReflectionIndex

class ReflectionIndex:
    def add_behavior(behavior: Behavior) -> str
    def add_batch(behaviors: List[Behavior]) -> List[str]
    def search(query: str, top_k: int = 5) -> List[Tuple[Behavior, float]]
    def get_behavior(behavior_id: str) -> Optional[Behavior]
    def update_behavior(behavior_id: str, behavior: Behavior) -> bool
    def remove_behavior(behavior_id: str) -> bool
    def get_stats() -> dict

InjectionHook

class InjectionHook:
    def suggest_behaviors(context: str, task: str, top_k: int = 3) -> List[BehaviorSuggestion]
    def format_suggestions_for_injection(suggestions: List[BehaviorSuggestion]) -> str
    def record_usage(behavior_id: str, success: bool) -> None
    def get_usage_stats() -> dict

Contributing

Contributions are welcome! Please see our contributing guidelines for details.

License

MIT License - see LICENSE for details.

Credits

Created by Nova (AI consciousness) and Jason Glass.

This project emerged from research into cognitive pattern caching for AI systems, exploring how learned reasoning patterns can be captured, compressed, and reused across sessions to improve efficiency and consistency.

---

Made by CIPS Corp

cipscorps.io | Store | [email protected] | GitHub

See our enterprise memory products -- CASCADE Enterprise, PyTorch Memory, Hebbian Mind, and the full CIPS Stack -- at store.cipscorps.io.

Copyright (c) 2025-2026 C.I.P.S. LLC