AHME MCP

---

AHME es un demonio auxiliar local que se sitúa silenciosamente junto a tu asistente de codificación con IA. Mientras trabajas, comprime el historial de tu conversación en un Bloque Maestro de Memoria denso utilizando un modelo local de Ollama — sin nube, sin tokens desperdiciados, sin contexto perdido.

Se integra con cualquier herramienta de IA que soporte MCP (Protocolo de Contexto de Modelo): Antigravity, Claude Code, Kilo Code, Cursor, Windsurf, Cline/Roo, y más.

---

✨ Cómo funciona

Your AI conversation
        │
        ▼  ingest_context
┌───────────────────┐
│   SQLite Queue    │  ← persistent, survives restarts
└────────┬──────────┘
         │  when CPU is idle
         ▼
┌───────────────────┐
│  Ollama Compressor│  ← local model (qwen2:1.5b, gemma3:1b, phi3…)
│  (structured JSON)│
└────────┬──────────┘
         │  recursive tree merge
         ▼
┌───────────────────┐
│ Master Memory Block│ ← dense, token-efficient summary
└────────┬──────────┘
         │
         ├── .ahme_memory.md   (file — for any tool that reads files)
         └── get_master_memory (MCP tool — for integrated tools)

Patrón de reemplazo de ventana de contexto: llamar a get_master_memory devuelve el resumen comprimido, limpia los datos antiguos y vuelve a sembrar el motor con el resumen — de modo que cada nueva conversación comienza desde un punto de control denso, no desde una pizarra en blanco.

---

🚀 Inicio Rápido

Requisitos previos

• Python 3.11+
• Ollama ejecutándose localmente
• Un modelo pequeño descargado: ollama pull qwen2:1.5b (o cualquier modelo de 1–4B)

Instalación

git clone https://github.com/your-username/ahme
cd ahme

# Copy the example config and set your model
cp config.example.toml config.toml

# Install the package
pip install -e .

Configuración

Abre config.toml y establece tu modelo de Ollama:

[ollama]
base_url = "http://localhost:11434"
model = "qwen2:1.5b"   # ← change to any model you have pulled

Esa es la única línea que necesitas cambiar. Todo lo demás está preconfigurado.

---

🔌 Conéctalo a tu herramienta de IA

AHME expone tres herramientas MCP: ingest_context, get_master_memory y clear_context.

Opción A — MCP (recomendado)

Añade AHME a la configuración MCP de tu herramienta. La ubicación exacta del archivo varía según la herramienta:

Herramienta	Ubicación de configuración
Claude Code	bandera --mcp-config .mcp.json, o ~/.claude/mcp.json
Kilo Code	VS Code settings.json → "kilocode.mcp.servers"
Cursor	Configuración → MCP → pegar JSON
Windsurf	~/.windsurf/mcp.json
Cline / Roo	Barra lateral de Servidores MCP → Editar JSON
Antigravity	~/.gemini/antigravity/mcp_config.json

Fragmento de configuración (funciona en todas partes):

{
  "mcpServers": {
    "ahme": {
      "command": "python",
      "args": ["-m", "ahme.mcp_server"],
      "env": { "PYTHONPATH": "/absolute/path/to/ahme" }
    }
  }
}

Un .mcp.json listo para usar está incluido en la raíz del repositorio — solo cópialo donde tu herramienta lo espere.

Opción B — Vigilancia de archivos (configuración cero)

Después de cualquier compresión, AHME escribe .ahme_memory.md en el directorio del proyecto. Refiérelo en cualquier prompt:

@[.ahme_memory.md] use this as your long-term context before answering

O configura la inyección persistente con .agents/instructions.md (Antigravity):

Before starting any task, read @[.ahme_memory.md] and treat it as background context.

---

🛠 Referencia de Herramientas MCP

Herramienta	Entrada	Comportamiento
ingest_context	text: string	Divide el texto en fragmentos y los pone en cola para compresión en segundo plano
get_master_memory	reset?: bool (por defecto true)	Devuelve el resumen comprimido; si reset=true, limpia la base de datos y vuelve a sembrar con el resumen
clear_context	—	Borra todos los datos en cola sin valor de retorno

