mini-tars 0.0.1__tar.gz

mini_tars-0.0.1/.claude/agents/construtor.md

@@ -0,0 +1,15 @@
+---
+name: construtor
+description: Implementa uma fatia do mini-Tars a partir de 01-definir/, com teste e avaliação. Use quando houver uma especificação pronta e aprovada.
+tools: Read, Write, Edit, Glob, Grep, Bash
+---
+Você implementa o mini-Tars, um servidor de memória MCP em Python. Leia `CONTEXT.md` e `CLAUDE.md` antes de tudo.
+
+Como trabalhar:
+- Implemente só a fatia pedida, ligada a IDs de `01-definir/requisitos.md` (RF-xx, RNF-xx). Não amplie o escopo.
+- Toda mudança de comportamento vem com teste (`tests/`) ou caso em `evals/`.
+- A busca é a medida em `evals/`; não altere o algoritmo sem experimento e conjunto de teste novos. Nunca leia nem rode `evals/teste-reservado.json`.
+- Datas em America/Sao_Paulo; nenhum dado real em testes, fixtures ou logs; nenhum log com o texto dos fatos.
+- Nunca leia ou edite `.env`, chaves ou credenciais; nunca publique, faça push ou deploy.
+- Se a especificação estiver ambígua, registre a dúvida em `docs/handoff.md` e siga a opção mais conservadora, dizendo qual foi.
+Ao terminar, entregue: o que mudou (arquivos), quais requisitos ficam atendidos, como verificar (comando), o que ficou de fora. O revisor vai ler seu diff sem ver esta conversa.

mini_tars-0.0.1/.claude/agents/revisor.md

@@ -0,0 +1,14 @@
+---
+name: revisor
+description: Revisa o diff de uma fatia do mini-Tars contra a especificação. Somente leitura, contexto separado. Use depois que o construtor terminar.
+tools: Read, Glob, Grep, Bash
+---
+Você revisa código do mini-Tars e NÃO edita nada. Não confie no resumo do construtor: leia o diff e rode os testes.
+
+Confira, nesta ordem:
+1. O diff atende os requisitos citados (`01-definir/requisitos.md`) e nada além? Aponte escopo extra.
+2. Há teste para cada comportamento novo e ele falharia se o código estivesse errado?
+3. Segurança: escuta local por padrão, token fora do local, texto dos fatos tratado como dado, nenhum segredo, nenhum log com conteúdo dos fatos.
+4. Regras do `CLAUDE.md`: fuso America/Sao_Paulo, sem dado real, nada de `.env`, nada do conjunto reservado.
+5. O algoritmo de busca continua igual ao medido em `evals/`.
+Responda com: aprovado ou não, lista de problemas por gravidade (com arquivo e linha), e o que você verificou e como. Se não conseguiu verificar algo, diga.

mini_tars-0.0.1/.claude/hooks/verify.py

@@ -0,0 +1,21 @@
+#!/usr/bin/env python3
+"""Gancho de parada: roda os testes antes de o agente encerrar.
+
+Se falharem, devolve código 2 e a mensagem, e o agente continua para corrigir.
+Se o gancho já bloqueou uma vez neste turno (stop_hook_active), deixa parar para não entrar em laço.
+"""
+import json, subprocess, sys
+
+try:
+    payload = json.load(sys.stdin)
+except Exception:
+    payload = {}
+if payload.get("stop_hook_active"):
+    sys.exit(0)
+if not __import__("os").path.isdir("tests"):
+    sys.exit(0)
+r = subprocess.run([sys.executable, "-m", "pytest", "-q", "-x"], capture_output=True, text=True)
+if r.returncode not in (0, 5):  # 5 = nenhum teste coletado
+    sys.stderr.write("Testes falharam; corrija antes de encerrar:\n" + (r.stdout + r.stderr)[-1500:])
+    sys.exit(2)
+sys.exit(0)

mini_tars-0.0.1/.claude/settings.json

@@ -0,0 +1,34 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(python -m pytest:*)",
+      "Bash(python3 -m pytest:*)",
+      "Bash(python3 evals/run_exp03.py:*)",
+      "Bash(git status:*)",
+      "Bash(git diff:*)",
+      "Bash(git log:*)"
+    ],
+    "deny": [
+      "Read(./.env)",
+      "Read(./.env.*)",
+      "Read(**/*.pem)",
+      "Read(**/*secret*)",
+      "Read(**/*credential*)",
+      "Edit(./.env)",
+      "Edit(./.env.*)",
+      "Bash(git push:*)",
+      "Bash(twine:*)",
+      "Bash(python -m twine:*)",
+      "Bash(pip publish:*)",
+      "Bash(uv publish:*)",
+      "Bash(rm -rf:*)",
+      "Read(./evals/teste-reservado.json)",
+      "Bash(*teste-reservado*)"
+    ]
+  },
+  "hooks": {
+    "Stop": [
+      { "hooks": [ { "type": "command", "command": "python3 .claude/hooks/verify.py" } ] }
+    ]
+  }
+}

mini_tars-0.0.1/.github/workflows/ci.yml

