Timofi Context Server

A secure, scalable repository-aware memory and code intelligence platform for AI assistants. The system consists of two main components: a Timofi API Server for centralized processing and secure token storage, and a lightweight MCP Client for local AI assistant integration.

Architecture

flowchart TD
  %% -------- CLIENT LAYER --------
  subgraph CLIENTS["🖥️ Client Applications"]
    CC[Claude Code]
    CHAT[ChatGPT]
    IDE[IDEs & Editors]
    CLI[CLI Tools]
  end

  %% -------- MCP CLIENT (LOCAL) --------
  subgraph MCP_CLIENT["📡 MCP Client (Local)"]
    MCP_SERVER[MCP Protocol Handler]
    API_CLIENT[Timofi API Client]
    CONFIG[Config Manager]
  end

  %% -------- TIMOFI API SERVER (CENTRALIZED) --------
  subgraph API_SERVER["🏗️ Timofi API Server (Centralized)"]
    AUTH_API[Authentication Service]
    TOKEN_VAULT[GitHub Token Vault]
    MEMORY_API[Memory Service API]
    CODE_API[Code Intelligence API]
    REPO_API[Repository Service API]
    WORKER[Background Workers]
  end

  %% -------- DATA LAYER --------
  subgraph DATA_LAYER["💾 Data Storage (Server-Side)"]
    POSTGRES[(PostgreSQL)]
    QDRANT[(Vector Database)]
    NEO4J[(Graph Database)]
    REDIS[(Cache Layer)]
  end

  %% -------- EXTERNAL SERVICES --------
  subgraph EXTERNAL["🌐 External Services"]
    GITHUB[GitHub API]
    EMBEDDING[Embedding Services]
  end

  %% Connections
  CLIENTS --> MCP_CLIENT
  MCP_CLIENT --> API_SERVER
  API_SERVER --> DATA_LAYER
  API_SERVER --> EXTERNAL

  %% Details
  MCP_SERVER -.->|"Single API Key"| API_CLIENT
  AUTH_API -.->|"Secure Storage"| TOKEN_VAULT
  TOKEN_VAULT -.->|"On Behalf Of Users"| GITHUB

Features

🔒 Secure Architecture

• Centralized Token Management: GitHub tokens stored securely on the API server
• Single API Key: Users only need one Timofi API key locally
• Zero Local Secrets: No sensitive credentials stored on user devices
• Enterprise Security: End-to-end encryption, audit logs, and access controls

🧠 Repository-Scoped Memory

• Intelligent Memory: Context-aware memory storage and retrieval per repository
• Vector Embeddings: Semantic search across conversational history and insights
• Multi-Repository Support: Seamless handling of organization-wide repositories
• Privacy by Design: Repository-scoped data isolation with secure access controls

🔍 Advanced Code Intelligence

• Real-time Code Analysis: Live symbol extraction and relationship mapping
• Semantic Code Search: Natural language queries for code discovery
• Background Indexing: Automated repository processing with progress tracking
• Cross-Reference Analysis: Find related functions, tests, and documentation

🔗 Universal Integration

• MCP Protocol: Compatible with Claude Code, ChatGPT, and major IDEs
• API First: RESTful API for custom integrations and advanced use cases
• Lightweight Client: Minimal local footprint with powerful remote capabilities
• Developer Friendly: Simple setup with comprehensive documentation

Installation

Quick Start (Recommended)

1. Install MCP Client

   npm install -g @goldcode-io/timofi-context-server

2. Get Your API Key

   • Visit Timofi Console
   • Sign up with GitHub OAuth
   • Generate your Timofi API key
   • Authorize GitHub repositories you want to access

3. Configure Claude Desktop

   {
     "mcpServers": {
       "timofi": {
         "command": "timofi-context-server",
         "env": {
           "TIMOFI_API_KEY": "your-api-key-here"
         }
       }
     }
   }

That's it! No local secrets, no complex setup, no Docker containers to manage.

Self-Hosted Installation (Advanced)

For organizations requiring complete control over data and infrastructure:

Prerequisites

• Node.js 18+
• Docker and Docker Compose
• PostgreSQL, Qdrant, Neo4j, Redis access

API Server Setup

1. Clone and Install API Server

   git clone https://github.com/goldcode-io/timofi-api-server.git
   cd timofi-api-server
   npm install

2. Configure Environment

   cp .env.example .env
   # Configure database connections, encryption keys, etc.

3. Start Infrastructure

   docker-compose up -d  # PostgreSQL, Qdrant, Neo4j, Redis
   npm run migrate      # Run database migrations
   npm start           # Start API server

MCP Client Setup

1. Install Local MCP Client

   npm install -g @goldcode-io/timofi-context-server

2. Configure for Self-Hosted

   {
     "mcpServers": {
       "timofi": {
         "command": "timofi-context-server",
         "env": {
           "TIMOFI_API_URL": "http://localhost:3000",
           "TIMOFI_API_KEY": "your-self-hosted-key"
         }
       }
     }
   }

