Writing Documents for RAG

Cremind has a knowledge base that the agent can search: Markdown documents under a documents/ directory that feed the built-in documentation_search tool. This is distinct from the web docs you are reading now — it is the in-app RAG corpus the running agent consults. This page explains the document format and, importantly, the token-frugal contract that shapes how you should write these files.

Where documents live

Documents are Markdown files kept in two scopes:

• Shared — <CREMIND_SYSTEM_DIR>/documents/, available to every profile. The bundled documents/*.md shipped with Cremind are mirrored here on boot (the bundle is authoritative — extras or in-session edits only live until the next restart).
• Per-profile — <CREMIND_SYSTEM_DIR>/<profile>/documents/, visible only to that profile.

A sync service keeps the files on disk, the profile directories, and the vector store in lockstep, upserting changed files and dropping points whose source files disappear.

The document format

An eligible document is a .md file with a YAML frontmatter block whose first non-empty line is exactly ---, containing a non-empty description:

---
description: "How to write a sample skill for Cremind, from SKILL.md to a uv-run CLI."
---

# Writing a sample skill

...the full body the agent receives when this document is chosen...

The parser is strict. A file is silently ineligible — skipped during sync, never indexed — if any of these hold:

• it has no ----delimited frontmatter pair,
• the frontmatter is not a YAML mapping,
• the description field is missing or empty.

Only description is required. The body is everything after the closing ---.

How retrieval works

The documentation_search tool runs in two stages, and the format exists to make that cheap:

1. Vector search. The user's query is embedded and matched against every document's description, returning the top candidates (default 10, capped at 20).
2. LLM-as-judge. A small internal LLM reads the query alongside each candidate's name and description only — never the bodies — and calls one of two tools: select_document(index) for the single best match, or no_relevant_result() when nothing is on-topic.
3. Fetch the winner. Only after the judge picks does the tool open the chosen file and return its body verbatim to the reasoning agent.

This is the token-frugal contract: bodies never reach the judge, so adding more documents grows the judge's prompt by one sentence each, not by whole files. The body cost is paid once, only for the document that actually wins.

Writing good documents

Because the description is the index and the body is the payload, write each accordingly:

• Make the description a precise single sentence. State what the document covers and the verbs or scenario it answers — that's what the judge ranks on. The parser already treats it as one sentence per the frontmatter contract, so don't pad it.
• Give the file a meaningful name. The judge also sees the document's name (derived from the file), so a clear name helps disambiguation.
• Put the real answer in the body. It's handed to the agent verbatim, so write it as complete, self-contained guidance — the agent won't see surrounding documents.
• One topic per document. A focused document with a sharp description out-ranks a sprawling one whose description can't summarize it.

Adding a document

Drop a conforming .md file into the appropriate documents/ directory. The sync service reconciles it into the vector store; eligible files become searchable, ineligible ones are silently skipped. If a document isn't being found, the first thing to check is that its frontmatter has a non-empty description and that the first non-empty line is exactly ---.