Metadata-Version: 2.4
Name: uml-aimem
Version: 0.2.4
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` is a local CLI for building a canonical, derived, and agent-aware shared memory layer inside a Git repository.

## Scope

A versão publicada em `pyproject.toml` (actualmente **0.2.x**) inclui, entre outros:

- `aimem init`
- `aimem compile --profile <name>`
- `aimem compile --profile <name> --objective "<goal>"`
- `aimem query "<objective>"`
- `aimem verify`
- `aimem verify --refresh`
- `aimem verify --fast`
- `aimem verify --strict`
- `aimem record decision`
- `aimem record task`
- `aimem install-hooks`
- `aimem promote`
- `aimem drift scan|report|reconcile|apply`
- `aimem manifest get <uuid>`
- `aimem context` — pacote único (stdout) com meta do repo, pinados do perfil, retrieval, drift e referência ao último ACM; `--objective` / `--profile` / `--format json` / `--after-compile`

The tool creates a `.ai_memory` contract with canonical Markdown documents, derived outputs, journal primitives, and Git ignore rules for generated and indexed artifacts.

**Governança operacional** (modos `verify`, ciclo de vida, drift, ACM após `promote`): [docs/governance.md](docs/governance.md).

**Alterações entre versões:** [CHANGELOG.md](CHANGELOG.md). **Contrato JSON do pacote de contexto:** [docs/context-bundle.md](docs/context-bundle.md). **Roadmap C3 / multi-LLM:** [docs/c3-multillm.md](docs/c3-multillm.md). **Templates vs governança:** [docs/templates-governance-sync.md](docs/templates-governance-sync.md). **Testes intensivos / pré-PyPI:** [docs/pre-publish-testing.md](docs/pre-publish-testing.md). **Matriz operacional (comandos e custo):** [docs/operations-matrix.md](docs/operations-matrix.md). **Perfilar compile/drift:** [docs/performance-profiling.md](docs/performance-profiling.md). **RFC MCP `sections` (condicional):** [docs/rfc-mcp-context-sections.md](docs/rfc-mcp-context-sections.md).

## 🚀 Guia Rápido de Instalação e Uso

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 (Sem Script)
### Passo 1: Instalação no Sistema

O pacote PyPI chama-se **`uml-aimem`** (o nome `aimem` já estava ocupado). Os comandos na shell continuam a ser `aimem` e `aimem-mcp`.

**PyPI (utilizadores finais)** — não uses `pip install` no Python do sistema (PEP 668 no Ubuntu); preferir `uv` ou `pipx`:

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

**Desenvolvimento** neste repositório:

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

*(O `-e` reflecte alterações ao código fonte; `[mcp,tokens]` activa MCP e estimativa de tokens no compile.)*

Confirma a instalação:
```bash
aimem --help
aimem-mcp --help
```

### Passo 2: Inicializar um Repositório (O dia a dia do CLI)
Para usar o `aimem` noutro projeto qualquer (ou até neste repositório), cria a Camada de Memória Unificada. No terminal do projeto alvo, corre:
```bash
aimem init
```
**O que isto faz:**
* Cria a pasta `.ai_memory/` na raiz do teu projeto.
* Gera os *templates* padrão (`manifest.yaml`, regras arquiteturais, etc.).
* Atualiza automaticamente o teu `.gitignore`.

Sempre que tomas uma decisão arquitetural, assumes tu o controlo canónico (e não a IA):
```bash
aimem record decision "Decidimos mudar do SQLite FTS5 puro para um motor híbrido com Vetores"
```
Isto vai gerar um ficheiro Markdown validado em `.ai_memory/decisions/` com o formato e *frontmatter* que a IA precisa.

### Passo 3: Ligar a Inteligência Artificial (O Servidor MCP)
O verdadeiro poder da ferramenta é como injetamos esta memória no teu editor de código via Model Context Protocol (MCP). Exemplo no **Cursor**:

1. Abre as Definições do Cursor.
2. Procura por **"MCP"**.
3. Adiciona um novo servidor com a seguinte configuração:
   * **Name:** `Aimem Server`
   * **Type:** `command`
   * **Command:** `aimem-mcp` *(ou o caminho absoluto gerado pelo uv, ex: `~/.local/bin/aimem-mcp`)*
   * **Args:** `--repo /caminho/absoluto/do/teu/projeto`

A partir desse momento, quando abrires o chat e pedires uma nova funcionalidade, o Cursor vai **automaticamente** ler as regras da arquitetura e as decisões técnicas usando a ferramenta `get_agent_context_bundle`, poupando milhares de tokens da tua conta e garantindo que a IA não alucina decisões.

### Passo 4: Verificação de Derivação (Drift Sentinel)
Antes de fazeres *commit* de código, deves garantir que as regras da memória correspondem ao código final:
```bash
aimem drift scan .
```
O motor local vai comparar as declarações documentadas (os *claims*) com o código fonte e verificar se as regras estão a ser cumpridas.

## Instalação e extras (núcleo vs opcional)

| Extra `uv` | Conteúdo | Quando usar |
| --- | --- | --- |
| *(nenhum)* | Só dependências do pacote: Typer + PyYAML — CLI, SQLite local, FTS5 no fluxo actual. | `uv sync` para uso normal do `aimem` sem MCP nem testes. |
| `dev` | `pytest`, `pytest-benchmark`, `pytest-asyncio`, `locust` | Desenvolvimento e CI local, e testes de concorrência. |
| `mcp` | Pacote `mcp` + entrada `aimem-mcp` | Servidor MCP stdio para IDEs. |
| `tokens` | `tiktoken` | Estimativa de tokens mais precisa no `compile` quando `max_tokens` está activo (`estimate_tokens` no compilador). |
| `semantic` | `sqlite-vec` | Caminho opt-in para extensão vectorial (v0.2b / retrieval avançado). |
| `local-embed` / `openai` | Embeddings opcionais | Caminho opt-in; não fazem parte da instalação base. |

## Para agentes / IDEs

`aimem context` imprime um **único** bloco (markdown, texto ou JSON) com estado do repositório, documentos pinados do perfil de compile (por defeito `bootstrap`), resultados de `query_memory`, eventos de drift abertos e o último manifesto ACM conhecido. **Complementa** `aimem query` e o servidor MCP para memória canónica em `.ai_memory`; **não substitui** `verify`, fontes externas (ver política MCP-first em [CONTRIBUTING.md](CONTRIBUTING.md)) nem julgamento humano sobre decisões.

Orçamento de caracteres (`--max-chars`, aplica-se à saída markdown/texto): reserva para cabeçalhos e meta; o remanescente reparte-se de forma fixa entre pinados (~45%), retrieval (~40%) e margem para listagens (drift, ACM).

Exemplos (mesmo padrão `uv run --directory` que no CI):

```bash
export AIMEM=/caminho/absoluto/para/aimem
uv run --directory "$AIMEM" aimem context "$(pwd)"
uv run --directory "$AIMEM" aimem context "$(pwd)" --profile bootstrap --objective "Implementar feature X"
uv run --directory "$AIMEM" aimem context "$(pwd)" --format json
# Opcional: corre um compile antes e inclui o manifesto dessa corrida no bundle
uv run --directory "$AIMEM" aimem context "$(pwd)" --after-compile --compile-profile bootstrap
# Objectivo só do compile (o retrieval continua a usar --objective se o passares)
uv run --directory "$AIMEM" aimem context "$(pwd)" --after-compile --compile-objective "handoff notes"
```

No Cursor, ao editares ficheiros sob `.ai_memory/`, a regra [`.cursor/rules/aimem-context-bootstrap.mdc`](.cursor/rules/aimem-context-bootstrap.mdc) sugere este fluxo (não é `alwaysApply`).

## Contributing

Development setup, **MCP-first retrieval policy** (external docs/APIs vs canonical `.ai_memory`), and **remote/PR workflow** are described in [CONTRIBUTING.md](CONTRIBUTING.md) and [docs/releasing.md](docs/releasing.md). Cursor loads the same rules from [`.cursor/rules/mcp-first-retrieval.mdc`](.cursor/rules/mcp-first-retrieval.mdc).

## Drift Sentinel

Drift compares **gold (or reviewed) memory claims** (`aimem_claims` in canonical frontmatter) against the working tree using rules declared under `aimem_drift` in `.ai_memory/manifest.yaml`.

```bash
uv run aimem drift scan .
uv run aimem drift report .
uv run aimem drift reconcile .
uv run aimem drift apply .          # dry-run: shows planned governance updates
uv run aimem drift apply . --write  # sets verification_status: drifted on affected docs (uses .ai_memory lock)
```

Open drift rows are stored in `.ai_memory/index/aimem.sqlite` and referenced from compile output / MCP helpers as `aimem://drift-event/<id>`.

