CPersona

---

Repositorio independiente — Esta es la versión independiente para usar con Claude Desktop, Claude Code, Codex CLI, Cursor, VS Code y cualquier otro cliente MCP (tabla de registro). Si eres usuario de ClotoCore, instala CPersona desde el mercado integrado (ClotoHub) — distribuye este mismo repositorio.

Estado del proyecto — 2.4.x es Estable; 2.5.x es Actual, una línea de estabilización interna donde se aplican todas las correcciones, pendiente de certificación de uso en producción. El esquema de la base de datos se conserva en toda la línea. También pueden incorporarse aquí funciones aditivas y seguras de reversión (estándar de ciclo de vida §2.6); un cambio que no se pueda revertir espera a la 2.6. Qué versión ejecutar y durante cuánto tiempo cada línea recibe correcciones: SUPPORT.md. Hacia dónde se dirigen las líneas: la hoja de ruta.

¿Actualizas desde 2.5.2 o anterior? Dos cosas requieren una decisión tuya. v2.5.3 no iniciará el transporte HTTP sin CPERSONA_AUTH_TOKEN, dondequiera que se vincule — establece uno, o exclúyete con CPERSONA_ALLOW_UNAUTHENTICATED_HTTP=true (por qué; stdio no se ve afectado). v2.5.2 cambió las formas de respuesta de las herramientas — ramifica en ok is false, y trata cualquier respuesta que lleve error como un fallo, ya sea que ok esté presente o no (contrato §10).

El Problema

Claude olvida todo entre sesiones. Cada conversación comienza desde cero — sin contexto sobre tu proyecto, tus preferencias o lo que discutiste ayer.

cpersona soluciona esto. Es un servidor MCP que almacena recuerdos en un archivo SQLite local y los recupera mediante búsqueda híbrida. Claude te recuerda. Funciona con cualquier host compatible con MCP — Claude Desktop, Claude Code, ClotoCore (la plataforma de agentes de IA donde se originó cpersona, y cuya capa de memoria es), o un cliente propio.

Inicio Rápido

¿Configurando esto como agente de IA? Lee la Habilidad de Agente — skills/cpersona-memory/SKILL.md en un clon de este repositorio — y síguela de principio a fin. Es el procedimiento completo: instalación, servidor de incrustaciones, registro, y los dos pasos que un inicio rápido tiende a omitir — verificar desde una sesión nueva, y persistir la política de memoria para que la próxima sesión sepa qué agent_id contiene los recuerdos.

¿Usas Claude Code tú mismo? La misma habilidad viene dentro del paquete. Una vez que cpersona esté instalado, cópialo y di "Configura CPersona."

python -c "import cpersona,pathlib,shutil; s=pathlib.Path(cpersona.__file__).parent/'skills'/'cpersona-memory'; shutil.copytree(s, pathlib.Path.home()/'.claude/skills/cpersona-memory', dirs_exist_ok=True)"

1. Instala — Python 3.11+, y uv para la ruta de un solo comando.

uvx cpersona          # run directly, no install step
pip install cpersona  # or install it

2. Ejecuta un servidor de incrustaciones — muy recomendado; impulsa la capa vectorial

uvx --from "cembedding[onnx]" cembedding-download-model --model jina-v5-nano
EMBEDDING_PROVIDER=onnx_jina_v5_nano uvx --from "cembedding[onnx]" cembedding   # serves http://127.0.0.1:8401/embed

La vida útil del servidor de referencia está vinculada a su stdin. Iniciado con stdin cerrado — por un administrador de servicios, por nohup … </dev/null, o desde el shell de fondo de un agente — vincula el puerto y sale en el mismo segundo con estado 0. Dale un stdin que permanezca abierto (sleep infinity | cembedding); Primeros pasos tiene los detalles.

Cualquier endpoint que implemente el contrato de incrustación funciona y es igualmente recomendado; CEmbedding es la implementación de referencia. La elección del backend es tuya — la recomendación es conectar uno, no conectar ese específico.

