I Built ContextForge with Gemma 4: A Project Memory Generator for Developers and AI Coding Agents

ContextForge is a developer tool that uses Google's Gemma 4 model (via the Gemini API) to automatically scan a codebase and generate AI-ready project documentation, including files like README.md, SETUP.md, ARCHITECTURE.md, and a specialized AGENT.md for preserving context across AI coding sessions. The tool accepts a ZIP upload or built-in sample project, processes files through a FastAPI backend and React frontend, and produces structured documentation designed to help both human developers and AI coding agents understand a project without needing to rediscover it from scratch. The project is available on GitHub and can be run locally using Docker Compose, with a mock mode available for testing without a Gemini API key.

This is a submission for the Gemma 4 Challenge: Build with Gemma 4. What I Built ContextForge is a developer tool that scans a codebase and generates practical, AI-ready project documentation using Gemma 4 through the Gemini API. The goal is simple: when a developer or AI coding agent opens a project, they should not have to rediscover the whole repository from scratch. ContextForge generates README.md , SETUP.md , ARCHITECTURE.md , and especially AGENT.md , a durable handoff file designed for future AI coding sessions. The problem: AI coding agents lose context AI coding agents are useful, but their context is fragile. When a chat is cleared, a session expires, or a different agent starts working on the same repository, a lot of hard-won project understanding disappears: - what framework the app uses - which files matter most - how to run the project locally - what generated folders should be ignored - what assumptions are still uncertain - what safety rules an agent should follow before editing Traditional README files help humans, but they are not always enough for AI agents. Agents need a project map, editing constraints, validation steps, and warnings about risky areas. That is why ContextForge focuses on AGENT.md . What ContextForge does ContextForge takes a ZIP upload or a built-in sample project and generates documentation from the actual files in the codebase. The MVP can: - upload a ZIP file - load a built-in Django sample project - safely extract and scan files - ignore folders like .git , node modules , .venv , dist , build , .next , and coverage - detect the tech stack - build a structured prompt for Gemma 4 - generate: README.md AGENT.md SETUP.md ARCHITECTURE.md - display generated docs in tabs - copy each generated document - download all generated docs as a ZIP The output is meant to be practical rather than marketing-heavy. If ContextForge is unsure about something, the prompt asks the model to mark that uncertainty instead of inventing details. Demo The project is available on GitHub and can be run locally with Docker Compose: git clone https://github.com/bryko254/contextforge.git cd contextforge cp backend/.env.example backend/.env cp frontend/.env.example frontend/.env docker compose up --build Then open http://localhost:5173 . The judge-friendly demo flow is: - Open the ContextForge frontend. - Click Try sample project . - The backend scans the built-in Django task API sample. - ContextForge detects Python, Django, PostgreSQL, Docker, and pip. - The app asks Gemma 4 to generate docs. - The UI displays: README.md AGENT.md SETUP.md ARCHITECTURE.md - Open AGENT.md and show the AI-agent-focused project handoff. - Copy a generated document. - Download all docs as a ZIP. - Optionally upload a small ZIP project and run the same flow. The app also supports mock mode, so the UI can be tested without a Gemini API key. For judging the real AI flow, run with USE MOCK AI=false and provide GEMINI API KEY . Code Repository: https://github.com/bryko254/contextforge https://github.com/bryko254/contextforge The project is structured as a small full-stack app: - backend/ : FastAPI API, ZIP handling, scanning, stack detection, prompt construction, and Gemma API client. - frontend/ : React/Vite UI for uploads, sample generation, document tabs, copy buttons, and ZIP export. - sample-projects/django-api-demo/ : built-in Django REST Framework sample used for the default demo. - docs/dev-to-submission-draft.md : this DEV submission draft. How I Used Gemma 4 ContextForge uses gemma-4-26b-a4b-it through the Gemini API. I chose this model because ContextForge is not trying to write arbitrary code; it is doing structured documentation synthesis over selected codebase context. The model needs to: - read selected project files - follow a strict JSON response schema - avoid inventing dependencies - summarize architecture clearly - generate instructions for both humans and AI coding agents Gemma 4 works well for this kind of grounded, instruction-following task. The hosted demo uses the Gemini API so judges can try the app without running a local model. The architecture is intentionally isolated behind a gemma client.py service, so the project can later support local Gemma 4 inference for private repositories. The Gemma 4 call is at the heart of the pipeline: - The backend scans selected files from the uploaded or sample project. - The scanner filters out large, generated, binary, and irrelevant files. - Stack detection summarizes languages, frameworks, databases, infrastructure, and package managers. - ContextForge builds a structured prompt with file summaries, selected file content, and safety rules. - Gemma 4 returns valid JSON containing readme , agent md , setup , architecture , and summary . - The backend validates the JSON schema before returning it to the frontend. Architecture The app has a small full-stack architecture: User | | ZIP upload or sample project v React + Vite frontend | | HTTP request v FastAPI backend | | safe ZIP extraction / sample project path v Scanner | | selected files + file tree v Stack detector | | structured stack summary v Prompt builder | | documentation prompt v Gemma 4 via Gemini API | | JSON response v Generated docs UI The backend is responsible for file handling, scan limits, prompt construction, and API calls. The frontend is responsible for upload controls, loading states, docs tabs, copy buttons, and ZIP download. How the codebase scanner works The scanner is intentionally simple and safe for an MVP. It walks an extracted project directory recursively and ignores noisy or risky paths, including: .git node modules venv .venv pycache dist build vendor .next .turbo coverage It also skips binary and large files such as databases, images, PDFs, and ZIPs. The scanner only reads text/code files and applies limits: - maximum individual file size: 80KB - maximum collected content: about 300KB Important files are prioritized, including: README.md package.json requirements.txt pyproject.toml Dockerfile docker-compose.yml manage.py settings.py urls.py models.py views.py serializers.py - folders like src , app , and routes The scanner returns a file tree summary, selected file contents, skipped file count, and total collected size. How AGENT.md is generated AGENT.md is generated from the same scan context as the other docs, but the prompt gives it a specific job. It asks Gemma 4 to write AGENT.md for future AI coding agents. That means the output should include: - project map - important directories and files - setup and validation guidance - safe development rules - uncertain assumptions - areas that need extra caution This is the core idea behind ContextForge: make project context durable across AI coding sessions. For example, after a chat is cleared, the next agent can open AGENT.md and immediately understand how to move safely inside the repository. Challenges faced The biggest challenge was deciding how much code context to send to the model. Sending everything is risky and inefficient. Sending too little gives weak documentation. The MVP solves this with a scanner that prioritizes important files, skips generated/binary folders, and keeps a strict total content limit. Another challenge was making the model output predictable. ContextForge asks Gemma 4 for valid JSON with a fixed schema, then the backend validates that response before sending it to the frontend. I also had to handle security basics around ZIP uploads. The backend checks for path traversal before extracting archives and cleans temporary folders after processing. Finally, I wanted the project to work without a real API key during local testing, so I added USE MOCK AI=true . What I would improve next Next improvements I would make: - add GitHub repository cloning from the frontend - support local Gemma 4 inference for private repositories - add richer language-specific parsing - generate docs from diffs after code changes - add server-side history for generated docs - support more output formats for different agent ecosystems - improve prompt compression for large repositories - add background jobs for larger scans The local inference path is especially important. The hosted demo uses Gemini API for easy judging, but private repositories should eventually be able to use local Gemma 4 inference without sending selected code context to an external API.