fraise

Armazenamento de conhecimento em memória para agentes de IA

GitHub
8

Documentação

Fraise

Docs · Discord · Linguagem de consulta · Issues

Stars Forks Release PyPI License: MIT
CI Python SDK Coverage OpenSSF Scorecard
Go Reference Discord

Fraise é um banco de dados de memória para agentes de IA. Um banco que eles consultam diretamente, em uma linguagem feita para tokens, não para humanos.

remember 'acme moved to annual billing' topic:billing entity:acme

recall billing entity:acme since:30d top:5

Dois verbos. Um binário. Nenhuma infraestrutura para executar.

Instalação

brew install fraisehq/tap/fraise
brew services start fraise
curl -X POST localhost:9876/api/v1/q -H 'content-type: application/json' \
  -d "{\"query\": \"remember 'the parrot is turquoise' topic:color\"}"

Pacotes Linux, Docker, go install e binários de lançamento assinados estão todos em Comece por aqui abaixo.

Leia Durabilidade antes de implantar. Persistência é a issue #171 e a próxima grande parte do trabalho.

Como se compara

Medido em LoCoMo — 10 conversas de múltiplas sessões, 1.986 perguntas — com cada sistema ingerindo as mesmas conversas, usando o mesmo modelo de extração e o mesmo modelo de incorporação, e respondendo às mesmas perguntas. k=10, dados completos, execução mais recente por sistema em 2026-10-11.

sistemarecall de recuperaçãop50 de buscatokens de memória
fraise 0.3.30.9100.185 s7.453.109
hindsight 0.9.20.9135.836 s1.688.873
everos 1.2.30.8970.376 s10.030.966
letta 0.16.80.8970.349 s226.854
mem0 2.0.180.8860.576 s4.120.078
memos 2.0.330.8650.307 s4.000.552
graphiti 0.30.20.8280.290 s9.861.973
cognee 1.5.30.7906.273 s8.526.019
langmem 0.0.300.7830.227 s1.078.110

Fraise fica a 0.003 do melhor recall, 31× mais rápido que o único sistema que o alcança. Quase a mesma evidência, em uma fração do tempo. A coluna de tokens é o preço desse recall: o extrator (fraise-sdk 0.2.0) lê cada mensagem ao lado do que o grafo já contém, e esse contexto é de onde veio o recall.

Estes dados vêm de agent-memory-benchmarks, um harness aberto — precisão, recall e F1 em k ∈ {1, 3, 5, 10}, por categoria, cada execução marcada e reproduzível a partir da tag. As tabelas completas estão em seu RESULTS.md.

Por que Fraise

  • Uma linguagem de consulta que agentes realmente conseguem escrever. FQL tem dois verbos — remember e recall — e uma única forma de dizer cada coisa. Menos graus de liberdade significa menos maneiras de um modelo errar, e menos tokens gastos para dizer algo.
  • Recuperação híbrida. Fatos são indexados para busca de texto completo, grafo e (opcionalmente) vetorial. Uma consulta, classificada nas três.
  • Temporal por padrão. Memórias recentes superam as mais antigas, então o recall é sensível à recência sem precisar pedir.
  • O sistema mais rápido medido. 0.185 s p50 no LoCoMo, à frente de todos os outros sistemas e 31× mais rápido que o único com recall equivalente. Lembre e recupere no meio do passo, enquanto o usuário espera.
  • Sem infraestrutura. Um único binário. Sem banco de dados para provisionar, sem serviço para levantar ao lado.
  • Código aberto, MIT.

Status

v0.3.3. O loop principal funciona de ponta a ponta e os caminhos de instalação são verificados em máquinas limpas. A linha do benchmark acima foi produzida a partir deste lançamento. 0.4.0 (final de outubro) muda o scorer e adiciona explain e describe; 0.5.0 (novembro) é persistência e forget.

Bom para construir memória de agente hoje. Ainda não para uso de produção de longo prazo.

Como funciona

Fraise armazena conhecimento como um grafo de memória temporal construído a partir de três tipos de nós:

  • fatos — as coisas que você lembra, uma declaração cada
  • entidades — quem ou o que um fato menciona
  • tópicos — sobre o que um fato é

Arestas conectam fatos às entidades que mencionam e aos tópicos sobre os quais são, então uma consulta pode começar de qualquer lado. Um recall encontra fatos-semente por texto e, opcionalmente, por similaridade vetorial; um recall que nomeia apenas tópicos ou entidades começa pelos fatos arquivados sob eles. Com depth:1 ou depth:2, um tópico ou entidade nomeado cujos fatos corresponderam melhor do que seu tamanho prevê repassa essa evidência para o restante de seus fatos. Resultados são classificados por relevância e recência, e os melhores top voltam.

A classificação não é uma caixa-preta: a pontuação de um fato é sua própria força de correspondência mais o que recebe através de âncoras que carregam mais massa do que seu tamanho preveria. A taxa de base contra a qual esse "mais" é medido é estimada por consulta, a partir da parte do grafo que a consulta tocou, então não há constante de relevância para ajustar. Recuperação híbrida tem o modelo completo.

Uma única instância do Fraise contém vários grafos de memória independentes (8 por padrão), endereçados com @N — um por usuário, por sessão, por agente, como você preferir.

Comece por aqui

Fraise é um único binário — sem banco de dados para provisionar, nada para configurar. Cada rota abaixo deixa você com um servidor ouvindo na porta 9876, em localhost:9876.

Com Homebrew

brew install fraisehq/tap/fraise
brew services start fraise

O serviço sobrevive a falhas e reinicia no login (keep_alive), registra logs em $(brew --prefix)/var/log/fraise.log e lê sua configuração de $(brew --prefix)/etc/fraise/fraise.config.toml — instalado com cada configuração comentada em seu padrão, e nunca sobrescrito em atualizações.

Com Docker

docker run -p 127.0.0.1:9876:9876 ghcr.io/fraisehq/fraise:latest

Tags publicadas: uma por lançamento, latest para o estável mais recente, edge para a ponta de main, e uma tag imutável de SHA completo do commit para cada merge que toca o servidor.

Imagens são construídas com proveniência SLSA, verificável sem puxar:

gh attestation verify oci://ghcr.io/fraisehq/fraise:latest --repo FraiseHQ/fraise

Com Go

go install github.com/FraiseHQ/fraise/cmd/server@latest
"$(go env GOPATH)/bin/server"

O binário instala como server, após seu caminho de pacote — renomeie para fraise se isso ler melhor.

Nada mais é necessário para confiar nisso: a toolchain Go verifica cada download de módulo contra o log público de transparência de checksums, e sua própria máquina compila o resultado.

Pacotes Linux

Pacotes .deb e .rpm acompanham cada lançamento, com uma unit de usuário systemd:

VERSION=0.3.0
ARCH=$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/')
curl -sSfLO "https://github.com/FraiseHQ/fraise/releases/download/v${VERSION}/fraise_${VERSION}_linux_${ARCH}.deb"
sudo dpkg -i "fraise_${VERSION}_linux_${ARCH}.deb"
systemctl --user enable --now fraise

Logs vão para o journal (journalctl --user -u fraise -f), e a unit lê ~/.config/fraise/fraise.config.toml quando presente — um padrão enviado com cada configuração comentada vive em /etc/fraise/fraise.config.toml para copiar. Para agentes que sobrevivem à sua sessão de login, deixe o gerenciador de usuário rodando: loginctl enable-linger $USER. Uma variante de nível de sistema (servidor compartilhado) da unit é descrita em Executando como um serviço gerenciado.

De um binário de lançamento

VERSION=0.3.0
OS=$(uname -s | tr '[:upper:]' '[:lower:]')                # linux | darwin
ARCH=$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/')  # amd64 | arm64
ASSET="fraise_${VERSION}_${OS}_${ARCH}.tar.gz"
BASE="https://github.com/FraiseHQ/fraise/releases/download/v${VERSION}"

curl -sSfLO "${BASE}/${ASSET}"
tar xzf "$ASSET"
./fraise

Builds Windows são enviados como .zip sob o mesmo esquema de nomenclatura.

Verifique um lançamento

Lançamentos carregam uma assinatura cosign sobre checksums.txt, usando o mesmo VERSION e BASE de acima:

curl -sSfLO "${BASE}/checksums.txt"
curl -sSfLO "${BASE}/checksums.txt.sigstore.json"

# 1. the bundle proves checksums.txt came from this repo's release workflow
cosign verify-blob \
  --bundle checksums.txt.sigstore.json \
  --certificate-identity-regexp 'https://github.com/FraiseHQ/fraise/.github/workflows/go.yaml@refs/tags/v.*' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  checksums.txt

# 2. checksums.txt proves your archive is the one it covers
sha256sum --ignore-missing -c checksums.txt   # macOS: shasum -a 256 --ignore-missing -c

Execute a partir do código-fonte

git clone https://github.com/FraiseHQ/fraise
cd fraise
make dev

Sua primeira memória

curl -X POST localhost:9876/api/v1/q \
  -H 'content-type: application/json' \
  -d "{\"query\": \"remember 'the parrot is turquoise' topic:color\"}"

