uml-aimem 0.2.2__tar.gz

uml_aimem-0.2.2/PKG-INFO

@@ -0,0 +1,282 @@
+Metadata-Version: 2.4
+Name: uml-aimem
+Version: 0.2.2
+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.2"
+# ou: pipx install "uml-aimem[mcp,tokens]==0.2.2"
+```
+
+**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.

uml_aimem-0.2.2/README.md

@@ -0,0 +1,254 @@
+# 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.2"
+# ou: pipx install "uml-aimem[mcp,tokens]==0.2.2"
+```
+
+**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.

uml_aimem-0.2.2/pyproject.toml

@@ -0,0 +1,60 @@
+[build-system]
+requires = ["setuptools>=69"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "uml-aimem"
+version = "0.2.2"
+description = "Unified Memory Layer CLI for canonical, derived, and agent-aware project memory."
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+  "PyYAML>=6.0",
+  "typer>=0.12,<1.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/Mexicanguy1987/aimem"
+Repository = "https://github.com/Mexicanguy1987/aimem"
+Changelog = "https://github.com/Mexicanguy1987/aimem/blob/master/CHANGELOG.md"
+PyPI = "https://pypi.org/project/uml-aimem/"
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=7.4",
+  "pytest-benchmark>=4.0",
+  "pytest-asyncio>=0.23",
+  "locust>=2.30",
+]
+mcp = [
+  "mcp>=1.0,<2",
+]
+semantic = [
+  "sqlite-vec>=0.1.6",
+]
+local-embed = [
+  "sentence-transformers>=3.0",
+]
+openai = [
+  "openai>=1.40.0",
+]
+tokens = [
+  "tiktoken>=0.7.0",
+]
+
+[project.scripts]
+aimem = "aimem.cli:app"
+aimem-mcp = "aimem.mcp_server:main"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+"aimem.templates" = ["*.md", "*.yaml", "*.txt", "*.jsonl"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

uml_aimem-0.2.2/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

uml_aimem-0.2.2/src/aimem/__init__.py

@@ -0,0 +1,19 @@
+"""aimem package."""
+
+import importlib.metadata
+
+from aimem._dist import DISTRIBUTION_NAME
+
+__all__ = ["__version__", "DISTRIBUTION_NAME"]
+
+
+def _installed_version() -> str:
+    for dist in (DISTRIBUTION_NAME, "aimem"):
+        try:
+            return importlib.metadata.version(dist)
+        except importlib.metadata.PackageNotFoundError:
+            continue
+    return "0.0.0+unknown"
+
+
+__version__ = _installed_version()

uml_aimem-0.2.2/src/aimem/_dist.py

@@ -0,0 +1,3 @@
+"""PyPI distribution name (import package remains ``aimem``)."""
+
+DISTRIBUTION_NAME = "uml-aimem"

uml_aimem-0.2.2/src/aimem/cli.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+import typer
+
+from aimem.commands.compile import compile_command
+from aimem.commands.context import context_command
+from aimem.commands.drift import drift_app
+from aimem.commands.hooks import install_hooks_command
+from aimem.commands.index import index_app
+from aimem.commands.init import init_command
+from aimem.commands.manifest import manifest_app
+from aimem.commands.promote import promote_command
+from aimem.commands.query import query_command
+from aimem.commands.record import record_app
+from aimem.commands.verify import verify_command
+
+app = typer.Typer(help="Unified Memory Layer CLI.")
+
+app.command("init")(init_command)
+app.command("compile")(compile_command)
+app.command("context")(context_command)
+app.command("query")(query_command)
+app.command("verify")(verify_command)
+app.command("install-hooks")(install_hooks_command)
+app.command("promote")(promote_command)
+app.add_typer(record_app, name="record")
+app.add_typer(drift_app, name="drift")
+app.add_typer(manifest_app, name="manifest")
+app.add_typer(index_app, name="index")
+
+
+def main() -> None:
+    app()
+
+
+if __name__ == "__main__":
+    main()