Reflection memory

Reflection memory is cipher’s advanced learning system that captures, evaluates, and stores reasoning patterns and decision-making processes. Unlike knowledge memory which stores factual information, reflection memory focuses on the “how” and “why” of reasoning, enabling continuous improvement of agent capabilities through pattern analysis and reuse.

Configuration

Required Environment Variables

# OpenAI API Key (Required for embeddings)
OPENAI_API_KEY=sk-proj-your-openai-key-here

# Vector Store Type (Required)
VECTOR_STORE_TYPE=qdrant  # qdrant, milvus, in-memory

# Reflection Memory Collection (Required for reflection memory)
REFLECTION_VECTOR_STORE_COLLECTION=reflection_memory

Vector Storage Configuration

Reflection memory uses the same vector storage backends as knowledge memory but requires a separate collection:

Qdrant Configuration

# Connection Options (choose one)
VECTOR_STORE_URL=http://localhost:6333           # Complete URL
# OR
VECTOR_STORE_HOST=localhost                      # Host + Port
VECTOR_STORE_PORT=6333

# Optional Settings
VECTOR_STORE_API_KEY=your-qdrant-api-key        # For Qdrant Cloud
VECTOR_STORE_DIMENSION=1536                     # Embedding dimensions
VECTOR_STORE_DISTANCE=Cosine                    # Distance metric
VECTOR_STORE_ON_DISK=false                      # Store vectors on disk

# Reflection Memory Specific
REFLECTION_VECTOR_STORE_COLLECTION=reflection_memory  # Separate collection
DISABLE_REFLECTION_MEMORY=false                        # Enable/disable reflection

Milvus Configuration

# Connection Options (choose one)
VECTOR_STORE_URL=http://localhost:19530          # Complete URL
# OR
VECTOR_STORE_HOST=localhost                      # Host + Port
VECTOR_STORE_PORT=19530

# Authentication (Zilliz Cloud)
VECTOR_STORE_USERNAME=your-username              # Optional
VECTOR_STORE_PASSWORD=your-password              # Optional
VECTOR_STORE_API_KEY=your-api-token             # Optional

# Collection Settings
VECTOR_STORE_DIMENSION=1536                     # Embedding dimensions
REFLECTION_VECTOR_STORE_COLLECTION=reflection_memory  # Separate collection

Development Configuration

# In-Memory (Development/Testing)
VECTOR_STORE_TYPE=in-memory
VECTOR_STORE_DIMENSION=1536
REFLECTION_VECTOR_STORE_COLLECTION=reflection_memory
VECTOR_STORE_MAX_VECTORS=10000                  # Memory limit

Agent Configuration

For reflection memory to work optimally, you should configure an evaluation LLM in your cipher.yml file:

# cipher.yml
llm:
  provider: anthropic
  model: claude-3-5-haiku-20241022
  apiKey: $ANTHROPIC_API_KEY

# Evaluation LLM for reasoning assessment (recommended)
evalLlm:
  provider: anthropic
  model: claude-3-5-sonnet-20241022
  apiKey: $ANTHROPIC_API_KEY

Note: If evalLlm is not specified, the evaluation tool will default to using the same model as llm. Using a separate evaluation model can provide more objective assessment of reasoning quality.

Reflection Memory Tools

Cipher provides four specialized tools for reflection memory management:

Extract Reasoning Steps Tool

cipher_extract_reasoning_steps This tool analyzes user input to identify and extract reasoning patterns, thought processes, and decision-making steps. It detects both explicit reasoning markup and implicit reasoning patterns from natural language. Important: This tool is only executed automatically when cipher detects reasoning content in user input. It does not run on every interaction - only when the system identifies that the input contains structured reasoning patterns or explicit reasoning markup. Key Features:

Automatic detection of reasoning content in conversations
Extraction of explicit markup (Thought:, Action:, Observation:)
Implicit reasoning pattern recognition from natural language
Task context extraction and categorization
Structured reasoning trace generation

Input Parameters

{
  userInput: string,                            // Original user input with reasoning
  reasoningContent?: string,                    // [DEPRECATED] Kept for compatibility
  options?: {                                   // Optional extraction configuration
    extractExplicit?: boolean,                  // Extract explicit markup (default: true)
    extractImplicit?: boolean,                  // Extract implicit patterns (default: true)
    includeMetadata?: boolean                   // Include context metadata (default: true)
  }
}

