# SHCortex

**Capa de memoria persistente para cualquier LLM.** SHCortex almacena contexto entre sesiones y comprime textos largos antes de que lleguen al modelo. Es 100% agnóstico al LLM — funciona con Claude, GPT, Llama, Mistral, Gemini, o modelos locales.

## El problema

Los LLMs y agentes tienen dos limitaciones fundamentales:
1. **No recuerdan entre sesiones** — cada conversación empieza en cero
2. **La ventana de contexto es finita y cara** — textos largos se truncan o saturan de tokens

Las soluciones existentes (RAG, Mem0, buffers de mensajes) resuelven parcialmente pero añaden dependencias pesadas: vectores DB, modelos de embeddings, APIs externas.

## Lo que hace SHCortex

Un sistema de memoria en dos niveles:

- **Entre sesiones**: los hechos importantes se almacenan en SQLite con FTS5 y se recuperan con `retrieve` en latencias sub-milisegundo
- **Dentro de la sesión**: el LCC (Lente de Corte Causal) comprime textos largos con sparsidad adaptativa basada en la complejidad de los conceptos detectados

### ¿Ahorra tokens?

Depende del uso:

- **Consultas cortas**: no. `retrieve` añade contexto que no estaba. El beneficio no es ahorrar, es que el LLM tenga información que de otra forma no tendría.
- **Textos largos**: sí. LCC reduce el texto manteniendo los fragmentos relevantes según la complejidad semántica detectada por BimoH.
- **Sesiones prolongadas**: sí. Comprimir el historial acumulado con LCC evita que el contexto se desborde en conversaciones largas.
- **Bucles de razonamiento**: sí. En cadenas de reflexión donde el LLM itera sobre su propio output, LCC extrae lo relevante y corta lo redundante.

Todo corre 100% local, sin cloud, sin vectores, sin descargar modelos. SHCortex produce texto plano — cualquier LLM lo entiende sin adaptación.

## Arquitectura

```
texto → lnhash (tokenización) → malla_multi (3 anillos) → bimoh (plasticidad)
                                    ↓
                              persistent_memory (SQLite + FTS5)
                                    ↓
                              lcc (compresión adaptativa)
                                    ↓
                              prompt_engine → system/user → LLM
```

| Módulo | Función |
|---|---|
| `lnhash` | Tokenización determinista con detección de dominio y idioma (crate externo, MIT) |
| `bimoh` | Plasticidad fractal: entropía, ganancia de información, actualización de d_i (crate externo, MIT) |
| `malla_multi` | 3 anillos de neuronas con propagación de actividad y consolidación |
| `persistent_memory` | SQLite con FTS5: store, retrieve, decay, prune |
| `lcc` | LCC adaptativo: sparsidad basada en complejidad de memcons (floor 0.3%–0.8%) |
| `prompt_engine` | Síntesis de prompts con jerarquía system/user, texto real (nunca hex IDs) |

## Instalación

### Como librería Rust

```bash
cargo add shcortex
```

```rust
use shcortex::Shcortex;

let mut sh = Shcortex::new(None);
sh.compress("SHCortex usa SQLite con WAL mode y FTS5");
let ctx = sh.retrieve("base de datos");
let (system_msg, user_msg) = sh.build_prompt("¿cómo funciona?");
```

### Como CLI

```bash
shcortex compress "texto a recordar"
shcortex retrieve "consulta"
shcortex prompt "pregunta"
shcortex status
```

### Como MCP Server

```json
{
  "mcpServers": {
    "shcortex-memory": {
      "command": "shcortex-mcp",
      "env": { "SHCORTEX_DB": "~/.shcortex/memory.db" }
    }
  }
}
```

Tools: `compress`, `retrieve`, `prompt`, `mem_status`.

## Tests

```bash
cargo test
```

## Licencia

BSL 1.1 — código fuente disponible, uso no-comercial libre. Uso en producción requiere licencia comercial.

Dependencias externas `lnhash` y `bimoh` son MIT.
