Quick Start - Code Graph Knowledge System

Quick Start Guide¶

Get Code Graph Knowledge System up and running in 5 minutes!

🎯 Choose Your Deployment Mode¶

Code Graph Knowledge System offers three deployment modes based on which features you need:

Mode	Description	Ports	LLM Required	Use Case
Minimal	Code Graph only	7474, 7687, 8000, 8080	❌ No	Static code analysis, repository exploration
Standard	Code Graph + Memory Store	7474, 7687, 8000, 8080	Embedding only	Project knowledge tracking, AI agent memory
Full	All Features + Knowledge RAG	7474, 7687, 8000, 8080	LLM + Embedding	Complete intelligent knowledge management

What's Running?

All modes start two servers:

Port 8000: MCP SSE Service (for AI assistants)
Port 8080: Web UI + REST API (for humans & programs)

See Architecture Overview to understand how these work together.

🚀 Choose Your Path¶

Minimal (Recommended)StandardFull

Code Graph only - No LLM required

Perfect for getting started and trying out the system.

# Clone repository
git clone https://github.com/royisme/codebase-rag.git
cd codebase-rag

# Initialize environment
make init-env
# Choose: minimal

# Start services
make docker-minimal

Code Graph + Memory - Embedding required

git clone https://github.com/royisme/codebase-rag.git
cd codebase-rag

# Initialize environment
make init-env
# Choose: standard

# Edit .env and add your embedding provider
# e.g., EMBEDDING_PROVIDER=ollama

make docker-standard

All Features - LLM + Embedding required

git clone https://github.com/royisme/codebase-rag.git
cd codebase-rag

# Initialize environment
make init-env
# Choose: full

# Edit .env and add your LLM provider
# e.g., LLM_PROVIDER=ollama

make docker-full-with-ollama

✅ Verify Installation¶

After starting the services, verify everything is running:

# Check service health
make health-check

# View logs
make docker-logs

You should see:

✅ Neo4j running at http://localhost:7474
✅ API running at http://localhost:8000
✅ API docs at http://localhost:8000/docs

📡 Understanding the Interfaces¶

After starting the services, you have three ways to interact with the system:

1. REST API (Port 8080)¶

For: Programmatic access, scripts, CI/CD integration

# Health check
curl http://localhost:8080/api/v1/health

# Query knowledge
curl -X POST http://localhost:8080/api/v1/knowledge/query \
  -H "Content-Type: application/json" \
  -d '{"question": "How does authentication work?"}'

Use cases: - Automation scripts - CI/CD pipelines - Custom applications - Testing and monitoring

Full REST API Documentation

2. Web UI (Port 8080)¶

For: Human users, visual monitoring

Open in browser: http://localhost:8080

Features: - 📊 Task monitoring dashboard - 📁 File and directory upload - 📈 System health and statistics - ⚙️ Configuration management

3. MCP Protocol (Port 8000)¶

For: AI assistants (Claude Desktop, Cursor, etc.)

Configure your AI tool to connect via MCP. The system provides 25+ tools for code intelligence.

MCP Integration Guide

🚀 First Steps¶

1. Access Neo4j Browser¶

Open http://localhost:7474 in your browser
Connect with:
URL: bolt://localhost:7687
User: neo4j
Password: (from your .env file)

2. Test the API¶

# Check health
curl http://localhost:8000/api/v1/health

# Get statistics
curl http://localhost:8000/api/v1/statistics

3. Ingest Your First Repository¶

Option A: Using REST API¶

curl -X POST http://localhost:8000/api/v1/code-graph/ingest \
  -H "Content-Type: application/json" \
  -d '{
    "local_path": "/path/to/your/repo",
    "repo_url": "https://github.com/user/repo",
    "mode": "incremental"
  }'

Option B: Using MCP (Claude Desktop)¶

Configure Claude Desktop to connect to MCP server
Use the tool:

code_graph_ingest_repo({
  "local_path": "/path/to/your/repo",
  "mode": "incremental"
})

4. Search Your Code¶

# Find files related to "authentication"
curl -X POST http://localhost:8000/api/v1/code-graph/related \
  -H "Content-Type: application/json" \
  -d '{
    "query": "authentication",
    "repo_id": "your-repo-name",
    "limit": 10
  }'

5. Analyze Impact¶

# See what depends on a specific file
curl -X POST http://localhost:8000/api/v1/code-graph/impact \
  -H "Content-Type: application/json" \
  -d '{
    "repo_id": "your-repo-name",
    "file_path": "src/auth/login.py",
    "depth": 2
  }'

🎓 Next Steps¶

Learn Code Graph Features¶

Repository Ingestion - Index your codebase
Search & Discovery - Find related files
Impact Analysis - Understand dependencies
Context Packing - Generate AI context

Explore Advanced Features¶

Available in Standard/Full modes only

Memory Store - Project knowledge management
Knowledge RAG - Document Q&A
Auto Extraction - Automated memory curation

Integrate with Your Workflow¶

Claude Desktop Setup - Use with Claude
VS Code Integration - Editor integration
API Reference - Complete tool documentation

🔧 Common Issues¶

Port Already in Use¶

If ports 7474, 7687, or 8000 are already in use:

# Edit .env file
NEO4J_HTTP_PORT=17474
NEO4J_BOLT_PORT=17687
APP_PORT=18000

# Restart
make docker-stop
make docker-minimal

Neo4j Connection Failed¶

Check Neo4j is healthy:

docker ps | grep neo4j
docker logs codebase-rag-neo4j

Verify credentials in .env match
Wait for Neo4j to fully start (can take 30s)

Ollama Not Found (Full mode)¶

If using local Ollama on your host:

# In .env file
OLLAMA_BASE_URL=http://host.docker.internal:11434

If Ollama is not installed:

# Install Ollama
curl -fsSL https://ollama.com/install.sh | sh

# Pull a model
ollama pull llama3.2
ollama pull nomic-embed-text

📚 Documentation Links¶

Deployment Overview - Choose the right mode
Configuration Guide - Detailed configuration options
Docker Guide - Docker-specific information
Troubleshooting - Common problems and solutions

💡 Tips & Tricks¶

Use Incremental Mode¶

Always use "mode": "incremental" for repository ingestion. It's 60x faster than full mode.

Start Small¶

Test with a small repository first (< 1000 files) before ingesting large monorepos.

Monitor Resources¶

# Watch Docker resource usage
docker stats

# Check Neo4j memory
docker logs codebase-rag-neo4j | grep memory

Batch Operations¶

For multiple repositories, use the batch ingestion API or write a simple script:

for repo in repo1 repo2 repo3; do
  curl -X POST http://localhost:8000/api/v1/code-graph/ingest \
    -H "Content-Type: application/json" \
    -d "{\"local_path\": \"/repos/$repo\", \"mode\": \"incremental\"}"
done

🎉 You're Ready!¶

Congratulations! You now have Code Graph Knowledge System running.

Try exploring your codebase with the MCP tools or REST API. Check out the User Guide for detailed feature documentation.

Need help? Join our GitHub Discussions or report an issue.