cuba-memorys 1.8.0__py3-none-win_amd64.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- cuba_memorys-1.8.0.data/scripts/cuba-memorys.exe +0 -0
- cuba_memorys-1.8.0.dist-info/METADATA +467 -0
- cuba_memorys-1.8.0.dist-info/RECORD +6 -0
- cuba_memorys-1.8.0.dist-info/WHEEL +4 -0
- cuba_memorys-1.8.0.dist-info/licenses/LICENSE +23 -0
- cuba_memorys-1.8.0.dist-info/sboms/cuba-memorys.cyclonedx.json +9700 -0
|
Binary file
|
|
@@ -0,0 +1,467 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: cuba-memorys
|
|
3
|
+
Version: 1.8.0
|
|
4
|
+
Classifier: Programming Language :: Rust
|
|
5
|
+
Classifier: Development Status :: 4 - Beta
|
|
6
|
+
Classifier: Intended Audience :: Developers
|
|
7
|
+
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
|
|
8
|
+
Classifier: License :: Other/Proprietary License
|
|
9
|
+
Classifier: Operating System :: POSIX :: Linux
|
|
10
|
+
Classifier: Operating System :: MacOS
|
|
11
|
+
Classifier: Operating System :: Microsoft :: Windows
|
|
12
|
+
License-File: LICENSE
|
|
13
|
+
Summary: Persistent memory for AI agents — knowledge graph MCP server with 19 tools: Hebbian learning, RRF fusion, episodic memory, contradiction detection, prospective triggers, Bayesian calibration, link prediction. PostgreSQL, sub-millisecond.
|
|
14
|
+
Keywords: mcp,memory,knowledge-graph,hebbian,ai-agent,anti-hallucination,pagerank,model-context-protocol
|
|
15
|
+
License: CC-BY-NC-4.0
|
|
16
|
+
Requires-Python: >=3.9
|
|
17
|
+
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
|
|
18
|
+
|
|
19
|
+
<!-- mcp-name: io.github.LeandroPG19/cuba-memorys -->
|
|
20
|
+
# Cuba-Memorys
|
|
21
|
+
|
|
22
|
+
[](https://github.com/LeandroPG19/cuba-memorys/actions/workflows/ci.yml)
|
|
23
|
+
[](https://pypi.org/project/cuba-memorys/)
|
|
24
|
+
[](https://www.npmjs.com/package/cuba-memorys)
|
|
25
|
+
[](https://registry.modelcontextprotocol.io)
|
|
26
|
+
[](https://rust-lang.org)
|
|
27
|
+
[](https://postgresql.org)
|
|
28
|
+
[](https://creativecommons.org/licenses/by-nc/4.0/)
|
|
29
|
+
[](https://github.com/LeandroPG19/cuba-memorys)
|
|
30
|
+
[](https://github.com/LeandroPG19/cuba-memorys)
|
|
31
|
+
|
|
32
|
+
**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.
|
|
33
|
+
|
|
34
|
+
19 tools with Cuban soul. Sub-millisecond handlers. Mathematically rigorous.
|
|
35
|
+
|
|
36
|
+
> [!IMPORTANT]
|
|
37
|
+
> **v0.6.0** — Contextual Retrieval, importance priors, score breakdown, session provenance, compact format, semantic dedup, auto-tagging, Adamic-Adar link prediction, contradiction detection, prospective memory triggers, Bayesian calibration, bulk ingest, episodic memory with power-law decay, temporal search filters, and gap detection. 56 tests, 0 clippy warnings.
|
|
38
|
+
|
|
39
|
+
## Demo
|
|
40
|
+
|
|
41
|
+
<p align="center">
|
|
42
|
+
<img src="assets/demo.gif" alt="Cuba-Memorys MCP demo — AI agent session with knowledge graph, hybrid search, and graph analytics" width="700" />
|
|
43
|
+
</p>
|
|
44
|
+
|
|
45
|
+
---
|
|
46
|
+
|
|
47
|
+
## Why Cuba-Memorys?
|
|
48
|
+
|
|
49
|
+
AI agents forget everything between conversations. Cuba-Memorys solves this:
|
|
50
|
+
|
|
51
|
+
- **Stratified exponential decay** — Memories fade by type (facts=30d, errors=14d, context=7d), strengthen with access
|
|
52
|
+
- **Hebbian + BCM metaplasticity** — Self-normalizing importance via Oja's rule with EMA sliding threshold
|
|
53
|
+
- **Hybrid RRF fusion search** — pg_trgm + full-text + pgvector HNSW, entropy-routed weighting (k=60), temporal filters, tag filters, compact format
|
|
54
|
+
- **Knowledge graph** — Entities, observations, typed relations with Leiden community detection and Adamic-Adar link prediction
|
|
55
|
+
- **Anti-hallucination grounding** — Verify claims with graduated confidence + Bayesian calibration over time
|
|
56
|
+
- **Episodic memory** — Separate temporal events (Tulving 1972) with power-law decay I(t) = I₀/(1+ct)^β (Wixted 2004)
|
|
57
|
+
- **Contradiction detection** — Scan for semantic conflicts via embedding cosine + bilingual negation heuristics
|
|
58
|
+
- **Prospective memory** — Triggers that fire on entity access, session start, or error match ("remind me when X")
|
|
59
|
+
- **Contextual Retrieval** — Entity context prepended before embedding (Anthropic technique, +20% recall)
|
|
60
|
+
- **REM Sleep consolidation** — Autonomous stratified decay + PageRank + auto-prune + auto-merge + episode decay
|
|
61
|
+
- **Graph intelligence** — PageRank, Leiden communities, Brandes centrality, Shannon entropy, gap detection
|
|
62
|
+
- **Session awareness** — Provenance tracking, session diff, importance priors per observation type
|
|
63
|
+
- **Error memory** — Never repeat the same mistake (anti-repetition guard + pattern detection)
|
|
64
|
+
|
|
65
|
+
### Comparison
|
|
66
|
+
|
|
67
|
+
| Feature | Cuba-Memorys | Basic Memory MCPs |
|
|
68
|
+
| ------- | :----------: | :---------------: |
|
|
69
|
+
| Knowledge graph with typed relations | Yes | No |
|
|
70
|
+
| Exponential importance decay | Yes | No |
|
|
71
|
+
| Hebbian learning + BCM metaplasticity | Yes | No |
|
|
72
|
+
| Hybrid entropy-routed RRF fusion | Yes | No |
|
|
73
|
+
| KG-neighbor query expansion | Yes | No |
|
|
74
|
+
| GraphRAG topological enrichment | Yes | No |
|
|
75
|
+
| Leiden community detection | Yes | No |
|
|
76
|
+
| Brandes betweenness centrality | Yes | No |
|
|
77
|
+
| Shannon entropy analytics | Yes | No |
|
|
78
|
+
| Adaptive prediction error gating | Yes | No |
|
|
79
|
+
| Anti-hallucination verification | Yes | No |
|
|
80
|
+
| Error pattern detection | Yes | No |
|
|
81
|
+
| Session-aware search boost | Yes | No |
|
|
82
|
+
| REM Sleep autonomous consolidation | Yes | No |
|
|
83
|
+
| Optional ONNX BGE embeddings | Yes | No |
|
|
84
|
+
| Write-time dedup gate | Yes | No |
|
|
85
|
+
| Contradiction auto-supersede | Yes | No |
|
|
86
|
+
| GDPR Right to Erasure | Yes | No |
|
|
87
|
+
| Graceful shutdown (SIGTERM/SIGINT) | Yes | No |
|
|
88
|
+
|
|
89
|
+
---
|
|
90
|
+
|
|
91
|
+
## Installation
|
|
92
|
+
|
|
93
|
+
### PyPI (recommended)
|
|
94
|
+
|
|
95
|
+
```bash
|
|
96
|
+
pip install cuba-memorys
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
### npm
|
|
100
|
+
|
|
101
|
+
```bash
|
|
102
|
+
npm install -g cuba-memorys
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
### From source
|
|
106
|
+
|
|
107
|
+
```bash
|
|
108
|
+
git clone https://github.com/LeandroPG19/cuba-memorys.git
|
|
109
|
+
cd cuba-memorys/rust
|
|
110
|
+
cargo build --release
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
### Binary download
|
|
114
|
+
|
|
115
|
+
Pre-built binaries available at [GitHub Releases](https://github.com/LeandroPG19/cuba-memorys/releases).
|
|
116
|
+
|
|
117
|
+
---
|
|
118
|
+
|
|
119
|
+
## Quick Start
|
|
120
|
+
|
|
121
|
+
**1. Start PostgreSQL** (if you don't have one running):
|
|
122
|
+
|
|
123
|
+
```bash
|
|
124
|
+
docker compose up -d
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
**2. Configure your AI editor** (Claude Code, Cursor, Windsurf, etc.):
|
|
128
|
+
|
|
129
|
+
<details>
|
|
130
|
+
<summary><b>Claude Code</b></summary>
|
|
131
|
+
|
|
132
|
+
```bash
|
|
133
|
+
claude mcp add cuba-memorys -- cuba-memorys
|
|
134
|
+
```
|
|
135
|
+
Set the environment variable:
|
|
136
|
+
```bash
|
|
137
|
+
export DATABASE_URL="postgresql://cuba:memorys2026@127.0.0.1:5488/brain"
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
</details>
|
|
141
|
+
|
|
142
|
+
<details>
|
|
143
|
+
<summary><b>Cursor / Windsurf / VS Code</b></summary>
|
|
144
|
+
|
|
145
|
+
Add to your MCP config (`.cursor/mcp.json`, `.windsurf/mcp.json`, or `.vscode/mcp.json`):
|
|
146
|
+
|
|
147
|
+
```json
|
|
148
|
+
{
|
|
149
|
+
"mcpServers": {
|
|
150
|
+
"cuba-memorys": {
|
|
151
|
+
"command": "cuba-memorys",
|
|
152
|
+
"env": {
|
|
153
|
+
"DATABASE_URL": "postgresql://cuba:memorys2026@127.0.0.1:5488/brain"
|
|
154
|
+
}
|
|
155
|
+
}
|
|
156
|
+
}
|
|
157
|
+
}
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
</details>
|
|
161
|
+
|
|
162
|
+
The server auto-creates the `brain` database and all tables on first run.
|
|
163
|
+
|
|
164
|
+
### Optional: ONNX Embeddings
|
|
165
|
+
|
|
166
|
+
For real BGE-small-en-v1.5 semantic embeddings instead of hash-based fallback:
|
|
167
|
+
|
|
168
|
+
```bash
|
|
169
|
+
export ONNX_MODEL_PATH="$HOME/.cache/cuba-memorys/models"
|
|
170
|
+
export ORT_DYLIB_PATH="/path/to/libonnxruntime.so"
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
Without ONNX, the server uses deterministic hash-based embeddings — functional but without semantic understanding.
|
|
174
|
+
|
|
175
|
+
---
|
|
176
|
+
|
|
177
|
+
## The 19 Tools
|
|
178
|
+
|
|
179
|
+
Every tool is named after Cuban culture — memorable, professional, meaningful.
|
|
180
|
+
|
|
181
|
+
### Knowledge Graph
|
|
182
|
+
|
|
183
|
+
| Tool | Meaning | What it does |
|
|
184
|
+
|------|---------|-------------|
|
|
185
|
+
| `cuba_alma` | **Alma** — soul | CRUD entities. Types: `concept`, `project`, `technology`, `person`, `pattern`, `config`. Hebbian boost + access tracking. Fires prospective triggers on access. |
|
|
186
|
+
| `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. |
|
|
187
|
+
| `cuba_puente` | **Puente** — bridge | Typed relations. **Traverse** walks the graph. **Infer** discovers transitive paths. **Predict** suggests missing relations via Adamic-Adar link prediction. |
|
|
188
|
+
| `cuba_ingesta` | **Ingesta** — intake | Bulk knowledge ingestion: accepts arrays of observations or long text with auto-classification by paragraph. |
|
|
189
|
+
|
|
190
|
+
### Search & Verification
|
|
191
|
+
|
|
192
|
+
| Tool | Meaning | What it does |
|
|
193
|
+
|------|---------|-------------|
|
|
194
|
+
| `cuba_faro` | **Faro** — lighthouse | RRF fusion (k=60) with entropy routing, pgvector, temporal filters (`before`/`after`), tag filters, **score breakdown** (text/vector/importance/session), **compact format** (~35% fewer tokens), Bayesian **calibrated accuracy**. |
|
|
195
|
+
|
|
196
|
+
### Error Memory
|
|
197
|
+
|
|
198
|
+
| Tool | Meaning | What it does |
|
|
199
|
+
|------|---------|-------------|
|
|
200
|
+
| `cuba_alarma` | **Alarma** — alarm | Report errors. Auto-detects patterns (>=3 similar = warning). Fires prospective triggers on error match. |
|
|
201
|
+
| `cuba_remedio` | **Remedio** — remedy | Resolve errors with cross-reference to similar unresolved issues. |
|
|
202
|
+
| `cuba_expediente` | **Expediente** — case file | Search past errors. **Anti-repetition guard**: warns if similar approach failed before. |
|
|
203
|
+
|
|
204
|
+
### Sessions & Decisions
|
|
205
|
+
|
|
206
|
+
| Tool | Meaning | What it does |
|
|
207
|
+
|------|---------|-------------|
|
|
208
|
+
| `cuba_jornada` | **Jornada** — workday | Session tracking with goals, outcomes, **session diff** (what was learned), and **previous session** context on start. Fires prospective triggers. |
|
|
209
|
+
| `cuba_decreto` | **Decreto** — decree | Record architecture decisions with context, alternatives, rationale. |
|
|
210
|
+
|
|
211
|
+
### Cognition & Analysis
|
|
212
|
+
|
|
213
|
+
| Tool | Meaning | What it does |
|
|
214
|
+
|------|---------|-------------|
|
|
215
|
+
| `cuba_reflexion` | **Reflexion** — reflection | Gap detection: isolated entities, underconnected hubs, type silos, observation gaps, density anomalies (z-score). |
|
|
216
|
+
| `cuba_hipotesis` | **Hipotesis** — hypothesis | Abductive inference: given an effect, find plausible causes via backward causal traversal. Plausibility = path_strength x importance. |
|
|
217
|
+
| `cuba_contradiccion` | **Contradiccion** — contradiction | Scan for semantic conflicts between same-entity observations via embedding cosine + bilingual negation heuristics. |
|
|
218
|
+
| `cuba_centinela` | **Centinela** — sentinel | Prospective memory triggers: "remind me when X is accessed / session starts / error matches". Auto-deactivate on max_fires, expiration support. |
|
|
219
|
+
| `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. |
|
|
220
|
+
|
|
221
|
+
### Memory Maintenance
|
|
222
|
+
|
|
223
|
+
| Tool | Meaning | What it does |
|
|
224
|
+
|------|---------|-------------|
|
|
225
|
+
| `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. |
|
|
226
|
+
| `cuba_eco` | **Eco** — echo | RLHF feedback: positive (Oja boost), negative (decrease), correct (update with versioning). |
|
|
227
|
+
| `cuba_vigia` | **Vigia** — watchman | Analytics: summary, **enhanced health** (null embeddings, active triggers, table sizes, embedding model), drift (chi-squared), Leiden communities, Brandes bridges. |
|
|
228
|
+
| `cuba_forget` | **Forget** — forget | GDPR Right to Erasure: cascading hard-delete of entity and ALL references (observations, episodes, relations, errors, sessions). Irreversible. |
|
|
229
|
+
|
|
230
|
+
---
|
|
231
|
+
|
|
232
|
+
## Architecture
|
|
233
|
+
|
|
234
|
+
```
|
|
235
|
+
cuba-memorys/
|
|
236
|
+
├── docker-compose.yml # Dedicated PostgreSQL 18 (port 5488)
|
|
237
|
+
├── rust/ # v0.3.0
|
|
238
|
+
│ ├── src/
|
|
239
|
+
│ │ ├── main.rs # mimalloc + graceful shutdown
|
|
240
|
+
│ │ ├── protocol.rs # JSON-RPC 2.0 + REM daemon (4h cycle)
|
|
241
|
+
│ │ ├── db.rs # sqlx PgPool (10 max, 600s idle, 1800s lifetime)
|
|
242
|
+
│ │ ├── schema.sql # 8 tables, 20+ indexes, HNSW
|
|
243
|
+
│ │ ├── constants.rs # Tool definitions, thresholds, importance priors
|
|
244
|
+
│ │ ├── handlers/ # 19 MCP tool handlers (1 file each)
|
|
245
|
+
│ │ ├── cognitive/ # Hebbian/BCM, access tracking, PE gating V5.2
|
|
246
|
+
│ │ ├── search/ # RRF fusion, confidence, LRU cache
|
|
247
|
+
│ │ ├── graph/ # Brandes centrality, Leiden, PageRank (NF-IDF)
|
|
248
|
+
│ │ └── embeddings/ # ONNX multilingual-e5-small (contextual, spawn_blocking)
|
|
249
|
+
│ ├── scripts/
|
|
250
|
+
│ │ └── download_model.sh # Download multilingual-e5-small ONNX
|
|
251
|
+
│ └── tests/
|
|
252
|
+
└── server.json # MCP Registry manifest
|
|
253
|
+
```
|
|
254
|
+
|
|
255
|
+
### Performance: Rust vs Python
|
|
256
|
+
|
|
257
|
+
| Metric | Python v1.6.0 | Rust v0.6.0 |
|
|
258
|
+
| ------ | :-----------: | :---------: |
|
|
259
|
+
| Binary size | ~50MB (venv) | **7.6MB** |
|
|
260
|
+
| Entity create | ~2ms | **498us** |
|
|
261
|
+
| Hybrid search | <5ms | **2.52ms** |
|
|
262
|
+
| Analytics | <2.5ms | **958us** |
|
|
263
|
+
| Memory usage | ~120MB | **~15MB** |
|
|
264
|
+
| Startup time | ~2s | **<100ms** |
|
|
265
|
+
| Dependencies | 12 Python packages | **0 runtime deps** |
|
|
266
|
+
|
|
267
|
+
### Database Schema
|
|
268
|
+
|
|
269
|
+
| Table | Purpose | Key Features |
|
|
270
|
+
|-------|---------|-------------|
|
|
271
|
+
| `brain_entities` | KG nodes | tsvector + pg_trgm + GIN indexes, importance, bcm_theta |
|
|
272
|
+
| `brain_observations` | Facts with provenance | 9 types, versioning, `vector(384)`, importance priors, auto-tags TEXT[], session_id FK, embedding_model tracking |
|
|
273
|
+
| `brain_relations` | Typed edges | 5 types, bidirectional, Hebbian strength, blake3 dedup |
|
|
274
|
+
| `brain_errors` | Error memory | JSONB context, synapse weight, pattern detection |
|
|
275
|
+
| `brain_sessions` | Working sessions | Goals (JSONB), outcome tracking, session diff |
|
|
276
|
+
| `brain_episodes` | Episodic memory | Tulving 1972, actors/artifacts TEXT[], power-law decay (Wixted 2004) |
|
|
277
|
+
| `brain_triggers` | Prospective memory | on_access/on_session_start/on_error_match, max_fires, expiration |
|
|
278
|
+
| `brain_verify_log` | Bayesian calibration | claim, confidence, grounding_level, outcome (correct/incorrect) |
|
|
279
|
+
|
|
280
|
+
### Search Pipeline
|
|
281
|
+
|
|
282
|
+
**Reciprocal Rank Fusion (RRF, k=60)** with entropy-routed weighting:
|
|
283
|
+
|
|
284
|
+
| # | Signal | Source | Condition |
|
|
285
|
+
|---|--------|--------|-----------|
|
|
286
|
+
| 1 | Entities (ts_rank + trigrams + importance) | `brain_entities` | Always |
|
|
287
|
+
| 2 | Observations (ts_rank + trigrams + importance) | `brain_observations` | Always |
|
|
288
|
+
| 3 | Errors (ts_rank + trigrams + synapse_weight) | `brain_errors` | Always |
|
|
289
|
+
| 4 | **Vector cosine distance (HNSW)** | `brain_observations.embedding` | pgvector installed |
|
|
290
|
+
|
|
291
|
+
**Post-fusion pipeline:** Dedup -> KG-neighbor expansion -> Session boost -> GraphRAG enrichment -> Token-budget truncation -> Batch access tracking
|
|
292
|
+
|
|
293
|
+
---
|
|
294
|
+
|
|
295
|
+
## Mathematical Foundations
|
|
296
|
+
|
|
297
|
+
Built on peer-reviewed algorithms, not ad-hoc heuristics:
|
|
298
|
+
|
|
299
|
+
### Exponential Decay (V3)
|
|
300
|
+
```
|
|
301
|
+
importance_new = importance * exp(-0.693 * days_since_access / halflife)
|
|
302
|
+
```
|
|
303
|
+
halflife=30d by default. Decision/lesson observations are protected from decay. Importance directly affects search ranking (score*0.7 + importance*0.3).
|
|
304
|
+
|
|
305
|
+
### Hebbian + BCM — Oja (1982), Bienenstock-Cooper-Munro (1982)
|
|
306
|
+
```
|
|
307
|
+
Positive: importance += eta * throttle(access_count, theta_M)
|
|
308
|
+
BCM EMA: theta_M = max(10, (1-alpha)*theta_prev + alpha*access_count)
|
|
309
|
+
```
|
|
310
|
+
V3: theta_M persisted in `bcm_theta` column for true temporal smoothing.
|
|
311
|
+
|
|
312
|
+
### RRF Fusion — Cormack (2009)
|
|
313
|
+
```
|
|
314
|
+
RRF(d) = sum( w_i / (k + rank_i(d)) ) where k = 60
|
|
315
|
+
```
|
|
316
|
+
Entropy-routed weighting: keyword-dominant vs mixed vs semantic queries get different signal weights.
|
|
317
|
+
|
|
318
|
+
### Other Algorithms
|
|
319
|
+
|
|
320
|
+
| Algorithm | Reference | Used in |
|
|
321
|
+
|-----------|-----------|---------|
|
|
322
|
+
| **Leiden communities** | Traag et al. (Nature 2019) | `community.rs` -> `vigia.rs` |
|
|
323
|
+
| **Personalized PageRank** | Brin & Page (1998) | `pagerank.rs` -> `zafra.rs` |
|
|
324
|
+
| **Brandes centrality** | Brandes (2001) | `centrality.rs` -> `vigia.rs` |
|
|
325
|
+
| **Adaptive PE gating** | Friston (Nature 2023) | `prediction_error.rs` -> `cronica.rs` |
|
|
326
|
+
| **Shannon entropy** | Shannon (1948) | `density.rs` -> information gating |
|
|
327
|
+
| **Chi-squared drift** | Pearson (1900) | Error distribution change detection |
|
|
328
|
+
|
|
329
|
+
---
|
|
330
|
+
|
|
331
|
+
## Configuration
|
|
332
|
+
|
|
333
|
+
### Environment Variables
|
|
334
|
+
|
|
335
|
+
| Variable | Default | Description |
|
|
336
|
+
|----------|---------|-------------|
|
|
337
|
+
| `DATABASE_URL` | — | PostgreSQL connection string (**required**) |
|
|
338
|
+
| `ONNX_MODEL_PATH` | — | Path to BGE model directory (optional) |
|
|
339
|
+
| `ORT_DYLIB_PATH` | — | Path to libonnxruntime.so (optional) |
|
|
340
|
+
| `RUST_LOG` | `cuba_memorys=info` | Log level filter |
|
|
341
|
+
|
|
342
|
+
### Docker Compose
|
|
343
|
+
|
|
344
|
+
Dedicated PostgreSQL 18 Alpine:
|
|
345
|
+
|
|
346
|
+
- **Port**: 5488 (avoids conflicts with 5432/5433)
|
|
347
|
+
- **Resources**: 256MB RAM, 0.5 CPU
|
|
348
|
+
- **Restart**: always
|
|
349
|
+
- **Healthcheck**: `pg_isready` every 10s
|
|
350
|
+
|
|
351
|
+
---
|
|
352
|
+
|
|
353
|
+
## How It Works
|
|
354
|
+
|
|
355
|
+
### 1. The agent learns from your project
|
|
356
|
+
|
|
357
|
+
```
|
|
358
|
+
Agent: FastAPI requires async def with response_model.
|
|
359
|
+
-> cuba_alma(create, "FastAPI", technology)
|
|
360
|
+
-> cuba_cronica(add, "FastAPI", "All endpoints must be async def with response_model")
|
|
361
|
+
```
|
|
362
|
+
|
|
363
|
+
### 2. Error memory prevents repeated mistakes
|
|
364
|
+
|
|
365
|
+
```
|
|
366
|
+
Agent: IntegrityError: duplicate key on numero_parte.
|
|
367
|
+
-> cuba_alarma("IntegrityError", "duplicate key on numero_parte")
|
|
368
|
+
-> cuba_expediente: Similar error found! Solution: "Add SELECT EXISTS before INSERT"
|
|
369
|
+
```
|
|
370
|
+
|
|
371
|
+
### 3. Anti-hallucination grounding
|
|
372
|
+
|
|
373
|
+
```
|
|
374
|
+
Agent: Let me verify before responding...
|
|
375
|
+
-> cuba_faro("FastAPI uses Django ORM", mode="verify")
|
|
376
|
+
-> confidence: 0.0, level: "unknown" — "No evidence. High hallucination risk."
|
|
377
|
+
```
|
|
378
|
+
|
|
379
|
+
### 4. Memories decay naturally
|
|
380
|
+
|
|
381
|
+
```
|
|
382
|
+
Initial importance: 0.5 (new observation)
|
|
383
|
+
After 30d no access: 0.25 (halved by exponential decay)
|
|
384
|
+
After 60d no access: 0.125
|
|
385
|
+
Active access resets the clock — frequently used memories stay strong.
|
|
386
|
+
```
|
|
387
|
+
|
|
388
|
+
### 5. Community intelligence
|
|
389
|
+
|
|
390
|
+
```
|
|
391
|
+
-> cuba_vigia(metric="communities")
|
|
392
|
+
-> Community 0 (4 members): [FastAPI, Pydantic, SQLAlchemy, PostgreSQL]
|
|
393
|
+
Summary: "Backend stack: async endpoints, V2 validation, 2.0 ORM..."
|
|
394
|
+
-> Community 1 (3 members): [React, Next.js, TypeScript]
|
|
395
|
+
Summary: "Frontend stack: React 19, App Router, strict types..."
|
|
396
|
+
```
|
|
397
|
+
|
|
398
|
+
---
|
|
399
|
+
|
|
400
|
+
## Security & Audit
|
|
401
|
+
|
|
402
|
+
**Internal Audit Verdict: GO** (2026-03-28)
|
|
403
|
+
|
|
404
|
+
| Check | Result |
|
|
405
|
+
|-------|:------:|
|
|
406
|
+
| SQL injection | All queries parameterized (sqlx bind) |
|
|
407
|
+
| SEC-002 wildcard injection | Fixed (POSITION-based) |
|
|
408
|
+
| CVEs in dependencies | 0 active (sqlx 0.8.6, tokio 1.50.0) |
|
|
409
|
+
| UTF-8 safety | `safe_truncate` on all string slicing |
|
|
410
|
+
| Secrets | All via environment variables |
|
|
411
|
+
| Division by zero | Protected with `.max(1e-9)` |
|
|
412
|
+
| Error handling | All `?` propagated with `anyhow::Context` |
|
|
413
|
+
| Clippy | 0 warnings |
|
|
414
|
+
| Tests | 106/106 passing (51 unit/smoke + 55 E2E) |
|
|
415
|
+
| Licenses | All MIT/Apache-2.0 (0 GPL/AGPL) |
|
|
416
|
+
|
|
417
|
+
---
|
|
418
|
+
|
|
419
|
+
## Dependencies
|
|
420
|
+
|
|
421
|
+
| Crate | Purpose | License |
|
|
422
|
+
|-------|---------|---------|
|
|
423
|
+
| `tokio` | Async runtime | MIT |
|
|
424
|
+
| `sqlx` | PostgreSQL (async) | MIT/Apache-2.0 |
|
|
425
|
+
| `serde` / `serde_json` | Serialization | MIT/Apache-2.0 |
|
|
426
|
+
| `pgvector` | Vector similarity | MIT |
|
|
427
|
+
| `ort` | ONNX Runtime (optional) | MIT/Apache-2.0 |
|
|
428
|
+
| `tokenizers` | HuggingFace tokenizers | Apache-2.0 |
|
|
429
|
+
| `blake3` | Cryptographic hashing | Apache-2.0/CC0 |
|
|
430
|
+
| `mimalloc` | Global allocator | MIT |
|
|
431
|
+
| `tracing` | Structured JSON logging | MIT |
|
|
432
|
+
| `lru` | O(1) LRU cache | MIT |
|
|
433
|
+
| `chrono` | Timezone-aware timestamps | MIT/Apache-2.0 |
|
|
434
|
+
|
|
435
|
+
---
|
|
436
|
+
|
|
437
|
+
## Version History
|
|
438
|
+
|
|
439
|
+
| Version | Key Changes |
|
|
440
|
+
|---------|-------------|
|
|
441
|
+
| **0.3.0** | Deep Research V3: exponential decay replaces FSRS-6, dead code/columns eliminated, SEC-002 fix, importance in ranking, embeddings storage on write, GraphRAG CTE fix, Opus 4.6 token optimization, zero tech debt. 106 tests (51 unit/smoke + 55 E2E), 0 clippy warnings. |
|
|
442
|
+
| **0.2.0** | Complete Rust rewrite. BCM metaplasticity, Leiden communities, Shannon entropy, blake3 dedup. Internal audit: GO verdict. |
|
|
443
|
+
| **1.6.0** | KG-neighbor expansion, embedding LRU cache, async embed rebuild, community summaries, batch access tracking |
|
|
444
|
+
| **1.5.0** | Token-budget truncation, post-fusion dedup, source triangulation, adaptive confidence, session-aware decay |
|
|
445
|
+
| **1.3.0** | Modular architecture (CC avg D->A), 87% CC reduction |
|
|
446
|
+
| **1.1.0** | GraphRAG, REM Sleep, conditional pgvector, 4-signal RRF |
|
|
447
|
+
| **1.0.0** | Initial release: 12 tools, Hebbian learning |
|
|
448
|
+
|
|
449
|
+
---
|
|
450
|
+
|
|
451
|
+
## License
|
|
452
|
+
|
|
453
|
+
[CC BY-NC 4.0](https://creativecommons.org/licenses/by-nc/4.0/) — Free to use and modify, **not for commercial use**.
|
|
454
|
+
|
|
455
|
+
---
|
|
456
|
+
|
|
457
|
+
## Author
|
|
458
|
+
|
|
459
|
+
**Leandro Perez G.**
|
|
460
|
+
|
|
461
|
+
- GitHub: [@LeandroPG19](https://github.com/LeandroPG19)
|
|
462
|
+
- Email: [leandropatodo@gmail.com](mailto:leandropatodo@gmail.com)
|
|
463
|
+
|
|
464
|
+
## Credits
|
|
465
|
+
|
|
466
|
+
Mathematical foundations: Oja (1982), Bienenstock, Cooper & Munro (1982, BCM), Cormack (2009, RRF), Brin & Page (1998, PageRank), Traag et al. (2019, Leiden), Brandes (2001), Shannon (1948), Pearson (1900, chi-squared), Friston (2023, PE gating), BAAI (2023, BGE), Malkov & Yashunin (2018, HNSW), O'Connor et al. (2020, blake3).
|
|
467
|
+
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
cuba_memorys-1.8.0.data/scripts/cuba-memorys.exe,sha256=JtzDqh7yj0dquOemCSU142hLpMTOrLvU9N-gxrd1MuU,6994432
|
|
2
|
+
cuba_memorys-1.8.0.dist-info/METADATA,sha256=Hwx6KhATNVUYkIGLht6Qao14sqbo_ha_EM4zCpVTPc8,21600
|
|
3
|
+
cuba_memorys-1.8.0.dist-info/WHEEL,sha256=uJOc2U-Q1x95AlblQcqMRb3iR4QnPtdI7X2ycPN99rM,94
|
|
4
|
+
cuba_memorys-1.8.0.dist-info/licenses/LICENSE,sha256=wlWIuWCY2z999ROsB6Kb9z35bmx99DMbuknjDZe9iiw,859
|
|
5
|
+
cuba_memorys-1.8.0.dist-info/sboms/cuba-memorys.cyclonedx.json,sha256=Lang4z1kSq_ip0LvgzZSmJlwS65xGc90ZFcymsNNIck,314473
|
|
6
|
+
cuba_memorys-1.8.0.dist-info/RECORD,,
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
Creative Commons Attribution-NonCommercial 4.0 International License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Leandro Pérez G.
|
|
4
|
+
|
|
5
|
+
You are free to:
|
|
6
|
+
|
|
7
|
+
Share — copy and redistribute the material in any medium or format
|
|
8
|
+
Adapt — remix, transform, and build upon the material
|
|
9
|
+
|
|
10
|
+
Under the following terms:
|
|
11
|
+
|
|
12
|
+
Attribution — You must give appropriate credit, provide a link to the
|
|
13
|
+
license, and indicate if changes were made. You may do so in any
|
|
14
|
+
reasonable manner, but not in any way that suggests the licensor
|
|
15
|
+
endorses you or your use.
|
|
16
|
+
|
|
17
|
+
NonCommercial — You may not use the material for commercial purposes.
|
|
18
|
+
|
|
19
|
+
No additional restrictions — You may not apply legal terms or
|
|
20
|
+
technological measures that legally restrict others from doing
|
|
21
|
+
anything the license permits.
|
|
22
|
+
|
|
23
|
+
Full license text: https://creativecommons.org/licenses/by-nc/4.0/legalcode
|