Memorys

<!-- mcp-name: io.github.LeandroPG19/memory-industry -->
# MemoryIndustry

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

[![CI](https://github.com/LeandroPG19/Memorys/actions/workflows/ci.yml/badge.svg)](https://github.com/LeandroPG19/Memorys/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/memory-industry?logo=pypi&logoColor=white&label=PyPI)](https://pypi.org/project/memory-industry/)
[![npm](https://img.shields.io/npm/v/memory-industry?logo=npm&logoColor=white&label=npm)](https://www.npmjs.com/package/memory-industry)
[![MCP Registry](https://img.shields.io/badge/MCP_Registry-published-8A2BE2)](https://registry.modelcontextprotocol.io)
[![Rust](https://img.shields.io/badge/rust-1.93+-orange?logo=rust&logoColor=white)](https://rust-lang.org)
[![PostgreSQL](https://img.shields.io/badge/PostgreSQL-18-336791?logo=postgresql&logoColor=white)](https://postgresql.org)
[![License: Apache 2.0](https://img.shields.io/badge/license-Apache%202.0-blue)](https://www.apache.org/licenses/LICENSE-2.0)

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

Written in Rust. Backed by PostgreSQL + pgvector. **31 MCP tools** (32 with `CUBA_DOCS=1`), **23 CLI commands**, and every number below measured on a benchmark that — as of v0.12 — actually measures what it claims to. (The previous one did not. See [Measured](#measured--and-the-benchmark-that-was-lying).)

<p align="center">
  <img src="assets/demo.gif" alt="MemoryIndustry terminal demo — hybrid search, claim verification with an LLM judge, procedural memory, and the CLI" width="760" />
</p>

---

## Install

```bash
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.

<details>
<summary><b>Cursor / Windsurf / VS Code / Zed</b></summary>

```json
{
  "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).
</details>

<details>
<summary><b>Bring your own PostgreSQL</b></summary>

```json
{
  "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.
</details>

<details>
<summary><b>One shared daemon instead of one process per client</b></summary>

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](https://blog.modelcontextprotocol.io/posts/2026-07-28/) settled on: no session handshake, every request self-describing.

```bash
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:

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

`GET /health` reports uptime, database reachability and the clients seen so far. `CUBA_HTTP_ADDR` overrides the address; `CUBA_HTTP_TOKEN` requires `Authorization: Bearer`, and is mandatory if you bind anything other than loopback — the daemon serves the entire graph with no authentication by default.

Models load in the background *after* the port opens, so a client that connects during startup waits on its first search instead of timing out the connection. Under stdio that timeout was how you ended up with abandoned multi-GB processes: the client gives up at 30 s but never closes stdin, so the server sat there holding every model it had loaded. Stdio now exits if no handshake arrives within `CUBA_HANDSHAKE_TIMEOUT_SECS` (60 s, `0` disables).
</details>

<details>
<summary><b>Semantic embeddings & models (recommended)</b></summary>

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`:

```bash
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/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`.
</details>

<details>
<summary><b>Modes: local · red · completo</b></summary>

`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:

| `CUBA_MODE` | Database | Capabilities | Network out |
|---|---|---|---|
| `local` (default) | Docker on this machine | embeddings + NLI as installed | none |
| `red` | shared managed Postgres (set `DATABASE_URL` with `sslmode=require`) | + provenance per node, real-time sync between machines | none |
| `completo` | whatever `DATABASE_URL` implies | **+ reranker (GPU if present) + `cuba_docs`** | `cuba_docs` |

**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](#sync-between-machines-through-git). Do **not** expose your own Postgres port to the internet — use a managed provider's TLS, or a private network like [Tailscale](https://tailscale.com).

**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, `with_intra_threads(2)` | 106,9 s | no — scores computed, then discarded |
| CPU, physical cores | 61,0 s | no |
| **`--features cuda`** | **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