🧠 Cuba-Memorys

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

12 tools with Cuban soul. Zero manual setup. Mathematically rigorous. v1.1.0 — God-Tier: RRF fusion, REM Sleep daemon, GraphRAG, conditional pgvector.

Why Cuba-Memorys?

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

• A knowledge graph — Entities, observations, and relations that persist across sessions

• Error memory — Never repeat the same mistake twice (anti-repetition guard)

• Hebbian learning — Memories strengthen with use and fade adaptively (FSRS spaced repetition)

• Anti-hallucination — Verify claims against stored knowledge with graduated confidence scoring

• Semantic search — 4-signal RRF fusion (TF-IDF + pg_trgm + full-text + optional pgvector HNSW)

• GraphRAG — Top results enriched with degree-1 graph neighbors for topological context

• REM Sleep — Autonomous background consolidation (FSRS decay + prune + PageRank) after 15min idle

• Graph intelligence — Personalized PageRank, Louvain community detection, betweenness centrality

Quick Start

1. Prerequisites

• Python 3.11+

• Docker (for PostgreSQL)

2. Install

git clone https://github.com/lENADRO1910/cuba-memorys.git
cd cuba-memorys

docker compose up -d

pip install -e .

# Optional: BGE embeddings for semantic search (~130MB model)
pip install -e ".[embeddings]"

3. Configure your AI editor

Add to your MCP configuration:

{
  "mcpServers": {
    "cuba-memorys": {
      "command": "/path/to/cuba_memorys_launcher.sh",
      "disabled": false
    }
  }
}

Or run directly:

DATABASE_URL="postgresql://cuba:memorys2026@127.0.0.1:5488/brain" python -m cuba_memorys

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

🇨🇺 Las 12 Herramientas

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

Knowledge Graph

Search & Verification

Error Memory

Sessions & Decisions

Memory Maintenance

Mathematical Foundations

Cuba-Memorys is built on peer-reviewed algorithms, not ad-hoc heuristics:

FSRS Adaptive Decay — Wozniak (1987) / Ye (2022)

stability = fsrs_stability · (1 + decay_factor)^rating
R(t) = (1 + t/(9·S))^(-1)

FSRS (Free Spaced Repetition Scheduler) provides adaptive memory decay. Stability grows with successful reviews — memories that are reinforced survive longer.

Oja's Rule (1982) — Hebbian Learning

Positive: Δw = η · (1 - w²)     → converges to 1.0, cannot explode
Negative: Δw = η · (1 + w²)     → converges to 0.01 (floor)

Where η = 0.05. The w² term provides natural saturation — self-normalizing without explicit clipping.

TF-IDF + RRF Fusion — Salton (1975) / Cormack (2009)

tfidf(t, d) = tf(t, d) · log(N / df(t))
RRF(d) = Σ 1/(k + rank_i(d))     where k = 60

Reciprocal Rank Fusion combines multiple ranked lists from independent signals into a single robust ranking. In v1.1.0, up to 4 signals are fused: entities (full-text + trigrams), observations (full-text + trigrams + TF-IDF), errors (full-text + trigrams), and optional pgvector (cosine distance on embeddings).

Optional BGE Embeddings — BAAI (2023)

model: Qdrant/bge-small-en-v1.5-onnx-Q (quantized, ~130MB)
runtime: ONNX (no PyTorch dependency)
similarity: cosine(embed(query), embed(observation))

Auto-downloads on first use. Falls back to TF-IDF if not installed.

GraphRAG Enrichment — v1.1.0

Top-3 search results are enriched with degree-1 graph neighbors via a single batched SQL query. Each result gets a graph_context array containing neighbor name, entity type, relation type, and Hebbian strength. Provides topological context without N+1 queries.

REM Sleep Daemon — v1.1.0

After 15 minutes of user inactivity, an autonomous consolidation coroutine runs:

1. FSRS Decay — Applies memory decay using Ye (2022) algorithm

2. Prune — Removes low-importance (< 0.1), rarely-accessed observations

3. PageRank — Recalculates personalized importance scores

Cancels immediately on new user activity. Prevents concurrent runs.

Conditional pgvector — v1.1.0

IF pgvector extension detected:
  → Migrate embedding column: float4[] → vector(384)
  → Create HNSW index (m=16, ef_construction=64, vector_cosine_ops)
  → Add vector cosine distance as 4th RRF signal
  → Persist embeddings on observation insert
ELSE:
  → Graceful degradation: TF-IDF + trigrams (unchanged)

Zero-downtime: auto-detects at startup, no configuration needed.

Personalized PageRank — Brin & Page (1998)

PR(v) = (1-α)/N + α · Σ PR(u)/deg(u)     where α = 0.85
personalization: biased toward recently active entities
final_importance = 0.6·PR + 0.4·current_importance

Graph-structural importance via networkx. Personalized bias prevents cold-start domination.

Shannon Entropy — Knowledge Diversity

H = -Σ p·log₂(p)
diversity_score = H / H_max

Measures how evenly distributed your knowledge is across entity/observation types. Score 0–1.

Spreading Activation — Collins & Loftus (1975)

When entity X is accessed, its graph neighbors receive a small importance boost (0.6% per hop, decaying 30% per level).

Chi-Squared Concept Drift — Pearson (1900)

χ² = Σ (observed - expected)² / expected
p-value via scipy.stats.chi2.sf()

Detects when the distribution of error types changes significantly — signals that something new is breaking.