@@ -0,0 +1,81 @@
+name: ci
+on:
+  push:
+  pull_request:
+permissions:
+  contents: read
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ["3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - run: python -m pip install -e ".[dev]"
+      - name: Testes e avaliações (regressão da busca)
+        run: python -m pytest -q
+
+  test-windows:
+    # Confirma no Windows o que o job `test` já confirma no Linux (achamos um bug só
+    # visível lá: arquivo de banco aberto ao apagar a pasta temporária, corrigido em 2026-09-24).
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python -m pip install -e ".[dev]"
+      - name: Testes e avaliações (regressão da busca)
+        run: python -m pytest -q
+
+  instalacao-limpa:
+    # RNF-06: instala só o pacote construído (sem as dependências de desenvolvimento) e
+    # confere que `mini-tars --version` e um ciclo guardar/buscar funcionam.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Constrói o pacote
+        run: |
+          python -m pip install build
+          python -m build
+      - name: Instala o pacote construído num ambiente novo, sem as dependências de dev
+        run: |
+          python -m venv /tmp/instalacao-limpa
+          /tmp/instalacao-limpa/bin/pip install dist/*.whl
+      - run: /tmp/instalacao-limpa/bin/mini-tars --version
+      - name: Guarda e busca um fato fictício (prova que o pacote funciona sozinho)
+        run: |
+          /tmp/instalacao-limpa/bin/python - <<'PY'
+          import tempfile
+          from pathlib import Path
+
+          from mini_tars.service import Service
+          from mini_tars.store import Store
+
+          d = Path(tempfile.mkdtemp())
+          svc = Service(Store(d / "m.db"))
+          svc.remember("fato fictício da instalação limpa")
+          resultado = svc.search("fato fictício instalação limpa")
+          assert resultado and resultado[0][0].text == "fato fictício da instalação limpa"
+          print("ok: instalação limpa funciona")
+          PY
+
+  dependencias:
+    # RNF-07: falha se alguma dependência tiver uma vulnerabilidade conhecida.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python -m pip install --upgrade pip setuptools
+      - run: python -m pip install -e ".[dev]" pip-audit
+      - name: Verifica vulnerabilidades conhecidas nas dependências
+        run: python -m pip_audit

mini_tars-0.0.1/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.pyc
+.venv/
+venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.env
+.env.*
+*.db
+*.db.bak

mini_tars-0.0.1/00-descobrir/assumptions.md

@@ -0,0 +1,18 @@
+---
+status: rascunho
+atualizado: 2026-09-23
+dono: Breno
+---
+# Hipóteses e riscos de aprendizado
+
+Ordenadas da mais arriscada para a menos. "Como testar" é o experimento mais barato que dá evidência.
+
+| # | Hipótese | Se for falsa | Como testar | Status |
+| --- | --- | --- | --- | --- |
+| H1 | Uma busca simples por palavra-chave recupera o fato certo na maioria dos casos | O projeto precisa de embeddings ou de outro método, e o escopo cresce | 30 fatos e 30 perguntas, medir acerto (ver `idea.md`) | Sustentada só em parte (2026-09-23): palavra-chave pura hit@3 72%, hit@1 41%, vocabulário 50%. Com o assistente reescrevendo a consulta: hit@3 83%, hit@1 55%, mas 5 de 6 perguntas sem resposta trazem ruído. Experimento 2 (124 fatos): hit@3 entre 55% e 72% (baseline) e entre 69% e 72% (reescrita), ruído 3 a 6 de 6; ganho da reescrita não confirmado como robusto. Experimento 3 (teste reservado, 18 perguntas): hit@3 72% (13/18) com desempate por regra, K1 passou por um acerto; ruído 4 de 5. Ver `decisions.md` e `evals/experimento-0{1,2,3}.md` |
+| H2 | Desenvolvedores têm esse problema com força suficiente para instalar algo novo | Fica só como projeto pessoal e de portfólio | Entrevistas puladas por decisão do Breno; só o uso real após o lançamento (K3) testa | Não validada (risco aceito) |
+| H3 | Desenvolvedores aceitam auto-hospedar (Docker ou Python local) em vez de usar um serviço pronto | Precisa de instalação de um comando ou de uma versão hospedada, que muda custo, legal e suporte | Teste de instalação limpa no CI; depois do lançamento, observar issues de instalação | Não validada (risco aceito) |
+| H4 | O Breno consegue manter o projeto e o suporte com o tempo que tem para estudo | Reduzir escopo ou o número de usuários | Registrar horas reais por semana nas 6 primeiras semanas | Não testada |
+| H5 | Uma memória própria oferece algo que alternativas existentes não oferecem | Melhor usar uma existente e focar o aprendizado em outra coisa | Pesquisa de concorrentes na fase 1 (fontes verificadas, estado atual) | Refutada como produto novo: o Basic Memory já cobre o mesmo espaço (ver `competitors.md`) |
+
+Regra: uma hipótese só muda de status com evidência registrada em `docs/decisions.md`.

mini_tars-0.0.1/00-descobrir/competitors.md

@@ -0,0 +1,46 @@
+---
+status: rascunho
+atualizado: 2026-09-23
+dono: Breno
+fontes: páginas dos repositórios no GitHub, abertas em 2026-09-23
+---
+# Concorrentes e alternativas (H5)
+
+Dados lidos nas páginas dos repositórios em 2026-09-23. Números de estrelas e versões mudam; confirmar antes de citar. Onde a página não informou, está marcado "não informado" (não significa que não exista).
+
+| Projeto | O que é | Licença | Estrelas | Armazenamento | MCP | Uso local |
+| --- | --- | --- | --- | --- | --- | --- |
+| [Basic Memory](https://github.com/basicmachines-co/basic-memory) | Memória em arquivos Markdown que humano e IA leem e escrevem; grafo de entidades, observações e relações | AGPL-3.0 | 3,6 mil | Markdown + SQLite (padrão) ou PostgreSQL | Sim (Claude Desktop, Claude Code, Cursor, VS Code, outros) | Sim; `uv tool install basic-memory` |
+| [Graphiti (Zep)](https://github.com/getzep/graphiti) | Grafo de contexto temporal para agentes (fatos com janela de validade) | Apache-2.0 | 29 mil | Banco de grafos: Neo4j, FalkorDB, Neptune | Sim (servidor MCP incluído) | Sim, com Docker Compose; exige banco de grafos |
+| [mem0](https://github.com/mem0ai/mem0) | Camada de memória para agentes de IA; busca híbrida (semântica, BM25, entidades) | Apache-2.0 | 65,9 mil | Vetorial (Qdrant citado); servidor com Docker Compose | Não informado na página | Sim, com Docker Compose; usa modelos da OpenAI por padrão |
+| [Letta](https://github.com/letta-ai/letta) | Plataforma de agentes com estado e memória própria | Apache-2.0 | 24,7 mil | Não detalhado na página | Não informado claramente | Servidor local (`letta server`) e nuvem própria |
+| [Tars](https://github.com/fonsecabc/tars) | Memória pessoal de usuário único, exposta ao Claude por MCP | MIT | 2 | PostgreSQL com pgvector | Sim (13 ferramentas) | Sim; Node.js, Docker |
+
+Fonte adicional: README do Tars enviado pelo Breno (benchmark LOCOMO com modelos locais).
+
+## O que isso diz sobre H5
+
+**H5 ("uma memória própria oferece algo que as existentes não oferecem") não se sustenta como produto novo.** O concorrente mais próximo é o **Basic Memory**: Python, SQLite local, MCP, distribuição por PyPI, instalação em um comando, grafo de entidades e observações. É essencialmente o que o mini-Tars pretende ser, com 3,6 mil estrelas e mais de 1.700 commits.
+
+Diferenças possíveis do mini-Tars, ainda não validadas:
+
+- **Método de avaliação como parte do produto** (placar de recuperação reproduzível, como o benchmark do Tars). Nenhuma das páginas lidas destacou isso, mas não conferi a documentação interna de cada uma.
+- **Escopo muito menor e mais simples de entender**, útil para aprender.
+- **Licença permissiva** (MIT ou Apache) em vez de AGPL, relevante para quem não quer copyleft.
+
+## Consequência para o projeto
+
+Como as entrevistas foram puladas (H2, H3) e a H5 fica fraca, o projeto se sustenta hoje **como aprendizado e portfólio**, não como produto que compete no mercado. Isso muda a decisão sobre o esforço em onboarding, suporte e documentação para terceiros, que está proposto como "mínimo até haver sinal de uso" em `depth.md`.
+
+Opções para o Breno decidir (registrar em `docs/decisions.md`):
+
+1. **Manter o mini-Tars como projeto de aprendizado**, com foco em arquitetura, testes e avaliações, e divulgar sem promessa de suporte.
+2. **Reposicionar em torno das avaliações:** um pequeno kit de avaliação de recuperação de memória que funcione com qualquer servidor MCP (inclusive Basic Memory). Diferencia do que existe e é bom material de portfólio, mas exige validar que alguém quer isso.
+3. **Contribuir com o Basic Memory** em vez de criar outro, e usar o mini-Tars só como estudo privado. Aprende-se com código real e o portfólio mostra contribuição aceita.
+4. **Parar aqui** e escolher outro projeto de teste do processo (o critério K1 e a regra de "matar cedo" existem para isso).
+
+## Limites desta pesquisa
+
+- Leitura feita só das páginas iniciais dos repositórios, resumidas por ferramenta automática. Detalhes (por exemplo, suporte a MCP no mem0 e no Letta, motores de armazenamento do Letta) não foram confirmados na documentação.
+- Não foram avaliados serviços proprietários nem outros projetos de memória para MCP. Uma busca adicional por "MCP memory server" pode revelar mais alternativas.
+- Não testei nenhum deles na prática; a comparação de qualidade de recuperação depende do teste da fase 2.

mini_tars-0.0.1/00-descobrir/idea.md

@@ -0,0 +1,34 @@
+---
+status: rascunho
+atualizado: 2026-09-23
+dono: Breno
+---
+# Ideia
+
+## Problema (sem citar a solução)
+Quem trabalha com assistentes de IA em vários projetos perde contexto entre sessões. Decisões, preferências e o estado de cada projeto precisam ser repetidos. Quando ficam em arquivos soltos, eles se desatualizam e se contradizem, e o assistente age com informação velha.
+
+## Para quem
+Desenvolvedores que usam assistentes de IA (Claude Code e similares) em vários projetos. Primeiro usuário: o próprio Breno.
+
+## Modelo de distribuição
+Auto-hospedado: cada pessoa roda o servidor na própria máquina (ou no próprio servidor), com os próprios dados. O Breno não opera nem armazena dados de ninguém.
+
+## Por que agora
+O MCP virou um padrão para conectar ferramentas a assistentes de IA, e projetos como o Tars mostram que uma memória pessoal desse tipo é viável.
+
+## Objetivo do projeto
+Principal (decisão de 2026-09-23): **aprender e montar portfólio** com Python e FastAPI, MCP, testes e avaliações, e arquitetura com decisões registradas. Não é um produto que compete com o Basic Memory (ver `competitors.md`).
+Secundário: se outros desenvolvedores usarem, ótimo; isso é medido só por K3, sem promessa de suporte.
+
+## Hipótese mais arriscada
+A recuperação traz o fato certo, e não ruído, com uma busca simples. Se isso falhar, o resto do sistema não importa.
+
+## Validação barata (fase 2)
+Antes de construir o servidor:
+1. Escrever cerca de 30 fatos sobre um projeto do Breno e 30 perguntas com a resposta esperada.
+2. Medir quantas vezes uma busca simples por palavra-chave devolve o fato certo.
+3. Entrevistas com usuários: puladas por decisão do Breno (ver `docs/decisions.md`). A demanda de outros desenvolvedores só será testada pelo uso real, após o lançamento (K3).
+
+## Fora de escopo por ora
+Busca semântica com embeddings, versão hospedada, aplicativo móvel, painel web, cobrança.

mini_tars-0.0.1/00-descobrir/kill-criteria.md

@@ -0,0 +1,20 @@
+---
+status: rascunho (números a confirmar pelo Breno)
+atualizado: 2026-09-23
+dono: Breno
+---
+# Critérios de parada
+
+Definidos antes de investir. Formato: se [métrica] não atingir [valor] até [prazo], então [ação].
+Contagem de prazo começa na data de aprovação deste arquivo. Mudar um critério depois de ver o resultado é sinal de apego, não de aprendizado, e deve ser registrado em `docs/decisions.md`.
+
+| # | Se | Até | Então |
+| --- | --- | --- | --- |
+| K1 | A busca simples acertar menos de 70% das perguntas do teste da fase 2 | Fim da fase 2 | Testar uma alternativa (por exemplo, embeddings). Como é projeto de aprendizado, também é válido seguir e documentar o porquê da falha, desde que registrado em `decisions.md` |
+| K2 | (Removido em 2026-09-23: entrevistas puladas por decisão do Breno. A demanda passa a ser testada só por K3) | n/a | n/a |
+| K3 | Menos de 3 pessoas (além do Breno) usarem por pelo menos 3 sessões por semana | 6 semanas após o lançamento | Não é motivo para encerrar (projeto de aprendizado): manter só como portfólio, sem suporte ativo. Só reforça o corte de onboarding e documentação |
+| K4 | O Breno gastar mais de 5 horas por semana em suporte e manutenção | Qualquer semana, 2 vezes seguidas | Reduzir escopo ou pausar novos usuários |
+| K5 | Surgir qualquer custo recorrente para o Breno (meta: R$ 0 por mês) | Qualquer mês | Pausar o item que gera o custo ou migrar para alternativa gratuita |
+| K6 | Vulnerabilidade de segurança relevante encontrada em versão já distribuída | Imediato | Corrigir, publicar aviso e orientar atualização; se não houver correção em 7 dias, retirar a versão |
+
+Teto de custo confirmado pelo Breno: R$ 0. Stack gratuita: GitHub (repositório, Actions, Pages, registro de contêineres), PyPI e SQLite local.

mini_tars-0.0.1/01-definir/arquitetura.md

@@ -0,0 +1,105 @@
+---
+status: rascunho
+atualizado: 2026-09-23
+dono: Breno
+---
+# Arquitetura do MVP
+
+Decisões individuais, com alternativas e consequências, ficam em `docs/adr/`. Este arquivo mostra o conjunto. Os ADRs 0001 a 0005 foram aceitos pelo Breno em 2026-09-23.
+
+## Visão geral
+```
+ Assistente de IA (Claude Code etc.)  <-- cliente MCP
+        |                 |
+   stdio (padrão)     HTTP em 127.0.0.1 (opcional, token fora do local)
+        |                 |
+        +------ mini-tars (processo Python) ------+
+                 |
+        Camada MCP (ferramentas)   remember | search | forget | list_recent
+                 |
+        Serviço (regras): validação, datas, substituição, sinal de resultado fraco
+             |                          |
+     Busca (índice em memória)     Armazenamento (SQLite)
+     palavra-chave, desempate        um arquivo no diretório de dados do usuário
+     por regra (evals/)              migrações versionadas, backup antes de migrar
+
+ CLI: mini-tars serve | export | import | --version   (usa o mesmo Serviço)
+```
+Nenhuma chamada de rede de saída. Nenhum serviço do Breno.
+
+## Componentes e responsabilidades
+| Módulo (`src/mini_tars/`) | Responsabilidade | Depende de |
+| --- | --- | --- |
+| `models.py` | Tipos: Fato, Resultado, erros do domínio | nada |
+| `config.py` | Caminho dos dados, porta, token, limites; lê variáveis de ambiente | nada |
+| `store.py` | SQLite: criar, ler, substituir, apagar, migrar, backup antes de migrar | `models` |
+| `search.py` | Normalização, índice, pontuação, desempate por regra, sinal de resultado fraco. **Mesmo algoritmo de `evals/run_exp03.py`** | `models` |
+| `service.py` | Regras de negócio: valida entradas, aplica datas em America/Sao_Paulo, substituição, mantém o índice em sincronia com o banco | `store`, `search` |
+| `mcp_server.py` | Declara as ferramentas MCP e converte para chamadas do serviço; rotula texto de fato como dado | `service` |
+| `http_app.py` | Modo HTTP (FastAPI ou Starlette), token e escuta local | `mcp_server`, `config` |
+| `cli.py` | Comandos `serve`, `export`, `import` | `service`, `http_app` |
+
+Regra de dependência: de cima para baixo na tabela; `search.py` e `store.py` não se conhecem (é o `service.py` que os liga). Isso permite testar a busca sem banco e trocá-la (por exemplo, por embeddings) sem tocar no armazenamento.
+
+## Modelo de dados
+```sql
+CREATE TABLE facts (
+  id            INTEGER PRIMARY KEY,
+  text          TEXT    NOT NULL CHECK (length(text) BETWEEN 1 AND 2000),
+  fact_date     TEXT    NOT NULL,          -- AAAA-MM-DD, data local (America/Sao_Paulo)
+  project       TEXT,                      -- opcional
+  created_at    TEXT    NOT NULL,          -- UTC, ISO 8601
+  superseded_by INTEGER REFERENCES facts(id)  -- preenchido quando outro fato substitui este
+);
+CREATE INDEX idx_facts_project ON facts(project);
+-- versão do esquema: PRAGMA user_version
+```
+Regra de escrita: **uma afirmação por fato** (ver limite de RF-03 nos requisitos). Nada de campos livres extras no MVP.
+
+## Contratos das ferramentas MCP
+Todos os resultados incluem o texto do fato dentro de um campo `data`, com um aviso curto de que é conteúdo guardado pelo usuário e não instrução (RNF-02).
+
+| Ferramenta | Entrada | Saída |
+| --- | --- | --- |
+| `remember` | `text` (obrigatório), `date` (opcional, AAAA-MM-DD), `project` (opcional), `supersedes` (opcional, id) | `{id}` ou erro |
+| `search` | `query` (obrigatório), `limit` (1 a 10, padrão 3), `project` (opcional), `include_superseded` (padrão falso) | lista de `{id, data: {text, date, project}, score, weak_match, superseded_by?}` |
+| `forget` | `id` | `{deleted: true}` ou erro |
+| `list_recent` | `limit` (padrão 10), `project` (opcional) | lista de fatos ativos |
+
+Erros têm mensagem em português clara e código estável (`empty_text`, `text_too_long`, `unknown_id`, `invalid_date`).
+
+## Segurança (modelo de ameaças resumido)
+| Ameaça | Risco | Controle |
+| --- | --- | --- |
+| Porta aberta para a rede sem autenticação | R2 | Escuta em 127.0.0.1; outra interface só com token; recusa iniciar sem token (RNF-01) |
+| Texto guardado que tenta comandar o assistente | R3 | Saída marcada como dado, aviso na documentação; limite honesto: o servidor não controla o assistente (RNF-02) |
+| Dependência vulnerável | R5 | Poucas dependências, verificação no CI, versões fixadas (RNF-07) |
+| Perda de dados ao atualizar | R6 | Migração com backup antes; exportar e importar (RF-08, RNF-04) |
+| Vazamento por log | R3/R2 | Logs sem o texto dos fatos (RNF-03) |
+| Página de outro site chamando o servidor local pelo navegador | novo, a tratar no modo HTTP | Validar cabeçalho `Origin` e `Host`; recusar origens que não sejam locais |
+
+O último item foi identificado agora e ainda não está em `risks.md`: entra como R13 (ver `docs/risks.md`).
+
+## Estratégia de testes
+| Nível | O que cobre | Ferramenta |
+| --- | --- | --- |
+| Unitário | `search.py` (normalização, desempate, sinal fraco), `service.py` (validação, datas, substituição) | pytest |
+| Armazenamento | `store.py` com SQLite em arquivo temporário; migração de banco antigo | pytest |
+| Contrato MCP | Cliente MCP de teste chama as ferramentas nos dois modos e confere formato e erros | pytest |
+| Segurança | Bind sem token falha; cabeçalhos de origem; texto de injeção devolvido como dado; logs sem conteúdo | pytest |
+| Avaliações | `evals/` como regressão: hit@3 no ajuste ≥ 19 de 29; modos padrão e histórico registrados | script de `evals/` chamado no CI |
+| Instalação limpa | Instala o pacote construído e roda uma busca | job do CI |
+
+Fixtures: só os dados fictícios de `evals/`.
+
+## Distribuição e CI (nível Mínimo, planos gratuitos a confirmar)
+Pacote Python publicado no PyPI; imagem Docker opcional. CI no GitHub Actions: testes, avaliações, instalação limpa e verificação de dependências. **A publicação é sempre feita pelo Breno** (`CLAUDE.md`). Limites dos planos gratuitos ainda precisam ser confirmados na fonte oficial antes de depender deles.
+
+## Passo zero da construção: verificação técnica (feita em 2026-09-23)
+Confirmado no SDK Python do MCP (linha 2.x, `MCPServer`, `mcp>=2,<3`): stdio, HTTP e montagem no FastAPI funcionam; a proteção de `Host` e `Origin` já vem no SDK. Detalhes e ressalvas no ADR-0003.
+
+## Decisões do Breno (resolvidas em 2026-09-23)
+1. **Nome do pacote e do comando**: `mini-tars` (conferir se o nome está livre no PyPI antes de publicar).
+2. **Licença**: MIT.
+3. **Versão mínima do Python**: 3.11.
+4. **ADRs 0001 a 0005**: aprovados.

mini_tars-0.0.1/01-definir/requisitos.md

@@ -0,0 +1,54 @@
+---
+status: rascunho
+atualizado: 2026-09-23
+dono: Breno
+---
+# Requisitos do MVP
+
+Prioridade: **M** (precisa estar no MVP), **S** (deveria; entra se o tempo permitir), **C** (poderia; depois). Cada requisito tem critério de aceite que um teste ou uma avaliação consegue verificar, e uma origem (hipótese, risco ou decisão), para rastrear.
+
+## Funcionais
+| ID | Requisito | Prior. | Critério de aceite | Origem |
+| --- | --- | --- | --- | --- |
+| RF-01 | **Guardar fato** (`remember`): texto (até 2.000 caracteres), data do fato (padrão: hoje em America/Sao_Paulo) e projeto opcional | M | Devolve o id; o fato existe após reiniciar o servidor; texto vazio ou acima do limite é recusado com mensagem clara | idea.md |
+| RF-02 | **Buscar** (`search`): consulta em linguagem natural devolve até 3 fatos (configurável até 10) ordenados por relevância, com id, texto, data, pontuação e sinal de resultado fraco | M | Usa a busca base dos experimentos (palavra-chave, desempate por regra); no conjunto de ajuste `evals/cases.grande.json`, hit@3 ≥ 66% (19 de 29) | H1, R1, experimento 3 |
+| RF-03 | **Substituir fato** (`remember` com `supersedes`): marca o fato antigo como substituído; a busca padrão ignora os substituídos, e `include_superseded` traz também o histórico | M | Nos casos f16→f17 (preço) e f05→f18 (donos dos testes), a busca padrão devolve só o atual e com `include_superseded` devolve também o antigo. Atenção: a pergunta temporal q06 ("em março, quem olhava os testes?") tem como resposta o fato antigo f05, então só funciona no modo histórico; as avaliações precisam registrar o modo de cada pergunta, e o hit@3 dos dois modos é medido e registrado. Limite: substituir um fato esconde tudo o que ele dizia (f05 também dizia quem cuidava da infraestrutura); por isso a regra de escrita é **uma afirmação por fato** | M | tipos "corrigido" (50%) e "temporal" |
+| RF-04 | **Apagar fato** (`forget`): remoção definitiva por id | M | Após apagar, o fato não aparece em busca, exportação nem no arquivo do banco; apagar id inexistente devolve erro claro. **Limite documentado:** os arquivos de backup criados antes de uma migração (`.bak-vN`) mantêm o conteúdo antigo; o usuário deve apagá-los se quiser eliminar o fato de vez (README) | depth.md (dados) |
+| RF-05 | **Sinal de resultado fraco** (`weak_match`) no resultado da busca, sem filtrar | S | Definido a partir da pontuação relativa da consulta; medido nas avaliações e registrado. Meta (revista em 2026-09-23 depois de medir; ver decisions.md): as perguntas sem resposta do ajuste voltam vazias ou sinalizadas em pelo menos 5 de 6, e no máximo 1 em cada 5 primeiros resultados corretos é sinalizado por engano | R12; experimento 3 (filtro perdia acertos, sinal não) |
+| RF-06 | **Projeto** como espaço de nomes: `project` opcional em `remember`, `search` e `list_recent` | S | Busca com `project` só devolve fatos daquele projeto; a pontuação (idf) é calculada só dentro do projeto | idea.md |
+| RF-07 | **Listar recentes** (`list_recent`): últimos N fatos ativos | S | Ordem por data do fato, depois por criação | uso diário |
+| RF-08 | **Exportar e importar** por linha de comando, em JSON com versão do esquema | M | Exportar e importar em banco vazio reproduz o mesmo conteúdo (incluindo substituições); importar arquivo de versão desconhecida falha com aviso | R6, depth.md (backup) |
+| RF-09 | **Iniciar o servidor**: `mini-tars serve` (stdio por padrão) e `mini-tars serve --http` (HTTP local) | M | Um cliente MCP real lista as ferramentas e chama `remember` e `search` nos dois modos | idea.md |
+| RF-10 | **Configuração**: caminho do banco padrão no diretório de dados do usuário, alterável por variável de ambiente ou opção | M | Nenhum caminho fixo do computador do Breno no código; nenhum segredo em arquivo do repositório | CLAUDE.md |
+
+## Não funcionais
+| ID | Requisito | Prior. | Critério de aceite | Origem |
+| --- | --- | --- | --- | --- |
+| RNF-01 | **Escuta local por padrão**: o modo HTTP escuta em 127.0.0.1; outra interface só com token configurado | M | Teste: iniciar com `0.0.0.0` sem token falha; com token, exige cabeçalho de autorização; sem token no modo local, funciona | R2, K6 |
+| RNF-02 | **Conteúdo recuperado é dado**: a saída das ferramentas marca o texto dos fatos como dados não confiáveis, e a documentação explica o risco | M | Teste com fato que contém "ignore as instruções anteriores": é devolvido literalmente, dentro do campo de dados, sem ser tratado como comando. Limite: não garante que o assistente obedeça | R3 |
+| RNF-03 | **Privacidade**: sem telemetria; logs sem o texto dos fatos | M | Teste procura texto de fato de teste nos logs; nenhuma chamada de rede de saída no servidor | depth.md, CLAUDE.md |
+| RNF-04 | **Migrações versionadas** com backup automático antes de migrar | M | Teste migra um banco antigo e confere o conteúdo; falha na migração deixa o banco original intacto (a transação é desfeita) e o arquivo de backup permanece | R6 |
+| RNF-05 | **Avaliações como regressão** no CI | M | O CI roda `evals/` e falha se o hit@3 no ajuste ficar abaixo de 19 de 29. Mudar a busca exige novo conjunto de teste (o atual está esgotado) | H1, R1 |
+| RNF-06 | **Instalação em um comando** (por exemplo `pipx` ou `uv tool`), testada em ambiente limpo no CI | S | Job do CI instala do pacote construído e roda `mini-tars --version` e uma busca | R4, H3 |
+| RNF-07 | **Dependências verificadas** automaticamente | S | Job do CI com verificação de vulnerabilidades conhecidas; falha em relevante | R5, K6 |
+| RNF-08 | **Fuso e datas**: datas do fato em America/Sao_Paulo; carimbos internos em UTC | M | Teste em torno da meia-noite: fato criado às 23h30 locais recebe a data local | CLAUDE.md |
+| RNF-09 | **Desempenho**: busca responde rápido com milhares de fatos | C | Medir com 5.000 fatos em um computador comum e registrar o p95; a meta será definida depois de medir (sem número sem evidência) | uso diário |
+| RNF-10 | **Sem dado real** em testes, fixtures e exemplos | M | Revisão do reviewer; fixtures são os fatos fictícios de `evals/` | CLAUDE.md |
+
+## Fora do escopo (decisão registrada)
+Embeddings (só depois, com experimento novo e conjunto de teste novo), painel web, versão hospedada, sincronização, multiusuário, importação automática de notas, autenticação por usuário.
+
+## Rastreabilidade
+| Hipótese ou risco | Requisitos que tratam |
+| --- | --- |
+| H1 recuperação (R1) | RF-02, RF-03, RNF-05 |
+| R12 ruído com confiança | RF-05, RNF-02 |
+| R2 servidor exposto | RNF-01 |
+| R3 injeção de prompt | RNF-02 |
+| R4 instalação difícil (H3) | RNF-06 |
+| R5 vulnerabilidades (K6) | RNF-07 |
+| R6 migração perde dados | RF-08, RNF-04 |
+| K5 custo zero | Restrição da visão; RNF-06 e RNF-07 usam só planos gratuitos |
+
+## Critérios de pronto do MVP
+Todos os requisitos M atendidos e verificados por teste ou avaliação; README com instalação em um comando e aviso "sem garantia" e "nenhum dado sai da sua máquina"; o Breno consegue explicar cada diff (`CLAUDE.md`).

mini_tars-0.0.1/01-definir/visao.md

@@ -0,0 +1,53 @@
+---
+status: rascunho
+atualizado: 2026-09-23
+dono: Breno
+---
+# Visão do produto
+
+## Em uma frase
+Um servidor de memória, auto-hospedado e feito em Python, que deixa um assistente de IA guardar e recuperar fatos sobre os seus projetos entre sessões, com recuperação medida por avaliações que qualquer pessoa consegue reproduzir.
+
+## Problema e público
+Ver `00-descobrir/idea.md`. Desenvolvedores que usam assistentes de IA em vários projetos perdem decisões, preferências e estado do projeto entre sessões. Primeiro usuário: o Breno.
+
+## Objetivo do projeto (ordem de importância)
+1. **Aprender e montar portfólio**: Python e FastAPI, MCP, testes, avaliações e arquitetura com decisões registradas (decisão de 2026-09-23).
+2. **Ser útil ao Breno** no dia a dia, como memória dos próprios projetos.
+3. **Outros desenvolvedores usarem**, sem promessa de suporte (K3 mede isso).
+
+## O que torna este projeto diferente
+Não é a funcionalidade: o Basic Memory já cobre o espaço (`competitors.md`). O que é próprio, e o que o README deve mostrar:
+- **Avaliações reproduzíveis**: o repositório traz o conjunto de fatos e perguntas, o script e os protocolos pré-registrados (`evals/`). Qualquer pessoa roda e confere os números.
+- **Decisões registradas** (`docs/decisions.md` e ADRs em `docs/adr/`), incluindo o que deu errado.
+- **Correções explícitas**: um fato pode substituir outro, e a busca devolve o atual (RF-03).
+
+## Princípios
+1. **Local primeiro.** Os dados ficam na máquina do usuário. Sem telemetria, sem conta, sem serviço do Breno.
+2. **Dizer "não sei" é melhor que inventar.** A busca sinaliza resultado fraco em vez de apresentar ruído como certeza (R12).
+3. **Conteúdo recuperado é dado, nunca instrução** (R3).
+4. **Simples e medido antes de sofisticado.** Nenhuma técnica de busca entra sem passar pelas avaliações (lição dos experimentos 1 a 3).
+5. **Seguro por padrão.** Escuta só em 127.0.0.1; qualquer outra interface exige token (R2).
+
+## Escopo do MVP
+Dentro: guardar, buscar, substituir e apagar fatos; exportar e importar; servidor MCP por stdio e por HTTP local; avaliações e testes no CI.
+Fora (por ora): embeddings e busca semântica, painel web, versão hospedada, sincronização entre máquinas, várias pessoas no mesmo servidor, importação automática de notas.
+Detalhes e critérios de aceite em `requisitos.md`.
+
+## Como saberemos que funcionou
+| Objetivo | Medida | Meta |
+| --- | --- | --- |
+| Aprender | ADRs escritos, testes e avaliações no CI, servidor rodando com um cliente MCP real | MVP funcionando de ponta a ponta |
+| Recuperação (H1, K1) | hit@3 no conjunto de ajuste (`evals/cases.grande.json`) | não cair abaixo de 66% (19/29); K1 mantém o mínimo de 70% em conjunto de teste novo |
+| Uso próprio | O Breno usa o mini-Tars em pelo menos um projeto real por 4 semanas | sim ou não, registrado no `handoff.md` |
+| Uso por outros (K3) | Colegas ativos além do Breno, 3 sessões por semana | menos de 3 em 6 semanas: manter como portfólio |
+| Custo (K5) | Custo recorrente | R$ 0 |
+
+## Restrições
+- Custo recorrente zero (K5): nada de domínio, hospedagem ou serviço pago.
+- Tempo do Breno limitado (K4, R7): escopo pequeno.
+- Sem dados reais de ninguém em testes, fixtures ou logs (`CLAUDE.md`).
+- Fuso America/Sao_Paulo (`CLAUDE.md`).
+
+## Perguntas em aberto para o Breno
+Ver o fim de `arquitetura.md` (seção "Decisões que dependem do Breno"): nome do pacote, licença e versão mínima do Python.

mini_tars-0.0.1/CLAUDE.md

@@ -0,0 +1,27 @@
+# mini-Tars
+
+Servidor de memória (MCP) para assistentes de IA, feito em Python com FastAPI.
+Status do projeto: fase 4 (entregar) aprovada em 2026-09-24. MVP completo (todos os requisitos M).
+
+## Como navegar
+Leia primeiro `CONTEXT.md` (índice). Estado atual em `docs/handoff.md`. Decisões em `docs/decisions.md`.
+
+## Regras permanentes
+- Nunca ler nem editar `.env`, chaves ou qualquer credencial.
+- Nunca fazer deploy, nem publicar nada: só o Breno faz.
+- Toda mudança de comportamento precisa de teste ou de caso em `evals/`.
+- Fuso horário sempre America/Sao_Paulo, nunca o padrão do servidor.
+- Dado que não puder ser interpretado com confiança: perguntar, nunca gravar.
+- Outras pessoas vão usar (auto-hospedado): nenhum dado real de ninguém em testes, fixtures ou logs; o servidor escuta só em 127.0.0.1 por padrão.
+- Se a especificação estiver ambígua, registrar a dúvida em `docs/handoff.md` em vez de adivinhar.
+- Se o Breno não conseguir explicar um diff, o diff não é aceito.
+
+## Fluxo
+Especificação em `01-definir/` -> construtor implementa -> revisor (contexto separado, só leitura) revisa -> Breno aprova.
+
+## Comandos
+- Testes: `python -m pytest -q`
+- Medir a busca: `python evals/run_pkg.py -v`
+- Servidor MCP (stdio): `mini-tars serve` (banco em `MINI_TARS_DB` ou `--db`)
+- Servidor MCP (HTTP local): `mini-tars serve --http` (token fora do local em `MINI_TARS_TOKEN`)
+- Exportar/importar: `mini-tars export saida.json` / `mini-tars import saida.json` (import exige banco vazio)

mini_tars-0.0.1/CONTEXT.md

@@ -0,0 +1,27 @@
+---
+status: rascunho
+atualizado: 2026-09-23
+dono: Breno
+---
+# Índice do projeto
+
+Para cada pergunta, o arquivo que responde. Leia só o que precisar.
+
+| Pergunta | Arquivo |
+| --- | --- |
+| Que problema resolvemos e para quem? | `00-descobrir/idea.md` |
+| O que ainda não sabemos e pode invalidar o projeto? | `00-descobrir/assumptions.md` |
+| Quando paramos ou mudamos de direção? | `00-descobrir/kill-criteria.md` |
+| Quem já faz algo parecido? | `00-descobrir/competitors.md` |
+| Quanto rigor cada área exige? | `depth.md` |
+| O que já foi decidido, e por quê? | `docs/decisions.md` |
+| O que pode dar errado? | `docs/risks.md` |
+| Em que ponto estamos e o que vem agora? | `docs/handoff.md` |
+| Como medimos a recuperação (H1)? | `evals/README.md` |
+| Regras que valem sempre | `CLAUDE.md` |
+| Que produto é, para quê e o que fica fora? | `01-definir/visao.md` |
+| O que o MVP precisa fazer e como verificamos? | `01-definir/requisitos.md` |
+| Como é o sistema por dentro? | `01-definir/arquitetura.md` |
+| Por que cada decisão técnica? | `docs/adr/` |
+
+Pastas ainda não criadas (aparecem conforme as fases): `02-entregar/`, `.claude/agents/`, `src/`.

mini_tars-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Breno Henrique Bortoloti Santos
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.