# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

**my-brain-importer** is a personal RAG (Retrieval-Augmented Generation) system written in Go. It ingests Markdown notes and image descriptions into a Qdrant vector database and answers questions using a local LLM via LocalAI.

## Commands

```bash
# Build all binaries (Linux + Windows cross-compile)
bash build.sh

# Run directly without building
go run ./cmd/ingest/
go run ./cmd/ask/ "your question here"

# Build individual binaries
go build ./cmd/ingest/
go build ./cmd/ask/

# Run tests
go test ./...

# Tidy dependencies
go mod tidy
```

Binaries are output to `./bin/`. The `config.yml` file must exist in the working directory at runtime.

## Architecture

Two CLI tools share a common internal library:

**`cmd/ingest/`** → `internal/brain/ingest.go` + `internal/brain/ingest_json.go`
- Markdown mode: recursively finds `.md` files, splits by `# `/`## ` headings, chunks long sections (max 800 chars) by paragraphs, embeds in batches of 10, upserts to Qdrant
- JSON mode (when arg ends in `.json`): imports image description records with `file_path`, `file_name`, `description` fields

**`cmd/ask/`** → `internal/brain/ask.go`
- Embeds the question, searches Qdrant (top-k, score threshold 0.5), deduplicates by text content, streams LLM response constrained to retrieved context

**`internal/config/config.go`** initializes all clients: gRPC connection to Qdrant and OpenAI-compatible HTTP clients for embeddings and chat (both point to LocalAI).

## Key Patterns

- **Deterministic IDs**: SHA256 of `source:text` — upserting the same content is always idempotent
- **Excluded directories**: `05_Agents` and `.git` are skipped during markdown ingest
- **config.yml** must be present in the working directory; defines Qdrant host/port/api_key, embedding model + dimensions, chat model, `brain_root` path, and `top_k`
- External services: Qdrant (gRPC port 6334) and LocalAI (HTTP, OpenAI-compatible API)