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.

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

[!IMPORTANT] v0.6.0 — Contextual Retrieval, importance priors, score breakdown, session provenance, compact format, semantic dedup, auto-tagging, Adamic-Adar link prediction, contradiction detection, prospective memory triggers, Bayesian calibration, bulk ingest, episodic memory with power-law decay, temporal search filters, and gap detection. 56 tests, 0 clippy warnings.

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
• 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
• Error memory — Never repeat the same mistake (anti-repetition guard + pattern detection)

Comparison

| Feature | Cuba-Memorys | Basic Memory MCPs | | ------- | :----------: | :---------------: | | Knowledge graph with typed relations | Yes | No | | Exponential importance decay | Yes | No | | Hebbian learning + BCM metaplasticity | Yes | No | | Hybrid entropy-routed RRF fusion | Yes | No | | KG-neighbor query expansion | Yes | No | | GraphRAG topological enrichment | Yes | No | | Leiden community detection | Yes | No | | Brandes betweenness centrality | Yes | No | | Shannon entropy analytics | Yes | No | | Adaptive prediction error gating | Yes | No | | Anti-hallucination verification | Yes | No | | Error pattern detection | Yes | No | | Session-aware search boost | Yes | No | | REM Sleep autonomous consolidation | Yes | No | | Optional ONNX BGE embeddings | Yes | No | | Write-time dedup gate | Yes | No | | Contradiction auto-supersede | Yes | No | | GDPR Right to Erasure | Yes | No | | Graceful shutdown (SIGTERM/SIGINT) | Yes | No |

Installation

PyPI (recommended)

pip install cuba-memorys

npm

npm install -g cuba-memorys

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

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

Set the environment variable:

export DATABASE_URL="postgresql://cuba:[email protected]:5488/brain"

Add to your MCP config (.cursor/mcp.json, .windsurf/mcp.json, or .vscode/mcp.json):