Output Structure

{
  success: boolean,
  result: {
    trace: {
      id: string,                               // Unique trace identifier
      steps: Array<{
        type: 'thought' | 'action' | 'observation' | 'decision' | 'conclusion' | 'reflection',
        content: string
      }>,
      metadata: {
        extractedAt: string,                    // ISO timestamp
        conversationLength: number,             // Input length in characters
        stepCount: number,                      // Number of reasoning steps
        hasExplicitMarkup: boolean,             // Contains explicit reasoning markup
        sessionId?: string,                     // Session identifier
        taskContext?: {                         // Auto-extracted task context
          goal?: string,                        // What agent was trying to achieve
          input?: string,                       // Original user request
          taskType?: string,                    // Type of task (e.g., code_generation)
          domain?: string,                      // Problem domain (e.g., programming)
          complexity?: 'low' | 'medium' | 'high'
        }
      }
    }
  },
  metadata: {
    toolName: 'extract_reasoning_steps',
    extractionTime: number,
    patternCount: number
  }
}

Evaluate Reasoning Tool

cipher_evaluate_reasoning This tool assesses the quality, efficiency, and effectiveness of extracted reasoning traces. It provides quality scores, identifies issues, and determines whether the reasoning should be stored for future reference. Important: This tool is automatically triggered only after reasoning extraction when cipher has detected and extracted reasoning content. It does not evaluate non-reasoning interactions. Key Features:

Multi-dimensional quality assessment (quality, efficiency, clarity)
Issue identification and severity classification
Improvement suggestions generation
Storage recommendation decisions
Pattern analysis and completeness checking

Input Parameters

{
  trace: {                                      // Reasoning trace from extract tool
    id: string,
    steps: Array<{
      type: string,
      content: string
    }>,
    metadata: {
      extractedAt: string,
      conversationLength: number,
      stepCount: number,
      hasExplicitMarkup: boolean,
      taskContext?: object
    }
  }
}

Output Structure

{
  success: boolean,
  result: {
    evaluation: {
      qualityScore: number,                     // Overall quality (0.0-1.0)
      issues: Array<{
        type: string,                           // Issue category
        description: string,                    // Detailed description
        severity: 'low' | 'medium' | 'high'   // Issue severity
      }>,
      suggestions: string[],                    // Improvement recommendations
      shouldStore: boolean,                     // Whether to store this reasoning
      metrics?: {                               // Optional detailed metrics
        efficiency: number,                     // Process efficiency (0.0-1.0)
        clarity: number,                        // Reasoning clarity (0.0-1.0)
        completeness: number                    // Solution completeness (0.0-1.0)
      }
    }
  },
  metadata: {
    toolName: 'evaluate_reasoning',
    evaluationTime: number
  }
}

Store Reasoning Memory Tool

cipher_store_reasoning_memory This tool stores high-quality reasoning traces with their evaluations in the reflection memory system. It operates in append-only mode and only stores reasoning that meets quality thresholds. Important: This tool is automatically executed only for high-quality reasoning that has been extracted and evaluated. It only runs when the evaluation determines the reasoning should be stored (when shouldStore: true). Key Features:

Append-only storage (no updates or deletions)
Quality threshold enforcement
Unified trace and evaluation storage
Rich metadata preservation
Automatic embedding generation for search

Input Parameters

{
  trace: {                                      // Complete reasoning trace
    id: string,
    steps: Array<{
      type: string,
      content: string
    }>,
    metadata: object
  },
  evaluation: {                                 // Quality evaluation results
    qualityScore: number,
    issues: Array<object>,
    suggestions: string[],
    shouldStore: boolean
  }
}

Output Structure

{
  success: boolean,
  result: {
    message: string,                            // Storage result message
    stored: boolean                             // Whether trace was stored
  },
  metadata: {
    toolName: 'store_reasoning_memory',
    vectorId?: string,                          // Generated vector ID (if stored)
    qualityScore?: number,                      // Quality score
    skipped?: boolean,                          // If storage was skipped
    reason?: string                             // Reason for skipping
  }
}

Storage Payload

Reflection memories are stored with comprehensive metadata:

interface ReasoningPayload {
  id: string,
  text: string,                                 // Searchable reasoning content
  tags: string[],                               // Always ['reasoning']
  timestamp: string,
  version: 2,
  
