memex-mcp

memex — contexto de engenharia confiável para engenharia de software agêntica

Uma camada de contexto de engenharia neutra em protocolo para agentes de codificação de IA. memex constrói um grafo de conhecimento bitemporal do seu repositório — módulos, símbolos, decisões, problemas, evidências e evolução de código — e expõe contexto limitado, com consciência de proveniência através do Hermes MemoryProvider ou MCP.

Um daemon e servidor MCP que transforma commits e alterações de arquivos em conhecimento de engenharia estruturado. Agentes podem receber contexto relevante do repositório antes de uma tarefa, com frescor e proveniência preservados, sem tornar o memex uma fonte de memória pessoal ou estado bruto de sessão.

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

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 .

Integração com Hermes

A integração Hermes v0.9 é somente leitura. Hermes retém memória pessoal, estado bruto de sessão e estado de execução. memex fornece contexto de engenharia do repositório através de um ContextPacket limitado; ele não ingere state.db do Hermes, transcrições, prompts ou resultados de ferramentas.

Adicione o provedor memex à configuração de perfil do Hermes:

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

Se o Hermes não estiver instalado, use o mesmo seletor de contexto através da ferramenta get_engineering_context do MCP. Ambos os caminhos compartilham o núcleo memex neutro em protocolo e falham abertamente quando a recuperação não está disponível.

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 o problema 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

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

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 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/                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

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 instala o toolchain de desenvolvimento. Execute uv run pytest -m "not integration" para a suíte offline e uv run ruff check . before opening a PR. Version bumps must update pyproject.toml, npm/package.json, server.json e a tag da imagem Docker da equipe juntos.

O registro da versão v0.9 está em CHANGELOG.md, com a arquitetura e evidências de avaliação sob docs/architecture/v0.9/.

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á."