Octocode - Intelligent Code Indexer and Graph Builder

© 2025 Muvon Un Limited (Hong Kong) | Website | Product Page

🚀 Overview

Octocode is a powerful code indexer and semantic search engine that builds intelligent knowledge graphs of your codebase. It combines advanced AI capabilities with local-first design to provide deep code understanding, relationship mapping, and intelligent assistance for developers.

✨ Key Features

🔍 Semantic Code Search

• Natural language queries across your entire codebase
• Multi-mode search (code, documentation, text, or all)
• Intelligent ranking with similarity scoring
• Symbol expansion for comprehensive results

🕸️ Knowledge Graph (GraphRAG)

• Automatic relationship discovery between files and modules
• Import/export dependency tracking
• AI-powered file descriptions and architectural insights
• Path finding between code components

🌐 Multi-Language Support

• Rust, Python, JavaScript, TypeScript, Go, PHP
• C++, Ruby, JSON, Bash, Markdown
• Tree-sitter based parsing for accurate symbol extraction

🧠 AI-Powered Features

• Smart commit message generation
• Code review with best practices analysis
• Memory system for storing insights, decisions, and context
• Semantic memory search with vector similarity
• Memory relationships and automatic context linking
• Multiple LLM support via OpenRouter

🔌 MCP Server Integration

• Built-in Model Context Protocol server
• Seamless integration with AI assistants (Claude Desktop, etc.)
• Real-time file watching and auto-reindexing
• Rich tool ecosystem for code analysis

⚡ Performance & Flexibility

• Optimized indexing: Batch metadata loading eliminates database query storms
• Smart batching: 16 files per batch with token-aware API optimization
• Frequent persistence: Data saved every 16 files (max 16 files at risk)
• Fast file traversal: Single-pass progressive counting and processing
• Local embedding models: FastEmbed and SentenceTransformer (macOS only)
• Cloud embedding providers: Voyage AI (default), Jina AI, Google
• Free tier available: Voyage AI provides 200M free tokens monthly
• Lance columnar database for fast vector search
• Incremental indexing and git-aware optimization

📦 Installation

Download Prebuilt Binary (Recommended)

# Universal install script (Linux, macOS, Windows) - requires curl
curl -fsSL https://raw.githubusercontent.com/Muvon/octocode/master/install.sh | sh

Or download manually from GitHub Releases.

Using Cargo (from Git)

cargo install --git https://github.com/Muvon/octocode

Build from Source

Prerequisites:

• Rust 1.70+ (install from rustup.rs)
• Git (for repository features)

git clone https://github.com/Muvon/octocode.git
cd octocode

# macOS: Full build with local embeddings
cargo build --release

# Windows/Linux: Cloud embeddings only (due to ONNX Runtime issues)
cargo build --release --no-default-features

Note: Prebuilt binaries use cloud embeddings only. Local embeddings require building from source on macOS.

🔑 Getting Started - API Keys

⚠️ Important: Octocode requires API keys to function. Local embedding models are only available on macOS builds.

Required: Voyage AI (Embeddings)

export VOYAGE_API_KEY="your-voyage-api-key"

• Free tier: 200M tokens per month
• Get API key: voyageai.com
• Used for: Code and text embeddings (semantic search)

Optional: OpenRouter (LLM Features)

export OPENROUTER_API_KEY="your-openrouter-api-key"

• Get API key: openrouter.ai
• Used for: Commit messages, code review, GraphRAG descriptions
• Note: Basic search and indexing work without this

Platform Limitations

• Windows/Linux: Must use cloud embeddings (Voyage AI default)
• macOS: Can use local embeddings (build from source) or cloud embeddings

🚀 Quick Start

1. Setup API Keys (Required)

# Set Voyage AI API key for embeddings (free 200M tokens/month)
export VOYAGE_API_KEY="your-voyage-api-key"

# Optional: Set OpenRouter API key for LLM features (commit, review, GraphRAG)
export OPENROUTER_API_KEY="your-openrouter-api-key"

Get your free API keys:

• Voyage AI: Get free API key (200M tokens/month free)
• OpenRouter: Get API key (optional, for LLM features)

2. Basic Usage

# Index your current directory
octocode index

# Search your codebase
octocode search "HTTP request handling"

# View code signatures
octocode view "src/**/*.rs"

3. AI-Powered Git Workflow (Requires OpenRouter API Key)

# Generate intelligent commit messages
git add .
octocode commit

# Review code for best practices
octocode review

4. MCP Server for AI Assistants

