memex-mcp

memex — memoria de grafo de conocimiento temporal para agentes de codificación de IA

Memoria persistente y contexto del codebase para agentes de codificación de IA, servidos a través de MCP. Un grafo de conocimiento bitemporal de tu repositorio — módulos, símbolos, decisiones, problemas — para Claude Code, Cursor, Codex, Gemini CLI, y cualquier agente compatible con MCP.

Un demonio y servidor MCP que convierte cada commit y cada cambio de archivo en estado de grafo estructurado: módulos, símbolos, decisiones, problemas, hechos de lockfile. Las sesiones dejan de empezar a ciegas. Los agentes dejan de redescubrir la misma refactorización cada vez que /clear.

flowchart LR
    A[Your repository<br/>files + git] --> B[memex watcher<br/>tree-sitter + Gemini]
    B --> C[Neo4j graph<br/>bitemporal facts]
    C --> D[MCP server<br/>stdio / HTTP]
    D --> E[AI agent<br/>Claude · Cursor · Codex · Gemini CLI]
    E -.->|writes decisions back| C

    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

A través del 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 .

Despliegue de equipo autogestionado

Para una configuración de equipo compartido (un Neo4j + un servidor memex, autenticación activada por defecto, los 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 la down -v trampa 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 contador 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 a través de today, last 7 days, last 30 days y lifetime.
• Mejores herramientas: las herramientas más valiosas ordenadas por total de tokens ahorrados.
• Clientes de agentes: agentes activos (Claude Code, Gemini CLI, Cursor, Codex) y su distribución de ahorro de tokens.
• Salud de validación: total de nodos 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/                333 passing, ~93% coverage
├── 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)

Contribuidores principales y mantenedores

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

Contribuir

Abre un issue o un PR. uv sync --all-extras && uv run pytest tests/ es toda la configuración que necesitas para ejecutar la suite. Los incrementos de versión deben actualizar ambos pyproject.toml y npm/package.json y deben coincidir.

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