Configuration

MCP Client Configuration

The MCP client requires minimal configuration:

{
  "mcpServers": {
    "timofi": {
      "command": "timofi-context-server",
      "env": {
        "TIMOFI_API_KEY": "your-api-key-here",
        "TIMOFI_API_URL": "https://api.timofi.goldcode.io"  // Optional: defaults to hosted service
      }
    }
  }
}

API Server Configuration (Self-Hosted Only)

# Database Configuration
DATABASE_URL=postgresql://user:pass@localhost:5432/timofi
QDRANT_URL=http://localhost:6333
NEO4J_URL=bolt://localhost:7687
REDIS_URL=redis://localhost:6379

# Security Configuration
ENCRYPTION_KEY=your-32-byte-encryption-key
JWT_SECRET=your-jwt-secret
GITHUB_WEBHOOK_SECRET=your-webhook-secret

# External Services
OPENAI_API_KEY=your-openai-key  # For embeddings
GITHUB_APP_ID=your-github-app-id
GITHUB_APP_PRIVATE_KEY=your-github-app-private-key

# Server Configuration
PORT=3000
LOG_LEVEL=info
NODE_ENV=production

# Webhooks: public URL of this API (required for auto-created GitHub webhooks)
# GitHub will send push events here; use your real API host (e.g. https://api.yourdomain.com)
API_BASE_URL=https://your-api-host.com

Repository Access Setup

1. Via Web Console (Recommended)

   • Visit Timofi Console
   • Connect your GitHub account
   • Select repositories to authorize
   • Generate scoped access tokens

2. Via API (Advanced)

   curl -X POST https://api.timofi.goldcode.io/v1/auth/github/connect \
     -H "Authorization: Bearer YOUR_TIMOFI_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"github_token": "ghp_your_github_token"}'

Webhooks (push → re-index)

When a webhook is active for a repository, pushes to the default branch create a pending indexing task; the worker picks it up within ~30 seconds and runs a new index.

1. Auto-creation on connect
When you connect a repository (Dashboard or POST /api/v1/repositories/connect), the server tries to create a GitHub webhook. For that to work:

