Cipher Quickstart

Build a knowledge navigator agent that enhances your coding workflow with persistent memory and context awareness. This tutorial shows you how to create a cipher agent that acts as an intelligent knowledge companion for coding editors like Cursor or Claude Code.

1. Create Your Knowledge Navigator Agent

The heart of a cipher agent is the cipher.yml configuration file where you define the agent’s identity, memory, and capabilities. Create a new directory for your knowledge navigator:
mkdir code-navigator
cd code-navigator
Create a basic cipher.yml file:
# cipher.yml
systemPrompt: |
  You are a knowledge navigator for developers. You help programmers by:
  - Maintaining project context and codebase understanding
  - Remembering coding patterns, decisions, and solutions
  - Providing intelligent code suggestions and explanations
  - Learning from development sessions to improve assistance

llm:
  provider: anthropic
  model: claude-3-5-haiku-20241022
  apiKey: $ANTHROPIC_API_KEY
  maxIterations: 50
This configuration creates a coding-focused agent with persistent memory capabilities built-in.

2. Enhance Your Navigator’s Coding Expertise

Let’s enhance your agent’s coding capabilities. Modify the systemPrompt to create a specialized development navigator:
# cipher.yml
systemPrompt: |
  You are an expert knowledge navigator for software development teams. You excel at:
  - Understanding and remembering codebase architecture and patterns
  - Tracking development decisions, trade-offs, and technical debt
  - Providing context-aware coding assistance and best practices
  - Learning from code reviews and development sessions
  - Connecting related code concepts across the entire project
  - Maintaining team knowledge and institutional memory

llm:
  provider: anthropic
  model: claude-3-5-haiku-20241022
  apiKey: $ANTHROPIC_API_KEY
  maxIterations: 50
Test your agent from inside the code-navigator directory:
cipher --agent cipher.yml "What kind of coding assistant are you?"
Your agent should now respond with its specialized development focus and memory capabilities.

3. Add Codebase Analysis Capabilities

A core feature of cipher is connecting agents to external tools through the Model Context Protocol (MCP). Let’s give your navigator access to analyze your codebase. Add the filesystem MCP server to your configuration:
# cipher.yml
systemPrompt: |
  You are an expert knowledge navigator for software development teams. You excel at:
  - Understanding and remembering codebase architecture and patterns
  - Tracking development decisions, trade-offs, and technical debt
  - Providing context-aware coding assistance and best practices
  - Learning from code reviews and development sessions
  - Connecting related code concepts across the entire project
  - Maintaining team knowledge and institutional memory

llm:
  provider: anthropic
  model: claude-3-5-haiku-20241022
  apiKey: $ANTHROPIC_API_KEY
  maxIterations: 50

mcpServers:
  filesystem:
    type: stdio
    command: npx
    args:
      - -y
      - '@modelcontextprotocol/server-filesystem'
      - .
    connectionMode: lenient
The cipher runtime will automatically handle MCP server installation and integration when you first run the agent.

4. Build Knowledge from Your Codebase

Let’s create some sample code for your navigator to analyze and remember:
# Create a sample React component
mkdir src
echo "import React, { useState, useEffect } from 'react';

