Mnemex

Mnemex es un servidor MCP en Python que proporciona a los asistentes de IA dinámicas de memoria similares a las humanas mediante decaimiento temporal y repetición espaciada natural, almacenando recuerdos localmente en formatos JSONL y Markdown legibles por humanos.

GitHub

Prueba este MCPPatrocinado

Documentación

CortexGraph: Memoria Temporal para IA

Un servidor de Protocolo de Contexto de Modelos (MCP) que proporciona dinámicas de memoria similares a las humanas para asistentes de IA. Los recuerdos se desvanecen naturalmente con el tiempo a menos que se refuercen mediante el uso, imitando la curva del olvido de Ebbinghaus.

[!NOTE] Acerca del Nombre y la Versión

Este proyecto fue desarrollado originalmente como mnemex (publicado en PyPI hasta v0.6.0). En noviembre de 2025, fue transferido a Prefrontal Systems y renombrado a CortexGraph para reflejar mejor su papel dentro de una arquitectura cognitiva más amplia para sistemas de IA.

La numeración de versiones comienza en 0.1.0 para el paquete cortexgraph para señalar un nuevo comienzo bajo el nuevo nombre, mientras se reconoce la base de código madura y bien probada (791 pruebas, cobertura del 98%+) heredada de mnemex. El paquete mnemex permanece congelado en v0.6.0 en PyPI.

Este enfoque de versionado:

Señala "nuevo paquete" a los usuarios de PyPI que descubren cortexgraph

Da espacio para evolucionar la marca, la API y la integración organizacional antes de 1.0

Mantiene la continuidad: los usuarios pueden migrar de pip install mnemex → pip install cortexgraph

Refleja que, aunque el código es maduro, la identidad de cortexgraph apenas comienza

[!IMPORTANT] 🔬 ARTEFACTO DE INVESTIGACIÓN - NO PARA PRODUCCIÓN

Este software es una Prueba de Concepto (PoC) y una implementación de referencia con fines de investigación. Existe para validar marcos teóricos en arquitectura cognitiva y seguridad de IA (específicamente el Protocolo STOPPER y CortexGraph).

NO es un producto comercial. No se mantiene para uso general en producción, puede contener cambios disruptivos y no ofrece garantías de estabilidad ni soporte. Úsalo para estudiar los conceptos, pero construye tus propias implementaciones de producción.

📖 ¿Nuevo en este proyecto? Comienza con la Guía ELI5 para una explicación sencilla de qué hace esto y cómo usarlo.

¿Qué es CortexGraph?

CortexGraph le da a asistentes de IA como Claude un sistema de memoria similar al humano.

El Problema

Cuando conversas con Claude, olvida todo entre conversaciones. Le dices "prefiero TypeScript" o "soy alérgico a los cacahuetes", y tres días después tienes que repetirte. Esto es frustrante y pierde tiempo.

Qué Hace CortexGraph

CortexGraph hace que los asistentes de IA recuerden cosas naturalmente, igual que la memoria humana:

🧠 Recuerda lo que importa - Tus preferencias, decisiones y datos importantes
⏰ Olvida naturalmente - La información vieja y no utilizada se desvanece con el tiempo (como la curva del olvido de Ebbinghaus)
💪 Se fortalece con el uso - Cuanto más referencias algo, más tiempo se recuerda
📦 Guarda cosas importantes permanentemente - Los recuerdos usados con frecuencia se promueven al almacenamiento a largo plazo

Cómo Funciona (Versión Simple)

Hablas naturalmente - "Prefiero el modo oscuro en todas mis aplicaciones"
La memoria se guarda automáticamente - No se necesitan comandos especiales
Pasa el tiempo - La memoria se desvanece gradualmente si no se usa
Lo referencias de nuevo - "Haz que esta aplicación esté en modo oscuro"
La memoria se fortalece - Ahora dura aún más
Los recuerdos importantes se promueven - ¿Usado 5+ veces? Guardado permanentemente en tu bóveda de Obsidian

Sin tarjetas de memoria. Sin repaso explícito. Solo conversación natural.

Por Qué es Diferente

La mayoría de los sistemas de memoria son simples:

❌ "Eliminar después de 7 días" (no le importa si lo usaste 100 veces)
❌ "Conservar los últimos 100 elementos" (descarta cosas importantes solo porque son antiguas)

CortexGraph es inteligente:

✅ Combina recencia (¿cuándo?), frecuencia (¿con qué frecuencia?) e importancia (¿qué tan crítico?)
✅ Los recuerdos se desvanecen naturalmente como la memoria humana
✅ Los recuerdos usados con frecuencia duran más
✅ Puedes marcar cosas críticas para "nunca olvidar"

Resumen Técnico

Este repositorio contiene investigación, diseño y una implementación completa de un sistema de memoria a corto plazo que combina:

Novedoso algoritmo de decaimiento temporal basado en ciencia cognitiva
Aprendizaje por refuerzo a través de patrones de uso
Arquitectura de dos capas (STM + LTM) para memoria de trabajo y permanente
Patrones de prompting inteligentes para integración natural con LLM
Almacenamiento compatible con Git con JSONL legible por humanos
Grafo de conocimiento con entidades y relaciones

Organización de Módulos

CortexGraph sigue una arquitectura modular:

cortexgraph.core: Algoritmos fundamentales (decaimiento, similitud, agrupamiento, consolidación, validación de búsqueda)
cortexgraph.agents: Pipeline de consolidación multiagente y utilidades de almacenamiento
cortexgraph.storage: Backends de almacenamiento JSONL y SQLite con operaciones por lotes
cortexgraph.tools: Implementaciones de herramientas MCP

¿Por Qué CortexGraph?

🔒 Privacidad y Transparencia

Todos los datos se almacenan localmente en tu máquina - sin servicios en la nube, sin rastreo, sin compartir datos.

Memoria a corto plazo:
- JSONL (predeterminado): Archivos legibles por humanos y compatibles con Git (~/.config/cortexgraph/jsonl/)
- SQLite: Almacenamiento de base de datos robusto para conjuntos de datos más grandes (~/.config/cortexgraph/cortexgraph.db)
Memoria a largo plazo: Archivos Markdown optimizados para Obsidian
- Frontmatter YAML con metadatos
- Wikilinks para conexiones
- Almacenamiento permanente que controlas
Exportación: Utilidad integrada para exportar recuerdos a Markdown para portabilidad.

Tus datos te pertenecen. Puedes leerlos, editarlos, eliminarlos o controlar sus versiones, todo sin herramientas especiales.

Algoritmo Central

La función de puntuación de decaimiento temporal:

$$ \Large \text{score}(t) = (n_{\text{use}})^\beta \cdot e^{-\lambda \cdot \Delta t} \cdot s $$

Donde:

$\large n_{\text{use}}$ - Conteo de uso (número de accesos)
$\large \beta$ (beta) - Ponderación sublineal del conteo de uso (predeterminado: 0.6)
$\large \lambda = \frac{\ln(2)}{t_{1/2}}$ (lambda) - Constante de decaimiento; establecida mediante vida media (predeterminado: 3 días)
$\large \Delta t$ - Tiempo desde el último acceso (segundos)
$\large s$ - Parámetro de fuerza $\in [0, 2]$ (multiplicador de importancia)

Umbrales:

$\large \tau_{\text{forget}}$ (predeterminado 0.05) — si la puntuación < esto, olvidar
$\large \tau_{\text{promote}}$ (predeterminado 0.65) — si la puntuación ≥ esto, promover (o si $\large n_{\text{use}}\ge5$ en 14 días)

Modelos de Decaimiento:

Ley de Potencia (predeterminado): cola más pesada; retención más similar a la humana
Exponencial: cola más ligera; olvida antes
Dos Componentes: olvido temprano rápido + cola más pesada

Consulta la referencia detallada de parámetros, la selección de modelos y ejemplos prácticos en docs/scoring_algorithm.md.

Hoja de Referencia de Ajuste

