Cuba-Memorys is a long-term memory system for AI coding agents, built on PostgreSQL + pgvector, providing a searchable, verifiable knowledge graph with 28 tools across knowledge management, hybrid search, error tracking, procedural memory, and more.
Knowledge Graph Management: Create, update, delete, and retrieve entities (cuba_alma); attach facts, lessons, decisions, errors, and episodic memories (cuba_cronica); create typed relations (uses, causes, depends_on, etc.), traverse connections, infer transitive links, and predict missing links (cuba_puente).
Hybrid Search & Verification: Perform hybrid RRF search combining full-text, BM25, and pgvector HNSW semantic search; verify claims against stored evidence with local NLI cross-encoder (mDeBERTa) or LLM fallback; rerank results (bge-reranker-v2-m3), diversify via MMR, abstain on out-of-distribution queries using Mahalanobis distance, and apply temporal filtering. Includes associative expansion and token budget control (cuba_faro).
Error Tracking & Learning: Report errors with automatic pattern detection (cuba_alarma), resolve errors with cross-referenced solutions (cuba_remedio), and search past errors with anti-repetition guard (cuba_expediente).
Session & Project Management: Track working sessions with goals and outcomes (cuba_jornada); isolate memories per project (cuba_proyecto); persist session snapshots to survive context compaction (cuba_pre_compact); record architectural decisions with rationale (cuba_decreto).
Procedural Memory: Store and search step-by-step recipes ranked by reliability (Wilson lower bound), not frequency (cuba_receta).
Cognition & Analysis: Detect structural gaps (cuba_reflexion), perform abductive inference (cuba_hipotesis), find semantic contradictions (cuba_contradiccion), set prospective triggers (cuba_centinela), calibrate confidence with Bayesian tracking (cuba_calibrar), and use LLM judge for conflicting observations (cuba_juez).
Maintenance & Governance: Decay, prune, merge duplicates, summarize, re-encode, and compute PageRank (cuba_zafra); apply RLHF feedback with quarantine gate (cuba_eco); run health analytics, drift detection, and community detection (cuba_vigia). Ensure GDPR erasure (cuba_forget) and tamper-evident audit logging with SHA-256 hash chain (cuba_archivo).
Bulk Ingestion: Ingest structured items, parse raw text, or auto-extract facts from conversations via LLM (cuba_ingesta).
Working Memory: TTL-bounded scratchpad for inter-step state (cuba_pizarra).
Meta & Tooling: Discover tools and load their schemas on demand (cuba_tools); invoke any tool by name (cuba_call). Export/import knowledge graph in Git-friendly JSON (cuba_sync). Manage server with 19 CLI commands for local/HTTP daemon mode, model installation, setup, calibration, and deduplication.
Enables git-friendly export and import of memory data, allowing version control and diff review in PRs.
Provides persistent memory storage using PostgreSQL as the database backend, enabling semantic search with pgvector HNSW and full-text search.
Formerly cuba-memorys. Same daemon, same cuba_* MCP tools, new product name.
Long-term memory for AI coding agents. An MCP server that gives your agent a knowledge graph it can search, reason over, and be corrected by — so it stops forgetting your codebase between sessions.
Written in Rust. Backed by PostgreSQL + pgvector. 31 MCP tools (32 with CUBA_DOCS=1), 23 CLI commands, and every number below measured on a benchmark that — as of v0.12 — actually measures what it claims to. (The previous one did not. See Measured.)
pip install memory-industry # or: npm install -g memory-industry
claude mcp add memory-industry -- memory-industry
# Previous names still install the same binary:
# pip install cuba-memorys
# npm install -g cuba-memorysThat is the whole setup. On first run it provisions a PostgreSQL 18 + pgvector container via Docker and initializes the schema. Docker must be running. The cuba-memorys command remains a binary alias.
{
"mcpServers": {
"memory-industry": {
"command": "memory-industry"
}
}
}No DATABASE_URL needed. Or run cuba-memorys setup (or memory-industry setup) and it writes the config for every client it finds — then cuba-memorys setup check audits them for disagreement, which is the failure that actually bites (two configs, two embedding dimensions, one silently broken search).
{
"mcpServers": {
"memory-industry": {
"command": "memory-industry",
"env": { "DATABASE_URL": "postgresql://user:pass@localhost:5432/brain" }
}
}
}Needs the vector and pg_trgm extensions. cuba-memorys doctor will tell you if anything is missing.
stdio gives every client its own process, and every process loads its own copy of the models — embeddings, reranker and NLI together are several GB. Three editor windows meant three copies, and on a 16 GB laptop that is the whole machine.
serve loads them once and answers every client over loopback HTTP, which is also the shape the 2026-07-28 MCP specification settled on: no session handshake, every request self-describing.
cuba-memorys serve # 127.0.0.1:8787 by default
cuba-memorys serve 127.0.0.1:9000 # or pick the addressmemory-industry serve is the same command. Point every client at it, and give each one its own Mcp-Client-Id so their sessions stay separate — without it jornada start in one window becomes the active session of the next:
{
"mcpServers": {
"memory-industry": {
"type": "http",
"url": "http://127.0.0.1:8787/mcp",
"headers": { "Mcp-Client-Id": "editor-window-1" }
}
}
}GET /health reports uptime, database reachability and the clients seen so far. CUBA_HTTP_ADDR overrides the address; CUBA_HTTP_TOKEN requires Authorization: Bearer, and is mandatory if you bind anything other than loopback — the daemon serves the entire graph with no authentication by default.
Models load in the background after the port opens, so a client that connects during startup waits on its first search instead of timing out the connection. Under stdio that timeout was how you ended up with abandoned multi-GB processes: the client gives up at 30 s but never closes stdin, so the server sat there holding every model it had loaded. Stdio now exits if no handshake arrives within CUBA_HANDSHAKE_TIMEOUT_SECS (60 s, 0 disables).
Without a model, embeddings are hash-based: deterministic, and semantically meaningless. Search still works through the lexical and BM25 branches, but nothing understands meaning.
One command installs the models and the ONNX runtime, on any OS — no shell scripts, no manual ORT_DYLIB_PATH:
cuba-memorys models all # embeddings + NLI + reranker + runtime
cuba-memorys models embed # just the embeddings model (~113 MB)
cuba-memorys models all --gpu # GPU runtime, if you have one
cuba-memorys doctor # confirms what loadedEverything lands in ~/.cache/cuba-memorys/ and is found automatically. models downloads only when you run it — nothing is fetched behind your back.
bge-m3 (1024-d) is better than e5-small for Spanish, though the size of the gap is no longer claimed (the old +21 nDCG figure came from a broken benchmark). It needs a dimension migration (scripts/migrate-embedding-dim.sh 1024) and CUBA_EMBED_MODEL=bge-m3 CUBA_POOLING=cls.
CUBA_MODE is a preset that sets the database, the models, and outbound network together, so you pick one name instead of lining up a dozen env vars:
| Database | Capabilities | Network out |
| Docker on this machine | embeddings + NLI as installed | none |
| shared managed Postgres (set | + provenance per node, real-time sync between machines | none |
| whatever | + reranker (GPU if present) + |
|
Two machines, one memory. Point both at the same managed Postgres (Neon or Supabase free tier both have pgvector and fit the 36 MB corpus many times over), give each a name with CUBA_NODE_NAME, and CUBA_MODE=red. What one writes, the other reads; every memory records which machine it came from (origin_node). Without a shared database, cuba_sync does the same job through a git repository — see Sync between machines. Do not expose your own Postgres port to the internet — use a managed provider's TLS, or a private network like Tailscale.
Real isolation when you share. A shared database is where row-level security stops being decorative. Run cuba-memorys secure once (as the admin role) to create a non-superuser cuba_app with RLS and append-only audit actually enforced, then point the runtime at it with CUBA_SKIP_MIGRATIONS=1. cuba-memorys doctor reports whether the runtime role is a superuser (which bypasses all of it) or not.
Maximum capability. CUBA_MODE=completo turns on the cross-encoder reranker (+93% nDCG) and cuba_docs. The reranker no longer needs that mode when the machine can actually run it: a build with a GPU provider that finds a working device turns it on by itself, because that is where it fits its budget. On CPU it stays off by default — the table below is why — and cuba-memorys doctor says which of the three reasons applies. Asking for rerank: true in the call still overrides everything. On CPU faro time-boxes it and falls back to the RRF ranking (CUBA_RERANK_TIMEOUT_SECS, default 20 s), so a slow machine still answers. GPU binaries ship with CUDA (NVIDIA) and, on Windows, DirectML (any GPU) — cuba-memorys models runtime --gpu fetches the accelerated runtime.
Fetching the GPU runtime is only half of it: the binary itself has to be built with --features cuda, or gpu::configure() registers no provider and the reranker runs on CPU. That is not a hypothetical — it is what a 50-candidate rerank costs on a 6-core laptop, measured with cargo run --release --example rerank_bench:
build | 50 candidates, mixed lengths | inside the 20 s budget? |
CPU, | 106,9 s | no — scores computed, then discarded |
CPU, physical cores | 61,0 s | no |
| 4,1 s | yes |
Same ranking either way — CPU and GPU agree candidate for candidate, differing only in the fifth decimal of the score. Run rerank_bench on any machine to see whether the reranker fits its budget there or is silently throwing the work away, and cuba-memorys doctor reports whether this build has a GPU provider at all.
This section used to say "every model quietly runs on CPU", implying all three would run on the GPU once you built with --features cuda. Only the reranker ever did. The embedder ships dynamically quantised to INT8, which means 96 DynamicQuantizeLinear feeding 144 MatMulInteger — and the CUDA provider registers no kernel for either, so ONNX Runtime partitions them onto the CPU no matter what you build. Registering CUDA for that session bought nothing and cost a VRAM arena the model never computed in: 374 MiB held while all 544 MB of weights sat in host RAM. The NLI cross-encoder has the opposite problem — it is FP32 and stuck there, because mDeBERTa is documented upstream as not supporting FP16 and the INT8 build returns confident false entailments.
So placement is now decided per model rather than once per process, and only the reranker asks for the GPU. On the 6 GB card this was measured on, the daemon went from 5228 MiB of VRAM to 2950 MiB while searching, and 0 while idle — and down to 1460 MiB with the two opt-in steps in Footprint below.
Individual env vars (CUBA_DOCS, CUBA_RERANKER_PATH, …) always override the preset.
Related MCP server: Mnemo Cortex
Most memory servers are a key-value store with an embedding bolted on. This one models four kinds of memory, because the psychology literature says they are four different things and they decay differently:
What it holds | How it strengthens | |
Semantic | Facts about entities — "all endpoints are async" | Access (Hebbian/BCM, Oja 1982) |
Episodic | Events with actors and time — "we shipped v2 on Tuesday" | Power-law decay (Tulving 1972, Wixted 2004) |
Procedural | How things are done here — recipes with a track record | Success, not access (ACT-R) |
Working | Scratch notes bound to the current session | Cleared with the session |
Procedural memory is a separate table rather than a ninth observation type for a specific reason: ACT-R separates declarative memory (reinforced by access) from procedural (reinforced by success). As an observation, a recipe consulted constantly because it keeps failing would climb in importance. It is ranked by Wilson lower bound, so 1/1 successes scores 0.21 and 47/50 scores 0.84 — a lucky first try does not outrank a track record.
Hybrid RRF fusion (k=60, Cormack 2009) over three signals — full-text, BM25 (ts_rank_cd), and pgvector HNSW — with entropy-routed weighting that shifts from keyword-heavy to semantic as the query's Shannon entropy rises.
Answers arrive in compact by default: abbreviated keys, content truncated at 1200 chars. 30% fewer tokens, and a slightly better nDCG — measured on the 221 id-scored questions, +0.0090 with a paired 95% interval of [+0.0024, +0.0166]. The format genuinely cannot change which documents rank; what it changes is how many of them survive the response token budget before they are scored. Verbose at the default 5000-token budget weighs 5286 tokens and loses its tail; compact weighs 3723 and keeps it. Pass "format": "verbose" for the full per-branch score breakdown.
cuba_faro mode=verify checks a claim against what is stored. It used to score claims by cosine similarity to the retrieved evidence, and that does not work — similarity measures what a text is about, not what it asserts. "cuba-memorys is written in Rust" and "…in Java" are nearly the same vector. Measured on the live corpus, the false claim scored 0.61 and the true one 0.59.
Entailment is a different question from similarity, and it needs something that reads. A local cross-encoder now judges each piece of evidence — supports / contradicts / unrelated — and confidence is derived from the verdicts, each weighted by that evidence's similarity. Same corpus, after:
Claim | Before (cosine) | Now |
"written in Rust" (true) | 0.59 | 0.995 · verified |
"written in Java" (false) | 0.61 | 0.00 · contradicted |
"the best paella uses saffron" (unrelated) | 0.45, with 10 "evidence" items | 0.00 · unknown, no evidence |
Being on-topic is not support, and unrelated counts for neither side.
The judge is mDeBERTa-v3-base-xnli running locally on ONNX: 100 languages, ~50 ms per verdict, no API key, no network, no cost. That matters here — about 75% of this corpus is Spanish, and the English-only NLI models everyone reaches for first would have silently failed on three memories out of four. Install it with cuba-memorys models nli; cuba-memorys doctor will tell you whether it loaded.
Without it, verification falls back to an LLM (your MCP client's own model via sampling, a local claude CLI, or the Anthropic API) — and with none of those, to an honest unknown rather than an invented verdict.
Two things it will not do. It will not confirm a claim on weak evidence: entailment must clear 0.80 while contradiction needs only 0.60, because confirming a false memory and doubting a true one are not errors of equal cost. And when it cannot tell, it says so instead of returning whichever number came out largest — an argmax over a 3-way head will happily publish supports for a claim that is flatly false, and did.
The out-of-distribution gate rejects queries the corpus cannot answer. The threshold is not a magic constant: Ledoit-Wolf covariance shrinkage plus a conformal quantile, calibrated against your own corpus with cuba-memorys calibrate --dataset <questions.jsonl> --apply and persisted (the dataset is required — without it the command refuses). (The theoretical χ² threshold rejected 100% of answerable queries. Distribution-free calibration is not a nicety here.)
CUBA_MODE=red puts two machines on one database. cuba_sync is the other route, for machines that never see each other: the graph is written out as JSON you can commit, and read back on the other side.
cuba-memorys sync export # write the bundle under .cuba-memorys/
cuba-memorys sync import # read one back in
cuba-memorys sync diff # entities on disk vs entities in the database
cuba-memorys sync status # which bundles this machine has already imported
cuba-memorys hook install # export after every commit, import after every checkoutThe same four actions are cuba_sync action=export|import|diff|status. A bundle is one JSON file per entity with its observations inside, plus episodes/YYYY-MM/, errors/, decisions/, relations.json, projects.json, tombstones.json and a manifest.json — the active project and anything not bound to a project, unless you pass --scope all. Embeddings stay out unless you ask for them (--with-embeddings): they are most of the bytes and they can be recomputed. A bundle imports once, and the manifest hash covers the contents of every file in it — so an unchanged bundle is skipped, and a hand-edited entity file is a new bundle rather than a silent no-op.
A deletion travels now, and stops where it would take something with it. Deleting a row records a tombstone, and the receiving side deletes exactly the ids that were named. Before this, a delete was not slow to arrive — it was undone: the peer still had the row, exported it, and it came back on the next round trip. The entity tombstone is the dangerous one, because deleting an entity cascades to everything hanging off it. It is applied only when this machine has no observations or episodes under that entity that the sender never named; otherwise it is withheld and reported in tombstones_withheld. A tombstone for an entity with three children there must not take three hundred here.
And a bundle cannot quietly wipe you. If the tombstones in it would delete at least 25 rows and more than 10% of the observations on this machine, the import refuses and asks for confirm=true. A remote wipe and a large legitimate cleanup look identical; the only difference is whether you meant it. The floor matters as much as the ratio: on a database with a single observation a pure percentage demanded confirmation to delete that one, and a guard that trips on ordinary curation is one everybody learns to pass confirm=true through — and then it guards nothing.
conflict=merge does not merge content, and now says so. merge and skip are one policy: rows that are missing here arrive, and where a row already exists with different content, the one that was here first wins and the incoming text is dropped. What changed is the silence — the import counts those rows and reports them as diverged, with their ids and a note saying what it did. conflict=overwrite takes the incoming version and keeps the one it replaced in previous_versions (the newest 20 are kept), and clears the embedding when the content changed, so a row stops being retrievable by a meaning it no longer carries.
Counters do merge, under either policy. importance and access_count on an entity, and strength on a relation, are not values one side copies from the other: each machine grows its own, from its own reinforcement and its own traversals. The higher of the two wins, which is idempotent — importing the same bundle twice inflates nothing. (Summing would be more faithful to "both machines counted", and would double on a re-import, so it loses to a rule that cannot corrupt the number.)
Which machine is which. Each installation generates a uuid in its own database on first migration — one row, stable across restarts, unique by construction — and the manifest carries it, so a bundle can say which machine produced it. CUBA_NODE_NAME keeps meaning what it always meant: a human-readable label stored in origin_node. It is not the identity and could not be one, because two machines both called pop-os is the likeliest outcome there is.
The clock ticks for what a peer needs, and stays still for local noise. An observation's version advances when its content, type, trust, evidence level or tags actually change, and for nothing else. Decay moves importance and last_accessed; reembed replaces vectors. If either woke the clock, every export would ship a graph that had not changed and the two machines would never stop talking to each other about nothing. Rewriting a row with the same content does not tick it either, so an idempotent re-import does not invent a conflict out of agreement.
Older bundles still import. The format is SCHEMA_VERSION 2: version, updated_at, origin_node, previous_versions, evidence, verification and trust travel now, because a conflict rule that compares clocks needs the clock to be in the file. Bundles written before that still import — every new field defaults, and a v1 observation lands as asserted, which is the honest reading of a file that never claimed anything stronger.
Anything in an incoming bundle that looks like a credential is stored quarantined instead of trusted — withheld from cuba_faro and cuba_expediente until you promote it with cuba_eco — because an import reads JSON out of a repository anyone with push access can write to.
A peer that only ever reads. CUBA_PEER_TOKEN reaches five more verbs and nothing else. pull returns the bundle in the response instead of writing it anywhere, paged by file (limit, offset) up to a 3 MB budget per page — abort if manifest_hash changes between pages, because that means this node was written to mid-transfer and the pages describe two different states. notify is the one write a peer token may make: a short summary (at most 2000 characters) saying the other machine learned something, tagged with node_id/node_name, surfaces at the next cuba_jornada start and in status, and closes itself when a bundle carrying its manifest_hash is imported — it never enters the graph itself. conflicts lists the rows two machines disagree about with both texts, and resolve id=… keep=ours|theirs|both closes one: keep=both (the default) keeps this machine's text current and files the other in previous_versions, discarding nothing, while theirs also clears the embedding because it described text that is no longer here. fetch is the other half and runs on the local machine: it pages a peer's pull over HTTP, lands the files, imports them with the same validation as any bundle, and records the peer's manifest hash so the next fetch stops before opening a transaction when nothing changed. Embeddings are omitted by default on export and included by default on pull — a peer that receives text without vectors cannot search what it just received until it re-embeds, which on a machine without a GPU is slow and sequential — and a bundle whose model or dimension does not match this machine is refused rather than silently filling the index with vectors from another space.
$ cuba-memorys doctor
[ ok ] migrations 49 aplicadas, ninguna dirty
[ ok ] embedding_dim runtime 1024-d == columna vector(1024)
[ ok ] runtime_role 'cuba_app' sin superuser — RLS y audit efectivos
[ warn ] binary_freshness 4 proceso(s) MCP corren un binario más viejo que el de discoThis exists because the failure mode of a hybrid search engine is not a crash — it is a vector branch dying and the search quietly becoming lexical, with no symptom. The server now refuses to start on an embedding-dimension mismatch, and search sets degraded: true in the response when a branch fails.
Twenty-three commands. memory-industry --help lists them all.
| One shared HTTP daemon for every client, instead of one process (and one copy of the models) per editor window |
| Read and write the brain from a shell |
| A self-contained HTML view of what is in there |
| Health check: schema, dimensions, config coherence, stale processes |
| Session-start context injection — wire it with |
| Re-encode what needs it (default: only stale rows, not all of them) |
| Recompute the abstention threshold from your corpus |
| Auto-link entities by NPMI co-occurrence |
| Entities that are the same thing under different names — see below |
| Write the graph out as committable JSON and read it back on another machine — see Sync between machines. |
| Export procedures as Claude Code Skills |
| Retrieval benchmark — nDCG@10 with confidence intervals, MRR, recall, token cost |
| Wire this into your MCP clients; |
dedupe — because a different string is a different entitycuba_alma create inserts with ON CONFLICT (name). So one project fragments into Mapupita-Web, Mapupitta-Web (typo), Mapupita Web, mapupita… and searching one finds none of the others. On a real 266-entity graph, 158 of them (59%) had not a single relation — for PageRank and multi-hop retrieval, they did not exist.
What decides a merge is not the embedding centroid. That was the obvious idea and it is wrong: M-Codes Reference Guide and G-Codes Reference Guide sit at 0.811 cosine between centroids. On a corpus about one domain, centroid similarity measures the domain, not the entity — a 0.80 threshold would have merged two different CNC guides, irreversibly.
So --apply merges only what is provable (identical after normalizing case and separators). Typos and near-matches are shown, and judged one at a time with --judge. The old name is written to brain_entity_aliases, so nothing is lost: looking it up still resolves.
Named after Cuban culture. cuba-memorys advertises all of them, or set CUBA_TOOL_PROFILE=lean to advertise an everyday core of 13 plus cuba_tools + cuba_call — 15 of 31, a 49% smaller catalogue with zero functions lost, the rest reachable on demand.
Knowledge graph — cuba_alma (entities) · cuba_cronica (observations, episodes, timeline) · cuba_puente (typed relations, traversal, link prediction) · cuba_ingesta (bulk import)
Search — cuba_faro (hybrid RRF, verification, MMR diversification, OOD abstention)
Error memory — cuba_alarma (report) · cuba_remedio (resolve) · cuba_expediente (search past errors; warns if an approach failed before)
Sessions & decisions — cuba_jornada (session lifecycle, diff) · cuba_decreto (architecture decisions) · cuba_proyecto (per-project isolation) · cuba_pre_compact (survive /compact)
Procedural — cuba_receta (recipes ranked by Wilson lower bound)
Cognition — cuba_reflexion (gap detection) · cuba_hipotesis (abductive inference) · cuba_contradiccion (semantic conflicts) · cuba_juez (LLM judge) · cuba_centinela (prospective triggers) · cuba_calibrar (Bayesian calibration, source credibility)
Maintenance — cuba_zafra (decay, prune, merge, PageRank, Leiden communities) · cuba_eco (RLHF feedback) · cuba_vigia (health, drift, centrality) · cuba_forget (GDPR erasure) · cuba_archivo (CFR-21 hash-chain audit log) · cuba_pizarra (working memory) · cuba_sync (git-friendly export/import between machines, with propagated deletions and a remote-wipe guard)
Meta — cuba_tools (discover) · cuba_call (invoke)
Variable | Default | What it does |
|
|
|
|
| A human-readable label for this machine, written into |
| auto (Docker) | PostgreSQL connection. Set it (external + TLS) for |
| auto ( | Semantic embeddings. |
|
| Log level, read by |
|
| Set to |
|
| Instruction prefixes prepended before tokenising. E5 was trained with them; |
|
| Content longer than the threshold is split into chunks of this many characters (200-char overlap). |
|
| Permits on the semaphore around the ONNX embedding session. Sized once, on first use |
|
|
|
|
|
|
|
| The CLI the offline judge shells out to, and the model it asks for. |
|
| Budget for one judgement, CLI and API alike. Anything that does not parse as an integer leaves the default |
|
| Candidate pairs |
| unset | Named cloud/local preset ( |
| unset | OpenAI-compatible |
| unset | Bearer for that base. Vendor fallthroughs: |
|
| Local entailment model ( |
| off | Send claims the NLI could not decide to an LLM. Buys recall, costs ~12 s each |
|
| Optional graph projection: |
| unset | Graph endpoint ( |
|
| Falkor/RedisGraph graph key. The gate keeps this unset/ |
|
| Extra RRF leg for factoid queries that mention an entity. Set |
|
| Cross-encoder reranker (+93% nDCG); on CPU it falls back to RRF past the budget |
| physical cores (2 on GPU) | ONNX threads per rerank inference. Past the physical core count it gets slower — measure with |
| on (off under fixed shape) | Batch similar-length candidates so padding does not become compute. Scores are unchanged |
|
| Candidates per forward pass. Under fixed shapes every batch pads to 512 tokens, making this the main lever on the GPU arena: |
|
| Permits on the semaphore around the reranker session. The session is a mutex, so raising this queues callers rather than parallelising them |
|
| Rounds the padded sequence length up to a multiple of this. Only |
| on when the reranker runs on GPU | Pads every batch to the same 512-token shape. |
|
| Per-model placement. Only the reranker gains from a GPU; the INT8 embedder cannot use one and the FP32 NLI is not worth the VRAM. Set to |
|
| Caps the CUDA arena and pins |
| half the logical cores, max 4 | ONNX threads per embedding. Measured on 12 threads: 1 → 94,8 ms, 2 → 52,3 ms, 4 → 35,8 ms, 6 → 68,1 ms, 12 → 155,4 ms per query |
|
| Exit after this long with no request from any client. Pairs with a systemd |
| off | Load the cross-encoder at startup instead of on its first batch. Off, a cold start costs 0,027 s instead of 11 s and holds no VRAM until something actually reranks |
|
| Address for |
| unset | Set to |
| unset | Without it, |
| unset | Default address of the other daemon for |
| unset | A second bearer token for another machine that syncs with this one. It reaches only the sync verbs — never |
|
| stdio exits if no MCP handshake arrives, instead of holding the models for a client that gave up. |
|
| Ceiling on one tool call. It is also the budget the LLM extraction inside |
| off |
|
|
| Compact truncation (measured knee) |
| calibrated | Override the abstention threshold |
| on | Mirror observations into |
| unset → | HMAC key for the |
| on | After migrations the pool reconnects as the unprivileged |
| unset (filter on) |
|
| off |
|
|
| Host address the managed Postgres container publishes its port on. Anything but loopback exposes the database to the network |
|
| Per-connection planner settings for the pool. Accepted ranges are |
| on |
|
|
| Free disk the gate demands before it compiles anything. Below it, it refuses to start and says so. A run on a 98%-full partition died as |
|
| Free disk under which the gate sweeps build artifacts before running. cargo never removes the binaries of earlier compilations — every edit makes a new hash and the old one stays — so |
|
| How old an artifact has to be for that sweep to take it. By age and not by size on purpose: anything this run needs was written today |
|
| How long after start-up the first REM consolidation runs. It used to be |
|
| Entities the REM cycle runs a relation scan over per pass. |
|
| Budget for one entity's relation scan |
|
| Observations the REM cycle runs |
|
| Observations without an embedding that the REM cycle backfills per pass. |
| unset → | Root for |
|
| Where destructive CLI commands write their undo snapshots |
A memory server is infrastructure: it is running when you are not using it. On the 6 GB laptop GPU this was measured on, it used to hold 5228 MiB of VRAM from boot — 93% of the card — and other GPU programs stopped being able to start. The NVIDIA driver was returning NV_ERR_NO_MEMORY on channel creation, which is what a game or a GPU-accelerated terminal fails on.
Two of the numbers below ship as defaults; two need a line of config, and this table keeps them apart rather than quoting the best one as if it came free.
before | 0.20.0 defaults |
| + fused artifact | |
VRAM while searching | 5228 MiB | 2950 MiB | 2364 MiB | 1460 MiB |
VRAM idle | 5228 MiB | 0 — the process is gone | 0 | 0 |
Cold start to answering | 11,1 s | 0,027 s | 0,027 s | 0,027 s |
Search, warm | 5,90 s | 5,25 s | 3,73 s | 1,70 s |
Embedding one query | 52,3 ms | 35,8 ms | 35,8 ms | 35,8 ms |
Everything in the defaults column is code that ships. CUBA_RERANK_CHUNK=4 is one env var. The last column additionally needs the rebuilt reranker described below. None of it removed a feature.
Four things got it there:
Placement per model, not per process. Only the reranker is accelerated by a GPU — the INT8 embedder cannot be, and the FP32 NLI is not worth a gigabyte of VRAM for a judge that runs occasionally and tolerates 150-400 ms. The arena cap is per session, so three sessions asking for CUDA on a 6 GB card is a 3× overcommit waiting to fail.
A CUDA arena that stops doubling. ArenaExtendStrategy::NextPowerOfTwo is the ONNX Runtime default and it reserves in powers of two rather than what the session asked for.
The reranker loads on its first batch. Under socket activation the daemon starts far more often than it reranks, and plenty of those starts only ever answer a save.
A daemon that is not running when nobody is asking. CUBA_IDLE_SHUTDOWN_SECS plus a systemd .socket unit: the socket owns the port, the daemon starts on the first real connection and exits after the idle window. It shuts down through the normal path — serve returns, the background drain flushes in-flight embedding writes, sqlx closes its pool — because exiting the process directly loses those writes silently.
# ~/.config/systemd/user/cuba-memorys.socket
[Socket]
ListenStream=127.0.0.1:8787
Accept=no
[Install]
WantedBy=default.target# ~/.config/systemd/user/cuba-memorys.service — no [Install]; the socket starts it
[Unit]
Requires=cuba-memorys.socket
[Service]
Type=exec
ExecStart=%h/.local/bin/cuba-memorys-daemon serve 127.0.0.1:8787
# An idle shutdown exits 0 — Restart=always would bounce it straight back up.
Restart=on-failure
Environment=CUBA_IDLE_SHUTDOWN_SECS=1200
Environment=CUBA_EMBED_DEVICE=cpu
Environment=CUBA_RERANK_DEVICE=gpu
Environment=CUBA_NLI_DEVICE=cpuBoth units ship in packaging/. ExecStart has to name the binary you actually installed — command -v cuba-memorys — and the -daemon suffix above is only the convention for keeping a GPU build beside a stock one. A wrong path here fails as status=203/EXEC.
serve adopts the socket systemd passes as fd 3 (LISTEN_FDS), so the port is held while the daemon is not running and no client sees a refused connection.
The unit must also bind loopback. With socket activation the .socket unit's ListenStream decides the address and CUBA_HTTP_ADDR is ignored, so serve checks the address of the socket it is handed and refuses a routable one unless CUBA_HTTP_TOKEN is set.
VRAM was only half of it. The weights also live in host memory, and that appetite used to be fixed no matter what the machine had. Measured with cargo run --release --features cuda --example mem_bench, daemon stopped, on the 6 GB laptop GPU:
stage | added RSS | VRAM | load |
process start | 5,5 MiB | 0 | — |
+ PostgreSQL pool | +1,3 MiB | 0 | — |
+ embedder (bge-m3, CPU) | +862,0 MiB | 0 | 1,72 s |
+ reranker (fused FP16, GPU) | +1034,7 MiB | 1460 MiB | 3,73 s |
+ OOD fit (n=1811, d=1024) | +37,4 MiB | 0 | 11,45 s |
peak | 2677 MiB | 1460 MiB |
Resident settles near 1941 MiB; the peak is 2677 because loading a 1,1 GB ONNX file costs transient memory on top of the weights it leaves behind. The peak is the number that has to fit, not the steady state.
On the machine this was measured on that is fine. On a 4 GB laptop it is not, and under a systemd unit capped at MemoryHigh=4500M it has been seen paging 2,56 GiB to swap — MemoryHigh does not kill, it reclaims, and reclaiming is paging.
Two traps worth knowing if you re-run this. mem_bench attributes VRAM to its own PID via nvidia-smi --query-compute-apps, because reading memory.used charges you for every other process on the card — that is how a first attempt showed 3590 MiB "at process start" that belonged to a game and a desktop shell. And run it with the daemon's own environment: with CUBA_RERANKER_PATH unset it silently loads the unfused artifact and the warm-up goes from 3,7 s to 131 s on CPU.
So the daemon now reads the machine at startup and picks a level. Nothing is invented for this: all three degradations already existed and are tested.
level | models loaded | host RAM | what you give up |
minimal | none | ~220 MiB | semantic search. BM25 + full-text + trigram still answer |
lean | embedder | ~1,1 GiB | reranking and local entailment |
standard | embedder + reranker | ~2,2 GiB | the NLI judge, which drops to its own fallback ladder |
full | all three | ~3,3 GiB | nothing |
How the level is chosen. The budget is min(cgroup limit, system available) − 768 MiB of headroom, and the cgroup has to win. On this machine /proc/meminfo reports 7,16 GB available while the daemon's cgroup caps it at 4,39 GiB — believing /proc would load 2,6 GiB of weights against a limit where the kernel already starts paging. The reader walks from the cgroup root down to the leaf and takes the tightest memory.max or memory.high it finds, because the limit is usually set on an ancestor.
Models are then fitted in order of measured value: the embedder first, then the reranker (+93% nDCG, so it outranks the judge), then NLI.
The plan can only take away. Every knob is capped at the value the daemon already used, so on a machine with room the level is full and nothing changes. Degradation only goes downward.
You always win. Any of these set by hand is left untouched — the regulator fills gaps, it does not overwrite decisions:
CUBA_EMBED_INTRA_THREADS CUBA_RERANK_INTRA_THREADS CUBA_NLI_INTRA_THREADS
CUBA_RERANK_CHUNK CUBA_GPU_MEM_LIMIT_MB CUBA_OOD_FIT_LIMIT
CUBA_DB_MAX_CONNECTIONSTo force a model off regardless of the budget, point it at a path that does not exist — CUBA_RERANKER_PATH=/nonexistent or CUBA_NLI_PATH=/nonexistent. That is the same mechanism the regulator itself uses.
To see what it decided, run cuba-memorys doctor: it reports the reading and the resulting plan, and warns when the level falls to minimal. The plan is also logged at startup with the full machine reading behind it.
The published bge-reranker-v2-m3 ONNX is converted to FP16 before any graph fusion, which leaves 785 Cast nodes threaded through it. ONNX Runtime claws some of that back at load time (2023 → 897 nodes, 49 SkipLayerNormalization), but it cannot fuse Gelu and it repeats the work on every cold start. Rebuilding from the FP32 export and fusing first:
python -m onnxruntime.transformers.optimizer \
--input model.onnx --output model.onnx \
--model_type bert --num_heads 16 --hidden_size 1024 \
--opt_level 1 --use_gpu --float16VRAM | search p50 | load + warm | |
shipped FP16 | 2364 MiB | 3,73 s | 22,8 s |
fused, then FP16 | 1460 MiB | 1,70 s | 10,2 s |
Identical top-10 order on a real search, fused_score differing by at most 0,0029; on synthetic logits at the real batch shapes, Pearson ≥ 0,9997 with the same ranking in every batch.
Attention does not fuse, and that is not fixable here. is_fully_optimized: Attention (or MultiHeadAttention) not fused, at opt_level 0, 1, 2 and 99, on both the FP16 artifact and the clean FP32 one. The export builds its Q/K/V reshapes from dynamic shape subgraphs (Shape → Gather → Unsqueeze → Concat → Reshape) and AttentionFusion needs a Reshape with a constant shape to read num_heads and head_size off it. So flash/efficient attention stays unavailable without a re-export using static shapes — worth knowing before anyone spends an afternoon on it.
Until v0.12 this section carried a line reading "every number here is measured rather than assumed", and every number in it was wrong. The benchmark was broken in three ways, and finding out cost two published conclusions.
It had ten queries. A 95% interval of roughly ±0.12; the smallest effect it could detect was ~0.25 nDCG. Any claim about a smaller difference was noise wearing a decimal point.
Relevance was judged by substring match. A result counted as correct if its text merely contained a marker word — so every observation mentioning "postgres" scored as a right answer to any question about postgres, whether it answered anything or not. That measures keyword presence, not retrieval, and it tilts the whole benchmark toward the lexical branch and against the vector one.
nDCG normalized against what was retrieved, not what exists. With 5 relevant documents in the corpus and 2 found, the "ideal" ranking was taken to be those 2 — so a system that missed 60% of the answer scored a perfect 1.0. (And R@10 = 3.125 shipped in this file. Recall is a proportion.)
The real number is not 0.894. On 221 id-scored queries it is nDCG@10 = 0.50 [95% CI 0.44–0.56]. The system did not get worse. It was never 0.894.
"The cross-encoder reranker earns nothing" — it had never run. Three bugs in series: faro wrapped the call in if let Ok(..) and dropped the error; it fed token_type_ids to a model that is XLM-RoBERTa and has none; it read f16 logits as f32. The output was "bit for bit identical" to no reranking not because reranking changed nothing, but because it never happened. Fixed; being measured properly now.
Associative retrieval does degrade — but the old evidence (−0.03 at n=10) could not have shown it. On the new dataset with a paired bootstrap (the correct test: same queries in both arms), the interval is [−0.051, −0.018] and never touches zero. It improves 0 queries and hurts 23. The decision was right; the reasoning was not. The power was never in more data — it was in using the right test.
| −30% tokens, nDCG +0.0090 (paired 95% CI [+0.0024, +0.0166], n=191). The earlier "exactly 0.0000" was measured with a harness that let the 5000-token response budget truncate the ranking before scoring it: verbose lost its tail, compact did not. The old "−40%" came from the broken benchmark. |
Conformal abstention | 100% of out-of-distribution queries caught, 0% false abstentions. |
| 15 tools of 31, −49% catalogue, zero functions lost. |
bge-m3 over e5-small | Direction almost certainly right; the +21.2 nDCG figure is withdrawn — it came from the broken benchmark and re-establishing it would mean re-embedding the corpus twice. |
The benchmark itself | 221 queries (was 10), relevance by document id, bootstrap confidence intervals, and the minimum detectable effect printed beside every result — so nobody reads a 3-point difference as a finding again. |
Algorithm | Reference |
RRF fusion (k=60) | Cormack et al. (2009) |
Hebbian + BCM metaplasticity | Oja (1982); Bienenstock, Cooper & Munro (1982) |
Conformal prediction | Vovk (2005); Angelopoulos & Bates (2023) |
Ledoit-Wolf covariance shrinkage | Ledoit & Wolf (2004) |
Mahalanobis OOD detection | Lee et al. (NeurIPS 2018) |
Wilson score interval | Wilson (1927) |
Declarative vs procedural memory | Anderson & Lebiere (ACT-R) |
Testing effect | Karpicke & Roediger (Science 2008) |
Power-law forgetting | Wixted (2004) |
Episodic vs semantic memory | Tulving (1972) |
PageRank · Leiden · Brandes | Brin & Page (1998); Traag et al. (2019); Brandes (2001) |
NPMI co-occurrence | Bouma (2009) |
MMR diversification | Carbonell & Goldstein (1998) |
Contextual Retrieval | Anthropic (2024) |
Prompt-injection spotlighting | Hines et al. (2024) |
git clone https://github.com/LeandroPG19/Memorys.git
cd Memorys/rust && cargo build --release
# On an NVIDIA machine, build this way instead — without it the reranker spends
# its whole budget for a ranking that gets discarded. It accelerates the
# reranker only; see Footprint for why the other two models stay on the CPU.
cargo build --release --features docs,cuda
./scripts/demo.sh # runs on a throwaway Postgres it removes on exit
./scripts/merge-gate.sh # local CI 100% — sole merge judge (see docs/gate.md)
cargo run --release --example rerank_bench # does the reranker fit its budget here?Publishing is tag-driven: v* on LeandroPG19/Memorys triggers GitHub Release binaries (5 platforms), PyPI wheels (memory-industry and the cuba-memorys alias), npm (memory-industry and the cuba-memorys alias), and the MCP Registry (io.github.LeandroPG19/memory-industry). A test pins Cargo.toml, package.json, pyproject.toml and server.json so those versions cannot drift.
Apache-2.0 — use it, modify it, ship it, sell it, embed it in a closed product. No copyleft obligation. The licence also grants patent rights explicitly, which is the part legal departments care about.
Leandro Perez G. — @LeandroPG19
Report errors immediately. Auto-detects patterns (≥3 similar = warning). Hebbian: similar errors get boosted for easier retrieval.
| Name | Required | Description | Default |
|---|---|---|---|
| context | No | Context: {file, function, stack_trace, line} | |
| project | No | Project name (default: 'default') | |
| error_type | Yes | Error category: TypeError, ConnectionError, etc. | |
| allow_secret | No | Refused when the text looks like a live credential (token, password, URL with embedded creds). Set true only for a false match — the text is then stored verbatim, in clear, and reachable by search, export and every client. | |
| error_message | Yes | Full error message |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does disclose non-obvious behavior: clustering of similar errors into warnings at ≥3 occurrences and reinforcement of similar errors for retrieval. It still omits whether this is a persistent write, what auth/permissions are needed, and what the call returns.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three terse fragments, action front-loaded with behavioral detail trailing. No wasted words, though the telegraphic style leaves gaps that fuller sentences could close.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 5-parameter mutation tool with no annotations and no output schema, the description covers the reporting act and emergent clustering behavior but leaves persistence, permissions, and return behavior unstated.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the nested context object is documented, so the schema carries the parameter load. The description adds no field-level meaning of its own; baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a clear verb+resource ('Report errors') and adds two behavioral traits (pattern auto-detection, Hebbian boosting). However, it never distinguishes itself from its obvious sibling memory_alarma, which an agent must choose between.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Report errors immediately' gives a weak timing hint but no when-to-use vs. memory_alarma, no prerequisites, and no exclusion conditions. The agent gets no routing guidance among the many cuba_*/memory_* siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
CRUD knowledge graph entities (concepts, projects, technologies, patterns, people). Auto-boosts neighbors on access. For transient info use cuba_cronica instead.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Entity name (unique identifier) | |
| action | Yes | Operation to perform | |
| new_name | No | New name for update action | |
| entity_type | No | Type: concept, project, technology, person, pattern, config |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the full behavioral burden. It goes beyond CRUD by stating 'Auto-boosts neighbors on access,' which is a notable behavioral trait. However, it does not detail what happens on delete or any authorization needs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences: first states purpose and resource, second adds behavioral trait and sibling alternative. Every sentence earns its place, with no wasted words. Front-loaded with key information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description could mention what the tool returns (e.g., the entity object). However, for a CRUD tool with clear input schema, the description is largely complete for invocation. The auto-boost behavior is a nice addition.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds context that entity_type can be one of the listed types, but for most properties, the schema's descriptions are already sufficient. The description does not add significant new meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'CRUD knowledge graph entities (concepts, projects, technologies, patterns, people)', which specifies the verb (CRUD) and resource (knowledge graph entities). It distinguishes itself from sibling cuba_cronica by noting that tool is for transient info.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly provides a usage guideline: 'For transient info use cuba_cronica instead.' This tells the agent when not to use this tool and what alternative to choose, which is strong guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tamper-evident audit log: append-only, SHA-256 hash chain, UPDATE/DELETE blocked at the PostgreSQL trigger level.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Limit for verify/tail (default 10000 / 20) | |
| action | Yes | append: add an event. verify: walk the hash chain and detect tampering. tail: read recent events. | |
| payload | No | Arbitrary JSON payload (for append) | |
| event_action | No | Event type (for append) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral burden and does disclose key traits: append-only, SHA-256 hash chain, and UPDATE/DELETE blocked at the PostgreSQL trigger level. It does not cover auth requirements or rate limits, but it gives useful tamper-evidence context beyond the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single compact sentence that front-loads the tool's core property. It wastes no words, though it could have used one clause to name the actions.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The schema fully describes the four parameters and action enum, but there is no output schema and no annotations. The description explains the audit-log guarantees but omits what each action returns and any permission or operational constraints, leaving it only minimally complete for a multi-action tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the enum actions, payload, event_action, and limit are already well documented in the schema. The description adds no additional parameter meaning, which is the baseline expectation when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states what the resource is (a tamper-evident audit log) but not what the tool actually does as a command. It does not mention the append/verify/tail operations, so an agent must open the schema to learn the tool's verbs, and it does not distinguish this tool from the sibling memory_archivo.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives such as memory_archivo or the other cuba/memory siblings. The description gives no conditions, prerequisites, or routing advice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Shared versioned artifacts between agents on the same daemon (and peers). put requires base_version (optimistic concurrency); lock is a short lease. Alias: memory_artifact.
| Name | Required | Description | Default |
|---|---|---|---|
| find | No | patch: substring to replace once | |
| path | No | Logical path, e.g. notes/plan.md | |
| limit | No | list limit | |
| action | Yes | Artifact operation | |
| prefix | No | list: path prefix filter | |
| content | No | Full content for put | |
| replace | No | patch: replacement | |
| ttl_seconds | No | lock lease length (default 60) | |
| base_version | No | Required for concurrent-safe put; omit or 0 to create |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations, so the description carries the full burden. It does usefully disclose the optimistic-concurrency contract on put and that lock is a short lease, which is real behavioral context. However, it omits permission/auth needs, lease expiry consequences, and what patch/watch_hint/unlock actually do.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two dense sentences, front-loaded with the resource definition followed by the two sharpest behavioral caveats. No filler or redundant restatement of the schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 9-parameter, 7-action tool with no annotations and no output schema, the description explains only put and lock. The semantics of list, get, patch, unlock, and especially the non-obvious watch_hint are never touched, leaving the agent under-informed about most operating modes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents all nine parameters with enums and defaults. The description's mention of base_version and ttl/lease semantics largely restates what the schema already carries, so baseline 3 is correct.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific resource and scope: 'Shared versioned artifacts between agents on the same daemon (and peers)', plus the alias memory_artifact. An agent knows this is an artifact store, though it does not distinguish itself from any of the many sibling memory_* / cuba_* tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives narrow action-level guidance: put needs base_version for optimistic concurrency, lock is a short lease. But with seven enum actions (list/get/put/patch/lock/unlock/watch_hint), it never says when to use one versus another or versus a sibling store, leaving most routing to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Bayesian confidence calibration: track verify predictions, mark outcomes, compute P(correct|level). Closes the feedback loop between faro verify and eco correct.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results for history (default 20) | |
| action | Yes | stats/history: past predictions. resolve: mark a verify_id correct/incorrect. trust: per-source Beta(α, β) credibility, updated by resolve outcomes. metrics: Brier score + Expected Calibration Error + reliability diagram. | |
| outcome | No | Whether the verify prediction was right (for resolve) | |
| verify_id | No | Verify log UUID (for resolve) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the whole burden. It usefully discloses a side effect — that trust scores are Beta(alpha,beta) credibilities 'updated by resolve outcomes' — and distinguishes read actions (stats/history/metrics) from write actions (resolve), but says nothing about permissions, persistence, or reversibility of resolve/trust updates.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two dense sentences, purpose first, relationship second, with no filler. Every clause carries information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a four-parameter, multi-action tool with no output schema and no annotations, the description adequately conveys the workflow and what metrics/trust represent. It stops short of describing result shapes for stats/metrics, but nothing critical for correct invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the action enum already explains each mode, so the baseline is 3. The description adds little parameter detail beyond restating the calibration concept, though it does clarify the causal link between resolve and trust.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource: track predictions, mark outcomes, compute P(correct|level), and names the calibration purpose explicitly. It is clear what the tool does, but it never distinguishes itself from its sibling memory_calibrar, which appears to be the same concept in a different namespace.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description names the upstream/downstream relationship ('closes the feedback loop between faro verify and eco correct'), which implies when to use it, but gives no explicit when-to-use or when-not guidance and no distinction from memory_calibrar or cuba_eco.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Invoke any cuba-memorys tool by name — including the ones not pre-loaded in this session. Discover them first with cuba_tools (use detail='full' to see the exact arguments). Goes through the same dispatcher as a direct call, so behaviour is identical.
| Name | Required | Description | Default |
|---|---|---|---|
| args | No | The tool's own arguments, exactly as its schema declares them | |
| tool | Yes | Tool name, e.g. cuba_zafra |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses that behavior is identical to direct calls via the same dispatcher, which is helpful. However, it does not mention potential side effects, error handling for unknown tools, or permission requirements, leaving gaps in transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (two sentences), front-loaded with the core purpose, and each sentence adds value—first defines the action, second gives usage guidance and behavioral note. No extraneous words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity as a generic caller and lack of output schema, the description is fairly complete. It explains how to discover other tools and confirms identical behavior. Missing details like error messages or argument handling corner cases, but these are minor for the task.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for both 'tool' and 'args'. The description adds value by explaining that args must match the invoked tool's schema, but this is largely redundant with the schema descriptions. No additional semantic details are provided beyond what the schema already conveys.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool invokes any cuba-memorys tool by name, including those not pre-loaded, distinguishing it from the sibling tools which are specific functions. The verb 'invoke' and resource 'any tool' are specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description advises discovering tools first with cuba_tools using detail='full', providing clear context for dynamic invocation. It implicitly differentiates from direct calls by noting tools may not be pre-loaded, though it doesn't explicitly state when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Prospective memory: triggers that fire on entity access, session start, or error match. 'Remember to remind me about X when Y happens.'
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | create: define a trigger. list: show triggers. delete: remove one (trigger_id). check: evaluate now. | |
| message | No | Reminder message to surface when triggered | |
| max_fires | No | Max times to fire (default 1, -1 for unlimited) | |
| expires_at | No | ISO8601 expiration datetime | |
| trigger_id | No | Trigger UUID (for delete) | |
| allow_secret | No | Refused when the text looks like a live credential (token, password, URL with embedded creds). Set true only for a false match — the text is then stored verbatim, in clear, and reachable by search, export and every client. | |
| condition_type | No | When to fire. on_session_start with the other session's name as entity_pattern is also the cross-session note channel: fires once (max_fires) the next time that session starts, carrying who left it. | |
| entity_pattern | No | Entity name or pattern to match |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It restates the firing conditions that the condition_type enum already covers, but discloses nothing about persistence, permissions, or what happens on repeated fires beyond what the schema already says. For a stateful mutation tool this is thin.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loaded with the core concept and followed by a clarifying analogy. Efficient with no obvious filler, though the second sentence is illustrative rather than informational.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, and the description does not explain the overall action workflow (create/list/delete/check) or what check/list return. The rich parameter schema partially compensates, but for an 8-parameter mutation tool with no annotations, the prose leaves meaningful gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all 8 parameters well (including the detailed allow_secret explanation). The description adds no parameter-level meaning beyond the schema, which is the expected baseline when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific concept (prospective memory) and enumerates the trigger conditions (entity access, session start, error match), with a concrete usage analogy. It is clear what the tool does, but it never differentiates itself from the many similarly-named siblings (memory_centinela, cuba_alarma/cuba_vigia, cuba_eco), so an agent cannot easily tell which radar-style tool to pick.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The quoted example ('Remember to remind me about X when Y happens') illustrates the intent but gives no explicit when-to-use guidance, no exclusions, and no named alternative among the ~50 siblings. The agent must infer that this is the reminder/trigger tool from concept alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Visible context window for the agent: working memory + agent notes (exact Mcp-Client-Id) + artifact index + recall of this session's recent writes (then WM mentions, then importance). Call at the start of a turn; call cuba_cronica add BEFORE editing. Alias: memory_context.
| Name | Required | Description | Default |
|---|---|---|---|
| budget_chars | No | Max serialized size (default 12000) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It usefully discloses the composition and prioritization order of the returned recall (recent writes, then WM mentions, then importance), which is real behavioral information. However, it says nothing about side-effect profile, whether the call mutates session state, or what happens when budget is exhausted.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loads the resource, then the usage directive, then the alias. Three sentences, no filler, though the parenthetical ordering clause makes the first sentence heavier than it needs to be.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description correctly compensates by describing what the returned context contains and in what priority order. Combined with the 100%-documented parameter, an agent has enough to invoke it, with only the side-effect profile missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with budget_chars documented as 'Max serialized size (default 12000)', so the baseline is 3. The description adds no further semantics about the budget parameter, and for a single-parameter tool that is acceptable but not additive.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a concrete resource — the agent's visible context window — and enumerates its ingredients (working memory, agent notes keyed by Mcp-Client-Id, artifact index, recent-write recall). This is specific enough to distinguish it from sibling memory tools, though the enumeration is dense and the 'alias: memory_context' note blurs rather than sharpens the boundary.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit timing ('call at the start of a turn') and a named alternative action for a related need ('call cuba_cronica add BEFORE editing'). It stops short of stating when not to call it, but the routing guidance is clear and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Detect semantic contradictions between observations of the same entity. Uses embedding cosine distance + negation heuristics. Read-only.
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | Contradiction detection action | |
| entity_name | No | Entity to scan (omit to scan top entities by observation count) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description bears full burden. It discloses read-only nature and method used, but lacks details on return format, error handling, or behavior when no contradictions are found. Partial transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise: two sentences front-load the purpose and key behavioral trait (read-only). No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema and description does not explain return values or response format. For a tool involving contradiction detection with embedded methods, the description is insufficient for an agent to fully anticipate results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with adequate parameter descriptions. Tool description adds no extra parameter semantics beyond method context, so baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the verb 'detect' and resource 'semantic contradictions between observations'. It specifies the method (embedding cosine distance + negation heuristics) and explicitly notes it's read-only, distinguishing it from sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus siblings or when not to use it. The 'read-only' note implies safety but does not provide context for selection among alternative tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Attach facts/lessons/decisions to entities. Also manages episodic memories (specific events with actors/artifacts) via episode_add/episode_list. Timeline view shows chronological history. Auto-creates entity if not found. Dedup gate blocks near-duplicates.
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | Operation to perform. episode_add stores a temporal event; episode_list retrieves events. timeline shows chronological observations+episodes. | |
| actors | No | People/agents involved in episode (for episode_add) | |
| source | No | Who/what created this observation | |
| content | No | Observation or episode text | |
| artifacts | No | Files/resources affected in episode (for episode_add) | |
| entity_name | No | Entity to attach observation/episode to | |
| allow_secret | No | Refused when the text looks like a live credential (token, password, URL with embedded creds). Set true only for a false match — the text is then stored verbatim, in clear, and reachable by search, export and every client. | |
| observations | No | Array of {entity_name, content, observation_type?, source?} objects (for batch_add, max 100) | |
| observation_id | No | Observation UUID (for delete action) | |
| observation_type | No | Type of observation |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden but does disclose two important behavioral traits: auto-creation of missing entities and a dedup gate that blocks near-duplicates. It still omits mutation/destructive behavior, authentication requirements, reversibility, and return behavior, so it is only partially transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is five short sentences and front-loads the core purpose before covering episodic memories, timeline, auto-creation, and deduplication. Each sentence carries useful information, though the action coverage is somewhat fragmented rather than systematically organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 7-action, 10-parameter memory tool with no annotations and no output schema, the description covers the main observation attachment, episodic memory, timeline, auto-creation, and dedup concepts. It leaves out explicit treatment of delete, list, and batch_add actions, but the schema's 100% coverage compensates for those gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all 10 parameters thoroughly, including enums and nested batch objects. The description only names episode_add, episode_list, and timeline actions and adds no syntax or format detail beyond what the schema provides, matching the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Attach facts/lessons/decisions to entities') and extends that to episodic memories and timeline views. The purpose is clear, but it does not explicitly distinguish this tool from the many similarly named sibling memory tools such as memory_cronica.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It mentions that episodic memories are managed via episode_add/episode_list and that timeline shows chronological history, which gives some action-level context. However, it provides no guidance on when to choose this tool over alternatives like memory_cronica or when to use add vs batch_add vs delete, so the agent must infer usage from the schema.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Record and query architecture/design decisions.
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | Search text (for query action) | |
| title | No | Decision title (for record) | |
| action | Yes | Decision action | |
| chosen | No | Option chosen | |
| context | No | Why this decision was needed | |
| rationale | No | Why this option was chosen | |
| allow_secret | No | Refused when the text looks like a live credential (token, password, URL with embedded creds). Set true only for a false match — the text is then stored verbatim, in clear, and reachable by search, export and every client. | |
| alternatives | No | Options considered |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. The schema's allow_secret description does disclose a real behavioral trait (credential detection and verbatim clear-text storage), but that appears in the schema, not the description. The description itself says nothing about persistence, secret-refusal, or that records are searchable/exportable — significant gaps for an un-annotated mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single short sentence, front-loaded, no filler. It underspecifies rather than overexplains, so conciseness is fine even though content is thin.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Eight parameters, a three-way action enum, no annotations, no output schema, and a credential-handling behavior with real safety consequences — the description should at least route between record/query/list and warn what recording persists. It doesn't, leaving the agent reliant entirely on schema text.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds no parameter-level meaning beyond what the schema already documents per-field (query text, title, alternatives, allow_secret, etc.).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a verb pair ('record and query') and resource ('architecture/design decisions'), which is clearer than a bare name. However, it doesn't distinguish itself from the sibling memory_decreto or from other memory_*/cuba_* decision-adjacent tools, leaving an agent to guess which of the 50+ siblings handles decision records.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No when-to-use guidance, no prerequisites, no mention of when to pick this over memory_decreto or cuba_cronica. The 'action' enum (record/query/list) is the only hint of use-case branching, and it lives in the schema, not the description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
RLHF feedback: positive boosts importance (Oja's rule), negative decreases, correct updates content. Also the quarantine gate: 'pending' lists memories withheld from search because they came from untrusted text, 'promote' makes one retrievable, 'quarantine' withdraws one. The gate covers observations, episodes and errors — pick which with 'kind'.
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | Target UUID for promote/quarantine when kind is episode or error. For kind=observation use observation_id. | |
| kind | No | Which table promote/quarantine acts on. Default 'observation'. An import quarantines whatever carried a credential, and cuba_sync writes episodes and errors too: without the matching kind those rows would stay stored and permanently unreachable. Ignored by positive/negative/correct, and by pending, which always returns all three. | |
| limit | No | Max rows for the 'pending' listing (default 20, max 200) | |
| action | Yes | Feedback type, or a quarantine transition: promote/quarantine flip one memory's retrievability; pending lists everything currently withheld, in three lists (quarantined, quarantined_episodes, quarantined_errors), each row tagged with its kind. | |
| correction | No | New content (for correct action) | |
| entity_name | No | Target entity | |
| allow_secret | No | Refused when the text looks like a live credential (token, password, URL with embedded creds). Set true only for a false match — the text is then stored verbatim, in clear, and reachable by search, export and every client. | |
| observation_id | No | Target observation UUID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well: it explains that positive/negative use Oja's rule to boost or decrease importance, that correct overwrites content, that 'pending' lists withheld memories from untrusted text, and that promote/quarantine flip retrievability. It also notes the gate covers observations, episodes and errors. What is missing is the reversibility of promote/quarantine, whether feedback is idempotent, and any error conditions. Strong but not complete.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single long block that mixes two unrelated functional areas (RLHF feedback and quarantine transitions) without headings or bullets, and it front-loads the RLHF part before the gate. It is not padded, but the structure makes it hard to scan and the opening sentence assumes the reader already knows what 'cuba_eco' is.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 8-parameter tool with no annotations and no output schema, the description covers the main behaviors: how feedback changes importance, how corrections replace content, and how the quarantine gate filters, promotes and quarantines across three kinds. It does not describe the pending return format in detail beyond naming the three lists, and it does not state what the tool returns for other actions, but the schema elsewhere is fully documented and this is close to sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents every parameter including the enum semantics and the kind selection. The description adds context that 'kind' exists to target observations, episodes or errors and that pending ignores it, but this largely repeats what the schema descriptions already state. Baseline 3 is appropriate when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names two distinct capabilities (RLHF feedback and a quarantine gate) with specific actions, but the tool name 'cuba_eco' provides no hint and the description begins mid-thought. It is possible to reconstruct the tool's purpose from the text plus the action enum, but the description itself is vague about the overall scope (is this one tool or two merged together?) and does not distinguish it from siblings like memory_eco or cuba_centinela.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit when-to-use guidance. The description explains what each action does but never states when to choose positive vs correct, or when to use pending before promote. The sibling list is long and no alternative tool is named for any scenario. Usage is implied only by action semantics.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search past errors/solutions. Use 'proposed_action' as anti-repetition guard: warns if similar approach previously failed.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Search text for errors | |
| project | No | Filter by project | |
| resolved_only | No | Only return errors with solutions | |
| proposed_action | No | Anti-repetition: describe what you plan to do. Returns warning if similar approach failed before. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description reveals that the tool returns a warning if a similar approach failed before (via 'proposed_action'), but with no annotations provided, it fails to disclose other behavioral traits such as read-only status, required permissions, or potential side effects. The behavioral transparency is minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose, no unnecessary words. Every sentence adds value—the first states what the tool does, the second gives a key usage hint. Excellent conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is brief and lacks details about return values, result ordering, pagination, or error handling. While the tool has a moderate number of parameters (4), the lack of output schema and limited context means the description is minimally complete for an effective search tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides full descriptions for all 4 parameters (100% coverage). The description adds a brief usage note about 'proposed_action,' but it does not provide additional meaning beyond what the schema already states. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Search past errors/solutions.' It uses a specific verb and resource, making it distinct from vague descriptions. However, it does not explicitly differentiate from siblings like cuba_remedio (which might also deal with errors/solutions), but the purpose is still clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a specific usage tip for the 'proposed_action' parameter, but it lacks any guidance on when to use this tool versus alternative tools (e.g., cuba_remedio or cuba_cronica). No mention of context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search memory BEFORE answering to ground responses. Returns grounding scores. Mode 'verify' checks claims against evidence (confidence: verified/partial/weak/unknown). Session-aware: boosts results matching active session goals. Supports temporal filtering. Optional MMR diversification, OOD abstention and an exact tiktoken-based token budget.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | Search mode (default: hybrid). 'verify' checks if claim is grounded. | |
| tags | No | Filter observations by tag keyword (exact match against auto-extracted tags) | |
| after | No | ISO8601 datetime — return results created after this time | |
| limit | No | Max results (default 10, max 50) | |
| query | Yes | Search text | |
| scope | No | Where to search (default: all) | |
| before | No | ISO8601 datetime — return results created before this time | |
| format | No | Response format. compact (DEFAULT): abbreviated keys — e=entity, c=content, t=type, i=importance, s=score. 71% fewer tokens (798 vs 2787 at limit=10, measured). verbose: full key names, only when you need every field. | |
| rerank | No | Cross-encoder rerank top-50 → top-K with bge-reranker-v2-m3. Auto-enabled when CUBA_MODE=completo, or when this build has a real GPU provider active (CUDA/DirectML compiled in AND a working device). Off by default everywhere else, even with the model on disk: on CPU it costs 60-110s and blows the search budget. Explicit true/false always wins; run `cuba-memorys doctor` to see which reason applies here. | |
| diversify | No | Post-RRF MMR pass that penalizes near-duplicates among top-K. Default false. | |
| max_tokens | No | Token budget for results (default 5000). Counted exactly via tiktoken cl100k_base. | |
| mmr_lambda | No | MMR balance — 1.0 pure relevance, 0.0 pure diversity. Default 0.7. | |
| abstain_ood | No | Abstain (return empty results with abstain_reason) when the query is out-of-distribution via Mahalanobis distance. Default false. | |
| associative | No | Multi-hop expansion: seeds spreading activation from query-matched entities and pulls in observations on graph-connected entities that no lexical/vector signal surfaced. Additive — never lowers a base hit. Default false. | |
| enable_bm25 | No | Enable BM25 (ts_rank_cd) as third RRF signal alongside text + vector. Catches queries with rare terms that dense embeddings miss. Default true. | |
| ood_threshold | No | Mahalanobis distance threshold for abstention. Defaults to sqrt(chi2_0.99(d)), which scales with the embedding dimension (~21.25 for d=384). Override only if you calibrated on your own corpus. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden and does disclose non-obvious traits: session-awareness that boosts results matching active session goals, grounding scores in the return, verify-mode confidence tiers, and optional MMR/OOD abstention. It omits safety/auth profile, but the operational behavior described is substantively beyond the structured fields (session-goal boosting appears nowhere in the schema).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Five short sentences, each carrying a distinct capability, with the primary directive ('Search memory BEFORE answering') front-loaded. No filler and no repetition of schema detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 16-parameter tool with no output schema and no annotations, the description covers the main mode split, temporal filtering, and the opt-in features well enough to call it correctly. It does not sketch the return shape beyond 'grounding scores', which is a minor gap given there is no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the parameter docs are themselves unusually detailed (rerank GPU gating, tiktoken budget, ood_threshold derivation). The description adds only the verify-mode confidence vocabulary, so baseline 3 is appropriate — the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Search memory') plus its goal ('ground responses'), which is a real functional purpose rather than a restatement of the name. However, it never distinguishes itself from the many near-identical siblings (memory_faro, memory_remedio, cuba_remedio), so an agent cannot tell from the text alone why it would pick this one.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Search memory BEFORE answering to ground responses' gives a clear triggering context, and the mention of verify mode implies a claim-checking use case. It stops short of naming alternatives or stating when-not to use it, despite an unusually crowded sibling namespace.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
GDPR Right to Erasure: cascading hard-delete of an entity and ALL references across observations, relations, errors, and sessions. IRREVERSIBLE. Requires confirm=true.
| Name | Required | Description | Default |
|---|---|---|---|
| confirm | Yes | Must be true to proceed (safety gate) | |
| entity_name | Yes | Entity name to erase completely |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description fully covers behavioral traits: it states the operation is 'cascading', 'hard-delete', 'IRREVERSIBLE', and lists affected areas (observations, relations, errors, sessions). No contradictions found.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero filler. First sentence states the action and scope; second sentence emphasizes irreversibility and a precondition. Every word is purposeful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive tool with no output schema, the description provides ample context about the effect and prerequisites. It could mention the return value (e.g., success/error), but the warnings make it largely sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear descriptions for both parameters. The description adds the safety requirement 'Requires confirm=true' but does not significantly enhance understanding beyond schema. Baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verbs ('cascading hard-delete') and clearly identifies the resource ('entity and ALL references across observations, relations, errors, and sessions'). It distinguishes itself from sibling tools like 'cuba_receta' or 'cuba_archivo' by focusing on complete erasure.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions 'GDPR Right to Erasure' as a use case and highlights the need for 'confirm=true', but does not explicitly state when not to use it or compare it to alternatives among siblings. Clear context but lacks exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Abductive inference: find plausible causes of an observed effect. Read-only.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max hypotheses to return (default 10, max 50) | |
| action | Yes | explain: traverse causal relations backwards from `effect`, ranked by path_strength × importance. | |
| effect | Yes | Entity name representing the observed effect | |
| max_depth | No | Max causal chain hops (default 3, max 5) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It does disclose a key behavioral trait, 'Read-only', which is valuable safety context. However, it omits the backward-traversal/ranking behavior, depth limits, and result-count capping that shape what the agent gets back.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with zero waste; the core purpose leads and the read-only qualifier follows. Nothing needs trimming.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only inference tool with no output schema and no annotations, the description covers purpose and safety but says nothing about the shape of the returned hypotheses (ranking, count, depth) or about the backward traversal mode already documented only in the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents action, effect, limit, and max_depth with defaults and the ranking formula. The description adds no parameter meaning beyond that, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource: 'find plausible causes of an observed effect', and names the inference type (abductive). An agent can tell it produces candidate causes rather than a stored hypothesis (contrast with the memory_hipotesis sibling), though it never names that sibling explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by 'observed effect' input, but there is no explicit when-to-use, when-not-to-use, or guidance on choosing this over memory_hipotesis or cuba_reflexion/cuba_contradiccion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Bulk knowledge ingestion. 'ingest': array of {entity_name, content, observation_type} items. 'parse': split long text by paragraphs + heuristic classify. 'auto_extract' (v0.11): the calling client's LLM extracts salient durable facts from a turn/conversation via MCP Sampling ($0, no API key) and ingests them — the automatic-extraction that mem0/Zep have. All routes share the dedup/PE-gating/embedding pipeline; none delete.
| Name | Required | Description | Default |
|---|---|---|---|
| text | No | Raw text: paragraphs to split (parse) or a turn/conversation to extract facts from (auto_extract) | |
| items | No | Array of {entity_name, content, observation_type?} objects (for ingest action, max 200) | |
| action | Yes | Ingestion mode. Default 'ingest' is the fast raw path (no LLM). 'parse' splits long text. 'auto_extract' is opt-in LLM extraction via MCP sampling — do not use it as the default write. | ingest |
| untrusted | No | Set when the text came from somewhere you do not control (a fetched page, a pasted document, a third party). Everything extracted lands quarantined — stored and inspectable via cuba_eco action=pending, but withheld from cuba_faro until promoted. Default false. | |
| entity_hint | No | Optional main-subject hint for auto_extract (biases entity_name) | |
| entity_name | No | Entity to attach parsed observations to (for parse action) | |
| allow_secret | No | Refused when the text looks like a live credential (token, password, URL with embedded creds). Set true only for a false match — the text is then stored verbatim, in clear, and reachable by search, export and every client. | |
| supersede_conflicts | No | v0.11 (auto_extract): when a new fact replaces/contradicts an existing related one, ask the judge and mark the old observation superseded (knowledge-update; never deletes). Default false. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the full behavioral burden and does so: it discloses the shared dedup/PE-gating/embedding pipeline, that no route deletes, that untrusted content lands quarantined and is withheld from cuba_faro until promoted (inspectable via cuba_eco action=pending), that allow_secret stores verbatim in clear and is globally searchable/exportable, and that supersede_conflicts marks old observations superseded rather than deleting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Dense but front-loaded: the action breakdown comes first, followed by pipeline behavior, with no filler sentences. Some jargon ("PE-gating", "v0.11") assumes prior context and the middle sentence is packed, but every clause carries information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no annotations and no output schema, the description supplies the safety and side-effect context an agent needs (quarantine, credential refusal, non-deletion, supersession). Given the complexity of 8 parameters and three modes, it is nearly complete; it stops short of describing failure/return behavior for long-running bulk ingests.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all 8 parameters, including the action enum and the untrusted/allow_secret/supersede_conflicts semantics. The description's action breakdown largely restates what the schema parameter descriptions already say, so it adds only marginal value over structured data — baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Opens with a specific verb+resource ("Bulk knowledge ingestion") and then decomposes the three actions with what each does, so an agent can tell ingest (raw), parse (paragraph split + classify) and auto_extract (LLM sampling extraction) apart. It does not explicitly name or differentiate from the sibling namespaces (memory_ingesta, etc.), which keeps it short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit routing guidance per action: 'ingest' is the fast raw path, 'parse' splits long text, and 'auto_extract' is opt-in with a clear prohibition ('do not use it as the default write'). It also states the condition for the untrusted flag (text you do not control) and for allow_secret (only to override a false credential match).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Track working sessions with goals and outcomes. v0.8: optional 'project' arg binds the session to a named project (upserts in brain_projects); subsequent handlers will scope reads/writes to that project.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Session name (for start) | |
| goals | No | Session goals (for start) | |
| action | Yes | Session action | |
| outcome | No | Session outcome (for end) | |
| project | No | v0.8: project name to bind this session to (created on first use). Omit to keep session global. | |
| summary | No | What was accomplished (for end) | |
| allow_secret | No | Refused when the text looks like a live credential (token, password, URL with embedded creds). Set true only for a false match — the text is then stored verbatim, in clear, and reachable by search, export and every client. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It does disclose real behavior: the project arg upserts into brain_projects and future handlers will scope reads/writes to that project. But it says nothing about persistence, permissions, or what 'end' does to a session, leaving significant behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core purpose before the version-specific detail. Efficient, though the 'v0.8' versioning preamble is mildly meta and could be trimmed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a 7-parameter, 4-action dispatch tool with no annotations and no output schema, yet the description never explains the actions that drive the tool. An agent must open the schema to learn that 'start', 'end', 'list' and 'current' exist and what each requires, which is a substantial completeness gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description's project note largely restates what the schema description for 'project' already says ('created on first use', 'omit to keep session global'), so it adds little meaning beyond the structured fields.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource: 'Track working sessions with goals and outcomes.' An agent understands the domain immediately. However, it offers no differentiation from the obvious sibling memory_jornada, so an agent cannot tell from the description which of the two session-tracking tools to pick.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use guidance, no mention of the start/end/list/current lifecycle, and no routing to or away from memory_jornada. The only conditional content is about the optional 'project' arg, which is schema-level detail rather than usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
LLM-judge for semantically-conflicting observations in the ambiguous cosine-similarity band (0.6-0.8), where heuristics miss vocabulary-different conflicts. Verdicts are cached in brain_judgments.
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | judge_pair: decide on two given observation ids. scan_entity: pull ambiguous pairs for an entity and judge each. | |
| max_pairs | No | Max pairs to escalate per call (default 5; controls LLM cost) | |
| entity_name | No | Entity to scan (for scan_entity) | |
| observation_a | No | UUID of first observation (for judge_pair) | |
| observation_b | No | UUID of second observation (for judge_pair) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It usefully discloses two side effects: that this is an LLM-backed (costly) operation and that verdicts are cached in brain_judgments. It does not state permissions required, cost bounds, or whether cached verdicts are reused/overwritten, leaving meaningful gaps for a mutating, LLM-invoking tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences with no filler, and the core purpose and the similarity band are front-loaded. The phrasing is dense but every clause contributes information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema and no annotations, so the description should do more of the explanatory work. It names the cache destination but never describes what a verdict returns or its shape, and the two actions are only clarified in the schema. Adequate to route a call but incomplete for a judge tool without structured output.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all five parameters including the action enum and max_pairs cost control. The description adds no syntax or format detail beyond that. Baseline 3 is appropriate when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: an LLM-judge that resolves semantically-conflicting observations in a defined cosine-similarity band. It clearly positions itself against heuristics ('where heuristics miss vocabulary-different conflicts'), which aids differentiation. It stops short of naming any actual sibling tool (e.g., memory_juez or cuba_contradiccion), so selection vs. siblings remains inferential.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives a concrete triggering condition: use when observations fall in the ambiguous 0.6-0.8 band and vocabulary-different conflicts would evade heuristics. That is clear when-to-use context. It offers no explicit when-not-to-use or pointer to an alternative tool, so it does not reach the top of the scale.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Working memory buffer (v0.9, Baddeley 1992): a TTL-bounded scratchpad orthogonal to episodic and semantic memory. Use for inter-step plan state during long-horizon agent tasks, tentative observations, cross-tool-call reminders inside one session. Auto-expire by ttl_seconds; bulk-purged by cuba_zafra REM cycle.
| Name | Required | Description | Default |
|---|---|---|---|
| tag | No | Optional tag for filtering on read/clear | |
| action | Yes | Working-memory operation | |
| content | No | Content to store (for write) | |
| ttl_seconds | No | Time-to-live in seconds (default 3600) | |
| allow_secret | No | Refused when the text looks like a live credential (token, password, URL with embedded creds). Set true only for a false match — the text is then stored verbatim, in clear, and reachable by search, export and every client. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well: it discloses the TTL auto-expiry lifecycle and that cuba_zafra's REM cycle bulk-purges entries. It omits write/overwrite semantics and read/clear behavior, but the credential-refusal behavior is covered in the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three dense sentences, front-loaded with the definition and followed by usage and lifecycle. The 'v0.9, Baddeley 1992' citation is mildly ornamental but does not bloat the text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 5-param tool with no annotations and no output schema, the description supplies purpose, when-to-use and lifecycle. It could say more about the write/read/clear actions and what a read returns, but the schema covers the parameters adequately.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3; the schema already documents tag, action enum, content, ttl_seconds and allow_secret in detail. The description only echoes ttl_seconds expiry, adding little parameter meaning beyond structured fields.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific resource ('working memory buffer... TTL-bounded scratchpad') and explicitly positions it relative to siblings by calling it 'orthogonal to episodic and semantic memory'. An agent can distinguish it from the many memory_* tools without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives concrete use cases: 'inter-step plan state during long-horizon agent tasks, tentative observations, cross-tool-call reminders inside one session'. Clear context for when to reach for it, though it does not explicitly name a sibling as the alternative or state when NOT to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compaction-survival protocol: persist and restore a session summary across /compact.
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | snapshot: before /compact, persists a dense markdown summary (observations, decisions, unresolved errors, pending embeddings, goals) for the active session. restore: after /compact, retrieves the latest snapshot and re-injects it into context. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It explains the core persist/restore behavior and the survival purpose, but does not disclose side effects, storage semantics, whether snapshots overwrite previous ones, or what exactly happens during restore beyond re-injection. This is adequate but incomplete for a stateful session tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It states the protocol name and core operation immediately, and every phrase contributes to understanding what the tool does.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool with a fully documented schema, the description covers the essential idea. However, with no output schema and no annotations, it should clarify return behavior for restore and differentiate from the sibling memory_pre_compact tool. The core is present, but important routing and output context is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single action parameter has 100% schema description coverage, including detailed enum semantics for snapshot and restore. The tool description adds the conceptual 'compaction-survival' framing but no additional parameter syntax or format details beyond what the schema already provides, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific protocol and verb pair: persist and restore a session summary across /compact. It is clear what the tool does, but it does not differentiate itself from the sibling memory_pre_compact tool, leaving some ambiguity about which one an agent should choose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'across /compact' implies the usage window (before and after compaction), and the schema's action enum explains snapshot vs. restore timing in more detail. However, the description itself gives no explicit when-to-use guidance, no alternatives, and no exclusions relative to memory_pre_compact.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Project scoping (v0.8): isolate memories per project so multiple projects sharing one DB don't bleed into each other. Active project is bound to the current session (cuba_jornada start --project NAME). Legacy rows with NULL project_id remain visible from every scope.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | Destination name (for rename/merge) | |
| name | No | Project name (for switch/stats/rename source) | |
| action | Yes | Project action |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses memory isolation and session binding but does not explain behavioral traits for actions like rename or merge (e.g., whether they are destructive, require permissions). The description is partially transparent but leaves gaps for a tool with multiple actions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences cover the core concept efficiently. The inclusion of 'v0.8' is minor clutter. Front-loaded with essential information. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and 3 parameters, the description is reasonably complete. It explains the isolation mechanism, session binding, and legacy behavior. However, it lacks details on return values or effects of each action, which could be inferred but are not explicit.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds context about project scoping and session binding but does not elaborate on parameter semantics beyond what the schema provides. Adequate but not enhanced.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: project scoping to isolate memories per project. It uses a specific verb ('isolate') and resource ('memories per project'), and distinguishes it from sibling tools by focusing on project management concepts like session binding and legacy rows.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions that the active project is bound to the session via cuba_jornada start --project NAME, and notes legacy row visibility. However, it does not provide explicit when-to-use or when-not-to-use guidance relative to sibling tools like cuba_jornada or cuba_alma. The usage context is implied but not clearly delineated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create edges between entities (uses, causes, implements, depends_on, related_to). 'traverse' explores connections, 'infer' does transitive reasoning (A→B→C), 'predict' suggests missing links via Adamic-Adar. Relations strengthen with use (Hebbian).
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | Operation to perform. 'predict' uses Adamic-Adar to suggest missing relations. | |
| persist | No | For predict: write the suggestions to brain_relations as provenance='predicted' (relation_type related_to) instead of only returning them. Default false — read-only. | |
| max_depth | No | Max hops for traverse/infer (default 3, max 5) | |
| to_entity | No | Target entity name | |
| entity_name | No | Entity name for predict action (Adamic-Adar link prediction) | |
| from_entity | No | Source entity name | |
| start_entity | No | Start point for traverse/infer | |
| bidirectional | No | If true, relation goes both ways | |
| relation_type | No | Relation: uses, causes, implements, depends_on, related_to. Also used by predict+persist to pick the type for the persisted edge (default related_to). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavior. It mentions 'Relations strengthen with use (Hebbian)' but does not explain what that means for the agent (e.g., automatic persistence, side effects). Critically, the delete action is omitted entirely, leaving a major behavioral gap unaddressed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short (two sentences) and front-loaded, but it omits the delete action entirely. This conciseness comes at the cost of completeness. Every sentence is functional, but the omission is a critical gap.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 9 parameters, multiple actions, no output schema, and no annotations, the description is moderately complete. It covers create, traverse, infer, and predict, but misses delete and does not explain how bidirectional, persist, or max_depth interact with the overall behavior. The Hebbian mention is vague.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds some context (e.g., Hebbian strengthening and Adamic-Adar for predict), but this largely duplicates what's already in the action parameter description. It does not significantly deepen understanding of individual parameters beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Create edges between entities' but the tool also includes delete, traverse, infer, and predict actions. The first sentence is misleading as it implies only creation. It lists the relation types and explains other actions, but fails to mention delete, making the purpose incomplete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus its siblings (e.g., cuba_vigia, cuba_proyecto). The description details when to use each action within the tool (traverse vs infer vs predict), but does not help an agent choose between this and other tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
PROCEDURAL MEMORY: how things are DONE here — bring up the dev services, run the test suite, deploy, migrate. The other tools remember what is TRUE; this one remembers what to DO, so an agent stops rediscovering it every session. Ranked by reliability, not by how often it is read: report the outcome with action='outcome' after running one, or the memory learns nothing. A recipe that keeps failing is worse than none, because it is trusted.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Procedure name, e.g. 'levantar el entorno de desarrollo' | |
| limit | No | Max results | |
| query | No | For action=search | |
| steps | No | Ordered steps: [{do: '...', run: 'comando'?, expect: 'qué debe pasar'?}] | |
| action | Yes | search: find by meaning. get: fetch by exact name. add: store/update (re-adding the same name edits it, keeping its track record). outcome: record success/failure — this is what teaches it. | |
| success | No | For action=outcome: did it work? | |
| trigger | No | WHEN this applies — the IF half. e.g. 'cuando hay que levantar los servicios de mapupita-web' | |
| allow_secret | No | Refused when the text looks like a live credential (token, password, URL with embedded creds). Set true only for a false match — the text is then stored verbatim, in clear, and reachable by search, export and every client. | |
| verification | No | How you know it actually worked | |
| preconditions | No | What must already be true before starting |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and discloses genuinely non-obvious behavior: ranking is by reliability rather than read frequency, and the memory only learns from action='outcome' reporting. The caveat that a persistently failing recipe is worse than none is a real behavioral warning. It does not cover permissions, what delete destroys, or result limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The conceptual framing is front-loaded and the actionable 'report the outcome' instruction follows immediately. The concluding aphorism about failing recipes is slightly rhetorical but reinforces the stakes rather than padding, so it mostly earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 10-parameter tool with no annotations and no output schema, the description adequately explains the mental model and the critical feedback loop, and the schema carries full parameter documentation. Return-shape details for get/search are left implicit, which is a minor gap given no output schema exists.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameter baseline is 3. The description adds meaning on top by singling out action='outcome' as the teaching mechanism and implying the reliability semantics that the enum alone does not convey, warranting a modest bump.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names the resource (procedural memory / recipes for how things are done) and gives concrete examples (bring up dev services, run tests, deploy, migrate). Critically, it distinguishes itself from siblings with 'The other tools remember what is TRUE; this one remembers what to DO,' so an agent can route between the two memory families without reading both schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit operational guidance — report the outcome with action='outcome' after running a recipe or 'the memory learns nothing' — and frames when this tool is the right choice versus the fact-memory siblings. It stops short of saying when NOT to use it (e.g. for exploratory or non-reproducible steps), so it lacks full exclusion coverage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Analyze the knowledge graph for structural gaps. Read-only.
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | analyze: the only action. Reports isolated entities, underconnected hubs, type silos, observation gaps (missing decisions/lessons), and statistical density anomalies. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It does disclose the key trait 'Read-only', which is genuinely useful safety information, but says nothing about output shape, cost, or side effects beyond that. The read-only claim is also largely implied by the schema's 'Reports...' wording, so the added value is modest.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the purpose and ending with the safety trait. Nothing is wasted or padded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter, read-only analysis tool the definition is nearly sufficient: the schema's enum description enumerates what the analysis reports (isolated entities, hubs, silos, observation gaps, density anomalies), which effectively covers the return content despite there being no output schema. The main missing piece is any guidance on when to use it versus its siblings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the single 'action' enum is fully documented in the schema itself, including what the analysis reports. The description adds no parameter-level meaning beyond that, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Analyze') and resource ('the knowledge graph') with a clear scope ('structural gaps'). It is clear what the tool does, but it does not distinguish itself from the sibling memory_reflexion, which likely performs the analogous analysis over memory.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No when-to-use context, no prerequisites, and no alternatives are named. The many sibling tools (cuba_* / memory_* pairs) make routing ambiguous, and the description offers no help in choosing this one over memory_reflexion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Mark an error as resolved with solution. Cross-references similar unresolved errors.
| Name | Required | Description | Default |
|---|---|---|---|
| error_id | Yes | UUID of the error to solve | |
| solution | Yes | Solution that fixed the error | |
| allow_secret | No | Refused when the text looks like a live credential (token, password, URL with embedded creds). Set true only for a false match — the text is then stored verbatim, in clear, and reachable by search, export and every client. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It does disclose a meaningful side effect — that similar unresolved errors are cross-referenced — but says nothing about permissions, reversibility, or whether the resolution is broadcast/persisted elsewhere, and the sensitive allow_secret behavior is only covered in the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short front-loaded sentences with no filler; the action comes first and the side effect second. It is efficiently sized, if a little terse for a mutation tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no annotations and no output schema, the description should say more about what happens on success and what the cross-referencing returns. It covers the core mutation but leaves the agent guessing about the response and about failure modes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so error_id, solution, and allow_secret are already fully documented including the credential-refusal warning. The description adds no parameter-level detail beyond what the schema provides; baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a concrete verb+resource: marking an error as resolved with a solution, plus the cross-referencing side effect. That is far clearer than the opaque tool name 'cuba_remedio', though it does nothing to distinguish this from the many similarly cryptic siblings (memory_remedio, cuba_alarma, etc.).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use or when-not-to-use guidance, and no alternative tool is named. The agent must infer that this is the call to make after fixing a problem, with nothing saying how it relates to the sibling remedio/alarma tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Git-friendly export/import of the knowledge graph between machines that share no database. export/import/diff/status work on a local directory (default ./.cuba-memorys/); pull/notify/fetch/conflicts/resolve talk to a peer over HTTP with CUBA_PEER_TOKEN.
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | resolve only: the conflict id from action=conflicts | |
| dir | No | Directory override (default $CUBA_SYNC_DIR or ./.cuba-memorys/) | |
| url | No | fetch only: the peer's base address, e.g. https://brain.example.net | |
| keep | No | resolve only: which text stays current (default 'both', which loses nothing) | |
| peer | No | fetch only: which peer to pull from (default 'default') | |
| limit | No | pull only: max files per page | |
| scope | No | Export scope: active project only (default) or all data | |
| action | Yes | export/import/diff/status: local bundle round-trip. pull: return the bundle in the response instead of writing it, for a peer to fetch. notify: tell a peer what changed. fetch: pull a peer's bundle over HTTP and import it. conflicts/resolve: list and settle rows two machines disagree about. | |
| offset | No | pull only: index of the first bundle file to return | |
| confirm | No | Required when the import's tombstones would delete more than 10% of this machine's observations and at least 25 rows | |
| node_id | No | notify only: self-asserted id of the sending node | |
| summary | No | notify only: what changed, in at most 2000 characters | |
| conflict | No | How to resolve a row that exists on both sides (default merge; merge and skip keep local content, overwrite takes the incoming version) | |
| node_name | No | notify only: readable name of the sending node | |
| manifest_hash | No | notify only: the bundle hash this notice refers to | |
| with_embeddings | No | Include embeddings (default false on export, true on pull) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations, so the description must carry the behavioral load. It discloses transport (local dir vs HTTP) and the CUBA_PEER_TOKEN requirement, but says nothing about import's destructive tombstone deletions, the confirm threshold, permission scope, or reversibility—all critical for a mutation-capable sync tool. Some context, but a major gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core purpose and then the action grouping. Every clause earns its place; no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The rich schema (16 documented params, detailed action enum, confirm parameter for destructive imports) fills most gaps. The description adds transport grouping and defaults, but omits a high-level warning about import deletions. With no output schema and no annotations, this is reasonably complete but not exhaustive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%; every parameter already has a description in the input schema. The tool description adds only action grouping and default directory knowledge, which is useful context but not parameter-level syntax beyond schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('export/import of the knowledge graph') and scopes it to machines without a shared database. It also splits the nine actions into local-directory and peer-HTTP groups, letting an agent tell it apart from generic sync tools. It lacks explicit mention of the sibling memory_sync, but is otherwise precise.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives clear context: export/import/diff/status operate on a local directory (default ./.cuba-memorys/); pull/notify/fetch/conflicts/resolve require a peer over HTTP with CUBA_PEER_TOKEN. No when-not conditions or named alternatives are provided, so it stops short of 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find cuba-memorys tools and load their schemas ON DEMAND. The server exposes 31 tools; under CUBA_TOOL_PROFILE=lean only the everyday core is pre-loaded and the rest live here. Search by capability ('audit', 'decay', 'contradiction', 'session'), then call what you find with cuba_call. detail='names' is cheapest, 'full' returns the exact argument schema.
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | Filter by capability — matches tool names and descriptions. Omit to list everything. | |
| detail | No | names: just the names. summary (default): name + description. full: the complete JSON Schema, which is what you need to call the tool correctly. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden and does disclose the key behavioral trait: the lean profile changes what is pre-loaded, which explains why this tool exists. It also hints at cost (detail='names' is cheapest). It doesn't explicitly label the operation as read-only or describe failure behavior when nothing matches, leaving a small gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four dense sentences, each carrying distinct information (purpose, server/profile context, search-then-call workflow, detail cost tradeoff), with the core action front-loaded. No filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description must cover the return shape, and the detail parameter descriptions do explain names/summary/full. For a two-param discovery tool that is nearly complete; only the empty-result and profile-default edge cases are unstated.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% so the baseline is 3, but the description adds genuine meaning: query matches names and descriptions by capability, and detail='full' is what you need to call correctly while 'names' is cheapest. This gives cost/usage intent beyond the enum values themselves.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a precise verb+resource (find tools and load their schemas on demand) and frames itself as the discovery layer for a 31-tool server. It distinguishes itself from siblings by naming cuba_call as the consumer of what it finds, so an agent knows this lists/schemas rather than executes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explains exactly when it is needed (under CUBA_TOOL_PROFILE=lean only the core is pre-loaded, so the rest must be discovered here) and prescribes the workflow: search by capability, then call via cuba_call. Example queries ('audit', 'decay', 'contradiction', 'session') make the search surface concrete.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Knowledge graph analytics: summary, health, drift, communities, bridges, structural.
| Name | Required | Description | Default |
|---|---|---|---|
| metric | Yes | summary: counts + token estimate. health: staleness, entropy, DB size. drift: chi-squared on errors. communities: Leiden clustering. bridges: betweenness centrality. structural: harmonic + closeness centrality + k-core ranking (backbone identification). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It never says whether the metrics are read-only, computationally expensive (Leiden clustering and betweenness centrality are heavy), whether they mutate graph state, or what latency to expect.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
It is a single short line, which is efficient, but roughly half its content is a bare enumeration that duplicates the enum values already present in the schema. It is under-specified rather than truly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The sole input parameter is fully documented by the schema, so the input side is covered. With no output schema and no annotations, the description leaves the return shape and operational cost of these analytics unstated, which is a real gap for a multi-mode analytics tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the enum's per-value descriptions are far richer than the description text (e.g. 'Leiden clustering', 'harmonic + closeness centrality + k-core ranking'). The description merely restates the enum keys, adding no meaning beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names the domain (knowledge graph analytics) and lists the six metric modes, so an agent can tell roughly what kind of tool this is. However, it is a noun fragment with no verb and no indication of what the tool actually returns or does with the graph, and it does not differentiate this from sibling analytics/supervision tools like cuba_centinela or cuba_calibrar.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no statement of when to reach for this tool versus alternatives, no prerequisites, and no mention of the large family of cuba_* siblings that perform adjacent analyses. The agent must infer usage entirely from the metric names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Identify this MCP client against the MemoryIndustry daemon: client id, project, session, node, LLM, graph-db, resource plan. Alias: memory_whoami.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry behavioral disclosure. It lists useful output fields and the identity-check purpose, but does not explicitly confirm that the operation is read-only, side-effect-free, or what permissions are needed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that identifies the tool's function and key return fields. The alias note at the end is short and earns its place by cross-referencing the sibling name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a no-argument, read-only diagnostic tool with no output schema, the description is nearly complete: it states the purpose, lists the returned identity fields, and provides the alias. Only explicit usage guidance is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the description correctly does not discuss parameter semantics. Per the rubric, a no-parameter tool has a baseline of 4 for this dimension.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Identify this MCP client against the MemoryIndustry daemon.' It lists the identity fields returned, making the tool's scope clear. It does not differentiate from most siblings beyond noting the memory_whoami alias, so it stops short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit when-to-use or when-not-to-use guidance. The alias note helps an agent recognize the equivalent memory_whoami tool, but no conditions or alternatives are described.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Memory maintenance, scoped to the active project: decay, prune, merge, summarize, pagerank, find_duplicates, export, reembed, decay_episodes.
| Name | Required | Description | Default |
|---|---|---|---|
| c | No | Power-law c parameter for decay_episodes (default 0.1) | |
| beta | No | Power-law β exponent for decay_episodes (default 0.5) | |
| action | Yes | decay: stratified exponential decay by type. prune: deletes low-importance observations, dry-run unless confirm=true. merge: deduplicates similar entities. summarize: replaces an entity's observations with compressed_summary. stats: counts. pagerank: personalized importance ranking. find_duplicates: lists near-duplicate pairs. export: writes a JSON dump. reembed: re-encodes with the current model. decay_episodes: power-law decay on brain_episodes. | |
| confirm | No | prune only: actually delete. Without it, prune returns a dry-run plan (would_prune, by_project) and deletes nothing — read the plan first, the default threshold reaches a large share of a mature corpus. | |
| threshold | No | Importance threshold for prune (default 0.1) | |
| batch_size | No | Max observations to re-encode in reembed (default 500) | |
| entity_name | No | Entity to summarize (for summarize action) | |
| allow_secret | No | Refused when the text looks like a live credential (token, password, URL with embedded creds). Set true only for a false match — the text is then stored verbatim, in clear, and reachable by search, export and every client. | |
| halflife_days | No | Global halflife override for decay (overrides per-type stratification) | |
| compressed_summary | No | Compressed text replacing observations (for summarize) | |
| similarity_threshold | No | Similarity threshold for merge (default 0.8) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full disclosure burden, yet 'maintenance' hides that several actions (prune, decay, merge, reembed) mutate or delete data. It says nothing about reversibility, confirmation requirements, or the dry-run default for prune, all of which matter for an unannotated multi-action tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence establishes purpose and scope before the action list, with no filler. The action enumeration partially duplicates the schema enum, costing a point.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a ten-action dispatcher with destructive operations, no annotations, and no output schema, the description is too thin: it omits safety posture, confirmation behavior, and any differentiation from the parallel memory_zafra sibling. An agent would need to open the schema to understand the tool at all.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and each parameter is thoroughly documented in the schema (including confirm's dry-run semantics and allow_secret's credential refusal), so the description adds nothing beyond listing action names already present in the enum. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a resource (memory) and a scope (the active project) and enumerates the nine operations the tool performs, so an agent can tell it is a maintenance dispatcher rather than a read/write CRUD tool. It falls short of a 5 because the opaque name 'cuba_zafra' is never explained and it does not distinguish itself from the near-identical sibling memory_zafra.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Scoped to the active project' is the only contextual hint; there is no statement of when to reach for this tool versus its siblings (cuba_zafra vs memory_zafra) or which of the ten actions fits a given situation. Action-level guidance lives only in the schema, not the description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[alias of cuba_alarma] Report errors immediately. Auto-detects patterns (≥3 similar = warning). Hebbian: similar errors get boosted for easier retrieval.
| Name | Required | Description | Default |
|---|---|---|---|
| context | No | Context: {file, function, stack_trace, line} | |
| project | No | Project name (default: 'default') | |
| error_type | Yes | Error category: TypeError, ConnectionError, etc. | |
| allow_secret | No | Refused when the text looks like a live credential (token, password, URL with embedded creds). Set true only for a false match — the text is then stored verbatim, in clear, and reachable by search, export and every client. | |
| error_message | Yes | Full error message |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden and does disclose non-obvious traits: auto-pattern detection with a ≥3-similar warning threshold, and Hebbian boosting of similar errors for retrieval. It still omits whether the record persists, side effects, or the return shape, but it adds real behavioral context beyond the raw schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences, front-loaded with the alias and purpose, then the two behavioral notes. No filler; every clause conveys information an agent can act on.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 5-parameter, nested-object tool with no annotations and no output schema, the description covers the distinctive behaviors but leaves open what the call returns and whether/how the error is stored. Adequate but with clear gaps given the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, including detailed guidance on allow_secret and the context object shape, so the schema does the heavy lifting. The description adds nothing about parameter semantics, making the baseline 3 appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Report errors immediately') and flags that this is an alias of cuba_alarma, so an agent knows it duplicates that sibling. It does not differentiate itself from the broader error/history siblings like memory_expediente or memory_remedio, but the core purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The imperative 'Report errors immediately' implies the usage context (capture an error as it occurs), but there is no explicit when-to-use versus when-not, and no named alternative for related needs. Usage is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[alias of cuba_alma] CRUD knowledge graph entities (concepts, projects, technologies, patterns, people). Auto-boosts neighbors on access. For transient info use cuba_cronica instead.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Entity name (unique identifier) | |
| action | Yes | Operation to perform | |
| new_name | No | New name for update action | |
| entity_type | No | Type: concept, project, technology, person, pattern, config |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden, and it does disclose a non-obvious side effect: neighbors are auto-boosted on access. Beyond that it says nothing about mutation semantics (delete reversibility, permission requirements, whether update overwrites unspecified fields), leaving meaningful behavioral gaps for a write-capable tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three compact sentences, front-loaded with the alias/identity and the core CRUD purpose, then the side effect, then the alternative-tool escape hatch. No filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 4-parameter CRUD tool with no output schema and full schema coverage, the description covers what it operates on, a key side effect, and one routing rule. It is nearly complete but omits return-shape expectations and per-action behavioral differences that an agent calling delete or update would benefit from.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and every parameter is documented inline (name, action enum, new_name, entity_type), so the description need not carry parameter detail. It adds only the loose mapping of entity types to the entities it manages, which is largely redundant with the entity_type schema description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb set (CRUD) and resource (knowledge graph entities) and enumerates the entity types it operates on. It also declares itself an alias of cuba_alma and routes transient-data callers to cuba_cronica, so an agent can place it relative to siblings without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly names the alternative tool (cuba_cronica) and the condition selecting it (transient info). That covers one important when-not case, but there is no guidance on when to prefer create vs update vs get, or when to use the alias rather than cuba_alma.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[alias of cuba_archivo] Tamper-evident audit log: append-only, SHA-256 hash chain, UPDATE/DELETE blocked at the PostgreSQL trigger level.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Limit for verify/tail (default 10000 / 20) | |
| action | Yes | append: add an event. verify: walk the hash chain and detect tampering. tail: read recent events. | |
| payload | No | Arbitrary JSON payload (for append) | |
| event_action | No | Event type (for append) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and delivers real behavioral substance: append-only semantics, SHA-256 hash chain tamper detection, and UPDATE/DELETE blocked at the PostgreSQL trigger level. It does not cover permissions, whether verify returns a boolean or a chain report, or cost of walking a large chain.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single dense sentence with the alias qualifier first and the defining behavioral traits front-loaded. Nothing is wasted or padded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 4-parameter, no-annotation, no-output-schema tool, the description explains the storage model well but is silent on what verify/tail actually return and on limits of the chain walk. An agent knows what the store is but not fully what a call yields.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with the action enum, limit, event_action and payload all documented inline, so the schema already does the heavy lifting. The description adds no parameter-level detail beyond what is in the schema, which is the baseline 3 case.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific resource — an append-only, tamper-evident audit log — and the alias note ('alias of cuba_archivo') tells an agent this duplicates a sibling, aiding routing. The verbs (append/verify/tail) live only in the schema, so the description itself does not state the operations, keeping it short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to choose this tool, when not to, or which sibling action replaces it other than the bare alias note. The action enum in the schema implies three modes but the description never frames them as usage scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[alias of cuba_artefacto] Shared versioned artifacts between agents on the same daemon (and peers). put requires base_version (optimistic concurrency); lock is a short lease. Alias: memory_artifact.
| Name | Required | Description | Default |
|---|---|---|---|
| find | No | patch: substring to replace once | |
| path | No | Logical path, e.g. notes/plan.md | |
| limit | No | list limit | |
| action | Yes | Artifact operation | |
| prefix | No | list: path prefix filter | |
| content | No | Full content for put | |
| replace | No | patch: replacement | |
| ttl_seconds | No | lock lease length (default 60) | |
| base_version | No | Required for concurrent-safe put; omit or 0 to create |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It usefully discloses the optimistic-concurrency contract for put and the leased nature of lock, but omits what happens on a version conflict, whether lock blocks other writers, and any auth or persistence scope beyond 'same daemon'. Partial but genuinely additive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two compact sentences, front-loaded with the resource definition, then the two most consequential behavioral clauses, then the alias. Dense and free of filler, though the alias parenthetical is slightly awkwardly placed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a nine-parameter, seven-action tool with no annotations and no output schema, the description covers the versioning and lease mechanics but leaves action semantics (especially watch_hint and unlock) unexplained. Adequate but with clear gaps for a tool of this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all nine parameters (including base_version's 'omit or 0 to create'). The description's summary that put 'requires base_version' slightly overstates the schema, which allows omission for creation. Baseline 3 applies since the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States the core resource and model clearly: shared, versioned artifacts between agents on the same daemon and peers. It does not enumerate the seven actions, nor does it distinguish itself from the many similarly named sibling alias tools (cuba_artefacto, memory_archivo, cuba_pizarra), so an agent still needs the schema to know what operations exist.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives two action-specific conditions ('put requires base_version', 'lock is a short lease') but no when-to-use vs. alternative guidance, no prerequisites, and no explanation of the remaining actions (get, list, patch, unlock, watch_hint). Usage is implied by the action enum rather than directed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[alias of cuba_calibrar] Bayesian confidence calibration: track verify predictions, mark outcomes, compute P(correct|level). Closes the feedback loop between faro verify and eco correct.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results for history (default 20) | |
| action | Yes | stats/history: past predictions. resolve: mark a verify_id correct/incorrect. trust: per-source Beta(α, β) credibility, updated by resolve outcomes. metrics: Brier score + Expected Calibration Error + reliability diagram. | |
| outcome | No | Whether the verify prediction was right (for resolve) | |
| verify_id | No | Verify log UUID (for resolve) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It hints that 'resolve' marks outcomes (a mutation of stored prediction state) and that the tool persists calibration data across calls, but it says nothing about permissions, reversibility of a resolve, or persistence scope. Useful but incomplete for a state-mutating feedback tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences with the purpose front-loaded after the alias tag, and no redundant restatement of the schema. Slightly diluted by the bracketed alias metadata, but otherwise efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a five-action tool with no output schema and no annotations, the description conveys the overall purpose but not the return shape of stats/trust/metrics or the effect of resolve. The schema covers action semantics, so nothing critical is missing, but the behavioral gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and every parameter (action enum, outcome, verify_id, limit) is already documented in the schema, so the description adds no syntax or format detail beyond it. Baseline 3 is appropriate when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names specific operations (track verify predictions, mark outcomes, compute P(correct|level)) and identifies the two siblings it bridges, faro verify and eco correct, so an agent can place it in the workflow. It is clear but the '[alias of cuba_calibrar]' prefix adds disambiguation noise rather than purpose detail, keeping it just short of 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Closes the feedback loop between faro verify and eco correct' implies the context in which this tool belongs, but there is no explicit when-to-use or when-not, and no statement of which action to pick. Usage is inferable rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[alias of cuba_call] Invoke any cuba-memorys tool by name — including the ones not pre-loaded in this session. Discover them first with cuba_tools (use detail='full' to see the exact arguments). Goes through the same dispatcher as a direct call, so behaviour is identical.
| Name | Required | Description | Default |
|---|---|---|---|
| args | No | The tool's own arguments, exactly as its schema declares them | |
| tool | Yes | Tool name, e.g. cuba_zafra |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It discloses that execution goes through the same dispatcher as a direct call and behaviour is identical, which is exactly the behavioral guarantee an agent needs. It does not mention error handling, permissions, or failure modes, so not a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences: identity/scope, discovery path, behavioral guarantee. Front-loaded with the alias and purpose; zero filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a dispatcher with no annotations and no output schema, it covers scope, discovery, and behavioral equivalence. It could be richer on what happens if the tool name is wrong or unknown, but nothing essential to a correct call is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and both parameters have schema descriptions defining the shape, so the baseline is 3. The description adds a small navigation hint (use cuba_tools with detail='full' to find args) but does not explain the args envelope or name format beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (invoke) and resource (any cuba-memorys tool by name), and explicitly frames itself as a dispatcher/alias of cuba_call, which is a sibling. An agent can immediately tell it apart from the pre-loaded direct tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives an explicit when: tools not pre-loaded in this session. Gives an explicit alternative path: discover them first with cuba_tools using detail='full' to see exact arguments. That is a full usage recipe.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[alias of cuba_centinela] Prospective memory: triggers that fire on entity access, session start, or error match. 'Remember to remind me about X when Y happens.'
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | create: define a trigger. list: show triggers. delete: remove one (trigger_id). check: evaluate now. | |
| message | No | Reminder message to surface when triggered | |
| max_fires | No | Max times to fire (default 1, -1 for unlimited) | |
| expires_at | No | ISO8601 expiration datetime | |
| trigger_id | No | Trigger UUID (for delete) | |
| allow_secret | No | Refused when the text looks like a live credential (token, password, URL with embedded creds). Set true only for a false match — the text is then stored verbatim, in clear, and reachable by search, export and every client. | |
| condition_type | No | When to fire. on_session_start with the other session's name as entity_pattern is also the cross-session note channel: fires once (max_fires) the next time that session starts, carrying who left it. | |
| entity_pattern | No | Entity name or pattern to match |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It discloses the firing conditions (entity access, session start, error match), which is the core behavioral trait, but says nothing about persistence across sessions, what happens on expiry, authorization needs, or limits beyond the schema's own field notes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences with zero filler, routing metadata (alias) front-loaded and the purpose plus example immediately after. Every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 8-parameter tool with no output schema and no annotations, the description covers the purpose and trigger semantics adequately, and the schema documents parameters and actions thoroughly. The gap is that the four actions (create/list/delete/check) and the tool's persistence model are left entirely to the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the parameter descriptions are unusually rich (enum meanings, allow_secret credential warning, cross-session note channel), so the baseline is 3. The description adds only conceptual framing ('when Y happens') and no details beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific resource and behavior: 'Prospective memory: triggers that fire on entity access, session start, or error match.' The example ('Remember to remind me about X when Y happens') nails the mental model. It only partly differentiates from siblings, noting it is an alias of cuba_centinela but not what the alias relationship implies for selection.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The quoted use case implies when to reach for it, but there is no explicit when/when-not framing and no routing to alternatives such as memory_remedio, memory_alarma, or memory_pre_compact. Usage is inferable rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[alias of cuba_contexto] Visible context window for the agent: working memory + agent notes (exact Mcp-Client-Id) + artifact index + recall of this session's recent writes (then WM mentions, then importance). Call at the start of a turn; call cuba_cronica add BEFORE editing. Alias: memory_context.
| Name | Required | Description | Default |
|---|---|---|---|
| budget_chars | No | Max serialized size (default 12000) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it does disclose useful behavior: the composition and ranking order of the window ('recent writes, then WM mentions, then importance'). However, it says nothing about permissions, side effects, idempotency, or cost of calling it, so the behavioral picture is partial.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The alias is front-loaded, then content, then usage, in a tight block with no filler. The parenthetical ranking clauses are dense but informative. Slightly crowded, but every clause carries meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-style context-retrieval tool with no output schema and one well-documented parameter, the description explains what the caller gets back and when to invoke it. It is complete enough to call correctly, missing only edge behavior like truncation or empty-window cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so budget_chars is already documented in the schema. The description adds no additional meaning about the budget parameter, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names the resource (the visible context window) and enumerates its exact contents: working memory, agent notes, artifact index, and recall of recent writes. It also flags itself as an alias of cuba_contexto, which helps an agent reconcile the duplicate. It is specific, though it never uses a clear retrieval verb like 'returns' or 'loads'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives an explicit trigger ('Call at the start of a turn') and a related-tool instruction ('call cuba_cronica add BEFORE editing'). That is real when-to-use guidance with a named alternative, but it stops short of stating when NOT to use it or how it differs from the many other memory_* retrieval siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[alias of cuba_contradiccion] Detect semantic contradictions between observations of the same entity. Uses embedding cosine distance + negation heuristics. Read-only.
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | Contradiction detection action | |
| entity_name | No | Entity to scan (omit to scan top entities by observation count) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It does disclose two useful traits: the method (embedding cosine distance + negation heuristics) and that the tool is read-only. However, it says nothing about runtime cost, scope limits, or the shape of results.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight fragments, zero padding, and the core purpose is front-loaded before the implementation note and the read-only flag. Every clause carries information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description would ideally sketch what a scan returns (contradiction pairs, confidence, etc.), and it does not. For a simple two-parameter read-only scan it is minimally adequate but leaves the result shape opaque.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the schema already explains both `action` and the omit-to-scan-top-entities behavior of `entity_name`. The description adds no syntactic or semantic detail beyond that, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: 'Detect semantic contradictions between observations of the same entity.' The bracketed alias note (['alias of cuba_contradiccion']) also distinguishes it from the sibling cuba_contradiccion, so the agent knows the two are functionally the same.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied: the agent can infer you call it when you want contradictions found, and the alias note hints it is interchangeable with cuba_contradiccion. There is no explicit when-to-use, when-not-to-use, or prerequisite statement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[alias of cuba_cronica] Attach facts/lessons/decisions to entities. Also manages episodic memories (specific events with actors/artifacts) via episode_add/episode_list. Timeline view shows chronological history. Auto-creates entity if not found. Dedup gate blocks near-duplicates.
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | Operation to perform. episode_add stores a temporal event; episode_list retrieves events. timeline shows chronological observations+episodes. | |
| actors | No | People/agents involved in episode (for episode_add) | |
| source | No | Who/what created this observation | |
| content | No | Observation or episode text | |
| artifacts | No | Files/resources affected in episode (for episode_add) | |
| entity_name | No | Entity to attach observation/episode to | |
| allow_secret | No | Refused when the text looks like a live credential (token, password, URL with embedded creds). Set true only for a false match — the text is then stored verbatim, in clear, and reachable by search, export and every client. | |
| observations | No | Array of {entity_name, content, observation_type?, source?} objects (for batch_add, max 100) | |
| observation_id | No | Observation UUID (for delete action) | |
| observation_type | No | Type of observation |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations at all, the description carries the full burden but does add real behavioral context: auto-creation of missing entities, a dedup gate blocking near-duplicates, and the differentiation of episode vs timeline storage. It says nothing about destructive delete semantics, batch limits, or the credential-refusal/allow_secret exposure behavior that matter for a mutating multi-action tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four tight sentences, front-loaded with the alias and the core operation, then the episodic/timeline additions and two behavioral caveats. No filler, though the alias-first framing arguably wastes the opening clause.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 7-action tool with 10 parameters, no annotations, and no output schema, the description sketches the shape but leaves delete, list, and batch_add behavior unspecified and gives no return-value or pagination context. Adequate as a minimum-viable overview, not complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents all 10 parameters including enum values for action, source, and observation_type. The description adds only loose mapping of episode_add/episode_list/timeline to the action enum, which the schema itself restates — baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Names a concrete verb+resource ('Attach facts/lessons/decisions to entities') and enumerates the additional functions (episodic memories, timeline view). The alias note points to cuba_cronica, which is a sibling, but nothing states how this differs functionally from memory_remedio, memory_expediente, or cuba_cronica beyond the alias equivalence.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied rather than directed: the description explains that episode_add/episode_list handle events and timeline gives chronological history, so an agent can infer when to pick each action. It never says when to prefer this tool over the many memory_*/cuba_* siblings, nor any prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[alias of cuba_decreto] Record and query architecture/design decisions.
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | Search text (for query action) | |
| title | No | Decision title (for record) | |
| action | Yes | Decision action | |
| chosen | No | Option chosen | |
| context | No | Why this decision was needed | |
| rationale | No | Why this option was chosen | |
| allow_secret | No | Refused when the text looks like a live credential (token, password, URL with embedded creds). Set true only for a false match — the text is then stored verbatim, in clear, and reachable by search, export and every client. | |
| alternatives | No | Options considered |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden and it discloses essentially nothing: not that records persist and are searchable/exportable, not that the secret heuristic can refuse input, not that this is a lightweight alias. The allow_secret schema text carries the one real behavioral signal, not the description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One compact bracketed alias note plus a single verb-resource sentence; front-loaded and free of padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 8-parameter tool with no annotations and no output schema, the description is too thin: it never enumerates the three actions, never explains persistence or retrieval scope, and leaves the agent to reconstruct intent from the schema alone.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so every parameter including allow_secret and its implications is already documented in the schema. The description adds no parameter-level meaning, which is the expected baseline when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Names a specific verb pair (record/query) and resource (architecture/design decisions), and discloses it is an alias of cuba_decreto, which helps an agent reason about duplicate siblings. However it omits the third supported action 'list', so the purpose statement is not fully accurate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to record versus query, when to use list, or how this differs from related siblings like memory_proyecto or memory_contradiccion. The agent must infer usage entirely from the action enum.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[alias of cuba_eco] RLHF feedback: positive boosts importance (Oja's rule), negative decreases, correct updates content. Also the quarantine gate: 'pending' lists memories withheld from search because they came from untrusted text, 'promote' makes one retrievable, 'quarantine' withdraws one. The gate covers observations, episodes and errors — pick which with 'kind'.
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | Target UUID for promote/quarantine when kind is episode or error. For kind=observation use observation_id. | |
| kind | No | Which table promote/quarantine acts on. Default 'observation'. An import quarantines whatever carried a credential, and cuba_sync writes episodes and errors too: without the matching kind those rows would stay stored and permanently unreachable. Ignored by positive/negative/correct, and by pending, which always returns all three. | |
| limit | No | Max rows for the 'pending' listing (default 20, max 200) | |
| action | Yes | Feedback type, or a quarantine transition: promote/quarantine flip one memory's retrievability; pending lists everything currently withheld, in three lists (quarantined, quarantined_episodes, quarantined_errors), each row tagged with its kind. | |
| correction | No | New content (for correct action) | |
| entity_name | No | Target entity | |
| allow_secret | No | Refused when the text looks like a live credential (token, password, URL with embedded creds). Set true only for a false match — the text is then stored verbatim, in clear, and reachable by search, export and every client. | |
| observation_id | No | Target observation UUID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full disclosure burden. It usefully explains the Oja's-rule importance effect and the retrievability semantics of the gate, plus that 'pending' withholds memories from search because they came from untrusted text. It omits permissions, persistence/reversibility guarantees, and response shape, leaving meaningful gaps for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two compact sentences that front-load the alias and primary purpose before the gate explanation. Dense but largely earning its place; the bracketed alias and repeated comma-clauses add minor friction.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 8 parameters, no output schema, and no annotations, the description covers the core action and gate behavior adequately and explains the important allow_secret-style nuance indirectly. Some parameter-level detail (entity_name, output format) is left to the schema, but nothing critical to calling it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents every parameter richly (including enum meanings for kind/action). The description adds conceptual framing for 'kind' spanning observations, episodes, and errors but no syntax or format detail beyond the schema. Baseline 3 is appropriate when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states concrete verbs and resources: RLHF-style feedback (positive/negative/correct) and a quarantine gate (promote/quarantine/pending). The bracketed '[alias of cuba_eco]' distinguishes it from that sibling explicitly. It stops just short of a crisp one-line statement, folding two capabilities into a dense paragraph.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explains what each action does conditionally (positive boosts, negative decreases, correct updates, promote makes retrievable, quarantine withdraws), which implies when to pick each. However, it gives no explicit when-not guidance and never routes to an alternative tool among the many siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[alias of cuba_expediente] Search past errors/solutions. Use 'proposed_action' as anti-repetition guard: warns if similar approach previously failed.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Search text for errors | |
| project | No | Filter by project | |
| resolved_only | No | Only return errors with solutions | |
| proposed_action | No | Anti-repetition: describe what you plan to do. Returns warning if similar approach failed before. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It usefully discloses the anti-repetition warning behavior triggered by proposed_action, but says nothing about return format, permissions, or result semantics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two compact sentences with the core purpose front-loaded and no wasted words. The alias note is placed first, which is mildly noisy but does not bury the main function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema and no annotations, so the description must stand alone for a search tool. It is adequate for selection but thin on what a result set looks like or how the warning surfaces.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all four parameters including the anti-repetition meaning of proposed_action. The description largely restates what the schema provides, so baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Search') and resource ('past errors/solutions'), so an agent knows it retrieves prior failure/solution records. It does not distinguish itself from the many sibling tools (memory_remedio, memory_cronica, etc.) beyond noting it is an alias of cuba_expediente.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied ('search past errors/solutions') and the proposed_action guard condition is stated, but there is no explicit when-to-use or when-not-to-use guidance versus the numerous sibling memory_/cuba_ tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[alias of cuba_faro] Search memory BEFORE answering to ground responses. Returns grounding scores. Mode 'verify' checks claims against evidence (confidence: verified/partial/weak/unknown). Session-aware: boosts results matching active session goals. Supports temporal filtering. Optional MMR diversification, OOD abstention and an exact tiktoken-based token budget.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | Search mode (default: hybrid). 'verify' checks if claim is grounded. | |
| tags | No | Filter observations by tag keyword (exact match against auto-extracted tags) | |
| after | No | ISO8601 datetime — return results created after this time | |
| limit | No | Max results (default 10, max 50) | |
| query | Yes | Search text | |
| scope | No | Where to search (default: all) | |
| before | No | ISO8601 datetime — return results created before this time | |
| format | No | Response format. compact (DEFAULT): abbreviated keys — e=entity, c=content, t=type, i=importance, s=score. 71% fewer tokens (798 vs 2787 at limit=10, measured). verbose: full key names, only when you need every field. | |
| rerank | No | Cross-encoder rerank top-50 → top-K with bge-reranker-v2-m3. Auto-enabled when CUBA_MODE=completo, or when this build has a real GPU provider active (CUDA/DirectML compiled in AND a working device). Off by default everywhere else, even with the model on disk: on CPU it costs 60-110s and blows the search budget. Explicit true/false always wins; run `cuba-memorys doctor` to see which reason applies here. | |
| diversify | No | Post-RRF MMR pass that penalizes near-duplicates among top-K. Default false. | |
| max_tokens | No | Token budget for results (default 5000). Counted exactly via tiktoken cl100k_base. | |
| mmr_lambda | No | MMR balance — 1.0 pure relevance, 0.0 pure diversity. Default 0.7. | |
| abstain_ood | No | Abstain (return empty results with abstain_reason) when the query is out-of-distribution via Mahalanobis distance. Default false. | |
| associative | No | Multi-hop expansion: seeds spreading activation from query-matched entities and pulls in observations on graph-connected entities that no lexical/vector signal surfaced. Additive — never lowers a base hit. Default false. | |
| enable_bm25 | No | Enable BM25 (ts_rank_cd) as third RRF signal alongside text + vector. Catches queries with rare terms that dense embeddings miss. Default true. | |
| ood_threshold | No | Mahalanobis distance threshold for abstention. Defaults to sqrt(chi2_0.99(d)), which scales with the embedding dimension (~21.25 for d=384). Override only if you calibrated on your own corpus. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does reasonably well: it discloses grounding-score returns, session-aware boosting against active goals (not visible in the schema), temporal filtering, and optional MMR/OOD/token-budget behavior. It never states the read-only nature or any auth/permission prerequisites, so it is not fully complete.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core action and intent, then packs mode, session-awareness, and the optional feature set into a tight block. The trailing feature list reads slightly like a spec dump but every clause carries information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 16-parameter tool with no annotations and no output schema, the description orients the agent well on purpose, modes, and the major behavioral toggles. It does not describe the shape of the returned results beyond "grounding scores," which is a modest gap given there is no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds genuine meaning beyond the schema by spelling out the verify-mode confidence taxonomy (verified/partial/weak/unknown) and the grounding-score output, which no parameter field explains.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource (search memory), plus the higher-order intent (ground responses BEFORE answering) and the alias relationship to cuba_faro. It does not differentiate itself from the many other memory_* siblings, which is the only thing keeping it from a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
"Search memory BEFORE answering to ground responses" gives clear timing/context for use, and the mode 'verify' guidance describes a distinct usage scenario for claim-checking. No explicit when-not or named alternatives among siblings, so it stops short of 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[alias of cuba_forget] GDPR Right to Erasure: cascading hard-delete of an entity and ALL references across observations, relations, errors, and sessions. IRREVERSIBLE. Requires confirm=true.
| Name | Required | Description | Default |
|---|---|---|---|
| confirm | Yes | Must be true to proceed (safety gate) | |
| entity_name | Yes | Entity name to erase completely |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden and does so well: it discloses cascading deletion across observations, relations, errors, and sessions, marks the action IRREVERSIBLE, and requires confirm=true. This is the critical information an agent needs before invoking a destructive tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two dense sentences with no waste. The scope, irreversibility, and safety gate are front-loaded and easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive tool with no annotations and no output schema, the description covers the essential scope, effect, and confirmation requirement. It does not describe return values or error behavior, but those omissions are minor for a hard-delete operation whose result is implicit.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the schema already states that confirm must be true and entity_name is the entity to erase. The description reinforces confirm=true but adds no additional parameter meaning beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: cascading hard-delete of an entity and all references. It also distinguishes this as the alias of cuba_forget, making the relationship to that sibling clear. An agent can tell exactly what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It frames the tool for GDPR Right to Erasure and notes the confirm=true gate, giving clear context for when to use it. However, it does not explicitly state when not to use it or name alternative tools beyond the alias relationship.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[alias of cuba_hipotesis] Abductive inference: find plausible causes of an observed effect. Read-only.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max hypotheses to return (default 10, max 50) | |
| action | Yes | explain: traverse causal relations backwards from `effect`, ranked by path_strength × importance. | |
| effect | Yes | Entity name representing the observed effect | |
| max_depth | No | Max causal chain hops (default 3, max 5) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It discloses 'Read-only', which is the key safety trait, but says nothing about cost/latency of the backward traversal, whether results are exhaustive, or what the response contains.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences with the alias relationship and core purpose front-loaded, followed by the safety trait. Nothing is wasted, though it is minimal to the point of under-specification.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and no annotations, the description should do more to characterize the return (ranked hypotheses, format). The schema covers inputs well, so the gap is mostly in behavioral and output context, keeping this at a minimum-viable 3.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so action, effect, limit, and max_depth are already fully documented in the schema. The description adds no parameter meaning beyond what the structured fields provide, making the baseline 3 correct.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource: abductive inference that finds plausible causes of an observed effect. The '[alias of cuba_hipotesis]' note clarifies its relationship to a sibling, but it doesn't distinguish its purpose from other causal/reasoning siblings like memory_contradiccion or memory_reflexion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No when-to-use guidance, no exclusions, and no routing between this alias and cuba_hipotesis or the other reasoning tools. The agent must infer usage from the one-line purpose statement alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[alias of cuba_ingesta] Bulk knowledge ingestion. 'ingest': array of {entity_name, content, observation_type} items. 'parse': split long text by paragraphs + heuristic classify. 'auto_extract' (v0.11): the calling client's LLM extracts salient durable facts from a turn/conversation via MCP Sampling ($0, no API key) and ingests them — the automatic-extraction that mem0/Zep have. All routes share the dedup/PE-gating/embedding pipeline; none delete.
| Name | Required | Description | Default |
|---|---|---|---|
| text | No | Raw text: paragraphs to split (parse) or a turn/conversation to extract facts from (auto_extract) | |
| items | No | Array of {entity_name, content, observation_type?} objects (for ingest action, max 200) | |
| action | Yes | Ingestion mode. Default 'ingest' is the fast raw path (no LLM). 'parse' splits long text. 'auto_extract' is opt-in LLM extraction via MCP sampling — do not use it as the default write. | ingest |
| untrusted | No | Set when the text came from somewhere you do not control (a fetched page, a pasted document, a third party). Everything extracted lands quarantined — stored and inspectable via cuba_eco action=pending, but withheld from cuba_faro until promoted. Default false. | |
| entity_hint | No | Optional main-subject hint for auto_extract (biases entity_name) | |
| entity_name | No | Entity to attach parsed observations to (for parse action) | |
| allow_secret | No | Refused when the text looks like a live credential (token, password, URL with embedded creds). Set true only for a false match — the text is then stored verbatim, in clear, and reachable by search, export and every client. | |
| supersede_conflicts | No | v0.11 (auto_extract): when a new fact replaces/contradicts an existing related one, ask the judge and mark the old observation superseded (knowledge-update; never deletes). Default false. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does substantial work: 'none delete' (non-destructive guarantee), the shared dedup/PE-gating/embedding pipeline, quarantine behavior for untrusted input (withheld from cuba_faro until promoted), and the irreversible consequence of allow_secret ('stored verbatim, in clear, and reachable by search, export and every client'). It stops short of describing return values or rate/permission behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core purpose and alias, then organized by mode/behavior. Dense but every clause carries information; a few parenthetical asides (v0.11, mem0/Zep comparison) are decorative but brief.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 3-mode, 8-param mutation tool with no output schema and no annotations, the description covers routing, safety (untrusted quarantine, secret refusal, no deletion), and conflict handling well. The main omission is what a call returns after ingestion (counts, ids, errors), which an agent would need to confirm success.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all 8 parameters including the action enum and defaults. The description adds marginal color (e.g., the items shape and the meaning of 'PE-gating', the entity_hint bias) but largely restates the schema's own param descriptions. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Bulk knowledge ingestion') and enumerates the three modes with distinct semantics ('ingest' raw path, 'parse' splitting, 'auto_extract' sampling-based LLM extraction). It clearly describes what the tool does, though it does not differentiate itself from the many similarly named sibling tools (cuba_ingesta aside, which it flags as its alias).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives per-mode guidance: 'ingest' is the fast default with no LLM, 'parse' is for long text, and 'auto_extract' is explicitly opt-in with 'do not use it as the default write.' It also explains the untrusted and supersede_conflicts conditions. It lacks guidance on choosing this tool over sibling ingestion-adjacent tools, but within the tool's own branching the routing advice is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[alias of cuba_jornada] Track working sessions with goals and outcomes. v0.8: optional 'project' arg binds the session to a named project (upserts in brain_projects); subsequent handlers will scope reads/writes to that project.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Session name (for start) | |
| goals | No | Session goals (for start) | |
| action | Yes | Session action | |
| outcome | No | Session outcome (for end) | |
| project | No | v0.8: project name to bind this session to (created on first use). Omit to keep session global. | |
| summary | No | What was accomplished (for end) | |
| allow_secret | No | Refused when the text looks like a live credential (token, password, URL with embedded creds). Set true only for a false match — the text is then stored verbatim, in clear, and reachable by search, export and every client. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It does add real behavioral context: the optional project arg upserts into brain_projects and later handlers scope reads/writes to it. However, it never states that start/end persist data, whether sessions are retrievable, or what the credential-refusal path means for callers beyond the schema text.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two compact sentences, front-loaded with the alias and the core purpose, then the versioned behavior note. Minimal waste, though the 'v0.8' and 'subsequent handlers' phrasing is somewhat internal-facing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no annotations and no output schema, the description must cover behavior on its own. It covers the project-binding side effect but says nothing about return values for list/current or what a completed session record contains, leaving a gap for a 7-parameter mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so every parameter (including action enum, allow_secret's credential guard, and project's global-fallback behavior) is already documented in the schema. The description's project note largely restates what the schema says, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: track working sessions with goals and outcomes, and flags itself as an alias of cuba_jornada. This distinguishes it from sibling memory tools at a high level, though many siblings (jornada, cronica, eco) share the 'session/memory' family and the description doesn't contrast them explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by enumerating the session lifecycle (start/end goals and outcomes) and by the project-binding note, but there is no explicit when-to-use or when-not-to-use versus cuba_jornada or memory_cronica/cuba_cronica. The agent must infer that this is the read/track counterpart.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[alias of cuba_juez] LLM-judge for semantically-conflicting observations in the ambiguous cosine-similarity band (0.6-0.8), where heuristics miss vocabulary-different conflicts. Verdicts are cached in brain_judgments.
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | judge_pair: decide on two given observation ids. scan_entity: pull ambiguous pairs for an entity and judge each. | |
| max_pairs | No | Max pairs to escalate per call (default 5; controls LLM cost) | |
| entity_name | No | Entity to scan (for scan_entity) | |
| observation_a | No | UUID of first observation (for judge_pair) | |
| observation_b | No | UUID of second observation (for judge_pair) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It discloses that verdicts are cached in brain_judgments and implies LLM cost via the judge role, but does not cover permissions, mutation semantics, or failure behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no wasted words. The alias and core purpose are front-loaded before the caching detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No annotations and no output schema mean the description should do more to explain return values and side effects. It covers the judge’s scope and caching but leaves the output format and mutation implications unspecified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all five parameters. The description adds no parameter-level meaning beyond what the schema provides, making the baseline 3 appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific function: an LLM judge for semantically conflicting observations in a defined cosine-similarity band. It also names the alias relationship with cuba_juez and distinguishes itself from heuristics, though it does not differentiate from all sibling memory tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Clearly indicates when to use it: the ambiguous 0.6-0.8 cosine-similarity band where heuristics miss vocabulary-different conflicts. It implies heuristics as an alternative but does not explicitly list when-not or other alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[alias of cuba_pizarra] Working memory buffer (v0.9, Baddeley 1992): a TTL-bounded scratchpad orthogonal to episodic and semantic memory. Use for inter-step plan state during long-horizon agent tasks, tentative observations, cross-tool-call reminders inside one session. Auto-expire by ttl_seconds; bulk-purged by cuba_zafra REM cycle.
| Name | Required | Description | Default |
|---|---|---|---|
| tag | No | Optional tag for filtering on read/clear | |
| action | Yes | Working-memory operation | |
| content | No | Content to store (for write) | |
| ttl_seconds | No | Time-to-live in seconds (default 3600) | |
| allow_secret | No | Refused when the text looks like a live credential (token, password, URL with embedded creds). Set true only for a false match — the text is then stored verbatim, in clear, and reachable by search, export and every client. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does reasonably well: it discloses that entries auto-expire by ttl_seconds (default 3600 per schema) and are bulk-purged by the cuba_zafra REM cycle. This is real behavioral context an agent needs. It does not discuss auth requirements or exactly what clear/read return, leaving some gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two compact sentences, front-loaded with the alias and the core identity, with the usage guidance following. No filler, though the parenthetical version/author citation is decorative rather than load-bearing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a no-output-schema, five-parameter write/read/clear tool, the description covers the lifecycle (auto-expire, REM purge) and usage context adequately. It omits return-value behavior for read/clear, but overall an agent has enough to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all five parameters including the allow_secret caveat. The description adds TTL context but no per-parameter syntax or format detail beyond what the schema provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific resource (working memory buffer/scratchpad) with a clear verb-neutral framing of what it stores and its TTL-bounded, orthogonal-to-episodic/semantic nature. It even flags itself as an alias of cuba_pizarra. It does not clearly enumerate that the tool is a multi-action (write/read/clear) surface, so the agent must open the schema to learn the actual operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives concrete when-to-use context: inter-step plan state during long-horizon tasks, tentative observations, cross-tool-call reminders within a session. The 'orthogonal to episodic and semantic memory' clause implicitly routes the agent away from those siblings, but no sibling is named or excluded explicitly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[alias of cuba_pre_compact] Compaction-survival protocol: persist and restore a session summary across /compact.
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | snapshot: before /compact, persists a dense markdown summary (observations, decisions, unresolved errors, pending embeddings, goals) for the active session. restore: after /compact, retrieves the latest snapshot and re-injects it into context. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It indicates that data is persisted and restored, but does not disclose storage location, permissions, reversibility, side effects, or what exactly gets re-injected. This is a significant gap for a tool that writes and restores session state.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single compact sentence with an alias tag. It is front-loaded and contains no redundant or filler language.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter enum tool with full schema description coverage and no output schema, the description sufficiently communicates the overall purpose and compaction timing. It is somewhat incomplete on behavioral and alternative-tool details, but the low parameter complexity makes that less critical.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the single action parameter has a detailed enum description covering both snapshot and restore. The description itself adds little parameter detail beyond mapping 'persist' and 'restore' to the two actions, so the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb pair and resource: 'persist and restore a session summary across /compact.' It also identifies the tool as an alias of cuba_pre_compact. However, it does not explicitly differentiate itself from the many sibling memory_/cuba_ tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'across /compact' gives clear timing context for when the tool is relevant, and the schema enum description clarifies snapshot before /compact and restore after /compact. There are no explicit exclusions or named alternatives, but the usage context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[alias of cuba_proyecto] Project scoping (v0.8): isolate memories per project so multiple projects sharing one DB don't bleed into each other. Active project is bound to the current session (cuba_jornada start --project NAME). Legacy rows with NULL project_id remain visible from every scope.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | Destination name (for rename/merge) | |
| name | No | Project name (for switch/stats/rename source) | |
| action | Yes | Project action |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden and partially meets it: it discloses the non-obvious rule that legacy rows with NULL project_id stay visible from every scope, which is genuine added context. However, it says nothing about the effects of rename/merge (destructive?), permissions, or whether switching persists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences with no filler, and the scoping premise is front-loaded ahead of the legacy-row caveat. The 'alias of cuba_proyecto' prefix is the only slightly wasteful element.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
A six-action tool with no annotations, no output schema, and no per-action explanation leaves major gaps: what stats returns, what merge combines, what rename changes, and what list emits are all unaddressed. The conceptual framing does not compensate for this.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter and the action enum already documented in the schema, so the baseline is 3. The description adds only the session-binding concept, no syntax or format detail beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explains the domain concept (isolating memories per project, session binding) but never states what the tool itself does with the six actions it exposes (list/current/switch/stats/rename/merge). 'alias of cuba_proyecto' is metadata rather than purpose. An agent learns the topic but not the verb+resource of the call.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It references cuba_jornada start --project NAME for binding, but gives no guidance on when to invoke memory_proyecto versus the many sibling memory_*/cuba_* tools, nor when each action is appropriate. No exclusions or prerequisites stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[alias of cuba_puente] Create edges between entities (uses, causes, implements, depends_on, related_to). 'traverse' explores connections, 'infer' does transitive reasoning (A→B→C), 'predict' suggests missing links via Adamic-Adar. Relations strengthen with use (Hebbian).
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | Operation to perform. 'predict' uses Adamic-Adar to suggest missing relations. | |
| persist | No | For predict: write the suggestions to brain_relations as provenance='predicted' (relation_type related_to) instead of only returning them. Default false — read-only. | |
| max_depth | No | Max hops for traverse/infer (default 3, max 5) | |
| to_entity | No | Target entity name | |
| entity_name | No | Entity name for predict action (Adamic-Adar link prediction) | |
| from_entity | No | Source entity name | |
| start_entity | No | Start point for traverse/infer | |
| bidirectional | No | If true, relation goes both ways | |
| relation_type | No | Relation: uses, causes, implements, depends_on, related_to. Also used by predict+persist to pick the type for the persisted edge (default related_to). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It usefully discloses that relations strengthen with use (Hebbian) and how predict works via Adamic-Adar, adding behavioral context. But it never covers the 'delete' action's reversibility or permissions, nor any auth or persistence semantics beyond what the schema already states for persist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Dense but efficient: the alias note leads, then capabilities are front-loaded, and each clause carries information. No filler sentences, though the concatenated style is slightly terse for a 9-param multi-action tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a multi-action, 9-parameter tool with no annotations and no output schema, the description covers the interesting actions but omits the delete action entirely and does not describe return shapes. It is adequate for the primary create/traverse/infer path but leaves gaps an agent would notice.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents every parameter including persist, max_depth, and relation_type. The description's restatement of relation types matches the schema, and its added depth (transitive A→B→C, Adamic-Adar) is useful but marginal against a fully documented schema, warranting the baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a concrete resource (edges between entities) and enumerates the relation types, then explains the non-obvious action modes (traverse, infer, predict). It is clear what the tool operates on, though the leading verb 'Create edges' undersells that the tool also deletes, traverses, and predicts, and it does not distinguish the tool from the many sibling memory_* tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explains what each action mode does ('traverse' explores, 'infer' does transitive reasoning, 'predict' suggests missing links), which implies usage. However, it gives no guidance on when to choose this tool over siblings like memory_contradiccion or memory_reflexion, and no prerequisites or when-not-to-use conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[alias of cuba_receta] PROCEDURAL MEMORY: how things are DONE here — bring up the dev services, run the test suite, deploy, migrate. The other tools remember what is TRUE; this one remembers what to DO, so an agent stops rediscovering it every session. Ranked by reliability, not by how often it is read: report the outcome with action='outcome' after running one, or the memory learns nothing. A recipe that keeps failing is worse than none, because it is trusted.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Procedure name, e.g. 'levantar el entorno de desarrollo' | |
| limit | No | Max results | |
| query | No | For action=search | |
| steps | No | Ordered steps: [{do: '...', run: 'comando'?, expect: 'qué debe pasar'?}] | |
| action | Yes | search: find by meaning. get: fetch by exact name. add: store/update (re-adding the same name edits it, keeping its track record). outcome: record success/failure — this is what teaches it. | |
| success | No | For action=outcome: did it work? | |
| trigger | No | WHEN this applies — the IF half. e.g. 'cuando hay que levantar los servicios de mapupita-web' | |
| allow_secret | No | Refused when the text looks like a live credential (token, password, URL with embedded creds). Set true only for a false match — the text is then stored verbatim, in clear, and reachable by search, export and every client. | |
| verification | No | How you know it actually worked | |
| preconditions | No | What must already be true before starting |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden and does well: it discloses that entries are ranked by reliability rather than read count, that a failing recipe is dangerous because it is 'trusted', and that results must be reported via outcome or nothing is learned. The secret-handling behavior (allow_secret refusal) is documented in the param, not the description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core definition followed by the contrast and the feedback instruction. Every sentence earns its place, though 'worse than none, because it is trusted' is slightly rhetorical flourish rather than load-bearing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 10-parameter, no-output-schema tool, the description supplies the operational model (add/get/search/outcome lifecycle and ranking) that the schema alone lacks. It does not describe what get/search actually return, a minor gap given the absence of an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds real meaning beyond the schema by explaining the outcome feedback loop ('this is what teaches it') and the reliability-ranking model, giving the 'outcome' action a purpose the schema alone does not convey.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
It states a specific verb+resource ('PROCEDURAL MEMORY: how things are DONE') and contrasts directly with sibling memories ('The other tools remember what is TRUE; this one remembers what to DO'). An agent can distinguish it from memory_remedio/memory_expediente without opening a schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It frames the usage context clearly (procedures vs facts) and instructs the agent to call action='outcome' after running a recipe, which is a concrete when-to-use rule. It does not name specific sibling alternatives (e.g. memory_remedio) or give exclusions, so it stops short of the top score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[alias of cuba_reflexion] Analyze the knowledge graph for structural gaps. Read-only.
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | analyze: the only action. Reports isolated entities, underconnected hubs, type silos, observation gaps (missing decisions/lessons), and statistical density anomalies. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are supplied, so the description carries the full burden. It does disclose the most important behavioral trait — 'Read-only' — which tells the agent no graph state is mutated. However it says nothing about cost, authentication, or how results are returned, leaving meaningful gaps for a no-annotation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short, front-loaded sentences with the alias routing first and the safety claim last. Nothing is redundant, though 'Read-only.' is a fragment that could have been folded into the purpose sentence.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter, no-output-schema analysis tool this is adequate: the schema enumerates the reported anomaly categories, so return content is covered. What is missing is usage context — when an agent should run this versus the many sibling analysis tools — which matters given the dense sibling set.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the single enum parameter is documented in detail, including exactly which gap categories are reported. The description adds no parameter information beyond that, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Analyze') and resource ('knowledge graph'), narrowed by 'structural gaps'. The alias note '[alias of cuba_reflexion]' usefully disambiguates it from the large family of cuba_/memory_ sibling pairs, though it does not differentiate it from analysis-adjacent siblings like memory_contradiccion or memory_calibrar.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use guidance, no statement of prerequisites, and no routing to alternatives. The only usage constraint ('analyze: the only action') comes from the schema enum, not the description, so the description itself provides essentially nothing about when this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[alias of cuba_remedio] Mark an error as resolved with solution. Cross-references similar unresolved errors.
| Name | Required | Description | Default |
|---|---|---|---|
| error_id | Yes | UUID of the error to solve | |
| solution | Yes | Solution that fixed the error | |
| allow_secret | No | Refused when the text looks like a live credential (token, password, URL with embedded creds). Set true only for a false match — the text is then stored verbatim, in clear, and reachable by search, export and every client. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It says the tool marks an error as resolved and cross-references similar unresolved errors, but it does not disclose permissions, side effects, reversibility, storage behavior, or how the cross-referencing affects other records. The critical allow_secret behavior is only described in the schema, not the description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one compact sentence plus an alias tag, with no wasted language. The alias is front-loaded before the action, which is slightly less ideal, but the definition remains easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations and no output schema, the description is thin. It does not explain the effect of cross-referencing similar unresolved errors, return behavior, or secret-handling implications. The schema covers parameters, but the behavioral context an agent needs is largely missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the input schema already documents error_id, solution, and allow_secret in detail. The description adds no additional parameter meaning beyond what the schema provides, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Mark an error as resolved with solution.' It also adds the cross-referencing behavior. The alias note '[alias of cuba_remedio]' signals it is a duplicate of the sibling cuba_remedio, which helps selection, though it does not distinguish broader use cases.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is used to resolve an error with a solution, but it gives no explicit when-to-use guidance, no when-not-to-use conditions, and no alternatives among the many memory_/cuba_ sibling tools. The agent must infer that this is for marking errors resolved.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[alias of cuba_sync] Git-friendly export/import of the knowledge graph between machines that share no database. export/import/diff/status work on a local directory (default ./.cuba-memorys/); pull/notify/fetch/conflicts/resolve talk to a peer over HTTP with CUBA_PEER_TOKEN.
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | resolve only: the conflict id from action=conflicts | |
| dir | No | Directory override (default $CUBA_SYNC_DIR or ./.cuba-memorys/) | |
| url | No | fetch only: the peer's base address, e.g. https://brain.example.net | |
| keep | No | resolve only: which text stays current (default 'both', which loses nothing) | |
| peer | No | fetch only: which peer to pull from (default 'default') | |
| limit | No | pull only: max files per page | |
| scope | No | Export scope: active project only (default) or all data | |
| action | Yes | export/import/diff/status: local bundle round-trip. pull: return the bundle in the response instead of writing it, for a peer to fetch. notify: tell a peer what changed. fetch: pull a peer's bundle over HTTP and import it. conflicts/resolve: list and settle rows two machines disagree about. | |
| offset | No | pull only: index of the first bundle file to return | |
| confirm | No | Required when the import's tombstones would delete more than 10% of this machine's observations and at least 25 rows | |
| node_id | No | notify only: self-asserted id of the sending node | |
| summary | No | notify only: what changed, in at most 2000 characters | |
| conflict | No | How to resolve a row that exists on both sides (default merge; merge and skip keep local content, overwrite takes the incoming version) | |
| node_name | No | notify only: readable name of the sending node | |
| manifest_hash | No | notify only: the bundle hash this notice refers to | |
| with_embeddings | No | Include embeddings (default false on export, true on pull) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It usefully discloses a real behavioral constraint the schema never states — peer actions require CUBA_PEER_TOKEN over HTTP — plus the default sync directory. It does not disclose the destructive potential of import (schema's 'confirm' hints at tombstone-driven deletion), reversibility, or conflict-write side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two dense sentences, zero filler: the alias note, the purpose, the local-action list, and the peer-action list with its credential all land in order of importance. Nothing could be removed without losing routing information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 16-parameter, nine-action tool with no output schema and no annotations, the description covers action routing but never explains what any action returns (e.g., diff/status/conflicts output shapes) — a real gap given there is no output schema to fall back on. The destructive import path is only indirectly signposted via the schema's confirm parameter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all 16 parameters, including the per-action scoping of id/url/peer/limit/offset and the 'confirm' deletion threshold. The description adds only grouping-level context (which action families are local vs HTTP) and the default dir, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb+resource ('Git-friendly export/import of the knowledge graph') and adds the key scope qualifier 'between machines that share no database'. It also declares its identity as an alias of cuba_sync, which lets an agent immediately relate it to that sibling rather than guessing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It splits the nine actions into two clear regimes — local-directory actions (export/import/diff/status) versus peer-over-HTTP actions (pull/notify/fetch/conflicts/resolve) — and names the credential (CUBA_PEER_TOKEN) required for the latter. That is strong routing guidance, though it stops short of stating when to prefer a local round-trip over a peer sync or naming any non-sibling alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[alias of cuba_tools] Find cuba-memorys tools and load their schemas ON DEMAND. The server exposes 31 tools; under CUBA_TOOL_PROFILE=lean only the everyday core is pre-loaded and the rest live here. Search by capability ('audit', 'decay', 'contradiction', 'session'), then call what you find with cuba_call. detail='names' is cheapest, 'full' returns the exact argument schema.
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | Filter by capability — matches tool names and descriptions. Omit to list everything. | |
| detail | No | names: just the names. summary (default): name + description. full: the complete JSON Schema, which is what you need to call the tool correctly. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden and does well: it discloses the 31-tool count, the lean-profile gating behavior, the cheapness ordering of detail modes, and that 'full' is required for correct invocation. It omits return-shape/cost specifics beyond the detail hint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three dense sentences, front-loaded with the alias/identity and the on-demand loading model before the search-then-call workflow. Each sentence carries information, though the profile/alias framing is somewhat heavy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description properly explains what each detail level returns and how to proceed to invocation. For a 2-param discovery tool this is essentially complete, missing only explicit pagination/listing-size behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% so the baseline is 3, but the description adds real interpretation: query matches names and descriptions and can be omitted to list everything, and detail='names' is cheapest while 'full' yields the exact argument schema needed to call a tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource: find cuba-memory tools and load their schemas on demand, plus its alias relationship to cuba_tools. An agent immediately understands this is a discovery/loader tool and how it differs from the concrete sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explains the triggering context (under CUBA_TOOL_PROFILE=lean the non-core tools live here) and the follow-up workflow ('call what you find with cuba_call'). It does not state explicit exclusions, but the when-to-use condition is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[alias of cuba_vigia] Knowledge graph analytics: summary, health, drift, communities, bridges, structural.
| Name | Required | Description | Default |
|---|---|---|---|
| metric | Yes | summary: counts + token estimate. health: staleness, entropy, DB size. drift: chi-squared on errors. communities: Leiden clustering. bridges: betweenness centrality. structural: harmonic + closeness centrality + k-core ranking (backbone identification). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It does not state whether the tool is read-only, what the return format is, whether it has side effects, or any performance characteristics—a significant gap for an analytics tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single compact sentence with the alias note up front and zero waste. Every word is relevant, and the metric list is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no annotations and no output schema, the description should carry more context about what the tool does (e.g., that it is read-only analytics) and what an agent can expect from each metric. It only names the metrics, leaving behavioral and return-value information entirely to inference.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the enum descriptions fully explain each metric (counts, staleness, chi-squared, Leiden clustering, etc.). The tool description merely repeats the enum values, adding no meaning beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States the resource ('knowledge graph analytics') and lists the six metrics, and identifies the tool as an alias of cuba_vigia. That is clear enough to separate it from most siblings, though the description lacks a verb and does not explain what the analytics actually produce.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no when-to-use guidance, no prerequisites, and no alternatives. It simply lists the metric names, leaving the agent to infer usage from the schema enum descriptions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[alias of cuba_whoami] Identify this MCP client against the MemoryIndustry daemon: client id, project, session, node, LLM, graph-db, resource plan. Alias: memory_whoami.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It usefully lists the fields returned (client id, project, session, node, LLM, graph-db, resource plan), but it does not explicitly state that this is a read-only, side-effect-free operation or disclose any auth or rate-limit behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and front-loads the purpose, with the alias note placed first. The final 'Alias: memory_whoami' sentence is slightly redundant with the tool name, keeping it from being maximally concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple, zero-parameter identity tool with no output schema, the description is nearly complete: it states the purpose, the alias relationship, and the returned fields. It stops short of explaining the return format or confirming read-only safety, but those are minor gaps for this tool type.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, so the baseline score is 4. The description correctly does not add parameter semantics beyond what an empty schema already communicates.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
It states a specific verb ('Identify') and resource ('this MCP client against the MemoryIndustry daemon'), and enumerates the exact identity fields returned. The alias note distinguishes it from other sibling tools by tying it explicitly to cuba_whoami.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The purpose implies when to use it—to retrieve client identity context—but there is no explicit when-to-use statement, no exclusion criteria, and no guidance on alternatives among the many sibling tools. It is adequate but leaves routing inference to the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[alias of cuba_zafra] Memory maintenance, scoped to the active project: decay, prune, merge, summarize, pagerank, find_duplicates, export, reembed, decay_episodes.
| Name | Required | Description | Default |
|---|---|---|---|
| c | No | Power-law c parameter for decay_episodes (default 0.1) | |
| beta | No | Power-law β exponent for decay_episodes (default 0.5) | |
| action | Yes | decay: stratified exponential decay by type. prune: deletes low-importance observations, dry-run unless confirm=true. merge: deduplicates similar entities. summarize: replaces an entity's observations with compressed_summary. stats: counts. pagerank: personalized importance ranking. find_duplicates: lists near-duplicate pairs. export: writes a JSON dump. reembed: re-encodes with the current model. decay_episodes: power-law decay on brain_episodes. | |
| confirm | No | prune only: actually delete. Without it, prune returns a dry-run plan (would_prune, by_project) and deletes nothing — read the plan first, the default threshold reaches a large share of a mature corpus. | |
| threshold | No | Importance threshold for prune (default 0.1) | |
| batch_size | No | Max observations to re-encode in reembed (default 500) | |
| entity_name | No | Entity to summarize (for summarize action) | |
| allow_secret | No | Refused when the text looks like a live credential (token, password, URL with embedded creds). Set true only for a false match — the text is then stored verbatim, in clear, and reachable by search, export and every client. | |
| halflife_days | No | Global halflife override for decay (overrides per-type stratification) | |
| compressed_summary | No | Compressed text replacing observations (for summarize) | |
| similarity_threshold | No | Similarity threshold for merge (default 0.8) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden, yet it discloses only the active-project scoping. Destructive actions bundled into the same tool (prune deletes observations, summarize replaces observations, merge deduplicates) are not flagged in the description; the safety details live only in the schema's per-parameter prose.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence, front-loaded with the alias relationship followed by the action list, with no filler. The alias tag consumes the opening slot that could have carried usage guidance, but the sentence itself is economical.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 11-parameter, multi-action tool with no output schema and no annotations, the description is thin: it gives the action roster but no ordering, destructive-action warnings, or selection logic. The unusually rich schema compensates for most parameter gaps, keeping this at minimum-viable rather than inadequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and the action enum is thoroughly documented in the schema, so the tool meets the baseline where structured data already does the heavy lifting. The description adds no format, default, or interaction details beyond what the schema states.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names the resource (memory), the scope (active project) and enumerates the concrete maintenance actions, so an agent knows this is a memory-upkeep tool rather than an ingest or query tool. It does not, however, explicitly differentiate itself from its sibling cuba_zafra beyond the '[alias of]' tag.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It lists the available actions but gives no guidance on when to choose this tool over its alias cuba_zafra or over the many sibling memory_* tools, nor on which action suits which situation. 'Scoped to the active project' is the only selection hint and it is implicit at best.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.25.0cuba_alarma1 field changedInput schema / properties / allow_secretAdded value: +{
+ "description": "Refused when the text looks like a live credential (token, password, URL with embedded creds). Set true only for a false match — the text is then stored verbatim, in clear, and reachable by search, export and every client.",
+ "type": "boolean"
+}cuba_archivo1 field changedInput schema / properties / action / descriptionPrevious value: -"Audit operation"New value: +"append: add an event. verify: walk the hash chain and detect tampering. tail: read recent events."cuba_artefactocuba_calibrar1 field changedInput schema / properties / action / descriptionPrevious value: -"Calibration action. v0.9: 'trust' returns per-source Beta(α, β) credibility; 'metrics' returns Brier score (1950) + Expected Calibration Error (Naeini AAAI 2015) + reliability diagram."New value: +"stats/history: past predictions. resolve: mark a verify_id correct/incorrect. trust: per-source Beta(α, β) credibility, updated by resolve outcomes. metrics: Brier score + Expected Calibration Error + reliability diagram."cuba_centinela3 fields changedInput schema / properties / action / descriptionPrevious value: -"Trigger action"New value: +"create: define a trigger. list: show triggers. delete: remove one (trigger_id). check: evaluate now."Input schema / properties / allow_secretAdded value: +{
+ "description": "Refused when the text looks like a live credential (token, password, URL with embedded creds). Set true only for a false match — the text is then stored verbatim, in clear, and reachable by search, export and every client.",
+ "type": "boolean"
+}Input schema / properties / condition_type / descriptionPrevious value: -"When to fire"New value: +"When to fire. on_session_start with the other session's name as entity_pattern is also the cross-session note channel: fires once (max_fires) the next time that session starts, carrying who left it."cuba_contextocuba_cronica1 field changedInput schema / properties / allow_secretAdded value: +{
+ "description": "Refused when the text looks like a live credential (token, password, URL with embedded creds). Set true only for a false match — the text is then stored verbatim, in clear, and reachable by search, export and every client.",
+ "type": "boolean"
+}cuba_decreto1 field changedInput schema / properties / allow_secretAdded value: +{
+ "description": "Refused when the text looks like a live credential (token, password, URL with embedded creds). Set true only for a false match — the text is then stored verbatim, in clear, and reachable by search, export and every client.",
+ "type": "boolean"
+}cuba_eco4 fields changedInput schema / properties / action / descriptionPrevious value: -"Feedback type, or a quarantine transition: promote/quarantine flip one observation's retrievability; pending lists what is currently withheld."New value: +"Feedback type, or a quarantine transition: promote/quarantine flip one memory's retrievability; pending lists everything currently withheld, in three lists (quarantined, quarantined_episodes, quarantined_errors), each row tagged with its kind."Input schema / properties / allow_secretAdded value: +{
+ "description": "Refused when the text looks like a live credential (token, password, URL with embedded creds). Set true only for a false match — the text is then stored verbatim, in clear, and reachable by search, export and every client.",
+ "type": "boolean"
+}Input schema / properties / idAdded value: +{
+ "description": "Target UUID for promote/quarantine when kind is episode or error. For kind=observation use observation_id.",
+ "type": "string"
+}Input schema / properties / kindAdded value: +{
+ "description": "Which table promote/quarantine acts on. Default 'observation'. An import quarantines whatever carried a credential, and cuba_sync writes episodes and errors too: without the matching kind those rows would stay stored and permanently unreachable. Ignored by positive/negative/correct, and by pending, which always returns all three.",
+ "enum": [
+ "observation",
+ "episode",
+ "error"
+ ],
+ "type": "string"
+}cuba_faro7 fields changedInput schema / properties / abstain_ood / descriptionPrevious value: -"v0.9: abstain (return empty results with abstain_reason) when query is out-of-distribution via Mahalanobis distance. Default false."New value: +"Abstain (return empty results with abstain_reason) when the query is out-of-distribution via Mahalanobis distance. Default false."Input schema / properties / associative / descriptionPrevious value: -"v0.11: multi-hop expansion (HippoRAG-style). Seeds spreading activation from query-matched entities and pulls in observations on graph-connected entities that no lexical/vector signal surfaced. Additive — never lowers a base hit. Measured +10pts recall@10 on the smoke set. Default false."New value: +"Multi-hop expansion: seeds spreading activation from query-matched entities and pulls in observations on graph-connected entities that no lexical/vector signal surfaced. Additive — never lowers a base hit. Default false."Input schema / properties / diversify / descriptionPrevious value: -"v0.9: post-RRF MMR pass that penalizes near-duplicates among top-K. Default false."New value: +"Post-RRF MMR pass that penalizes near-duplicates among top-K. Default false."Input schema / properties / enable_bm25 / descriptionPrevious value: -"v0.9: enable BM25 (ts_rank_cd) as third RRF signal alongside text + vector. Catches queries with rare terms that dense embeddings miss. Default true."New value: +"Enable BM25 (ts_rank_cd) as third RRF signal alongside text + vector. Catches queries with rare terms that dense embeddings miss. Default true."Input schema / properties / mmr_lambda / descriptionPrevious value: -"v0.9: MMR balance — 1.0 pure relevance, 0.0 pure diversity. Default 0.7."New value: +"MMR balance — 1.0 pure relevance, 0.0 pure diversity. Default 0.7."Input schema / properties / ood_threshold / descriptionPrevious value: -"v0.9: Mahalanobis distance threshold for abstention. Defaults to sqrt(chi2_0.99(d)), which scales with the embedding dimension (~21.25 for d=384). Override only if you calibrated on your own corpus."New value: +"Mahalanobis distance threshold for abstention. Defaults to sqrt(chi2_0.99(d)), which scales with the embedding dimension (~21.25 for d=384). Override only if you calibrated on your own corpus."Input schema / properties / rerank / descriptionPrevious value: -"v0.9.2: cross-encoder rerank top-50 → top-K with bge-reranker-v2-m3 (Xiao 2023). Auto-enabled when CUBA_RERANKER_PATH points to a valid ONNX. Identity fallback otherwise."New value: +"Cross-encoder rerank top-50 → top-K with bge-reranker-v2-m3. Auto-enabled when CUBA_MODE=completo, or when this build has a real GPU provider active (CUDA/DirectML compiled in AND a working device). Off by default everywhere else, even with the model on disk: on CPU it costs 60-110s and blows the search budget. Explicit true/false always wins; run `cuba-memorys doctor` to see which reason applies here."cuba_hipotesis1 field changedInput schema / properties / action / descriptionPrevious value: -"Inference action"New value: +"explain: traverse causal relations backwards from `effect`, ranked by path_strength × importance."cuba_ingesta3 fields changedInput schema / properties / action / defaultAdded value: +"ingest"Input schema / properties / action / descriptionPrevious value: -"Ingestion mode. 'ingest' for structured items, 'parse' for raw text splitting, 'auto_extract' for LLM extraction via MCP sampling."New value: +"Ingestion mode. Default 'ingest' is the fast raw path (no LLM). 'parse' splits long text. 'auto_extract' is opt-in LLM extraction via MCP sampling — do not use it as the default write."Input schema / properties / allow_secretAdded value: +{
+ "description": "Refused when the text looks like a live credential (token, password, URL with embedded creds). Set true only for a false match — the text is then stored verbatim, in clear, and reachable by search, export and every client.",
+ "type": "boolean"
+}cuba_jornada1 field changedInput schema / properties / allow_secretAdded value: +{
+ "description": "Refused when the text looks like a live credential (token, password, URL with embedded creds). Set true only for a false match — the text is then stored verbatim, in clear, and reachable by search, export and every client.",
+ "type": "boolean"
+}cuba_juez1 field changedInput schema / properties / action / descriptionPrevious value: -"judge_pair = decide on two given obs ids; scan_entity = pull ambiguous pairs and judge each"New value: +"judge_pair: decide on two given observation ids. scan_entity: pull ambiguous pairs for an entity and judge each."cuba_pizarra1 field changedInput schema / properties / allow_secretAdded value: +{
+ "description": "Refused when the text looks like a live credential (token, password, URL with embedded creds). Set true only for a false match — the text is then stored verbatim, in clear, and reachable by search, export and every client.",
+ "type": "boolean"
+}cuba_pre_compact1 field changedInput schema / properties / action / descriptionPrevious value: -"snapshot persists a session summary; restore returns the latest"New value: +"snapshot: before /compact, persists a dense markdown summary (observations, decisions, unresolved errors, pending embeddings, goals) for the active session. restore: after /compact, retrieves the latest snapshot and re-injects it into context."cuba_receta1 field changedInput schema / properties / allow_secretAdded value: +{
+ "description": "Refused when the text looks like a live credential (token, password, URL with embedded creds). Set true only for a false match — the text is then stored verbatim, in clear, and reachable by search, export and every client.",
+ "type": "boolean"
+}cuba_reflexion1 field changedInput schema / properties / action / descriptionPrevious value: -"Gap analysis action (only 'analyze' supported)"New value: +"analyze: the only action. Reports isolated entities, underconnected hubs, type silos, observation gaps (missing decisions/lessons), and statistical density anomalies."cuba_remedio1 field changedInput schema / properties / allow_secretAdded value: +{
+ "description": "Refused when the text looks like a live credential (token, password, URL with embedded creds). Set true only for a false match — the text is then stored verbatim, in clear, and reachable by search, export and every client.",
+ "type": "boolean"
+}cuba_sync16 fields changedInput schema / properties / action / descriptionPrevious value: -"Sync mode"New value: +"export/import/diff/status: local bundle round-trip. pull: return the bundle in the response instead of writing it, for a peer to fetch. notify: tell a peer what changed. fetch: pull a peer's bundle over HTTP and import it. conflicts/resolve: list and settle rows two machines disagree about."Input schema / properties / action / enumPrevious value: -[
- "export",
- "import",
- "diff",
- "status"
-]New value: +[
+ "export",
+ "import",
+ "diff",
+ "status",
+ "pull",
+ "notify",
+ "fetch",
+ "conflicts",
+ "resolve"
+]Input schema / properties / confirmAdded value: +{
+ "description": "Required when the import's tombstones would delete more than 10% of this machine's observations and at least 25 rows",
+ "type": "boolean"
+}Input schema / properties / conflict / descriptionPrevious value: -"Import conflict policy (default merge)"New value: +"How to resolve a row that exists on both sides (default merge; merge and skip keep local content, overwrite takes the incoming version)"Input schema / properties / idAdded value: +{
+ "description": "resolve only: the conflict id from action=conflicts",
+ "type": "string"
+}Input schema / properties / keepAdded value: +{
+ "description": "resolve only: which text stays current (default 'both', which loses nothing)",
+ "enum": [
+ "ours",
+ "theirs",
+ "both"
+ ],
+ "type": "string"
+}Input schema / properties / limitAdded value: +{
+ "description": "pull only: max files per page",
+ "type": "integer"
+}Input schema / properties / manifest_hashAdded value: +{
+ "description": "notify only: the bundle hash this notice refers to",
+ "type": "string"
+}Input schema / properties / node_idAdded value: +{
+ "description": "notify only: self-asserted id of the sending node",
+ "type": "string"
+}Input schema / properties / node_nameAdded value: +{
+ "description": "notify only: readable name of the sending node",
+ "type": "string"
+}Input schema / properties / offsetAdded value: +{
+ "description": "pull only: index of the first bundle file to return",
+ "type": "integer"
+}Input schema / properties / peerAdded value: +{
+ "description": "fetch only: which peer to pull from (default 'default')",
+ "type": "string"
+}Input schema / properties / scope / descriptionPrevious value: -"Export scope: only the active project (default) or all data"New value: +"Export scope: active project only (default) or all data"Input schema / properties / summaryAdded value: +{
+ "description": "notify only: what changed, in at most 2000 characters",
+ "type": "string"
+}Input schema / properties / urlAdded value: +{
+ "description": "fetch only: the peer's base address, e.g. https://brain.example.net",
+ "type": "string"
+}Input schema / properties / with_embeddings / descriptionPrevious value: -"Include the embeddings.bin.zst blob on export (default false)"New value: +"Include embeddings (default false on export, true on pull)"cuba_vigia1 field changedInput schema / properties / metric / descriptionPrevious value: -"Metric to compute. v0.9: 'structural' adds harmonic + closeness centrality (Boldi-Vigna 2014, Bavelas 1950) + k-core decomposition (Seidman 1983)."New value: +"summary: counts + token estimate. health: staleness, entropy, DB size. drift: chi-squared on errors. communities: Leiden clustering. bridges: betweenness centrality. structural: harmonic + closeness centrality + k-core ranking (backbone identification)."cuba_whoamicuba_zafra3 fields changedInput schema / properties / action / descriptionPrevious value: -"Consolidation action. decay_episodes applies power-law decay to brain_episodes."New value: +"decay: stratified exponential decay by type. prune: deletes low-importance observations, dry-run unless confirm=true. merge: deduplicates similar entities. summarize: replaces an entity's observations with compressed_summary. stats: counts. pagerank: personalized importance ranking. find_duplicates: lists near-duplicate pairs. export: writes a JSON dump. reembed: re-encodes with the current model. decay_episodes: power-law decay on brain_episodes."Input schema / properties / allow_secretAdded value: +{
+ "description": "Refused when the text looks like a live credential (token, password, URL with embedded creds). Set true only for a false match — the text is then stored verbatim, in clear, and reachable by search, export and every client.",
+ "type": "boolean"
+}Input schema / properties / confirmAdded value: +{
+ "description": "prune only: actually delete. Without it, prune returns a dry-run plan (would_prune, by_project) and deletes nothing — read the plan first, the default threshold reaches a large share of a mature corpus.",
+ "type": "boolean"
+}memory_alarmamemory_almamemory_archivomemory_artifactmemory_calibrarmemory_callmemory_centinelamemory_contextmemory_contradiccionmemory_cronicamemory_decretomemory_ecomemory_expedientememory_faromemory_forgetmemory_hipotesismemory_ingestamemory_jornadamemory_juezmemory_pizarramemory_pre_compactmemory_proyectomemory_puentememory_recetamemory_reflexionmemory_remediomemory_syncmemory_toolsmemory_vigiamemory_whoamimemory_zafrav0.18.0cuba_alarmacuba_almacuba_archivocuba_calibrarcuba_callcuba_centinelacuba_contradiccioncuba_cronicacuba_decretocuba_ecocuba_expedientecuba_farocuba_forgetcuba_hipotesiscuba_ingestacuba_jornadacuba_juezcuba_pizarracuba_pre_compactcuba_proyectocuba_puentecuba_recetacuba_reflexioncuba_remediocuba_synccuba_toolscuba_vigiacuba_zafraScored across 62 tools
The 31 cuba_* tools have mostly distinct documented purposes, but each is duplicated verbatim by a memory_* alias, so the agent sees 62 near-identical entries and must rely on the '[alias of ...]' tag to avoid redundancy. Several core tools also overlap conceptually (alma vs cronica vs pizarra vs receta all store different memory types; faro/expediente/remedio all revolve around retrieval of prior knowledge), though the descriptions do draw boundaries.
Every tool follows an identical lowercase prefix_noun pattern (cuba_<domain> with a parallel memory_<domain> alias), using single Spanish domain nouns rather than verbs. There is no mixing of camelCase/snake_case or competing verb styles, so the pattern is perfectly predictable across the whole set.
There are 62 listed tools (31 functional tools each mirrored by an alias), which is far above a well-scoped surface and lands in the 'too many' band. The presence of cuba_tools/cuba_call to lazy-load schemas shows the authors know the surface is heavy, but the sheer number plus the alias doubling makes the set unwieldy.
The surface is exceptionally thorough: entity CRUD, observations/facts/episodes, relations, error tracking (record/search/resolve), sessions, decisions, maintenance (decay/prune/merge), GDPR erasure, graph analytics, contradiction detection, confidence calibration, bulk ingestion, project scoping, sync, audit log, working memory, artifacts, and a context-window view. Essentially every lifecycle stage of a memory domain is covered with no obvious dead ends.
Persistent memory and knowledge graphs for AI agents. Hybrid search, context checkpoints, and more.
Persistent memory and knowledge management for AI agents with semantic search and 50+ tools.
Persistent memory and knowledge graph for AI assistants — keyword + vector + graph search.
Persistent long-term memory for AI agents: semantic search, knowledge graph, and task canvas.