// UserProfile component handles user data display and editing
export const UserProfile = ({ userId }) => {
  const [user, setUser] = useState(null);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState(null);

  useEffect(() => {
    fetchUserData(userId);
  }, [userId]);

  const fetchUserData = async (id) => {
    try {
      setLoading(true);
      const response = await fetch(\`/api/users/\${id}\`);
      const userData = await response.json();
      setUser(userData);
    } catch (err) {
      setError('Failed to load user data');
    } finally {
      setLoading(false);
    }
  };

  if (loading) return <div>Loading...</div>;
  if (error) return <div>Error: {error}</div>;

  return (
    <div className=\"user-profile\">
      <h2>{user.name}</h2>
      <p>{user.email}</p>
    </div>
  );
};" > src/UserProfile.jsx
Start an interactive session with your enhanced navigator:
cipher --agent cipher.yml
Now ask it to analyze your code:
Please analyze the UserProfile.jsx component in the src/ directory. What patterns does it use, and remember this codebase structure for future assistance.
Your navigator will:
  1. Use the filesystem tool to read the component
  2. Analyze React patterns, hooks usage, and error handling
  3. Store the codebase knowledge in its persistent memory
  4. Provide insights about the code structure and patterns

5. Test Knowledge Persistence

Exit the session (/exit) and start a new one:
cipher --agent cipher.yml
Ask about the previous code analysis:
What React patterns did we analyze in our previous session? Can you suggest improvements for the UserProfile component?
Your navigator should recall the code analysis from its persistent memory and provide contextual suggestions, demonstrating how cipher maintains development knowledge across sessions.

6. Connect to Cursor or Claude Code

Now let’s configure your navigator as an MCP server that Cursor or Claude Code can connect to. This allows your coding editor to access the navigator’s knowledge and memory. First, enhance your agent configuration:
# cipher.yml - Production Navigator
systemPrompt: |
  You are an expert knowledge navigator for software development teams. You excel at:
  - Understanding and remembering codebase architecture and patterns
  - Tracking development decisions, trade-offs, and technical debt
  - Providing context-aware coding assistance and best practices
  - Learning from code reviews and development sessions
  - Connecting related code concepts across the entire project
  - Maintaining team knowledge and institutional memory

llm:
  provider: anthropic
  model: claude-3-5-haiku-20241022
  apiKey: $ANTHROPIC_API_KEY
  maxIterations: 50

evalLlm:
  provider: anthropic
  model: claude-3-7-sonnet-20250219
  apiKey: $ANTHROPIC_API_KEY

mcpServers:
  filesystem:
    type: stdio
    command: npx
    args:
      - -y
      - '@modelcontextprotocol/server-filesystem'
      - .
    connectionMode: lenient

sessions:
  maxSessions: 100
  sessionTTL: 14400000  # 4 hours

agentCard:
  name: CodeNavigator
  version: 1.0.0
  description: "Knowledge navigator for development teams with persistent memory"
  provider:
    organization: "YourTeam"
    url: "https://yourteam.dev"

7. Environment Variables Configuration

Before connecting to editors, configure your environment variables for enhanced capabilities. Create or update your .env file:
# API Configuration (Required)
OPENAI_API_KEY=sk-proj-...                    # Required for embeddings
ANTHROPIC_API_KEY=sk-ant-...                  # Required for Anthropic models

# Vector Database (Optional - enhances memory capabilities)
VECTOR_STORE_TYPE=qdrant                      # or 'milvus', default: 'in-memory'
VECTOR_STORE_HOST=localhost                   # Vector DB hostname
VECTOR_STORE_PORT=6333                        # Qdrant port (19530 for Milvus)
VECTOR_STORE_API_KEY=your-qdrant-key         # For cloud services
VECTOR_STORE_COLLECTION=code_knowledge        # Collection name

# Knowledge Graph (Optional - advanced relationship modeling)
KNOWLEDGE_GRAPH_ENABLED=true                  # Enable graph features
KNOWLEDGE_GRAPH_TYPE=neo4j                    # or 'in-memory'
KNOWLEDGE_GRAPH_HOST=localhost                # Neo4j hostname
KNOWLEDGE_GRAPH_PORT=7687                     # Neo4j bolt port
KNOWLEDGE_GRAPH_USERNAME=neo4j                # Neo4j username
KNOWLEDGE_GRAPH_PASSWORD=your-neo4j-password  # Neo4j password

# Storage Backend (Optional - for persistence)
STORAGE_CACHE_TYPE=redis                      # or 'in-memory'
STORAGE_CACHE_HOST=localhost                  # Redis hostname
STORAGE_CACHE_PORT=6379                       # Redis port
STORAGE_DATABASE_TYPE=sqlite                  # or 'in-memory'
STORAGE_DATABASE_PATH=./data                  # SQLite path

# Logging
CIPHER_LOG_LEVEL=info                         # error, warn, info, debug
REDACT_SECRETS=true                           # Hide API keys in logs

Configuration Priority

  1. Environment variables (.env file) - Highest priority
  2. Agent configuration (cipher.yml) - Medium priority
  3. System defaults - Lowest priority

Required vs Optional Variables

Always Required:
  • OPENAI_API_KEY - For embeddings, even with other LLM providers
Provider-specific Required:
  • ANTHROPIC_API_KEY - When using Anthropic models
  • OPENROUTER_API_KEY - When using OpenRouter
External Services (Optional but Recommended for Production):
  • Qdrant: VECTOR_STORE_HOST when VECTOR_STORE_TYPE=qdrant
  • Milvus: VECTOR_STORE_HOST + VECTOR_STORE_USERNAME/PASSWORD when VECTOR_STORE_TYPE=milvus
  • Neo4j: KNOWLEDGE_GRAPH_PASSWORD when KNOWLEDGE_GRAPH_ENABLED=true
  • Redis: STORAGE_CACHE_HOST when STORAGE_CACHE_TYPE=redis

8. Start Your Navigator as an MCP Server

Start your navigator in MCP server mode so editors can connect to it:
npx cipher --agent cipher.yml --mode mcp

Connect from Cursor

Add this configuration to your Cursor settings (settings.json):
{
  "mcp.servers": {
    "code-navigator": {
      "command": "cipher",
      "args": ["--agent", "/path/to/your/code-navigator/cipher.yml", "--mode", "mcp"],
      "env": {
        "ANTHROPIC_API_KEY": "your-anthropic-key",
        "OPENAI_API_KEY": "your-openai-key",
        "VECTOR_STORE_TYPE": "qdrant",
        "VECTOR_STORE_HOST": "localhost",
        "VECTOR_STORE_PORT": "6333",
        "KNOWLEDGE_GRAPH_ENABLED": "true",
        "KNOWLEDGE_GRAPH_TYPE": "neo4j",
        "KNOWLEDGE_GRAPH_HOST": "localhost",
        "KNOWLEDGE_GRAPH_PASSWORD": "your-neo4j-password",
        "STORAGE_CACHE_TYPE": "redis",
        "STORAGE_DATABASE_TYPE": "sqlite"
      }
    }
  }
}
For basic setup (in-memory only):
{
  "mcp.servers": {
    "code-navigator": {
      "command": "cipher",
      "args": ["--agent", "/path/to/your/code-navigator/cipher.yml", "--mode", "mcp"],
      "env": {
        "ANTHROPIC_API_KEY": "your-anthropic-key",
        "OPENAI_API_KEY": "your-openai-key"
      }
    }
  }
}

Connect from Claude Code

Create an MCP configuration file (.mcp.json) in your project root:
{
  "mcpServers": {
    "code-navigator": {
      "command": "cipher",
      "args": ["--agent", "./cipher.yml", "--mode", "mcp"],
      "env": {
        "ANTHROPIC_API_KEY": "your-anthropic-key",
        "OPENAI_API_KEY": "your-openai-key",
        "VECTOR_STORE_TYPE": "qdrant",
        "VECTOR_STORE_HOST": "localhost",
        "VECTOR_STORE_PORT": "6333",
        "KNOWLEDGE_GRAPH_ENABLED": "true",
        "KNOWLEDGE_GRAPH_TYPE": "neo4j",
        "KNOWLEDGE_GRAPH_HOST": "localhost",
        "KNOWLEDGE_GRAPH_PASSWORD": "your-neo4j-password",
        "STORAGE_CACHE_TYPE": "redis",
        "STORAGE_DATABASE_TYPE": "sqlite"
      }
    }
  }
}
For basic setup (in-memory only):
{
  "mcpServers": {
    "code-navigator": {
      "command": "cipher",
      "args": ["--agent", "./cipher.yml", "--mode", "mcp"],
      "env": {
        "ANTHROPIC_API_KEY": "your-anthropic-key",
        "OPENAI_API_KEY": "your-openai-key"
      }
    }
  }
}

External Database Setup

For production setups with external databases: Qdrant (Vector Database):
# Docker setup
docker run -p 6333:6333 qdrant/qdrant
Neo4j (Knowledge Graph):
# Docker setup
docker run -p 7474:7474 -p 7687:7687 \
  -e NEO4J_AUTH=neo4j/your-password \
  neo4j:latest
Redis (Caching):
# Docker setup
docker run -p 6379:6379 redis:latest

9. Other Usage Modes

Your navigator also supports direct interaction: Interactive CLI Mode:
cipher --agent cipher.yml
One-shot Code Questions:
cipher --agent cipher.yml "Analyze the error handling patterns in this codebase"
API Server Mode:
cipher --agent cipher.yml --mode api --port 3000
Then use HTTP requests:
curl -X POST http://localhost:3000/api/message/sync \
  -H "Content-Type: application/json" \
  -d '{"message": "What coding patterns have we discussed?"}'

Congratulations! 🎉

You’ve just built your first knowledge navigator that enhances your coding workflow with persistent memory! You’ve learned how to: ✅ Create a coding-focused agent with cipher.yml configuration
✅ Give your navigator development expertise through specialized prompts
✅ Add codebase analysis capabilities via MCP filesystem integration
✅ Build persistent knowledge from code analysis
✅ Connect your navigator to Cursor or Claude Code as an MCP server
✅ Test knowledge persistence across coding sessions

Key Advantages for Developers

Unlike traditional coding assistants, your cipher navigator:
  • Remembers your codebase: Maintains understanding of architecture, patterns, and decisions
  • Learns from your team: Builds institutional knowledge from code reviews and discussions
  • Provides context-aware help: Suggests improvements based on your existing code patterns
  • Persists across sessions: Maintains project knowledge even after editor restarts
  • Integrates seamlessly: Works with your existing development tools through MCP

Your Development Workflow Enhanced

With cipher integrated into your editor:
  1. Write code in Cursor or Claude Code as usual
  2. Ask your navigator about patterns, best practices, or architecture decisions
  3. Get contextual suggestions based on your existing codebase
  4. Build team knowledge as the navigator learns from your development sessions
  5. Maintain continuity across coding sessions and team member changes

Next Steps

  • Expand tool integration: Add MCP servers for Git, databases, testing frameworks
  • Try different models: Experiment with OpenAI, OpenRouter, or local Ollama models
  • Scale your setup: Configure advanced memory backends (Neo4j, Redis, vector stores)
  • Create specialized navigators: Build domain-specific agents for frontend, backend, DevOps, or testing
Your cipher navigator is now ready to become an integral part of your development workflow, growing smarter with every coding session!