Frequently Asked Questions (FAQ)¶

Common questions and answers about the Code Graph Knowledge System.

Table of Contents¶

General Questions
Deployment and Installation
Features and Capabilities
LLM Providers and Models
Memory Store
Performance and Scaling
Cost and Resources
Security and Privacy
Integration and APIs
Troubleshooting

General Questions¶

What is Code Graph Knowledge System?¶

Code Graph Knowledge System is an intelligent knowledge management system designed specifically for software development. It combines:

Neo4j Graph Database: Stores relationships between code, documents, and memories
Vector Search: Semantic search across your codebase and documentation
LLM Integration: AI-powered code analysis and question answering
Memory Store: Long-term knowledge persistence for AI agents
MCP Protocol: Integration with AI assistants like Claude

Use Cases: - Intelligent code navigation and search - Automated documentation generation - AI-assisted development with persistent memory - Code relationship mapping - Database schema analysis

What's new in version 0.7?¶

Version 0.7 introduces Automatic Memory Extraction:

Extract memories from AI conversations
Analyze git commits for decisions and experiences
Mine code comments (TODO, FIXME, NOTE markers)
Suggest important memories from Q&A sessions
Batch extract from entire repositories

See the Changelog for complete details.

Is this project open source?¶

Yes! Code Graph Knowledge System is open source under [appropriate license]. You can:

View source code on GitHub
Contribute improvements
Fork for custom needs
Use commercially (check license terms)

Who maintains this project?¶

The project is maintained by a team of contributors led by @royisme. See Contributing Guide to join the community.

Deployment and Installation¶

What are the different deployment modes?¶

Three Docker deployment modes are available:

1. Minimal Mode (Code Graph only) - Size: ~800MB - Features: Code graph, vector search, basic RAG - Best for: Lightweight code analysis, resource-constrained environments - RAM: 2-4GB - Pull: docker pull royisme/codebase-rag:minimal

2. Standard Mode (Code Graph + Memory) - Size: ~1.2GB - Features: Everything in Minimal + Memory Store for AI agents - Best for: AI-assisted development with memory - RAM: 4-8GB - Pull: docker pull royisme/codebase-rag:standard

3. Full Mode (All Features) - Size: ~1.5GB - Features: Everything + Web UI, monitoring, Prometheus metrics - Best for: Production deployment, team environments - RAM: 8-16GB - Pull: docker pull royisme/codebase-rag:full

Which deployment mode should I choose?¶

Choose Minimal if: - You only need code analysis - Running on limited resources (Raspberry Pi, small VPS) - Don't need memory features - Want smallest footprint

Choose Standard if: - Using with AI assistants (Claude Desktop, VSCode) - Need memory persistence - Want balanced features and size - Typical development environment

Choose Full if: - Need web UI for teams - Want monitoring and metrics - Production deployment - Multiple users - Have resources available

Can I switch between deployment modes later?¶

Yes! Data is stored in Neo4j volumes, which are shared across modes:

# Start with minimal
docker-compose -f docker/docker-compose.minimal.yml up -d

# Later, switch to standard (data preserved)
docker-compose -f docker/docker-compose.minimal.yml down
docker-compose -f docker/docker-compose.standard.yml up -d

Note: Switching modes doesn't delete your data, but some features may not be available in smaller modes.

What are the minimum system requirements?¶

Development (Minimal Mode): - CPU: 2 cores - RAM: 4GB - Disk: 10GB - OS: Linux, macOS, Windows with WSL2

Development (Standard/Full Mode): - CPU: 4 cores - RAM: 8GB - Disk: 20GB - OS: Linux, macOS, Windows with WSL2

Production: - CPU: 8 cores - RAM: 16GB (32GB with Ollama) - Disk: 50GB+ (depends on data size) - OS: Linux (Ubuntu 22.04+ recommended)

Can I run this without Docker?¶

Yes, you can run natively:

# Install Python 3.13+
python3.13 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -e .

# Install Neo4j separately
# Follow: https://neo4j.com/docs/operations-manual/current/installation/

# Configure and run
python -m codebase_rag