Equilibrado (predeterminado)
- Vida media: 3 días (λ ≈ 2.67e-6)
- β = 0.6, τ_forget = 0.05, τ_promote = 0.65, conteo_de_uso≥5 en 14d
- Fuerza: 1.0 (aumentar a 1.3–2.0 para crítico)
Contexto de alta velocidad (notas efímeras, cambio rápido)
- Vida media: 12–24 horas (λ ≈ 1.60e-5 a 8.02e-6)
- β = 0.8–0.9, τ_forget = 0.10–0.15, τ_promote = 0.70–0.75
Retención larga (investigación/archivo)
- Vida media: 7–14 días (λ ≈ 1.15e-6 a 5.73e-7)
- β = 0.3–0.5, τ_forget = 0.02–0.05, τ_promote = 0.50–0.60
Asistentes con muchas preferencias/decisiones
- Vida media: 3–7 días; β = 0.6–0.8
- Fuerzas predeterminadas: 1.3–1.5 para preferencias; 1.8–2.0 para decisiones
Control agresivo de espacio
- Aumentar τ_forget a 0.08–0.12 y/o acortar la vida media; programar GC semanal
Plantilla de entorno
- CORTEXGRAPH_DECAY_LAMBDA=2.673e-6, CORTEXGRAPH_DECAY_BETA=0.6
- CORTEXGRAPH_FORGET_THRESHOLD=0.05, CORTEXGRAPH_PROMOTE_THRESHOLD=0.65
- CORTEXGRAPH_PROMOTE_USE_COUNT=5, CORTEXGRAPH_PROMOTE_TIME_WINDOW=14

Umbrales de decisión:

Olvidar: $\text{score} < 0.05$ → eliminar memoria
Promover: $\text{score} \geq 0.65$ O $n_{\text{use}} \geq 5$ dentro de 14 días → mover a LTM

Innovaciones Clave

1. Decaimiento Temporal con Refuerzo

A diferencia del almacenamiento en caché tradicional (TTL, LRU), Mnemex puntúa las memorias continuamente combinando recencia (decaimiento exponencial), frecuencia (conteo de uso sublineal) e importancia (fuerza ajustable). Consulta Algoritmo Central para la fórmula matemática. Esto crea dinámicas de memoria que imitan de cerca la cognición humana.

2. Sistema de Prompting Inteligente + Activación por Lenguaje Natural (v0.6.0+)

Patrones para hacer que los asistentes de IA usen la memoria naturalmente, ahora mejorados con extracción automática de entidades y puntuación de importancia:

Auto-Enriquecimiento (NUEVO en v0.6.0)

Cuando guardas memorias, CortexGraph automáticamente:

Extrae entidades (personas, tecnologías, organizaciones) usando NER de spaCy
Calcula importancia/fuerza basándose en marcadores de contenido
Detecta intención de guardar/recuperar a partir de frases en lenguaje natural

# Before v0.6.0 - manual entity specification
save_memory(content="Use JWT for auth", entities=["JWT", "auth"])

# v0.6.0+ - automatic extraction
save_memory(content="Use JWT for auth")
# Entities auto-extracted: ["jwt", "auth"]
# Strength auto-calculated based on content

Auto-Guardado

User: "Remember: I prefer TypeScript over JavaScript"
→ Detected save phrase: "Remember"
→ Automatically saved with:
   - Entities: [typescript, javascript]
   - Strength: 1.5 (importance marker detected)
   - Tags: [preferences, programming]

Auto-Recuperación

User: "What did I say about TypeScript?"
→ Detected recall phrase: "what did I say about"
→ Automatically searches for TypeScript memories
→ Retrieves preferences and conventions

Auto-Refuerzo

User: "Yes, still using TypeScript"
→ Memory strength increased, decay slowed

Herramientas de Soporte a Decisiones (v0.6.0+)

Dos nuevas herramientas ayudan a Claude a decidir cuándo guardar/recuperar:

analyze_message - Detecta contenido digno de memoria, sugiere entidades y fuerza
analyze_for_recall - Detecta intención de recuperación, sugiere consultas de búsqueda

No se necesitan comandos de memoria explícitos - solo conversación natural.

3. Repetición Espaciada Natural

Inspirado en cómo los conceptos se refuerzan naturalmente en diferentes contextos (el "efecto Maslow" - recordar mejor la jerarquía de Maslow cuando aparece en clases de historia, economía y sociología).

Sin tarjetas de memoria. Sin sesiones de repaso explícitas. Solo conversación natural.

Cómo funciona:

Cálculo de Prioridad de Repaso - Las memorias en la "zona de peligro" (puntuación de decaimiento 0.15-0.35) obtienen la prioridad más alta
Detección entre Dominios - Detecta cuando las memorias se usan en diferentes contextos (similitud Jaccard de etiquetas <30%)
Refuerzo Automático - Las memorias se fortalecen naturalmente cuando se usan, especialmente entre dominios
Búsqueda Mezclada - Los candidatos de repaso aparecen en el 30% de los resultados de búsqueda (configurable)

Patrón de uso:

User: "Can you help with authentication in my API?"
→ System searches, retrieves JWT preference memory
→ System uses memory to answer question
→ System calls observe_memory_usage with context tags [api, auth, backend]
→ Cross-domain usage detected (original tags: [security, jwt, preferences])
→ Memory automatically reinforced, strength boosted
→ Next search naturally surfaces memories needing review

Configuración:

CORTEXGRAPH_REVIEW_BLEND_RATIO=0.3           # 30% review candidates in search
CORTEXGRAPH_REVIEW_DANGER_ZONE_MIN=0.15      # Lower bound of danger zone
CORTEXGRAPH_REVIEW_DANGER_ZONE_MAX=0.35      # Upper bound of danger zone
CORTEXGRAPH_AUTO_REINFORCE=true              # Auto-reinforce on observe

Consulta docs/prompts/ para plantillas de prompt de sistema LLM que permiten el uso natural de la memoria.

4. Arquitectura de Dos Capas

graph TD
    STM["<b>Short-Term Memory</b><br/>- JSONL storage<br/>- Temporal decay<br/>- Hours to weeks retention"]
    LTM["<b>LTM (Long-Term Memory)</b><br/>- Markdown files Obsidian<br/>- Permanent storage<br/>- Git version control"]
    
    STM -->|Automatic promotion| LTM
    
    style STM fill:#e1f5ff,stroke:#01579b,stroke-width:2px
    style LTM fill:#f3e5f5,stroke:#4a148c,stroke-width:2px

5. Pipeline de Consolidación Multiagente

Mantenimiento automatizado de memoria a través de cinco agentes especializados:

graph LR
    decay["<b>DecayAnalyzer</b><br/>Find at-risk<br/>memories"]
    cluster["<b>ClusterDetector</b><br/>Find similar<br/>groups"]
    merge["<b>SemanticMerge</b><br/>Combine<br/>similar groups"]
    promote["<b>LTMPromoter</b><br/>Promote<br/>to LTM"]
    relations["<b>RelationshipDiscovery</b><br/>Discover cross-<br/>domain links"]
    
    decay --> cluster
    cluster --> merge
    merge --> promote
    promote --> relations
    relations -.->|feedback| decay
    
    style decay fill:#ffebee,stroke:#b71c1c,stroke-width:2px
    style cluster fill:#fff3e0,stroke:#e65100,stroke-width:2px
    style merge fill:#f3e5f5,stroke:#4a148c,stroke-width:2px
    style promote fill:#e8f5e9,stroke:#1b5e20,stroke-width:2px
    style relations fill:#e1f5fe,stroke:#01579b,stroke-width:2px

Los Cinco Agentes:

Agente	Propósito
DecayAnalyzer	Encontrar memorias en riesgo de ser olvidadas (zona de peligro: 0.15-0.35)
ClusterDetector	Agrupar memorias similares usando similitud de embeddings
SemanticMerge	Combinar inteligentemente memorias agrupadas, preservando información única
LTMPromoter	Mover memorias de alto valor al almacenamiento permanente de Obsidian
RelationshipDiscovery	Encontrar conexiones entre dominios mediante entidades compartidas

Características Clave:

Modo de simulación: Previsualizar cambios sin modificar datos
Límite de velocidad: Operaciones configurables por minuto (predeterminado: 60)
Rastro de auditoría: Cada decisión rastreada mediante seguimiento de problemas beads
Anulación humana: Revisar y aprobar decisiones antes de la ejecución

