orkmind 0.1.0__tar.gz

orkmind-0.1.0/.gitignore

@@ -0,0 +1,44 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+*.egg
+dist/
+build/
+*.whl
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Environment
+.env
+.env.local
+
+# Ruff
+.ruff_cache/
+
+# Benchmark: so os resultados canonicos sao versionados
+bench/results/*
+!bench/results/.gitkeep
+!bench/results/latest.json
+!bench/results/baseline-pre-port.json

orkmind-0.1.0/.python-version

@@ -0,0 +1 @@
+3.11

orkmind-0.1.0/.worktrees/docs-acentuacao/.gitignore

@@ -0,0 +1,44 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+*.egg
+dist/
+build/
+*.whl
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Environment
+.env
+.env.local
+
+# Ruff
+.ruff_cache/
+
+# Benchmark: so os resultados canonicos sao versionados
+bench/results/*
+!bench/results/.gitkeep
+!bench/results/latest.json
+!bench/results/baseline-pre-port.json

orkmind-0.1.0/.worktrees/docs-acentuacao/.python-version

@@ -0,0 +1 @@
+3.11

orkmind-0.1.0/.worktrees/docs-acentuacao/CHANGELOG.md

@@ -0,0 +1,253 @@
+# Changelog
+
+All notable changes to OrkMind will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- **Storage plugavel (ciclo Devmaster "storage plugavel", F3.1-F3.9)**: o
+  OrkMind deixa de ter um unico backend. Sao tres nesta leva, e o padrao nao
+  muda para quem ja usa. Ver `docs/storage-backends/MATRIZ-BACKENDS.md` e
+  `docs/storage-backends/GUIA-BACKENDS.md`.
+- `[store].backend` no `config.toml`, `[store.options]` como bag de opcoes por
+  backend, e as variaveis `ORKMIND_STORE_BACKEND` e `ORKMIND_STORE_OPTIONS`
+  (JSON, merge raso). `OrkMindConfig.has_store` nasce ao lado de
+  `has_database`, que fica intacta.
+- Registry `STORE_BACKENDS` com builders lazy: `pgvector` (default), o alias
+  `postgres`, `memory` e `qdrant`. Importar `orkmind.store.factory` nao arrasta
+  mais `psycopg` nem `pgvector`.
+- `StoreCapabilities` (`orkmind.store.capabilities`): cada backend declara o
+  que sabe fazer. Toda degradacao passa por ai, e nenhuma acontece em silencio.
+- `orkmind store info`: imprime o backend ativo, as capabilities e os avisos
+  ativos (`--json` para consumo por ferramenta).
+- `GovernedStore` (`orkmind.store.governed`) e as funcoes puras de
+  `orkmind.store.governance`: a governanca (protecao D2, ACL de leitura e de
+  escrita, versionamento, ordenacao constitucional, filtro de expiracao e de
+  `injection_risk`) sobe para uma camada unica acima dos adapters.
+  `create_store()` passa a devolver sempre um store governado.
+- `ProfileStore` (`orkmind.store.profiles`) com duas implementacoes:
+  `PostgresProfileStore` (tabela `profiles`, comportamento de hoje) e
+  `EntryProfileStore` (perfis como entries da colecao `users`). A ACL por grupo
+  passa a funcionar em qualquer backend, sem migrar dado de producao.
+- `MemoryAdapter` (backend `memory`): storage volatil em dicts, com cosseno em
+  numpy. Da cobertura de contrato em qualquer maquina, sem servico externo.
+- `QdrantAdapter` (backend `qdrant`, extra `orkmind[qdrant]`): uma colecao com
+  payload discriminado por `kind`, vetor nomeado `content` e distancia cosseno.
+- `MemoryStore.capabilities`, `search_semantic_text()`,
+  `list_entries_without_embedding()` e `set_embedding()` entram no contrato,
+  todos concretos e com falha alta e nomeada quando nao suportados.
+- `orkmind store export` e `orkmind store import` (`orkmind.store.transfer`):
+  migracao entre backends em JSONL com manifesto. A migracao nunca remove a
+  origem, o import nunca sobrescreve, o destino ganha snapshot antes de
+  qualquer escrita e a reconciliacao de entries `mandatory` e obrigatoria.
+- Suite de contrato parametrizada por backend, com guarda destrutiva propria e
+  mais rigida para cada backend novo (`tests/contract/backends.py`,
+  `tests/unit/test_guarda_backends.py`).
+- Teste de equivalencia de governanca entre backends
+  (`tests/contract/test_governanca_equivalencia.py`): o mesmo corpus fixo e
+  carregado em todos os backends disponiveis e as mesmas consultas rodam com o
+  mesmo `requester_id` nos tres. Verifica ordem total identica em
+  `search_by_tags`, conjunto identico em busca textual e vetorial com
+  `mandatory` sempre na frente, ACL igual para autor, membro de grupo, estranho
+  e requester ausente, `ProtectionError` com a MESMA mensagem em todos, e
+  `version + 1` com exatamente uma versao arquivada. Com menos de dois backends
+  disponiveis o teste PULA com aviso ruidoso, para nao ser aprovado por
+  vacuidade.
+
+### Changed
+
+- `SemanticLayer.search_semantic_intent` escolhe entre `search_semantic` e
+  `search_semantic_text` pelo que o backend DECLARA em `capabilities`, e avisa
+  uma vez por processo quando o backend nao faz busca vetorial.
+- `embeddings/backfill.py` passa a usar o contrato do store
+  (`list_entries_without_embedding` e `set_embedding`) em vez de SQL cru e da
+  conexao interna do adapter. Era o ultimo vazamento de backend no codigo
+  Python.
+- `scripts/seed_profiles.py` usa `store.profiles` e perdeu os quatro
+  `# type: ignore[attr-defined]`. O gate passou de `has_database` para
+  `has_store`.
+- **Quebra de texto de erro (nao de tipo):** `create_store()` levantava
+  `ValueError("No database URL configured...")` e agora levanta
+  `BackendMalConfiguradoError` ou `BackendDesconhecidoError`, com mensagem em
+  pt-BR nomeando o backend. As duas herdam de `ValueError`, entao quem captura
+  por tipo nao quebra; quem captura pelo texto precisa ajustar.
+- A limpeza do backend `pgvector` na suite de contrato passa a incluir a tabela
+  `profiles`, porque a suite agora exercita identidades.
+
+### Fixed
+
+Correcoes do F4 (QA do ciclo), cada uma com teste de regressao provado vermelho
+sem a correcao. Auditoria completa em `docs/audit/2026-09-01-f4-storage/`.
+
+- **Regra `mandatory` sumindo do contexto sob volume** (`memory` e `qdrant`).
+  O contrato promete que entries `mandatory` que casam as tags sao SEMPRE
+  incluidas, e isso era falso: com centenas de entries casando a consulta, a
+  janela de candidatos era preenchida pela ordem NEUTRA do adapter e a regra
+  obrigatoria mais antiga nao aparecia. `GovernedStore._garantir_mandatory`
+  passa a fazer uma segunda consulta com `mandatory_only=True` nos backends sem
+  ordenacao nativa. O `pgvector` nao paga nada por isso.
+- **Ordem de `search_by_tags` nao era total no `pgvector` (I9).** Sem over-fetch
+  o `LIMIT` do SQL corta, e o `ORDER BY` sem desempate por `id` escolhia
+  arbitrariamente entre empates: com `limit=2` os conjuntos devolvidos por
+  `pgvector` e `memory` chegavam a ser disjuntos. Entra `, id ASC` em
+  `search_by_tags`, `search_by_text`, `search_semantic` e `get_children`.
+- **Migracao perdia a ACL em silencio.** `store/transfer.py` nao carregava
+  identidades e nao declarava a perda: uma migracao mudava quem enxerga o que e
+  o relatorio dizia que estava tudo certo. Agora o manifesto traz `profile_count`
+  e `profiles_as_entries`, a perda de identidades e declarada no import e exige
+  `--accept-loss`, e o destino reconcilia a contagem de perfis.
+
+### Notes
+
+- `pgvector` continua sendo o default. Uma instalacao sem `[store].backend` no
+  TOML e sem `ORKMIND_STORE_BACKEND` resolve para `pgvector` e funciona sem
+  editar nada.
+- Para `pgvector` nao ha over-fetch de candidatos: o `limit` enviado ao adapter
+  e o `limit` pedido, e o SQL emitido e o mesmo de antes do ciclo. Ha teste com
+  espiao provando isso nas tres buscas.
+- Dividas registradas neste ciclo: **D-1** `psycopg`/`pgvector` seguem
+  obrigatorios em vez de extra; **D-2** o plugin OpenClaw continua falando SQL
+  com pgvector; **D-3** perfis de producao permanecem na tabela `profiles`;
+  **D-4** Qdrant ainda nao e servico no CI; **D-5** `snapshot_*` continua
+  devolvendo `dict`; **D-6** `PostgresAdapter` mantem conexao unica sem pool;
+  **D-7** o SQL de ACL e de ordenacao do `PostgresAdapter` fica como
+  redundancia por um ciclo.
+
+#### Status de maturidade dos backends
+
+- `pgvector` (default): **apto a producao**. E o unico backend com ACL e
+  ordenacao nativas no SQL, com as identidades na tabela `profiles`, e nao e
+  atingido por nenhuma das dividas criticas abaixo.
+- `memory`: **so para teste e desenvolvimento**. Volatil, nao duravel, nao pode
+  virar default e nao deve ser habilitado em producao.
+- `qdrant`: **EXPERIMENTAL, nao habilitavel em producao neste ciclo**. Entra na
+  `main` para consolidar a arquitetura plugavel, nao para ser ligado. As
+  dividas S1 e S4 abaixo sao bloqueantes para produzi-lo, e a evidencia deste
+  ciclo veio do Qdrant em modo local, que tem semantica de busca textual
+  diferente da do servidor e ignora indices de payload.
+
+#### Dividas conhecidas do F4 (registradas, nao bloqueiam a `main`)
+
+O QA do F4 fechou com CHANGES NEEDED por dois achados criticos que continuam
+ABERTOS. Nenhum dos dois atinge o default `pgvector`, e os dois so tem efeito
+em backends que nao estao aptos a producao, entao a consolidacao da `main`
+segue com as dividas registradas. Detalhe e prova de conceito em
+`docs/audit/2026-09-01-f4-storage/REVIEW_SEC.md`.
+
+- **S1 (D-F4-S1), CRITICO, ABERTO: identidade forjavel pela API de memoria**
+  (`memory` e `qdrant`). Em backends que usam `EntryProfileStore` os perfis sao
+  entries comuns da colecao `users`, publicas e sem `protected`. Um agente que
+  pode gravar memoria pode criar um grupo com ele proprio dentro, se incluir num
+  grupo real ou apagar o grupo real, e com isso ler entries `restricted` das
+  quais nao era destinatario. **O `pgvector` e imune**, porque le identidade da
+  tabela `profiles`, fora do alcance da API de memoria. A correcao e decisao de
+  desenho e ficou para o proximo ciclo; o comportamento correto ja esta escrito
+  como teste `xfail(strict=True)`
+  (`TestA9IdentidadeNaoEForjavelPelaApiDeMemoria`), entao quando a correcao
+  entrar o teste passa, o `strict` derruba a suite e obriga a remover o
+  marcador. Nao da para esquecer.
+- **S4 (D-F4-S4), CRITICO, ABERTO: TTL nao apaga no Qdrant.**
+  `garbage_collect` remove os pontos `kind="entry"` e deixa os `kind="version"`,
+  que guardam o conteudo verbatim. Uma entry com TTL de retencao some das
+  buscas mas continua legivel por `get_history` para sempre, porque sem a
+  entry-mae nenhum `delete` futuro a alcanca. `pgvector` e `memory` apagam
+  corretamente. Enquanto isso nao for corrigido, TTL no Qdrant nao significa
+  apagamento e o backend nao pode receber dado com prazo de retencao.
+- Tambem bloqueantes para produzir o Qdrant: **D-F4-M1** (trunca antes de
+  ordenar em `search_by_tags` e `search_by_text`) e **D-B/D-4** (falta evidencia
+  contra um Qdrant SERVIDOR real). As demais dividas do F4 (D-F4-1 a D-F4-8) e
+  as menores M1 a M11 estao listadas em
+  `docs/audit/2026-09-01-f4-storage/REVIEW_QA_SUMMARY.md`.
+
+#### Estado da suite ao fechar o ciclo
+
+```
+1002 passed, 2 skipped, 1 xfailed
+```
+
+Com os tres backends configurados (`ORKMIND_TEST_DATABASE_URL`,
+`ORKMIND_TEST_QDRANT_URL`, `ORKMIND_TEST_QDRANT_PREFIX`). O `xfailed` e o S1
+acima. Sem nenhuma variavel `ORKMIND_TEST_*` a guarda destrutiva pula os
+backends externos e a suite fecha em `721 passed, 284 skipped`, sem tocar em
+base de producao.
+
+---
+
+### Added (ciclo "sempre gravar", anterior)
+
+- **Gravacao garantida (solucao "sempre gravar")**: conteudo de agente e
+  cron nao pode mais ficar orfao quando as tools de execucao faltam no
+  toolset do job ou quando o backend esta fora. Ver `docs/sempre-gravar.md`.
+- `orkmind.spool`: fila de saida (outbox) em disco com escrita atomica,
+  transicoes por rename (`pending/` -> `done/` | `failed/`), backoff
+  progressivo e `content_hash` como chave deterministica de deduplicacao.
+- `orkmind.api`: API HTTP local idempotente (Starlette, sem dependencia
+  nova). `POST /entries` responde `status: created|duplicate`,
+  `GET /entries/by-hash` faz o lookup de idempotencia, `GET /health`
+  reporta vivacidade. Token Bearer obrigatorio com falha fechada,
+  comparacao em tempo constante, conferencia de simetria de hash e
+  lookup que nunca devolve conteudo.
+- Comando `orkmind api` para servir a API (loopback por padrao).
+- `scripts/orkmind_drain.py`: drainer externo ao agente, com `--once`
+  (cron), `--watch` (continuo), `--status` (fila em JSON) e `--backfill`
+  (migracao de orfaos legados, repetivel e nao destrutiva).
+- `MemoryStore.find_by_content_hash()` e implementacao no
+  `PostgresAdapter`, base do lookup de idempotencia.
+- `migrations/f4_content_hash_idempotencia.sql`: indice unico parcial
+  em `memories(collection, content_hash)`, com consulta de diagnostico
+  de duplicatas preexistentes.
+- CLI `orkmind add`: opcoes `--content-hash` (conferencia de simetria),
+  `--dedupe` (idempotente por hash) e `--json` (saida para automacao).
+  Retrocompativel: sem as flags, o comportamento nao muda.
+- **Evolucao core (31/08/2026) - Blocos A/B/C**: **A) gap OpenClaw
+  N1/N2/N3** em `integrations/openclaw/memory-orkmind`: modulo `rules.ts`
+  (port literal da governanca, getMandatoryRules sem embedder, bucket de
+  regras + truncamento), shim do SDK com o contrato real de
+  `before_prompt_build`, garantia constitucional (N1) sempre presente no
+  prompt, guardrail anti-destruicao e via hook (contingencia D1), heuristica
+  de `allowPromptInjection`, seed idempotente das regras em `orkmind_openclaw`,
+  script de sync + runner de testes TS. **B) Recuperacao**: busca hibrida
+  (deterministica + vetorial com rerank RRF) como fonte adicional em
+  `query_for_context`, gate/embedder nos pontos de entrada Python, timeout
+  curto do embedder no caminho de consulta, janela de sessao ancorando o
+  prefetch no Hermes, detectores de palavra-chave pt-BR. **C) Benchmark**:
+  `bench/` com runner Hermes e contra o plugin OpenClaw, baseline retroativo
+  pre-port (M1/M2 = 0), evidencias e higiene documental.
+
+### Changed (ciclo "sempre gravar", anterior)
+
+- `PostgresAdapter.initialize()` cria o indice unico parcial de
+  idempotencia. A criacao e tolerante: se o banco ja tiver duplicatas,
+  apenas avisa, sem derrubar o CLI. Resolver duplicata e decisao humana.
+- Plugin Hermes 1.0.0 -> 1.1.0: `orkmind_store` estagia na fila ANTES de
+  tentar gravar e distingue `status: armazenado` (com id real) de
+  `status: pendente` (id nulo). Ver
+  `integrations/hermes/orkmind/CHANGELOG.md`.
+
+## [0.1.0] - 2026-08-22
+
+### Added
+
+- Core ontology with 16 typed collections and 5 semantic tag dimensions
+- MemoryEntry model (Pydantic v2) with full metadata support
+- MemoryStore abstract contract (ABC) with CRUD, tag search, text search, semantic search
+- PostgresAdapter with pgvector for vector search, tsvector for FTS, GIN for tags
+- SemanticLayer for context-aware memory retrieval with mandatory injection and token budget
+- Context detectors: Keyword and File path based detection
+- MCP Server (stdio) for Claude Code integration with 7 tools
+- Hermes MemoryProvider for Hermes agent integration
+- CLI with commands: add, list, search, detect, remove, export, import, stats, gc
+- Configuration via env vars and ~/.orkmind/config.toml
+- 75 tests: unit (51), integration (9), contract (15)
+- Documentation: ontology, integration guide, MCP setup, Hermes setup
+- Skills: SKILL.md for Claude Code, AGENTS.md for Codex
+- Apache 2.0 license
+
+### Fixed
+
+- pgvector `Vector.tolist()` compatibility in `query_for_context` return values
+- OR-across-dimensions logic in tag search queries (was incorrectly using AND across all dimensions)

orkmind-0.1.0/.worktrees/docs-acentuacao/IMPLEMENTATION_REPORT-SEMPRE-GRAVAR.md

@@ -0,0 +1,315 @@
+# Relatorio de implementacao: solucao "sempre gravar"
+
+> Executor: Claude Code (via goose), sob orquestracao do Hermes
+> Data: 31/08/2026
+> Repositorio: `~/OrkMind`, branch `main` (commits locais, sem push)
+> Fonte de verdade da proposta: `/home/julio/A-solucao-sempre-gravar.md`
+
+## 1. Resumo
+
+Implementados os itens P1 a P7 do plano, exceto os que sao de
+orquestracao (cron, systemd, toolset minimo dos jobs), listados na
+secao 7 como pendencias.
+
+O conteudo de agente e cron deixou de depender de duas condicoes
+fragilissimas (a tool certa estar no toolset naquela rodada, e o banco
+estar de pe naquele instante). A ordem de escrita foi invertida: estagia
+em disco primeiro, grava depois. O que nao gravar na hora e reconciliado
+por um processo externo ao agente, de forma retroativa e auditavel.
+
+O orfao legado real (`possibilidades-ia-2026-W36.md`) foi recuperado e
+gravado, com entry_id verificado no banco.
+
+## 2. Requisitos do plano e onde foram atendidos
+
+| Req | Descricao | Onde |
+|---|---|---|
+| R1 | API de escrita idempotente | `src/orkmind/api/app.py` (`POST /entries`) |
+| R2 | Lookup por hash | `src/orkmind/api/app.py` (`GET /entries/by-hash`) |
+| R3 | Indice unico parcial | `migrations/f4_content_hash_idempotencia.sql` |
+| R4 | CLI idempotente | `src/orkmind/cli/main.py` (`--content-hash`, `--dedupe`, `--json`) |
+| R5 | `orkmind_store` estagia primeiro | `integrations/hermes/orkmind/__init__.py` |
+| R6 | `stage_to_spool` / `mark_done` / `ORKMIND_SPOOL_DIR` | idem |
+| R7 | Bump 1.0.0 -> 1.1.0 + CHANGELOG | `plugin.yaml`, `integrations/hermes/orkmind/CHANGELOG.md` |
+| R8 | Script drainer | `scripts/orkmind_drain.py` |
+| R9 | `--once` / `--watch` | idem (mais `--status` e `--backfill`) |
+| R13 | Backfill dos orfaos legados | executado, ver secao 5 |
+
+## 3. Decisoes de projeto que valem registro
+
+**A API foi criada no core, nao reaproveitada do `orkmind-web`.** A
+porta 8000 e servida pelo `orkmind-web` (repo separado, fora de escopo
+desta rodada, com prefixo `/api/entries`). A API idempotente foi
+implementada dentro do repo OrkMind, em `127.0.0.1:8077`, para que o
+core seja dono do seu proprio caminho de escrita.
+
+**Starlette em vez de FastAPI.** Starlette ja vem como dependencia
+transitiva de `mcp`. Nenhuma dependencia nova foi adicionada ao
+`pyproject.toml`.
+
+**O indice unico nao entrou no `MIGRATION_SQL` comum.** `MIGRATION_SQL`
+roda a cada `initialize()`. Se um banco ja tiver duplicatas, criar o
+indice unico ali derrubaria o CLI inteiro. Ele ficou em
+`IDEMPOTENCY_INDEX_SQL`, executado em `try/except UniqueViolation` que
+apenas avisa. A conexao usa `autocommit=True`, entao a falha isolada nao
+envenena a transacao seguinte.
+
+**Duplicatas preexistentes nunca sao resolvidas automaticamente.** A
+regra constitucional proibe apagar memoria. A migracao falha de
+proposito nesse caso e traz no cabecalho a consulta de diagnostico, para
+decisao humana.
+
+**Os helpers de spool do plugin usam apenas a stdlib.** Se o plugin
+dependesse do pacote `orkmind` para estagiar, a garantia cairia
+exatamente no cenario que ela existe para cobrir. O custo e ter o
+algoritmo de hash declarado nos dois lados, e ha um teste que trava essa
+equivalencia (`test_hash_bate_com_o_do_core`).
+
+**Simetria de hash no servidor.** Se o cliente enviar `content_hash`, o
+servidor recomputa e rejeita divergencia. Sem isso, um cliente poderia
+registrar conteudo sob o hash de outro, ocupando a chave de dedupe de um
+conteudo legitimo que ainda nao existe. O conteudo verdadeiro chegaria
+depois e seria descartado como duplicata: perda silenciosa de memoria.
+
+## 4. Testes executados
+
+### 4.1 Suite completa
+
+```
+ORKMIND_TEST_DATABASE_URL=postgresql://orkmind:orkmind@localhost:5432/orkmind_test \
+  .venv/bin/python -m pytest -q
+```
+
+**Resultado: 537 passaram, 0 falharam** (21,27s).
+
+Conferencia da conta: 429 preexistentes + 108 novos = 537.
+
+| Arquivo novo | Testes | Cobertura |
+|---|---|---|
+| `tests/unit/test_spool.py` | 31 | Contrato em disco, hash, backoff, serializacao |
+| `tests/unit/test_api_seguranca.py` | 33 | Auth, simetria de hash, idempotencia, governanca |
+| `tests/unit/test_hermes_plugin_spool.py` | 21 | Ordem de escrita, honestidade do id |
+| `tests/integration/test_sempre_gravar.py` | 23 | Indice unico, lookup, drainer ponta a ponta |
+| **Total novo** | **108** | |
+
+Os 23 testes de integracao rodaram de fato (nao pularam), com
+`ORKMIND_TEST_DATABASE_URL` apontando para `orkmind_test`.
+
+### 4.2 Banco de teste (nao producao)
+
+O banco `orkmind_test` foi **criado nesta rodada** (nao existia) em
+`postgresql://orkmind:orkmind@localhost:5432/orkmind_test`, com a
+extensao `vector`, e as migracoes foram aplicadas ali.
+
+A guarda de `tests/conftest.py` (`resolve_test_database_url`) nao foi
+tocada. Ela ja recusa qualquer URL cujo nome de banco nao tenha marcador
+de teste, e como o `ORKMIND_DATABASE_URL` do ambiente aponta para
+`orkmind` (producao, sem marcador), os testes de integracao pulam por
+padrao em vez de rodar contra producao.
+
+Indices confirmados no banco de teste:
+
+```
+['idx_memories_content_hash', 'uq_memories_collection_content_hash']
+```
+
+### 4.3 Auditoria de contaminacao de producao
+
+Antes e depois da rodada, com a base de producao `orkmind`:
+
+| Verificacao | Resultado |
+|---|---|
+| Total de entries antes | 50 |
+| Total apos backfill | 51 (apenas o orfao recuperado) |
+| Busca por 10 padroes de conteudo de teste | **NENHUM vestigio** |
+| Indices criados em producao pela rodada | **NENHUM** (nunca rodamos `initialize()` contra producao) |
+
+Padroes buscados: `conteudo de teste`, `memoria de teste`,
+`Integration test`, `item numero`, `nao deve ser gravado`,
+`conteudo drenado`, `drenado pelo teste`, `conteudo repetido`,
+`conteudo unico`, `teste de integracao`.
+
+O banco de teste foi limpo ao fim da validacao.
+
+### 4.4 Validacao ao vivo da API
+
+API subida com `orkmind api --port 8077` contra o **banco de teste**,
+com `ORKMIND_API_TOKEN` definido. Escuta confirmada em `127.0.0.1:8077`
+(nunca `0.0.0.0`).
+
+| # | Cenario | Esperado | Obtido |
+|---|---|---|---|
+| 1 | POST sem token | 401 | 401 |
+| 2 | POST com token errado | 401 | 401 |
+| 3 | POST valido | 201 `created` | `created`, id `dcc76fbc-...` |
+| 4 | POST repetido | `duplicate`, mesmo id | `duplicate`, id `dcc76fbc-...` |
+| 5 | GET by-hash | `found` com id | `found`, id `dcc76fbc-...` |
+| 6 | POST com hash divergente | 400 | 400, com `expected`/`received` |
+| 7 | `source=agent` + `mandatory=true` | 403 | 403 |
+
+Confirmado tambem que a resposta de erro de credencial nao ecoa o token,
+e que o lookup por hash nao devolve o conteudo (teste
+`test_lookup_nao_devolve_conteudo`).
+
+### 4.5 Drainer ponta a ponta
+
+**Backend API (caminho preferencial):**
+
+```
+1a drenagem: item ... gravado via api: entry_id=0ecd0482-... status=created
+2a drenagem: item ... ja existia: entry_id=0ecd0482-... (duplicate)
+```
+
+**Backend CLI (fallback), usado no backfill real:** ver secao 5.
+
+**Backend totalmente fora** (API derrubada, `--no-cli`):
+
+```
+WARNING backend api falhou: api store indisponivel: [Errno 111] Connection refused
+WARNING item ... falhou (tentativa 1/8), novo retry em 2026-08-31T16:01:18
+passada: {'total': 1, 'created': 0, 'duplicate': 0, 'falha': 1, ...}
+```
+
+Estado do item retido, verificado em disco:
+
+```
+entry_id : None      <- nao inventou id
+status   : pending   <- continua na fila
+attempts : 1
+retry em : 2026-08-31T16:01:18-03:00
+conteudo : integro no .md
+```
+
+**Item corrompido** (hash que nao descreve o conteudo em disco): vai
+direto para `failed/` sem nunca ser gravado, com o conteudo preservado
+para revisao (`test_item_corrompido_vai_para_failed`).
+
+### 4.6 Qualidade de codigo
+
+| Verificacao | Resultado |
+|---|---|
+| `ruff check` nos arquivos novos/alterados | All checks passed |
+| `mypy` em `spool.py` e `api/app.py` | Success: no issues found |
+| em-dash (U+2014) / en-dash (U+2013) nos arquivos novos | **nenhum** |
+| Espanhol | nenhum (grep marcou `porque` e `usuario`, ambos pt-BR validos) |
+
+Os avisos de `E501` remanescentes em `postgres_adapter.py` e
+`test_semantic_layer.py` sao preexistentes, em trechos nao tocados.
+
+## 5. Backfill dos orfaos legados (R13)
+
+Diagnostico previo de producao: **nenhuma duplicata** `(collection,
+content_hash)` e **zero** entries sem `content_hash`. A migracao F4 e
+aplicavel a producao sem conflito.
+
+Ensaio a seco identificou 1 orfao em `~/.hermes/reports/`. Comando real:
+
+```bash
+.venv/bin/python scripts/orkmind_drain.py \
+  --backfill ~/.hermes/reports --collection content \
+  --tags '{"project": ["possibilidades-ia"], "situation": ["semanal"]}' \
+  --priority medium --source agent --once
+```
+
+**1 orfao drenado.** Entry id real retornado pelo backend:
+
+| Arquivo | entry_id | Colecao | Hash |
+|---|---|---|---|
+| `possibilidades-ia-2026-W36.md` | `b4b19995-ed92-42e1-b9ba-db5585179512` | `content` | `9f76116d4809e0ed...` |
+
+Conferido no banco de producao:
+
+```
+colecao   : content
+prioridade: medium
+source    : agent
+tags      : {'project': ['possibilidades-ia'], 'situation': ['semanal']}
+tamanho   : 8460 chars   (8673 bytes UTF-8, conteudo verbatim)
+```
+
+**Idempotencia verificada apos o backfill:**
+
+1. Backfill repetido: `0 itens estagiados` (hash ja conhecido na spool).
+2. Reestagio forcado do mesmo conteudo + drenagem:
+   `status=duplicate`, mesmo `entry_id=b4b19995-...`.
+3. Producao segue com **51 entries**, e **1 unica copia** do relatorio.
+
+O arquivo de origem em `~/.hermes/reports/` foi preservado intacto: o
+backfill nao apaga nem move a origem.
+
+## 6. Arquivos
+
+### Novos
+
+| Arquivo | Papel |
+|---|---|
+| `src/orkmind/spool.py` | Contrato da fila de saida em disco |
+| `src/orkmind/api/__init__.py` | Pacote da API |
+| `src/orkmind/api/app.py` | API idempotente (Starlette) |
+| `scripts/orkmind_drain.py` | Drainer externo |
+| `migrations/f4_content_hash_idempotencia.sql` | Indice unico parcial |
+| `docs/sempre-gravar.md` | Documentacao da arquitetura |
+| `integrations/hermes/orkmind/CHANGELOG.md` | Changelog do plugin |
+| `tests/unit/test_spool.py` | 31 testes |
+| `tests/unit/test_api_seguranca.py` | 33 testes |
+| `tests/unit/test_hermes_plugin_spool.py` | 21 testes |
+| `tests/integration/test_sempre_gravar.py` | 23 testes |
+
+### Alterados
+
+| Arquivo | Mudanca |
+|---|---|
+| `src/orkmind/store/base.py` | Contrato `find_by_content_hash` |
+| `src/orkmind/store/postgres_adapter.py` | Implementacao + indices F4 |
+| `src/orkmind/cli/main.py` | `add --content-hash/--dedupe/--json`, comando `api` |
+| `integrations/hermes/orkmind/__init__.py` | Spool + reordenacao do store |
+| `integrations/hermes/orkmind/plugin.yaml` | 1.0.0 -> 1.1.0 |
+| `integrations/hermes/orkmind/README.md` | Secao de gravacao garantida |
+| `scripts/sync_hermes_plugin.sh` | Publica tambem o CHANGELOG |
+| `README.md` | Secao Guaranteed Writes + link de docs |
+| `CHANGELOG.md` | Secao Unreleased |
+
+O plugin vivo em `~/.hermes/plugins/orkmind/` foi publicado a partir da
+copia versionada via `scripts/sync_hermes_plugin.sh`, como manda a
+convencao. A copia viva nunca foi editada diretamente, e segue
+funcionando na versao 1.1.0.
+
+## 7. Pendencias para o orquestrador
+
+Nada abaixo foi feito, por estar fora do escopo do executor:
+
+1. **Push do core.** Commits locais em `main`, sem push nem merge.
+2. **Migracao em producao.** Aplicar
+   `migrations/f4_content_hash_idempotencia.sql` na base `orkmind`.
+   Diagnostico ja feito: nenhuma duplicata, aplicavel sem conflito.
+   Sem o indice, a idempotencia continua valendo por lookup (API e CLI
+   `--dedupe`), mas falta a rede de seguranca contra drainers
+   concorrentes.
+3. **Cron do drainer (R10).** Criar o job dedicado em
+   `~/.hermes/cron/jobs.json` com `enabled_toolsets: ['terminal','file']`
+   e frequencia de 1 a 5 min, chamando
+   `.venv/bin/python ~/OrkMind/scripts/orkmind_drain.py --once`.
+   Enquanto ele nao existir, a fila so drena quando alguem rodar o
+   comando: o conteudo esta seguro, mas a reconciliacao nao e automatica.
+4. **Toolset minimo nos crons (R12).** Exigir `terminal/file/memory` em
+   todo job agendado. Depende do runner do Hermes, fora deste repo.
+5. **Timer systemd (R11).** Garantia dura, independente de o Hermes estar
+   vivo. E o destino final recomendado para o drainer.
+6. **Servico da API + token (R14).** A API nao esta rodando como servico.
+   Definir `ORKMIND_API_TOKEN` num segredo do sistema e subir
+   `orkmind api` sob systemd. Sem ela, o drainer opera pelo fallback CLI,
+   que foi validado e funciona, mas a API e o caminho preferencial.
+   Manter sempre em `127.0.0.1`.
+7. **Rodar no Hermes.** O plugin 1.1.0 esta publicado, mas nao foi
+   exercitado dentro de uma sessao real do Hermes nesta rodada.
+8. **DSN em segredo do sistema.** Hoje `ORKMIND_DATABASE_URL` vem do
+   ambiente do shell. O drainer sob systemd precisara dele no
+   `EnvironmentFile`.
+
+## 8. Estado final
+
+- Suite: **537 passaram, 0 falharam**.
+- Producao: **51 entries**, intacta, sem contaminacao de teste.
+- Orfaos: **0 pendentes**; 1 recuperado com id real.
+- Spool: `pending=0`, `done=2`, `failed=0`.
+- Plugin vivo: versao 1.1.0, sincronizado do versionado.