Note: Docker is recommended for easier setup and isolation.

How do I upgrade to a new version?¶

# Pull new images
docker pull royisme/codebase-rag:latest

# Or specific version
docker pull royisme/codebase-rag:0.7.0-full

# Restart with new version
docker-compose down
docker-compose up -d

# Check version
curl http://localhost:8000/api/v1/health | jq .version

Your data is preserved in volumes across upgrades.

Features and Capabilities¶

What programming languages are supported?¶

Fully Supported (with import/relationship analysis): - Python (.py) - TypeScript/JavaScript (.ts, .tsx, .js, .jsx) - Java (.java) - PHP (.php) - Go (.go)

Document Processing (any file type): - Markdown (.md) - Text files (.txt) - Code files (analyzed as text if not in supported list) - SQL files (.sql) with schema parsing

Future Support (planned): - Rust, C++, C#, Ruby, Kotlin

What's the difference between Memory Store and Knowledge Graph?¶

Knowledge Graph: - Purpose: Store documents, code, and their relationships - Content: Code files, documentation, SQL schemas - Search: Vector similarity + graph traversal - Updates: Add/remove documents - Use Case: "Show me all files that import module X"

Memory Store: - Purpose: Long-term knowledge for AI agents - Content: Decisions, preferences, experiences, conventions - Search: Semantic search + importance filtering - Updates: Add, update, supersede memories - Use Case: "Remember we decided to use PostgreSQL because..."

Analogy: - Knowledge Graph = Your codebase and documentation - Memory Store = Your project's institutional memory

Can I use this with GitHub Copilot or other AI assistants?¶

GitHub Copilot: No direct integration (closed API)

Claude Desktop: ✅ Yes, via MCP protocol

// claude_desktop_config.json
{
  "mcpServers": {
    "code-graph": {
      "command": "python",
      "args": ["/path/to/start_mcp.py"]
    }
  }
}

VS Code with MCP: ✅ Yes (requires MCP extension)

Any Tool with HTTP API: ✅ Yes, use REST API

curl -X POST http://localhost:8000/api/v1/knowledge/query \
  -d '{"query": "how does authentication work?"}'

Can I analyze private repositories?¶

Yes! All processing is local:

Clone your private repo to your machine

Ingest with MCP:

Use ingest_directory tool with your repo path

Or via API:

curl -X POST http://localhost:8000/api/v1/ingest/directory \
  -d '{"path": "/path/to/private/repo"}'

Privacy: No code leaves your machine (unless you use cloud LLM providers).

Does it work with monorepos?¶

Yes, monorepos are fully supported:

# Ingest entire monorepo
ingest_directory(/path/to/monorepo)

# Or specific workspaces
ingest_directory(/path/to/monorepo/packages/frontend)
ingest_directory(/path/to/monorepo/packages/backend)

# Query across entire monorepo
query_knowledge("How does the API communicate with frontend?")

Tip: Use project-specific tags to organize large monorepos.

Can I customize the code analysis?¶

Yes, several customization options:

1. File Patterns:

# Include/exclude specific patterns
include_globs = ["**/*.py", "**/*.ts"]
exclude_globs = ["**/test_*.py", "**/node_modules/**"]

2. Chunk Size:

CHUNK_SIZE=512
CHUNK_OVERLAP=50

3. Embedding Model:

EMBEDDING_PROVIDER=ollama
OLLAMA_EMBEDDING_MODEL=nomic-embed-text  # Fast
# or
OLLAMA_EMBEDDING_MODEL=mxbai-embed-large  # More accurate

4. Custom Parsers: Extend services/pipeline/transformers.py to add new language support.

LLM Providers and Models¶

Which LLM provider should I use?¶

Ollama (Recommended for Development): - ✅ Free - ✅ No API keys needed - ✅ Unlimited requests - ✅ Privacy (100% local) - ❌ Requires powerful hardware - ❌ Slower than cloud APIs

OpenAI (Recommended for Production): - ✅ Fast and accurate - ✅ No local resources needed - ✅ Best quality results - ❌ Costs money per request - ❌ Requires API key - ❌ Data sent to OpenAI

