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, neuroscience-inspired algorithms, and anti-hallucination grounding.

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

[!IMPORTANT] v0.10.0 (2026-06-04) — Knowledge-graph memory plane on top of the v0.9 hybrid stack. No breaking MCP API changes for existing clients. Bitemporal facts (brain_facts, migration 0018): every cuba_cronica add/batch_add and cuba_ingesta ingest mirrors into valid-time rows — on by default (CUBA_BITEMPORAL=0 to disable). Graph metrics (0022–0023): brain_node_metrics (PageRank, energy, betweenness) + brain_communities; cuba_zafra pagerank / communities persist; cuba_vigia communities metric writes tags. Spreading activation enriches cuba_puente predict alongside Adamic-Adar. Eval harness (rust/src/eval/): nDCG@k, MRR, P@k, R@k over live cuba_faro hybrid (production path unchanged). Unified search view (v_unified_memory_search, 0024) joins facts via brain_entities — never fact_id = node_id. Shipped: Cargo/npm 0.10.0, PyPI 1.12.0, GitHub Release v0.10.0, MCP Registry. QA: ./scripts/merge-gate.sh (118 unit + smoke, E2E 73, MCP live 25).

[!NOTE] v0.9.x — BM25 3-way RRF, MMR, OOD abstention, conformal PE gating, testing-effect decay, tiktoken budget, cross-encoder reranker (CUBA_RERANKER_PATH), cuba_archivo audit chain, cuba_pizarra working memory. 25 sqlx migrations (0001–0025), bootstrap transparente para DBs legacy.

Demo

Why Cuba-Memorys?

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

• Stratified exponential decay — Memories fade by type (facts=30d, errors=14d, context=7d), 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, entropy-routed weighting (k=60), temporal filters, tag filters, compact format
• Knowledge graph — Entities, observations, typed relations with Leiden community detection and Adamic-Adar link prediction
• Anti-hallucination grounding — Verify claims with graduated confidence + Bayesian calibration over time
• Episodic memory — Separate temporal events (Tulving 1972) with power-law decay I(t) = I₀/(1+ct)^β (Wixted 2004)
• Contradiction detection — Scan for semantic conflicts via embedding cosine + bilingual negation heuristics
• LLM-judge for ambiguous contradictions (v0.8) — Escalate cosine 0.6-0.8 pairs to Claude Code CLI subprocess ($0 with subscription) or Anthropic API (feature flag). Verdicts cached permanently
• Prospective memory — Triggers that fire on entity access, session start, or error match ("remind me when X")
• Contextual Retrieval — Entity context prepended before embedding (Anthropic technique, +20% recall)
• REM Sleep consolidation — Autonomous stratified decay + PageRank + auto-prune + auto-merge + episode decay
• Graph intelligence — PageRank, Leiden communities, Brandes centrality, Shannon entropy, gap detection
• Session awareness — Provenance tracking, session diff, importance priors per observation type
• Project scoping (v0.8) — Isolate memories per project (cuba_jornada start --project NAME); legacy NULL rows stay globally visible (zero-regression upgrade path)
• Compaction-survival snapshots (v0.8) — cuba_pre_compact snapshot persists session state before /compact; restore re-injects post-compact
• Git-friendly sync (v0.8) — cuba_sync export writes 1 JSON per entity (diff-able in PR review), import is idempotent via ON CONFLICT DO NOTHING, optional zstd embeddings blob
• BM25 hybrid 3-way fusion (v0.9) — text + vector + BM25 (ts_rank_cd) en una sola RRF (Robertson-Walker 1994 baseline), captura queries con términos raros que dense embeddings pierden
• MMR diversification (v0.9) — cuba_faro diversify=true aplica Carbonell-Goldstein 1998 con Jaccard sim entre candidatos, evita top-K redundantes
• OOD abstention (v0.9) — cuba_faro abstain_ood=true con Mahalanobis ridge-regularized Σ⁻¹ (Lee NeurIPS 2018), retorna abstención formal en lugar de matches espurios
• Conformal prediction (v0.9) — quantiles empíricos sin asumir normalidad (Vovk 2005, Angelopoulos-Bates 2023); captura anisotropía cosine documentada por Ethayarajh 2019
• Testing effect decay (v0.9) — halflife escalado por (1 + ln(1+access_count)) (Karpicke-Roediger Science 2008); high-access obs decae 4-5× más lento
• Hebbian Δt-aware (v0.9) — burst suppression boost *= (1 - exp(-Δt/τ)), τ=600s; anti-saturación inspirada en STDP triplet rules (Pfister-Gerstner 2006)
• Robbins-Monro stochastic LR (v0.9) — η = 0.05/√(1 + access_count/100) en Oja's rule, convergencia O(1/√t)
• Source credibility tracking (v0.9) — Beta(α,β) Bayesian update per source en brain_source_trust (Yin-Han-Yu IEEE TKDE 2008), action cuba_calibrar trust
• sqlx-migrate — 25 migraciones SQL versionadas en rust/migrations/ (0001–0025), bootstrap transparente para DBs legacy
• Bitemporal facts (v0.10) — brain_facts + supersede chain; mirrors observations on write (default on)
• Graph energy & communities (v0.10) — persisted PageRank/energy in brain_node_metrics; Leiden → brain_communities
• Spreading activation (v0.10) — multi-hop graph propagation for link prediction hints
• Retrieval benchmarks (v0.10) — eval/ harness measures live cuba_faro (nDCG, MRR, P@k, R@k)
• CFR-21 audit log (v0.9) — cuba_archivo hash-chain tamper evidence
• Working memory buffer (v0.9) — cuba_pizarra scratchpad per session
• Error memory — Never repeat the same mistake (anti-repetition guard + pattern detection)