## Context manifests (ACM)

Each `aimem compile` run can emit an **auditable context manifest** (JSON) under `.ai_memory/journal/manifests/<manifest_id>.json`. The CLI prints a line such as:

`Context manifest: aimem://manifest/<manifest_id>`

Inspect a manifest:

```bash
uv run aimem manifest get <manifest_id> .
```

The `aimem_version` field reflects the installed `aimem` package version.

## MCP server (stdio, optional)

With the optional `mcp` extra, this package exposes `aimem-mcp`, a stdio MCP server that wraps `query_capsules`, `get_drift_alerts`, `get_context_manifest`, **`get_agent_context_bundle`** (same structured JSON as `aimem context --format json`), and resource templates `aimem://manifest/{manifest_id}` (JSON) and `aimem://capsule/{capsule_id}` (Markdown on disk under `.ai_memory/journal/capsules/`).

```bash
uv sync --extra mcp
```

Example **Cursor** MCP entry (`.cursor/mcp.json` or equivalent), pointing at this repo’s virtualenv:

```json
{
  "mcpServers": {
    "aimem": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/this/repo", "aimem-mcp", "--repo", "/absolute/path/to/target/repo"]
    }
  }
}
```

Adjust `--directory` to the checkout where `aimem` is installed and `--repo` to the Git project whose `.ai_memory` you want to query.