Uso:

from cortexgraph.agents import Scheduler

# Preview what would change (dry run)
scheduler = Scheduler(dry_run=True)
preview = scheduler.run_pipeline()

# Run full pipeline
scheduler = Scheduler(dry_run=False)
results = scheduler.run_pipeline()

# Run single agent
decay_results = scheduler.run_agent("decay")

CLI:

# Dry run (preview)
cortexgraph-consolidate --dry-run

# Run specific agent
cortexgraph-consolidate --agent decay --dry-run

# Scheduled execution (with interval)
cortexgraph-consolidate --scheduled --interval-hours 1

Consulta docs/agents.md para documentación completa incluyendo configuración, integración con beads y solución de problemas.

Inicio Rápido

Instalación

Recomendado: Instalación con Herramienta UV (desde PyPI)

# Install from PyPI (recommended - fast, isolated, includes all 7 CLI commands)
uv tool install cortexgraph

Esto instala cortexgraph y los 7 comandos CLI en un entorno aislado.

Métodos de Instalación Alternativos

# Using pipx (similar isolation to uv)
pipx install cortexgraph

# Using pip (traditional, installs in current environment)
pip install cortexgraph

# From GitHub (latest development version)
uv tool install git+https://github.com/simplemindedbot/cortexgraph.git

Para Desarrollo (Instalación Editable)

# Clone and install in editable mode
git clone https://github.com/simplemindedbot/cortexgraph.git
cd cortexgraph
uv pip install -e ".[dev]"

Configuración

IMPORTANTE: La ubicación de configuración depende del método de instalación:

Método 1: Archivo .env (Funciona para todos los métodos de instalación)

Crear ~/.config/cortexgraph/.env:

# Create config directory
mkdir -p ~/.config/cortexgraph

# Option A: Copy from cloned repo
cp .env.example ~/.config/cortexgraph/.env

# Option B: Download directly
curl -o ~/.config/cortexgraph/.env https://raw.githubusercontent.com/simplemindedbot/cortexgraph/main/.env.example

Editar ~/.config/cortexgraph/.env con tus ajustes:

# Storage
CORTEXGRAPH_STORAGE_PATH=~/.config/cortexgraph/jsonl

# Decay model (power_law | exponential | two_component)
CORTEXGRAPH_DECAY_MODEL=power_law

# Power-law parameters (default model)
CORTEXGRAPH_PL_ALPHA=1.1
CORTEXGRAPH_PL_HALFLIFE_DAYS=3.0

# Exponential (if selected)
# CORTEXGRAPH_DECAY_LAMBDA=2.673e-6  # 3-day half-life

# Two-component (if selected)
# CORTEXGRAPH_TC_LAMBDA_FAST=1.603e-5  # ~12h
# CORTEXGRAPH_TC_LAMBDA_SLOW=1.147e-6  # ~7d
# CORTEXGRAPH_TC_WEIGHT_FAST=0.7

# Common parameters
CORTEXGRAPH_DECAY_LAMBDA=2.673e-6
CORTEXGRAPH_DECAY_BETA=0.6

# Thresholds
CORTEXGRAPH_FORGET_THRESHOLD=0.05
CORTEXGRAPH_PROMOTE_THRESHOLD=0.65

# Long-term memory (optional)
LTM_VAULT_PATH=~/Documents/Obsidian/Vault

Dónde busca cortexgraph los archivos .env:

Principal: ~/.config/cortexgraph/.env ← Usa esto para uv tool install / uvx
Respaldo: ./.env (directorio actual) ← Solo funciona para instalaciones editables

Configuración MCP

Recomendado: Usar ruta absoluta (funciona en todas partes)

Añadir a ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "cortexgraph": {
      "command": "/Users/yourusername/.local/bin/cortexgraph"
    }
  }
}

Encuentra tu ruta real:

which cortexgraph
# Example output: /Users/yourusername/.local/bin/cortexgraph

Usa esa ruta en tu configuración. Reemplaza yourusername con tu nombre de usuario real.

