AHME MCP

---

AHME é um daemon local auxiliar que fica silenciosamente ao lado do seu assistente de codificação com IA. Enquanto você trabalha, ele comprime o histórico da sua conversa em um Bloco de Memória Mestre denso usando um modelo local do Ollama — sem nuvem, sem desperdício de tokens, sem perda de contexto.

Ele se integra a qualquer ferramenta de IA que suporte MCP (Model Context Protocol): Antigravity, Claude Code, Kilo Code, Cursor, Windsurf, Cline/Roo e outras.

---

✨ Como 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)

Padrão de substituição de janela de contexto: chamar get_master_memory retorna o resumo comprimido, limpa os dados antigos e reinicia o mecanismo com o resumo — para que cada nova conversa comece a partir de um ponto de verificação denso, não de uma página em branco.

---

🚀 Início Rápido

Pré-requisitos

• Python 3.11+
• Ollama rodando localmente
• Um modelo pequeno baixado: ollama pull qwen2:1.5b (ou qualquer modelo de 1–4B)

Instalação

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 .

Configuração

Abra config.toml e defina seu modelo do Ollama:

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

Essa é a única linha que você precisa alterar. Todo o resto já vem pré-configurado.

---

🔌 Conecte à sua ferramenta de IA

AHME expõe três ferramentas MCP: ingest_context, get_master_memory e clear_context.

Opção A — MCP (recomendado)

Adicione AHME à configuração MCP da sua ferramenta. A localização exata do arquivo varia conforme a ferramenta:

Ferramenta	Localização da configuração
Claude Code	flag --mcp-config .mcp.json, ou ~/.claude/mcp.json
Kilo Code	VS Code settings.json → "kilocode.mcp.servers"
Cursor	Configurações → MCP → colar JSON
Windsurf	~/.windsurf/mcp.json
Cline / Roo	Barra lateral de Servidores MCP → Editar JSON
Antigravity	~/.gemini/antigravity/mcp_config.json

Trecho de configuração (funciona em qualquer lugar):

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

Um .mcp.json pronto está incluído na raiz do repositório — basta copiá-lo para onde sua ferramenta espera.

Opção B — Monitoramento de arquivo (zero configuração)

Após qualquer compressão, AHME grava .ahme_memory.md no diretório do projeto. Referencie-o em qualquer prompt:

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

Ou configure injeção persistente com .agents/instructions.md (Antigravity):

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

---

🛠 Referência das Ferramentas MCP

Ferramenta	Entrada	Comportamento
ingest_context	text: string	Particiona o texto em blocos e os coloca na fila para compressão em segundo plano
get_master_memory	reset?: bool (padrão true)	Retorna o resumo comprimido; se reset=true, limpa o banco de dados e reinicia com o resumo
clear_context	—	Apaga todos os dados enfileirados sem valor de retorno

Padrão 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

---

⚙️ Referência de Configuração

config.example.toml — copie para 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 Python

Se preferir controlar AHME diretamente do 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()

---

📁 Estrutura do Projeto

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

---

🧪 Testes

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

Saída esperada: 19 aprovados — todos os testes usam mocks e nunca exigem uma instância ativa do Ollama.

---

🔑 Principais Decisões de Design

Decisão	Justificativa
SQLite em vez de Redis	Zero dependências externas, persistência em arquivo único, sobrevive a falhas
tiktoken para particionamento	Contagem real de tokens BPE evita estouro de prompt
Sobreposição de 150 tokens	Preserva o contexto nas fronteiras dos blocos
CPU + bloqueio por arquivo de trava	AHME nunca compete com sua sessão ativa de IA por GPU/CPU
Mesclagem recursiva em árvore	Escala a compressão com o tamanho da conversa — passagens O(log n)
Prompt de sistema somente JSON	Garante saída estruturada do Ollama para análise confiável
Caminhos relativos a __file__	Configuração e banco de dados são sempre encontrados independentemente do diretório de trabalho

---

🤝 Contribuindo

Contribuições são bem-vindas! Por favor, abra uma issue antes de enviar PRs grandes.

---

📄 Licença

MIT — faça o que quiser.

---