YourMemory

A sua IA tem memória de peixinho dourado. Não mais.

Memória persistente e auto-melhorável para agentes de IA — construída com base na ciência de como os humanos lembram.

▶ Experimente a demo interativa ao vivo · Site · Benchmarks

O problema

Todas as manhãs o seu agente de IA trata-o como um estranho. O mesmo contexto reexplicado. As mesmas preferências esquecidas. Cada sessão começa do zero.

A maioria das ferramentas de "memória" junta uma base de dados vetorial a um agente e diz que está pronto — mas isso é apenas armazenamento. Acumula todos os quase-duplicados até que a recuperação se afogue em ruído. Um peixinho dourado com um aquário maior.

YourMemory é diferente: memória que funciona como um cérebro, não como uma base de dados.

flowchart LR
    A["🧠 You tell your<br/>AI something"] --> B["Extract durable<br/>facts"]
    B --> C["Dedup + embed<br/>+ graph-link"]
    C --> D[("Memory<br/>store")]
    D -->|"related facts pile up"| E["✨ Consolidate<br/>N → 1 summary"]
    D -->|"stale + unused"| F["📉 Decay<br/>+ prune"]
    D -->|"new session"| G["♻️ Recall<br/>hybrid + graph"]
    E --> D
    G --> H["🤖 Your agent<br/>picks up where<br/>it left off"]
    style D fill:#0a2540,stroke:#19cdff,color:#fff
    style E fill:#0c2b3a,stroke:#5eead4,color:#fff
    style H fill:#0c2b3a,stroke:#19cdff,color:#fff

✨ O que a torna diferente

Um comando para instalar. DuckDB por defeito (zero configuração), Postgres + pgvector para equipas.

Índice

• 🏆 Benchmarks
• 🚀 Início Rápido
• 🧠 Como Funciona a Memória
  • Consolidação
  • Decaimento
  • Recuperação Híbrida
• 🔒 Confiança e Registo de Auditoria
• 👥 Pools de Memória de Equipa
• 🛡️ Direitos de Dados e Conformidade
• 🎛️ Painéis
• 🔧 Ferramentas MCP
• ⚡ Perguntar Sem Chamada LLM
• 🔀 Proxy API — Memória Garantida
• 🏗️ Arquitetura e Stack
• 🩺 Resolução de Problemas
• 🤝 Contribuir

🏆 Benchmarks

Três conjuntos de dados externos. Cada número é independentemente reproduzível — o código de benchmark está no repositório. Metodologia completa em BENCHMARKS.md.

LoCoMo-10 — memória conversacional multi-sessão

xychart-beta
    title "Recall@5 · LoCoMo-10 (higher is better)"
    x-axis ["Mem0", "Zep Cloud", "Supermemory", "YourMemory"]
    y-axis "Recall@5 percent" 0 --> 70
    bar [18, 28, 31, 59]

2× melhor recall que o Zep Cloud em todas as 10 amostras. *Supermemory e Mem0 esgotaram as quotas gratuitas a meio do benchmark; pontuações calculadas sobre os 1.534 pares completos.

LongMemEval-S — 500 perguntas, ~53 sessões de distração cada

O benchmark padrão mais difícil para memória de longo prazo. Cada pergunta está enterrada em ~53 sessões.

HotpotQA — 200 perguntas de múltiplos saltos

As arestas do grafo de entidades adicionam +12 pp — percorrem do Facto 1 ao Facto 2 mesmo quando o Facto 2 tem baixa similaridade de embedding com a consulta.

Artigo: Construí decaimento de memória para agentes de IA usando a curva de esquecimento de Ebbinghaus

🚀 Início Rápido

Python 3.11–3.14. Sem Docker, sem configuração de base de dados. Toda a memória armazenada localmente em ~/.yourmemory/.

pip install yourmemory
yourmemory-register <your-token>
yourmemory-setup

Obtenha o seu token: visite yourmemoryai.xyz → insira o seu email → verifique com um código de 6 dígitos → copie o seu token.

yourmemory-setup deteta automaticamente e configura Claude Code, Claude Desktop, Cursor, Windsurf e Cline, depois pergunta qual backend usar:

