Documents

Cremind has a built-in document store you feed simply by dropping Markdown files into a watched folder. A background watcher notices the new file, indexes it, and the agent can then pull it up on demand through the documentation_search built-in tool. There is no upload button and no rebuild step — saving the file is the whole workflow.

Where documents live

A document is a Markdown (.md) file under one of two watched roots:

• Shared — <CREMIND_WORKING_DIR>/documents/*.md
• Per-profile — <CREMIND_WORKING_DIR>/<profile>/documents/*.md

The file must sit directly inside a documents/ folder. Files nested in a subdirectory are not indexed.

The file format

Every document begins with a YAML frontmatter block, then a Markdown body. The parser is strict — files that don't match the shape are silently skipped and never appear in search results.

---
description: "<one-sentence summary of the whole file>"
---

# Document Title

Body in plain Markdown...

The rules:

• The first non-empty line of the file must be exactly ---.
• A YAML mapping of key/value pairs follows.
• A closing --- on its own line ends the frontmatter.
• The mapping must contain a description key with a non-empty string value. No other keys are required.
• Everything after the closing --- is the body.

The description is what gets searched

The description is the single most important field. It is the only text embedded into the vector store — the body is never indexed. When you call documentation_search, ranking is driven entirely by how well your query matches each file's description. The body is read from disk only after a description matches.

Write the description as a concise summary of the whole file: name the topic and the scenario where the document is useful.

A good description:

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."

Writing the body

The body is shown to the agent only after retrieval, so write it for a reader who already knows roughly why they are here.

• Use ## for top-level sections and ### for subsections; reserve a single # for the document title.
• Prefer concrete examples and fenced code blocks (with a language tag) over long prose.
• Cross-reference other documents by relative path.
• Don't repeat the description verbatim — the description is for discovery, the body is for detail.

A minimal example

The smallest valid document:

---
description: "How to configure the foo widget for the bar workflow."
---

# Configuring the Foo Widget

To enable the foo widget in the bar workflow, set `foo.enabled = true`
in the profile config and restart the server.

Searching from the agent

Once a file is indexed, ask the agent something whose keywords appear in a description. The agent calls the documentation_search built-in tool, gets back the matching files, and reads their bodies to answer. You don't invoke the tool by hand — you just ask.

Verifying a new document

After saving a file:

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

If the file doesn't show up, the usual causes are:

Related