Persistent memory for AI agents — A Model Context Protocol (MCP) server that gives AI coding assistants long-term memory with a knowledge graph, neuroscience-inspired algorithms, and anti-hallucination grounding.

13 tools with Cuban soul. Sub-millisecond handlers. Mathematically rigorous.

AI agents forget everything between conversations. Cuba-Memorys solves this:

• Exponential decay — Memories fade realistically (halflife=30d), strengthen with access
• Hebbian + BCM metaplasticity — Self-normalizing importance via Oja's rule with EMA sliding threshold
• Hybrid RRF fusion search — pg_trgm + full-text + pgvector HNSW, with entropy-routed weighting (k=60)
• Knowledge graph — Entities, observations, typed relations with Leiden community detection
• Anti-hallucination grounding — Verify claims against stored knowledge with graduated confidence scoring
• REM Sleep consolidation — Autonomous background decay + PageRank after idle
• Graph intelligence — Personalized PageRank, Leiden communities, Brandes centrality, Shannon entropy
• Error memory — Never repeat the same mistake (anti-repetition guard)

pip install cuba-memorys

npm install -g cuba-memorys

git clone https://github.com/LeandroPG19/cuba-memorys.git
cd cuba-memorys/rust
cargo build --release

Pre-built binaries available at GitHub Releases.

1. Start PostgreSQL (if you don't have one running):

docker compose up -d

2. Configure your AI editor (Claude Code, Cursor, Windsurf, etc.):

claude mcp add cuba-memorys -- cuba-memorys

export DATABASE_URL="postgresql://cuba:memorys2026@127.0.0.1:5488/brain"

{
  "mcpServers": {
    "cuba-memorys": {
      "command": "cuba-memorys",
      "env": {
        "DATABASE_URL": "postgresql://cuba:memorys2026@127.0.0.1:5488/brain"
      }
    }
  }
}

The server auto-creates the brain database and all tables on first run.

For real BGE-small-en-v1.5 semantic embeddings instead of hash-based fallback:

export ONNX_MODEL_PATH="$HOME/.cache/cuba-memorys/models"
export ORT_DYLIB_PATH="/path/to/libonnxruntime.so"

Without ONNX, the server uses deterministic hash-based embeddings — functional but without semantic understanding.

Every tool is named after Cuban culture — memorable, professional, meaningful.

cuba-memorys/
├── docker-compose.yml           # Dedicated PostgreSQL 18 (port 5488)
├── rust/                        # v0.3.0
│   ├── src/
│   │   ├── main.rs              # mimalloc + graceful shutdown
│   │   ├── protocol.rs          # JSON-RPC 2.0 + REM daemon (4h cycle)
│   │   ├── db.rs                # sqlx PgPool (10 max, 600s idle, 1800s lifetime)
│   │   ├── schema.sql           # 5 tables, 15+ indexes, HNSW
│   │   ├── constants.rs         # Tool definitions, thresholds, enums
│   │   ├── handlers/            # 13 MCP tool handlers (1 file each)
│   │   ├── cognitive/           # Hebbian/BCM, access tracking, PE gating
│   │   ├── search/              # RRF fusion, confidence, LRU cache
│   │   ├── graph/               # Brandes centrality, Leiden, PageRank
│   │   └── embeddings/          # ONNX BGE-small (optional, spawn_blocking)
│   ├── scripts/
│   │   └── migrate_v3.sql       # v2.x -> v0.3.0 column cleanup
│   └── tests/
└── server.json                  # MCP Registry manifest

Reciprocal Rank Fusion (RRF, k=60) with entropy-routed weighting:

Post-fusion pipeline: Dedup -> KG-neighbor expansion -> Session boost -> GraphRAG enrichment -> Token-budget truncation -> Batch access tracking

Built on peer-reviewed algorithms, not ad-hoc heuristics:

importance_new = importance * exp(-0.693 * days_since_access / halflife)

halflife=30d by default. Decision/lesson observations are protected from decay. Importance directly affects search ranking (score0.7 + importance0.3).

Positive: importance += eta * throttle(access_count, theta_M)
BCM EMA: theta_M = max(10, (1-alpha)*theta_prev + alpha*access_count)

V3: theta_M persisted in bcm_theta column for true temporal smoothing.

RRF(d) = sum( w_i / (k + rank_i(d)) )   where k = 60

Entropy-routed weighting: keyword-dominant vs mixed vs semantic queries get different signal weights.

Dedicated PostgreSQL 18 Alpine:

• Port: 5488 (avoids conflicts with 5432/5433)
• Resources: 256MB RAM, 0.5 CPU
• Restart: always
• Healthcheck: pg_isready every 10s

Agent: FastAPI requires async def with response_model.
-> cuba_alma(create, "FastAPI", technology)
-> cuba_cronica(add, "FastAPI", "All endpoints must be async def with response_model")

Agent: IntegrityError: duplicate key on numero_parte.
-> cuba_alarma("IntegrityError", "duplicate key on numero_parte")
-> cuba_expediente: Similar error found! Solution: "Add SELECT EXISTS before INSERT"

Agent: Let me verify before responding...
-> cuba_faro("FastAPI uses Django ORM", mode="verify")
-> confidence: 0.0, level: "unknown" — "No evidence. High hallucination risk."

Initial importance:    0.5  (new observation)
After 30d no access:  0.25 (halved by exponential decay)
After 60d no access:  0.125
Active access resets the clock — frequently used memories stay strong.

-> cuba_vigia(metric="communities")
-> Community 0 (4 members): [FastAPI, Pydantic, SQLAlchemy, PostgreSQL]
  Summary: "Backend stack: async endpoints, V2 validation, 2.0 ORM..."
-> Community 1 (3 members): [React, Next.js, TypeScript]
  Summary: "Frontend stack: React 19, App Router, strict types..."

Internal Audit Verdict: GO (2026-03-28)

CC BY-NC 4.0 — Free to use and modify, not for commercial use.

Leandro Perez G.

• GitHub: @LeandroPG19
• Email: leandropatodo@gmail.com

Mathematical foundations: Oja (1982), Bienenstock, Cooper & Munro (1982, BCM), Cormack (2009, RRF), Brin & Page (1998, PageRank), Traag et al. (2019, Leiden), Brandes (2001), Shannon (1948), Pearson (1900, chi-squared), Friston (2023, PE gating), BAAI (2023, BGE), Malkov & Yashunin (2018, HNSW), O'Connor et al. (2020, blake3).