Memex

Reúna conversaciones dispersas de Codex, destile conocimiento duradero, conéctelo, indícelo y recupere la memoria adecuada cuando sea importante.

Memex es un sistema personal de conocimiento local-first para Codex. Convierte las sesiones de rollout locales en un archivo de conversaciones buscable, hechos duraderos, un grafo de conocimiento basado en ontología y un contexto acotado que Codex puede reutilizar en trabajos posteriores.

한국어 README · Documentación · Instalación y operaciones · Arquitectura · Esquema

Memex es un proyecto independiente nativo de Codex derivado del jung-wan-kim/memory-bank con licencia MIT, que a su vez desciende de obra/episodic-memory. Conserva las capacidades del sistema de conocimiento, no el código de compatibilidad con Claude Code. Consulte linaje y migración.

¿Por qué 0.1.0?

0.1.0 es la primera versión pública adecuada. El conjunto de funciones es sustancial y está probado, pero el repositorio es recientemente independiente y sus contratos de marketplace de Codex, adaptador de host e instalación pueden cambiar antes de una 1.0.0 estable. La versión 1.0.0 significará que esos contratos públicos son intencionadamente estables, no simplemente que existen muchas funciones.

Related MCP server: codex-memory-mcp

Características

• Búsqueda semántica, FTS5/BM25 e híbrida sobre el historial de conversaciones de Codex

• Análisis determinista del historial completo sin una llamada a un LLM

• Extracción incremental de hechos, umbrales de confianza, consolidación, revisiones y procedencia

• Ontología de dominio/categoría y relaciones tipadas en el grafo de conocimiento

• Aislamiento de ámbito por proyecto, global y de todos los proyectos solicitado explícitamente

• Recorrido de grafo de 1 a 3 saltos e información transversal entre proyectos

• Inyección de contexto RAG acotada con relevancia y deduplicación por sesión

• Lecturas acotadas y transparentes para archivos comprimidos .jsonl.zst

• Nueve herramientas MCP para conversaciones, hechos, ontología, grafo y procedencia

• Tres habilidades de Codex para flujos de trabajo de recuperación, análisis de historial y panel de control

• Interfaz web solo de loopback con hechos, salud de la canalización y una galaxia de conocimiento 3D

• Ganchos SessionStart, UserPromptSubmit y SessionEnd nativos de Codex

Arquitectura de un vistazo

flowchart LR
    R[Codex rollout JSONL] --> S[Sync and parser]
    S --> A[Immutable local archive]
    S --> C[(Conversation index)]
    C --> X[Incremental fact extraction]
    X --> F[(Facts and revisions)]
    F --> O[(Ontology and typed relations)]
    C --> Q[Hybrid retrieval]
    F --> Q
    O --> Q
    Q --> M[MCP tools and skills]
    Q --> H[Prompt context hook]
    C --> UI[Loopback Web UI]
    F --> UI
    O --> UI

Los rollouts de origen son de solo lectura. Los archivos, los índices SQLite/FTS/vectoriales, los hechos y los datos del grafo son estado local derivado. El trabajo respaldado por modelos se ejecuta a través de un codex exec local efímero y aislado; no hay respaldo de Claude ni un proveedor de claves API independiente.

Para conocer los mecanismos detallados, consulte:

• Arquitectura del sistema

• Ciclo de vida de la conversación

• Ciclo de vida de los hechos

• Grafo de conocimiento

• Recuperación e inyección de contexto

• MCP y habilidades

• Interfaz web y visualización 3D

Requisitos

• Node.js 22.15 o superior

• Una CLI de Codex autenticada

• macOS o Linux para el gancho actual y el runtime de socket Unix

El plugin usa el lanzador npx incluido con Node para resolver el runtime más reciente desde BongSuCHOI/memex#main en la caché aislada de npm. No clona ni compila en su proyecto, no instala un paquete global ni escribe dependencias en la caché de plugins de Codex.

Instalación recomendada

Instale directamente desde el repositorio público:

codex plugin marketplace add BongSuCHOI/memex
codex plugin add memex@memex

Esa es la instalación completa para el usuario. Instala el manifiesto del plugin, tres habilidades, la declaración MCP, los ganchos del ciclo de vida, el lanzador CLI y el lanzador de la interfaz web. La primera llamada en tiempo de ejecución puede tardar más mientras npx llena su caché con dependencias nativas de SQLite, vectoriales y de embeddings.

Flujo de marketplace manual existente

El diseño de marketplace externo sigue siendo compatible para desarrollo y pruebas sin conexión o locales:

memex-local-marketplace/
├── .agents/plugins/marketplace.json
└── plugins/memex -> /absolute/path/to/memex

Apunte su entrada a ./plugins/memex, regístrelo con codex plugin marketplace add /absolute/path/memex-local-marketplace, instale memex@<marketplace-name>. El instalador de origen sigue disponible para la validación de desarrollo local. El JSON completo y el comportamiento de reversión se mantienen en la guía de operaciones.

Configuración inicial

Después de la instalación, reinicie Codex para que el servidor MCP recién instalado, las habilidades y los ganchos gestionados por el plugin se carguen en una sesión nueva. Las funciones dentro de la sesión (búsqueda de conversaciones, extracción/inyección de hechos, herramientas MCP) funcionan entonces sin configuración adicional. Para usar la CLI memex directamente en su terminal, tenga en cuenta que el registro del plugin por sí solo no coloca un binario memex en su PATH — ejecute esto una vez para instalar un shim permanente (nunca una instalación global; se comprueba y se informa del PATH):

npx --yes --package=github:BongSuCHOI/memex#main memex setup --install-cli

Eso crea ~/.local/bin/memex, que usará para la configuración única del corpus:

memex setup
memex sync
memex backfill all
memex status

memex setup comprueba la función memories efectiva de Codex. Cuando la memoria integrada está habilitada, Memex explica el riesgo de doble memoria o memoria conflictiva y recomienda deshabilitarla. Los terminales interactivos piden confirmación; la automatización y los shells no interactivos nunca cambian el ajuste sin la bandera de aprobación explícita memex setup --disable-codex-memory. El cambio usa el propio comando codex features disable memories de Codex y se verifica después.

Qué hace cada etapa:

1. sync lee las sesiones existentes en $CODEX_HOME/sessions, archiva nuevos rollouts y crea índices de búsqueda de conversaciones.

2. backfill all ejecuta cada etapa del trabajo pendiente en orden — extract destila hechos duraderos de los intercambios ya indexados, ontology clasifica los hechos y construye la estructura del grafo, y embeddings rellena los vectores semánticos faltantes. Cada etapa se ejecuta en primer plano por defecto, de modo que la finalización es directamente observable; la orquestación se detiene en la primera etapa que falla y es idempotente al volver a ejecutarse.

3. status informa por separado del estado de conversaciones, hechos y grafo.

Los historiales grandes y la extracción local respaldada por modelos pueden tardar varios minutos o más. El modo de primer plano predeterminado informa de la finalización directamente. Si elige --background, «iniciado» no es «terminado»; siga comprobando memex status hasta que los recuentos pendientes alcancen el estado esperado.

La instalación desde marketplace no modifica los rollouts de origen ni los datos derivados antes de este paso de configuración. sync es idempotente y seguro de repetir.

Uso diario

memex sync
memex search "why did we choose SQLite?"
memex search --both "authentication migration"
memex stats
memex analyze --top 30 --out ~/memex-report.md
memex status

Herramientas MCP y habilidades

El plugin expone:

search, read, search_facts, search_ontology, ask_avatar,
trace_fact, explore_graph, cross_project_insights, graph_stats

Las herramientas sensibles al proyecto requieren una ruta de proyecto absoluta canónica o un ámbito global/all explícito. El proceso MCP nunca deduce el ámbito desde su propio cwd. Consulte MCP y habilidades para ver esquemas y ejemplos.

Interfaz web local

npx --yes --package=github:BongSuCHOI/memex#main memex-ui
# http://localhost:3847

Rutas:

• / — conversaciones, proyectos, búsqueda e intercambios