{
  "mcpServers": {
    "cuba-memorys": {
      "command": "cuba-memorys",
      "env": {
        "DATABASE_URL": "postgresql://cuba:[email protected]: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 19 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. Hebbian boost + access tracking. Fires prospective triggers on access. | | cuba_cronica | Cronica — chronicle | Observations with semantic dedup, PE gating V5.2, importance priors by type, auto-tagging (TF-IDF top-5 keywords), session provenance, contextual embedding. Also manages episodic memories (episode_add/episode_list) and timeline view. | | cuba_puente | Puente — bridge | Typed relations. Traverse walks the graph. Infer discovers transitive paths. Predict suggests missing relations via Adamic-Adar link prediction. | | cuba_ingesta | Ingesta — intake | Bulk knowledge ingestion: accepts arrays of observations or long text with auto-classification by paragraph. |

Search & Verification

| Tool | Meaning | What it does | |------|---------|-------------| | cuba_faro | Faro — lighthouse | RRF fusion (k=60) with entropy routing, pgvector, temporal filters (before/after), tag filters, score breakdown (text/vector/importance/session), compact format (~35% fewer tokens), Bayesian calibrated accuracy. |

Error Memory

| Tool | Meaning | What it does | |------|---------|-------------| | cuba_alarma | Alarma — alarm | Report errors. Auto-detects patterns (>=3 similar = warning). Fires prospective triggers on error match. | | cuba_remedio | Remedio — remedy | Resolve errors with cross-reference to similar unresolved issues. | | cuba_expediente | Expediente — case file | Search past errors. Anti-repetition guard: warns if similar approach failed before. |

Sessions & Decisions

| Tool | Meaning | What it does | |------|---------|-------------| | cuba_jornada | Jornada — workday | Session tracking with goals, outcomes, session diff (what was learned), and previous session context on start. Fires prospective triggers. | | cuba_decreto | Decreto — decree | Record architecture decisions with context, alternatives, rationale. |

Cognition & Analysis

| Tool | Meaning | What it does | |------|---------|-------------| | cuba_reflexion | Reflexion — reflection | Gap detection: isolated entities, underconnected hubs, type silos, observation gaps, density anomalies (z-score). | | cuba_hipotesis | Hipotesis — hypothesis | Abductive inference: given an effect, find plausible causes via backward causal traversal. Plausibility = path_strength x importance. | | cuba_contradiccion | Contradiccion — contradiction | Scan for semantic conflicts between same-entity observations via embedding cosine + bilingual negation heuristics. | | cuba_centinela | Centinela — sentinel | Prospective memory triggers: "remind me when X is accessed / session starts / error matches". Auto-deactivate on max_fires, expiration support. | | cuba_calibrar | Calibrar — calibrate | Bayesian confidence calibration: track faro/verify predictions, compute P(correct|grounding_level) via Beta distribution. Closes the verify-correct feedback loop. |

Memory Maintenance

| Tool | Meaning | What it does | |------|---------|-------------| | cuba_zafra | Zafra — sugar harvest | Stratified decay (30d/14d/7d by type), power-law episode decay, prune, merge, summarize, pagerank, find_duplicates, export, stats, reembed (model migration with versioning). Auto-consolidation on >50 observations. | | cuba_eco | Eco — echo | RLHF feedback: positive (Oja boost), negative (decrease), correct (update with versioning). | | cuba_vigia | Vigia — watchman | Analytics: summary, enhanced health (null embeddings, active triggers, table sizes, embedding model), drift (chi-squared), Leiden communities, Brandes bridges. | | cuba_forget | Forget — forget | GDPR Right to Erasure: cascading hard-delete of entity and ALL references (observations, episodes, relations, errors, sessions). Irreversible. |

Architecture

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           # 8 tables, 20+ indexes, HNSW
│   │   ├── constants.rs         # Tool definitions, thresholds, importance priors
│   │   ├── handlers/            # 19 MCP tool handlers (1 file each)
│   │   ├── cognitive/           # Hebbian/BCM, access tracking, PE gating V5.2
│   │   ├── search/              # RRF fusion, confidence, LRU cache
│   │   ├── graph/               # Brandes centrality, Leiden, PageRank (NF-IDF)
│   │   └── embeddings/          # ONNX multilingual-e5-small (contextual, spawn_blocking)
│   ├── scripts/
│   │   └── download_model.sh    # Download multilingual-e5-small ONNX
│   └── tests/
└── server.json                  # MCP Registry manifest

Performance: Rust vs Python

| Metric | Python v1.6.0 | Rust v0.6.0 | | ------ | :-----------: | :---------: | | Binary size | ~50MB (venv) | 7.6MB | | Entity create | ~2ms | 498us | | Hybrid search | <5ms | 2.52ms | | Analytics | <2.5ms | 958us | | Memory usage | ~120MB | ~15MB | | Startup time | ~2s | <100ms | | Dependencies | 12 Python packages | 0 runtime deps |

Database Schema

| Table | Purpose | Key Features | |-------|---------|-------------| | brain_entities | KG nodes | tsvector + pg_trgm + GIN indexes, importance, bcm_theta | | brain_observations | Facts with provenance | 9 types, versioning, vector(384), importance priors, auto-tags TEXT[], session_id FK, embedding_model tracking | | brain_relations | Typed edges | 5 types, bidirectional, Hebbian strength, blake3 dedup | | brain_errors | Error memory | JSONB context, synapse weight, pattern detection | | brain_sessions | Working sessions | Goals (JSONB), outcome tracking, session diff | | brain_episodes | Episodic memory | Tulving 1972, actors/artifacts TEXT[], power-law decay (Wixted 2004) | | brain_triggers | Prospective memory | on_access/on_session_start/on_error_match, max_fires, expiration | | brain_verify_log | Bayesian calibration | claim, confidence, grounding_level, outcome (correct/incorrect) |

Search Pipeline

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

| # | Signal | Source | Condition | |---|--------|--------|-----------| | 1 | Entities (ts_rank + trigrams + importance) | brain_entities | Always | | 2 | Observations (ts_rank + trigrams + importance) | brain_observations | Always | | 3 | Errors (ts_rank + trigrams + synapse_weight) | brain_errors | Always | | 4 | Vector cosine distance (HNSW) | brain_observations.embedding | pgvector installed |

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

Mathematical Foundations

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

Exponential Decay (V3)

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

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: keyword-dominant vs mixed vs semantic queries get different signal weights.

Other Algorithms

| Algorithm | Reference | Used in | |-----------|-----------|---------| | Leiden communities | Traag et al. (Nature 2019) | community.rs -> vigia.rs | | Personalized PageRank | Brin & Page (1998) | pagerank.rs -> zafra.rs | | Brandes centrality | Brandes (2001) | centrality.rs -> vigia.rs | | Adaptive PE gating | Friston (Nature 2023) | prediction_error.rs -> cronica.rs | | Shannon entropy | Shannon (1948) | density.rs -> information gating | | Chi-squared drift | Pearson (1900) | Error distribution change detection |

Configuration

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | DATABASE_URL | — | PostgreSQL connection string (required) | | ONNX_MODEL_PATH | — | Path to BGE model directory (optional) | | ORT_DYLIB_PATH | — | Path to libonnxruntime.so (optional) | | RUST_LOG | cuba_memorys=info | Log level filter |

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

Security & Audit

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

| Check | Result | |-------|:------:| | SQL injection | All queries parameterized (sqlx bind) | | SEC-002 wildcard injection | Fixed (POSITION-based) | | CVEs in dependencies | 0 active (sqlx 0.8.6, tokio 1.50.0) | | UTF-8 safety | safe_truncate on all string slicing | | Secrets | All via environment variables | | Division by zero | Protected with .max(1e-9) | | Error handling | All ? propagated with anyhow::Context | | Clippy | 0 warnings | | Tests | 106/106 passing (51 unit/smoke + 55 E2E) | | Licenses | All MIT/Apache-2.0 (0 GPL/AGPL) |

Dependencies

| Crate | Purpose | License | |-------|---------|---------| | tokio | Async runtime | MIT | | sqlx | PostgreSQL (async) | MIT/Apache-2.0 | | serde / serde_json | Serialization | MIT/Apache-2.0 | | pgvector | Vector similarity | MIT | | ort | ONNX Runtime (optional) | MIT/Apache-2.0 | | tokenizers | HuggingFace tokenizers | Apache-2.0 | | blake3 | Cryptographic hashing | Apache-2.0/CC0 | | mimalloc | Global allocator | MIT | | tracing | Structured JSON logging | MIT | | lru | O(1) LRU cache | MIT | | chrono | Timezone-aware timestamps | MIT/Apache-2.0 |

Version History

| Version | Key Changes | |---------|-------------| | 0.3.0 | Deep Research V3: exponential decay replaces FSRS-6, dead code/columns eliminated, SEC-002 fix, importance in ranking, embeddings storage on write, GraphRAG CTE fix, Opus 4.6 token optimization, zero tech debt. 106 tests (51 unit/smoke + 55 E2E), 0 clippy warnings. | | 0.2.0 | Complete Rust rewrite. BCM metaplasticity, Leiden communities, Shannon entropy, blake3 dedup. Internal audit: GO verdict. | | 1.6.0 | KG-neighbor expansion, embedding LRU cache, async embed rebuild, community summaries, batch access tracking | | 1.5.0 | Token-budget truncation, post-fusion dedup, source triangulation, adaptive confidence, session-aware decay | | 1.3.0 | Modular architecture (CC avg D->A), 87% CC reduction | | 1.1.0 | GraphRAG, REM Sleep, conditional pgvector, 4-signal RRF | | 1.0.0 | Initial release: 12 tools, Hebbian learning |

License

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

Author

Leandro Perez G.

• GitHub: @LeandroPG19
• Email: [email protected]

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), BAAI (2023, BGE), Malkov & Yashunin (2018, HNSW), O'Connor et al. (2020, blake3).