ImprintMCP

Memória Vetorial MCP com Atualização Automática

Documentação

Imprint

Memória persistente para ferramentas de codificação com IA. 100% local. Custo zero de API.

Dê ao Claude Code, Cursor, Codex CLI, Copilot e Cline uma memória de longo prazo.
Pare de reexplicar sua base de código a cada sessão.

imprintmcp.alexandruleca.com →

Imprint UI

Por que Imprint

Lembra o que sua IA esquece. Decisões, padrões, correções de bugs e escolhas arquiteturais persistem entre sessões — pesquisados semanticamente, não por grep.
−70,4% de tokens, −31,7% de custo. Medido em 150 execuções no Claude Code (Sonnet). Sua IA pesquisa a memória em vez de reler arquivos. Veja BENCHMARK.md para os números brutos.
Funciona 100% localmente por padrão. EmbeddingGemma-300M via ONNX, banco vetorial Qdrant, chunking Chonkie — tudo na sua máquina. Nenhum crédito de API é consumido, a menos que você opte por isso.
Um comando, qualquer host. Integra-se ao Claude Code, Cursor, Codex CLI, Copilot ou Cline via MCP. A mesma memória, compartilhada entre ferramentas.

Funciona 100% localmente. Zero créditos de API consumidos por padrão. Tudo, desde embeddings, chunking, marcação, busca vetorial e o grafo de conhecimento — roda na sua máquina:

Embeddings: EmbeddingGemma-300M via ONNX Runtime (GPU ou CPU), sem chamadas de rede, sem custo por token.
Armazenamento vetorial: Qdrant iniciado automaticamente como um daemon local em 127.0.0.1:6333. Seus dados nunca saem da máquina, a menos que você os sincronize com outro dispositivo.
Chunking: Chonkie híbrido (tree-sitter CodeChunker + SemanticChunker), Python puro, local.
Marcação: regras determinísticas + similaridade de cosseno zero-shot contra rótulos pré-incorporados. Chamada LLM local por chunk, se você quiser.
Grafo Imprint: SQLite em disco para fatos temporais.

O fluxo de ingestão: escanear diretório → detectar projeto → dividir arquivos em chunks → incorporar chunks → marcar (linguagem/camada/tipo/domínio/tópicos) → upsert no Qdrant. Um hook Stop extrai automaticamente decisões de transcrições do Claude; um hook PreCompact salva o contexto antes da compressão da janela. A busca vai direto ao banco vetorial local — sem ida e volta a nenhum provedor.

Marcação opcional com LLM em nuvem é somente opt-in (imprint config set tagger.llm true) se você quiser tópicos mais granulares e não se importar em gastar créditos. Provedores: Anthropic, OpenAI, Gemini ou Ollama/vLLM totalmente locais. Deixe desativado e nada nunca falará com uma API paga.

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

Instalação 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

Fixar uma versão específica, escolher o canal de desenvolvimento ou usar imagens Docker pré-construídas — veja docs/installation.md.

Atualização

Depois de instalado, use o atualizador integrado — sem curl, sem sudo. data/ (workspaces, armazenamento Qdrant, grafos SQLite, configuração, gpu_state.json) e .venv/ são sempre preservados; apenas a árvore de código é substituída.

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)

Reexecutar install.sh também funciona e agora pergunta antes de sobrescrever uma instalação existente. Para atualizações não interativas, passe --yes ou defina IMPRINT_ASSUME_YES=1.

Se a configuração de GPU falhar uma vez (por exemplo, Blackwell + nvcc antigo ou incompatibilidade de runtime CUDA), a falha é lembrada em data/gpu_state.json para que futuras execuções de imprint setup ignorem o caminho quebrado silenciosamente. Depois de atualizar o toolchain, force uma nova tentativa com:

imprint setup --retry-gpu

Hosts suportados

imprint setup <target> conecta automaticamente o servidor MCP a cada ferramenta de codificação com IA suportada. Execute imprint setup all para configurar todos os hosts instalados na sua máquina; ferramentas ausentes são ignoradas com um aviso, não um erro.

