ImprintMCP

Memoria Vectorial MCP de Autoactualización

Documentación

Imprint

Memoria persistente para herramientas de codificación con IA. 100% local. Coste de API cero.

Dale a Claude Code, Cursor, Codex CLI, Copilot y Cline una memoria a largo plazo.
Deja de re-explicar tu base de código en cada sesión.

imprintmcp.alexandruleca.com →

Imprint UI

Por qué Imprint

Recuerda lo que tu IA olvida. Las decisiones, patrones, correcciones de errores y elecciones arquitectónicas persisten entre sesiones — se buscan semánticamente, no con grep.
−70.4% tokens, −31.7% coste. Medido en 150 ejecuciones en Claude Code (Sonnet). Tu IA busca en la memoria en lugar de releer archivos. Consulta BENCHMARK.md para los números brutos.
Se ejecuta 100% local por defecto. EmbeddingGemma-300M vía ONNX, base de datos vectorial Qdrant, chunking Chonkie — todo en tu máquina. No se consumen créditos de API salvo que lo actives.
Un comando, cualquier host. Se conecta a Claude Code, Cursor, Codex CLI, Copilot o Cline vía MCP. La misma memoria, compartida entre herramientas.

Se ejecuta 100% local. Cero créditos de API consumidos por defecto. Todo, desde embeddings, chunking, etiquetado, búsqueda vectorial y el grafo de conocimiento — se ejecuta en tu máquina:

Embeddings: EmbeddingGemma-300M vía ONNX Runtime (GPU o CPU), sin llamadas de red, sin coste por token.
Almacén vectorial: Qdrant se inicia automáticamente como daemon local en 127.0.0.1:6333. Tus datos nunca salen de la máquina salvo que los sincronices con otro dispositivo.
Chunking: Chonkie híbrido (tree-sitter CodeChunker + SemanticChunker), Python puro, local.
Etiquetado: reglas deterministas + similitud coseno zero-shot contra etiquetas pre-embedidas. Llamada LLM local por chunk si lo deseas.
Grafo Imprint: SQLite en disco para hechos temporales.

El flujo de ingesta: escanear directorio → detectar proyecto → dividir archivos en chunks → embeber chunks → etiquetar (lang/layer/kind/domain/topics) → upsert en Qdrant. Un hook Stop extrae automáticamente decisiones de las transcripciones de Claude; un hook PreCompact guarda el contexto antes de la compresión de la ventana. La búsqueda va directa a la base de datos vectorial local — sin ida y vuelta a ningún proveedor.

El etiquetado LLM en la nube opcional es solo opt-in (imprint config set tagger.llm true) si quieres temas más granulares y no te importa gastar créditos. Proveedores: Anthropic, OpenAI, Gemini, u Ollama / vLLM totalmente local. Déjalo desactivado y nada hablará jamás con una API de pago.

graph TB
    subgraph "Your Machine"
        CC[Claude Code] -->|MCP tools| MCP[Imprint MCP Server]
        MCP -->|HTTP localhost:6333| QDB[(Qdrant Server<br/>auto-spawned daemon)]
        MCP -->|facts| KG[(SQLite<br/>Imprint Graph)]
        CLI[imprint CLI] -->|HTTP| QDB
        CC -->|Stop hook| EXT[Auto-Extract<br/>Decisions]
        CC -->|PreCompact hook| SAVE[Save Before<br/>Compression]
        EXT -->|HTTP| QDB
        EMB[EmbeddingGemma ONNX<br/>GPU/CPU] -->|768-dim vectors| QDB
        TAG[Tagger<br/>lang/layer/kind/domain/topics] -->|payload| QDB
        CHK[Chonkie Hybrid<br/>CodeChunker + SemanticChunker] -->|chunks| EMB
    end

    subgraph "Sync Relay"
        RELAY[imprint relay<br/>WebSocket forwarder]
    end

    subgraph "Other Machine"
        CC2[Claude Code] -->|MCP| MCP2[Imprint MCP]
        MCP2 --> QDB2[(Qdrant Server)]
    end

    CLI -->|sync serve| RELAY
    RELAY -->|sync pull/push| QDB2

    style QDB fill:#1a1a3a,stroke:#60a5fa,color:#fff
    style KG fill:#1a1a3a,stroke:#4ecdc4,color:#fff
    style MCP fill:#0d1117,stroke:#a78bfa,color:#fff
    style RELAY fill:#0d1117,stroke:#ff6b6b,color:#fff
    style EMB fill:#0d1117,stroke:#fbbf24,color:#fff
    style TAG fill:#0d1117,stroke:#34d399,color:#fff
    style CHK fill:#0d1117,stroke:#f472b6,color:#fff

