Skip to the content.

RAG

Overview

CLike currently supports repository-grounded RAG for Harper, coding, and free-mode use cases.

Main goals:

Main surfaces

Extension

The extension supports:

Relevant files:

Orchestrator

The orchestrator exposes RAG APIs under /v1/rag/*.

Relevant files:

Indexing is batched and incremental: chunks are embedded in batches (RAG_EMBED_BATCH_SIZE, default 64, RAG_EMBED_CONCURRENCY 4 calls at a time) and files whose content is already indexed are skipped (point ids derive from path + content).

Gateway

The gateway can consume RAG materials during Harper execution. It is a client of the orchestrator /v1/rag API (no store of its own); its /v1/embeddings accepts a list input and returns one vector per item.

Relevant files:

Current APIs

Current orchestrator RAG endpoints:

Memory panel

CLike: Memory (or 🧠 Memory in the chat, every layout) opens a panel of its own next to the chat. It holds two memories:

Ask (the default tab, ⌘K) answers instead of listing files. CLike takes the best passages of the chosen memories (Project, CLike Guide, or both), numbers them, and the model writes a short answer only from them, in the language of the question: the sources cited as [n], the steps with the exact CLike command to copy when the question asks what to do, how sure it is and why, and up to three next questions. When the sources do not answer, it says so (“not in the memory”). The answer also gets the project as it is now — the next action, the last eval or gate with its blocking failures, a test patch waiting for review — and each project source carries the date its file changed: when an older note disagrees with the state, the state wins and the answer says the note is outdated. The NOW questions above the box come from the same state (a test patch to review, the last failed run, the next action). Ask uses the chat’s execution choice: the cloud model, or the local agent in a short read-only run, with no session and no chat history.

Search lists the matching files instead. Ask in natural language, in any language (the search is semantic): each result is a file with the lines that answer — the question’s words highlighted — and a link to open it. The semantic ranking is refined by the question’s exact words, weighted by how rare they are among the candidates (--accept counts, how does not); words no candidate contains, e.g. of another language, change nothing. On the left, Contents lists what each memory holds (by group, with a filter) and Recent searches repeats a search with a click.

The chat and the Memory panel do not exchange anything: 💬 Chat in the panel and 🧠 Memory in the chat only open the other panel, or bring it to the front. Files reach the memory from the chat (📎 Attach); the panel lists them.

/adopt fills it

On a project brought into CLike, /adopt indexes the documentation it finds (docs/ of the root and of each area, READMEs, agent context files, changelogs, API and event contracts), the code map docs/harper/CODEMAP.md and the source code of the areas adopted (code, tests, contracts, configuration; never a real .env or a lock file). Unchanged files are not embedded again. See Bringing an existing project into CLike.

The project memory follows the KITs

The KIT of a REQ is indexed after /kit and after /eval, without hidden folders (ci/.tmp copies of the workspace, caches). Right after, the memory drops that REQ’s files the KIT no longer has, and files in hidden folders of any KIT indexed by earlier versions (unless the KIT reached the indexing cap, when the files past it are still in the KIT).

Current extension commands

Manual indexing

Attachment management

Inline vs RAG attachments

The current codebase keeps a clear conceptual distinction.

Inline attachments

Used when the extension decides to send raw content directly.

Best suited for:

RAG attachments

Used when files are indexed and passed by reference.

Best suited for:

Extension-side RAG behavior

The extension no longer chunks Harper documents itself (its rag.js helper was removed in 1.0.0): indexing and retrieval go through the orchestrator /v1/rag/* APIs.

Project inputs that every phase should read (requirements, UI references, release folders docs/inputs/vN/, docs/reference/vN/) can be declared as context sources instead (.clike/context.yaml, see context-sources.md): they are delivered whole to the phases that read them, not retrieved by similarity.

Current RAG decision parameters in runtime config

The runtime stack currently exposes threshold-style RAG tuning such as:

These values influence the boundary between:

RAG project identity

The code uses project-aware or workspace-aware IDs for RAG namespaces.

Common concepts in current sources:

RAG in Harper flows

Harper requests can carry:

This means RAG is not bolted on after the fact. It is part of the Harper request model.

Fetch and search patterns

Search

Search returns scored matches by path and chunk content.

Fetch

Fetch endpoints support:

Current documentation rule

The current sources support documenting RAG as:

The current sources do not justify documenting it as: