Memória que você consegue encontrar de novo.

01. Instalar e conectar

Use Python 3.11 ou superior. O backend padrão é PostgreSQL com a extensão pgvector. Prepare uma instância de banco para o seu ambiente antes de gravar memórias.

python3 -m venv .venv
source .venv/bin/activate
pip install orkmind

Na configuração abaixo, substitua os campos entre sinais de menor e maior pelos dados da sua conexão. Em ambientes compartilhados, peça ao responsável as credenciais e permissões apropriadas.

# Use os dados do seu banco, sem guardar senhas no Git
export ORKMIND_DATABASE_URL="postgresql://<usuario>:<senha>@<host>:5432/<banco>"
orkmind store info
orkmind stats

store info mostra o backend ativo, as capacidades e os avisos. stats ajuda a conferir se a memória está acessível. O backend memory é volátil e serve para testes; seus dados terminam com o processo.

Configurar ou trocar o backend ↗

02. Sua primeira memória

Comece com uma decisão curta e compreensível fora da conversa em que ela nasceu. Informe a coleção e as tags que permitirão encontrá-la depois.

orkmind add --collection decision   --content "Usar revisão antes de publicar alterações"   --tags '{"project": ["meu-projeto"], "skill": ["deploy"]}'   --dedupe --json

O retorno em JSON inclui a identificação da entrada. A opção --dedupe solicita uma escrita idempotente: quando o backend oferece a garantia necessária, o mesmo conteúdo não cria outra entrada. Confira os limites do seu backend em store info.

Inclua o motivo e as condições da decisão no conteúdo quando forem necessários para usá-la corretamente. Não copie credenciais ou uma conversa inteira como substituto de uma memória bem delimitada.

03. Coleções, tipos e tags

A coleção organiza uma memória. O tipo ontológico diz o que uma entidade é. As tags descrevem onde o conteúdo se aplica. São 23 coleções de memória e 11 dimensões de contexto; esses números não contam os tipos do Company Brain.

As dimensões incluem skill, agent, domain, project, situation, person, audience, editors, prod, proj e init. A dimensão legada project continua identificando isolamento e federação; proj identifica o projeto de produto na nova hierarquia.

Tags organizam o contexto. Elas não substituem autenticação nem autorização de acesso.

04. Produtos, projetos e iniciativas

Use o catálogo de portfólio para dar ao roadmap uma semântica estável. Um produto contém vários projetos. Cada projeto pertence a um produto, pode envolver vários repositórios e contém iniciativas. Uma iniciativa pode depender de outra iniciativa do mesmo projeto.

orkmind portfolio create product prod-orkastery   --title "Orkastery"

orkmind portfolio create project proj-company-brain   --title "Company Brain" --parent prod-orkastery   --workspace orkastery --workspace orkmind --workspace orkmind-web

orkmind portfolio create initiative init-library-query   --title "Consulta governada" --parent proj-company-brain

orkmind portfolio list --json

Os prefixos prod-, proj- e init- evitam ambiguidade entre os três níveis. O catálogo recusa pai ausente e dependência fora do projeto. No Orkastery, o ciclo vincula esse escopo ao Objective Envelope.

05. Recuperar contexto

orkmind list --collection decision
orkmind search --tags '{"project": ["meu-projeto"], "skill": ["deploy"]}'
orkmind detect --text "Preparar o deploy do projeto"

list permite explorar uma coleção. search consulta o contexto informado. detect ajuda a reconhecer contexto em um texto; confira as tags inferidas antes de usá-las em uma automação importante.

Na busca determinística, valores de uma mesma dimensão funcionam como alternativas e dimensões distintas restringem o contexto em conjunto. A busca semântica é uma capacidade adicional, dependente da configuração.

As camadas E1, E2 e E3 permitem carregar contexto progressivamente: essência, estrutura e fonte completa. Regras mandatórias recebem tratamento próprio. O orçamento de tokens e as regras de governança influenciam o contexto entregue ao agente.

06. Permissões e regras

Mandatory indica uma entrada que deve participar da recuperação quando corresponde ao contexto autorizado. Não significa acesso global nem permite ignorar filtros de segurança.

Entradas protegidas e regras críticas têm restrições de alteração. Conflitos entre regras mandatórias podem exigir revisão humana antes da injeção. Conteúdo suspeito pode ser preservado para análise e excluído do contexto automático.

Se uma operação for recusada, confira a identidade, o escopo e o motivo informado. Não use o acesso direto ao armazenamento para contornar a camada governada.

07. Memória federada por projeto

A federação mantém uma memória fisicamente separada para cada projeto e permite recall somente leitura entre fontes autorizadas. O resultado conserva source, project e producer; uma fonte indisponível é declarada sem apagar os resultados saudáveis das demais.

orkmind federation profile-set --id julio --display-name "Julio"   --role system_owner --manifest ~/.orkmind/federation.json

orkmind federation profile-set --id builder-web --display-name "Builder Web"   --role builder --projects orkastery,orkmind   --manifest ~/.orkmind/federation.json