• DuckDB — zero configuração, único ficheiro local (predefinido)
• Postgres — partilhado/produção; fornece um DATABASE_URL (precisa da extensão pgvector)

Opcional — extração local mais inteligente: O YourMemory funciona de imediato com heurísticas incorporadas. Para extração de factos de maior qualidade e totalmente local, instale Ollama e o yourmemory-setup descarrega o modelo (qwen2.5:7b, ~4,7 GB) automaticamente. Prefere a nuvem? Defina YOURMEMORY_EXTRACT_BACKEND=anthropic.

Ou instale a partir de um binário — sem necessidade de Python

Prefere não mexer no pip? Obtenha o binário independente para a sua plataforma a partir do último lançamento:

# macOS / Linux — download, extract, run
tar -xzf yourmemory-macos-arm64.tar.gz
./yourmemory-macos-arm64 register <your-token>
./yourmemory-macos-arm64 setup
./yourmemory-macos-arm64            # start the server

Um executável trata de cada comando: register, setup, ask "<question>", path, e (sem argumentos) inicia o servidor.

Totalmente autónomo e offline — o binário agrupa Python, todas as dependências, e ambos os modelos ML (o modelo de embedding + spaCy). Nada é descarregado na primeira execução. O compromisso é o tamanho (~2 GB). Crie o seu próprio com um único comando — ./build-binary.sh — e binários de lançamento para várias plataformas são produzidos automaticamente pelo fluxo de trabalho de build.

🧠 Como Funciona a Memória

O YourMemory trata a memória como um sistema vivo — cresce, consolida, esquece e conecta, tal como um cérebro.

Consolidação — N → 1

A maioria das ferramentas de memória apenas continua a crescer. O YourMemory monitoriza clusters de factos relacionados e, assim que se acumulam suficientes, comprime-os num único resumo limpo — arquivando os originais (nunca apaga, por isso nada se perde).

flowchart LR
    subgraph before [Related facts pile up]
        A1["Railway uses Nixpacks"]
        A2["Railway on Pro plan"]
        A3["Railway env vars hold<br/>the Postgres URL"]
        A4["Deploys on Railway<br/>with Postgres"]
    end
    before --> C{"cluster +<br/>LLM summarize"}
    C --> S["✨ Summary<br/>Deploys on Railway (Pro,<br/>Nixpacks) with Postgres<br/>via env vars"]
    C -.->|"archived, recoverable"| ARC[("archive")]
    style S fill:#0a2540,stroke:#5eead4,color:#fff
    style C fill:#0c2b3a,stroke:#19cdff,color:#fff

Exemplo real de uma store de produção: 444 memórias → 16 resumos — mesmo conhecimento, uma fração do ruído. A consolidação é orientada a eventos (acionada quando as memórias relacionadas se acumulam), não um trabalho noturno cego.

Decaimento — a curva de esquecimento

A força da memória decai exponencialmente. A importância e a frequência de recordação atenuam esse decaimento:

effective_λ  = base_λ × (1 − importance × 0.8)
strength     = clamp(importance × e^(−effective_λ × active_days) × (1 + recall_count × 0.2), 0, 1)

active_days conta apenas os dias em que esteve ativo — férias não causam perda de memória. Memórias abaixo da força 0.05 são podadas automaticamente. Cada categoria envelhece ao seu próprio ritmo:

Poda consciente da cadeia: uma memória deteriorada é mantida viva se algum vizinho do grafo ainda estiver forte — o contexto de suporte sobrevive mesmo quando raramente consultado diretamente.

Recuperação Híbrida — Vetor + BM25 + Grafo

A recordação ocorre em duas rondas, revelando tanto o que perguntou como o que esqueceu de perguntar:

flowchart LR
    Q["query"] --> R1["Vector + BM25<br/>hybrid search"]
    R1 --> R2["Graph expansion<br/>(what you forgot to ask)"]
    R2 --> S["rank by<br/>similarity × strength"]
    S --> OUT["🎯 Ranked memories"]
    style OUT fill:#0a2540,stroke:#19cdff,color:#fff

