{"id":48330960,"url":"https://github.com/leandropg19/cuba-memorys","last_synced_at":"2026-06-04T13:00:24.908Z","repository":{"id":342958944,"uuid":"1175771298","full_name":"LeandroPG19/cuba-memorys","owner":"LeandroPG19","description":"Persistent memory MCP server for AI agents — Rust, 19 tools, knowledge graph, Hebbian learning, episodic memory, contradiction detection, prospective triggers, Bayesian calibration, zero-config Docker setup.","archived":false,"fork":false,"pushed_at":"2026-05-05T01:02:40.000Z","size":1206,"stargazers_count":21,"open_issues_count":12,"forks_count":3,"subscribers_count":3,"default_branch":"main","last_synced_at":"2026-05-05T03:10:15.586Z","etag":null,"topics":["ai-memory","ai-tools","anti-hallucination","episodic-memory","exponential-decay","graph-database","graphrag","hebbian-learning","knowledge-graph","mcp","mcp-server","model-context-protocol","npm-package","pagerank","postgresql","pypi-package","rag","rust","semantic-search","vector-search"],"latest_commit_sha":null,"homepage":"https://registry.modelcontextprotocol.io","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/LeandroPG19.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":".github/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-08T06:23:50.000Z","updated_at":"2026-05-05T01:02:30.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/LeandroPG19/cuba-memorys","commit_stats":null,"previous_names":["lenadro1910/cuba-memorys","leandropg19/cuba-memorys"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/LeandroPG19/cuba-memorys","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LeandroPG19%2Fcuba-memorys","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LeandroPG19%2Fcuba-memorys/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LeandroPG19%2Fcuba-memorys/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LeandroPG19%2Fcuba-memorys/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/LeandroPG19","download_url":"https://codeload.github.com/LeandroPG19/cuba-memorys/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LeandroPG19%2Fcuba-memorys/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33905359,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-04T02:00:06.755Z","response_time":64,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-memory","ai-tools","anti-hallucination","episodic-memory","exponential-decay","graph-database","graphrag","hebbian-learning","knowledge-graph","mcp","mcp-server","model-context-protocol","npm-package","pagerank","postgresql","pypi-package","rag","rust","semantic-search","vector-search"],"created_at":"2026-04-05T01:04:19.128Z","updated_at":"2026-06-04T13:00:24.887Z","avatar_url":"https://github.com/LeandroPG19.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!-- mcp-name: io.github.LeandroPG19/cuba-memorys --\u003e\n# Cuba-Memorys\n\n[![CI](https://github.com/LeandroPG19/cuba-memorys/actions/workflows/ci.yml/badge.svg)](https://github.com/LeandroPG19/cuba-memorys/actions/workflows/ci.yml)\n[![PyPI](https://img.shields.io/pypi/v/cuba-memorys?logo=pypi\u0026logoColor=white\u0026label=PyPI)](https://pypi.org/project/cuba-memorys/)\n[![npm](https://img.shields.io/npm/v/cuba-memorys?logo=npm\u0026logoColor=white\u0026label=npm)](https://www.npmjs.com/package/cuba-memorys)\n[![MCP Registry](https://img.shields.io/badge/MCP_Registry-published-8A2BE2?logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0id2hpdGUiPjxwYXRoIGQ9Ik0xMiAyQzYuNDggMiAyIDYuNDggMiAxMnM0LjQ4IDEwIDEwIDEwIDEwLTQuNDggMTAtMTBTMTcuNTIgMiAxMiAyem0tMiAxNWwtNS01IDEuNDEtMS40MUwxMCAxNC4xN2w3LjU5LTcuNTlMMTkgOGwtOSA5eiIvPjwvc3ZnPg==)](https://registry.modelcontextprotocol.io)\n[![Rust](https://img.shields.io/badge/rust-1.93+-orange?logo=rust\u0026logoColor=white)](https://rust-lang.org)\n[![PostgreSQL](https://img.shields.io/badge/PostgreSQL-18-336791?logo=postgresql\u0026logoColor=white)](https://postgresql.org)\n[![License: CC BY-NC 4.0](https://img.shields.io/badge/license-CC%20BY--NC%204.0-green)](https://creativecommons.org/licenses/by-nc/4.0/)\n[![Audit](https://img.shields.io/badge/audit-GO-brightgreen)](https://github.com/LeandroPG19/cuba-memorys)\n[![Tech Debt](https://img.shields.io/badge/tech%20debt-0-brightgreen)](https://github.com/LeandroPG19/cuba-memorys)\n\n**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.\n\n25 tools with Cuban soul. Sub-millisecond handlers. Mathematically rigorous.\n\n\u003e [!IMPORTANT]\n\u003e **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.\n\u003e **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).\n\u003e **Graph metrics** (`0022`–`0023`): `brain_node_metrics` (PageRank, energy, betweenness) + `brain_communities`; `cuba_zafra pagerank` / **`communities`** persist; `cuba_vigia` communities metric writes tags.\n\u003e **Spreading activation** enriches `cuba_puente predict` alongside Adamic-Adar.\n\u003e **Eval harness** (`rust/src/eval/`): nDCG@k, MRR, P@k, R@k over live `cuba_faro` hybrid (production path unchanged).\n\u003e **Unified search view** (`v_unified_memory_search`, `0024`) joins facts via `brain_entities` — never `fact_id = node_id`.\n\u003e **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).\n\n\u003e [!NOTE]\n\u003e **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.\n\n## Demo\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/demo-v0.10.gif\" alt=\"Cuba-Memorys v0.10.0 terminal demo — 25 MCP tools, bitemporal facts, hybrid BM25+RRF search, PageRank, Leiden communities, session lifecycle\" width=\"700\" /\u003e\n\u003c/p\u003e\n\n---\n\n## Why Cuba-Memorys?\n\nAI agents forget everything between conversations. Cuba-Memorys solves this:\n\n- **Stratified exponential decay** — Memories fade by type (facts=30d, errors=14d, context=7d), strengthen with access\n- **Hebbian + BCM metaplasticity** — Self-normalizing importance via Oja's rule with EMA sliding threshold\n- **Hybrid RRF fusion search** — pg_trgm + full-text + pgvector HNSW, entropy-routed weighting (k=60), temporal filters, tag filters, compact format\n- **Knowledge graph** — Entities, observations, typed relations with Leiden community detection and Adamic-Adar link prediction\n- **Anti-hallucination grounding** — Verify claims with graduated confidence + Bayesian calibration over time\n- **Episodic memory** — Separate temporal events (Tulving 1972) with power-law decay I(t) = I₀/(1+ct)^β (Wixted 2004)\n- **Contradiction detection** — Scan for semantic conflicts via embedding cosine + bilingual negation heuristics\n- **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\n- **Prospective memory** — Triggers that fire on entity access, session start, or error match (\"remind me when X\")\n- **Contextual Retrieval** — Entity context prepended before embedding (Anthropic technique, +20% recall)\n- **REM Sleep consolidation** — Autonomous stratified decay + PageRank + auto-prune + auto-merge + episode decay\n- **Graph intelligence** — PageRank, Leiden communities, Brandes centrality, Shannon entropy, gap detection\n- **Session awareness** — Provenance tracking, session diff, importance priors per observation type\n- **Project scoping** *(v0.8)* — Isolate memories per project (`cuba_jornada start --project NAME`); legacy NULL rows stay globally visible (zero-regression upgrade path)\n- **Compaction-survival snapshots** *(v0.8)* — `cuba_pre_compact snapshot` persists session state before `/compact`; `restore` re-injects post-compact\n- **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\n- **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\n- **MMR diversification** *(v0.9)* — `cuba_faro diversify=true` aplica Carbonell-Goldstein 1998 con Jaccard sim entre candidatos, evita top-K redundantes\n- **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\n- **Conformal prediction** *(v0.9)* — quantiles empíricos sin asumir normalidad (Vovk 2005, Angelopoulos-Bates 2023); captura anisotropía cosine documentada por Ethayarajh 2019\n- **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\n- **Hebbian Δt-aware** *(v0.9)* — burst suppression `boost *= (1 - exp(-Δt/τ))`, τ=600s; anti-saturación inspirada en STDP triplet rules (Pfister-Gerstner 2006)\n- **Robbins-Monro stochastic LR** *(v0.9)* — `η = 0.05/√(1 + access_count/100)` en Oja's rule, convergencia O(1/√t)\n- **Source credibility tracking** *(v0.9)* — Beta(α,β) Bayesian update per source en `brain_source_trust` (Yin-Han-Yu IEEE TKDE 2008), action `cuba_calibrar trust`\n- **sqlx-migrate** — 25 migraciones SQL versionadas en `rust/migrations/` (`0001`–`0025`), bootstrap transparente para DBs legacy\n- **Bitemporal facts** *(v0.10)* — `brain_facts` + supersede chain; mirrors observations on write (default on)\n- **Graph energy \u0026 communities** *(v0.10)* — persisted PageRank/energy in `brain_node_metrics`; Leiden → `brain_communities`\n- **Spreading activation** *(v0.10)* — multi-hop graph propagation for link prediction hints\n- **Retrieval benchmarks** *(v0.10)* — `eval/` harness measures live `cuba_faro` (nDCG, MRR, P@k, R@k)\n- **CFR-21 audit log** *(v0.9)* — `cuba_archivo` hash-chain tamper evidence\n- **Working memory buffer** *(v0.9)* — `cuba_pizarra` scratchpad per session\n- **Error memory** — Never repeat the same mistake (anti-repetition guard + pattern detection)\n\n### Comparison\n\n| Feature | Cuba-Memorys | Basic Memory MCPs |\n| ------- | :----------: | :---------------: |\n| Knowledge graph with typed relations | Yes | No |\n| Exponential importance decay | Yes | No |\n| Hebbian learning + BCM metaplasticity | Yes | No |\n| Hybrid entropy-routed RRF fusion | Yes | No |\n| KG-neighbor query expansion | Yes | No |\n| GraphRAG topological enrichment | Yes | No |\n| Leiden community detection | Yes | No |\n| Brandes betweenness centrality | Yes | No |\n| Shannon entropy analytics | Yes | No |\n| Adaptive prediction error gating | Yes | No |\n| Anti-hallucination verification | Yes | No |\n| Error pattern detection | Yes | No |\n| Session-aware search boost | Yes | No |\n| REM Sleep autonomous consolidation | Yes | No |\n| Multilingual ONNX embeddings (e5-small) | Yes | No |\n| Episodic memory (power-law decay) | Yes | No |\n| Contradiction detection | Yes | No |\n| Prospective memory triggers | Yes | No |\n| Bayesian confidence calibration | Yes | No |\n| Link prediction (Adamic-Adar) | Yes | No |\n| Auto-tagging (TF-IDF) | Yes | No |\n| Contextual Retrieval (Anthropic) | Yes | No |\n| Temporal search filters | Yes | No |\n| Zero-config Docker auto-setup | Yes | No |\n| Write-time dedup gate | Yes | No |\n| Contradiction auto-supersede | Yes | No |\n| GDPR Right to Erasure | Yes | No |\n| Graceful shutdown (SIGTERM/SIGINT) | Yes | No |\n| Project scoping (per-project isolation) *(v0.8)* | Yes | No |\n| Compaction-survival snapshots *(v0.8)* | Yes | No |\n| Git-friendly export/import *(v0.8)* | Yes | No |\n| LLM-judge for ambiguous contradictions *(v0.8)* | Yes | No |\n| BM25 + vector + text 3-way RRF *(v0.9)* | Yes | No |\n| MMR diversification *(v0.9)* | Yes | No |\n| OOD abstention via Mahalanobis *(v0.9)* | Yes | No |\n| Conformal prediction (distribution-free) *(v0.9)* | Yes | No |\n| Testing-effect decay *(v0.9)* | Yes | No |\n| Hebbian Δt-aware burst suppression *(v0.9)* | Yes | No |\n| Robbins-Monro stochastic LR *(v0.9)* | Yes | No |\n| Source credibility tracking Beta(α,β) *(v0.9)* | Yes | No |\n| sqlx-migrate versioned migrations *(v0.9+)* | Yes | No |\n| Exact tiktoken token budget *(v0.9)* | Yes | No |\n| Bitemporal fact store *(v0.10)* | Yes | No |\n| Persisted graph metrics \u0026 communities *(v0.10)* | Yes | No |\n| Spreading activation link hints *(v0.10)* | Yes | No |\n| Built-in faro eval harness *(v0.10)* | Yes | No |\n\n---\n\n## Installation\n\n### PyPI (recommended)\n\n```bash\npip install cuba-memorys==1.12.0   # wheels bundle the Rust binary (v0.10.0)\n```\n\n### npm\n\n```bash\nnpm install -g cuba-memorys@0.10.0   # downloads binary from GitHub Release on postinstall\n```\n\n### From source\n\n```bash\ngit clone https://github.com/LeandroPG19/cuba-memorys.git\ncd cuba-memorys/rust\ncargo build --release\n```\n\n### Binary download\n\nPre-built binaries available at [GitHub Releases](https://github.com/LeandroPG19/cuba-memorys/releases).\n\n---\n\n## Quick Start\n\n**Zero configuration required** — just install and add to your editor. Cuba-memorys automatically provisions a PostgreSQL database via Docker on first run.\n\n\u003e **Prerequisite**: [Docker](https://docs.docker.com/get-docker/) must be installed and running.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eClaude Code\u003c/b\u003e\u003c/summary\u003e\n\n```bash\nnpm install -g cuba-memorys\nclaude mcp add cuba-memorys -- cuba-memorys\n```\nThat's it. On first run, Cuba-memorys will:\n1. Detect that no database is configured\n2. Create a Docker container with PostgreSQL + pgvector\n3. Initialize the schema automatically\n4. Start serving 25 MCP tools\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eCursor / Windsurf / VS Code\u003c/b\u003e\u003c/summary\u003e\n\n```bash\nnpm install -g cuba-memorys\n```\n\nAdd to your MCP config (`.cursor/mcp.json`, `.windsurf/mcp.json`, or `.vscode/mcp.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"cuba-memorys\": {\n      \"command\": \"cuba-memorys\"\n    }\n  }\n}\n```\n\nNo `DATABASE_URL` needed — auto-provisioned via Docker on first run.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eAdvanced: Custom PostgreSQL\u003c/b\u003e\u003c/summary\u003e\n\nIf you already have PostgreSQL with pgvector, set the environment variable:\n\n```json\n{\n  \"mcpServers\": {\n    \"cuba-memorys\": {\n      \"command\": \"cuba-memorys\",\n      \"env\": {\n        \"DATABASE_URL\": \"postgresql://user:pass@localhost:5432/brain\"\n      }\n    }\n  }\n}\n```\n\n\u003c/details\u003e\n\n### Optional: Multilingual ONNX Embeddings\n\nFor real multilingual-e5-small semantic embeddings (94 languages, 384d) instead of hash-based fallback:\n\n```bash\n./rust/scripts/download_model.sh  # Downloads ~113MB model\nexport ONNX_MODEL_PATH=\"$HOME/.cache/cuba-memorys/models\"\nexport ORT_DYLIB_PATH=\"/path/to/libonnxruntime.so\"\n```\n\nWithout 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.\n\n---\n\n## The 25 Tools\n\nEvery tool is named after Cuban culture — memorable, professional, meaningful.\n\n### Knowledge Graph\n\n| Tool | Meaning | What it does |\n|------|---------|-------------|\n| `cuba_alma` | **Alma** — soul | CRUD entities. Types: `concept`, `project`, `technology`, `person`, `pattern`, `config`. Hebbian boost + access tracking. Fires prospective triggers on access. |\n| `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**. |\n| `cuba_puente` | **Puente** — bridge | Typed relations. **Traverse**, **infer**, **predict** — Adamic-Adar + **spreading activation** neighbors *(v0.10)*. |\n| `cuba_ingesta` | **Ingesta** — intake | Bulk knowledge ingestion: accepts arrays of observations or long text with auto-classification by paragraph. |\n\n### Search \u0026 Verification\n\n| Tool | Meaning | What it does |\n|------|---------|-------------|\n| `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. |\n\n### Error Memory\n\n| Tool | Meaning | What it does |\n|------|---------|-------------|\n| `cuba_alarma` | **Alarma** — alarm | Report errors. Auto-detects patterns (\u003e=3 similar = warning). Fires prospective triggers on error match. |\n| `cuba_remedio` | **Remedio** — remedy | Resolve errors with cross-reference to similar unresolved issues. |\n| `cuba_expediente` | **Expediente** — case file | Search past errors. **Anti-repetition guard**: warns if similar approach failed before. |\n\n### Sessions \u0026 Decisions\n\n| Tool | Meaning | What it does |\n|------|---------|-------------|\n| `cuba_jornada` | **Jornada** — workday | Session tracking with goals, outcomes, **session diff** (what was learned), and **previous session** context on start. Fires prospective triggers. |\n| `cuba_decreto` | **Decreto** — decree | Record architecture decisions with context, alternatives, rationale. |\n\n### Cognition \u0026 Analysis\n\n| Tool | Meaning | What it does |\n|------|---------|-------------|\n| `cuba_reflexion` | **Reflexion** — reflection | Gap detection: isolated entities, underconnected hubs, type silos, observation gaps, density anomalies (z-score). |\n| `cuba_hipotesis` | **Hipotesis** — hypothesis | Abductive inference: given an effect, find plausible causes via backward causal traversal. Plausibility = path_strength x importance. |\n| `cuba_contradiccion` | **Contradiccion** — contradiction | Scan for semantic conflicts between same-entity observations via embedding cosine + bilingual negation heuristics. |\n| `cuba_centinela` | **Centinela** — sentinel | Prospective memory triggers: \"remind me when X is accessed / session starts / error matches\". Auto-deactivate on max_fires, expiration support. |\n| `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. |\n\n### Memory Maintenance\n\n| Tool | Meaning | What it does |\n|------|---------|-------------|\n| `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 \u003e50 observations. |\n| `cuba_eco` | **Eco** — echo | RLHF feedback: positive (Oja boost), negative (decrease), correct (update with versioning). |\n| `cuba_vigia` | **Vigia** — watchman | Summary, **health**, drift (chi-squared), **communities** (detect + persist), Brandes bridges. |\n| `cuba_forget` | **Forget** — forget | GDPR Right to Erasure: cascading hard-delete of entity and ALL references (observations, episodes, relations, errors, sessions). Irreversible. |\n\n### v0.8 — Engram-inspired additions\n\n| Tool | Meaning | What it does |\n|------|---------|-------------|\n| `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`. |\n| `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. |\n| `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). |\n| `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). |\n\n### v0.8 environment variables\n\n| Variable | Default | Purpose |\n|----------|---------|---------|\n| `CUBA_PROJECT_FILTER` | _(unset)_ | Set to `off` to disable project scoping (admin/debug). |\n| `CUBA_SYNC_DIR` | `./.cuba-memorys` | Root for `cuba_sync` export/import. |\n| `CUBA_JUDGE` | `auto` | Judge backend: `claude_cli` / `anthropic_api` / `heuristic` / `auto`. |\n| `CUBA_JUEZ_CLI` | `claude` | Subprocess CLI for `ClaudeCodeJudge`. |\n| `CUBA_JUEZ_MODEL` | `claude-haiku-4-5` | Model passed to the judge backend. |\n| `CUBA_JUEZ_TIMEOUT_SECS` | `30` | Subprocess/HTTP timeout. |\n| `CUBA_JUEZ_MAX_PAIRS` | `5` | Cap on pairs `cuba_juez scan_entity` will escalate per call. |\n| `ANTHROPIC_API_KEY` | _(unset)_ | Required for `AnthropicApiJudge` (only when feature `anthropic-api` is built in). |\n\n### v0.9–v0.10 additional tools\n\n| Tool | Meaning | What it does |\n|------|---------|-------------|\n| `cuba_archivo` | **Archivo** — archive | CFR-21 inspired **hash-chain audit log**: append, verify integrity, tail. Tamper-evident session/ops trail. |\n| `cuba_pizarra` | **Pizarra** — chalkboard | **Working memory** scratchpad: write/read/clear short-lived notes bound to the active session. |\n\n### v0.10 environment variables\n\n| Variable | Default | Purpose |\n|----------|---------|---------|\n| `CUBA_BITEMPORAL` | **on** (unset) | Set to `0`/`false`/`off` to stop mirroring observations into `brain_facts`. |\n| `CUBA_RERANKER_PATH` | _(unset)_ | Directory with bge-reranker-v2-m3 ONNX + tokenizer; enables cross-encoder rerank in `cuba_faro`. |\n\n---\n\n## Architecture\n\n```\ncuba-memorys/\n├── docker-compose.yml           # Dedicated PostgreSQL 18 (port 5488)\n├── server.json                  # MCP Registry manifest (npm 0.10.0 / PyPI 1.12.0)\n├── pyproject.toml               # Maturin (bindings = \"bin\") — PyPI wheel\n├── package.json                 # npm wrapper → GitHub Release binary\n├── scripts/                     # merge-gate, backup/restore, MCP live session test\n└── rust/                        # v0.10.0\n    ├── migrations/              # sqlx-migrate 0001–0025 (bitemporal, graph, views)\n    ├── src/\n    │   ├── main.rs              # mimalloc + graceful shutdown\n    │   ├── lib.rs               # Library surface (handlers, eval, graph, core)\n    │   ├── protocol.rs          # JSON-RPC 2.0 + MCP correlator / sampling / cancel\n    │   ├── core/                # bitemporal, entity_linking, temporal_query\n    │   ├── eval/                # faro benchmark harness (nDCG, MRR, P@k, R@k)\n    │   ├── handlers/            # 25 MCP tool handlers\n    │   ├── cognitive/           # Hebbian, conformal PE, calibration, judge\n    │   ├── search/              # RRF, BM25, MMR, OOD, rerank, tiktoken budget\n    │   ├── graph/               # PageRank, Leiden, energy, activation, k-core\n    │   └── embeddings/          # ONNX e5-small (contextual), hash fallback\n    ├── scripts/download_model.sh\n    └── tests/                   # unit + smoke + integration + e2e_all_tools.py\n```\n\n### Performance: Rust vs Python\n\n| Metric | Python v1.6.0 | Rust v0.7.0 |\n| ------ | :-----------: | :---------: |\n| Binary size | ~50MB (venv) | **7.6MB** |\n| Entity create | ~2ms | **498us** |\n| Hybrid search | \u003c5ms | **2.52ms** |\n| Analytics | \u003c2.5ms | **958us** |\n| Memory usage | ~120MB | **~15MB** |\n| Startup time | ~2s | **\u003c100ms** |\n| Dependencies | 12 Python packages | **0 runtime deps** |\n\n### Database Schema\n\n| Table | Purpose | Key Features |\n|-------|---------|-------------|\n| `brain_entities` | KG nodes | tsvector + pg_trgm + GIN indexes, importance, bcm_theta |\n| `brain_observations` | Facts with provenance | 9 types, versioning, `vector(384)`, importance priors, auto-tags TEXT[], session_id FK, embedding_model tracking |\n| `brain_relations` | Typed edges | 5 types, bidirectional, Hebbian strength, ON CONFLICT dedup |\n| `brain_errors` | Error memory | JSONB context, synapse weight, pattern detection |\n| `brain_sessions` | Working sessions | Goals (JSONB), outcome tracking, session diff |\n| `brain_episodes` | Episodic memory | Tulving 1972, actors/artifacts TEXT[], power-law decay (Wixted 2004) |\n| `brain_triggers` | Prospective memory | on_access/on_session_start/on_error_match, max_fires, expiration |\n| `brain_verify_log` | Bayesian calibration | claim, confidence, grounding_level, outcome (correct/incorrect) |\n| `brain_facts` *(v0.10)* | Bitemporal semantics | subject/predicate/object, valid_from/to, `is_current`, entity FK |\n| `brain_fact_supersedes` *(v0.10)* | Fact lineage | old_fact_id → new_fact_id + reason |\n| `brain_node_metrics` *(v0.10)* | Graph analytics | pagerank_score, energy_score, betweenness, community_id |\n| `brain_communities` *(v0.10)* | Leiden clusters | community_name, algorithm_version, modularity |\n| `v_unified_memory_search` *(v0.10)* | MCP search view | Observations + facts joined via `brain_entities` |\n\n### Search Pipeline\n\n**Reciprocal Rank Fusion (RRF, k=60)** with entropy-routed weighting:\n\n| # | Signal | Source | Condition |\n|---|--------|--------|-----------|\n| 1 | Entities (ts_rank + trigrams + importance) | `brain_entities` | Always |\n| 2 | Observations (ts_rank + trigrams + importance) | `brain_observations` | Always |\n| 3 | Errors (ts_rank + trigrams + synapse_weight) | `brain_errors` | Always |\n| 4 | **Vector cosine distance (HNSW)** | `brain_observations.embedding` | pgvector installed |\n| 5 | Episodes (ts_rank + trigrams + importance) | `brain_episodes` | Always |\n\n**Post-fusion pipeline:** Dedup -\u003e KG-neighbor expansion -\u003e Session boost -\u003e Score breakdown -\u003e GraphRAG enrichment -\u003e Token-budget truncation -\u003e Compact format (optional) -\u003e Batch access tracking\n\n**Filters:** `before`/`after` (ISO8601 temporal), `tags` (keyword), `format` (verbose/compact)\n\n---\n\n## Mathematical Foundations\n\nBuilt on peer-reviewed algorithms, not ad-hoc heuristics:\n\n### Stratified Exponential Decay (V4)\n```\nimportance_new = importance * exp(-0.693 * days_since_access / halflife)\n```\nStratified 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 (score*0.7 + importance*0.3).\n\n### Hebbian + BCM — Oja (1982), Bienenstock-Cooper-Munro (1982)\n```\nPositive: importance += eta * throttle(access_count, theta_M)\nBCM EMA: theta_M = max(10, (1-alpha)*theta_prev + alpha*access_count)\n```\nV3: theta_M persisted in `bcm_theta` column for true temporal smoothing.\n\n### RRF Fusion — Cormack (2009)\n```\nRRF(d) = sum( w_i / (k + rank_i(d)) )   where k = 60\n```\nEntropy-routed weighting via smooth sigmoid (Jaynes 1957 MaxEnt):\n```\nt = sigmoid(2.0 * (entropy - 2.75))\ntext_w  = 0.7 - 0.4*t    (keyword-heavy → balanced → semantic-heavy)\nvector_w = 0.3 + 0.4*t   (always sums to 1.0)\n```\nReplaces V2 step function which had 40% relative jumps at thresholds.\n\n### PageRank Blend — Brin \u0026 Page (1998)\n```\nimportance_new = 0.3 * rank_normalized + 0.7 * importance_existing\n```\nMin-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).\n\n### Other Algorithms\n\n| Algorithm | Reference | Used in |\n|-----------|-----------|---------|\n| **Leiden communities** | Traag et al. (Nature 2019) | `community.rs` -\u003e `vigia.rs` |\n| **PageRank + blend** | Brin \u0026 Page (1998) | `pagerank.rs` -\u003e convex combination (α=0.3) |\n| **Brandes centrality** | Brandes (2001) | `centrality.rs` -\u003e undirected normalization |\n| **Adaptive PE gating** | Friston (Nature 2023) | `prediction_error.rs` -\u003e `cronica.rs` |\n| **Shannon entropy** | Shannon (1948) | `density.rs` -\u003e information gating |\n| **Chi-squared drift** | Pearson (1900) | Error distribution change detection |\n| **Power-law forgetting** | Wixted (2004) | `setup.rs` -\u003e episodic memory decay |\n| **Contextual Retrieval** | Anthropic (2024) | `onnx.rs` -\u003e entity context prepend |\n| **Adamic-Adar** | Adamic \u0026 Adar (2003) | `puente.rs` -\u003e link prediction |\n| **Episodic/Semantic** | Tulving (1972) | `brain_episodes` vs `brain_observations` |\n| **Bayesian calibration** | Beta distribution | `calibrar.rs` -\u003e P(correct\\|level) |\n\n---\n\n## Configuration\n\n### Environment Variables\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `DATABASE_URL` | — | PostgreSQL connection string (auto-provisioned via Docker if not set) |\n| `ONNX_MODEL_PATH` | — | Path to multilingual-e5-small model directory (optional) |\n| `ORT_DYLIB_PATH` | — | Path to libonnxruntime.so (optional) |\n| `RUST_LOG` | `cuba_memorys=info` | Log level filter |\n| `CUBA_BITEMPORAL` | on | Bitemporal mirror on write (`0` to disable) |\n| `CUBA_RERANKER_PATH` | — | bge-reranker-v2-m3 ONNX directory for `cuba_faro` rerank |\n| `CUBA_JUDGE` | `auto` | Contradiction judge backend (`heuristic` / `claude_cli` / …) |\n\n### Docker Compose\n\nDedicated PostgreSQL 18 Alpine:\n\n- **Port**: 5488 (avoids conflicts with 5432/5433)\n- **Resources**: 256MB RAM, 0.5 CPU\n- **Restart**: always\n- **Healthcheck**: `pg_isready` every 10s\n\n---\n\n## How It Works\n\n### 1. The agent learns from your project\n\n```\nAgent: FastAPI requires async def with response_model.\n-\u003e cuba_alma(create, \"FastAPI\", technology)\n-\u003e cuba_cronica(add, \"FastAPI\", \"All endpoints must be async def with response_model\")\n```\n\n### 2. Error memory prevents repeated mistakes\n\n```\nAgent: IntegrityError: duplicate key on numero_parte.\n-\u003e cuba_alarma(\"IntegrityError\", \"duplicate key on numero_parte\")\n-\u003e cuba_expediente: Similar error found! Solution: \"Add SELECT EXISTS before INSERT\"\n```\n\n### 3. Anti-hallucination grounding\n\n```\nAgent: Let me verify before responding...\n-\u003e cuba_faro(\"FastAPI uses Django ORM\", mode=\"verify\")\n-\u003e confidence: 0.0, level: \"unknown\" — \"No evidence. High hallucination risk.\"\n```\n\n### 4. Memories decay naturally\n\n```\nInitial importance:    0.5  (new observation)\nAfter 30d no access:  0.25 (halved by exponential decay)\nAfter 60d no access:  0.125\nActive access resets the clock — frequently used memories stay strong.\n```\n\n### 5. Community intelligence\n\n```\n-\u003e cuba_vigia(metric=\"communities\")\n-\u003e Community 0 (4 members): [FastAPI, Pydantic, SQLAlchemy, PostgreSQL]\n  Summary: \"Backend stack: async endpoints, V2 validation, 2.0 ORM...\"\n-\u003e Community 1 (3 members): [React, Next.js, TypeScript]\n  Summary: \"Frontend stack: React 19, App Router, strict types...\"\n```\n\n---\n\n## Release \u0026 QA (v0.10)\n\nPre-merge / pre-release gate (requires Postgres on `:5488`):\n\n```bash\nexport DATABASE_URL=postgresql://cuba:memorys2026@127.0.0.1:5488/brain\n./scripts/merge-gate.sh          # fmt, clippy, unit+integration, E2E 73, MCP live 25, cargo audit\n./scripts/backup-db.sh           # optional; keeps last 7 dumps in ./backups/\n```\n\nPublishing (maintainers): tag `v0.10.0` triggers [`.github/workflows/publish.yml`](.github/workflows/publish.yml) — GitHub Release binaries, PyPI wheels, npm, MCP Registry.\n\nRegenerate README demo GIF: `./scripts/record-demo-gif.sh` → `assets/demo-v0.10.gif` (requires [asciinema](https://asciinema.org/) + [agg](https://github.com/asciinema/agg)).\n\n| Channel | Version | Install |\n|---------|---------|---------|\n| Cargo / Release | `0.10.0` | [releases/tag/v0.10.0](https://github.com/LeandroPG19/cuba-memorys/releases/tag/v0.10.0) |\n| npm | `0.10.0` | `npm i -g cuba-memorys@0.10.0` |\n| PyPI | `1.12.0` | `pip install cuba-memorys==1.12.0` |\n\n---\n\n## Security \u0026 Audit\n\n**Internal Audit Verdict: GO** (2026-03-28) — re-validated on v0.10 merge gate.\n\n| Check | Result |\n|-------|:------:|\n| SQL injection | All queries parameterized (sqlx bind) |\n| SEC-002 wildcard injection | Fixed (POSITION-based) |\n| CVEs in dependencies | `cargo audit` in CI (allowed advisories documented) |\n| UTF-8 safety | `safe_truncate` on all string slicing |\n| Secrets | All via environment variables |\n| Division by zero | Protected with `.max(1e-9)` |\n| Error handling | All `?` propagated with `anyhow::Context` |\n| Clippy | 0 warnings (`-D warnings` locally) |\n| Tests | 118 unit + 13 smoke; E2E 73; MCP live session 25 tools |\n| Licenses | All MIT/Apache-2.0 (0 GPL/AGPL) |\n\n---\n\n## Dependencies\n\n| Crate | Purpose | License |\n|-------|---------|---------|\n| `tokio` | Async runtime | MIT |\n| `sqlx` | PostgreSQL (async) | MIT/Apache-2.0 |\n| `serde` / `serde_json` | Serialization | MIT/Apache-2.0 |\n| `pgvector` | Vector similarity | MIT |\n| `ort` | ONNX Runtime (optional) | MIT/Apache-2.0 |\n| `tokenizers` | HuggingFace tokenizers | Apache-2.0 |\n| `mimalloc` | Global allocator | MIT |\n| `tracing` | Structured JSON logging | MIT |\n| `lru` | O(1) LRU cache | MIT |\n| `chrono` | Timezone-aware timestamps | MIT/Apache-2.0 |\n\n---\n\n## Version History\n\n| Version | Key Changes |\n|---------|-------------|\n| **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). |\n| **0.9.3** | Real bge-reranker-v2-m3 ONNX cross-encoder in `cuba_faro` (`CUBA_RERANKER_PATH`). |\n| **0.9.0** | Search \u0026 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. |\n| **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. |\n| **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 \u0026 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. |\n| **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. |\n| **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. |\n| **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. |\n| **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. |\n| **0.2.0** | Complete Rust rewrite. BCM metaplasticity, Leiden communities, Shannon entropy, blake3 dedup. |\n| **1.0-1.6** | Python era: 12 tools, Hebbian learning, GraphRAG, REM Sleep, token-budget truncation. |\n\n---\n\n## License\n\n[CC BY-NC 4.0](https://creativecommons.org/licenses/by-nc/4.0/) — Free to use and modify, **not for commercial use**.\n\n---\n\n## Author\n\n**Leandro Perez G.**\n\n- GitHub: [@LeandroPG19](https://github.com/LeandroPG19)\n- Email: [leandropatodo@gmail.com](mailto:leandropatodo@gmail.com)\n\n## Credits\n\nMathematical foundations: Oja (1982), Bienenstock, Cooper \u0026 Munro (1982, BCM), Cormack (2009, RRF), Brin \u0026 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 \u0026 Adar (2003, link prediction), Anthropic (2024, Contextual Retrieval), Wang et al. (2022, E5 embeddings), Malkov \u0026 Yashunin (2018, HNSW), Jaynes (1957, MaxEnt sigmoid routing), Robertson (1977, score fusion), Collins \u0026 Loftus (1975, spreading activation).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fleandropg19%2Fcuba-memorys","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fleandropg19%2Fcuba-memorys","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fleandropg19%2Fcuba-memorys/lists"}