Google Gemini: - ✅ Good free tier - ✅ Fast response times - ✅ Large context window - ❌ Requires API key - ❌ Data sent to Google

OpenRouter: - ✅ Access to many models - ✅ Pay-as-you-go pricing - ✅ Model flexibility - ❌ Requires API key - ❌ Variable quality

Can I use multiple LLM providers?¶

Currently, one provider at a time is supported:

# Choose one
LLM_PROVIDER=ollama  # or openai, gemini, openrouter

Workaround: Run multiple instances with different configurations on different ports.

Future: Multi-provider support is planned for v0.8.

For LLM (text generation):

llama3.2:3b - Fast, good for development (4GB RAM)
mistral:7b - Balanced quality and speed (8GB RAM)
llama3.1:8b - High quality (8GB RAM)
codellama:13b - Best for code (16GB RAM)

For Embeddings:

nomic-embed-text - Fast, good quality (recommended)
mxbai-embed-large - Better quality, slower
all-minilm - Smallest, fastest

Install:

ollama pull llama3.2:3b
ollama pull nomic-embed-text

How do I switch LLM providers?¶

Simply update .env and restart:

# From Ollama to OpenAI
LLM_PROVIDER=openai
OPENAI_API_KEY=sk-your-key
OPENAI_MODEL=gpt-4

EMBEDDING_PROVIDER=openai
OPENAI_EMBEDDING_MODEL=text-embedding-3-small

# Restart
docker-compose restart api
# or
pkill -f start.py && python -m codebase_rag

No data migration needed - embeddings are recalculated automatically.

Memory Store¶

What is the Memory Store for?¶

Memory Store provides long-term project knowledge for AI agents:

Without Memory:

Session 1: "Use PostgreSQL" → AI learns
Session 2: AI forgot, suggests MySQL again ❌

With Memory:

Session 1: "Use PostgreSQL" → Saved to memory
Session 2: AI remembers: "You decided on PostgreSQL" ✅

Types of Memories: - Decisions: "Chose JWT for auth" - Preferences: "Use raw SQL over ORM" - Experiences: "Redis fails with localhost in Docker" - Conventions: "API endpoints use kebab-case" - Plans: "Migrate to PostgreSQL 16"

How is Memory Store different from conversation history?¶

Conversation History (Short-term): - Temporary (session only) - All messages (including noise) - Lost when session ends - Not searchable - No importance ranking

Memory Store (Long-term): - Permanent (persisted in Neo4j) - Curated knowledge only - Survives restarts/sessions - Searchable by topic/tag - Importance-ranked

Think of Memory Store as your project's institutional memory.

Do I need Memory Store?¶

You need Memory Store if: - Using AI assistants (Claude, Copilot, etc.) - Working on long-term projects - Multiple people/agents on same project - Want AI to remember past decisions - Need consistent AI behavior

You don't need Memory Store if: - Just analyzing code (use Minimal mode) - One-off queries - Don't use AI assistants - Limited to Knowledge Graph features

How do I add memories manually?¶

Via MCP (in Claude Desktop):

Add a memory:
- Type: decision
- Title: Use PostgreSQL
- Content: Selected PostgreSQL for main database
- Reason: Need advanced JSON support
- Importance: 0.9

Via HTTP API:

curl -X POST http://localhost:8000/api/v1/memory/add \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "myapp",
    "memory_type": "decision",
    "title": "Use PostgreSQL",
    "content": "Selected PostgreSQL for main database",
    "reason": "Need advanced JSON support",
    "importance": 0.9,
    "tags": ["database", "architecture"]
  }'

Can memories be automatically extracted?¶

Yes! Version 0.7 added automatic extraction:

1. From Conversations:

# Extract from AI chat history
extract_from_conversation(project_id, conversation_history)

2. From Git Commits:

# Analyze git commits
extract_from_git_commit(project_id, commit_sha, commit_message)

3. From Code Comments:

# Mine TODO, FIXME, NOTE markers
extract_from_code_comments(project_id, file_path)

4. From Repository:

# Full repo analysis
batch_extract_from_repository(project_id, repo_path)

See Memory Extraction Guide for details.

How do I search memories?¶

MCP Tool:

search_memories(
  project_id="myapp",
  query="database decisions",
  memory_type="decision",
  min_importance=0.7
)

HTTP API:

curl -X POST http://localhost:8000/api/v1/memory/search \
  -d '{
    "project_id": "myapp",
    "query": "database",
    "memory_type": "decision",
    "min_importance": 0.7
  }'

Results ranked by: - Relevance to query - Importance score - Recency

Performance and Scaling¶

How fast is document processing?¶

Speed depends on: - File size - LLM provider - Hardware specs - Chunk size

Typical Performance:

File Size	Ollama (Local)	OpenAI (Cloud)
10KB	2-5 seconds	1-2 seconds
100KB	20-30 seconds	5-10 seconds
1MB	3-5 minutes	30-60 seconds

Tips for faster processing: - Use smaller embedding models - Reduce chunk size - Use OpenAI (fastest) - Process in background/batch

Can it handle large codebases?¶

Yes! Tested with:

Large PHP Project: 25,000+ files, 5GB code
Oracle Database Schema: 356 tables, 4,511 columns
Monorepo: Multiple packages, 100,000+ LOC

Performance Tips: 1. Use batch ingestion: Process directories in background 2. Filter files: Use .gitignore patterns to skip unnecessary files 3. Increase resources: Allocate more RAM to Neo4j 4. Add indexes: Create Neo4j indexes on frequently queried fields

What's the maximum document size?¶

Recommended Limits: - API upload: 50KB (configurable) - Directory processing: No limit (batch mode) - Single file processing: 1MB recommended

For Large Files:

# Use MCP client with automatic temp file handling
# Or process directory in batch mode
ingest_directory(/path/to/large/files)

How do I improve query performance?¶

1. Add Neo4j Indexes:

CREATE INDEX document_content IF NOT EXISTS
FOR (d:Document) ON (d.content);

CREATE INDEX memory_tags IF NOT EXISTS
FOR (m:Memory) ON (m.tags);

2. Optimize Chunk Size:

CHUNK_SIZE=512  # Smaller = faster search

3. Use Faster Embeddings:

OLLAMA_EMBEDDING_MODEL=nomic-embed-text  # Fast
OPENAI_EMBEDDING_MODEL=text-embedding-3-small  # Fastest

4. Increase Neo4j Memory:

environment:
  - NEO4J_dbms_memory_heap_max__size=4G

5. Limit Results:

# Request fewer results
query_knowledge("...", limit=10)  # Instead of 100

Cost and Resources¶

How much does it cost to run?¶

Infrastructure Costs:

Local Deployment (Ollama): - Hardware: One-time cost ($1000-$3000 for good GPU) - Electricity: ~$20-50/month (GPU running 24/7) - Internet: Standard connection sufficient - Total: $0/month after initial investment

Cloud Deployment (Minimal, OpenAI): - VPS: $20-40/month (4GB RAM, 2 CPU) - Neo4j Cloud: $65/month (Aura free tier available) - OpenAI API: Variable (see below) - Total: $20-105/month + API costs

Cloud Deployment (Full, OpenAI): - VPS: $80-160/month (16GB RAM, 8 CPU) - Neo4j Cloud: $65/month - OpenAI API: Variable - Total: $145-225/month + API costs

LLM API Costs:

OpenAI (GPT-4): - Embeddings: $0.00002/1K tokens (~$0.02 per 1MB document) - Queries: $0.03/1K tokens (~$0.30 per complex query) - Estimate: $10-50/month for moderate use

OpenAI (GPT-3.5): - 10x cheaper than GPT-4 - Estimate: $1-5/month for moderate use

Google Gemini: - Free tier: 15 RPM, 1M tokens/day - Paid: $0.35/1M input tokens - Estimate: Free to $5/month

OpenRouter: - Variable per model - Usually cheaper than direct APIs - Estimate: $5-20/month

Can I use the free tiers of LLM providers?¶

Ollama: ✅ Completely free, no limits

