How do I improve the quality of what the brain returns?

Practical steps to get better recall from the Unison brain: ingest more, write clearer facts, use the right mode, and scope your queries.

The brain keeps returning weak or irrelevant context. How do I fix it?

Recall quality is a function of what's in the brain and how you ask for it. Here's a checklist to work through.

1. Ingest more relevant content

The brain can only recall what it knows. If a topic is returning weakEvidence: true, the most direct fix is ingesting content that covers it.

Conversations: POST recent agent/user exchanges so entity extraction can pull out facts automatically.
Documents: Write structured facts directly — they're ingested synchronously and available immediately.

# Write a fact directly
curl -X PUT https://brain.unisonlabs.ai/v1/brain/doc \
  -H "Authorization: Bearer $UNISON_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"path": "/private/notes/my-fact.md", "bodyMd": "We use PostgreSQL 16 as the primary database.", "title": "DB choice"}'

2. Write clearer, more specific facts

Vague content produces vague recalls. Instead of "we talked about the database," write "we chose PostgreSQL 16 over MySQL because of JSONB support and our existing team familiarity."

3. Use deep mode

If the information is in the brain but spread across many small facts, mode=standard may not aggregate it. Switch to mode=deep:

GET /v1/brain/context?q=your+question&mode=deep

4. Be more specific in your query

Short, vague queries match too many things. "decisions" scores against everything. "API authentication decisions from Q1" is specific enough to rank the right facts first.

5. Scope with pathPrefix

If you know the relevant facts live under a specific path, add pathPrefix to the request to narrow the search space and improve ranking within that scope:

GET /v1/brain/context?q=database&pathPrefix=/private/notes/

See Scoping recall for details.