Deduplicação consciente do sujeito é executada antes de cada armazenamento — incorpora o sujeito de cada frase para que "Sachit uses DuckDB" e "YourMemory uses DuckDB" permaneçam separados (entidades diferentes), enquanto "YourMemory uses DuckDB" e "YourMemory stores data in DuckDB" se fundem (mesma entidade). Sem listas de palavras fixas; generaliza-se a qualquer idioma.

🔒 Confiança e Registo de Auditoria

As empresas não deixarão uma caixa preta opaca armazenar os seus dados. Por isso, cada operação — leitura, escrita, atualização, eliminação, consolidação — é anexada a um registo de auditoria com cadeia de hash e à prova de adulteração.

flowchart LR
    E0["GENESIS"] --> E1
    subgraph E1 [Event 1]
        H1["row_hash =<br/>sha256(prev + data)"]
    end
    E1 --> E2
    subgraph E2 [Event 2]
        H2["row_hash =<br/>sha256(#1.hash + data)"]
    end
    E2 --> E3
    subgraph E3 [Event 3]
        H3["row_hash =<br/>sha256(#2.hash + data)"]
    end
    E3 --> V{"GET /audit/verify"}
    V -->|chain intact| OK["✅ verified"]
    V -->|any row altered| BAD["❌ chain breaks<br/>at that row"]
    style OK fill:#0a2540,stroke:#5eead4,color:#fff
    style BAD fill:#3a0c14,stroke:#fb7185,color:#fff

Cada linha regista o timestamp, utilizador ator + agente, ação, operação, memória alvo, origem (http vs mcp) e o hash da linha anterior. Altere qualquer registo histórico e verify_chain() identifica exatamente onde a cadeia quebrou.

GET  /audit            # browse the trail (filter by user / action / operation)
GET  /audit/verify     # cryptographically verify the chain is untampered
POST /audit/prune      # retention-based cleanup (90-day minimum, never lower)

A registação de auditoria é fail-open — nunca bloqueia uma operação de memória — e os eventos de leitura/lista do próprio ciclo de renderização do painel são excluídos, para que o rasto permaneça sinal, não ruído.

👥 Pools de Memória de Equipa

Dê aos agentes de toda uma equipa um cérebro partilhado — sem vazar o contexto privado de ninguém. As memórias são partilhadas (visíveis para o pool) ou privadas (visíveis apenas para o seu proprietário).

flowchart TB
    P(("🧠 Team Pool<br/>shared memory"))
    A["Alice's agent"] <-->|shared| P
    B["Bob's agent"] <-->|shared| P
    C["Carol's agent"] <-->|shared| P
    A -. private .-> AP["🔒 Alice-only"]
    B -. private .-> BP["🔒 Bob-only"]
    style P fill:#0a2540,stroke:#19cdff,color:#fff
    style AP fill:#0c1424,stroke:#5a6b80,color:#8294a8
    style BP fill:#0c1424,stroke:#5a6b80,color:#8294a8

O acesso baseado em funções é aplicado por agente — o que o agente de um engenheiro aprende, toda a equipa beneficia instantaneamente; o contexto sensível permanece no âmbito do seu proprietário.

POST   /pools                          # create a pool
POST   /pools/{id}/members             # add a member (with role)
POST   /pools/{id}/memories            # contribute a shared memory
POST   /pools/{id}/retrieve            # recall across the pool

🛡️ Direitos de Dados e Conformidade

Porque a memória que armazena dados reais precisa dos controlos para ser confiável:

Combinados com o registo de auditoria com cadeia de hash e o piso de retenção de 90 dias, estes mapeiam-se diretamente nos controlos documentados em SECURITY.md (alinhados com SOC 2).

🎛️ Painéis

Duas interfaces de utilizador de navegador incorporadas — sem configuração extra, iniciam automaticamente com o servidor.

Painel de Memória — http://localhost:3033/ui

Uma visão completa de leitura/escrita com separadores Memórias · Auditoria · Pools: barra de estatísticas (Forte / A Desvanecer / Próximo da poda), separadores por agente, cartões de memória com barras de força em tempo real, filtros de categoria, o registo de auditoria e gestão de pools.