  // Reasoning-specific data
  reasoningSteps: Array<{
    type: string,                               // Step type (thought, action, etc.)
    content: string                             // Step content
  }>,
  evaluation: {
    qualityScore: number,                       // Quality assessment (0.0-1.0)
    issues: Array<{
      type: string,
      description: string,
      severity?: string
    }>,
    suggestions: string[]                       // Improvement recommendations
  },
  context: string,                              // Task context summary
  stepCount: number,                            // Number of reasoning steps
  stepTypes: string[],                          // Unique step types
  issueCount: number,                           // Number of identified issues
  sourceSessionId?: string                      // Source session tracking
}

Search Reasoning Patterns Tool

cipher_search_reasoning_patterns This tool performs semantic search over stored reflection memory to find relevant reasoning patterns that can inform current decision-making processes. Key Features:

Semantic search over reasoning patterns
Context-aware filtering by task type and domain
Query deduplication to reduce redundant searches
Detailed similarity scoring and ranking
Pattern analysis and recommendations

Input Parameters

{
  query: string,                                // Natural language search query
  context?: {                                   // Optional filtering context
    taskType?: string,                          // Task type filter
    domain?: string,                            // Domain filter (e.g., javascript, python)
    complexity?: 'low' | 'medium' | 'high'    // Complexity level filter
  }
}

Output Structure

{
  success: boolean,
  result: {
    patterns: Array<{
      id: string,
      text: string,                             // Reasoning content summary
      reasoningSteps: Array<{
        type: string,
        content: string
      }>,
      evaluation: {
        qualityScore: number,
        issues: Array<object>,
        suggestions: string[]
      },
      context: string,                          // Task context
      stepCount: number,
      stepTypes: string[],
      similarity: number,                       // Search similarity score
      timestamp: string
    }>,
    metadata: {
      searchTime: number,
      totalResults: number,
      deduplicatedQuery?: boolean,              // If query was deduplicated
      originalQuery?: string                    // Original similar query
    }
  }
}

Advanced Features

Intelligent Reasoning Detection

Reflection memory automatically detects reasoning content in conversations and only processes interactions that contain reasoning:

Explicit Markup: Recognizes structured reasoning with tags like “Thought:”, “Action:”, “Observation:”
Implicit Patterns: Identifies natural language reasoning patterns and decision-making processes
Context Extraction: Automatically infers task goals, complexity, and domain from conversation context
Quality Filtering: Only processes interactions that contain meaningful reasoning content

Key Behavior: When cipher receives outputs from reasoning models or human users that contain reasoning patterns, it automatically extracts and evaluates these reasoning traces for future usage. Non-reasoning and simple retrieval inputs are completely skipped - no reflection memory tools are executed for basic questions, factual queries, or simple requests that don’t involve step-by-step reasoning processes. This selective processing ensures that reflection memory focuses only on valuable reasoning patterns while avoiding noise from routine interactions.

Multi-Dimensional Quality Assessment

The evaluation system assesses reasoning across multiple dimensions:

Quality Score: Overall reasoning effectiveness and correctness
Efficiency: How streamlined and direct the reasoning process is
Clarity: How clear and understandable the reasoning steps are
Completeness: Whether the reasoning covers all necessary aspects

Automatic Storage Decisions

The system intelligently decides what reasoning to preserve:

Quality Thresholds: Only stores reasoning above configurable quality scores
Issue Analysis: Identifies common reasoning pitfalls and areas for improvement
Storage Recommendations: Uses evaluation results to determine storage worthiness
Append-Only: Never modifies stored reasoning, maintaining historical accuracy

Query Deduplication

Search functionality includes intelligent query optimization:

Similarity Detection: Identifies similar search queries within recent time windows
Result Caching: Avoids redundant searches for similar queries
Session Tracking: Maintains query history per session for better deduplication
Performance Optimization: Reduces unnecessary vector search operations

Examples

Basic Reasoning Extraction

# User input with reasoning
User: "I need to solve this step by step:
Thought: The user wants to implement a React component
Action: I should break this down into smaller parts
Observation: We need state management and event handling
Decision: I'll use useState and event handlers
Conclusion: This approach will provide the required functionality"