Alvo	Conectado em	Arquivo de configuração	Aplicação
`claude-code`	Claude Code CLI (MCP + hooks + `CLAUDE.md` global)	`~/.claude/settings.json` + MCP registrado via `claude mcp add`	Rígida (PreToolUse)
`cursor`	Cursor IDE (MCP + regra sempre ativa)	`~/.cursor/mcp.json` + `~/.cursor/rules/imprint.mdc`	Somente texto (regra)
`codex`	OpenAI Codex CLI	`~/.codex/config.toml` (`[mcp_servers.imprint]`)	Somente texto
`copilot`	GitHub Copilot (modo agente VSCode), global do usuário	`<VSCode user>/mcp.json` (`servers.imprint`)	Somente texto
`cline`	Cline — extensão VSCode + CLI independente	`<VSCode user>/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json` e/ou `~/.cline/data/settings/cline_mcp_settings.json`	Somente texto

imprint disable é simétrico — ele remove a entrada MCP de cada arquivo de configuração acima que ainda existir (o venv e os dados são sempre preservados para que a reativação seja rápida).

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

Documentação

Tópico	Arquivo
Instalação, versionamento, canais, Docker	docs/installation.md
Componentes, fluxo de dados, daemon Qdrant, ciclo de vida	docs/architecture.md
Pipeline de embeddings + aceleração de GPU	docs/embeddings.md
Estratégia de chunking + ajustes	docs/chunking.md
Tags de metadados, provedores LLM, filtros de busca	docs/tagging.md
Workspaces + detecção de projetos	docs/workspaces.md
Ferramentas MCP + atualizações automáticas	docs/mcp.md
Sincronização entre pares, servidor relay, painel	docs/sync.md
Fila de comandos + cancelamento	docs/queue.md
Todas as configurações (`imprint config`)	docs/configuration.md
Compilação a partir do código-fonte + fluxo CI/release	docs/building.md
Benchmarks e economia de tokens	BENCHMARK.md

Glossário

Termos usados em toda a documentação.

Termo	Definição
Chunk	Uma unidade de texto sub-arquivo (uma função, classe, seção de markdown, turno de conversa) que recebe seu próprio vetor de embedding. Produzido pelo chunker.
Embedding	Vetor numérico denso (padrão 768-dimensões) que representa o significado semântico de um chunk. Significados semelhantes → vetores próximos.
Qdrant	O banco de dados vetorial que armazena embeddings + payloads. Executa como um daemon local iniciado automaticamente em `127.0.0.1:6333`.
Coleção	Termo do Qdrant para um conjunto nomeado de vetores. Cada workspace tem sua própria coleção (por exemplo, `memories`, `memories_research`).
Workspace	Ambiente de memória isolado — coleção Qdrant dedicada + banco SQLite + WAL. Permite separar memórias de pesquisa/staging/produção.
Grafo Imprint	Armazenamento de fatos temporais (SQLite) para fatos estruturados `subject → predicate → object` com carimbos de data/hora `valid_from` / `ended`.
MCP	Model Context Protocol — o protocolo aberto que o Claude Code usa para chamar ferramentas externas. O Imprint inclui um servidor MCP com 12 ferramentas — veja docs/mcp.md.
Projeto	Uma base de código identificada por um nome canônico a partir de seu manifesto (`package.json`, `go.mod`, etc.). Projetos recebem a mesma identidade entre máquinas, mesmo que os caminhos difiram.
Camada	Tag derivada do caminho: `api`, `ui`, `tests`, `infra`, `config`, `migrations`, `docs`, `scripts`, `cli`.
Tipo	Tag derivada do nome do arquivo: `source`, `test`, `migration`, `readme`, `types`, `module`, `qa`, `auto-extract`.
Domínio	Tag derivada do conteúdo por regex de palavras-chave: `auth`, `db`, `api`, `math`, `rendering`, `ui`, `testing`, `infra`, `ml`, `perf`, `security`, `build`, `payments`.
Tópicos	Tags de forma livre de similaridade de cosseno zero-shot ou (opt-in) classificação por LLM — mais granulares que `domain`.
Ingestão	Escanear um diretório, detectar projetos, dividir arquivos em chunks, incorporar chunks, marcar e fazer upsert no Qdrant.
Atualização	Re-ingestão incremental — apenas redivide e reincorpora arquivos cujo mtime mudou desde a última execução.
Fila	FIFO de slot único (`data/queue.sqlite3` + `data/queue.lock`) que serializa ingest/refresh/retag/ingest-url para que execuções paralelas não estourem a memória da máquina. A interface em `/queue` lista ativos + enfileirados + histórico; o cancelamento propaga SIGTERM→SIGKILL ao grupo de processos do subprocesso, então chamadas de marcação LLM em andamento morrem junto. Veja docs/queue.md.
Auto-extração	Hook Stop que analisa transcrições de conversa após cada resposta do Claude e armazena trocas de Q+A + declarações semelhantes a decisões.
Hook PreCompact	Hook síncrono que dispara antes da compressão da janela de contexto do Claude — instrui o Claude a salvar contexto importante via ferramentas MCP primeiro.
Servidor relay	Encaminhador WebSocket sem estado (`imprint relay`) que intermedia a sincronização entre pares entre duas máquinas. Nenhum vetor cruza a rede — apenas conteúdo bruto, reincorporado localmente no receptor.
WAL	Write-ahead log — `wal.jsonl` somente anexação por workspace, usado para replay/recuperação de operações de memória.
Marcação zero-shot	Classificar chunks por similaridade de cosseno contra protótipos de rótulos pré-incorporados — sem chamada LLM por chunk.
Canal dev / estável	Duas trilhas de release. Dev = pré-lançamento a cada push `dev` (`vX.Y.Z-dev.N`). Estável = release de commit convencional em merges `main` (`vX.Y.Z`).