Patrón de uso típico

1. [After each conversation turn]
   → call ingest_context with the latest messages

2. [When approaching context limit, or starting a new session]
   → call get_master_memory
   → inject the result into your system prompt
   → the engine resets and starts accumulating again from this checkpoint

---

⚙️ Referencia de Configuración

config.example.toml — copia a config.toml:

[chunking]
chunk_size_tokens = 1500   # tokens per chunk
overlap_tokens = 150        # overlap between chunks (preserves context at boundaries)

[queue]
db_path = "ahme_queue.db"  # SQLite database path (relative to config.toml)
max_retries = 3             # retry failed compressions before marking as failed

[monitor]
poll_interval_seconds = 2.0
cpu_idle_threshold_percent = 30.0   # only compress when CPU is below this %

[ollama]
base_url = "http://localhost:11434"
model = "qwen2:1.5b"   # ← set this to your local model
timeout_seconds = 120

[merger]
batch_size = 5   # summaries per merge pass (lower = more frequent master updates)

[logging]
log_file = "ahme.log"
memory_file = ".ahme_memory.md"
max_bytes = 5242880    # 5 MB log rotation
backup_count = 3

---

🐍 API de Python

Si prefieres controlar AHME directamente desde Python:

import asyncio
from ahme.api import AHME

engine = AHME("config.toml")

# Push text into the queue
engine.ingest("The user asked about Python async patterns. We discussed...")

# Run the daemon (this blocks; use asyncio.create_task for non-blocking)
asyncio.run(engine.run())

# Read the compressed memory
print(engine.master_memory)

# Stop the daemon
engine.stop()

---

📁 Estructura del Proyecto

ahme/
├── ahme/
│   ├── __init__.py          # Package marker & version
│   ├── config.py            # Typed TOML config loader
│   ├── db.py                # SQLite queue — enqueue, dequeue, clear, retry
│   ├── partitioner.py       # Token-accurate overlapping chunker (tiktoken)
│   ├── monitor.py           # CPU + lock-file idle detector (psutil)
│   ├── compressor.py        # Ollama async caller → structured JSON summaries
│   ├── merger.py            # Recursive batch-reduce tree → Master Memory Block
│   ├── daemon.py            # Main event loop + graceful shutdown + file bridge
│   ├── api.py               # Clean public Python API
│   └── mcp_server.py        # MCP server — stdio & SSE transports
├── tests/                   # 19 tests, all passing
├── .mcp.json                # Ready-to-use MCP config
├── config.example.toml      # Template config — copy to config.toml
├── pyproject.toml           # pip-installable package
└── README.md

---

🧪 Pruebas

pip install -e ".[dev]"
python -m pytest tests/ -v

Salida esperada: 19 aprobadas — todas las pruebas usan mocks y nunca requieren una instancia de Ollama en vivo.

---

🔑 Decisiones Clave de Diseño

Decisión	Justificación
SQLite sobre Redis	Cero dependencias externas, persistencia en un solo archivo, sobrevive a fallos
tiktoken para fragmentación	El conteo real de tokens BPE previene el desbordamiento del prompt
Superposición de 150 tokens	Preserva el contexto en los límites de los fragmentos
CPU + bloqueo por archivo de bloqueo	AHME nunca compite con tu sesión de IA activa por GPU/CPU
Fusión recursiva de árbol	Escala la compresión con la longitud de la conversación — pasadas O(log n)
Prompt de sistema solo JSON	Fuerza la salida estructurada de Ollama para un análisis confiable
Rutas relativas a __file__	La configuración y la base de datos siempre se encuentran independientemente del directorio de trabajo

---

🤝 Contribuciones

¡Las contribuciones son bienvenidas! Por favor, abre un issue antes de enviar PRs grandes.

---

📄 Licencia

MIT — haz lo que quieras.

---