ai-agent/CLAUDE.md

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

# 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)