Google Gemini: ✅ Generous free tier (15 RPM, 1M tokens/day)

OpenAI: ❌ No free tier, but trial credits available

OpenRouter: ⚠️ Small free tier, then pay-as-you-go

Recommendation: Start with Ollama or Gemini free tier.

What are the hosting costs?¶

Self-Hosted (Recommended for Development): - Your own machine: $0/month - Electric cost: ~$10-30/month (if running 24/7)

VPS Hosting: - DigitalOcean Droplet: $24/month (4GB RAM) - Linode: $24/month (4GB RAM) - AWS EC2: $30-50/month (t3.medium) - Google Cloud: $25-45/month (e2-standard-2)

Platform-as-a-Service: - Railway.app: ~$20/month (with free trial) - Render.com: ~$25/month - Heroku: Not recommended (disk limitations)

Managed Neo4j: - Neo4j Aura Free: $0/month (limited) - Neo4j Aura Pro: $65/month (production)

How can I reduce costs?¶

1. Use Ollama Locally: - Zero API costs - One-time hardware investment

2. Use Smaller Models:

OLLAMA_MODEL=llama3.2:3b  # Instead of 13b
OPENAI_MODEL=gpt-3.5-turbo  # Instead of gpt-4

3. Batch Operations: - Process multiple files at once - Reduce API calls with caching

4. Optimize Chunk Size:

CHUNK_SIZE=1024  # Larger chunks = fewer embeddings = lower cost

5. Use Minimal Mode: - Smaller Docker image - Lower resource requirements

6. Self-Host Neo4j: - Avoid managed database costs - Use Docker Neo4j

Security and Privacy¶

Is my code sent to external services?¶

Depends on LLM provider:

Ollama (Local): - ✅ 100% local processing - ✅ No data leaves your machine - ✅ Complete privacy

OpenAI/Gemini/OpenRouter: - ⚠️ Code sent to provider for processing - ⚠️ Subject to provider's terms of service - ⚠️ Check provider's data retention policies

Recommendation: Use Ollama for sensitive/proprietary code.

How is data stored?¶

Neo4j Database: - Stored in Docker volumes (encrypted at rest if configured) - Local machine or private VPS - Not shared with external services

File System: - Temporary files during processing (deleted after) - Logs (can contain query text, check before sharing)

No external storage unless you explicitly configure cloud backups.

Can I use this in an enterprise environment?¶

Yes, with considerations:

✅ Suitable for Enterprise: - Self-hosted (complete control) - Local Ollama (no data leakage) - Isolated networks - Compliance with data residency requirements

⚠️ Considerations: - Review LLM provider terms (if using cloud APIs) - Implement access controls - Secure Neo4j with authentication - Use HTTPS for API endpoints - Regular security updates

Enterprise Checklist: - [ ] Use Ollama or enterprise LLM provider - [ ] Enable Neo4j authentication - [ ] Configure firewall rules - [ ] Set up SSL/TLS - [ ] Implement audit logging - [ ] Regular backups - [ ] Security scanning

Are there any security best practices?¶

1. Secure Neo4j:

NEO4J_AUTH=neo4j/strong-password-here
NEO4J_dbms_security_auth__enabled=true

2. Use Environment Variables:

# Never commit .env to git
echo ".env" >> .gitignore

3. API Authentication (not implemented yet, planned for v0.8):

# Coming soon: JWT authentication for API

4. Network Isolation:

# docker-compose.yml
services:
  api:
    networks:
      - internal  # Not exposed to internet

5. Regular Updates:

# Pull latest security patches
docker pull royisme/codebase-rag:latest

6. Audit Logging:

LOG_LEVEL=INFO  # Log all API access

Integration and APIs¶

What APIs are available?¶