• Set API_BASE_URL (or NEXT_PUBLIC_API_URL) to the public URL of your API server (e.g. https://api.yourdomain.com). GitHub must be able to reach this URL; do not use localhost in production.
• The user connecting the repo must have a GitHub token stored (Dashboard → Settings → GitHub tokens).

2. Create webhook manually (if auto-creation failed or the repo was connected earlier without it)

• Dashboard: Repositories → select the repo → Manage webhook (webhook icon) → Create Webhook. The default URL is the current page origin + /api/v1/webhooks/github. If your API runs on a different host than the dashboard, enter the full API URL (e.g. https://api.yourdomain.com/api/v1/webhooks/github).
• API:
  POST /api/v1/repositories/:id/webhooks
  Body: { "webhookUrl": "https://your-api-host/api/v1/webhooks/github", "events": ["push", "repository", "delete"], "active": true }
  Requires authentication and a GitHub token for a user with access to the repo.

3. Check

• In GitHub: repo → Settings → Webhooks. You should see a webhook pointing to your API URL; “Recent Deliveries” shows push events.
• Only pushes to the default branch (e.g. main) trigger indexing.

4. 401 Invalid signature

• The webhook secret is not visible anywhere (stored in the app DB and in GitHub). If you get 401, the secret may not match (e.g. webhook was edited in GitHub with a new secret).
• Fix: Dashboard → Repositories → select repo → Manage webhook → Regenerate secret (updates both GitHub and the app).
• Or via API: POST /api/v1/repositories/:id/webhooks/regenerate with body { "webhookUrl": "https://your-api-host/api/v1/webhooks/github" } (requires auth and a GitHub token).

Usage

Command Line Interface

# Start MCP server for a specific repository
timofi-context --repository owner/repo-name

# Start with custom configuration
timofi-context --repository owner/repo-name --config /path/to/config.json

# Index a repository
timofi-context index --repository owner/repo-name

# Query memories
timofi-context query --repository owner/repo-name --query "authentication logic"

# List supported repositories
timofi-context list-repos

MCP Tools

The server provides the following MCP tools:

Memory Management

• store_memory: Store conversation context or code insights
• retrieve_memories: Get relevant memories for current context
• search_memories: Semantic search across stored memories

Code Retrieval

• search_code: Find relevant code snippets and symbols
• get_file_context: Retrieve file content with related symbols
• find_tests: Locate tests related to specific code
• get_dependencies: Analyze code dependencies and relationships

Repository Management

• index_repository: Index a repository for search and memory
• check_access: Verify user access to repository
• get_repo_info: Retrieve repository metadata and structure

Self-Hosted Services

Docker Compose Services

The included docker-compose.yml provides:

• Mem0: Memory management service
• Sourcegraph: Code intelligence and search
• Qdrant: Vector database for embeddings
• Redis: Caching layer for improved performance

Service Configuration

Mem0 Configuration

mem0:
  image: mem0ai/mem0:latest
  ports:
    - '8000:8000'
  environment:
    - VECTOR_STORE_URL=http://qdrant:6333
  volumes:
    - mem0_data:/app/data

Sourcegraph Configuration

sourcegraph:
  image: sourcegraph/server:latest
  ports:
    - '3080:7080'
  environment:
    - SRC_LOG_LEVEL=warn
  volumes:
    - sourcegraph_data:/var/opt/sourcegraph

API Reference

Authentication

All requests require a valid GitHub token that provides access to the target repository:

curl -H "Authorization: Bearer ghp_your_token" \
     -H "X-Repository: owner/repo-name" \
     http://localhost:3000/api/memories

Memory Endpoints

Store Memory

POST /api/memories
{
  "content": "User discussed authentication implementation",
  "context": {
    "file": "src/auth.js",
    "function": "validateToken",
    "conversation_id": "conv_123"
  },
  "repository": "owner/repo-name"
}

Retrieve Memories

GET /api/memories?query=authentication&repository=owner/repo-name&limit=10

Code Search Endpoints

Search Code

GET /api/code/search?q=authentication&repository=owner/repo-name&type=function

Get File Context

GET /api/code/context?file=src/auth.js&repository=owner/repo-name

Development

Project Structure

timofi-context-server/
├── src/
│   ├── server.ts           # MCP server implementation
│   ├── memory/             # Memory management
│   │   ├── mem0.ts
│   │   └── zep.ts
│   ├── code/               # Code retrieval
│   │   ├── sourcegraph.ts
│   │   └── llamaindex.ts
│   ├── auth/               # GitHub authentication
│   └── utils/              # Utilities
├── docker-compose.yml      # Self-hosted services
├── package.json
└── README.md

Scripts

# Development
npm run dev          # Start with hot reload
npm run build        # Build for production
npm run test         # Run tests
npm run lint         # Lint code

# Docker
npm run docker:up    # Start all services
npm run docker:down  # Stop all services
npm run docker:logs  # View service logs

# Utilities
npm run index-repo   # Index a repository
npm run clean-cache  # Clear all caches

Testing

# Unit tests
npm test

# Integration tests with services
npm run test:integration

# Test specific repository
npm run test -- --repository owner/repo-name

Security

Access Control

• Repository access verified via GitHub API before each request
• GitHub tokens validated and scoped appropriately
• Memory and code data isolated by repository

Data Privacy

• All data stored in self-hosted services
• No data sent to external services without explicit configuration
• Configurable data retention policies

Best Practices

• Use fine-grained GitHub tokens with minimal required permissions
• Regularly rotate API keys and tokens
• Monitor access logs for suspicious activity
• Keep self-hosted services updated

Troubleshooting

Common Issues

Service Connection Errors

# Check service status
docker-compose ps

# View service logs
docker-compose logs mem0
docker-compose logs sourcegraph

GitHub Authentication

# Test token validity
curl -H "Authorization: Bearer ghp_your_token" \
     https://api.github.com/user

# Check repository access
curl -H "Authorization: Bearer ghp_your_token" \
     https://api.github.com/repos/owner/repo-name

MCP Connection Issues

# Test MCP server
timofi-context --test-connection

# Debug mode
timofi-context --repository owner/repo-name --debug

Logs

Service logs are available at:

• MCP Server: ~/.timofi-context/logs/server.log
• Memory Service: docker-compose logs mem0
• Code Service: docker-compose logs sourcegraph

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Commit changes: git commit -m 'Add amazing feature'
4. Push to branch: git push origin feature/amazing-feature
5. Open a Pull Request

License

MIT License - see LICENSE file for details.

Support

• 📧 Email: [email protected]
• 🐛 Issues: GitHub Issues
• 📖 Documentation: Wiki

Secret Scanning with Gitleaks

This repository uses Gitleaks to detect hardcoded secrets and prevent sensitive data from being committed.
To guarantee consistent behavior between local development and CI, all scans are performed as filesystem scans (not Git history scans).

There are two scanning modes, depending on when and how they are executed.

1. Github Actions Scans (Pull Requests and Manual)

Gitleaks is executed on:

• Every Pull Request
• Manually: via GitHub Actions → Run workflow

What is scanned automatically ?

• On PRs: The diff between the current state of the repository filesystem compared to your changes
• Manually: All filesystem on (trunk/master/main/default)
• Git history and other branches are not scanned

This is the primary protection mechanism for day-to-day development.

2. Running a full scan locally

Developers can run a full scan locally at any time:

$ make gitleaks

This executes a full filesystem scan using the project’s .gitleaks.local.toml configuration.
Make sure you have Gitleaks installed locally (GitLeaks Repository).

About .gitleaks.toml file

The .gitleaks.local.toml and .gitleaks.ci.toml files defines allowlists and rules to reduce noise, such as:

• test files and fixtures
• examples and documentation
• .env files and templates

This keeps results actionable and avoids reporting known non-issues.