orkmind federation recall --requester-id julio --caller hermes   --collection decision --tags '{"skill":["roadmap"]}'   --manifest ~/.orkmind/federation.json

system_owner acessa os projetos do manifesto. Um builder acessa somente os projetos e fontes atribuídos. Um agent também precisa de current_project e fica limitado a ele. Depois dessa checagem, a ACL da própria entrada continua valendo.

Guarde apenas nomes de variáveis no manifesto e mantenha os DSNs no ambiente. Ork, Hermes, OpenClaw, Claude Code e Codex usam o mesmo contrato e identificam o canal em --caller.

08. Usar com agentes

O OrkMind oferece CLI, servidor MCP e integração com hosts compatíveis. Configure a conexão no ambiente do processo que executará o agente; a configuração do seu terminal pode não chegar ao host.

Para o MCP, o ponto de entrada documentado é python -m orkmind.mcp. Use o Python do ambiente em que o pacote foi instalado e forneça a conexão por variável de ambiente.

No Orkastery, consulte ork memory status para distinguir o regime solicitado do efetivo. O OrkMind Web oferece uma interface para explorar e trabalhar com a memória; sua instalação é separada da biblioteca.

09. Usar no Orkastery

O Orkastery integra a biblioteca instalada sem copiar a lógica do OrkMind. O manifesto informa o tenant e o nome da variável que contém a conexão; a credencial permanece fora do Git.

ork memory status --json
ork memory sync <thread> --json
ork recall <thread> --fase GOAL --json

memory status distingue o regime solicitado do regime efetivo. memory sync publica somente o material elegível da thread informada. recall recupera o contexto da fase e respeita tenant, thread, coleção e janela.

Decisões humanas vindas do Telegram usam um ingresso autenticado. No Claude Code e no Codex, o formulário MCP produz um recibo local assinado e ligado ao pedido e ao veredito. A publicação recusa recibo ausente, reutilizado ou uma recusa reescrita como aprovação.

Na integração local, a conta do sistema operacional é a fronteira de confiança. Separe o servidor MCP em outra conta ou sandbox quando agentes sob o mesmo usuário não puderem ler a chave privada.

10. Entender o Company Brain

Company Brain é a camada governada que conecta o que a empresa sabe, decide e entrega. No corte C1, produtos, projetos, iniciativas, fases, pedidos HITL, decisões, resultados, claims e artefatos compartilham identidades estáveis e proveniência consultável.

Memória não é autoridade. A identidade é derivada do transporte autenticado, e a ACL é revalidada em cada operação. Escritas usam revisão esperada; versões anteriores permanecem no histórico. Receipts, outbox, readback, reconciliação e rollback tornam falhas observáveis em vez de silenciosas.

Os próximos pacotes ampliarão organização, geografias, sistemas, estratégia, coleções e fontes empresariais. Atlas, cuidadores e dados analíticos continuam no roadmap; não são capacidades disponíveis neste corte.

11. Biblioteca e memória operacional

O OrkMind Web usa o backend B1 real para sessão, busca, leitura e escrita de documentos e decisões. Não existe fixture ou fallback de produção: ausência de conexão, permissão ou revisão correta aparece como falha explícita.

# No OrkMind Web autenticado
GET /api/workspace/v1/session
POST /api/workspace/v1/library/search
GET /api/workspace/v1/library/records/proj-company-brain
PUT /api/workspace/v1/records/doc-minha-decisao

/knowledge é a Biblioteca principal: reúne memórias, documentos, decisões, produtos, projetos e iniciativas autorizados. Os filtros separam tipo, coleção e origem. Afirmações fact-<sha256> sem título útil ficam ocultas por padrão, mas podem ser incluídas ou isoladas sem apagar o dado. /memory permanece como a administração operacional das memórias.

Entidades de portfólio podem aparecer como “Sem coleção”, pois pertencem ao catálogo, não a um compartimento de memória. Documentos aceitam referências fixadas; uma edição concorrente obsoleta recebe conflito e não sobrescreve a versão atual.

A autenticação HTTP do workspace é single-user na instalação atual. O username enviado pelo cliente não define a identidade do Brain; o servidor usa o principal da conta operacional autenticada.

12. Orquestração via agentes

O OrkMind Web é uma superfície de conhecimento: Hoje, Biblioteca, Estratégia, documentos, decisões, memória e grafo. Ele não oferece Cockpit, Kanban, configuração de runtime nem ações de ciclo.

Para criar, acompanhar, aprovar, revisar ou interromper uma entrega, converse com Hermes, OpenClaw, Claude ou Codex. Os quatro hosts chegam ao mesmo núcleo do Orkastery, preservando identidade, Objective Envelope, gates, claims e evidências. A troca de host não cria uma segunda autoridade.

Produtos, projetos e iniciativas continuam visíveis na Biblioteca como entidades ontológicas do Company Brain. Vê-los no navegador não concede autorização de execução; comandos e decisões operacionais permanecem no canal autenticado do agente.

13. Resolver problemas