# mcp-memoria

> MCP server: capa unificada de memoria para agentes IA de desarrollo.

Un solo endpoint MCP que expone **13 tools** combinando:
- **codebase-memory-mcp** — grafo de código (search, trace, query, detect)
- **Engram** — memoria episódica persistente (save, search, context)
- **orient** — briefing warm-start (V3Code-inspired)
- **AI-CONTEXT.md** — snapshot destilado de arquitectura

## Compatibilidad

Cualquier herramienta que hable MCP:
- OpenCode
- Claude Code
- Codex CLI
- Cursor
- Aider
- Gemini CLI
- KiloCode
- Kiro

## Instalación

```bash
npm install -g mcp-memoria
```

## Uso

### Como MCP server (stdio)

```bash
# OpenCode — agregar a opencode.json:
{
  "mcp": {
    "mcp-memoria": {
      "enabled": true,
      "type": "local",
      "command": ["mcp-memoria"]
    }
  }
}
```

### CLI directo

```bash
mcp-memoria --tool=orient     # Briefing warm-start
mcp-memoria --tool=ai_context  # Leer AI-CONTEXT.md
```

## Tools

| Tool | Fuente | Descripción |
|------|--------|-------------|
| `orient` | scripts/orient.sh | Briefing warm-start: posición, paridad, grafo, distillate, memoria |
| `ai_context` | AI-CONTEXT.md | Snapshot destilado: rutas API, hotspots, tablas BD, apps |
| `code_search` | codebase-memory | Búsqueda BM25/semántica en grafo de código |
| `code_trace` | codebase-memory | Trazado de llamadas (callers/callees/impacto) |
| `code_graph_query` | codebase-memory | Queries Cypher sobre el grafo |
| `code_read` | codebase-memory | Leer código fuente de una función/símbolo |
| `code_changes` | codebase-memory | Detectar cambios recientes y su impacto |
| `code_architecture` | codebase-memory | Overview de arquitectura (packages, clusters) |
| `mem_save` | Engram | Guardar observación persistente |
| `mem_search` | Engram | Buscar en memoria persistente |
| `mem_context` | Engram | Contexto reciente de sesiones anteriores |
| `mem_stats` | Engram | Estadísticas del sistema de memoria |
| `mem_reindex` | Ambos | Re-indexar grafo + regenerar AI-CONTEXT.md |

## Detección automática de proyecto

El server auto-detecta la raíz del proyecto buscando:
1. CLI arg `--project-root=/path`
2. Env var `PROJECT_ROOT`
3. Walk-up desde cwd buscando `AGENTS.md`, `docker-compose.yml`, `turbo.json`
4. Paths conocidos (`/config/ERP-DOCKER-STACK`)

## Licencia

MIT