Document RAG

Cremind gives the agent a searchable knowledge base from plain markdown files. Drop a .md file into a watched folder and Cremind indexes it; ask a question and the documentation_search tool surfaces the relevant document. The trick is what gets indexed — only each file's one-sentence description — which keeps the vector store lean and retrieval sharp.

Watched roots

Cremind watches two kinds of documentation roots:

• Shared — a single working_dir/documents/ folder, available to the install.
• Per-profile — a documents/ folder scoped to a single profile.

A file dropped into a profile's documents/ is indexed for that profile only, honoring the profile isolation boundary.

How indexing works

When a markdown file appears in a watched root, a watcher parses it and indexes the description from its frontmatter into the vector store. The body is not embedded — it's fetched from disk on demand only after a query matches the description.

  documents/my-note.md          vector store           documentation_search
  ┌────────────────────┐        ┌──────────────┐        ┌──────────────────┐
  │ ---                │ watch  │ embedding of │ query  │ match description │
  │ description: "..." │ ─────► │  description │ ─────► │  → fetch body     │
  │ ---                │        └──────────────┘        │     from disk     │
  │ # body (on demand) │                                └──────────────────┘
  └────────────────────┘

This is why the description matters so much: it is the only text that gets embedded, so retrieval ranking is driven entirely by how well a query matches it.

File format

Every document must begin with a YAML frontmatter block, and the parser is strict — files that don't match are silently skipped and never appear in results.

---
description: "One-sentence summary of the whole file."
---

# Document Title

Body in plain Markdown — fetched only after a query matches the description.

Rules that matter:

• The first non-empty line must be exactly ---, with a matching closing ---.
• The mapping must contain a non-empty description string. No other keys are required.
• Quote the description value so colons, hashes, and other YAML special characters parse cleanly.
• The file must sit directly under a documents/ folder, not in a nested subdirectory.

Writing a good description

The description is the single most important field, because it's the only thing embedded. Write it as a concise summary of the entire file that names the topic and the scenario it's useful in.

• Front-load concrete keywords — tool names, command names, artifact names.
• Name the scenario, not just the topic: "How to configure X when Y" beats "About X".
• Avoid vague openers like "documentation about ..." or "notes on ...".
• Keep it to one sentence where you can.

description: "How to configure the exec_shell built-in tool to run long-running background apps, including the metadata.long_running_app.command key and autostart behavior."

Retrieving documents

The agent reaches this knowledge base through the documentation_search built-in tool. It matches a query against the indexed descriptions, then fetches the body of the matching file from disk to read in full.

Verifying a new document

1. Place the file directly under a watched documents/ root (shared or per-profile), not in a subdirectory.
2. Wait about a second for the watcher's debounce to pick it up — no server restart needed.
3. Call documentation_search with a query whose keywords appear in your description; the new file should be in the results.