vibebase

A semantic GIF database for AI chatbots. Ingest GIFs from Giphy, describe them with Gemini vision, embed the descriptions, and search by conversational context using cosine similarity.

How it works

1. Ingest — Fetches GIFs from Giphy across emotion categories (celebration, confused, excited, awkward, etc.)
2. Describe — Sends a still frame of each GIF to Gemini 2.5 Flash, which writes a 2-3 sentence description covering emotional tone, energy level, and ideal conversational context
3. Embed — Generates a vector embedding of each description using gemini-embedding-001
4. Store — Saves the GIF URL, description, and embedding in a local SQLite database (gifs.db)
5. Search — Embeds a query string and finds the closest match via cosine similarity

Prerequisites

• Node.js 18+
• A Giphy API key
• A Google AI API key (for Gemini)

Setup

npm install

Create a .env file:

GIPHY_API_KEY=your_giphy_key
GOOGLE_API_KEY=your_google_key

Usage

Ingest GIFs

npm run ingest

Fetches 5 GIFs per category (10 categories), describes each with Gemini vision, and stores them with embeddings. Skips GIFs that are already in the database.

Search

Import searchGif in your own code:

import { searchGif } from "./search.js";

const result = await searchGif("someone just deployed to production on a Friday");
// { url: "https://media.giphy.com/...", description: "..." }

Audit UI

Browse the full database in your browser:

npx tsx audit.ts

Opens a filterable grid at http://localhost:3000 showing every GIF with its description.

Database schema

Single table, gifs:

Column	Type	Description
id	INTEGER	Auto-incrementing primary key
giphy_id	TEXT	Unique Giphy identifier
url	TEXT	Original GIF URL
still_url	TEXT	Still frame URL (used for describing)
description	TEXT	Gemini-generated description
embedding	TEXT	JSON array of embedding floats

MCP Server

vibebase exposes an MCP stdio server for use with any MCP-compatible agent.

Run the server

npm run mcp

Or with a custom database path:

VIBEBASE_DB_PATH=/path/to/gifs.db npm run mcp

Available tools

Tool	Description
search_gif(context)	Find a GIF matching a conversational context description
ingest_category(category, limit?)	Seed the database with GIFs for a given emotional category

Nanoclaw Integration

To add vibebase as an agent tool:

1. Copy nanoclaw/SKILL.md to .claude/skills/add-vibebase/SKILL.md in your project
2. Run /add-vibebase in Claude Code

That's it. The skill handles wiring up the MCP server, copying runtime docs, and configuring environment variables.

Project structure

db.ts       — SQLite setup and schema
ingest.ts   — Giphy fetch + Gemini describe + embed pipeline
search.ts   — Semantic search via cosine similarity
mcp.ts      — MCP stdio server (search_gif + ingest_category)
audit.ts    — Local web UI to browse the database
nanoclaw/   — Agent integration skills