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.

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

[!IMPORTANT] v0.9.0 — Search & Retrieval upgrades + Cognitive layer refinements + sqlx-migrate foundation. Zero breaking changes. cuba_faro ahora hace fusión RRF 3-way (text + vector + BM25 ts_rank_cd, Robertson-Walker 1994), con MMR diversification opcional (Carbonell-Goldstein 1998, λ=0.7), OOD abstention vía Mahalanobis con ridge-regularized Σ⁻¹ (Lee NeurIPS 2018), hnsw.ef_search=200 dinámico en verify (recall@10≈0.99), y conteo exacto de tokens vía tiktoken-rs cl100k_base (reemplaza la heurística "len/4" que mis-contaba español 30%). Cognitive: cuba_zafra decay con testing effect (Karpicke-Roediger Science 2008) — halflife escalado por (1 + ln(1+access_count)). Hebbian Δt-aware (anti-saturación de bursts, τ=600s, inspirado en STDP triplet). Robbins-Monro stochastic LR en Oja positive/negative (η = 0.05/√(1+access/100)). Conformal prediction empírica reemplaza z-score gaussiano en PE gating (Vovk 2005, Angelopoulos-Bates 2023) — distribution-free, captura anisotropía documentada por Ethayarajh EMNLP 2019. Source credibility tracking Beta(α,β) Bayesian update por outcome (Yin-Han-Yu IEEE TKDE 2008), nueva action cuba_calibrar trust. Foundation: migraciones SQL versionadas via sqlx-migrate (14 archivos, idempotente, bootstrap transparente). 23 tools, 97 tests, 0 clippy warnings, 0 tech debt.

[!IMPORTANT] v0.8.0 — 4 new tools inspired by Engram Cloud + zero-regression refactor. cuba_proyecto isolates memories per project (column project_id on 6 tables, NULL = global = backward compat). cuba_pre_compact persists a markdown summary of the active session before /compact and restores it post-compact. cuba_sync writes a git-friendly export (1 JSON per entity, monthly-partitioned episodes, optional zstd embeddings blob) and re-imports it idempotently. cuba_juez escalates ambiguous-similarity (0.6-0.8) observation pairs to an LLM judge — defaults to a subprocess call against the user's installed claude CLI ($0 with a Pro/Max subscription); also supports the Anthropic API behind the anthropic-api Cargo feature, with a heuristic fallback when neither is available. Verdicts cached permanently in brain_judgments. All 19 v0.7 tools were audited for project scoping (≈30 SQL queries patched). 75 tests passing, 0 clippy warnings, 0 tech debt.

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 (v0.9) — 14 migraciones SQL versionadas en rust/migrations/, bootstrap transparente para DBs legacy v0.7/v0.8
• 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 | | Multilingual ONNX embeddings (e5-small) | Yes | No | | Episodic memory (power-law decay) | Yes | No | | Contradiction detection | Yes | No | | Prospective memory triggers | Yes | No | | Bayesian confidence calibration | Yes | No | | Link prediction (Adamic-Adar) | Yes | No | | Auto-tagging (TF-IDF) | Yes | No | | Contextual Retrieval (Anthropic) | Yes | No | | Temporal search filters | Yes | No | | Zero-config Docker auto-setup | 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 | | Project scoping (per-project isolation) (v0.8) | Yes | No | | Compaction-survival snapshots (v0.8) | Yes | No | | Git-friendly export/import (v0.8) | Yes | No | | LLM-judge for ambiguous contradictions (v0.8) | Yes | No | | BM25 + vector + text 3-way RRF (v0.9) | Yes | No | | MMR diversification (v0.9) | Yes | No | | OOD abstention via Mahalanobis (v0.9) | Yes | No | | Conformal prediction (distribution-free) (v0.9) | Yes | No | | Testing-effect decay (v0.9) | Yes | No | | Hebbian Δt-aware burst suppression (v0.9) | Yes | No | | Robbins-Monro stochastic LR (v0.9) | Yes | No | | Source credibility tracking Beta(α,β) (v0.9) | Yes | No | | sqlx-migrate versioned migrations (v0.9) | Yes | No | | Exact tiktoken token budget (v0.9) | 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

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

That's it. On first run, Cuba-memorys will:

1. Detect that no database is configured
2. Create a Docker container with PostgreSQL + pgvector
3. Initialize the schema automatically
4. Start serving 19 MCP tools

npm install -g cuba-memorys

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

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

No DATABASE_URL needed — auto-provisioned via Docker on first run.

If you already have PostgreSQL with pgvector, set the environment variable:

{
  "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 23 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 sigmoid entropy routing, pgvector, temporal filters (before/after), tag filters, score breakdown (text/vector/importance/session), compact format (~35% fewer tokens), hybrid verify (trigram + embedding fusion), Bayesian calibrated accuracy, token-budget truncation, max_tokens control. |

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

v0.8 — Engram-inspired additions

| Tool | Meaning | What it does | |------|---------|-------------| | cuba_proyecto | Proyecto — project | Per-project isolation. switch upserts a project and binds it to the active session; reads/writes auto-scope via project_id. Legacy NULL rows stay globally visible. Actions: list / current / switch / stats / rename / merge. | | cuba_pre_compact | Pre-compact | Survives /compact. snapshot persists session state (recent obs, decisions, unresolved errors, pending embeddings, goals) into brain_compaction_snapshots. restore returns the latest snapshot for the active session. | | cuba_sync | Sync | Git-friendly export/import. Writes 1 JSON per entity + monthly-partitioned episodes + decisions + relations.json + manifest.json (sha hash). import is idempotent via ON CONFLICT DO NOTHING. Optional embeddings.bin.zst blob (off by default — re-embed on import). | | cuba_juez | Juez — judge | LLM-judge for ambiguous (cosine 0.6-0.8) contradictions. Trait ContradictionJudge with three backends: ClaudeCodeJudge (subprocess, $0 with subscription), AnthropicApiJudge (feature anthropic-api), HeuristicJudge (fallback). Verdicts cached in brain_judgments (UNIQUE per pair). |

v0.8 environment variables

| Variable | Default | Purpose | |----------|---------|---------| | CUBA_PROJECT_FILTER | (unset) | Set to off to disable project scoping (admin/debug). | | CUBA_SYNC_DIR | ./.cuba-memorys | Root for cuba_sync export/import. | | CUBA_JUDGE | auto | Judge backend: claude_cli / anthropic_api / heuristic / auto. | | CUBA_JUEZ_CLI | claude | Subprocess CLI for ClaudeCodeJudge. | | CUBA_JUEZ_MODEL | claude-haiku-4-5 | Model passed to the judge backend. | | CUBA_JUEZ_TIMEOUT_SECS | 30 | Subprocess/HTTP timeout. | | CUBA_JUEZ_MAX_PAIRS | 5 | Cap on pairs cuba_juez scan_entity will escalate per call. | | ANTHROPIC_API_KEY | (unset) | Required for AnthropicApiJudge (only when feature anthropic-api is built in). |

Architecture

cuba-memorys/
├── docker-compose.yml           # Dedicated PostgreSQL 18 (port 5488)
├── server.json                  # MCP Registry manifest
├── pyproject.toml               # Maturin (bindings = "bin") — PyPI wheel
├── package.json                 # npm wrapper
└── rust/                        # v0.7.0
    ├── src/
    │   ├── main.rs              # mimalloc + graceful shutdown (SIGTERM/SIGINT)
    │   ├── lib.rs               # Shared types and utilities
    │   ├── protocol.rs          # JSON-RPC 2.0 + REM daemon (4h cycle)
    │   ├── db.rs                # sqlx PgPool (10 max, 600s idle, 1800s lifetime)
    │   ├── setup.rs             # Zero-config Docker PostgreSQL auto-provisioning
    │   ├── 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 (hebbian.rs), PE gating V5.2
    │   │                        # (prediction_error.rs), dual-strength learning
    │   │                        # (dual_strength.rs), Shannon entropy (density.rs)
    │   ├── search/              # RRF fusion (rrf.rs), confidence (confidence.rs),
    │   │                        # LRU cache (cache.rs)
    │   ├── graph/               # Brandes centrality (centrality.rs), Leiden
    │   │                        # communities (community.rs), PageRank (pagerank.rs)
    │   └── embeddings/          # ONNX multilingual-e5-small (contextual embedding,
    │                            # spawn_blocking, hash fallback)
    ├── scripts/
    │   └── download_model.sh    # Download multilingual-e5-small ONNX (~113MB)
    └── tests/                   # 55 unit + 13 smoke tests

Performance: Rust vs Python

| Metric | Python v1.6.0 | Rust v0.7.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, ON CONFLICT 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 | | 5 | Episodes (ts_rank + trigrams + importance) | brain_episodes | Always |

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

| Algorithm | Reference | Used in | |-----------|-----------|---------| | Leiden communities | Traag et al. (Nature 2019) | community.rs -> vigia.rs | | PageRank + blend | Brin & Page (1998) | pagerank.rs -> convex combination (α=0.3) | | Brandes centrality | Brandes (2001) | centrality.rs -> undirected normalization | | 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 | | Power-law forgetting | Wixted (2004) | setup.rs -> episodic memory decay | | Contextual Retrieval | Anthropic (2024) | onnx.rs -> entity context prepend | | Adamic-Adar | Adamic & Adar (2003) | puente.rs -> link prediction | | Episodic/Semantic | Tulving (1972) | brain_episodes vs brain_observations | | Bayesian calibration | Beta distribution | calibrar.rs -> P(correct|level) |

Configuration

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | DATABASE_URL | — | PostgreSQL connection string (auto-provisioned via Docker if not set) | | ONNX_MODEL_PATH | — | Path to multilingual-e5-small 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 | 68 passing (55 unit + 13 smoke) + 49 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 | | 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.9.0 | Search & Retrieval upgrades + Cognitive layer refinements + sqlx-migrate foundation. PR #5: 14 migraciones versionadas en rust/migrations/, bootstrap transparente para DBs v0.7/v0.8. PR #6: BM25 ts_rank_cd 3-way RRF (Robertson-Walker 1994), MMR diversification con Jaccard sim (Carbonell-Goldstein 1998), OOD Mahalanobis con ridge regularization (Lee NeurIPS 2018), tiktoken-rs cl100k_base exact counting, hnsw.ef_search=200 dinámico en verify (recall@10≈0.99). PR #7: conformal prediction empírica reemplaza z-score gaussiano (Vovk 2005, Angelopoulos-Bates 2023), testing effect Karpicke-Roediger 2008 en zafra decay, Hebbian Δt-aware burst suppression τ=600s (anti-saturación STDP-light), Robbins-Monro stochastic LR en Oja η=0.05/√(1+access/100), source credibility tracking Beta(α,β) Bayesian Yin-Han-Yu IEEE TKDE 2008 con nueva action cuba_calibrar trust. Nuevas deps: tiktoken-rs 0.7, nalgebra 0.33 (no LAPACK), sqlx feature migrate, async-trait 0.1. 23 tools, 97 tests (+22 nuevos), 0 clippy, 0 tech debt, 0 breaking changes. | | 0.8.0 | 4 new tools inspired by Engram Cloud + zero-regression refactor of all v0.7 readers/writers. cuba_proyecto — per-project isolation via project_id UUID FK on 6 tables (NULL = global = back-compat). cuba_pre_compact — snapshot/restore session state across /compact. cuba_sync — git-friendly export (1 JSON per entity + monthly-partitioned episodes + manifest with content-derived hash) and idempotent import. cuba_juez — LLM-judge for ambiguous (cosine 0.6-0.8) contradictions via subprocess to claude CLI ($0 with subscription) or Anthropic API behind feature anthropic-api, with heuristic fallback. Verdicts cached permanently. 4 new idempotent migrations (project scoping, compaction snapshots, sync state, judgments). All 19 v0.7 handlers audited (~30 SQL queries patched with ($N::uuid IS NULL OR project_id = $N OR project_id IS NULL) pattern). New deps: zstd 0.13, async-trait 0.1, optional reqwest 0.12. 75 tests, 0 clippy, 0 tech debt. | | 0.7.0 | 10 algorithmic improvements: PageRank blend (α=0.3, preserves Hebbian/BCM), hybrid verify (trigram+embedding fusion), ONNX semaphore (Little's Law), sigmoid entropy routing (Jaynes MaxEnt), word-level session boost, weighted Hebbian neighbors (Collins & Loftus), exponential coverage saturation, O(n) entropy. 19 bug fixes: hash embeddings corrupting DB (×5), centrality /2, cache LRU, jornada TOCTOU, alarma self-match, 6 schema mismatches. Removed blake3 dependency. MCP Registry publish fixed. npm postinstall version sync. 68 tests, 0 clippy, 0 tech debt. | | 0.6.0 | Contextual Retrieval (+20% recall), importance priors, score breakdown, compact format (~35% fewer tokens), session provenance/diff, semantic dedup, auto-tagging (TF-IDF), Adamic-Adar link prediction, bulk ingest (cuba_ingesta), enhanced health metrics, partial indexes, embedding model versioning. Auto Docker PostgreSQL setup. 19 tools, 56 tests. | | 0.5.0 | Temporal reasoning (before/after/timeline), contradiction detection (cosine + negation heuristics), prospective memory triggers (centinela), Bayesian calibration (calibrar), abductive inference (hipotesis), gap detection (reflexion). 18 tools. | | 0.4.0 | Multilingual embeddings (e5-small, 94 languages), episodic memory (Tulving 1972, power-law Wixted 2004), stratified decay (30d/14d/7d by type), E2E tests in CI with PostgreSQL. 15 tools. | | 0.3.0 | Deep Research V3: exponential decay replaces FSRS-6, dead code eliminated, SEC-002 fix, embeddings storage on write, GraphRAG CTE fix. 13 tools. | | 0.2.0 | Complete Rust rewrite. BCM metaplasticity, Leiden communities, Shannon entropy, blake3 dedup. | | 1.0-1.6 | Python era: 12 tools, Hebbian learning, GraphRAG, REM Sleep, token-budget truncation. |

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