Instalación rápida

Linux / macOS:

curl -fsSL https://raw.githubusercontent.com/alexandruleca/imprint-memory-layer/main/install.sh | bash

Windows (PowerShell):

irm https://raw.githubusercontent.com/alexandruleca/imprint-memory-layer/main/install.ps1 | iex

Fija una versión específica, elige el canal dev, o usa imágenes Docker precompiladas — consulta docs/installation.md.

Actualización

Una vez instalado, usa el actualizador integrado — sin curl, sin sudo. data/ (workspaces, almacenamiento Qdrant, grafos SQLite, configuración, gpu_state.json) y .venv/ siempre se conservan; solo se reemplaza el árbol de código.

imprint update              # latest stable, asks for confirmation
imprint update --dev        # latest prerelease
imprint update --version v0.3.1
imprint update --check      # show current + latest release and exit
imprint update -y           # skip confirmation (CI / scripts)

Volver a ejecutar install.sh también funciona y ahora pregunta antes de sobrescribir una instalación existente. Para actualizaciones no interactivas pasa --yes o establece IMPRINT_ASSUME_YES=1.

Si la configuración de GPU falla una vez (p. ej. Blackwell + nvcc antiguo, o desajuste del runtime CUDA) el fallo se recuerda en data/gpu_state.json para que futuras ejecuciones de imprint setup omitan la ruta rota silenciosamente. Después de actualizar el toolchain, fuerza un reintento con:

imprint setup --retry-gpu

Hosts compatibles

imprint setup <target> conecta automáticamente el servidor MCP en cada herramienta de codificación con IA compatible. Ejecuta imprint setup all para configurar cada host instalado en tu máquina; las herramientas ausentes se omiten con una advertencia, no con un error.

Destino	Conectado a	Archivo de configuración	Aplicación
`claude-code`	Claude Code CLI (MCP + hooks + `CLAUDE.md` global)	`~/.claude/settings.json` + MCP registrado vía `claude mcp add`	Estricta (PreToolUse)
`cursor`	Cursor IDE (MCP + regla siempre activa)	`~/.cursor/mcp.json` + `~/.cursor/rules/imprint.mdc`	Solo texto (regla)
`codex`	OpenAI Codex CLI	`~/.codex/config.toml` (`[mcp_servers.imprint]`)	Solo texto
`copilot`	GitHub Copilot (modo agente VSCode), global de usuario	`<VSCode user>/mcp.json` (`servers.imprint`)	Solo texto
`cline`	Cline — extensión VSCode + CLI independiente	`<VSCode user>/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json` y/o `~/.cline/data/settings/cline_mcp_settings.json`	Solo texto

imprint disable es simétrico — elimina la entrada MCP de cada archivo de configuración anterior que aún exista (el venv y los datos siempre se conservan para que reactivarlo sea rápido).

Comandos

imprint setup [target]     # install deps, register MCP, configure the chosen host tool
                           #   target: claude-code (default) | cursor | codex | copilot | cline | all
                           # add --retry-gpu to forget a sticky GPU failure and retry ORT / llama-cpp CUDA
imprint update [--version v0.3.1] [--dev] [-y] [--check]
                           # upgrade imprint in place; preserves data/ and .venv/
imprint uninstall [-y] [--keep-data]
                           # full removal: disable + strip CLAUDE.md + delete venv/data/install dir
imprint status             # is everything wired? show enabled/disabled, server pid, memory stats
imprint enable [target]    # re-wire MCP + hooks + start server
                           #   target: claude-code | cursor | codex | copilot | cline | all
imprint disable            # stop server, unregister MCP from every host, strip Claude hooks (data preserved)
imprint ingest <path>      # index project source files (directory or single file)
imprint learn              # index Claude Code conversations + memory files
imprint learn --desktop    # also ingest Claude Desktop / ChatGPT Desktop export zips from Downloads
imprint ingest-url <url>   # fetch URL(s), extract content, and index (html/pdf/etc)
imprint refresh <dir>      # re-index only changed files (mtime-based)
imprint refresh-urls       # re-check stored URLs via ETag/Last-Modified and re-index changed
imprint retag [--project] [--all]
                           # re-run the tagger on existing memories (--all re-tags already-tagged chunks)
