wicked-brain

Indexes markdown files containing code skills and knowledge into a local SQLite database with FTS5 (Full-Text Search 5) enabled, enabling semantic keyword matching without vector embeddings or external infrastructure. The system parses markdown structure (headings, code blocks, metadata) and builds inverted indices for fast retrieval of skill documentation by natural language queries. No external vector DB or embedding service required — all indexing and search happens locally.

Retrieves indexed skills from the local SQLite database and injects them into the context window of AI coding CLIs (Claude Code, Cursor, Gemini CLI, GitHub Copilot) as formatted markdown or structured prompts. The system acts as a middleware layer that intercepts queries, searches the skill index, and prepends relevant documentation to the AI's input context before sending to the LLM. Supports multiple CLI integrations through adapter patterns.

Provides a command-line interface for managing the skill library (add, remove, search, list, export) without requiring programmatic API calls. Commands include `wicked-brain add <file>`, `wicked-brain search <query>`, `wicked-brain list`, `wicked-brain export`, enabling developers to manage skills from the terminal. Supports piping and scripting for automation.

Provides a structured system for organizing, storing, and versioning coding skills as markdown files with optional metadata (tags, difficulty, language, category). Skills are stored in a flat or hierarchical directory structure and can be edited directly in any text editor. The system tracks which skills are indexed and provides utilities to add, update, and remove skills from the index without requiring a database UI or special tooling.

Executes all knowledge indexing and retrieval operations locally on the developer's machine using SQLite FTS5, eliminating the need for external services, API keys, or cloud infrastructure. The entire skill database is stored as a single SQLite file that can be backed up, versioned, or shared via Git. No network calls, no rate limits, no vendor lock-in — all operations complete in milliseconds on local hardware.

Provides an extensible adapter pattern for integrating the skill library with multiple AI coding CLIs through standardized interfaces. Each CLI adapter handles the specific protocol, context format, and API of its target tool (Claude Code's prompt format, Cursor's context injection, Gemini CLI's request structure). New adapters can be added by implementing a simple interface without modifying core indexing logic.

Converts natural language queries into FTS5 search expressions by tokenizing, normalizing, and optionally expanding queries with synonyms or related terms. The system handles common query patterns (e.g., 'how do I X' → search for skill tags matching X) and applies FTS5 operators (AND, OR, phrase matching) to improve precision. No machine learning or semantic models — purely lexical matching with heuristic query expansion.

Parses markdown skill files to extract structured metadata (title, description, tags, language, difficulty, category) from frontmatter (YAML/TOML) or markdown conventions (heading levels, code fence language tags). Metadata is indexed alongside skill content, enabling filtered searches (e.g., 'find all Python skills tagged with async'). Supports custom metadata fields through configuration.

Indexes multiple markdown files in batch operations, computing file hashes to detect changes and only re-indexing modified files. The system maintains an index state file tracking which skills have been indexed and their modification timestamps. Supports full re-indexing and incremental updates, enabling fast skill library updates without rebuilding the entire index.

Selects and ranks the most relevant skills from search results to fit within the LLM's context window limit, using heuristics like skill size, relevance score, and recency. The system truncates or summarizes skills that exceed token budgets and prioritizes high-relevance matches. Supports configurable context window sizes for different LLMs (Claude 3, GPT-4, Gemini) and provides fallback strategies when skills don't fit.

Exports the indexed skill library in multiple formats (JSON, CSV, markdown index) for sharing, backup, or integration with other tools. Supports selective exports (e.g., export only Python skills) and includes metadata, search indices, and skill content. Exported libraries can be re-imported into other wicked-brain instances or used as standalone documentation.