Comparison

Installation

PyPI (recommended)

pip install cuba-memorys==1.12.0   # wheels bundle the Rust binary (v0.10.0)

npm

npm install -g cuba-memorys@0.10.0   # downloads binary from GitHub Release on postinstall

From source

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

Binary download

Pre-built binaries available at GitHub Releases.

Quick Start

Zero configuration required — just install and add to your editor. Cuba-memorys automatically provisions a PostgreSQL database via Docker on first run.

Prerequisite: Docker must be installed and running.

npm install -g cuba-memorys
claude mcp add cuba-memorys -- cuba-memorys

npm install -g cuba-memorys

{
  "mcpServers": {
    "cuba-memorys": {
      "command": "cuba-memorys"
    }
  }
}

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

Optional: Multilingual ONNX Embeddings

For real multilingual-e5-small semantic embeddings (94 languages, 384d) instead of hash-based fallback:

./rust/scripts/download_model.sh  # Downloads ~113MB model
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. With ONNX, Contextual Retrieval prepends [entity_type:entity_name] to content before embedding for +20% recall.

The 25 Tools

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

Knowledge Graph

Search & Verification

Error Memory

Sessions & Decisions

Cognition & Analysis

Memory Maintenance

v0.8 — Engram-inspired additions

v0.8 environment variables

v0.9–v0.10 additional tools

v0.10 environment variables

Architecture

cuba-memorys/
├── docker-compose.yml           # Dedicated PostgreSQL 18 (port 5488)
├── server.json                  # MCP Registry manifest (npm 0.10.0 / PyPI 1.12.0)
├── pyproject.toml               # Maturin (bindings = "bin") — PyPI wheel
├── package.json                 # npm wrapper → GitHub Release binary
├── scripts/                     # merge-gate, backup/restore, MCP live session test
└── rust/                        # v0.10.0
    ├── migrations/              # sqlx-migrate 0001–0025 (bitemporal, graph, views)
    ├── src/
    │   ├── main.rs              # mimalloc + graceful shutdown
    │   ├── lib.rs               # Library surface (handlers, eval, graph, core)
    │   ├── protocol.rs          # JSON-RPC 2.0 + MCP correlator / sampling / cancel
    │   ├── core/                # bitemporal, entity_linking, temporal_query
    │   ├── eval/                # faro benchmark harness (nDCG, MRR, P@k, R@k)
    │   ├── handlers/            # 25 MCP tool handlers
    │   ├── cognitive/           # Hebbian, conformal PE, calibration, judge
    │   ├── search/              # RRF, BM25, MMR, OOD, rerank, tiktoken budget
    │   ├── graph/               # PageRank, Leiden, energy, activation, k-core
    │   └── embeddings/          # ONNX e5-small (contextual), hash fallback
    ├── scripts/download_model.sh
    └── tests/                   # unit + smoke + integration + e2e_all_tools.py

