memex-mcp

memex — contexto de ingeniería confiable para ingeniería de software agéntica

Una capa de contexto de ingeniería neutral al protocolo para agentes de codificación de IA. memex construye un grafo de conocimiento bitemporal de tu repositorio — módulos, símbolos, decisiones, problemas, evidencia y evolución del código — y expone contexto acotado y consciente de procedencia a través de Hermes MemoryProvider o MCP.

Un daemon y servidor MCP que convierte commits y cambios de archivos en conocimiento de ingeniería estructurado. Los agentes pueden recibir contexto relevante del repositorio antes de una tarea, con frescura y procedencia preservadas, sin convertir a memex en una fuente de memoria personal o estado de sesión crudo.

flowchart LR
    A[Your repository<br/>files + git] --> B[memex watcher<br/>tree-sitter + Gemini]
    B --> C[Neo4j graph<br/>bitemporal facts]
    C --> D[memex core<br/>ContextPacket selection]
    D --> E[Hermes MemoryProvider<br/>automatic read-only prefetch]
    D --> F[MCP fallback<br/>explicit lookup]
    E --> G[AI coding agent]
    F --> G

    style B fill:#cfe8ff,stroke:#0066cc,color:#000
    style C fill:#fff4cf,stroke:#cc9900,color:#000
    style E fill:#d4f5d4,stroke:#2d8f2d,color:#000

Instalación

Vía el marketplace de Claude Code

/plugin marketplace add STiFLeR7/claude-plugins
/plugin install memex-mcp@stifler-marketplace

Reinicia tu sesión de Claude Code.

Manual

docker compose -f docker/docker-compose.yml up -d
cat > .env <<EOF
NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=memex-local
GEMINI_API_KEY=your-key-here
EOF
npx stifler-memex-mcp init --repo .
npx stifler-memex-mcp watch --repo .
npx stifler-memex-mcp serve --repo .

Integración con Hermes

La integración con Hermes v0.9 es de solo lectura. Hermes retiene memoria personal, estado de sesión crudo y estado de ejecución. memex suministra contexto de ingeniería del repositorio a través de un ContextPacket acotado; no ingiere state.db de Hermes, transcripciones, prompts ni resultados de herramientas.

Agrega el proveedor de memex a la configuración de perfil de Hermes:

memory:
  provider: memex
plugins:
  memex:
    repo_path: /absolute/path/to/repository
    prefetch_timeout_seconds: 7
    max_items: 8
    max_chars: 12000

Si Hermes no está instalado, usa el mismo selector de contexto a través de la herramienta get_engineering_context de MCP. Ambas rutas comparten el núcleo de memex neutral al protocolo y fallan abiertamente cuando la recuperación no está disponible.

Despliegue de equipo autoalojado

Para una configuración de equipo compartida (un Neo4j + un memex-server, autenticación activada por defecto, puertos de Neo4j nunca expuestos al host):

bash docker/bootstrap-team-env.sh
docker compose -f docker/docker-compose.team.yml up -d

Consulta docker/TEAM-DEPLOY.md para el flujo completo, capturando la clave de administrador inicial y el down -v a evitar.

De un vistazo

El ciclo de vida

flowchart TD
    Init[memex init<br/>extract baseline] --> Watch[memex watch<br/>daemon + git hooks]
    Watch -->|commit| Extract[tree-sitter extract<br/>symbols, imports, lockfile]
    Extract --> Synth[Gemini Flash<br/>diff → Decision nodes]
    Synth --> Write[Graphiti add_episode<br/>+ post-hoc bitemporal SET]
    Write --> Decay[Scheduler<br/>nightly confidence decay]
    Decay -->|stale edges| Archive[expired_at = now]

    Serve[memex serve<br/>MCP stdio/HTTP] -.->|reads| Write
    Agent[AI agent] -->|14 MCP tools| Serve
    Serve -->|record_decision / record_problem| Write

    Cluster[memex cluster<br/>Leiden over hybrid edges] -.->|every N commits| Write

    style Init fill:#e8f4ff,color:#000
    style Watch fill:#fff4cf,color:#000
    style Synth fill:#ffe0cc,color:#000
    style Serve fill:#d4f5d4,color:#000

Herramientas MCP

14 herramientas — ocho de lectura, cuatro de escritura, dos analíticas.

Lectura

Escritura

Confianza bitemporal

La confianza no es un número almacenado que muta. Se calcula en tiempo de consulta a partir de base_confidence, estado de validación, tiempo desde el último refuerzo y recuento de accesos.