curl -X POST localhost:9876/api/v1/q \
  -H 'content-type: application/json' \
  -d '{"query":"recall parrot"}'

{
  "results": {
    "count": 1,
    "hits": [
      { "value": "the parrot is turquoise", "timestamp": "...", "score": 0.2867 }
    ]
  }
}

Use a partir de um agente

MCP

fraise mcp é um servidor MCP stdio — uma ponte fina para um daemon em execução, então qualquer cliente MCP pode lembrar e recuperar. Ele expõe duas ferramentas, recall e remember, e não precisa de flags quando o daemon está em seu endereço padrão.

Inicie o daemon primeiro (brew services start fraise, ou systemctl --user start fraise no Linux), então registre a ponte com o agente de codificação que você usa.

Claude Code

claude mcp add fraise -- fraise mcp

Isso o registra para o projeto atual; adicione --scope user para torná-lo disponível em todos os projetos.

Codex

codex mcp add fraise -- fraise mcp

Ou escreva diretamente em ~/.codex/config.toml:

[mcp_servers.fraise]
command = "fraise"
args = ["mcp"]

OpenCode

Adicione a opencode.json na raiz do seu projeto:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "fraise": {
      "type": "local",
      "command": ["fraise", "mcp"]
    }
  }
}

Qualquer outro cliente

{
  "mcpServers": {
    "fraise": { "command": "fraise", "args": ["mcp"] }
  }
}

A ponte se descreve via MCP: cada ferramenta chega com uma descrição e um schema JSON completo para seus argumentos e resultados — as formas FQL, um exemplo trabalhado, o que uma pontuação significa — então um cliente sabe o que recall e remember fazem e como chamá-los sem ser informado. O que uma descrição de ferramenta não pode carregar é a política: o hábito de buscar memória sem ser solicitado, e o julgamento sobre o que vale a pena manter. Isso pertence ao arquivo que seu agente já lê — CLAUDE.md para Claude Code, AGENTS.md para Codex e OpenCode — e dois hábitos são suficientes: recuperar antes de responder qualquer coisa que dependa de decisões ou preferências anteriores, e lembrar apenas fatos que ainda importarão em uma sessão posterior, um fato autocontido por chamada com os tópicos e entidades que o tornarão encontrável.

SDKs

Python (sdk/python) — o único SDK hoje:

pip install --pre fraise-sdk

from fraise_sdk import FraiseClient

with FraiseClient("http://localhost:9876") as fraise:
    fraise.remember("the parrot is turquoise", topics=["color"])
    for hit in fraise.recall("parrot", top=5):
        print(hit.value, hit.score)

O SDK Python é leve em dependências e suporta busca vetorial quando você fornece um embedder. Veja seu README para embeddings e a API completa.

TypeScript — ainda não disponível (#179). Até chegar, chamadas TypeScript usam fraise mcp ou falam diretamente com o endpoint HTTP; são dois verbos sobre uma rota, então um cliente é um wrapper curto em torno de fetch. Veja a API HTTP.

Claude Agent SDK

O SDK Python envia ferramentas de memória para o Claude Agent SDK, expostas como um servidor MCP em processo para que o agente decida o que armazenar e recuperar:

from claude_agent_sdk import ClaudeAgentOptions
from fraise_sdk import FraiseClient
from fraise_sdk.integrations.claude_agents import memory_server, allowed_tools

fraise = FraiseClient("http://localhost:9876")
options = ClaudeAgentOptions(
    system_prompt="Remember durable facts the user shares, and recall them when relevant.",
    mcp_servers={"fraise_memory": memory_server(fraise)},
    allowed_tools=allowed_tools(),
)

Um agente completo, executável via Docker, vive em examples/claude-agent-sdk.

OpenAI Agents SDK

memory_tools(client) retorna ferramentas recall e remember vinculadas:

from agents import Agent, Runner
from fraise_sdk import FraiseClient
from fraise_sdk.integrations.openai_agents import memory_tools

fraise = FraiseClient("http://localhost:9876")
agent = Agent(
    name="Assistant",
    instructions="Remember durable facts the user shares, and recall them when relevant.",
    tools=memory_tools(fraise),
)

result = Runner.run_sync(agent, "My favourite colour is orange.")
print(result.final_output)

Um agente completo, executável via Docker, vive em examples/openai-agents.

Referências

Contribuindo

Contribuições são bem-vindas — veja CONTRIBUTING.md para como construir, testar e enviar mudanças.

Código de Conduta

Este projeto segue o Contributor Covenant.

Comunidade

Perguntas, ideias ou construindo algo com Fraise? Junte-se ao Discord. Bugs e pedidos de recursos pertencem às issues para não se perderem.

Licença

MIT — veja LICENSE.