Which integrations are available for this server?

Enables git-friendly export and import of memory data, allowing version control and diff review in PRs. Provides persistent memory storage using PostgreSQL as the database backend, enabling semantic search with pgvector HNSW and full-text search.

Cuba-Memorys

PyPI npm MCP Registry Rust PostgreSQL License: CC BY-NC 4.0 Audit Tech Debt

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

Related MCP server: ogham-mcp

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

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
Bitemporal fact store (v0.10)	Yes	No
Persisted graph metrics & communities (v0.10)	Yes	No
Spreading activation link hints (v0.10)	Yes	No
Built-in faro eval harness (v0.10)	Yes	No

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

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

Detect that no database is configured
Create a Docker container with PostgreSQL + pgvector
Initialize the schema automatically
Start serving 25 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 25 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, importance priors, auto-tagging, session provenance, contextual embedding. Bitemporal mirror to `brain_facts` on add/batch_add (v0.10, default on). Episodic memory (`episode_add`/`episode_list`) and timeline.
`cuba_puente`	Puente — bridge	Typed relations. Traverse, infer, predict — Adamic-Adar + spreading activation neighbors (v0.10).
`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, episode decay, prune, merge, summarize, pagerank (persists `brain_node_metrics` + energy refresh), `communities` (Leiden persist), find_duplicates, export, stats, reembed. Auto-consolidation on >50 observations.
`cuba_eco`	Eco — echo	RLHF feedback: positive (Oja boost), negative (decrease), correct (update with versioning).
`cuba_vigia`	Vigia — watchman	Summary, health, drift (chi-squared), communities (detect + persist), 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).

v0.9–v0.10 additional tools

Tool	Meaning	What it does
`cuba_archivo`	Archivo — archive	CFR-21 inspired hash-chain audit log: append, verify integrity, tail. Tamper-evident session/ops trail.
`cuba_pizarra`	Pizarra — chalkboard	Working memory scratchpad: write/read/clear short-lived notes bound to the active session.

v0.10 environment variables

Variable	Default	Purpose
`CUBA_BITEMPORAL`	on (unset)	Set to `0`/`false`/`off` to stop mirroring observations into `brain_facts`.
`CUBA_RERANKER_PATH`	(unset)	Directory with bge-reranker-v2-m3 ONNX + tokenizer; enables cross-encoder rerank in `cuba_faro`.

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

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)
`brain_facts` (v0.10)	Bitemporal semantics	subject/predicate/object, valid_from/to, `is_current`, entity FK
`brain_fact_supersedes` (v0.10)	Fact lineage	old_fact_id → new_fact_id + reason
`brain_node_metrics` (v0.10)	Graph analytics	pagerank_score, energy_score, betweenness, community_id
`brain_communities` (v0.10)	Leiden clusters	community_name, algorithm_version, modularity
`v_unified_memory_search` (v0.10)	MCP search view	Observations + facts joined via `brain_entities`

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
`CUBA_BITEMPORAL`	on	Bitemporal mirror on write (`0` to disable)
`CUBA_RERANKER_PATH`	—	bge-reranker-v2-m3 ONNX directory for `cuba_faro` rerank
`CUBA_JUDGE`	`auto`	Contradiction judge backend (`heuristic` / `claude_cli` / …)

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

Channel	Version	Install
Cargo / Release	`0.10.0`	releases/tag/v0.10.0
npm	`0.10.0`	`npm i -g cuba-memorys@0.10.0`
PyPI	`1.12.0`	`pip install cuba-memorys==1.12.0`

Security & Audit

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

Check	Result
SQL injection	All queries parameterized (sqlx bind)
SEC-002 wildcard injection	Fixed (POSITION-based)
CVEs in dependencies	`cargo audit` in CI (allowed advisories documented)
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 (`-D warnings` locally)
Tests	118 unit + 13 smoke; E2E 73; MCP live session 25 tools
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.10.0	Bitemporal `brain_facts` (default on), graph metrics/communities/activation, eval harness over live `cuba_faro`, views `v_unified_memory_search` + `v_observations_compat`, migrations `0018`–`0025`, merge-gate scripts. Shipped npm `0.10.0`, PyPI `1.12.0`. Hybrid search unchanged (RRF+BM25+vector).
0.9.3	Real bge-reranker-v2-m3 ONNX cross-encoder in `cuba_faro` (`CUBA_RERANKER_PATH`).
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: 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).