Skip to main content

​
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
{
  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)
  }
}

{
  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
{
  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
    }
  }
}

{
  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
{
  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
  }
}

{
  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
  }
}
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
{
  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
  }
}

{
  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

# 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"
      }
    }
  }
}

# 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
    }
  }
}

# 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.
⌘I