# Heavy jobs (ingest/refresh/retag/ingest-url/refresh-urls) serialize via a
# shared queue lock. If another job is already running the CLI exits with an
# error — cancel it from /queue in the UI or kill the PID it reports.
imprint migrate --from WS1 --to WS2 --project NAME | --topic TAG [--dry-run]
                           # move memories between workspaces (preserves vectors)
imprint config             # show all settings with current values
imprint config set <k> <v> # persist a setting (e.g. model.name, qdrant.port)
imprint config get <key>   # show one setting with source + default
imprint config reset <key> # remove override, revert to default
imprint server <cmd>       # manage the local Qdrant daemon: start | stop | status | log
imprint workspace          # list workspaces and show active
imprint workspace switch <name>  # switch to workspace (creates if new)
imprint workspace delete <name>  # delete a workspace and its data
imprint wipe [--force]     # wipe active workspace
imprint wipe --all         # wipe everything (all workspaces)
imprint sync serve [--relay <host>]      # expose KB for peer syncing (default: imprint.alexandruleca.com)
imprint sync <id> --pin <pin>            # sync via default relay (or <host>/<id> / wss://<host>/<id>)
imprint sync export | import <dir>       # snapshot bundle, no re-embed on import
imprint relay              # run the sync relay server
imprint ui [start|stop|status|open|restart|log] [--port N]
                           # dashboard (FastAPI + Next.js); bare `imprint ui` runs foreground
imprint version            # print version

Documentación

Tema	Archivo
Instalación, versionado, canales, Docker	docs/installation.md
Componentes, flujo de datos, daemon Qdrant, ciclo de vida	docs/architecture.md
Pipeline de embeddings + aceleración GPU	docs/embeddings.md
Estrategia de chunking + parámetros ajustables	docs/chunking.md
Etiquetas de metadatos, proveedores LLM, filtros de búsqueda	docs/tagging.md
Workspaces + detección de proyectos	docs/workspaces.md
Herramientas MCP + actualizaciones automáticas	docs/mcp.md
Sincronización entre pares, servidor relay, dashboard	docs/sync.md
Cola de comandos + cancelación	docs/queue.md
Todos los ajustes (`imprint config`)	docs/configuration.md
Compilación desde el código fuente + flujo CI/release	docs/building.md
Benchmarks y ahorro de tokens	BENCHMARK.md

Glosario

Términos usados en la documentación.

Término	Definición
Chunk	Una unidad de texto dentro de un archivo (una función, clase, sección markdown, turno de conversación) que recibe su propio vector de embedding. Producido por el chunker.
Embedding	Vector numérico denso (768-dim por defecto) que representa el significado semántico de un chunk. Significados similares → vectores cercanos.
Qdrant	La base de datos vectorial que almacena embeddings + payloads. Se ejecuta como daemon local auto-iniciado en `127.0.0.1:6333`.
Collection	El término de Qdrant para un conjunto nombrado de vectores. Cada workspace tiene su propia collection (p. ej. `memories`, `memories_research`).
Workspace	Entorno de memoria aislado — collection Qdrant dedicada + base de datos SQLite + WAL. Te permite separar memorias de investigación/staging/producción.
Imprint Graph	Almacén de hechos temporales (SQLite) para hechos estructurados `subject → predicate → object` con marcas de tiempo `valid_from` / `ended`.
MCP	Model Context Protocol — el protocolo abierto que Claude Code usa para llamar herramientas externas. Imprint incluye un servidor MCP con 12 herramientas — consulta docs/mcp.md.
Project	Una base de código identificada por un nombre canónico de su manifest (`package.json`, `go.mod`, etc.). Los proyectos obtienen la misma identidad entre máquinas incluso si las rutas difieren.
Layer	Etiqueta derivada de la ruta: `api`, `ui`, `tests`, `infra`, `config`, `migrations`, `docs`, `scripts`, `cli`.
Kind	Etiqueta derivada del nombre de archivo: `source`, `test`, `migration`, `readme`, `types`, `module`, `qa`, `auto-extract`.
Domain	Etiqueta derivada del contenido mediante regex de palabras clave: `auth`, `db`, `api`, `math`, `rendering`, `ui`, `testing`, `infra`, `ml`, `perf`, `security`, `build`, `payments`.
Topics	Etiquetas de formato libre a partir de similitud coseno zero-shot o clasificación LLM (opt-in) — más granulares que `domain`.
Ingestion	Escanear un directorio, detectar proyectos, dividir archivos en chunks, embeber chunks, etiquetar y hacer upsert en Qdrant.
Refresh	Re-ingesta incremental — solo re-divide y re-embebe los archivos cuyo mtime cambió desde la última ejecución.
Queue	FIFO de un solo slot (`data/queue.sqlite3` + `data/queue.lock`) que serializa ingest/refresh/retag/ingest-url para que las ejecuciones paralelas no agoten la memoria de la máquina. La UI en `/queue` lista activos + en cola + historial; cancelar propaga SIGTERM→SIGKILL al grupo de procesos del subproceso, así que las llamadas LLM de etiquetado en curso mueren con él. Consulta docs/queue.md.
Auto-extract	Hook Stop que analiza las transcripciones de conversación tras cada respuesta de Claude y almacena intercambios de preguntas y respuestas + declaraciones tipo decisión.
PreCompact hook	Hook síncrono que se dispara antes de que se comprima la ventana de contexto de Claude — instruye a Claude para que guarde primero el contexto importante mediante las herramientas MCP.
Relay server	Reenviador WebSocket sin estado (`imprint relay`) que media la sincronización entre pares entre dos máquinas. Ningún vector cruza la red — solo contenido bruto, re-embedido localmente en el receptor.
WAL	Write-ahead log — `wal.jsonl` de solo añadido por workspace, usado para reproducción / recuperación de operaciones de memoria.
Zero-shot tagging	Clasificar chunks por similitud coseno contra prototipos de etiquetas pre-embedidos — sin llamada LLM por chunk.
Dev / stable channel	Dos canales de release. Dev = prerelease en cada push de `dev` (`vX.Y.Z-dev.N`). Stable = release conventional-commit en merges de `main` (`vX.Y.Z`).

