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.
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. 28 MCP tools (29 with CUBA_DOCS=1), 22 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 cuba-memorys # or: npm install -g cuba-memorys
claude mcp add cuba-memorys -- 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.
{
"mcpServers": {
"cuba-memorys": {
"command": "cuba-memorys"
}
}
}No DATABASE_URL needed. Or run cuba-memorys 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": {
"cuba-memorys": {
"command": "cuba-memorys",
"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 addressPoint 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": {
"cuba-memorys": {
"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-two commands. cuba-memorys --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 10 plus cuba_tools + cuba_call — 12 of 28, a 51% 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 |
|
| Local entailment model ( |
| off | Send claims the NLI could not decide to an LLM. Buys recall, costs ~12 s each |
|
| 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. |
| 12 tools of 28, −51% 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/cuba-memorys.git
cd cuba-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 # fmt · clippy -D warnings · 316 tests · audit · integration
cargo run --release --example rerank_bench # does the reranker fit its budget here?Publishing is tag-driven: v* triggers GitHub Release binaries (5 platforms), PyPI wheels, npm, and the MCP Registry. A test pins all four files that hold a version number to the same value, because they used to drift and nothing caught it.
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. | |
| error_message | Yes | Full error message |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses automatic pattern detection (≥3 similar = warning) and Hebbian learning (similar errors boosted). This is useful behavioral context. However, it does not explain side effects like whether entries are created or notifications sent, and no annotations exist to supplement.
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 sentences, front-loading the core action. No wasted words, but the second sentence could be more structured. Overall 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?
Given 4 parameters, no output schema, and no annotations, the description covers the tool's behavior adequately but lacks details on return values, error handling, or prerequisites. It is minimally 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 description does not need to add much. It repeats parameter details already in the schema. The extra behavioral info about patterns and boosting relates to tool function, not parameter semantics. 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: 'Report errors immediately.' It also mentions auto-detection of patterns and Hebbian learning, which adds specificity. However, it does not explicitly differentiate from sibling tools like cuba_vigia 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?
The description only says 'Report errors immediately,' implying when to use, but provides no guidance on when not to use or alternatives among siblings. No explicit context for usage.
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 (v0.9, CFR-21 Part 11 inspired). Append-only with SHA-256 hash chain — every row's current_hash commits to the previous row's, the action and the canonical payload. UPDATE/DELETE blocked at the PostgreSQL trigger level (only cuba_admin role can bypass). Use 'verify' to walk the chain and detect tampering, 'tail' to read recent events, 'append' to add a new event.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Limit for verify/tail (default 10000 / 20) | |
| action | Yes | Audit operation | |
| 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?
The description fully discloses core behaviors: append-only, SHA-256 hash chain, UPDATE/DELETE blocked at trigger level with admin bypass. No annotations were provided, so the description carries the full burden. It does not mention rate limits or payload size limits, but the behavioral details are substantial.
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 sentences, front-loaded with purpose, followed by technical details and usage guidance. No extraneous content. Every sentence 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?
The description covers the tool's main purpose, security model, and available operations. Given no output schema, it could mention return values (e.g., verify returns chain results, tail returns events, append returns success). However, the provided details are sufficient for an audit log tool with moderate 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 coverage is 100%, providing descriptions for all four parameters. The description adds value by specifying default limits for 'verify/tail' and clarifying that payload and event_action are for 'append'. This goes beyond the schema's attribute descriptions.
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 identifies the tool as a 'Tamper-evident audit log' with specific operations (append, verify, tail) and technical details (SHA-256 hash chain, append-only). This clearly defines the resource and verb, and the unique hash chain feature distinguishes 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?
The description explicitly tells when to use each action ('Use 'verify' to walk the chain...'tail' to read recent events...'append' to add a new event'). However, it does not discuss when not to use the tool or alternatives among siblings.
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. v0.9: action 'trust' returns per-source credibility (Beta posterior updated by resolve outcomes; Yin-Han-Yu IEEE TKDE 2008).
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results for history (default 20) | |
| action | Yes | Calibration action. v0.9: 'trust' returns per-source Beta(α, β) credibility; 'metrics' returns Brier score (1950) + Expected Calibration Error (Naeini AAAI 2015) + 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?
No annotations provided, so description carries full burden. It discloses that 'trust' returns credibility updated by resolve outcomes, but doesn't clarify if other actions modify data, auth requirements, or 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 concise sentences with front-loaded purpose. However, jargon like 'P(correct|level)' and references reduce accessibility.
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; description lacks details on return formats for actions like 'stats', 'history', and 'resolve'. Incomplete for a multi-action calibration 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 covers all parameters (100% coverage). Description adds minor context for 'trust' and 'metrics' actions with references, but doesn't significantly enhance understanding beyond 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?
Description states it performs Bayesian confidence calibration, tracking predictions and computing probabilities. It clearly identifies the resource and verb, but doesn't differentiate from sibling tools like cuba_faro or cuba_eco, which might have overlapping functions.
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 alternatives. The description mentions closing a feedback loop but doesn't specify context or exclusion criteria.
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: set triggers that fire when entities are accessed, sessions start, or errors match. 'Remember to remind me about X when Y happens.'
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | Trigger action | |
| 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) | |
| condition_type | No | When to fire | |
| entity_pattern | No | Entity name or pattern to match |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explains the core behavior (triggers fire on conditions) but omits details on trigger lifecycle, persistence, side effects, and the effect of parameters like max_fires and expires_at. With no annotations, more transparency is 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?
Very concise at two sentences; front-loaded with the key concept. The quote example adds clarity but could be integrated more smoothly. Still, it earns its place and avoids redundancy.
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 tool has multiple actions (create, list, delete, check) but the description only implies creation. No mention of managing triggers (listing, deleting) or what the output is after creation. Given the complexity and no output schema, this is a significant 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 coverage is 100%, but the description adds value by contextualizing parameters (e.g., 'message' as reminder, 'condition_type' as events). The prospective memory framing ties parameters together meaningfully, exceeding 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 clearly states the tool's purpose: setting triggers for prospective memory, with specific event types (entity access, session start, error match). The example quote reinforces the intent. It distinguishes from sibling tools by focusing on trigger-based reminders tied to specific conditions.
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 usage for setting reminders conditioned on events, but does not explicitly state when to use this tool versus alternatives like alarms or watches. No exclusions or guidance on when not to use it are provided.
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 | |
| 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 and mentions key behaviors: auto-creating entities, dedup gate for near-duplicates, and supporting episodic memory actions. It could add more details on side effects or error handling but is above average.
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 paragraph of three sentences, concise and front-loaded. However, it is dense and could benefit from breaking into bullet points for clarity.
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 9 parameters, multiple actions, no output schema, no annotations, the description covers core functionalities but lacks details on return values, error conditions, and action-specific constraints. It is adequate but not comprehensive.
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 for action values (e.g., 'episode_add stores a temporal event') but does not significantly enhance parameter 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 the tool attaches facts/lessons/decisions to entities and manages episodic memories with actions like episode_add, episode_list, and timeline. It distinguishes itself from siblings by specifying unique functionalities such as auto-creating entities and dedup gates.
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 usage for attaching observations and managing memories but lacks explicit guidance on when not to use or alternatives among the 27 sibling tools. No 'when-to-use' or 'when-not-to-use' advice is provided.
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 | |
| alternatives | No | Options considered |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavioral traits. It only says 'record and query' without specifying side effects (e.g., does recording overwrite or append?), persistence, permissions, or any constraints. The agent is left guessing about the tool's effect on system 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, efficient sentence that states the purpose without waste. It is front-loaded and easy to parse. However, given 7 parameters and 3 actions, one sentence may under-communicate, but it is still appropriately concise for a minimal definition.
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 fails to explain what each action returns, how errors are handled, or how parameters interact. For a tool with multiple actions and several parameters, this lack of context leaves the agent underinformed.
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%—all seven parameters have inline descriptions. The tool description adds no additional meaning beyond what the schema already provides. Baseline 3 is appropriate since the schema fills the semantics gap adequately.
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 records and queries architecture/design decisions. It identifies the specific resource type and includes both actions. However, given the 27 sibling tools with similar naming patterns (cuba_*), it does not differentiate itself. A score of 4 reflects clear purpose but no sibling distinction.
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 guidance on when to use this tool versus siblings or when to choose among its three actions (record, query, list). It does not mention any prerequisites or exclusions. With many similar tools, the lack of usage context is a significant gap.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max rows for the 'pending' listing (default 20, max 200) | |
| action | Yes | Feedback type, or a quarantine transition: promote/quarantine flip one observation's retrievability; pending lists what is currently withheld. | |
| correction | No | New content (for correct action) | |
| entity_name | No | Target entity | |
| 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 full burden. It discloses that positive/negative affect importance (Oja's rule), correct updates content, and quarantine actions change retrievability. However, it omits side effects like whether changes are reversible, rate limits, or interaction with other tools. Not contradictory but incomplete.
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 pack multiple concepts, but they are front-loaded with the main purpose. No fluff. Could be clearer by separating feedback and quarantine into bullet points, but no waste.
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?
Despite 100% schema coverage and 5 parameters, the description fails to explain how parameters like entity_name and observation_id relate to each action, or what the tool returns (no output schema). The agent must guess parameter usage for each action, making the description insufficient for correct invocation.
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 parameters are already documented. The description adds context about Oja's rule and quarantine semantics, but does not clarify action-parameter dependencies (e.g., which parameters are needed for each action). Value added is marginal.
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 explicitly states the tool handles RLHF feedback (positive/negative/correct) and quarantine gate actions (pending/promote/quarantine), specifying verbs like 'boosts importance', 'decreases', 'updates content', 'lists', 'promote', 'quarantine', and resources (memories/observations). It distinguishes the two main sub-functions, though the jargon 'Oja's rule' may reduce clarity for some agents.
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 its 28 siblings (e.g., cuba_calibrar, cuba_cronica). No prerequisites, success criteria, or examples of when each action is appropriate are provided. The agent must infer from action names alone.
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. v0.9: optional MMR diversification + OOD abstention + exact tiktoken-based 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 | 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. | |
| diversify | No | v0.9: 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 | v0.9: MMR balance — 1.0 pure relevance, 0.0 pure diversity. Default 0.7. | |
| abstain_ood | No | v0.9: abstain (return empty results with abstain_reason) when query is out-of-distribution via Mahalanobis distance. Default false. | |
| associative | No | 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. | |
| enable_bm25 | No | 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. | |
| ood_threshold | No | 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. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description adequately discloses behavioral traits: it is a search (read-only) operation, returns grounding scores, supports temporal filtering, and details version-specific features. It does not mention authentication or rate limits, but these are less critical for a search 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 concise at 4-5 sentences, front-loaded with the primary purpose, and efficiently lists key features and version numbers without extraneous 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 16 parameters and no output schema, the description covers the essential behavior, including temporal filtering, modes, and versioned features. It could briefly mention the return structure (e.g., list of results) but overall is fairly 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?
The description adds significant value beyond the 100% schema coverage by explaining parameter contexts (e.g., '71% fewer tokens' for format, 'cross-encoder rerank' for rerank, defaults and version details). This enriches understanding.
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 core function: 'Search memory BEFORE answering to ground responses.' It specifies modes ('verify') with confidence levels, session-aware boosting, and temporal filtering, 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?
The description provides clear context for use (grounding responses) and explains the primary modes. However, it lacks explicit guidance on when not to use this tool versus siblings, which would be helpful given the large sibling list.
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: given an observed effect, find plausible causes by traversing causal relations backwards. Returns hypotheses ranked by plausibility (path_strength × importance). Read-only.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max hypotheses to return (default 10, max 50) | |
| action | Yes | Inference action | |
| 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?
Since no annotations are provided, the description carries full burden. It explicitly states 'Read-only', describes the ranking formula (path_strength × importance), and mentions traversing causal relations backwards. This fully discloses the tool's 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 two sentences, front-loaded with the core purpose. Every word adds value, no redundancy or fluff.
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 inference tool with 4 parameters and no output schema, the description is complete. It explains what the tool does, how results are ranked, and that it is read-only. No missing information critically needed for invocation.
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%, but the description adds significant context: explaining abductive inference, the ranking method, and the read-only nature. This enhances understanding of each parameter's role beyond their individual descriptions.
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 specifies 'abductive inference' with a clear verb+resource: given an observed effect, find plausible causes by traversing causal relations backwards. It distinguishes from siblings by focusing on hypothesis generation. No other sibling tool suggests this abductive role.
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 clearly states when to use: when you have an observed effect and need plausible causes. It does not explicitly state when not to use or mention alternatives, but the context is clear enough for an agent to decide.
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. 'ingest' for structured items, 'parse' for raw text splitting, 'auto_extract' for LLM extraction via MCP sampling. | |
| 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) | |
| 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 provided, so the description carries the full burden. It discloses that all routes share a dedup/PE-gating/embedding pipeline and none delete, and explains the quarantine behavior via the 'untrusted' parameter. This adds meaningful behavioral 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 well-structured with a clear front-loaded purpose and bullet-like explanations for each action. It is moderately concise, though slightly verbose; each sentence 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?
The description covers actions, parameters, and behavioral aspects adequately, but lacks information about return values or output format. Since no output schema exists, the description could be more complete by describing what each action returns.
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%, but the description adds extra meaning: it explains each action mode, the quarantine behavior of 'untrusted', and the knowledge-update feature of 'supersede_conflicts'. This provides value beyond the parameter descriptions in 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 'Bulk knowledge ingestion' and lists three specific actions (ingest, parse, auto_extract) with brief explanations. It distinguishes the tool's function but does not explicitly differentiate from sibling tools like cuba_faro or cuba_eco.
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 context for when to use each action (e.g., 'ingest for structured items', 'parse for raw text splitting'), but lacks explicit guidance on when not to use this tool or mentions of alternatives among siblings.
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) |
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 reveals that the optional 'project' arg triggers an upsert into brain_projects and scopes subsequent operations, which is helpful. However, it does not describe side effects of 'start' or 'end' actions (e.g., whether sessions are persisted, overwritten, or conflict), leaving 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?
The description is two sentences long, with the first clearly stating the tool's purpose and the second explaining the key parameter. It is concise and front-loaded. However, it could be improved by structuring the information (e.g., bullet points for actions) to aid scanning.
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 6 parameters (1 required), no output schema, and no annotations, the description should cover return values, behavior for each action, and edge cases (e.g., what happens if 'end' is called without 'start'). It only elaborates on the 'project' parameter, leaving many scenarios undocumented, making it incomplete for reliable invocation.
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 value by explaining that the 'project' parameter binds the session to a named project (upserts in brain_projects) and that omitting it keeps the session global. It also contextualizes the 'action' enum by implying start/end/list/current usage, though explicit mapping to each action's behavior is missing.
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 tracks working sessions with goals and outcomes, using a specific verb ('track') and resource ('sessions'). It also mentions the optional project argument for binding. However, it does not distinguish its purpose from sibling tools like cuba_vigia or cuba_proyecto, leaving some ambiguity for the agent.
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 lacks explicit guidance on when to use this tool versus alternatives. It mentions actions (start, end, list, current) but does not specify prerequisites, fallback strategies, or scenarios where other tools would be preferred (e.g., if only logging notes). An agent would need to infer usage from context.
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 (v0.8). When cosine similarity sits in the ambiguous band (0.6-0.8), heuristic detectors miss vocabulary-different conflicts (e.g. 'Postgres' vs 'MongoDB'). cuba_juez escalates a pair to a real LLM via subprocess (Claude Code CLI, $0 if you have a subscription) or — when feature 'anthropic-api' is built in — the Anthropic API directly. Verdicts are persisted in brain_judgments (UNIQUE per pair = permanent cache).
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | judge_pair = decide on two given obs ids; scan_entity = pull ambiguous pairs 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 exist, so the description fully carries the burden. It discloses the LLM call via subprocess (Claude Code CLI or Anthropic API), cost implications ($0 with subscription), caching (UNIQUE per pair = permanent), and cost control via max_pairs. This is thorough behavioral disclosure.
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 sentences, each earning its place: purpose, context, mechanism, caching. Front-loaded with the core purpose and progressively adds detail. 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?
The description covers parameters and behavior well, but the absence of an output schema means the description should clarify what the tool returns (e.g., verdict, status). It mentions verdict persistence but not the immediate response. This leaves ambiguity for the agent.
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 value by explaining the two action modes (judge_pair vs scan_entity), default max_pairs (5), and cost control implications. However, it does not add extra meaning for observation_a/b or entity_name 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 it is an 'LLM-judge for semantically-conflicting observations' with a specific trigger condition (cosine similarity 0.6-0.8). It defines its scope and differentiates from heuristic detectors, making its unique role apparent even among siblings.
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?
Provides clear usage context: when cosine similarity sits in the ambiguous band and heuristic detectors fail. However, it does not explicitly state when not to use the tool or mention alternative tools for other scenarios.
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) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses key behaviors: TTL-bound, auto-expire, bulk-purge by another tool, and the three operations (write, read, clear). Does not explicitly state if write overwrites or appends, but given the scratchpad semantics, it's implied. Overall, informative for a tool with no annotations.
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 model name and purpose. Every clause is informative and contributes to understanding. No redundant or filler content.
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 4 parameters, no output schema, and no annotations, the description covers purpose, usage, parameter behavior, and lifecycle (expiry and purge). It also references a related sibling tool (cuba_zafra) for additional context, making it self-contained and complete for an agent.
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 value by explaining tag filtering for read/clear, default TTL, and the action enum implicitly. The context 'Content to store (for write)' clarifies optional fields. This exceeds the schema's minimal descriptions.
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?
Clearly defines as a working memory buffer, references the Baddeley 1992 model, and distinguishes itself from episodic and semantic memory. Lists specific use cases (inter-step plan state, tentative observations, cross-tool-call reminders) and differentiates from sibling tools like cuba_cronica (episodic) and cuba_alma (semantic).
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 instructs to use for inter-step plan state during long-horizon tasks, tentative observations, and reminders. Mentions auto-expire by ttl_seconds and bulk-purge by cuba_zafra REM cycle, providing context on lifecycle. Lacks explicit 'when not to use' but the positive guidance is strong.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compaction-survival protocol (v0.8). Before the agent runs /compact, call action='snapshot' to persist a dense markdown summary of the active session (recent observations, decisions, unresolved errors, pending embeddings, goals). After compaction, call action='restore' to retrieve the latest snapshot for the active session and re-inject it into context.
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | snapshot persists a session summary; restore returns the latest |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It describes the actions' effects (persisting and retrieving a summary), but lacks detail on error handling, what happens if called at other times, or permissions.
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 sentences, efficiently front-loading the protocol name and version, then clearly specifying the two actions and their timing. 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 annotations, no output schema, and a single parameter, the description is fairly complete. It tells the agent exactly when to call each action, though it omits potential edge cases or 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?
The input schema has one parameter with 100% description coverage. The description adds value by embedding the protocol context (snapshot before compact, restore after), which goes beyond the schema's simple enum 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?
The description explicitly states the tool's purpose: providing snapshot and restore actions for session state during compaction. It clearly distinguishes itself from sibling tools, none of which serve this specific protocol.
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 gives explicit when to use each action: call action='snapshot' before /compact and action='restore' after. This provides clear context, though it does not mention alternative tools or 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.
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' | |
| 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?
No annotations exist, so the description carries the full burden. It explains the learning mechanism (recording outcomes), the ranking by reliability, and that re-adding a name edits it while keeping its track record. This gives agents good insight into the tool's 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 somewhat verbose and metaphorical ('PROCEDURAL MEMORY', 'the other tools remember what is TRUE'). While it is front-loaded and clear, it could be more concise by reducing philosophical framing. Every sentence adds some value, but some 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?
Given the tool's complexity (9 parameters, 1 required, no output schema), the description provides enough context to use it correctly. It explains the core mechanics and the outcome reporting. However, it could be more explicit about parameter relationships and usage patterns beyond actions.
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%, but the description adds significant meaning beyond the schema. It explains the purpose of each action (e.g., 'outcome: record success/failure — this is what teaches it') and the concept of procedural memory. This helps an agent understand how to use the parameters correctly.
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 it is a procedural memory for how things are done, distinguishing it from sibling tools that remember facts. It specifies actions like bringing up dev services, running tests, deploying, migrating. However, the metaphorical language ('PROCEDURAL MEMORY', 'the other tools remember what is TRUE') slightly obscures the direct function.
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 guidance on reporting outcomes using the 'outcome' action for learning, and warns that failing recipes are harmful. It implies usage context but does not explicitly state when not to use this tool or list alternative tools for specific scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Analyze knowledge graph for structural gaps: isolated entities, underconnected hubs, type silos, observation gaps (missing decisions/lessons), and statistical density anomalies. Read-only introspection.
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | Gap analysis action (only 'analyze' supported) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden and explicitly states 'Read-only introspection', confirming no destructive actions. It also details the specific gap types analyzed, providing good 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?
Two sentences, front-loaded with purpose, no redundancy. Every sentence adds value and is efficiently worded.
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 simple input schema and no output schema, the description adequately explains the tool's function and scope. However, the lack of any mention of output format or return value is a minor 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?
The single parameter 'action' with enum 'analyze' is fully covered by the schema (100% coverage). The description adds the list of gap types, but it's not directly about parameter syntax or options, so baseline score is 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 clearly states the tool analyzes knowledge graph for structural gaps, listing specific gap types. However, it does not differentiate from sibling tools, which lowers the score.
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 usage for finding structural gaps but lacks explicit when-to-use or when-not-to-use guidance, nor does it mention alternatives.
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 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must convey behavior. It mentions cross-referencing but does not detail side effects like status changes, permissions, or irreversibility.
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, concise and front-loaded. However, the cross-referencing note is vague and could be clearer.
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 no annotations, the description covers the main action but lacks details on what 'mark as resolved' entails (e.g., state change) and what 'cross-references' produces.
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 parameter descriptions. The tool description adds no additional parameter-specific semantics beyond cross-referencing, which is a behavioral note.
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 action: marking an error as resolved with a solution. It also mentions cross-referencing similar unresolved errors, which distinguishes it from sibling tools like cuba_vigia or cuba_alarma.
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 usage for resolving errors and cross-referencing similar ones, but does not explicitly state when not to use it or provide alternatives among siblings.
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 (v0.8). action='export' writes one JSON file per entity (with embedded observations) plus episodes/decisions/errors/relations under CUBA_SYNC_DIR (default ./.cuba-memorys/). 'import' merges files back via INSERT...ON CONFLICT DO NOTHING (idempotent). 'diff' compares disk vs DB. 'status' lists not-yet-imported manifests. Embeddings are omitted by default (set with_embeddings=true to include the binary blob).
| Name | Required | Description | Default |
|---|---|---|---|
| dir | No | Directory override (default $CUBA_SYNC_DIR or ./.cuba-memorys/) | |
| scope | No | Export scope: only the active project (default) or all data | |
| action | Yes | Sync mode | |
| conflict | No | Import conflict policy (default merge) | |
| with_embeddings | No | Include the embeddings.bin.zst blob on export (default false) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of disclosure. It reveals key behaviors: export writes one JSON file per entity, import uses INSERT ON CONFLICT DO NOTHING (idempotent), diff compares disk vs DB, and status lists manifests. It also clarifies that embeddings are omitted by default. This is fairly transparent, though it could mention potential side effects like directory creation or permission requirements.
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 dense paragraph that efficiently conveys the core information (purpose, actions, defaults). It is front-loaded with the main purpose. However, it could be improved with bullet points or separate sentences for each action to enhance scanability. Every sentence adds value, but the structure could be cleaner.
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 5 parameters, no annotations, and no output schema, the description covers the essential aspects: all four actions, default directory, conflict handling for import, and embedding behavior. It lacks details on return values or error handling, but the actions (diff, status) imply comparisons and listings. The description is sufficient for typical usage scenarios.
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 parameters. The description adds meaningful context beyond the schema: it explains the default directory derivation, the idempotent nature of import, and that embeddings are excluded by default. This enhances understanding of the 'dir', 'action', 'conflict', and 'with_embeddings' parameters.
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: 'Git-friendly export/import of the knowledge graph (v0.8).' It enumerates four distinct actions (export, import, diff, status) with brief explanations, making it easy to distinguish from sibling tools like cuba_vigia or cuba_proyecto which have different purposes.
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 fails to provide guidance on when to use this tool versus alternatives. It explains what each action does but does not specify contexts or trade-offs (e.g., when to use 'import' with 'merge' vs 'overwrite', or when 'diff' is appropriate). No explicit 'when-to-use' or 'when-not-to-use' statements are present.
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 29 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 full burden. It discloses the on-demand loading behavior, profile sensitivity, and that this tool is for discovery only. It does not mention side effects, but for a read-only discovery tool, this is sufficient.
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, no redundancy. Front-loaded with main purpose, then provides details on usage and parameters. Every sentence 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?
Given no output schema, the description explains what each detail level returns. It mentions the total tool count, the lean profile context, and the workflow (search then call with cuba_call). It is complete for a discovery 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 coverage is 100%, but description adds significant value: explains detail level trade-offs ('cheapest'), what each detail returns, and that 'full' gives the schema needed to call the tool. This goes 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 the tool finds cuba-memorys tools and loads their schemas on demand. It specifies the verb 'find' and resource 'tools + schemas', and distinguishes from siblings by explaining its role in lazy loading and discovery, contrasting with execution tools like cuba_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?
The description provides explicit guidance on when to use this tool: when tools are not pre-loaded under the lean profile. It recommends searching by capability and gives examples. It does not explicitly list scenarios to avoid, but the context is clear enough.
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 (counts + token estimate), health (staleness, entropy, DB size), drift (chi-squared on errors), communities (Leiden), bridges (betweenness centrality). v0.9: 'structural' returns harmonic + closeness + k-core ranking for backbone identification.
| Name | Required | Description | Default |
|---|---|---|---|
| metric | Yes | Metric to compute. v0.9: 'structural' adds harmonic + closeness centrality (Boldi-Vigna 2014, Bavelas 1950) + k-core decomposition (Seidman 1983). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully convey behavioral traits. It mentions version v0.9 and that 'structural' returns specific centralities, but does not disclose whether the tool is read-only, has side effects, requires authorization, or any other behavioral aspects. The description is insufficient for a agent to understand the tool's safety profile.
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 and front-loaded, listing all metrics in a clear, scannable format. Every sentence adds value, and there is no extraneous text. The structure is appropriate for quick understanding.
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 single enum parameter and no output schema, the description gives a reasonable idea of what each metric returns. However, it lacks details on output format, return structure, or error handling. For a tool with multiple analytic capabilities, an agent might need more context on how to interpret 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?
The input schema already describes the single parameter 'metric' with detailed enum values, including the v0.9 note. The tool description adds an overview of each metric's output, but this is largely redundant. Since schema coverage is 100%, the description provides minimal additional value beyond a summary.
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 that the tool performs knowledge graph analytics and lists all specific metrics (summary, health, drift, communities, bridges, structural) with brief explanations. It distinguishes itself from sibling tools which have different purposes (e.g., cuba_proyecto, cuba_alma).
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 does not provide any guidance on when to use this tool versus alternatives. It only lists what metrics are available without context about appropriate use cases or exclusions. No comparison with sibling tools is made.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Memory maintenance: decay (stratified exponential by type), prune (remove low-importance), merge (deduplicate), summarize (compress observations), pagerank (personalized importance), find_duplicates, export, stats, reembed (re-encode with current model).
| 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 | Consolidation action. decay_episodes applies power-law decay to brain_episodes. | |
| 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) | |
| 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?
With no annotations, the description carries full burden for behavioral disclosure. It only offers brief parenthetical hints (e.g., 'stratified exponential by type') but does not explain side effects, required permissions, or irreversible actions like prune or merge.
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 very concise, using a single sentence with parenthetical clarifications. However, the structure is a flat list, which reduces readability and may omit important contextual details.
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 9 parameters and no output schema, the description is incomplete. It fails to explain return values, error conditions, or how the tool integrates with the broader system, leaving significant gaps for an AI agent.
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 extra meaning beyond the schema; it merely lists actions without detailing how parameters like 'halflife_days' or 'similarity_threshold' affect behavior.
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 'Memory maintenance' and lists actions, providing a general purpose. However, it does not clearly distinguish this tool from similar sibling tools like cuba_forget or cuba_reflexion, and the list format lacks a clear verb+resource structure.
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 alternatives. The description does not mention use cases, prerequisites, or conditions under which specific actions (e.g., decay vs. prune) are appropriate.
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. Dates show when Glama detected each change.
v0.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_zafraEach tool has a clearly distinct purpose, from entity CRUD (cuba_alma) to error tracking (cuba_alarma, cuba_remedio, cuba_expediente) to search (cuba_faro) and maintenance (cuba_zafra). No two tools appear to do the same thing, even within related domains like error handling or memory operations.
All tools follow a consistent cuba_ prefix and snake_case naming, with single-word or compound names like cuba_pre_compact. The pattern is uniform, making it easy for an agent to predict tool names based on concept.
With 28 tools, the count is higher than typical, but each tool serves a specialized function within a complex knowledge graph system. The scope justifies the number, though it might be slightly overwhelming for simple use cases.
The tool set covers the full lifecycle: CRUD for entities and relations, search, error handling, sessions, decisions, bulk ingestion, sync, audit logs, working memory, hypothesis, contradiction detection, and more. No obvious gaps exist for a comprehensive memory management server.
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.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/LeandroPG19/Memorys'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
