OpenExp

OpenExp

Como isso aconteceu? — um hipocampo para agentes de IA.
Capture trajetórias brutas. Avalie somente quando a realidade devolver seu veredito. Construa um corpus rotulado de decisões humano-IA ligadas a resultados concretos.

Início Rápido · Como Funciona · Pipeline · Publicar · Ferramentas MCP · Status

---

A Pergunta

Quando você fecha um negócio, entrega um recurso ou perde um cliente — como isso aconteceu? Quais decisões, em que ordem, contra qual contexto, com base em quais hipóteses? Os agentes de IA de hoje não conseguem responder isso. Eles seguem habilidades e instruções perfeitamente, mas não acumulam conhecimento fundamentado sobre como os resultados realmente chegaram.

O OpenExp captura cada decisão humano-IA como um passo em uma trajetória, liga esses passos em jornadas coerentes e avalia cada jornada retroativamente quando a realidade devolve seu veredito — um negócio fecha, um sprint é entregue, um pagamento cai. O resultado é um conjunto de dados rotulado em crescimento contínuo, de decisões ligadas a resultados, pronto para treinar intuição específica de domínio.

O Que Não É

• Não é um sistema de memória Q-learning. Tentamos valores Q por 8 meses. O valor Q médio em 27.000 memórias foi 0,006; 90% das memórias nunca receberam nenhum sinal de recompensa. Removido em 26/04/2026.
• Não é Mem0 / Zep / Letta. Esses são camadas de armazenamento. Armazenamento é a parte fácil — busca semântica sozinha não diz qual memória realmente levou a um resultado.
• Não substitui habilidades ou CLAUDE.md. Esses dizem como fazer algo. O OpenExp captura o que aconteceu e como terminou.

O Núcleo Metodológico: Sem Pré-Rotulação

Nós não criamos features manualmente no nível de passo (tone: urgent, signal: positive, hypothesis: probable). A pré-rotulação injeta os vieses do rotulador e corrompe o sinal de treinamento eventual. Mesma higiene da pontuação de crédito: colete features ricas por candidato, rotule apenas o resultado terminal (pagou / não pagou), deixe o modelo aprender o que prevê o reembolso apenas com os dados.

Somente resultados terminais recebem rótulos:

• outcome — closed_won / closed_lost / failed / abandoned
• grade — 0.0 a 1.0, estilo escolar

Os passos são armazenados brutos. Os autores anotam suas próprias intenções, hipóteses e decisões ("Eu acreditava em X neste ponto", "Escolhi Y porque Z"). Eles não rotulam a qualidade do sinal de eventos individuais — isso é o que o modelo eventual aprende.

Analogia casual: crianças na escola não recebem anotações em cada problema de dever de casa. Elas entregam o trabalho, recebem uma nota no final do período e desenvolvem intuição ao longo de centenas de notas.

Início Rápido

git clone https://github.com/anthroos/openexp.git
cd openexp
./setup.sh

Isso instala os quatro hooks no Claude Code, garante que o Qdrant esteja ativo e registra o servidor MCP.

Se algo já estiver servindo Qdrant na localhost:6333, o script o usa e não interfere. Caso contrário, ele inicia o Qdrant no Docker para você.

Pré-requisitos: Python 3.11+, jq e Qdrant — seja Docker (o script cuida do contêiner) ou um binário Qdrant nativo que você mesmo executa.

Nenhuma chave de API é necessária para a funcionalidade principal. Embeddings rodam localmente via FastEmbed. Uma chave de API Anthropic é opcional e só alimenta o pipeline de dois prompts (anonimizar + extrair experiência) quando você publica.

Como Funciona

Quatro hooks rodam automaticamente dentro do Claude Code:

Hook	Quando	O quê
SessionStart	Sessão abre	Busca memórias relevantes no Qdrant, injeta os principais resultados como contexto
UserPromptSubmit	Cada mensagem	Recuperação leve por prompt
PostToolUse	Após Write / Edit / Bash	Captura observações como JSONL
SessionEnd	Sessão fecha	Ingere a transcrição no Qdrant; extrai decisões via Opus 4.x (assíncrono)

A recuperação classifica por similaridade semântica + BM25 + recência. Sem números mágicos. Sem componente de pontuação Q-value.

O Pipeline

Quando você decide publicar uma experiência — transformar uma trajetória real e terminal em um artefato compartilhável — dois prompts fazem o trabalho:

1. prompts/anonymize.md — pega dados brutos de trajetória (transcrições, e-mails, decisões) e produz uma trajetória YAML anonimizada. PII é substituída por tokens de categoria (<counterparty_cto>, <regulated_industry>, <value:10k-100k>, <local_currency>, day_+5) enquanto features estruturais são preservadas. O prompt impõe uma regra de identificação reversa: tokens estreitos o suficiente para identificar uma contraparte na jurisdição devem ser generalizados um nível acima antes da publicação.

2. prompts/extract_experience.md — lê a trajetória anonimizada mais o rótulo de resultado terminal e produz um meta.yaml somente com fatos (id, rótulo de resultado, duração, contagem de passos, tokens de categoria, licença). Ele deliberadamente se recusa a escrever applies_when, searchable_summary ou um motivo de nota — essas são interpretações e pertencem ao Claude do leitor no momento do uso, não ao publicador no momento da publicação.

Você executa ambos os prompts dentro do seu próprio Claude Code, contra seu próprio Qdrant. Nada é enviado a um servidor central.

Publicando uma Experiência

Uma experiência publicada são quatro arquivos em um diretório nomeado por UUID (schema v3, 27/04/2026):

experiences/<uuid>/
├── meta.yaml                    # facts only: id, outcome label, duration, category tokens, license
├── trajectory.anonymized.yaml   # raw ordered timeline of N steps, anonymized
├── README.md                    # human-readable face for the marketplace
└── SKILL.md                     # Claude entry point — read first when skill is invoked

Formato meta.yaml (resumido da semente d49e0997):

pack:
  id: d49e0997-8455-4d3c-90ca-d6cf54d0f662
  author: ivan-pasichnyk
  license: MIT
  schema_version: 3

  outcome:
    label: closed_won            # fact, not interpretation
    closed_at: day_+57

  duration_days: 57
  step_count: 26

  category_tokens:               # what appears in the trajectory
    - <counterparty_cto>
    - <counterparty_pm>
    - <regulated_industry>
    - <e_signing_platform_local>
    # ...

Sem applies_when, sem searchable_summary, sem grade_reason. Schemas anteriores (v2) embutiam a leitura do publicador sobre a linha do tempo no artefato — a interpretação de um Claude, congelada. O schema v3 inverte isso: o pacote é enviado bruto, e o Claude do leitor deriva a correspondência em tempo real contra a situação real do leitor. Leitores diferentes, contextos diferentes, inferências diferentes da mesma trajetória. Veja CHANGELOG.md para a justificativa completa da transição v2 → v3.

Instalar como habilidade do Claude Code

Uma experiência publicada é uma habilidade do Claude Code com namespace:

openexp:<author-handle>:<experience-slug>

Coloque o pacote em ~/.claude/skills/openexp:<author>:<slug>/ (renomeie o diretório para a forma com namespace de habilidade ao copiar). O Claude Code o descobre automaticamente na próxima sessão.

# Install the seed pack as a skill
cp -r ~/openexp/experiences/d49e0997 \
  ~/.claude/skills/openexp:ivan-pasichnyk:inbound-acquisition-with-free-pilot

Duas camadas de identidade:

• A identidade do autor é pública — ela assina o pacote, como autoria em um artigo de pesquisa.
• A identidade da contraparte permanece anonimizada — o nome da habilidade revela quem criou o pacote, nunca com quem eles estavam lidando.

SKILL.md dentro do pacote é o ponto de entrada — ele diz ao Claude do usuário quando invocar, como usar a trajetória e o que não fazer (sem fabricação, sem desanonimização, atribuição obrigatória).

Veja docs/skill-architecture.md para a convenção de nomenclatura completa, fluxo de instalação e justificativa de design.

O diretório experiences/ neste repositório é a semente de um eventual marketplace. Pacotes publicados são listados em CATALOG.md. O formato de publicação funciona; as sementes se acumularão. Um diretório de experiências instaláveis é a superfície eventual, não um produto construído hoje.

Ferramentas MCP

Cinco ferramentas focadas (modelo hipocampo — escreva tudo, recupere seletivamente):

Ferramenta	Descrição
search_memory	Busca híbrida: similaridade semântica + BM25 + recência
add_memory	Armazena uma memória. Suporta client_id para marcação de entidades
log_prediction	Registra uma previsão fundamentada em pacote. Obrigatório quando um pacote de experiência instalado cita um relative_day específico como base para uma recomendação de ação.
log_outcome	Resolve uma previsão com o sinal observado — registro livre de interpretação.
memory_stats	Estatísticas da coleção: contagens de pontos por fonte/tipo, contagem de sessões

Instrumentação de previsão / resultado

