uml-aimem 0.2.6

Unified Memory Layer CLI for canonical, derived, and agent-aware project memory.

Unified Memory Layer (aimem)

aimem is a local CLI and MCP server for building a canonical, derived, and agent-aware shared memory layer inside a Git repository. It bridges the gap between raw codebase context and high-level project goals, leveraging governance, objective-based context retrieval, and drift detection.

---

📚 Documentation & References

• Operational Governance (verify, lifecycle, drift, ACM): docs/governance.md
• Context Bundle JSON Contract: docs/context-bundle.md
• C3 / Multi-LLM Roadmap: docs/c3-multillm.md
• Templates vs Governance: docs/templates-governance-sync.md
• Intensive Testing / Pre-PyPI: docs/pre-publish-testing.md
• Operations Matrix (Commands & Cost): docs/operations-matrix.md
• Performance Profiling: docs/performance-profiling.md
• Changelog: CHANGELOG.md

---

🧠 Memory Model

The tool creates a .ai_memory contract inside your repository. Each canonical Markdown document uses YAML frontmatter with ownership, verification, and provenance metadata.

• Canonical Memory: rules, state, decisions, tasks (Checked into Git).
• Journal: journal (Append-only operational history, sessions, manifests).
• Derived: generated (Derived outputs).
• Local-only: cache, index, workspaces (Local-only artifacts ignored by Git).

---

🚀 Guia Rápido de Instalação e Uso (Quick Start)

A forma mais simples de começar a utilizar o aimem é através do nosso painel interativo. Basta abrires o terminal na raiz do projeto e correres:

./aimem-menu.sh

Isto abrirá um menu guiado onde podes instalar o pacote, inicializar a memória, gravar decisões técnicas e ver as instruções detalhadas de como ligar a Inteligência Artificial do teu IDE (como o Cursor) ao sistema.

Instalação Manual

O pacote PyPI chama-se uml-aimem. Os comandos na shell continuam a ser aimem e aimem-mcp.

Para utilizadores finais (preferir uv ou pipx para evitar quebrar o sistema base):

uv tool install "uml-aimem[mcp,tokens]==0.2.6"
# ou: pipx install "uml-aimem[mcp,tokens]==0.2.6"

Para desenvolvimento neste repositório:

uv tool install -e ".[mcp,tokens]"

(O -e reflete alterações ao código fonte em tempo real)

---

⚙️ Core Workflows & CLI

A versão atual (0.2.x) inclui os seguintes comandos principais:

1. Inicialização

• aimem init: Inicializa a camada de memória na raiz do projeto gerando .ai_memory/ e o respetivo .gitignore.

2. Registo de Decisões e Tarefas (Recording)

Cria documentos canónicos com IDs, filenames, frontmatter e entradas no journal consistentes.

• aimem record decision "Adopt MCP"
• aimem record task "Add SQLite index" --done-when "query returns docs"
• aimem record session --target handoff --slug ...

(Dica: Usa --allow-secrets apenas se necessitares intencionalmente de contornar o bloqueio de segredos).

3. Governança e Verificação (Verify)

O ciclo de vida dos documentos visa segurança e precisão (draft → reviewed → gold → deprecated).

• aimem verify: Verifica metadados e integridade.
• aimem verify --fast: Verificação otimizada (ideal para Git hooks locais - instalados via aimem install-hooks).
• aimem verify --strict: Verificação profunda (incluindo review consensus para documentos críticos).
• aimem verify --refresh: Reescreve documentos canónicos com as timestamps de validação e commit atualizados.
• aimem promote: Promove um documento no seu ciclo de vida.

4. Drift Sentinel (Derivação)

Compara as regras canónicas (claims) com o código final (working tree). Regras definidas em .ai_memory/manifest.yaml.

• aimem drift scan . (avalia desvios)
• aimem drift report .
• aimem drift reconcile .
• aimem drift apply . (dry-run das atualizações de governance planeadas)
• aimem drift apply . --write (marca verification_status: drifted nos documentos afetados)

5. Contexto e Pesquisa (Query & Compile)

• aimem query "<objective>": Atualiza o index local (SQLite) e retorna os documentos mais relevantes para o objetivo (FTS5 + metadata reranking).
• aimem compile --profile <name> --objective "<goal>": Compilação focada. Preenche o budget (em tokens ou caracteres) com os pinos fixos do perfil e documentos da pesquisa. Gera um Auditable Context Manifest (ACM) referenciado via aimem://manifest/<uuid>.
• aimem manifest get <uuid>: Inspeciona um ACM emitido.

---

🤖 AI & MCP Integration (O Servidor MCP)

A integração via Model Context Protocol (MCP) expõe de forma padronizada os comandos do aimem aos agentes de IA (como o Cursor).

Configuração no Cursor

1. Definições > "MCP" > Adicionar servidor:
   • Name: Aimem Server
   • Type: command
   • Command: aimem-mcp (ou o caminho absoluto do uv)
   • Args: --repo /caminho/absoluto/do/teu/projeto

Geração de Contexto (aimem context)

Se o IDE não suportar MCP nativo de forma ideal, a IA pode correr manualmente na shell para extrair toda a memória:

uv run aimem context "$(pwd)" --profile bootstrap --objective "Implementar feature X"

Isto imprime um bloco consolidado com o estado do repositório, pinos fixos, resultados do retrieval, drift alerts e o último ACM. Não substitui o julgamento humano nem regras do verify. Pode usar o formato --format json para extração estruturada (que o MCP já devolve nativamente).

---

📦 Instalação e Extras (Opt-in)

Extra uv	Funcionalidades Incluídas	Quando Usar
(nenhum)	Dependências base: Typer + PyYAML (CLI, SQLite, FTS5)	uv sync para uso diário sem MCP.
dev	pytest, pytest-benchmark, pytest-asyncio, locust	Desenvolvimento do aimem, CI local, testes.
mcp	Pacote mcp oficial + entrypoint aimem-mcp	Servidor MCP stdio para integração com IDEs.
tokens	tiktoken	Precisão superior no budgeting do contexto no compile (max_tokens).
semantic	sqlite-vec	Pesquisa vetorial híbrida (Retrieval Avançado / v0.2b).
local-embed / openai	Embeddings	Opcional (não base); suporta vetores locais/remotos.

---

🤝 Contributing

Para regras sobre as contribuições (development setup, fluxo de PRs e lançamento de releases remoto), bem como a política de pesquisa MCP-first imposta aos agentes, consulta:

• CONTRIBUTING.md
• docs/releasing.md
• docs/dogfooding-mcp.md