Sin un backend, cpersona aún funciona — FTS5 + búsqueda de palabras clave, y dice en cada recuperación que está degradado en lugar de devolver silenciosamente menos. Ese es un respaldo compatible, no una forma recomendada de ejecutar: la recuperación entonces coincide en palabras compartidas, por lo que un recuerdo expresado de manera diferente a tu pregunta puede pasarse por alto, y también uno más antiguo.

3. Regístralo con tu cliente MCP

claude mcp add-json cpersona '{"type":"stdio","command":"uvx","args":["cpersona"],"env":{"CPERSONA_DB_PATH":"/home/you/.claude/cpersona.db","EMBEDDING_MODE":"http","EMBEDDING_HTTP_URL":"http://127.0.0.1:8401/embed"}}' -s user

4. Verifica desde una sesión nueva — pide al agente que store algo, luego recall en una sesión nueva. Sobrevivir al límite de la sesión es el punto principal.

5. Hazlo persistente — el registro le da al agente las herramientas. No le dice a la próxima sesión que las use, ni qué agent_id contiene los recuerdos: la recuperación está limitada a un agent_id exacto, por lo que una sesión que adivine el incorrecto no obtiene nada. Persiste el bloque de política corto en el archivo que tu cliente carga cada sesión (~/.claude/CLAUDE.md, AGENTS.md, …) — Primeros pasos §5.

Al inicio, el servidor pregunta a pypi.org si existe una versión más reciente y se lo dice al agente que llama a través de recall; establece CPERSONA_UPDATE_CHECK=false para desactivar eso. La actualización nunca es automática.

Configuración de Claude Desktop, rutas de Windows, instalación desde el código fuente y el tutorial completo: Primeros pasos.

Lo Que Obtienes

• Búsqueda híbrida — vectorial (la capa que impulsa un servidor de incrustaciones), FTS5 (trigrama, por lo que funciona en japonés y otros scripts sin espacios) y palabras clave, fusionadas por rango o puntuación relativa. Las capas FTS y de palabras clave rescatan lo que los vectores pierden: identificadores, cadenas de error, nombres exactos.
• Tres tipos de memoria — hechos, resúmenes de sesión y un perfil acumulado.
• Cero dependencia de LLM — cpersona nunca llama a un modelo generativo; tu agente resume y entrega el resultado. La recuperación es determinista dado un umbral calibrado, pero el umbral se muestrea, por lo que dos instalaciones con datos idénticos pueden establecerse de manera diferente.
• SQLite de archivo único — sin base de datos externa; sqlite3 .backup copia el corpus (el archivo lateral de calibración junto a él también necesita copiarse).
• Operable — umbrales auto-calibrados, verificación de salud con auto-reparación, un aviso cuando la capa de incrustación falla, exportación/importación JSONL, fusión agente a agente.
• Aislamiento — agent_id, project_id y channel permiten que varios agentes y proyectos compartan una base de datos sin mezclarse entre sí.

Cómo encaja todo: Arquitectura · qué hacen las herramientas: Herramientas · en qué puedes confiar: Contratos de Comportamiento.

Puntos de Referencia

Medido en LMEB (Long-horizon Memory Embedding Benchmark, arXiv:2603.12572) — 22 conjuntos de datos que subsumen LoCoMo y LongMemEval, medidos aquí como 22 tareas de recuperación. La métrica es Mean NDCG@10 en las 22 tareas. La Pista A es el modelo de incrustación crudo solo; La Pista B enruta las mismas incrustaciones a través de las rutas de código reales de store/recall de cpersona (SQLite + FTS5 + fusión RRF + auto-calibración por agente).

Modelo de Incrustación	Params	Dim	Pista A (crudo)	Pista B (cpersona)	Δ
all-MiniLM-L6-v2	22M	384	43.67	50.10	+6.43
bge-m3	568M	1024	56.83	57.66	+0.83