Visualizador de Grafo — http://localhost:3033/graph

Um mapa interativo dirigido por força de como as memórias se conectam — memória raiz como um nó brilhante, vizinhos codificados por cor por categoria, espessura da aresta = força da conexão. Arraste, amplie e clique em qualquer nó para conteúdo completo.

http://localhost:3033/graph?memoryId=42&userId=alex&depth=2

🔧 Ferramentas MCP

Três ferramentas, chamadas pela sua IA automaticamente.

# Store with spatial context
store_memory(
    "Alex prefers tabs over spaces in Python",
    importance=0.9, category="fact",
    context_paths=["/projects/backend"],
)

# Next session — spatial boost fires when working in that directory
recall_memory("Python formatting", current_path="/projects/backend")
# → {"content": "Alex prefers tabs over spaces in Python", "strength": 0.87}

⚡ Perguntar Sem Chamada LLM

O único sistema de memória que pode responder a perguntas sem fazer qualquer chamada à API LLM:

yourmemory ask "what database does this project use"
# → YourMemory uses DuckDB locally and Postgres in production.

yourmemory ask "how do I fix a kubernetes deployment"
# → Not enough memory context to answer without an LLM.

Quando a memória é suficientemente forte, responde instantaneamente — zero tokens, zero custo de nuvem, zero latência. Quando não é, recusa educadamente em vez de alucinar. A sua consulta nunca sai da sua máquina.

🔀 Proxy API — Memória Garantida

As ferramentas MCP são chamadas ao critério da IA. O proxy API remove essa incerteza — interceta cada chamada LLM, injeta memórias relevantes automaticamente e lida com store_memory / update_memory sem configuração de modelo.

Inicie o servidor (yourmemory), depois aponte o seu cliente para localhost:3033:

from anthropic import Anthropic

client = Anthropic(
    api_key="sk-ant-...",
    base_url="http://localhost:3033/proxy/anthropic",
    default_headers={"X-YourMemory-User": "alex"},  # per-user memory
)

# Memory is injected automatically — no other changes needed
response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[{"role": "user", "content": "What database do I use?"}],
)

OpenAI funciona de forma idêntica através de base_url="http://localhost:3033/proxy/openai".

🏗️ Arquitetura e Stack

flowchart LR
    C["Your AI client<br/>Claude · Cursor · any MCP"] <--> Y["🧠 YourMemory"]
    Y --> M[("Memory<br/>store")]
    Y --> A[("Audit<br/>ledger")]
    style Y fill:#0a2540,stroke:#19cdff,color:#fff
    style M fill:#0c1a2c,stroke:#5eead4,color:#fff
    style A fill:#0c1a2c,stroke:#5eead4,color:#fff

🩺 Resolução de Problemas

Escritas pendentes / tempo esgotado (bloqueio de escritor único do DuckDB). Se o servidor MCP e o servidor HTTP forem executados ao mesmo tempo, competem pelo bloqueio de escrita do DuckDB. Correção:

pkill -f yourmemory 2>/dev/null || true
rm -f ~/.yourmemory/memories.duckdb.wal ~/.yourmemory/memories.duckdb.lock 2>/dev/null || true
# restart your client

A executar Claude Desktop (MCP) e Claude Code (hooks) simultaneamente? Use SQLite em vez disso — lida com leitores/escritores concorrentes de forma limpa: DATABASE_URL=sqlite:///~/.yourmemory/memories.db

🤝 Contribuir

PRs bem-vindos — veja CONTRIBUTORS.md.

📚 Referências de Conjuntos de Dados

• LoCoMo — Maharana et al. (2024)
• LongMemEval — Wu et al. (2024)
• HotpotQA — Yang et al. (2018)

📄 Licença

Direitos de Autor 2026 Sachit Misra — Licenciado sob CC-BY-NC-4.0.

Gratuito para uso pessoal, educação, investigação académica e projetos open-source. Uso comercial requer um acordo escrito separado → [email protected]