¿Por qué ruta absoluta? Las aplicaciones GUI como Claude Desktop no heredan la configuración PATH de tu shell (.zshrc, .bashrc). Usar la ruta completa garantiza que siempre funcione.

Para desarrollo (instalación editable):

{
  "mcpServers": {
    "cortexgraph": {
      "command": "uv",
      "args": ["--directory", "/path/to/cortexgraph", "run", "cortexgraph"],
      "env": {"PYTHONPATH": "/path/to/cortexgraph/src"}
    }
  }
}

La configuración se puede cargar desde ./.env en el directorio del proyecto O ~/.config/cortexgraph/.env.

Solución de problemas: Comando no encontrado

Si Claude Desktop muestra errores de spawn cortexgraph ENOENT, el comando cortexgraph no está en el PATH de Claude Desktop.

macOS/Linux: las aplicaciones GUI no heredan el PATH del shell

Las aplicaciones GUI en macOS y Linux no ven la configuración PATH de tu shell (.zshrc, .bashrc, etc.). Claude Desktop solo busca:

/usr/local/bin
/opt/homebrew/bin (macOS)
/usr/bin
/bin
/usr/sbin
/sbin

Si uv tool install colocó cortexgraph en ~/.local/bin/ u otra ubicación personalizada, Claude Desktop no puede encontrarlo.

Solución: Usa la ruta absoluta

# Find where cortexgraph is installed
which cortexgraph
# Example output: /Users/username/.local/bin/cortexgraph

Actualiza tu configuración de Claude con la ruta absoluta:

{
  "mcpServers": {
    "cortexgraph": {
      "command": "/Users/username/.local/bin/cortexgraph"
    }
  }
}

Reemplaza /Users/username/.local/bin/cortexgraph con tu ruta real de which cortexgraph.

Mantenimiento

Usa la CLI de mantenimiento para inspeccionar y compactar el almacenamiento JSONL:

# Show storage stats (active counts, file sizes, compaction hints)
cortexgraph-maintenance stats

# Compact JSONL (rewrite without tombstones/duplicates)
cortexgraph-maintenance compact

Migración a la instalación de herramientas UV

Si actualmente usas una instalación editable (uv pip install -e .), puedes cambiar a la instalación de herramientas UV más simple:

# 1. Uninstall editable version
uv pip uninstall cortexgraph

# 2. Install as UV tool
uv tool install git+https://github.com/simplemindedbot/cortexgraph.git

# 3. Update Claude Desktop config to just:
#    {"command": "cortexgraph"}
#    Remove the --directory, run, and PYTHONPATH settings

¡Tus datos están a salvo! Esto solo cambia cómo se instala el comando. Tus recuerdos en ~/.config/cortexgraph/ no se modifican.

Comandos CLI

El servidor incluye 7 herramientas de línea de comandos:

cortexgraph                  # Run MCP server
cortexgraph-migrate          # Migrate from old STM setup
cortexgraph-index-ltm        # Index Obsidian vault
cortexgraph-backup           # Git backup operations
cortexgraph-vault            # Vault markdown operations
cortexgraph-search           # Unified STM+LTM search
cortexgraph-maintenance      # JSONL storage stats and compaction

Visualización

Visualización interactiva de grafos usando PyVis:

# Install visualization dependencies
pip install "cortexgraph[visualization]"
# or with uv
uv pip install "cortexgraph[visualization]"

# Or install dependencies manually
pip install pyvis networkx

# Generate interactive HTML visualization
python scripts/visualize_graph.py

# Custom output location
python scripts/visualize_graph.py --output ~/Desktop/memory_graph.html

# Custom data paths
python scripts/visualize_graph.py --memories ~/data/memories.jsonl --relations ~/data/relations.jsonl

Características:

Grafo de red interactivo con desplazamiento/zoom
Colores de nodos por estado (activo=azul, promovido=verde, archivado=gris)
Tamaño de nodo basado en el recuento de uso
Colores de aristas por tipo de relación
Información emergente al pasar el cursor mostrando contenido completo, etiquetas y entidades
Controles de física para ajuste del diseño