La Pista B se sitúa en o por encima de la Pista A en ambos modelos: las capas de fusión añaden señal en lugar de simplemente persistir vectores, y una incrustación más débil gana más porque las capas FTS5/palabras clave rescatan lo que sus vectores pierden. Cómo leer los deltas, el sobre de ruido, el arnés de medición y el régimen de reproducción: benchmarks/.

Documentación

cloto-dev.github.io/CPersona es canónico — cuando este README discrepe con él, el sitio gana.

Primeros pasos	Instalación, servidor de incrustaciones, registro de cliente, verificación
Contratos de Comportamiento	En qué puedes confiar: orden de recuperación, deduplicación, ventana de escaneo, formas de respuesta
Herramientas	Cada herramienta, agrupada por para qué la usas
Arquitectura	Almacenamiento, el pipeline de recuperación, ejes de aislamiento
Hoja de ruta	Para qué sirve cada línea de lanzamiento y qué puede romper; características de recuperación planificadas y la escalera de escala
Manual de Operaciones	Copia de seguridad, detección de degradación, ajuste, guía CJK, sincronización de corpus
Configuración	Cada variable de entorno y su valor predeterminado
Aseguramiento de Calidad	Cómo se controla un lanzamiento: auditorías, el registro de errores, puertas estructurales y de mutación
FAQ	Respuestas cortas a las preguntas que los operadores realmente hacen

Las traducciones al japonés están en el selector de idioma (el inglés es canónico) y los agentes pueden leer llms.txt. Lecturas más largas en japonés: un libro sobre el diseño y la configuración, y un artículo sobre la economía de tokens del fin de sesión → /clear → recall.

Aseguramiento de Calidad

Cada lanzamiento está controlado por un proceso verificable por máquina: rondas de auditoría multiagente con verificación adversarial, un registro de errores que falla CI si un marcador de corrección desaparece o un defecto eliminado regresa, puertas estructurales para invariantes que una prueba simple no puede expresar, una prueba de mutación de que esas puertas se ponen rojas cuando el invariante se rompe, y puertas que mantienen los recuentos, valores predeterminados y afirmaciones de versión documentados en la fuente que los define.

Detrás: ~2,092 funciones de prueba en ~156 módulos de prueba (~2,667 casos parametrizados, más código de prueba que código de servidor), en Schema v15 — cómo se controla un lanzamiento.

Soporte

Tres niveles — Estable (certificado para producción, solo correcciones críticas), Actual (línea más nueva, todas las correcciones llegan aquí) y Experimental (pre-lanzamientos opcionales). Una línea reemplazada mantiene soporte de correcciones críticas por 30 días más. Lee SUPPORT.md § Problemas conocidos antes de fijar una versión — algunos de ellos cambian lo que deberías ejecutar.

¿Encontraste un error, o algo que los documentos no explican? Abre un informe de error o solicitud de característica, incluso si no estás seguro — un problema de configuración confundido con un error significa que la documentación no era clara, lo cual es un defecto en sí mismo. Reporta vulnerabilidades de seguridad de forma privada a través de SECURITY.md.

Patrocinio

CPersona tiene licencia MIT y sigue siendo totalmente utilizable independientemente de si alguien lo patrocina o no. El patrocinio no compra ninguna característica, ningún nivel de lanzamiento ni ninguna posición en la cola de problemas — los problemas se clasifican por impacto, reproducibilidad y seguridad, y eso no cambia para nadie.

Si CPersona se ha ganado un lugar en tu flujo de trabajo y te gustaría que el trabajo continúe, puedes patrocinar a Cloto-dev en GitHub. La misma página cubre CPersona, ClotoCore y los otros proyectos publicados bajo esa cuenta; el patrocinio se destina al tiempo de desarrollo, pruebas e infraestructura, documentación y mantenimiento.

El dinero no es lo único que ayuda, y no es lo que este proyecto necesita más. Marcar el repositorio con una estrella, decir qué parte de la configuración fue confusa, presentar un problema reproducible o corregir una oración en la documentación, todo lo hace avanzar.

Licencia

MIT — libre de usar desde cualquier host MCP sin restricción.