51 lines
2.1 KiB
Markdown
51 lines
2.1 KiB
Markdown
# 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)
|