RAG lets free-code answer from your material — docs, runbooks, ADRs, API references, a third-party library's manual — instead of guessing. You index documents once; during a session the agent retrieves the most relevant passages and grounds its answer in them (and can cite the source) rather than hallucinating.

Everything runs locally: a small server on your machine, a local embedding model, and an on-disk vector index. Nothing is uploaded to the cloud.

Indexing (once per document)

1. The file is loaded and split into overlapping chunks.
2. Each chunk is turned into a 384-dimension vector by the embedding model.
3. Vectors + metadata (source file, text) are stored in the FAISS index for the active knowledge base.

Searching & matching

1. Your query is embedded with the same model, into the same vector space.
2. FAISS finds the nearest chunk vectors by L2 (Euclidean) distance — smaller distance means more semantically similar (it matches by meaning, not keywords).
3. The closest top 5 chunks are returned, and results past a distance threshold (~1.2) are dropped so weak matches don't add noise.
4. The surviving chunks are injected into the conversation as context for the model to answer from.

1 · Indexing — putting information in

2 · Querying — getting information back out

Start the server

# Keep this running (default http://localhost:8085)
free-code-rag

Quick start in a session

/rag-kb create my-docs     # create a knowledge base
/rag-kb use my-docs        # make it the active one
/rag addFile ./README.md   # index a document
/rag search "how does auth work?"   # query it

Documents

Knowledge bases

Each knowledge base is its own isolated index. Keeping several — instead of one big pile — pays off:

• Sharper results — searching a focused KB returns more on-topic matches; unrelated documents can't crowd out the right ones.
• Per-project / per-domain context — one KB for your backend, one for the design system, one for a client's docs. Switch with /rag-kb use.
• No cross-contamination — confidential or client-specific material stays in its own KB and never leaks into another project's answers.
• Cheaper, faster — a smaller, relevant index means quicker search and tighter, lower-token context.
• Easy lifecycle — refresh, rebuild, or drop a whole topic by managing just its KB.

RAG permite que free-code responda a partir de tu material — documentación, runbooks, ADRs, referencias de API, el manual de una librería de terceros — en lugar de adivinar. Indexas los documentos una vez; durante una sesión el agente recupera los pasajes más relevantes y basa su respuesta en ellos (pudiendo citar la fuente) en vez de alucinar.

Todo se ejecuta localmente: un pequeño servidor en tu máquina, un modelo de embeddings local y un índice vectorial en disco. Nada se sube a la nube.

Indexación (una vez por documento)

1. El archivo se carga y se divide en fragmentos solapados.
2. Cada fragmento se convierte en un vector de 384 dimensiones mediante el modelo de embeddings.
3. Los vectores + metadatos (archivo de origen, texto) se almacenan en el índice FAISS de la base de conocimiento activa.

Búsqueda y coincidencia

1. Tu consulta se convierte en embedding con el mismo modelo, dentro del mismo espacio vectorial.
2. FAISS encuentra los vectores de fragmentos más cercanos por distancia L2 (euclidiana) — una distancia menor significa mayor similitud semántica (coincide por significado, no por palabras clave).
3. Se devuelven los 5 fragmentos más cercanos, y los resultados que superan un umbral de distancia (~1.2) se descartan para que las coincidencias débiles no añadan ruido.
4. Los fragmentos que sobreviven se inyectan en la conversación como contexto para que el modelo responda a partir de ellos.

1 · Indexación — ingresando información

2 · Consulta — recuperando la información

Iniciar el servidor

# Deja esto en ejecución (por defecto http://localhost:8085)
free-code-rag

Inicio rápido en una sesión

/rag-kb create my-docs     # crea una base de conocimiento
/rag-kb use my-docs        # la convierte en la activa
/rag addFile ./README.md   # indexa un documento
/rag search "how does auth work?"   # la consulta

Documentos

Bases de conocimiento

Cada base de conocimiento es un índice aislado propio. Mantener varias — en lugar de un único gran montón — vale la pena:

• Resultados más precisos — buscar en una base de conocimiento enfocada devuelve más coincidencias relevantes; los documentos no relacionados no pueden desplazar a los correctos.
• Contexto por proyecto/dominio — una base de conocimiento para tu backend, otra para el sistema de diseño, otra para la documentación de un cliente. Cambia con /rag-kb use.
• Sin contaminación cruzada — el material confidencial o específico de un cliente permanece en su propia base de conocimiento y nunca se filtra en las respuestas de otro proyecto.
• Más económico y rápido — un índice más pequeño y relevante implica una búsqueda más rápida y un contexto más ajustado, con menos tokens.
• Ciclo de vida sencillo — actualiza, reconstruye o elimina un tema completo gestionando solo su base de conocimiento.