Cuba Memorys

古巴记忆

  ](https://www.npmjs.com/package/cuba-memorys)      

AI代理的持久内存 --一个模型上下文协议（MCP）服务器，为AI编码助手提供长期记忆，包括知识图、神经科学启发的算法和抗幻觉基础。

23种具有古巴灵魂的工具。亚毫秒处理程序。数学严谨。

\[！重要\] v0.9.0版本 --搜索和检索升级+认知层改进+sqlx迁移基础。零破坏性变化。 cuba_faro 现在进行RRF 3路合并（文本+矢量）+ BM25 ts_rank_cd，罗伯逊·沃克1994），骗子 MMR多样化 操作（Carbonell-Goldstein 1998，λ=0.7）， OOD弃权 通过Mahalanobis与Ridge-Regularized∑ò（Lee Neurips 2018）， hnsw.ef_search=200 动态的 verify (recall@10≈0.99），并通过 tiktoken rs cl100k_base （取代了MIS-30%西班牙语的“Len/4”启发式）。 认知: cuba_zafra decay 骗局 测试效应 （Karpicke-Roediger Science 2008）-半飞攀登者 (1 + ln(1+access_count)). HebbianΔt感知 （抗饱和突发，τ=600s，灵感来自STDP Triplet）。 Robbins-Monro随机LR en Oja阳性/阴性(η = 0.05/√(1+access/100)). 共形预测 Ethayarakh EMNLP 2019记录的经验取代了PE Gating（Vovk 2005，Angelopoulos-Bates 2023）-无分布，捕获各向异性。 来源可信度跟踪 贝塔（α，β）贝叶斯更新结果（Yin Han Yu IEEE TKDE 2008），新行动 cuba_calibrar trust. 基础：通过版本控制的SQL迁移 sqlx-migrate （14个存档，幂等，引导透明）。23个工具，97个测试，0个简短的警告，0个科技债务。

\[！重要\] v0.8.0 --4个受Engram Cloud启发的新工具+零回归重构。 cuba_proyecto 按项目隔离内存（列 project_id 在6个表上，NULL=全局=向后兼容）。 cuba_pre_compact 在之前保留活动会话的降价摘要 /compact 并在压缩后将其恢复。 cuba_sync 编写一个git友好的导出（每个实体1个JSON，每月分区的剧集，可选的zstd嵌入blob），并幂等地重新导入它。 cuba_juez 将模糊的相似性（0.6-0.8）观察对升级为LLM判断——默认为对用户安装的子流程调用 claude CLI（订阅Pro/Max时为0美元）；还支持 anthropic-api 货物功能，当两者都不可用时，具有启发式回退功能。判决永久缓存在 brain_judgments所有19个v0.7工具都经过了项目范围审核（≈修补了30个SQL查询）。75个测试通过，0个简短的警告，0个科技债务。

演示

______________________________________________________________________

为什么古巴记忆？

AI代理在对话之间会忘记一切。古巴记忆解决了这个问题：

• 分层指数衰减 --记忆按类型逐渐消失（事实=30s，错误=14d，上下文=7d），随着访问而增强
• Hebbian+BCM化塑性 --基于EMA滑动阈值的Oja规则的自归一化重要性
• 混合RRF融合搜索 --pg_trgm+全文+pgvector HNSW，熵路由加权（k=60），时间过滤器，标签过滤器，紧凑格式
• 知识图谱 --实体、观察结果、与莱顿社区检测和阿达姆阿达尔链接预测的类型关系
• 抗幻觉接地 --随着时间的推移，用分级置信度+贝叶斯校准验证索赔
• 情景记忆 --幂律衰变I（t）=I的独立时间事件（Tulving 1972）₀/（1+ct）^β（Wixted 2004）
• 矛盾检测 --通过嵌入余弦+双语否定启发式算法扫描语义冲突
• 法学硕士模糊矛盾评判 *（v0.8）* --将余弦0.6-0.8对升级到Claude Code CLI子流程($0 带有订阅）或Anthropic API（功能标志）。永久缓存判决
• 前瞻性记忆 --触发实体访问、会话启动或错误匹配（“X时提醒我”）
• 上下文检索 --嵌入前预先添加实体上下文（人择技术，+20%召回率）
• REM睡眠巩固 --自主分层衰减+PageRank+自动修剪+自动合并+事件衰减
• 图形智能 --PageRank、莱顿社区、布兰德斯中心性、香农熵、差距检测
• 会话意识 --来源跟踪、会话差异、每种观察类型的重要性先验
• 项目范围界定 *（v0.8）* --按项目隔离内存(cuba_jornada start --project NAME)；遗留NULL行保持全局可见（零回归升级路径）
• 压缩生存快照 *（v0.8）* — cuba_pre_compact snapshot 保持之前的会话状态 /compact; restore 重新注入后紧凑型
• Git友好同步 *（v0.8）* — cuba_sync export 每个实体写入1个JSON（在PR审查中有所不同）， import 是幂等的 ON CONFLICT DO NOTHING，可选的zstd嵌入blob
• BM25混合三向融合 *（v0.9）* --文本+矢量+BM25(ts_rank_cd)在一个单一的RRF（罗伯逊-沃克1994基线）中，它捕获了具有罕见术语的查询，这些查询会丢失密集的嵌入
• MMR多样化 *（v0.9）* — cuba_faro diversify=true 在候选人之间应用Carbonell-Goldstein 1998和Jaccard Sim，避免冗余的Top-K
• OOD弃权 *（v0.9）* — cuba_faro abstain_ood=true 随着马哈拉诺比斯·里奇（Mahalanobis Ridge）-正规化∑⁻ò（Lee Neurips 2018），他恢复了正式弃权，而不是虚假的比赛
• 共形预测 *（v0.9）* -未假设常态的经验分位数（Vovk 2005，Angelopoulos-Bates 2023）；Ethayarajh 2019记录的Cosine捕获各向异性
• 测试效果衰减 *（v0.9）* -半鳞片 (1 + ln(1+access_count)) （Karpicke-Roediger科学2008）；高访问OBS下降4-5×较慢
• HebbianΔt感知 *（v0.9）* --突发抑制 boost *= (1 - exp(-Δt/τ))，τ=600s；受STDP三重规则启发的抗饱和（Pfister-Gerstner 2006）
• Robbins-Monro随机LR *（v0.9）* — η = 0.05/√(1 + access_count/100) 在Oja的规则中，收敛O（1/√T）
• 来源可信度跟踪 *（v0.9）* --每个源的贝塔（α，β）贝叶斯更新 brain_source_trust （尹涵宇IEEE TKDE 2008），行动 cuba_calibrar trust
• sqlx迁移 *（v0.9）* -14个版本化的SQL迁移 rust/migrations/，DBS遗留版本V 0.7/V 0.8的引导透明
• 错误记忆 --永远不要重复同样的错误（防重复保护+模式检测）

比较

______________________________________________________________________

安装

PyPI（推荐）

pip install cuba-memorys

npm

npm install -g cuba-memorys

来源

git clone https://github.com/LeandroPG19/cuba-memorys.git
cd cuba-memorys/rust
cargo build --release

二进制下载

预构建的二进制文件可在 .

______________________________________________________________________

快速开始

无需配置 --只需安装并添加到编辑器中即可。Cuba memorys在首次运行时通过Docker自动配置PostgreSQL数据库。

先决条件: 码头工人 必须安装并运行。

Claude Code

npm install -g cuba-memorys
claude mcp add cuba-memorys -- cuba-memorys

就是这样。在第一轮比赛中，古巴队将：

1. 检测未配置数据库
2. 使用PostgreSQL+pgvector创建Docker容器
3. 自动初始化架构
4. 开始为19个MCP工具提供服务

Cursor / Windsurf / VS Code

npm install -g cuba-memorys

添加到MCP配置(.cursor/mcp.json, .windsurf/mcp.json，或 .vscode/mcp.json):

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

不 DATABASE_URL need——首次运行时通过Docker自动配置。

Advanced: Custom PostgreSQL

如果你已经有了带pgvector的PostgreSQL，设置环境变量：

{
  "mcpServers": {
    "cuba-memorys": {
      "command": "cuba-memorys",
      "env": {
        "DATABASE_URL": "postgresql://user:pass@localhost:5432/brain"
      }
    }
  }
}

可选：多语言ONNX嵌入

对于真正的多语言e5-small语义嵌入（94种语言，384d）而不是基于哈希的回退：

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

如果没有ONNX，服务器将使用基于哈希的确定性嵌入——功能性但没有语义理解。使用ONNX，上下文检索已准备就绪 [entity_type:entity_name] 嵌入前的内容，召回率为+20%。

______________________________________________________________________

23工具

每个工具都以古巴文化命名——令人难忘、专业、有意义。

知识图谱

搜索与验证

错误记忆

会议和决定

认知与分析

记忆维护

v0.8——基于Engram的新增功能

v0.8环境变量

______________________________________________________________________

建筑

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

性能：Rust与Python

过滤器： before/after （ISO8601临时）， tags （关键字）， format （冗长/紧凑）

______________________________________________________________________

数学基础

基于同行评审的算法，而不是临时启发式算法：

分层指数衰减（V4）

importance_new = importance * exp(-0.693 * days_since_access / halflife)

按观察类型分层：事实/偏好=30s，错误/解决方案=14d，上下文/工具用法=7d。决策/教训观察结果受到保护（永不衰减）。情景记忆使用幂律： I(t) = 0.5 / (1 + 0.1*t)^0.5 （Wixted 2004）。重要性直接影响搜索排名（分数*0.7+重要性*0.3).

Hebbian+BCM-Oja（1982），Biennstock 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持续存在 bcm_theta 用于真实时间平滑的列。

RRF聚变——科马克（2009）

RRF(d) = sum( w_i / (k + rank_i(d)) )   where k = 60

通过平滑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)

替换V2阶跃函数，该函数在阈值处具有40%的相对跳跃。

PageRank混合——布林和佩奇（1998）

importance_new = 0.3 * rank_normalized + 0.7 * importance_existing

通过凸组合混合的最小-最大归一化秩（α=0.3）。保留Hebbian/BCM/RLHF累积的重要性，而不是覆盖。均匀分布保护：当所有等级相等时跳过混合（无结构性信号）。

其他算法

______________________________________________________________________

配置

环境变量

Docker Compose

专用PostgreSQL 18 Alpine：

• 港口5488（避免与5432/5433发生冲突）
• 资源：256MB内存，0.5个CPU
• 重启：总是
• 健康检查: pg_isready 每10秒

______________________________________________________________________

运作原理

1.代理人从你的项目中学习

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.错误记忆防止重复错误

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.抗幻觉接地

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.记忆会自然衰退

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.社区情报

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

______________________________________________________________________

安全与审计

内部审计裁定：GO (2026-03-28)

所有MIT/Apache-2.0（0 GPL/AGPL）

______________________________________________________________________

依赖项

______________________________________________________________________

版本历史记录

______________________________________________________________________

许可证

CC BY NC 4.0 --免费使用和修改， 非商业用途.

______________________________________________________________________

作者

莱安德罗·佩雷斯G。

• github： @LeandroPG19
• 电子邮件： leandropatodo@gmail.com

学分

数学基础：Oja（1982），Biennstock，Cooper&Munro（1982，BCM），Cormack（2009，RRF），Brin&Page（1998，PageRank），Traag等人（2019，莱顿），Brandes（2001），Shannon（1948），Pearson（1900，卡方），Friston（2023，PE门控），Tulving（1972，情景记忆），Wixted（2004，幂律遗忘），Adamic&Adar（2003，链接预测），Anthropic（2024，上下文检索），Wang等人（2022，E5嵌入），Malkov&Yashunin（2018，HNSW）、Jaynes（1957，MaxEnt sigmoid路由）、Robertson（1977，分数融合）、Collins&Loftus（1975，传播激活）。