# Extracted reasoning trace
{
  "trace": {
    "id": "trace_abc123",
    "steps": [
      {
        "type": "thought",
        "content": "The user wants to implement a React component"
      },
      {
        "type": "action", 
        "content": "I should break this down into smaller parts"
      },
      {
        "type": "observation",
        "content": "We need state management and event handling"
      },
      {
        "type": "decision",
        "content": "I'll use useState and event handlers"
      },
      {
        "type": "conclusion",
        "content": "This approach will provide the required functionality"
      }
    ],
    "metadata": {
      "stepCount": 5,
      "hasExplicitMarkup": true,
      "taskContext": {
        "taskType": "code_generation",
        "domain": "react",
        "complexity": "medium"
      }
    }
  }
}

Quality Evaluation Example

# Evaluation results
{
  "evaluation": {
    "qualityScore": 0.85,
    "issues": [
      {
        "type": "specificity",
        "description": "Could be more specific about state structure",
        "severity": "low"
      }
    ],
    "suggestions": [
      "Consider specifying the exact state variables needed",
      "Add implementation details for event handlers"
    ],
    "shouldStore": true,
    "metrics": {
      "efficiency": 0.90,
      "clarity": 0.80,
      "completeness": 0.85
    }
  }
}

Pattern Search Example

# Search query
"How to handle async operations in React components?"

# Search results
{
  "patterns": [
    {
      "text": "Step-by-step approach for implementing async data fetching in React hooks",
      "reasoningSteps": [
        {
          "type": "thought",
          "content": "Need to handle loading states and errors for async operations"
        },
        {
          "type": "action",
          "content": "Implement useEffect with async function and state management"
        }
      ],
      "evaluation": {
        "qualityScore": 0.92,
        "suggestions": ["Consider error boundaries for better error handling"]
      },
      "similarity": 0.89,
      "context": "React async patterns for data fetching"
    }
  ]
}

Best Practices

Configuration

Use separate collections - keep knowledge and reflection memory in different collections
Set quality thresholds - configure evaluation criteria based on your use case

Content Optimization

Use explicit reasoning markup - “Thought:”, “Action:”, “Observation:” for better extraction
Provide complete reasoning chains - include all steps from problem to solution
Include context information - specify task goals and problem domains clearly

Search Strategies

Query with specific context - “React async patterns” vs just “async patterns”
Use domain filters - specify taskType and domain for targeted results
Leverage pattern similarity - high-quality stored reasoning provides better search results

Memory Management

Monitor quality scores - reasoning below 0.6 may not provide value for reuse
Enable debug logging - set CIPHER_LOG_LEVEL=debug to see detailed reasoning analysis
Regular pattern analysis - review stored reasoning to identify improvement opportunities

Reflection memory transforms reasoning processes into a persistent, searchable knowledge base that enables continuous learning and reasoning improvement over time.

Getting Started

Configuration

Memory System

MCP Integration

Configuration

Required Environment Variables

Vector Storage Configuration

Qdrant Configuration

Milvus Configuration

Development Configuration

Agent Configuration

Reflection Memory Tools

Extract Reasoning Steps Tool

Evaluate Reasoning Tool

Store Reasoning Memory Tool

Search Reasoning Patterns Tool

Advanced Features

Intelligent Reasoning Detection

Multi-Dimensional Quality Assessment

Automatic Storage Decisions

Query Deduplication

Examples

Best Practices

Configuration

Content Optimization

Search Strategies

Memory Management

Getting Started

Configuration

Memory System

MCP Integration

​Configuration

​Required Environment Variables

​Vector Storage Configuration

​Qdrant Configuration

​Milvus Configuration

​Development Configuration

​Agent Configuration

​Reflection Memory Tools

​Extract Reasoning Steps Tool

​Evaluate Reasoning Tool

​Store Reasoning Memory Tool

​Search Reasoning Patterns Tool

​Advanced Features

​Intelligent Reasoning Detection

​Multi-Dimensional Quality Assessment

​Automatic Storage Decisions

​Query Deduplication

​Examples

​Best Practices

​Configuration

​Content Optimization

​Search Strategies

​Memory Management

Configuration

Required Environment Variables

Vector Storage Configuration

Qdrant Configuration

Milvus Configuration

Development Configuration

Agent Configuration

Reflection Memory Tools

Extract Reasoning Steps Tool

Evaluate Reasoning Tool

Store Reasoning Memory Tool

Search Reasoning Patterns Tool

Advanced Features

Intelligent Reasoning Detection

Multi-Dimensional Quality Assessment

Automatic Storage Decisions

Query Deduplication

Examples

Best Practices

Configuration

Content Optimization

Search Strategies

Memory Management