The durable specification for Brainy — a personal bookmark knowledge base that uses AI and hybrid search to help you organize, search, and discover bookmarks across platforms like YouTube, Twitter/X, Instagram, TikTok, and the web.
This repository contains no implementation code. On purpose.
The idea comes from Chad Fowler's Evaluations Are the Real Codebase, which argues that in the age of AI-assisted development, code is cheap to generate but understanding and verifying behavior are expensive. The durable asset isn't the codebase — it's the specification that defines what the system must do.
The core diagnostic: if deleting your codebase feels terrifying, your evaluations are insufficient.
Brainy Spec puts that idea into practice. Everything here — the system contracts, invariants, behavioral properties, and tiered test definitions — is designed to survive reimplementation. The code that implements Brainy can be rewritten in any language, by any team (human or AI), and these specs remain the source of truth.
SPEC.md— The full system specification: API contracts, data models, processing pipelines, search algorithms, system invariants, and behavioral properties.tests.yaml— A three-tier test suite (durable evaluations, ephemeral tests, live evaluations) that any implementation must satisfy.
Brainy is an async-first bookmark system with:
- Google Gemini AI for embeddings, entity extraction, summaries, and answer generation
- Hybrid search combining semantic (vector embeddings) and lexical (full-text) search
- Knowledge graph (Neo4j) for entity extraction and discovery
- Graceful degradation — optional subsystems can fail without blocking core functionality
- Multi-platform content extraction with paywall detection and archive fallbacks
- Streaming answers via SSE for question-answering over your bookmarks
Following Fowler's framework, the test suite is organized by durability:
- Durable evaluations — Invariant checks, property-based tests, contract conformance, and end-to-end lifecycle tests. These survive reimplementation.
- Ephemeral tests — Example-based tests tied to specific implementation details. Disposable when the code changes.
- Live evaluations — Continuous production monitoring for drift detection, operational metrics, and business invariants.