Performance: Rust vs Python

Database Schema

Search Pipeline

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

Post-fusion pipeline: Dedup -> KG-neighbor expansion -> Session boost -> Score breakdown -> GraphRAG enrichment -> Token-budget truncation -> Compact format (optional) -> Batch access tracking

Filters: before/after (ISO8601 temporal), tags (keyword), format (verbose/compact)

Mathematical Foundations

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

Stratified Exponential Decay (V4)

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

Stratified by observation type: facts/preferences=30d, errors/solutions=14d, context/tool_usage=7d. Decision/lesson observations are protected (never decay). Episodic memories use power-law: I(t) = 0.5 / (1 + 0.1*t)^0.5 (Wixted 2004). Importance directly affects search ranking (score0.7 + importance0.3).

Hebbian + BCM — Oja (1982), Bienenstock-Cooper-Munro (1982)

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 Fusion — Cormack (2009)

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

Entropy-routed weighting via smooth sigmoid (Jaynes 1957 MaxEnt):

t = sigmoid(2.0 * (entropy - 2.75))
text_w  = 0.7 - 0.4*t    (keyword-heavy → balanced → semantic-heavy)
vector_w = 0.3 + 0.4*t   (always sums to 1.0)

Replaces V2 step function which had 40% relative jumps at thresholds.

PageRank Blend — Brin & Page (1998)

importance_new = 0.3 * rank_normalized + 0.7 * importance_existing

Min-max normalized ranks blended via convex combination (α=0.3). Preserves Hebbian/BCM/RLHF accumulated importance instead of overwriting. Uniform distribution guard: skips blend when all ranks are equal (no structural signal).

Other Algorithms

Configuration

Environment Variables

Docker Compose

Dedicated PostgreSQL 18 Alpine:

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

How It Works

1. The agent learns from your project

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")

2. Error memory prevents repeated mistakes

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"

3. Anti-hallucination grounding

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

4. Memories decay naturally

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.

5. Community intelligence

-> 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..."

Release & QA (v0.10)

Pre-merge / pre-release gate (requires Postgres on :5488):

export DATABASE_URL=postgresql://cuba:memorys2026@127.0.0.1:5488/brain
./scripts/merge-gate.sh          # fmt, clippy, unit+integration, E2E 73, MCP live 25, cargo audit
./scripts/backup-db.sh           # optional; keeps last 7 dumps in ./backups/

Publishing (maintainers): tag v0.10.0 triggers .github/workflows/publish.yml — GitHub Release binaries, PyPI wheels, npm, MCP Registry.

Regenerate README demo GIF: ./scripts/record-demo-gif.sh → assets/demo-v0.10.gif (requires asciinema + agg).

Security & Audit

Internal Audit Verdict: GO (2026-03-28) — re-validated on v0.10 merge gate.

Dependencies

Version History

License

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

Author

Leandro Perez G.

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

Credits

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), Tulving (1972, episodic memory), Wixted (2004, power-law forgetting), Adamic & Adar (2003, link prediction), Anthropic (2024, Contextual Retrieval), Wang et al. (2022, E5 embeddings), Malkov & Yashunin (2018, HNSW), Jaynes (1957, MaxEnt sigmoid routing), Robertson (1977, score fusion), Collins & Loftus (1975, spreading activation).