REST API (HTTP): - /api/v1/knowledge/query - Query knowledge base - /api/v1/knowledge/search - Vector search - /api/v1/documents/* - Document management - /api/v1/memory/* - Memory operations - /api/v1/sql/* - SQL schema analysis

MCP Protocol (AI Assistants): - 30 tools across 6 categories - Knowledge, Code Graph, Memory, Tasks, System - Compatible with Claude Desktop, VSCode

Real-time APIs: - Server-Sent Events (SSE) for task monitoring - WebSocket (via NiceGUI monitoring UI)

See REST API Documentation for details.

Can I integrate this with my CI/CD pipeline?¶

Yes! Several integration options:

1. Pre-commit Hook:

# .git/hooks/pre-commit
#!/bin/bash
# Extract memories from commit
curl -X POST http://localhost:8000/api/v1/memory/extract/commit \
  -d "{\"commit_sha\": \"$(git rev-parse HEAD)\"}"

2. GitHub Actions:

# .github/workflows/code-analysis.yml
name: Code Analysis
on: [push]
jobs:
  analyze:
    runs-on: ubuntu-latest
    steps:
      - name: Analyze code
        run: |
          curl -X POST http://code-graph-server/api/v1/ingest/directory \
            -d '{"path": "${{ github.workspace }}"}'

3. Build Script:

# In your build.sh
python -c "
from src.codebase_rag.services.memory import MemoryStore
# Auto-extract memories after build
"

How do I backup my data?¶

Neo4j Backup:

# Export Neo4j data
docker exec code-graph-neo4j neo4j-admin dump \
  --database=neo4j --to=/backups/neo4j-backup.dump

# Copy from container
docker cp code-graph-neo4j:/backups/neo4j-backup.dump ./backups/

# Or backup volume
docker run --rm \
  -v code-graph_neo4j_data:/data \
  -v $(pwd)/backups:/backup \
  alpine tar czf /backup/neo4j-data.tar.gz /data

Restore Backup:

# Stop Neo4j
docker-compose stop neo4j

# Restore
docker cp ./backups/neo4j-backup.dump code-graph-neo4j:/backups/
docker exec code-graph-neo4j neo4j-admin load \
  --from=/backups/neo4j-backup.dump --database=neo4j --force

# Restart
docker-compose start neo4j

Can I export my data?¶

Export Memories as JSON:

curl http://localhost:8000/api/v1/memory/project/myapp/export > memories.json

Export Knowledge Graph:

// In Neo4j Browser
CALL apoc.export.json.all("/export/graph.json", {})

Export to CSV:

MATCH (m:Memory)
RETURN m.title, m.content, m.importance
// Click "Export" in Neo4j Browser

Troubleshooting¶

Where can I find logs?¶

Docker Logs:

# Application logs
docker logs code-graph-api

# Neo4j logs
docker logs code-graph-neo4j

# Follow logs
docker logs -f code-graph-api

Local Logs:

# Application logs
tail -f logs/application.log

# Debug logs
tail -f logs/debug.log

The application won't start. What should I check?¶

Quick Checklist:

Neo4j Running:
```
docker ps | grep neo4j
```
Environment Variables:
```
cat .env | grep NEO4J
```
Dependencies Installed:
```
pip list | grep llama-index
```
Port Available:
```
lsof -i :8000
```

Logs for Errors:

docker logs code-graph-api | grep ERROR

See Troubleshooting Guide for detailed solutions.

Where can I get help?¶

Documentation: - Main docs: https://code-graph.vantagecraft.dev - This FAQ - Troubleshooting guide - API documentation

Community: - GitHub Issues: Bug reports and feature requests - GitHub Discussions: Questions and community help - Discord/Slack: Real-time chat (if available)

Support: - Email maintainers for critical issues - Check existing issues before posting - Include logs and error messages

How do I report a bug?¶

Good Bug Report:

Search existing issues first
Use issue template if available
Include:
System info (OS, Python version, Docker version)
Steps to reproduce
Expected vs actual behavior
Error messages and logs
Configuration (sanitized .env)
Create minimal reproduction if possible

See Contributing Guide for details.

Is there a community forum or chat?¶

Check the GitHub Discussions for: - Questions and answers - Feature discussions - Show and tell - Community support

Coming soon: Discord/Slack community (watch for announcements).

Still Have Questions?¶

Can't find your answer here?

Found an error in this FAQ? Please open an issue or submit a PR!