hipercampo 0.1.0a2__tar.gz

hipercampo-0.1.0a2/.github/workflows/ci.yml

@@ -0,0 +1,54 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install
+        run: pip install -e .
+
+      - name: Test suite (todas las suites, incluidas las generativas)
+        run: |
+          set -e
+          for t in vsa semantic surprise memory update axes hardening namespaces calibration roles safety factstore guardrails muse dream properties; do
+            echo "::group::test_$t"
+            python tests/test_$t.py
+            echo "::endgroup::"
+          done
+
+  benchmarks:
+    runs-on: ubuntu-latest
+    needs: test
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - name: Install
+        run: pip install -e .
+      - name: Benchmark de calidad (modo léxico)
+        run: python scripts/benchmark.py
+      - name: Banco de estrés (10 hechos + 10 distractores confusos)
+        run: python scripts/stress.py
+      - name: Comparativa con baselines (BM25 vs hipercampo, léxico)
+        run: python scripts/baselines.py
+      - name: Ejemplos de uso (smoke)
+        run: |
+          for e in examples/*.py; do echo "== $e =="; python "$e"; done

hipercampo-0.1.0a2/.github/workflows/release.yml

@@ -0,0 +1,32 @@
+name: Release to PyPI
+
+# Publica en PyPI al empujar un tag vX.Y.Z. Usa "trusted publishing" (OIDC): sin
+# tokens ni secretos. Requiere una configuración ÚNICA en PyPI (ver más abajo).
+#
+# Pasos de un solo uso (los hace el dueño del paquete):
+#   1. Crear el proyecto/nombre "hipercampo" en https://pypi.org
+#   2. En "Publishing", añadir un Trusted Publisher de GitHub Actions:
+#        owner: armandojaleo   repo: hipercampo   workflow: release.yml
+#   3. A partir de ahí, cada tag vX.Y.Z publica solo.
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write        # necesario para trusted publishing (OIDC)
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - name: Build
+        run: |
+          pip install build
+          python -m build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

hipercampo-0.1.0a2/.gitignore

@@ -0,0 +1,22 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+venv/
+build/
+dist/
+
+# Datos de memoria (no versionar)
+data/
+*.db
+
+# IDE / OS
+.DS_Store
+.idea/
+.vscode/
+
+# Configuración local del usuario (rutas y ajustes personales, no portables)
+.claude/
+.mcp.json
+*.bak-*

hipercampo-0.1.0a2/ATTRIBUTION.md

@@ -0,0 +1,65 @@
+# Atribución y procedencia
+
+Este proyecto es explícito sobre qué es original y qué debe crédito a terceros.
+Regla de la casa: **si usamos trabajo de otros, sobre todo con copyright, se dice.**
+
+## Código
+
+**Todo el código de `hipercampo/` es original**, escrito para este proyecto (por
+Armando Jaleo con asistencia de Claude, de Anthropic). No se ha copiado código con
+copyright de otros proyectos. El álgebra de hipervectores (`bind`=XOR,
+`bundle`=voto por mayoría, `permute`=rotación, distancia de Hamming) son
+operaciones matemáticas estándar de dominio público, no una implementación ajena.
+
+## Dependencias de software (con su licencia)
+
+Se instalan por separado vía `pip`; **su código no se incluye** en este repositorio.
+
+| Dependencia | Uso | Licencia |
+|-------------|-----|----------|
+| [NumPy](https://numpy.org) | operaciones sobre los hipervectores | BSD-3-Clause |
+| [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk) | servidor MCP (`FastMCP`) | MIT |
+| Python (stdlib: `sqlite3`, `hashlib`, `re`) | persistencia y utilidades | PSF |
+
+Cada una conserva su propia licencia y copyright.
+
+### Dependencia OPCIONAL del hook semántico (no se instala por defecto)
+
+Solo si activas la semántica con `pip install hipercampo[semantic]`:
+
+| Dependencia / recurso | Uso | Licencia |
+|-----------------------|-----|----------|
+| [sentence-transformers](https://github.com/UKPLab/sentence-transformers) | generar embeddings densos | Apache-2.0 |
+| Modelo `paraphrase-multilingual-MiniLM-L12-v2` (por defecto) | embeddings multilingües | Apache-2.0 (autores del modelo) |
+
+El puente SimHash (`semantic.embedding_to_hv`) que convierte esos embeddings en
+hipervectores es **código original nuestro**. El modelo lo descarga el usuario y se
+rige por su propia licencia; puedes sustituirlo por cualquier otro con `make_hook`.
+
+## Ideas y trabajo académico en el que nos inspiramos
+
+hipercampo **no implementa** estos trabajos; se inspira en sus ideas y las cita
+como es debido. Los conceptos son de sus autores:
+
+- **Pentti Kanerva** — *Sparse Distributed Memory* (memoria asociativa dispersa).
+- **Tony A. Plate** — *Holographic Reduced Representations* (HRR / binding).
+- **Torchhd** — Heddes et al., *JMLR* 2023: librería de referencia HD/VSA. La
+  citamos como estado del arte; **no usamos su código** (implementamos VSA propio).
+- Línea reciente de memoria en LLMs (2024-2026): **Titans**, **MIRAS**, **HippoRAG**,
+  **MemGPT / Letta**, **Mem0**, **Graphiti**, y **MnemoCore** (HDC/VSA para memoria de
+  IA), además de la relación *atención ≈ SDM* (Bricken & Pehlevan, 2021). Sirvieron
+  para situar el hueco a explorar; ninguna aportó código a este repo. hipercampo no
+  reclama inventar HDC ni la memoria de agentes: reclama una *combinación* concreta
+  (VSA + sorpresa + consolidación + olvido, vía MCP).
+
+## El "hook" semántico opcional
+
+`encoder.set_semantic_hook()` permite enchufar un codificador semántico externo
+(por ejemplo un modelo de embeddings). **hipercampo no incluye ningún modelo.**
+Si conectas uno, ese modelo trae su propia licencia y sus propios términos, y eres
+tú quien los acepta: decláralo en tu despliegue.
+
+## Cómo citar hipercampo
+
+> Jaleo, A. (2026). *hipercampo: memoria asociativa para LLMs basada en
+> hipervectores*. https://github.com/armandojaleo/hipercampo

hipercampo-0.1.0a2/CHANGELOG.md

@@ -0,0 +1,41 @@
+# Changelog
+
+All notable changes to this project are documented here. Format loosely based on
+[Keep a Changelog](https://keepachangelog.com/); versions follow [SemVer](https://semver.org/).
+
+## [0.1.0a1] — 2026-07-22
+
+First public alpha. Local-first, single-user memory for Claude via MCP.
+
+### Added
+- **Memory cycle**: surprise-gated writing (double veto: redundant + predictable via
+  an in-house incremental LM / MDL, with an *adaptive* threshold), spreading-activation
+  recall with **abstention**, sleep **consolidation** (structural, optional summarizer),
+  and **active forgetting** driven by a transparent retention value.
+- **Four separated axes**: novelty, importance, reliability (`confidence`), utility.
+- **Fact updates** (`hc_update`): safe supersession by id or minimum similarity.
+- **Compositional roles** (`hc_remember_fact` / `hc_ask_role`): store subject-predicate-
+  object facts and query by role via VSA unbinding (distinguishes a fact from its reverse).
+- **Contexts**: namespace isolation (reads, id-writes and links), enforced in depth.
+- **Reliability**: SQLite WAL + `busy_timeout`, reentrant transactions, input validation.
+- **Performance**: vectorized similarity (native popcount) — ~5× faster scans.
+- **Safeguards**: secret-detection warnings, injection flagging of recalled memories,
+  optional secret **redaction** (`HIPERCAMPO_REDACT_SECRETS`) and per-context memory
+  **cap** (`HIPERCAMPO_MAX_MEMORIES`).
+- **Optional semantic hook** (SimHash bridge over sentence-transformers).
+- Docs (EN/ES), SECURITY, ATTRIBUTION, ROADMAP; 16 test suites + CI (Python 3.11–3.13)
+  running tests, benchmarks and a baseline comparison (BM25 / embeddings).
+
+### Added (post-tag, unreleased)
+- **Dormant memory & creative recall**: forgetting now *archives* memories as
+  `dormant` (not deleted, like the human mind); `hc_muse` performs serendipitous
+  recall — favoring indirect associations and resurfacing dormant memories to tie
+  ideas together (insight/brainstorming).
+
+### Known limits (declared, not hidden)
+- Retrieval is linear (no ANN index): fine for hundreds–thousands of memories.
+- Surprise counters are not fully persisted (rebuilt from stored memories on start).
+- Benchmarks are small/synthetic — a signal, not proof at scale.
+- Local, single-user scope: no auth/encryption/multi-user isolation.
+
+[0.1.0a1]: https://github.com/armandojaleo/hipercampo/releases/tag/v0.1.0-alpha

hipercampo-0.1.0a2/Dockerfile

@@ -0,0 +1,17 @@
+# Imagen mínima para el servidor MCP de hipercampo.
+FROM python:3.13-slim
+
+WORKDIR /app
+
+# Dependencias primero (mejor cache de capas)
+COPY pyproject.toml README.md ./
+COPY hipercampo ./hipercampo
+
+RUN pip install --no-cache-dir .
+
+# La memoria persiste en el volumen /data (ver docker-compose.yml)
+ENV HIPERCAMPO_DB=/data/hipercampo.db
+VOLUME ["/data"]
+
+# MCP habla por stdio: mantener STDIN abierto con `docker run -i`.
+ENTRYPOINT ["python", "-m", "hipercampo.server"]

hipercampo-0.1.0a2/INSTALL.md

@@ -0,0 +1,299 @@
+# Guía de instalación de hipercampo
+
+De cero a "Claude tiene memoria" en unos minutos. Elige **una** de las dos vías
+(A: Python local — la más simple para empezar; B: Docker — más portable).
+
+Requisitos: **Python 3.11+** (vía A) o **Docker** (vía B). Windows, macOS o Linux.
+
+---
+
+## Paso 0 · Conseguir el código
+
+```bash
+git clone https://github.com/armandojaleo/hipercampo.git
+cd hipercampo
+```
+
+---
+
+## Vía A · Python local (recomendada para empezar)
+
+### A.1 Instalar
+
+```bash
+pip install -e .
+```
+
+Esto instala `hipercampo` y su única dependencia real (numpy) + el SDK de MCP.
+
+### A.2 Comprobar que funciona (sin Claude todavía)
+
+```bash
+python scripts/demo.py        # ves el ciclo completo: sorpresa, recuerdo, sueño, olvido
+python -m pytest -q           # o: python tests/test_memory.py
+```
+
+### A.3 Arrancar el servidor MCP a mano (opcional, para verlo vivo)
+
+```bash
+python -m hipercampo.server
+```
+
+Se queda esperando por stdio (es lo normal en MCP). Córtalo con Ctrl+C. No hace
+falta lanzarlo tú: lo lanzará Claude automáticamente al conectarlo (paso siguiente).
+
+---
+
+## Vía B · Docker
+
+```bash
+docker compose build
+```
+
+La memoria se guarda en el volumen `hipercampo_data`. Para una prueba manual:
+
+```bash
+docker compose run --rm hipercampo   # arranca el server (stdio); Ctrl+C para salir
+```
+
+---
+
+## Paso final · Conectar con Claude
+
+### Claude Code (CLI / extensión de VSCode)
+
+**Opción 1 — con el comando** (desde la carpeta del proyecto):
+
+```bash
+# Vía A (Python):
+claude mcp add hipercampo -- python -m hipercampo.server
+
+# Vía B (Docker):
+claude mcp add hipercampo -- docker run --rm -i -v hipercampo_data:/data hipercampo:latest
+```
+
+**Opción 2 — a mano**: crea un archivo `.mcp.json` en la raíz del proyecto:
+
+```json
+{
+  "mcpServers": {
+    "hipercampo": {
+      "command": "python",
+      "args": ["-m", "hipercampo.server"],
+      "env": { "HIPERCAMPO_DB": "./data/hipercampo.db" }
+    }
+  }
+}
+```
+
+Reinicia Claude Code. Deberías ver 10 herramientas: `hc_remember`, `hc_recall`,
+`hc_update`, `hc_consolidate`, `hc_forget`, `hc_stats`.
+
+### Memoria compartida entre TODOS los proyectos (global)
+
+El `.mcp.json` del paso anterior activa hipercampo **solo en ese proyecto**. Como la
+base de datos ya vive en una ruta global (`~/.hipercampo/hipercampo.db`), los datos
+se comparten igual; lo único "por proyecto" es el registro del servidor.
+
+Para que Claude tenga las herramientas en **cualquier** proyecto, registra el
+servidor a nivel **usuario**:
+
+```bash
+claude mcp add --scope user hipercampo -- python -m hipercampo.server
+```
+
+O a mano, añade un bloque `mcpServers` de nivel raíz en `~/.claude.json` (Claude
+Code) — misma forma que el `.mcp.json`, pero en el archivo global del usuario. Usa
+rutas absolutas del ejecutable de Python y de `HIPERCAMPO_DB`. Reinicia Claude Code.
+
+> Puedes tener ambos (global + `.mcp.json` del repo): si apuntan a la misma BD y
+> comando, es inofensivo. El `.mcp.json` del repo es útil para quien clone el proyecto.
+
+### Aislar contextos: namespaces (recomendado) o ficheros distintos
+
+Dos formas de que lo de un proyecto no se mezcle con otro (local-first, ambas válidas):
+
+**Opción A — namespaces (una sola BD).** Añade `HIPERCAMPO_NAMESPACE` al `env` de
+cada servidor. Cada recuerdo lleva su contexto y **nada cruza** (lecturas, escrituras
+por id y enlaces, todo acotado):
+
+```json
+"env": {
+  "HIPERCAMPO_DB": "C:/Users/tu/.hipercampo/hipercampo.db",
+  "HIPERCAMPO_NAMESPACE": "mplayer"
+}
+```
+
+**Opción B — ficheros distintos.** Un `HIPERCAMPO_DB` por proyecto (abajo). Es
+aislamiento **local entre contextos**, no una frontera de seguridad multiusuario
+(ver [SECURITY.md](SECURITY.md)).
+
+### Híbrida: memoria personal + memoria por proyecto
+
+Dos servidores con **BD distinta** (o mismo fichero y distinto namespace), para que
+lo técnico de un proyecto no se mezcle con otro pero Claude te siga conociendo:
+
+**1) Personal (global, `~/.claude.json`)** — un servidor `memoria` con su propia BD:
+
+```json
+"mcpServers": {
+  "memoria": {
+    "command": "C:/Python313/python.exe",
+    "args": ["-m", "hipercampo.server"],
+    "env": { "HIPERCAMPO_DB": "C:/Users/tu/.hipercampo/personal.db" }
+  }
+}
+```
+
+**2) Por proyecto (`.mcp.json` en la raíz de cada proyecto)** — un servidor
+`proyecto` con una BD propia por proyecto:
+
+```json
+{
+  "mcpServers": {
+    "proyecto": {
+      "command": "C:/Python313/python.exe",
+      "args": ["-m", "hipercampo.server"],
+      "env": { "HIPERCAMPO_DB": "C:/Users/tu/.hipercampo/proj-NOMBRE.db" }
+    }
+  }
+}
+```
+
+Cambia `proj-NOMBRE.db` por proyecto (`proj-mplayer.db`, `proj-web.db`...). Claude
+verá dos juegos de herramientas (`memoria` y `proyecto`) y elegirá dónde guardar
+cada cosa. Para copiar tu memoria actual a la personal: `python -m hipercampo.backup
+C:/Users/tu/.hipercampo/personal.db` (con `HIPERCAMPO_DB` apuntando a la vieja).
+
+### Claude Desktop
+
+Edita el archivo de configuración:
+
+- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "hipercampo": {
+      "command": "docker",
+      "args": ["run", "--rm", "-i",
+               "-v", "hipercampo_data:/data",
+               "hipercampo:latest"]
+    }
+  }
+}
+```
+
+(O con Python: `"command": "python"`, `"args": ["-m", "hipercampo.server"]`, y
+`"env": {"HIPERCAMPO_DB": "C:/ruta/a/hipercampo.db"}`.)
+
+Reinicia Claude Desktop.
+
+---
+
+## Comprobar que Claude ya tiene memoria
+
+En una conversación con Claude, pídele:
+
+> «Guarda en tu memoria que prefiero respuestas directas» → usará `hc_remember`.
+> Más tarde: «¿qué recuerdas sobre cómo prefiero que me hables?» → usará `hc_recall`.
+
+También puedes verificar el servidor sin Claude, con un handshake MCP crudo:
+
+```bash
+printf '%s\n' \
+'{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"t","version":"0"}}}' \
+'{"jsonrpc":"2.0","method":"notifications/initialized"}' \
+'{"jsonrpc":"2.0","id":2,"method":"tools/list"}' | python -m hipercampo.server
+```
+
+Debe listar las 10 herramientas `hc_*`.
+
+---
+
+## Controlar y respaldar la memoria
+
+Toda la memoria de hipercampo es **un único fichero SQLite**. Fácil de ver, mover,
+copiar o borrar.
+
+### ¿Dónde está?
+
+Por defecto:
+
+- **Local (Windows)**: `C:\Users\<tú>\.hipercampo\hipercampo.db`
+- **Local (macOS/Linux)**: `~/.hipercampo/hipercampo.db`
+- **Docker**: dentro del volumen `hipercampo_data` (`/data/hipercampo.db`)
+
+Puedes cambiarla con la variable **`HIPERCAMPO_DB`** (en el `env` de la config MCP,
+o al lanzar el server). Y puedes preguntárselo a Claude: la herramienta `hc_stats`
+devuelve el campo `db` con la ruta absoluta.
+
+### Controlar su uso desde Claude
+
+Las 10 herramientas te dan control total, sin tocar código:
+
+| Quieres… | Pídele a Claude (usa la tool) |
+|----------|-------------------------------|
+| Ver cuánto recuerda y dónde | `hc_stats` |
+| Que guarde algo concreto | `hc_remember` (con `importance` alta para que no se olvide) |
+| Que recuerde algo | `hc_recall` |
+| Actualizar un hecho que cambió | `hc_update` |
+| Condensar (fase de sueño) | `hc_consolidate` |
+| Podar lo viejo/trivial | `hc_forget` (usa `dry_run=true` para ver antes qué se iría) |
+| Empezar de cero | cierra el server y borra el fichero `.db` |
+
+Los umbrales (cuándo algo es "novedoso", "predecible", cuándo se olvida) están al
+inicio de [`hipercampo/memory.py`](hipercampo/memory.py) — comentados y ajustables.
+
+### Backup y restauración
+
+```bash
+# Copia de seguridad (consistente, aunque el server esté activo):
+python -m hipercampo.backup                       # -> <db>.YYYYMMDD-HHMMSS.bak
+python -m hipercampo.backup C:\copias\hc.db        # -> a la ruta que elijas
+
+# Restaurar desde una copia:
+python -m hipercampo.backup --restore C:\copias\hc.db
+```
+
+O simplemente **copia el fichero `.db`** con el server parado; es igual de válido.
+En Docker: `docker run --rm -v hipercampo_data:/data -v "%cd%":/backup alpine \
+cp /data/hipercampo.db /backup/`.
+
+---
+
+## Semántica opcional (para sinónimos)
+
+Por defecto hipercampo es léxico (CPU, sin GPU). Si quieres que capte sinónimos:
+
+```bash
+pip install -e ".[semantic]"     # trae sentence-transformers (Apache-2.0)
+```
+
+Y actívala en el servidor con una variable de entorno (en el `env` de tu config MCP):
+
+```json
+"env": {
+  "HIPERCAMPO_DB": "C:/Users/tu/.hipercampo/hipercampo.db",
+  "HIPERCAMPO_SEMANTIC": "1"
+}
+```
+
+(O en código: `from hipercampo import encoder; encoder.enable_semantic()`.)
+
+Sube el MRR global de recuperación de **0.77 a 0.95** en el banco de estrés
+(`python scripts/stress.py --semantic`). La 1ª vez descarga el modelo. Ver
+[ATTRIBUTION.md](ATTRIBUTION.md) para licencias del modelo.
+
+---
+
+## Problemas frecuentes
+
+| Síntoma | Causa / solución |
+|---|---|
+| `No module named hipercampo` | No hiciste `pip install -e .` en la carpeta del proyecto. |
+| Claude no ve las herramientas | Reinicia el cliente tras editar la config; revisa que la ruta/comando sea correcta. |
+| El comando `hipercampo` no existe | Usa `python -m hipercampo.server` (el script de consola puede no estar en el PATH). |
+| Docker: "cannot access stdin" | Falta `-i` en `docker run` (MCP habla por stdin). |
+| La memoria "se pierde" | En Docker, comprueba que montas el volumen `-v hipercampo_data:/data`. |

hipercampo-0.1.0a2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Armando Jaleo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.