La visualización lee directamente de tus archivos JSONL y crea un archivo HTML independiente que puedes abrir en cualquier navegador.

Herramientas MCP

13 herramientas para que los asistentes de IA gestionen recuerdos:

Herramienta	Propósito
`save_memory`	Guardar nuevo recuerdo con etiquetas, entidades (autoenriquecimiento en v0.6.0+)
`search_memory`	Buscar con filtros y puntuación (incluye candidatos de revisión)
`search_unified`	Búsqueda unificada en STM + LTM
`touch_memory`	Reforzar recuerdo (aumentar fuerza)
`observe_memory_usage`	Registrar uso del recuerdo para repetición espaciada natural
`analyze_message`	✨ NUEVO v0.6.0 - Detectar contenido digno de recordar, sugerir entidades/fuerza
`analyze_for_recall`	✨ NUEVO v0.6.0 - Detectar intención de recuerdo, sugerir consultas de búsqueda
`gc`	Recolectar recuerdos con baja puntuación
`promote_memory`	Mover al almacenamiento a largo plazo
`cluster_memories`	Encontrar recuerdos similares
`consolidate_memories`	Fusionar recuerdos similares (algorítmico)
`read_graph`	Obtener grafo de conocimiento completo
`open_memories`	Recuperar recuerdos específicos
`create_relation`	Enlazar recuerdos explícitamente

Ejemplo: Búsqueda unificada

Busca en STM y LTM con la CLI:

cortexgraph-search "typescript preferences" --tags preferences --limit 5 --verbose

Ejemplo: Reforzar (tocar) recuerdo

Aumenta la actualidad/recuento de uso de un recuerdo para ralentizar la decadencia:

{
  "memory_id": "mem-123",
  "boost_strength": true
}

Respuesta de ejemplo:

{
  "success": true,
  "memory_id": "mem-123",
  "old_score": 0.41,
  "new_score": 0.78,
  "use_count": 5,
  "strength": 1.1
}

Ejemplo: Promover recuerdo

Sugiere y promueve recuerdos de alto valor a la bóveda de Obsidian.

Detección automática (prueba en seco):

{
  "auto_detect": true,
  "dry_run": true
}

Promover un recuerdo específico:

{
  "memory_id": "mem-123",
  "dry_run": false,
  "target": "obsidian"
}

Como herramienta MCP (cuerpo de solicitud):

{
  "query": "typescript preferences",
  "tags": ["preferences"],
  "limit": 5,
  "verbose": true
}

Ejemplo: Consolidar recuerdos similares

Encuentra y fusiona recuerdos duplicados o muy similares para reducir el desorden:

Detección automática de candidatos (vista previa):

{
  "auto_detect": true,
  "mode": "preview",
  "cohesion_threshold": 0.75
}

Aplicar consolidación a los clústeres detectados:

{
  "auto_detect": true,
  "mode": "apply",
  "cohesion_threshold": 0.80
}

La herramienta:

Fusionará contenido de forma inteligente (preservando información única)
Combinará etiquetas y entidades (unión)
Calculará la fuerza basada en la cohesión del clúster
Preservará las marcas de tiempo más antiguas created_at y más recientes last_used
Creará relaciones de seguimiento que muestran el historial de consolidación

Detalles matemáticos

Curvas de decadencia

Para un recuerdo con $n_{\text{use}}=1$, $s=1.0$ y $\lambda = 2.673 \times 10^{-6}$ (vida media de 3 días):

Tiempo	Puntuación	Estado
0 horas	1.000	Nuevo
12 horas	0.917	Activo
1 día	0.841	Activo
3 días	0.500	Vida media
7 días	0.210	En decadencia
14 días	0.044	Cerca del olvido
30 días	0.001	Olvidado

Impacto del recuento de uso

Con $\beta = 0.6$ (ponderación sublineal):

Recuento de uso	Factor de aumento
1	1.0×
5	2.6×
10	4.0×
50	11.4×

El acceso frecuente extiende significativamente la retención.

Documentación