Benchmarks

O Imprint reduz o consumo de tokens do Claude Code ao fornecer resultados de busca semântica focados em vez de exigir leituras completas de arquivos. Medido em 15 prompts em 6 categorias, 5 execuções por prompt por modo, modelo principal Sonnet.

Categoria	Prompts	Δ Tokens	Δ Custo	Notas
Depuração	2	−94,2%	−68,3%	O Imprint responde a partir de padrões de modos de falha indexados em vez de ler a base de código
Recuperação entre projetos	2	−90,6%	−46,9%	Padrões que abrangem múltiplos projetos indexados — impossível sem memória
Perguntas e respostas de arquitetura	5	−87,2%	−42,6%	Perguntas como "como funciona o chunking?" respondidas a partir de busca semântica
Recuperação de decisões	2	−78,8%	−46,1%	Perguntas de por-que-fizemos-X respondidas a partir de decisões armazenadas
Tarefas de criação	3	+9,9%	+15,1%	Quase paridade — geração de código ainda precisa do contexto da base de código
Resumo de sessão	1	+179,6%	+204,1%	Valor atípico: prompt único, ON entrou em um surto de exploração de grafo
Geral	15	−70,4% (10,28M → 3,05M)	−31,7% ($2,84 → $1,94)

Os números são medianas por prompt, somadas entre categorias. Veja BENCHMARK.md para tabelas por prompt, detalhamento por modelo, análise de qualidade de resposta e as flags exatas usadas.

Reproduzir: bash benchmark/run.sh (suíte completa, ~$15–25) ou bash benchmark/run.sh --subset (um prompt por categoria, ~$6–10).

Roadmap

Backup automático local
Instância Qdrant externa em vez de banco local
Backup/Sincronização para outro servidor remoto Qdrant
Capacidade de ingestão de documentos (pdf, doc, odt, ...etc)
Capacidade de ingestão de vídeo / áudio
Capacidade de ingestão de URL

Licença

O Imprint é licenciado sob a Apache License 2.0.

Dependências de terceiros mantêm suas próprias licenças — veja THIRD_PARTY_LICENSES.md para a tabela completa. Modelo de incorporação padrão (EmbeddingGemma-300M) é regido pelos Termos de Uso do Gemma e pela Política de Uso Proibido — não Apache 2.0. O Imprint não inclui pesos; eles são baixados em tempo de execução do HuggingFace, onde você aceita os termos do Gemma. Mude para um modelo com licença diferente (por exemplo, BGE-M3, MIT) via imprint config set model.name <repo>.

Contato

Dúvidas, feedback ou relatórios de bugs? Entre em contato: