Persistent memory for AI agents with knowledge graph and adaptive learning.
🧠 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.
12 tools with Cuban soul. Sub-millisecond handlers. Mathematically rigorous.
[!IMPORTANT] v2.0.0 — Complete Rust rewrite. 5,452 LOC, 36 source files, 0 CVEs, 0 tech debt. Internally audited with GO verdict. The Python version (v1.6.0) remains in
src/as legacy reference.
Why Cuba-Memorys?
AI agents forget everything between conversations. Cuba-Memorys solves this:
- 🧬 FSRS-6 adaptive decay — Memories strengthen with use and fade realistically (21 parameters, per-entity sigmoid)
- 🧠 Hebbian + BCM metaplasticity — Self-normalizing importance via Oja's rule with Bienenstock-Cooper-Munro throttle
- 🔍 4-signal RRF fusion search — TF-IDF + pg_trgm + full-text + pgvector HNSW, with entropy-routed adaptive k
- 🕸️ 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 + neighbor diffusion after idle
- 📊 Graph intelligence — Personalized PageRank, Leiden communities, Brandes centrality, Shannon entropy
- 🔐 Dual-Strength memory — Storage + retrieval strengths track independently (Bjork 1992)
- ⚡ Error memory — Never repeat the same mistake (anti-repetition guard)
Comparison
| Feature | Cuba-Memorys | Basic Memory MCPs |
|---|---|---|
| Knowledge graph with typed relations | ✅ | ❌ |
| FSRS-6 adaptive spaced repetition | ✅ | ❌ |
| Hebbian learning + BCM metaplasticity | ✅ | ❌ |
| Dual-Strength memory model | ✅ | ❌ |
| 4-signal entropy-routed RRF fusion | ✅ | ❌ |
| KG-neighbor query expansion | ✅ | ❌ |
| GraphRAG topological enrichment | ✅ | ❌ |
| Leiden community detection | ✅ | ❌ |
| Brandes betweenness centrality | ✅ | ❌ |
| Shannon entropy analytics | ✅ | ❌ |
| Adaptive prediction error gating | ✅ | ❌ |
| Anti-hallucination verification | ✅ | ❌ |
| Error pattern detection + MTTR | ✅ | ❌ |
| Session-aware search boost | ✅ | ❌ |
| REM Sleep autonomous consolidation | ✅ | ❌ |
| Embedding LRU cache | ✅ | ❌ |
| Optional ONNX BGE embeddings | ✅ | ❌ |
| Write-time dedup gate | ✅ | ❌ |
| Contradiction auto-supersede | ✅ | ❌ |
| Graceful shutdown (SIGTERM/SIGINT) | ✅ | ❌ |
Quick Start
git clone https://github.com/LeandroPG19/cuba-memorys.git
cd cuba-memorys
# Start PostgreSQL
docker compose up -d
# Build Rust binary
cd rust
cargo build --release
Configure your AI editor (Claude Code, Cursor, Windsurf, etc.):
{
"mcpServers": {
"cuba-memorys": {
"command": "/path/to/cuba-memorys/rust/target/release/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.
Optional: ONNX Embeddings
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.
🇨🇺 The 12 Tools
Every tool is named after Cuban culture — memorable, professional, meaningful.
Knowledge Graph
| Tool | Meaning | What it does |
|---|---|---|
cuba_alma |
Alma — soul | CRUD entities. Types: concept, project, technology, person, pattern, config. Triggers Hebbian + Dual-Strength boost. |
cuba_cronica |
Crónica — chronicle | Attach observations with dedup gate, contradiction detection, Shannon density gating, and adaptive PE gating V5.1. Supports batch_add. |
cuba_puente |
Puente — bridge | Typed relations (uses, causes, implements, depends_on, related_to). Traverse walks the graph. Infer discovers tra |
Tools (3)
cuba_almaCRUD entities including concepts, projects, technologies, persons, patterns, and configs.cuba_cronicaAttach observations with dedup gate, contradiction detection, and adaptive PE gating.cuba_puenteManage typed relations and traverse the knowledge graph.Environment Variables
DATABASE_URLrequiredPostgreSQL connection string for the brain database.ONNX_MODEL_PATHPath to directory containing ONNX models for semantic embeddings.ORT_DYLIB_PATHPath to the ONNX runtime dynamic library.Configuration
{"mcpServers": {"cuba-memorys": {"command": "/path/to/cuba-memorys/rust/target/release/cuba-memorys", "env": {"DATABASE_URL": "postgresql://cuba:memorys2026@127.0.0.1:5488/brain"}}}}