flowchart LR
    Edge[Edge created<br/>base_confidence] --> Q{Validated by<br/>a human?}
    Q -->|yes| Slow[Slow regime<br/>half-life ~139d]
    Q -->|no| Fast[Fast regime<br/>stale at exactly 30d]
    Slow --> Score[Composite score<br/>conf × recency × rehearsal]
    Fast --> Score
    Score -->|below floor| Stale[get_stale_context surfaces it]
    Score -->|access| Bump[last_reinforced_at updated]
    Bump --> Score

    style Slow fill:#d4f5d4,color:#000
    style Fast fill:#ffd4d4,color:#000

Clústeres jerárquicos

memex cluster ejecuta Leiden jerárquico sobre un grafo de aristas híbrido:

Mide tus ahorros

memex rastrea métricas de reducción de tokens y acciones de revisión humana localmente en una base de datos SQLite (~/.config/memex/telemetry.db).

Puedes consultar tus ahorros en cualquier momento usando la CLI:

memex stats

O ver el payload JSON crudo:

memex stats --json

O apuntar a un alcance de repositorio específico:

memex stats --repo /path/to/repo

Esto devuelve una agregación de:

• Resúmenes de período: Llamadas, tokens devueltos, tokens ingenuos (tamaño de archivos solicitados), tokens ahorrados y porcentaje de reducción de tokens en today, last 7 days, last 30 days y lifetime.
• Herramientas principales: Las herramientas más valiosas ordenadas por tokens totales ahorrados.
• Clientes de agentes: Agentes activos (Claude Code, Gemini CLI, Cursor, Codex) y su distribución de ahorro de tokens.
• Salud de validación: Nodos totales validados, no validados y corroborados, junto con los días transcurridos desde la última revisión.

Las mismas estadísticas se exponen a través del transporte HTTP MCP:

GET /stats?repo=/path/to/repo
Authorization: Bearer <your-key>

Conecta tu agente

{
  "mcpServers": {
    "memex": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "stifler-memex-mcp", "serve", "--repo", "."]
    }
  }
}

{
  "mcpServers": {
    "memex": {
      "command": "npx",
      "args": ["-y", "stifler-memex-mcp", "serve", "--repo", "."]
    }
  }
}

{
  "mcpServers": {
    "memex": {
      "command": "npx",
      "args": ["-y", "stifler-memex-mcp", "serve", "--repo", "."]
    }
  }
}

[mcp_servers.memex]
command = "npx"
args = ["-y", "stifler-memex-mcp", "serve", "--repo", "."]

memex memory-tool serve --repo .                     # in-process
memex memory-tool serve --repo . --transport http    # FastAPI on :7464

from memex.memory_tool import MemexAsyncMemoryTool
memory_tool = MemexAsyncMemoryTool(repo_root=".")
client.beta.messages.run_tools(..., tools=[memory_tool])

Principios operativos

Cuándo usar memex

Estructura del proyecto

memex/
├── memex/
│   ├── extractor/        tree-sitter + lockfile parsers
│   ├── graph/            Neo4j writes, confidence, archive, cluster engine
│   ├── synthesizer/      Gemini Flash → Decision nodes
│   ├── mcp_server/       14 MCP tools (read + write + analytic)
│   ├── memory_tool/      Anthropic memory_20250818 adapter
│   ├── watcher/          daemon + git hooks
│   └── cli.py            init / watch / serve / review / graph / cluster
├── tests/                unit, integration, and objective evaluation suites
├── docker/               Neo4j compose
├── npm/                  npx wrapper (publishes as stifler-memex-mcp)
└── Dockerfile            introspection-only image for MCP directory sandboxes

Comandos

Licencia

MIT. Consulta LICENSE.

Autor

Hill Patel (@STiFLeR7)

Contribuyentes principales y mantenedores

• Hill Patel (@STiFLeR7) — arquitecto, mantenedor
• Nirvaan Lagishetty (@Nirvaan05) — contribuyente principal, mantenedor

Contribuciones

Abre un issue o PR. uv sync --all-extras instala el toolchain de desarrollo. Ejecuta uv run pytest -m "not integration" para la suite sin conexión y uv run ruff check . before opening a PR. Version bumps must update pyproject.toml, npm/package.json, server.json y la etiqueta de imagen Docker del equipo juntos.

El registro de la versión v0.9 está en CHANGELOG.md, con la arquitectura y la evidencia de evaluación bajo docs/architecture/v0.9/.

Vannevar Bush, 1945: "Considera un dispositivo futuro para uso individual, que es una especie de archivo y biblioteca privada mecanizada. Necesita un nombre, y para acuñar uno al azar, memex servirá."