Benchmarks

Imprint reduce el consumo de tokens de Claude Code al ofrecer resultados de búsqueda semántica enfocados en lugar de requerir lecturas completas de archivos. Medido en 15 prompts en 6 categorías, 5 ejecuciones por prompt por modo, modelo principal Sonnet.

Categoría	Prompts	Δ Tokens	Δ Coste	Notas
Debugging	2	−94.2%	−68.3%	Imprint responde desde patrones indexados de modos de fallo en lugar de leer la base de código
Cross-project recall	2	−90.6%	−46.9%	Patrones que abarcan múltiples proyectos indexados — imposible sin memoria
Architecture Q&A	5	−87.2%	−42.6%	Preguntas como «¿cómo funciona el chunking?» respondidas desde la búsqueda semántica
Decision recall	2	−78.8%	−46.1%	Preguntas de por-qué-hicimos-X respondidas desde decisiones almacenadas
Tareas de creación	3	+9.9%	+15.1%	Casi paridad — la generación de código aún necesita contexto de la base de código
Resumen de sesión	1	+179.6%	+204.1%	Valor atípico: prompt único, ON se lanzó a explorar el grafo
General	15	−70.4% (10.28M → 3.05M)	−31.7% ($2.84 → $1.94)

Los números son la mediana por prompt, sumados entre categorías. Consulta BENCHMARK.md para tablas por prompt, desglose por modelo, análisis de calidad de respuesta y las flags exactas usadas.

Reproduce: bash benchmark/run.sh (suite completa, ~$15–25) o bash benchmark/run.sh --subset (un prompt por categoría, ~$6–10).

Roadmap

Copia de seguridad automática local
Instancia Qdrant externa en lugar de la base de datos local
Copia de seguridad/Sincronización con otro servidor de instancia remota Qdrant
Capacidad de ingesta de documentos (pdf, doc, odt, ...etc)
Capacidad de ingesta de video / audio
Capacidad de ingesta de URLs

Licencia

Imprint está licenciado bajo la Apache License 2.0.

Las dependencias de terceros conservan sus propias licencias — consulta THIRD_PARTY_LICENSES.md para la tabla completa. Modelo de incrustación predeterminado (EmbeddingGemma-300M) se rige por los Términos de uso de Gemma y la Política de uso prohibido — no Apache 2.0. Imprint no incluye pesos; se descargan en tiempo de ejecución desde HuggingFace, donde aceptas los términos de Gemma. Cambia a un modelo con otra licencia (p. ej., BGE-M3, MIT) mediante imprint config set model.name <repo>.

Contacto

¿Preguntas, comentarios o informes de errores? Ponte en contacto: