How memory works
Store a typed outcome, retrieve with hybrid search, cite what you used.
A "memory" in ValorBrain is a document in a collection, inside a tenant. Agents should treat retrieval as lookup of company truth, not as a chat log.
Store
Prefer the typed write:
- MCP:
memory_storewithtype∈decision|observation|problem|milestone|handoff|lesson|note - REST/CLI:
POST /documents(CLIadd)
store (bare) still exists on the MCP catalog as a deprecated alias of
memory_store. Do not document it to new clients; do not call it.
Text is stored verbatim. Portuguese stays Portuguese.
Short bodies (under ~200 characters) may skip embedding. They remain searchable on the lexical path.
Retrieve
The default path is hybrid: BM25 + dense vectors + RRF, then a cross-encoder rerank on the hosted product.
| Tool / route | When |
|---|---|
memory_retrieve / POST /search | One well-formed question. The server expands and fuses. |
memory_prepare | Session start / "give me the context for this task" |
working_context | Cheapest orientation: stable facts + recent decisions |
memory_grep | Exact string, id, date, key — not a paraphrase |
Do not fire five near-duplicate retrieves. If the first set is thin, switch
tool: exact → memory_grep; more of a hit → get / multi_get; why →
find_causal_links (graph toolset).
Collections
A collection is a named bucket (decisions, incidents, …). list /
GET /collections shows what the tenant has. You choose the name when you
write; there is no global required taxonomy for customers.
Ranking loop
After you answer with retrieved memory, call memory_used with the docids
you actually relied on. Used memories rise; ignored ones decay. Optional
verdict: confirmed or corrected when the human reacts. This is the
strongest ranking signal in the product. Current declaration rate in the
wild is low — do not be part of that number.