Previsões fundamentadas em pacotes são como o sistema aprende se um pacote de experiência publicado realmente move resultados do mundo real. Sem pares previsão/resultado, o valor do pacote não pode ser medido contra qualquer linha de base, e qualquer experimento futuro (votação entre pacotes, recuperação por embedding, novos pacotes de novos autores) é infalsificável.

O critério de disparo é preciso. O registro só acontece quando o assistente cita o relative_day específico de um pacote como razão para uma recomendação de ação. Sem citação do dia → sem registro. Descrição de uma situação sem recomendação → sem registro. Isso mantém o conjunto de dados honesto e o custo baixo.

log_prediction (novo caminho, schema_version 2)

Campo	Obrigatório	Propósito
pack_id	sim	O slug do pacote
pack_author	sim	Identificador do autor
cited_step	sim	O day +N exato citado
case_id	sim	Referência externa (lead_id do CRM, ID do ticket, ID do negócio — string opaca)
applied_action	sim	O que foi recomendado FAZER
expected_signal	sim	Resolução observável
expected_window_days	sim	Prazo em dias para log_outcome
prevented_action	opcional	Previsão de espaço negativo — o que foi recomendado NÃO fazer (frequentemente a metade de maior valor)
notes	opcional	Contexto em texto livre

log_outcome (novo caminho, schema_version 2)

Campo	Obrigatório	Propósito
prediction_id	sim	ID retornado de log_prediction
actual_signal	sim	O que foi observado — fato bruto, sem interpretação
days_to_resolve	sim	Quantos dias da previsão até a resolução
notes	opcional	Texto livre, ex. eventos inesperados

O que está deliberadamente FORA do schema: confidence (a confiança do lado do Claude não é calibrada até ≥30 pontos de dados de resultado), alternative_action_if_no_pack e predicted_outcome_alternative (o mesmo Claude que escreve a previsão inventaria o contrafactual, tendencioso para "o pacote ajudou" — ablação real precisa de uma execução sem pacote, trilha separada).

Compatibilidade retroativa. O schema legado (prediction, confidence, strategic_value, memory_ids_used) ainda é aceito por ambas as ferramentas e registrado como dados. A partir de 03/07/2026 nada atualiza valores Q — o motor Q está totalmente deletado. Entradas do novo caminho são marcadas como schema_version: 2 na linha JSONL.

CLI

openexp search -q "stalled enterprise procurement" -n 5
openexp ingest          # ingest pending transcripts into Qdrant
openexp stats           # collection + prediction stats

Configuração

Variáveis de ambiente (.env):

Variável	Padrão	Descrição
QDRANT_HOST	localhost	Host do servidor Qdrant
QDRANT_PORT	6333	Porta do servidor Qdrant
OPENEXP_COLLECTION	openexp_memories	Nome da coleção Qdrant
OPENEXP_DATA_DIR	~/.openexp/data	Previsões, logs de recuperação
OPENEXP_OBSERVATIONS_DIR	~/.openexp/observations	Saída do hook
OPENEXP_SESSIONS_DIR	~/.openexp/sessions	Resumos de sessão
OPENEXP_EMBEDDING_MODEL	BAAI/bge-small-en-v1.5	Modelo de embedding (local, gratuito)
ANTHROPIC_API_KEY	(opcional)	Necessário apenas para o pipeline de publicação

Status

Piloto. Congelamento de arquitetura em 26/04/2026. Primeira semente de experiência publicada: experiences/d49e0997/ — uma aquisição inbound de 57 dias que fechou com nota 1.0 (avaliação do próprio autor), anonimizada em tokens de categoria.

Sendo honesto sobre o que não está feito:

• A UI do marketplace é apenas um diretório neste repositório. Sem superfície web ainda.
• A anonimização é conservadora, mas não à prova de balas para leitores com conhecimento profundo de domínio.
• O schema pode iterar — campos de anotação do autor (author_intent, author_hypothesis, author_decision) são uma adição provável em curto prazo.
• O modelo de ML eventual treinado neste corpus ainda não existe. ≥30 trajetórias avaliadas primeiro.

Veja docs/redesign-2026-04-26.md para o congelamento completo da arquitetura e docs/claude-design-brief.md para o enquadramento do produto v2.

Contribuindo

Este projeto está em estágios iniciais. Consulte CONTRIBUTING.md para configuração e fluxo de trabalho.

A contribuição mais útil agora é publicar uma experiência real. Pegue uma de suas próprias trajetórias fechadas, execute-a por meio de prompts/anonymize.md e prompts/extract_experience.md, e abra um PR adicionando um novo diretório em experiences/.

Licença

MIT © Ivan Pasichnyk