🧠 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.6.0 — KG-neighbor query expansion, embedding LRU cache, community summaries, batch access tracking, pool race fix, session-aware search.

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 v4 spaced repetition)
• Anti-hallucination — Verify claims against stored knowledge with graduated confidence + source triangulation
• Semantic search — 4-signal RRF fusion (TF-IDF + pg_trgm + full-text + optional pgvector HNSW)
• KG-neighbor query expansion — Auto-expands low-recall searches via graph neighbors (PRF + Zep/Graphiti)
• 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 with summaries, betweenness centrality
• Embedding cache — LRU cache eliminates redundant ONNX inference (~84% reduction)
• Session-aware search — Results matching active session goals boosted by 15%

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 v4 Adaptive Decay — Wozniak (1987) / Ye (2023)

R(t, S) = (1 + t/(9·S))^(-1)
S_new = S · (1 + e^0.1 · (11 - D) · S^(-0.2) · (e^((1-R)·0.9) - 1))

FSRS v4 provides adaptive memory decay. Stability grows with successful recalls — memories that are reinforced survive longer. V6: Active session goals exempt observations from decay.

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. V2: Post-fusion deduplication removes semantic duplicates via word-overlap ratio.

KG-Neighbor Query Expansion (V9) — Zep/Graphiti (2025)

R₁ = φ(q)                                    # Initial search
q' = q ∪ {e.name : e ∈ neighbors(R₁, depth=1)}  # Expand via KG
R₂ = φ_trgm(q')                              # Re-search
Final = RRF(R₁, R₂)                          # Fuse

Inspired by Zep/Graphiti BFS search (arXiv 2501.13956 §3.1). Only triggered when initial results < limit (low recall). Caps neighbor names to 5 to prevent query bloat. Literature shows +15-25% recall improvement.

Source Triangulation (V3) — Multi-Source Confidence

diversity = unique_entities / total_evidence
confidence_adjusted = confidence × (0.7 + 0.3 × diversity)

Penalizes single-source evidence to reduce confirmation bias. Multiple independent entities providing evidence increases confidence.

Shannon Entropy — Information Density Gating (V5)

H = -Σ (c/n) · log₂(c/n)
density = H / H_max     ∈ [0, 1]

Observations with density < 0.3 get reduced initial importance (0.3 instead of 0.5). Prevents low-information noise from polluting the knowledge base. Applied in both add and batch_add with parity.

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. V10: LRU cache (256 entries) eliminates redundant ONNX calls (~84% reduction per session).

GraphRAG Enrichment

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.

REM Sleep Daemon

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

1. FSRS Decay — Applies memory decay using Ye (2023) v4 algorithm. V6: Excludes observations linked to active session goals
2. Prune — Removes low-importance (< 0.1), rarely-accessed observations
3. PageRank — Recalculates personalized importance scores
4. Relation Decay — Weakens unused relation strengths
5. TF-IDF Rebuild — Refreshes the TF-IDF index
6. Cache Clear — Clears search cache + V10 embedding LRU cache

Cancels immediately on new user activity. Prevents concurrent runs.

Conditional pgvector

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 (async, V7/V11)
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

Community Detection + Summaries (V12)

communities = Louvain(G, resolution=1.0)     — Blondel et al. (2008)

For communities ≥3 entities, V12 generates structured summaries from top-3 observations per entity (by importance). Inspired by Zep/Graphiti hierarchical KG (arXiv 2501.13956 §2.3).

Other Algorithms

• Shannon Entropy — Knowledge diversity scoring (diversity = H/H_max ∈ [0,1])
• Spreading Activation — Collins & Loftus (1975): neighbors get 0.6% importance boost per access
• Chi-Squared Drift — Pearson (1900): detects error type distribution changes
• Contradiction Detection — TF-IDF overlap (>0.7) + negation patterns (EN + ES)

Architecture

v1.6.0 uses a modular architecture — decomposed into focused modules with cyclomatic complexity avg grade A.

cuba-memorys/
├── docker-compose.yml          # Dedicated PostgreSQL (port 5488)
├── pyproject.toml              # Package metadata + optional deps
├── README.md
└── src/cuba_memorys/
    ├── __init__.py             # Version (1.6.0)
    ├── __main__.py             # Entry point
    ├── server.py               # Thin re-export (24 LOC)
    ├── protocol.py             # JSON-RPC transport, event loop, REM Sleep daemon
    ├── handlers.py             # 12 MCP tool handlers (CC-reduced via sub-function extraction)
    ├── constants.py            # Tool definitions, thresholds, enums
    ├── db.py                   # asyncpg pool + orjson + pgvector detection + V15 race fix
    ├── schema.sql              # 5 tables, 15+ indexes, pg_trgm, versioning, V8 temporal index
    ├── hebbian.py              # FSRS v4, Oja's rule, spreading activation, info density
    ├── search.py               # LRU cache, RRF fusion + V2 dedup, NEIGHBORS_SQL
    ├── tfidf.py                # TF-IDF semantic search (scikit-learn)
    └── embeddings.py           # Optional BGE embeddings (ONNX) + V10 LRU cache

Database Schema

Search Pipeline

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

1. V2 Deduplication — Removes semantic duplicates via word-overlap ratio
2. V9 KG-neighbor expansion — When results < limit, expands query via graph neighbors
3. V13 Session boost — Active session goal keywords boost matching results by 15%
4. GraphRAG enrichment — Top-3 results get degree-1 neighbor context
5. V1 Token-budget truncation — Character budget allocated proportionally to RRF score
6. V14 Batch access tracking — All returned observations get access_count bump for FSRS accuracy

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 v4

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. KG-neighbor query expansion (V9)

Query: "deployment strategy"    → 2 results (below limit of 5)
→ KG neighbors: [Docker, CI/CD, NGINX]
→ Expanded: "deployment strategy Docker CI/CD NGINX"
→ 5 results (recall improved by graph context)

6. Community summaries (V12)

→ cuba_vigia(metric="communities")
→ Community 0 (4 members): [FastAPI, Pydantic, SQLAlchemy, PostgreSQL]
  Summary: "FastAPI: All endpoints async def; Pydantic: V2 strict models; ..."
→ Community 1 (3 members): [React, Next.js, TypeScript]
  Summary: "React: 19 hooks patterns; Next.js: App Router; ..."

Verification

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

🟢 Normal (12/12)  — All 12 tools, all CRUD actions, GraphRAG enrichment,
                     Hebbian cross-reference, RRF fusion, Oja's rule,
                     dedup gate, anti-repetition guard, batch_add,
                     V14 access_count bump confirmed, V12 community summaries,
                     V9 KG expansion, V10 embedding cache transparent
🟡 Pessimist (4/4) — Empty queries, non-existent entities, duplicate observations
                     (dedup gate: similarity 0.85), ungrounded claims
                     (confidence: 0.0, level: "unknown", hallucination warning)
🔴 Extreme (3/3)   — SQL injection (parametrized queries — stored as text, not executed),
                     XSS (HTML entities escaped), repetitive content AAA×430
                     (density gating: importance reduced to 0.3)

Previous versions: v1.3.0 (12/12, 8/8, 9/9), v1.1.0 (13/13), v1.0.1 (18/18).

Performance

Version History

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 (2023, FSRS v4), 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), McCabe (1976, CC), BAAI (2023, BGE), Malkov & Yashunin (2018, HNSW), Karpicke & Roediger (2008, testing effect), Zep/Graphiti (2025, arXiv 2501.13956).