Neural Kitchen 🧠👨‍🍳

A recipe/cookbook management system for AI agents

Neural Kitchen helps developers create and organize structured guidance for AI agents working on software projects. Think of it as a knowledge base that captures institutional knowledge, coding patterns, and step-by-step workflows that AI agents can follow.

Screenshots

  

The Problem

AI agents often struggle with:

• Lack of context: They don't understand project-specific conventions or patterns
• Missing institutional knowledge: Why certain approaches are used over others, or when an old pattern is being phased out
• Inconsistent implementations: Without examples, they reinvent solutions differently each time
• Limited guidance: Hard to know which files contain good examples to follow

Humans often struggle with:

• AI forgets: AI tools don't remember your past conversations or corrections you made
• AI is eager to please: The AI tools don't stop to ask questions, they just build what they "know"
• Forgetting about best practices: Best practices are learned (and contextual), yours wont match the AIs

The Kitchen

Neural Kitchen provides:

• Recipes: Step-by-step instructions and code examples for common development tasks written by you
• NLP Search: Natural language (RAG Based) search for your documentation and standards
• Project Association: Group recipes by codebase or project (share with other teams or projects)
• MCP Integration: Model Context Protocol interface for AI agents to access and search recipes

Current Status

🚧 Early Development - This project is just getting started!

Implemented:

• Basic recipe/version management system
• Tag organization
• Project grouping
• Web interface for managing recipes
• MCP server integration for AI agent access
• Project specific MCP endpoints

Planned:

• Rich recipe templates and examples
• Advanced search and filtering
• Recipe validation
• Recipe auto generation
• Recipe review tools

Tech Stack

• React 19 with TanStack Start
• PostgreSQL with Prisma ORM
• TailwindCSS v4 + Shadcn/ui
• Biome
• MCP (Model Context Protocol) server

Getting Started

Option 1: Docker/Podman (Recommended)

1. Clone the repository

   git clone https://github.com/mikevalstar/NeuralKitchen.git
   cd NeuralKitchen

2. Set up environment (optional)

   cp .env.example .env
   # Edit .env and add your OPENAI_API_KEY if you want AI features

3. Start with Docker Compose

   docker-compose up
   # or with Podman
   podman-compose up

4. Set up database (first time only)

   # In another terminal, run migrations
   docker-compose exec app pnpm db:push
   docker-compose exec app pnpm db:seed  # Optional: add sample data

5. Create an admin user

   # Create your first admin user to access the application
   docker-compose exec app pnpm user:add admin@example.com mypassword123 "Admin User"

The application will be available at:

• Web UI: http://localhost:3000

Option 2: Local Development

1. Clone the repository

   git clone https://github.com/mikevalstar/NeuralKitchen.git
   cd NeuralKitchen

2. Install dependencies

   pnpm install

3. Set up the database

   # Start a psql shell as the postgres superuser
   psql postgres
   
   # Inside the psql shell, run:
   CREATE USER neuralkitchen WITH PASSWORD 'yourpassword' CREATEDB SUPERUSER ;
   CREATE DATABASE neuralkitchen OWNER neuralkitchen;
   \q
   
   # Your DATABASE_URL for .env will look like:
   # DATABASE_URL="postgresql://neuralkitchen:yourpassword@localhost:5432/neuralkitchen"

   Install pgvector if not already installed

   CREATE EXTENSION vector;
   
   -- confirm
   SELECT * FROM pg_extension WHERE extname = 'vector';

   # Configure your DATABASE_URL in .env, and seed (optional)
   pnpm db:migrate
   pnpm db:seed

4. Create an admin user

   # Create your first admin user to access the application
   pnpm user:add admin@example.com mypassword123 "Admin User"

5. Start development

   pnpm dev

Development

• pnpm dev - Start development server and mcp server
• pnpm build - Build for production
• pnpm check - Run linting and formatting
• pnpm db:studio - Open database GUI

Logging System

Neural Kitchen includes comprehensive structured logging using Pino:

Server-Side Logging (Node.js environments):

• Component-specific logs: Separate log files for different services
  • logs/combined.log - All system logs
  • logs/app.log - Web application logs
  • logs/mcp.log - MCP server operations
  • logs/background-tasks.log - Queue processing and AI operations
  • logs/auth.log - Authentication events
  • logs/database.log - Database queries and performance

Client-Side Logging (Browser):

• Simple console logging with component prefixes ([WEB], [AUTH])
• Structured error tracking for debugging

Environment Configuration:

# In your .env file
LOG_LEVEL=info                    # debug, info, warn, error
LOG_DIR=./logs                   # Directory for log files
LOG_TO_FILE=true                 # Enable file logging
LOG_TO_CONSOLE=true              # Enable console output
LOG_PRETTY_CONSOLE=true          # Pretty formatting in development

Key Features:

• Request correlation: Track requests across components with unique IDs
• Performance timing: Measure and log operation duration
• Error tracking: Comprehensive error logging with stack traces
• Authentication events: Login attempts, failures, and user actions
• AI operations: Track summarization and embedding generation
• Database monitoring: Slow query detection and connection logging

Logs are structured as JSON for easy parsing and analysis in production environments.

User Management

• pnpm user:add <email> <password> [name] - Create a new admin user
• pnpm user:list - List all users
• pnpm user:delete <email> - Delete a user

See CLAUDE.md for detailed AI development guidance.

AI Development Disclosure

This project was developed with assistance from AI coding tools including Cursor and Claude. AI tools were used for code generation, debugging, and documentation throughout the development process. All code has been reviewed before addition to the project for good structure and security concerns.

Contributing

This project is in early development. Contributions, ideas, and feedback are welcome!

This project welcomes contributions developed with or without AI assistance. Contributors using AI tools should ensure all generated code is reviewed and tested before submission and indicate the tools used in the Pull Request.

License

MIT License - see LICENSE for details.

---

Neural Kitchen: Empowering AI agents with structured knowledge and proven patterns.