Cuba Memorys

MemoryIndustry

Formerly cuba-memorys. Same daemon, same cuba_* MCP tools, new product name.

Long-term memory for AI coding agents. An MCP server that gives your agent a knowledge graph it can search, reason over, and be corrected by — so it stops forgetting your codebase between sessions.

Written in Rust. Backed by PostgreSQL + pgvector. 31 MCP tools (32 with CUBA_DOCS=1), 28 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.)

Install

pip install memory-industry        # or: npm install -g memory-industry

claude mcp add memory-industry -- memory-industry

Previous names still install the same binary:

pip install cuba-memorys

npm install -g cuba-memorys

That is the whole setup. On first run it provisions a PostgreSQL 18 + pgvector container via Docker and initializes the schema. [Docker](https://docs.docker.com/get-docker/) must be running. The cuba-memorys command remains a binary alias.

Cursor / Windsurf / VS Code / Zed

{

"mcpServers": { "memory-industry": { "command": "memory-industry" } } }

No DATABASE_URL needed. Or run cuba-memorys setup (or memory-industry setup) and it writes the config for every client it finds — then cuba-memorys setup check audits them for disagreement, which is the failure that actually bites (two configs, two embedding dimensions, one silently broken search).

Bring your own PostgreSQL

{

"mcpServers": { "memory-industry": { "command": "memory-industry", "env": { "DATABASE_URL": "postgresql://user:pass@localhost:5432/brain" } } } }

Needs the `vector` and `pg_trgm` extensions. `cuba-memorys doctor` will tell you if anything is missing.

One shared daemon instead of one process per client

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 address

memory-industry serve is the same command. Point every client at it, and give each one its own Mcp-Client-Id so their sessions stay separate — without it jornada start in one window becomes the active session of the next:

{

"mcpServers": { "memory-industry": { "type": "http", "url": "http://127.0.0.1:8787/mcp", "headers": { "Mcp-Client-Id": "editor-window-1" } } } }

GET /health reports uptime, database reachability and how many clients have been seen. status is three-valued — ok, starting, degraded — and the code is always 200: a 503 would take out of rotation a daemon that still serves lexical search and still serves the one endpoint that can explain what is wrong. Alert on status, not on the code.

GET /identity and POST /pair are how a client finds out that the daemon it reached is the right one and pairs with it. GET /identity answers {service, host_id, name} to anyone and, given a credential id and a nonce, a proof only a host that holds that credential's hash can compute (or revoked / unknown, with no proof). POST /pair redeems a pairing code and answers a MAC only a host that knows the code can compute. Both refuse a request that carries a forwarding header or a foreign Origin, /pair takes at most 4 KiB, answers every failure with the same 401 {"error":"pairing failed"}, and counts its failures in the same per-address brake as /mcp (10 per minute).

With CUBA_HTTP_TOKEN in an Authorization: Bearer header the answer also carries runtime: mode, resource_tier, {state, device, reason} for the embedder, reranker and NLI — device is where the session actually opened (gpu, or cpu with the provider's cause in reason when the GPU provider refused to start) and null for a model that has no session yet or never opened one — gpu{build, degraded, placement}, where placement is only what the plan asked for and degraded also turns true when a provider refused, and llm{configured, backend, model, base_url} — which is how you find out where the reranker is actually running without reading the source. Without the token none of that is served, and neither is graph_db.last_error, which can name an internal host and port. No key, no DATABASE_URL and no model path is ever printed, with or without a token.

The token is mandatory if you bind anything other than loopback — the daemon serves the entire graph with no authentication by default — and on a routable address it must be at least 32 characters.

The port opens first, then the models load, and only then does the daemon announce itself and start serving. Binding first keeps the cheap diagnosis — a second daemon on the same port fails immediately instead of spending two minutes loading before it finds out — and connections that arrive during the load queue in the kernel backlog, so a client waits and gets a real answer rather than a refused connection. If the load overruns MEMORY_INDUSTRY_WARM_BEFORE_SERVE_SECS (180 s) the daemon serves anyway, /health says starting, and every search asking for reranking comes back marked degraded. Under stdio a client that gives up at 30 s without closing stdin used to leave an abandoned multi-GB process holding every model it had loaded; stdio now exits if no handshake arrives within MEMORY_INDUSTRY_HANDSHAKE_TIMEOUT_SECS (60 s, 0 or off disables).

That queue only helps a client that can outwait the load: one whose own budget is shorter — a sync peer gives up after CUBA_HANDLER_TIMEOUT_SECS (30 s) — still cuts the call, and cuts it seeing a timeout instead of a refused connection, which is the better diagnosis but is not the real answer the queue was there to buy. /health is what says which of the two states the daemon is in, and it answers two different questions. That it answers at all means the port is served, which is everything a caller needs when what it is about to call does not touch the models — a sync fetch moves rows. That it answers ready: true means the models finished loading as well, which is what to wait for before a search that asks for reranking, or when the first search must not be the one that pays for the load. The first wait is bounded and the second is not: the daemon opens within MEMORY_INDUSTRY_WARM_BEFORE_SERVE_SECS whatever the models are doing, but a warm-up that overruns that ceiling keeps serving everything with ready: false for as long as it takes, so ready: true can fail to arrive on a daemon that is answering perfectly. Wait on it without a ceiling of your own and you hang on a healthy machine.

Semantic embeddings & models (recommended)

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 loaded

Everything lands in ~/.cache/memory-industry/ (or in ~/.cache/cuba-memorys/ on an install from before the rename) and is found automatically. models downloads only when you run it — nothing is fetched behind your back. A download goes to .downloading first and becomes only once every file is down and verified, so a failed one leaves no empty directory for the loaders to pick.

Moving an old cache under the new name. The ~/.cache/cuba-memorys/ root is still read for this release, but each file decides between the two roots on its own, and one entry created under the new name — pgpass_app at startup, undo/ from delete — is enough for models to download again what the old root already holds. doctor warns while the old root has anything in it. One command moves it:

memory-industry cache migrate            # the plan: touches nothing

memory-industry cache migrate --apply # moves it

An entry only in the old root moves; one identical in both loses its old copy. One that differs keeps the copy the binary reads today — for pgpass_app the one next to the pgpass in use, for a model directory the one that actually holds the model — and the other is set aside as .legacy-YYYYMMDD in the new root, never deleted. A file another process holds (on Windows, the runtime a running daemon loaded) is skipped and the command exits non-zero: stop the daemon and run it again. What already moved stays moved, and a second run says there is nothing to migrate.

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.

Modes: local · red · completo

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:

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 — se