rony-llm-agent/pkg/rag/README.md

# pkg/rag

> Retrieval-Augmented Generation: memory, embeddings, and semantic search.

## Responsibility

Provide persistent memory and semantic search over agent content.

## Components

| Type | What it stores | Persistence |
|---|---|---|
| **Working** | Current session messages | RAM |
| **Episodic** | Past events: "what I did on 2026-06-20" | Vector DB |
| **Semantic** | Consolidated knowledge: "how is the architecture" | Vector DB (curated) |
| **Procedural** | How to do things: user workflows | Vector DB (auto-learned) |

## Public API

```go
type Memory interface {
    Add(ctx context.Context, fragment Fragment) error
    Search(ctx context.Context, query string, topK int) ([]Fragment, error)
    Forget(ctx context.Context, id string) error
}

type Fragment struct {
    ID         string
    Content    string
    Vector     []float32
    Metadata   map[string]string
    Timestamp  time.Time
    ProjectID  string
}

type Embedder interface {
    Embed(ctx context.Context, text string) ([]float32, error)
    Dimensions() int
}
```

## Backends

| Backend | When to use |
|---|---|
| ChromaDB embedded | Default. Simple, sufficient for <100k docs |
| Qdrant embedded | If you need >100k docs or very fast queries |
| SQLite + sqlite-vec | If you want zero-dependency (no CGO with `modernc.org/sqlite`) |

## Embeddings

| Provider | Model | Dimensions |
|---|---|---|
| Ollama | `nomic-embed-text` | 768 |
| Ollama | `bge-m3` | 1024 |
| Local ONNX | `all-MiniLM-L6-v2` | 384 |

## Usage

```go
import "github.com/VictorVargas/rony-llm-agent/pkg/rag"
import "github.com/VictorVargas/rony-llm-agent/pkg/rag/backends/chroma"

backend, _ := chroma.New(chroma.Config{
    Path: "~/.local/share/rony/chroma",
})

memory := rag.New(rag.Config{
    Backend: backend,
    Embedder: ollamaEmbedder,
})

err := memory.Add(ctx, rag.Fragment{
    Content: "Refactored auth.go using hexagonal",
    ProjectID: "rony",
})
```

## See also

- [pkg/agent](../agent/README.md) — Injects memory into the loop
- [pkg/llm](../llm/README.md) — For summarization in compaction