Referencia de herramientas MCP - Documentación completa para las 18 herramientas MCP
Referencia rápida de API - Firmas mínimas de herramientas y ejemplos de uso
Algoritmo de puntuación - Modelo matemático completo con fórmulas LaTeX
Prompting inteligente - Patrones para integración natural con LLM
Arquitectura - Diseño e implementación del sistema
Sistema multiagente - Agentes de consolidación y arquitectura de pipeline
Integración con Bear - Guía para usar la aplicación Bear como almacén LTM
Características del grafo - Uso del grafo de conocimiento

Casos de uso

Asistente personal (Equilibrado)

Vida media de 3 días
Recordar preferencias y decisiones
Promover automáticamente información referenciada con frecuencia

Entorno de desarrollo (Agresivo)

Vida media de 1 día
Cambio rápido de contexto
Olvido agresivo de contexto antiguo

Investigación / Archivo (Conservador)

Vida media de 14 días
Retención prolongada
Preservación integral del conocimiento

Licencia

Licencia AGPL-3.0 - Consulta LICENSE para más detalles.

Este proyecto utiliza la Licencia Pública General Affero de GNU v3.0, que requiere que las modificaciones a este software se pongan a disposición como código fuente cuando se utilice para proporcionar un servicio de red.

Trabajo relacionado

Model Context Protocol - Especificación MCP
Curva del olvido de Ebbinghaus - Fundamento de la ciencia cognitiva
Basic Memory - Inspiración principal para la capa de integración. CortexGraph extiende este concepto añadiendo la curva del olvido de Ebbinghaus, algoritmos de decadencia temporal, memoria a corto plazo en almacenamiento JSONL y repetición espaciada natural.
Investigación adicional inspirada en: mem0, Neo4j Graph Memory

Cita

Si usas este trabajo en investigación, por favor cita:

@software{cortexgraph_2025,
  title = {Mnemex: Temporal Memory for AI},
  author = {simplemindedbot},
  year = {2025},
  url = {https://github.com/simplemindedbot/cortexgraph},
  version = {0.5.3}
}

Contribuciones

¡Las contribuciones son bienvenidas! Consulta CONTRIBUTING.md para instrucciones detalladas.

🚨 ¡Se necesitan probadores de Windows y Linux!

Desarrollo en macOS y necesito ayuda para probar en Windows y Linux. Si tienes acceso a estas plataformas, por favor:

Prueba las instrucciones de instalación
Ejecuta el conjunto de pruebas
Informa qué funciona y qué no

Consulta la sección de Ayuda necesaria en CONTRIBUTING.md para más detalles.

Contribuciones generales

Para todos los contribuyentes, consulta CONTRIBUTING.md para:

Configuración específica por plataforma (Windows, Linux, macOS)
Flujo de trabajo de desarrollo
Directrices de pruebas
Requisitos de estilo de código
Proceso de solicitudes de extracción (pull requests)

Inicio rápido:

Lee CONTRIBUTING.md para la configuración específica por plataforma
Comprende la documentación de Arquitectura
Revisa el Algoritmo de puntuación
Sigue los patrones de código existentes
Añade pruebas para nuevas funciones
Actualiza la documentación

Estado

Versión: 1.0.0 Estado: Implementación de investigación - funcional pero en evolución

Fase 1 (Completa) ✅

14 herramientas MCP
Algoritmo de decadencia temporal
Grafo de conocimiento

Fase 2 (Completa) ✅

Almacenamiento JSONL
Índice LTM
Integración con Git
Documentación de prompting inteligente
CLI de mantenimiento
Consolidación de recuerdos (fusión algorítmica)

Fase 3 (Completa) ✅

Pipeline de consolidación multiagente
- DecayAnalyzer, ClusterDetector, SemanticMerge, LTMPromoter, RelationshipDiscovery
- Programador para orquestación
- Integración de seguimiento de incidencias Beads
- Soporte de prueba en seco y limitación de velocidad
Activación por lenguaje natural (v0.6.0+)
Autoenriquecimiento para extracción de entidades

Trabajo futuro

Parámetros de decadencia adaptativos
Puntos de referencia de rendimiento
Consolidación asistida por LLM (mejora opcional)

Construido con Claude Code 🤖