For a longer dogfooding checklist (paths, extras, typical errors), see [docs/dogfooding-mcp.md](docs/dogfooding-mcp.md).

## Record Commands

Use the `record` subcommands to create canonical documents with consistent IDs, filenames, frontmatter, and journal entries.

```bash
uv run aimem record decision "Adopt MCP"
uv run aimem record task "Add SQLite index" --done-when "query returns relevant docs"
```

Use `--allow-secrets` only in controlled scenarios when you intentionally need to bypass high-confidence secret blocking.

## Query

`aimem query` refreshes a local SQLite index in `.ai_memory/index/aimem.sqlite` from canonical memory and returns the most relevant documents for an objective. The index is local-only and remains Git-ignored.

Default retrieval mode is `hybrid_metadata` (`FTS5` + metadata reranking). Semantic/vector retrieval remains opt-in.

## Objective-Aware Compile

`aimem compile` keeps the previous ordered behavior when no objective is provided. When `--objective` is present and the selected profile uses `selection_mode: retrieval`, the command includes pinned baseline documents first and then fills the remaining budget with the most relevant retrieved documents.

Compile profiles support `max_tokens` with `max_chars` fallback for environments without tokenizer extras.

## Governance Lifecycle

Canonical documents use a lifecycle aimed at safe shared memory:

- `draft`
- `reviewed`
- `gold`
- `deprecated`

Deprecated documents are strongly penalized during retrieval and excluded by default from objective-focused context packs.

## Hooks and Fast Verification

Install local Git hooks with:

```bash
uv run aimem install-hooks
```

The generated `pre-commit` hook runs `aimem verify --fast` for low-latency local checks.

## Strict Governance

For stricter checks (including high-criticality review requirements), use:

```bash
uv run aimem verify --strict
```

## Verification Refresh

`aimem verify --refresh` rewrites canonical documents with the current `verified_at` timestamp and the current Git `HEAD` in `verified_from.git_commit`, then reports the refreshed verification status.

## Memory Model

- `rules`, `state`, `decisions`, `tasks`: canonical memory
- `journal`: append-only operational history
- `generated`: derived outputs
- `cache`, `index`, `workspaces`: local-only artifacts ignored by Git

Each canonical Markdown document uses YAML frontmatter with ownership, verification, and provenance metadata.
