Memory-powered AI agent framework with MCP integration

Cipher is a simple, composable framework to build memory for agents using Model Context Protocol.

Key Features:

• Handles MCP server connection lifecycle management
• Layered memory system that improves with every run
• Memory aligned with cognitive structures
• Reflection mechanisms for agent learning
• Zero configuration changes required for memory improvements

Cipher is the simplest way to add persistent memory to MCP-compatible agents.

# Install globally npm install -g @byterover/cipher # Or install locally in your project npm install @byterover/cipher

# Clone and setup git clone https://github.com/campfirein/cipher.git cd cipher # Configure environment cp .env.example .env # Edit .env with your API keys # Start with Docker docker-compose up -d # Test curl http://localhost:3000/health

pnpm i && pnpm run build && npm link

# Interactive mode cipher # One-shot command cipher "What is binary search?" # API server mode cipher --mode api # MCP server mode cipher --mode mcp

Configure Cipher using environment variables and YAML config:

# Required: At least one API key (except Ollama) OPENAI_API_KEY=your_openai_api_key ANTHROPIC_API_KEY=your_anthropic_api_key OPENROUTER_API_KEY=your_openrouter_api_key # Ollama (self-hosted, no API key needed) OLLAMA_BASE_URL=http://localhost:11434/v1 # Optional CIPHER_LOG_LEVEL=info NODE_ENV=production

# LLM Configuration llm: provider: openai # openai, anthropic, openrouter, ollama model: gpt-4-turbo apiKey: $OPENAI_API_KEY # System Prompt systemPrompt: 'You are a helpful AI assistant with memory capabilities.' # MCP Servers (optional) mcpServers: filesystem: type: stdio command: npx args: ['-y', '@modelcontextprotocol/server-filesystem', '.']

• Multiple Operation Modes: CLI interactive, one-shot commands, REST API server, MCP server
• Session Management: Create, switch, and manage multiple conversation sessions
• Memory Integration: Persistent memory that learns from every interaction
• MCP Protocol Support: Full Model Context Protocol integration for tools and resources
• Multi-LLM Support: OpenAI, Anthropic, OpenRouter, and Ollama compatibility
• Knowledge Graph: Structured memory with entity relationships (Neo4j, in-memory)
• Real-time Learning: Memory layers that improve automatically with usage

Cipher supports multiple LLM providers:

llm: provider: openai model: gpt-4-turbo apiKey: $OPENAI_API_KEY

llm: provider: anthropic model: claude-3-5-sonnet-20241022 apiKey: $ANTHROPIC_API_KEY

llm: provider: openrouter model: openai/gpt-4-turbo # Any OpenRouter model apiKey: $OPENROUTER_API_KEY

llm: provider: ollama model: qwen2.5:32b # Recommended for best performance baseURL: $OLLAMA_BASE_URL

Recommended Ollama Models:

• High Performance: qwen2.5:32b, llama3.1:70b
• Balanced: qwen2.5:8b, llama3.1:8b
• Lightweight: phi3:mini, granite3-dense:2b

# Basic usage cipher # Interactive CLI mode cipher "Your prompt here" # One-shot mode # Server modes cipher --mode api # REST API server cipher --mode mcp # MCP server # Configuration cipher --agent /path/to/config.yml # Custom config cipher --strict # Strict MCP connections cipher --new-session [id] # Start with new session # CLI commands /session list # List sessions /session new [id] # Create session /session switch <id> # Switch session /config # Show config /stats # Show statistics /help # Show help

For detailed documentation, visit:

• Quick Start Guide
• Configuration Guide
• Complete Documentation

We welcome contributions! Refer to our Contributing Guide for more details.

cipher is the opensource version of the agentic memory of byterover which is built and maintained by the byterover team.

• Join our Discord to share projects, ask questions, or just say hi!
• If you enjoy cipher, please give us a ⭐ on GitHub—it helps a lot!
• Follow @kevinnguyendn on X

Thanks to all these amazing people for contributing to cipher!

Contributors

Elastic License 2.0. See LICENSE for full terms.