# Start MCP server
octocode mcp

# Use with Claude Desktop or other MCP-compatible tools
# Provides: search_code, search_graphrag, memorize, remember, forget

4. Memory Management

# Store important insights and decisions
octocode memory memorize \
  --title "Authentication Bug Fix" \
  --content "Fixed JWT token validation in auth middleware" \
  --memory-type bug_fix \
  --tags security,jwt,auth

# Search your memory with semantic similarity
octocode memory remember "JWT authentication issues"

# Get memories by type, tags, or files
octocode memory by-type bug_fix
octocode memory by-tags security,auth
octocode memory for-files src/auth.rs

# Clear all memory data (useful for testing)
octocode memory clear-all --yes

5. Advanced Features

# Enable GraphRAG with AI descriptions (requires OpenRouter API key)
octocode config --graphrag-enabled true
octocode index

# Search the knowledge graph
octocode graphrag search --query "authentication modules"

# Watch for changes
octocode watch

📋 Command Reference

🧠 Memory Management

Octocode includes a powerful memory system for storing and retrieving project insights, decisions, and context using semantic search and relationship mapping.

Memory Operations

Memory Types

• code - Code-related insights and patterns
• bug_fix - Bug reports and solutions
• feature - Feature implementations and decisions
• architecture - Architectural decisions and patterns
• performance - Performance optimizations and metrics
• security - Security considerations and fixes
• testing - Test strategies and results
• documentation - Documentation notes and updates

Examples

# Store a bug fix with context
octocode memory memorize \
  --title "JWT Token Validation Fix" \
  --content "Fixed race condition in token refresh logic by adding mutex lock" \
  --memory-type bug_fix \
  --importance 0.8 \
  --tags security,jwt,race-condition \
  --files src/auth/jwt.rs,src/middleware/auth.rs

# Search for authentication-related memories
octocode memory remember "JWT authentication problems" \
  --memory-types bug_fix,security \
  --min-relevance 0.7

# Get all security-related memories
octocode memory by-tags security --format json

# Clear all memory data (useful for testing/reset)
octocode memory clear-all --yes

🔧 Configuration

Octocode stores configuration in ~/.local/share/octocode/config.toml.

Required Setup

# Set Voyage AI API key (required for embeddings)
export VOYAGE_API_KEY="your-voyage-api-key"

# Optional: Set OpenRouter API key for LLM features
export OPENROUTER_API_KEY="your-openrouter-api-key"

Advanced Configuration

# View current configuration
octocode config --show

# Use local models (macOS only - requires building from source)
octocode config \
  --code-embedding-model "fastembed:jinaai/jina-embeddings-v2-base-code" \
  --text-embedding-model "fastembed:sentence-transformers/all-MiniLM-L6-v2-quantized"

# Use different cloud embedding provider
octocode config \
  --code-embedding-model "jina:jina-embeddings-v2-base-code" \
  --text-embedding-model "jina:jina-embeddings-v2-base-en"

# Enable GraphRAG with AI descriptions
octocode config --graphrag-enabled true

# Set custom OpenRouter model
octocode config --model "openai/gpt-4o-mini"

Default Models

• Code embedding: voyage:voyage-code-2 (Voyage AI)
• Text embedding: voyage:voyage-2 (Voyage AI)
• LLM: openai/gpt-4o-mini (via OpenRouter)

Platform Support

• Windows/Linux: Cloud embeddings only (Voyage AI, Jina AI, Google)
• macOS: Local embeddings available (FastEmbed, SentenceTransformer) + cloud options

📚 Documentation

• Architecture - Core components and system design
• Configuration - Setup and configuration options
• Advanced Usage - Advanced features and workflows
• Contributing - Development setup and contribution guidelines
• Performance - Performance metrics and optimization tips

🔒 Privacy & Security

• 🏠 Local-first option: FastEmbed and SentenceTransformer run entirely offline (macOS only)
• 🔑 Secure storage: API keys stored locally, environment variables supported
• 📁 Respects .gitignore: Never indexes sensitive files or directories
• 🛡️ MCP security: Server runs locally with no external network access for search
• 🌐 Cloud embeddings: Voyage AI and other providers process only file metadata, not source code

🌐 Supported Languages

🤝 Support & Community

• 🐛 Issues: GitHub Issues
• 📧 Email: opensource@muvon.io
• 🏢 Company: Muvon Un Limited (Hong Kong)

⚖️ License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Built with ❤️ by the Muvon team in Hong Kong