• /facts — hechos, revisiones, procedencia y mutaciones protegidas

• /graph — grafo de conocimiento 3D en vivo con ámbito

• /pipeline — estado de preparación y salud del trabajo pendiente

El servidor solo se vincula a loopback. Consulte visualización.

Actualizaciones

Previsualice, luego actualice la instantánea del marketplace de Git y reinstale el plugin:

memex update --dry-run
memex update

El lanzador en tiempo de ejecución ya sigue la última main; memex update actualiza también la instantánea del marketplace, de modo que las habilidades, los ganchos y los metadatos MCP actualizados se instalan juntos. Reinicie Codex después. Los datos duraderos de Memex se conservan.

Procedencia de la recuperación y seguridad de la autoingesta

Memex registra las recuperaciones de gancho como recibos memex_recall duraderos por evento, claveados por sesión y hash de la indicación humana. Los resultados de recuperación MCP de Memex se clasifican de la misma manera. La procedencia es a nivel de evidencia, no a nivel de turno: las afirmaciones humanas y los resultados permitidos del repositorio local, el historial de Git y la ejecución de pruebas siguen siendo aprendibles incluso junto a una recuperación; los resultados de Memex, la salida de herramientas externas o desconocidas y la síntesis generada por el asistente no lo son. El intercambio completo sigue siendo buscable. Esto evita la amplificación «recuperación → eco del agente → nuevo hecho → recuperación» a la vez que preserva la evolución de hechos respaldada por evidencia.

Desinstalación

Los ganchos gestionados por el plugin desaparecen cuando se elimina el plugin. Si una instalación anterior o manual usó setup-hooks, elimine solo esas entradas con huella antes de borrar el plugin:

npx --yes --package=github:BongSuCHOI/memex#main memex remove-hooks --dry-run
npx --yes --package=github:BongSuCHOI/memex#main memex remove-hooks
codex plugin remove memex@memex --json
codex plugin marketplace remove memex --json

La desinstalación conserva tanto $CODEX_HOME/sessions como los datos derivados de Memex. Para borrar los datos de Memex por completo, ejecute memex home para resolver la raíz de datos exacta y luego elimine ese directorio — nunca toque $CODEX_HOME/sessions. Consulte la guía de operaciones para ver el procedimiento completo de eliminación de datos, incluidas las opciones de restablecimiento parcial.

Datos y privacidad

La raíz de datos derivados predeterminada es ~/.config/memex. Orden de resolución:

1. MEMEX_HOME

2. MEMORY_BANK_HOME (histórica, respetada de solo lectura)

3. MEMORY_BANK_CONFIG_DIR (histórica, respetada de solo lectura)

4. $XDG_CONFIG_HOME/memex

5. ~/.config/memex

Las instalaciones anteriores a v0.2 que aún conservan datos bajo el espacio de nombres histórico memory-bank se migran explícitamente con memex migrate-home (copiar → verificar → completar con éxito; el directorio de origen nunca se elimina). El nombre es compatibilidad de almacenamiento histórica, no un adaptador de runtime de Claude. Consulte esquema y límites de seguridad.

Verificación

npm run typecheck
npm run build
npm test
npm run test:marketplace
npm run test:package
node --test test/codex-slice.test.mjs
node --test test/*slice.test.mjs
node scripts/validate-plugin.mjs

Codex CLI 0.149.1 no expone codex plugin validate; el repositorio registra ese límite de versión y ejecuta en su lugar un sustituto aislado del artefacto instalado. Los recibos actuales y los límites restantes se documentan en verificación.

Contribuciones

Clone y compile solo para desarrollo o contribución:

git clone https://github.com/BongSuCHOI/memex.git
cd memex
npm ci
npm run build
npm test

Lea AGENTS.md para conocer los invariantes del producto, los límites de propiedad y las comprobaciones requeridas. Cuando cambie el comportamiento, actualice el documento propietario identificado en el mapa de documentación en el mismo cambio.

Licencia

MIT. La atribución ascendente y los avisos de terceros se encuentran en docs/LINEAGE.md y THIRD_PARTY_NOTICES.md.