memex-mcp

memex — memória de grafo temporal para agentes de codificação de IA

Memória persistente e contexto de código para agentes de codificação de IA, servidos via MCP. Um grafo de conhecimento bitemporal do seu repositório — módulos, símbolos, decisões, problemas — para Claude Code, Cursor, Codex, Gemini CLI e qualquer agente compatível com MCP.

Um daemon e servidor MCP que transforma cada commit e cada alteração de arquivo em estado de grafo estruturado: módulos, símbolos, decisões, problemas, fatos de lockfile. Sessões param de começar às cegas. Agentes param de redescobrir o mesmo refactor toda vez que você /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

Instalação

Via marketplace do Claude Code

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

Reinicie sua sessão do 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 .

Implantação de equipe auto-hospedada

Para uma configuração de equipe compartilhada (um Neo4j + um memex-server, autenticação ativada por padrão, portas do Neo4j nunca expostas ao host):

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

Veja docker/TEAM-DEPLOY.md para o fluxo completo, capturando a chave de administrador inicial e a armadilha down -v a evitar.

De relance

O 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

Ferramentas MCP

14 ferramentas — oito de leitura, quatro de escrita, duas analíticas.

Leitura

Escrita

Confiança bitemporal

A confiança não é um número armazenado que muda. Ela é calculada no momento da consulta a partir de base_confidence, status de validação, tempo desde o último reforço e contagem de acessos.

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

Clusters hierárquicos

memex cluster executa Leiden hierárquico sobre um grafo de arestas híbrido:

Meça suas economias

O memex rastreia métricas de redução de tokens e ações de revisão humana localmente em um banco de dados SQLite (~/.config/memex/telemetry.db).

Você pode consultar suas economias a qualquer momento usando a CLI:

memex stats

Ou visualizar o payload JSON bruto:

memex stats --json

Ou direcionar um escopo específico de repositório:

memex stats --repo /path/to/repo

Isso retorna uma agregação de:

• Resumos de período: Chamadas, tokens retornados, tokens ingênuos (tamanho dos arquivos solicitados), tokens economizados e porcentagem de redução de tokens em today, last 7 days, last 30 days e lifetime.
• Principais ferramentas: As ferramentas mais valiosas ordenadas por total de tokens economizados.
• Clientes de agente: Agentes ativos (Claude Code, Gemini CLI, Cursor, Codex) e sua distribuição de economia de tokens.
• Saúde de validação: Total de nós validados, não validados e corroborados, juntamente com os dias decorridos desde a última revisão.

As mesmas estatísticas são expostas via transporte HTTP MCP:

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

Conecte seu 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])

Princípios operacionais

Quando usar o memex

Estrutura do projeto

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

Licença

MIT. Veja LICENSE.

Autor

Hill Patel (@STiFLeR7)

Principais contribuidores e mantenedores

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

Contribuindo

Abra uma issue ou PR. uv sync --all-extras && uv run pytest tests/ é toda a configuração que você precisa para executar a suíte. Bumps de versão devem atualizar ambos pyproject.toml e npm/package.json e eles devem concordar.

Vannevar Bush, 1945: "Considere um dispositivo futuro para uso individual, que é uma espécie de arquivo e biblioteca privada mecanizada. Ele precisa de um nome, e para cunhar um aleatoriamente, memex servirá."