Metadata-Version: 2.4
Name: uml-aimem
Version: 0.2.6
Summary: Unified Memory Layer CLI for canonical, derived, and agent-aware project memory.
Project-URL: Homepage, https://github.com/Mexicanguy1987/aimem
Project-URL: Repository, https://github.com/Mexicanguy1987/aimem
Project-URL: Changelog, https://github.com/Mexicanguy1987/aimem/blob/master/CHANGELOG.md
Project-URL: PyPI, https://pypi.org/project/uml-aimem/
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: PyYAML>=6.0
Requires-Dist: typer<1.0,>=0.12
Provides-Extra: dev
Requires-Dist: pytest>=7.4; extra == "dev"
Requires-Dist: pytest-benchmark>=4.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: locust>=2.30; extra == "dev"
Provides-Extra: mcp
Requires-Dist: mcp<2,>=1.0; extra == "mcp"
Provides-Extra: semantic
Requires-Dist: sqlite-vec>=0.1.6; extra == "semantic"
Provides-Extra: local-embed
Requires-Dist: sentence-transformers>=3.0; extra == "local-embed"
Provides-Extra: openai
Requires-Dist: openai>=1.40.0; extra == "openai"
Provides-Extra: tokens
Requires-Dist: tiktoken>=0.7.0; extra == "tokens"

# 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](docs/governance.md)
- **Context Bundle JSON Contract**: [docs/context-bundle.md](docs/context-bundle.md)
- **C3 / Multi-LLM Roadmap**: [docs/c3-multillm.md](docs/c3-multillm.md)
- **Templates vs Governance**: [docs/templates-governance-sync.md](docs/templates-governance-sync.md)
- **Intensive Testing / Pre-PyPI**: [docs/pre-publish-testing.md](docs/pre-publish-testing.md)
- **Operations Matrix (Commands & Cost)**: [docs/operations-matrix.md](docs/operations-matrix.md)
- **Performance Profiling**: [docs/performance-profiling.md](docs/performance-profiling.md)
- **Changelog**: [CHANGELOG.md](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:
```bash
./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):
```bash
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:
```bash
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:
```bash
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](CONTRIBUTING.md)
- [docs/releasing.md](docs/releasing.md)
- [docs/dogfooding-mcp.md](docs/dogfooding-mcp.md)
