Anki Card Manager (acm)

Capa local entre Claude y Anki. Vos creás tarjetas conversando con Claude; acm las deduplica (entre todos los mazos, por similitud semántica), clasifica, rutea y sube a Anki — sin copiar/pegar ni organizar a mano.

Es un connector MCP (lo usa Claude como herramienta) y también un CLI. Todo corre local: embeddings, dedup y clasificación con Ollama; tu material no sale de tu máquina.

---

Qué hace

El flujo que automatiza es crear → revisar → subir:

1. Claude propone tarjetas y llama a acm_annotate. Cada tarjeta vuelve anotada (sin subir nada): ¿es duplicada y de cuál?, mazo sugerido, tags, confianza, flags de calidad. Mostrás una lista ya deduplicada y clasificada.
2. Aprobás las que van → se persisten en una cola con estado.
3. acm_sync las inserta en Anki vía AnkiConnect, ruteadas y taggeadas. Se elimina el copy-paste.

Principios: no destructivo (nunca borra/fusiona sin tu OK), economía de tokens (resuelve local y solo escala a Claude el caso difícil), cualquier materia (cero lógica de dominio en el código; la taxonomía vive en config).

El motor de deduplicación

Usa embeddings como recuperador kNN (coseno) sobre toda la colección, con atajo exacto por huella. Captura paráfrasis sin solape de palabras —incluso cross-lingual ES↔EN— que un motor léxico se perdería. Si Ollama no está disponible, degrada con gracia a una capa léxica y lo reporta (embeddings_used: false). Ver SPIKE_EMBEDDINGS.md para la elección de modelo y la calibración.

La escalera de clasificación (barata → cara)

determinista (taxonomía/keywords en config) → propagación por kNN (vecinos ya etiquetados) → LLM local (Ollama, opcional) → Claude (solo el residuo). Solo se auto-aplican tags con alta confianza; lo ambiguo se marca para vos.

---

Requisitos

• Python ≥ 3.11
• Ollama con el modelo de embeddings:

  ollama pull qwen3-embedding:0.6b
  # opcional, para el fallback de clasificación con LLM local:
  ollama pull qwen2.5:0.5b-instruct   # o uno más capaz, p.ej. qwen2.5:7b-instruct
  

• Anki con el addon AnkiConnect (solo para subir/auditar; el resto funciona offline).

Instalación

# con uv (recomendado)
uv venv && uv pip install -e .

# o con pip
python -m venv .venv && .venv/bin/pip install -e .

Esto instala los comandos acm (CLI) y acm-mcp (servidor MCP).

Datos y configuración (ACM_HOME)

El registro, índices, colas y backups viven en ACM_HOME (env var, default ~/.acm). Es una ruta absoluta independiente del cwd, así Claude puede lanzar el MCP desde cualquier directorio sin partir el registro.

La config está en config/settings.yaml (modelo de embeddings, umbrales, perfiles, reglas de dominio data-driven) y la taxonomía en config/taxonomy.yaml.

---

Uso

Como connector MCP en Claude

Agregá el servidor a tu configuración de Claude (Desktop/Code), por ejemplo:

{
  "mcpServers": {
    "anki-card-manager": { "command": "acm-mcp" }
  }
}

Tools expuestas (13):

Tool	Qué hace
acm_annotate	Anota candidatas (dup/mazo/tags/calidad) sin subir. El punto de entrada.
acm_ingest	Persiste un lote (clasifica + dedup + encola).
acm_resolve	Resuelve la cola con una acción: approve / reject / correct.
acm_review	Lista la cola de revisión (dups + ambiguas) con su estado.
acm_sync	Sube las aprobadas a Anki (idempotente; dry_run, fallback TSV).
acm_undo	Deshace un lote de sync (borra esas notas + revierte estado).
acm_audit	Audita un mazo: mode=duplicates|recent|untagged|suggest_taxonomy|maintenance.
acm_reorganize	Reorganización masiva one-shot (dry-run + backup previo).
acm_find_similar_card	Busca similares a un front/back dado.
acm_apply_tags	Aplica tags a notas nuevas o existentes (por note_id).
acm_auto_classify	Clasificación determinista token-eficiente (sin LLM).
acm_taxonomy	Consulta/edita la taxonomía: action=show|add.
acm_stats	Estadísticas + métricas de observabilidad + lotes deshacibles.

Como CLI

acm ingest cards.json            # procesa un archivo de tarjetas
acm review                       # ve la cola de revisión
acm approve <id>  /  acm reject <id>
acm sync                         # sube las aprobadas (--export-tsv como fallback)
acm audit-duplicates --deck "Cloud Certs"
acm similar --front "¿Qué es un CDN?"
acm taxonomy show

---

Estados de una tarjeta

propuesta (anotada, sin persistir) → en-revisión (duplicado posible o tags ambiguos) → aprobada (lista para subir) → subida (en Anki) · descartada.

Las aprobadas son la cola offline: si Anki está cerrado, esperan y suben al reconectar (o se exportan a TSV).

---

Desarrollo

# tests (corren sin Ollama: degradan a léxico)
.venv/bin/python -m pytest -q

# validación del motor de embeddings (elección de modelo + calibración)
PYTHONPATH=. .venv/bin/python scripts/spike_knn.py

# validación end-to-end sobre tu colección real
PYTHONPATH=. .venv/bin/python scripts/validate_real.py

Arquitectura: la lógica de negocio vive en acm/pipeline/ (motor de similitud, clasificación, calidad, propagación, LLM) y acm/service.py (sync, cola, undo, backup). acm/mcp_server.py y acm/cli.py son adaptadores finos. acm/store/registry.py es el SQLite (registro + índice + cache de embeddings).