Contradiction Detection

conflict = tfidf_similarity(new, existing) > 0.7 AND has_negation(new, existing)

Checks for semantic overlap + negation patterns (not, never, instead of, replaced, deprecated) in both English and Spanish.

Architecture

cuba-memorys/
├── docker-compose.yml          # Dedicated PostgreSQL (port 5488)
├── pyproject.toml              # Package metadata + optional deps
├── README.md
└── src/cuba_memorys/
    ├── __init__.py
    ├── __main__.py             # Entry point
    ├── server.py               # 12 MCP tools + REM Sleep daemon (~1850 LOC)
    ├── db.py                   # asyncpg pool + orjson + pgvector detection + Decimal
    ├── schema.sql              # 5 tables, 15+ indexes, pg_trgm, versioning
    ├── hebbian.py              # FSRS, Oja's rule, spreading activation
    ├── search.py               # LRU cache, RRF fusion, NEIGHBORS_SQL, SEARCH_VECTOR_SQL
    ├── tfidf.py                # TF-IDF semantic search (scikit-learn)
    └── embeddings.py           # Optional BGE embeddings (ONNX Runtime)

Database Schema

Search Pipeline (v1.1.0)

Cuba-Memorys uses Reciprocal Rank Fusion (RRF, k=60) to combine up to 4 independent ranked signals:

Each signal produces an independent ranking. RRF fuses them: score(d) = Σ 1/(60 + rank_i(d)).

Post-fusion enrichment:

• Top-3 results receive GraphRAG context (degree-1 neighbors)

• Active session goals boost matching results by 15%

Dependencies

Core:

• asyncpg — PostgreSQL async driver

• orjson — Fast JSON serialization (handles UUID/datetime)

• scikit-learn — TF-IDF vectorization

• networkx — PageRank + Louvain + betweenness centrality

• scipy — Chi-squared statistical tests

• rapidfuzz — Entity duplicate detection

• numpy — Numerical operations

Optional (pip install -e ".[embeddings]"):

• onnxruntime — ONNX model inference

• huggingface-hub — Auto-download BGE model

• tokenizers — Fast tokenization

Configuration

Environment Variables

Docker Compose

Runs a dedicated PostgreSQL 18 Alpine instance:

• Port: 5488 (avoids conflicts with 5432/5433)

• Resources: 256MB RAM, 0.5 CPU

• Restart: always (auto-starts on boot)

• Healthcheck: pg_isready every 10s

How It Works in Practice

1. The agent learns from your project

Agent: I learned that FastAPI endpoints must use async def with response_model.
→ cuba_alma(create, "FastAPI", technology)
→ cuba_cronica(add, "FastAPI", "All endpoints must be async def with response_model")

2. Error memory prevents repeated mistakes

Agent: I got IntegrityError: duplicate key on numero_parte.
→ cuba_alarma("IntegrityError", "duplicate key on numero_parte")
→ Similar error found! Solution: "Add SELECT EXISTS before INSERT with FOR UPDATE"

3. Anti-hallucination grounding

Agent: Let me verify this claim before responding...
→ cuba_faro("FastAPI uses Django ORM", mode="verify")
→ confidence: 0.0, level: "unknown"
→ recommendation: "No supporting evidence found. High hallucination risk."

4. Memories adapt with FSRS

Initial stability:    S = 1.0 (decays in ~9 days)
After 5 reviews:      S = 8.2 (decays in ~74 days)
After 20 reviews:     S = 45.0 (survives ~13 months)

5. Contradiction detection

Existing:  "Project uses PostgreSQL 15"
New:       "Project does NOT use PostgreSQL, it uses MySQL instead"
→ ⚠️ CONFLICT detected (similarity=0.82, negation pattern: "does NOT")

6. Graph intelligence

→ cuba_zafra(action="pagerank")
→ Top entities: FastAPI (0.42), SQLAlchemy (0.38), PostgreSQL (0.35)

→ cuba_vigia(metric="communities")
→ Community 1: [FastAPI, Pydantic, SQLAlchemy] — Backend cluster
→ Community 2: [React, Next.js, TypeScript] — Frontend cluster

Verification

Tested with NEMESIS protocol (3-tier) — v1.1.0 results:

🟢 Normal (4/4)   — RRF fusion (rrf_score on all results), GraphRAG (graph_context with
                     neighbors), scope=observations with grounding, verify mode (0.7093)
🟡 Pessimist (4/4) — Empty queries, whitespace, dedup gate (similarity=1.0),
                     graph traversal depth=2 with strength decay
🔴 Extreme (5/5)  — SQL injection, XSS, path traversal, min-length content,
                     transitive inference depth=5

Previous v1.0.1 tests (18/18) also verified: Entity CRUD, observe, search, relate, PageRank, communities, decay, find_duplicates, export, health, entropy, Unicode, bidirectional delete.

Performance

License

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

Author

Leandro Pérez G.

• GitHub: @lENADRO1910

• Email: leandropatodo@gmail.com

Credits

Mathematical foundations: Wozniak (1987), Ye (2022, FSRS), Oja (1982), Salton (1975, TF-IDF), Cormack (2009, RRF), Brin & Page (1998, PageRank), Collins & Loftus (1975), Shannon (1948), Pearson (1900, χ²), Blondel et al. (2008, Louvain), BAAI (2023, BGE embeddings), Malkov & Yashunin (2018, HNSW).