Documentation

Guide

Find context

Your agent needs one fact from a large knowledge tree. This guide finds it in a few bounded steps and reads only the sections that answer the task.

Choose a starting route

You haveStart with
A known areacumaru tree <area>
A question, no exact termcumaru context "<query>"
An exact identifierrg -n -F -- "<term>" .cumaru
A known fileRead it directly.

1. List candidates

Start shallow. Each row is a path and its one-line summary:

cumaru tree specs

Pick the candidates whose summaries match the task. Recurse only into those directories.

2. Map the sections

Get the headings of a selected file with their line ranges:

cumaru map specs/auth.md

Each row starts with a selector such as specs/auth.md:18,42.

3. Read only that section

cumaru get specs/auth.md:18,42

Stop when the evidence answers the task.

Rank by meaning

When you do not know where a fact lives, rank the files against a short English query. Each row is a path range and a score:

cumaru context "how sessions expire"
  • A Markdown row is a get selector relative to .cumaru/. A source row starts with ./ and is relative to the project root. get cannot read it. Read it with a normal tool, such as sed -n 'START,ENDp' PATH.
  • Scores are uncalibrated. Compare ordering and read the top results; no score proves absence.
  • Without a model, a lightweight lexical scorer runs and can miss paraphrases. If the results are weak, refine the query or switch to tree or exact search. The lightweight scorer ranks whole files. Run cumaru map first and read only the relevant section.
  • context works offline and never downloads. To use the optional encoder, a person must run cumaru model pull bge-micro-v2 once (about 35 MB).

In an agent session

The cumaru-search skill applies these routes for your agent. With the read hook installed, a cat of a .cumaru/ Markdown file is redirected to map and get.

Sources: tree, map, get, context, model, cumaru-search. Command details: CLI reference.