YourMemory

---

O problema

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

A maioria das ferramentas de "memória" acopla um banco de dados vetorial a um agente e pronto — mas isso é apenas armazenamento. Ela acumula quase-duplicatas até que a recuperação se afogue em ruído. Um peixe dourado com um aquário maior.

YourMemory é diferente: memória que funciona como um cérebro, não como um banco 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

	Recurso	O que faz
🧠	Consolidação	Quando fatos relacionados suficientes se acumulam, eles são comprimidos em um resumo limpo e os originais são arquivados. A memória fica mais nítida com o tempo, não mais inchada.
📉	Decaimento biológico	Cada memória envelhece em uma curva de esquecimento de Ebbinghaus. Fatos antigos e sem uso desaparecem; os importantes e frequentemente lembrados persistem.
🔗	Grafo de entidades	Memórias se conectam por pessoas, lugares e conceitos compartilhados — então a recuperação traz à tona o que você esqueceu de pedir.
♻️	Sobrevive a redefinições de contexto	Quando a janela de contexto é compactada, o YourMemory devolve o contexto de trabalho — sem reler arquivos para descobrir onde você estava.
🔒	Trilha de auditoria à prova de adulteração	Cada leitura / escrita / exclusão é registrada em um livro-razão encadeado por hash. Altere um registro e a cadeia se quebra.
👥	Pools de memória de equipe	Memória compartilhada baseada em papéis, para que os agentes de toda uma equipe usem o mesmo conhecimento institucional — com memórias privadas mantidas privadas.
🛡️	Direitos de dados integrados	Exportação com um comando (direito de acesso) e direito ao esquecimento (purga), além de controles alinhados ao SOC 2.
🔌	Nativo MCP e local-first	Funciona com Claude, Cursor, Cline, Windsurf ou qualquer cliente MCP. Roda inteiramente na sua máquina — sem chave de API, nada sai do seu sistema.

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

---

Índice

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

---

🏆 Benchmarks

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

LoCoMo-10 — memória conversacional multissessã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]

Recall 2× melhor que o Zep Cloud em todas as 10 amostras. *Supermemory e Mem0 esgotaram as cotas do nível gratuito durante o benchmark; pontuações calculadas sobre todos os 1.534 pares.

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.

Métrica	Pontuação
Recall@5 (qualquer sessão dourada no top-5)	89,4%
Recall-all@5 (todas as sessões douradas no top-5)	84,8%
nDCG@5 (qualidade de ranqueamento)	87,4%

HotpotQA — 200 perguntas multipasso

Sistema	BOTH_FOUND@5
YourMemory (vetor + BM25 + grafo de entidades)	71,5%
YourMemory (sem arestas de entidades)	59,5%

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

Relato: 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 banco de dados. Toda a memória é armazenada localmente em ~/.yourmemory/.

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

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

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

• DuckDB — zero configuração, um único arquivo local (padrão)
• Postgres — compartilhado / produção; você fornece uma DATABASE_URL (precisa da extensão pgvector)

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

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

Prefere não mexer com pip? Baixe o binário autônomo para sua plataforma na última versão:

Plataforma	Artefato
macOS (Apple Silicon)	yourmemory-macos-arm64.tar.gz
macOS (Intel)	yourmemory-macos-x86_64.tar.gz
Linux (x86-64)	yourmemory-linux-x86_64.tar.gz
Windows (x86-64)	yourmemory-windows-x86_64.exe.zip

# 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 único executável cuida de todos os comandos: register, setup, ask "<question>", path e (sem argumentos) inicia o servidor.

Totalmente autocontido e offline — o binário inclui Python, todas as dependências e os dois modelos de ML (o modelo de embedding + spaCy). Nada é baixado na primeira execução. O custo é o tamanho (~2 GB). Compile o seu com um único comando — ./build-binary.sh — e binários de lançamento multiplataforma são produzidos automaticamente pelo workflow de build.

---

🧠 Como a Memória Funciona

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

Consolidação — N → 1

A maioria das ferramentas de memória apenas continua crescendo. O YourMemory observa agrupamentos de fatos relacionados e, quando o suficiente se acumula, comprime-os em um único resumo limpo — arquivando os originais (nunca excluindo, para que nada se perca).

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 um store de produção: 444 memórias → 16 resumos — mesmo conhecimento, uma fração do ruído. A consolidação é orientada a eventos (disparada quando memórias relacionadas se acumulam), não um job cego noturno.

Decaimento — a curva de esquecimento

A força da memória decai exponencialmente. A importância e a frequência de recall desaceleram 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 você 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 no seu próprio ritmo:

Categoria	Meia-vida	Ideal para
strategy	~38 dias	Padrões que funcionaram, decisões de arquitetura
fact	~24 dias	Preferências, identidade, conhecimento estável
assumption	~19 dias	Contexto inferido, crenças incertas
failure	~11 dias	Erros, abordagens erradas, problemas específicos de ambiente

Podagem sensível a cadeias: uma memória em decaimento é mantida viva se algum vizinho do grafo ainda for forte — contexto estrutural sobrevive mesmo quando raramente consultado diretamente.

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

O recall acontece em duas rodadas para trazer tanto o que você pediu quanto o que você esqueceu de pedir:

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

Desduplicação consciente do assunto é executada antes de todo store — ela incorpora o assunto 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 codificadas; generaliza para qualquer idioma.

---

🔒 Confiança e Trilha de Auditoria

Empresas não deixam uma caixa-preta opaca armazenar seus dados. Por isso, toda operação — leitura, escrita, atualização, exclusão, consolidação — é anexada a um log de auditoria encadeado por 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 registra o timestamp, usuário ator + agente, ação, operação, memória alvo, fonte (http vs mcp) e o hash da linha anterior. Altere qualquer registro histórico e o verify_chain() aponta 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)

O log de auditoria é fail-open — ele nunca bloqueia uma operação de memória — e eventos de leitura/listagem do próprio loop de renderização do painel são excluídos, para que a trilha permaneça sinal, não ruído.

---

👥 Pools de Memória de Equipe

Dê a todos os agentes de uma equipe um único cérebro compartilhado — sem vazar o contexto privado de ninguém. As memórias são compartilhadas (visíveis ao pool) ou privadas (visíveis apenas ao seu dono).

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 papéis é aplicado por agente — o que o agente de um engenheiro aprende a equipe inteira aproveita instantaneamente; o contexto sensível permanece restrito ao seu dono.

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 memória que armazena dados reais precisa dos controles para ser confiável:

Direito	Endpoint	O que faz
Acesso (exportação DSAR)	GET /users/{id}/export	Exportação completa de tudo o que está armazenado para um usuário
Apagamento (direito ao esquecimento)	DELETE /users/{id}/memories	Purga com um comando das memórias de um usuário
Portabilidade	POST /users/{id}/import	Reimportar uma exportação anterior
Recuperabilidade	GET /users/{id}/archive	Recuperar originais arquivados pela consolidação

Combinados com a trilha de auditoria encadeada por hash e o piso de retenção de 90 dias, esses mapas se relacionam diretamente aos controles documentados em SECURITY.md (alinhado ao SOC 2).

---

🎛️ Painéis

Duas UIs de navegador integradas — 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 abas Memórias · Auditoria · Pools: barra de estatísticas (Forte / Enfraquecendo / Quase poda), abas por agente, cartões de memória com barras de força ao vivo, filtros por categoria, trilha de auditoria e gerenciamento de pools.

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

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

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

---

🔧 Ferramentas MCP

Três ferramentas, chamadas automaticamente pela sua IA.

Ferramenta	Quando sua IA chama	O que faz
recall_memory(query, current_path?)	Início de cada tarefa	Traz memórias ranqueadas por similaridade × força de decaimento; aumento espacial para memórias com correspondência de caminho
store_memory(content, importance, category?, context_paths?)	Depois de aprender algo novo	Incorpora, desduplica, armazena com decaimento; marca caminhos opcionais de arquivos/diretórios
update_memory(id, new_content, importance)	Quando um fato armazenado está desatualizado	Reincorpora e substitui; registra a alteração na trilha de auditoria

# 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}

---

⚡ Pergunte Sem Chamada de LLM

O único sistema de memória que consegue responder perguntas sem fazer nenhuma chamada de API de 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 é forte o suficiente, ela responde instantaneamente — zero tokens, zero custo de nuvem, zero latência. Quando não é, ela recusa educadamente em vez de alucinar. Sua consulta nunca sai da sua máquina.

---

🔀 Proxy de API — Memória Garantida

As ferramentas MCP são chamadas a critério da IA. O proxy de API remove essa incerteza — ele intercepta cada chamada de LLM, injeta memórias relevantes automaticamente e lida com store_memory / update_memory sem configuração de modelo. Inicie o servidor (yourmemory), e aponte 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?"}],
)

A OpenAI funciona de forma idêntica via 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

Componente	Função
DuckDB	Armazenamento vetorial padrão — zero configuração, similaridade de cosseno nativa
PostgreSQL + pgvector	Opcional — para equipes ou grandes conjuntos de dados
NetworkX	Backend de grafo padrão (~/.yourmemory/graph.pkl)
Neo4j	Backend de grafo opcional
sentence-transformers	Embeddings locais (multi-qa-mpnet-base-dot-v1, 768 dims)
spaCy	NLP local para deduplicação e extração de entidades
APScheduler	Decaimento automático + poda

---

🩺 Solução de Problemas

Gravações travam / expiram (bloqueio de escritor único do DuckDB). Se o servidor MCP e o servidor HTTP forem executados ao mesmo tempo, eles competem pelo bloqueio de gravação 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

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

---

🤝 Contribuindo

PRs são 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

Copyright 2026 Sachit Misra — Licenciado sob CC-BY-NC-4.0.

Gratuito para uso pessoal, educação, pesquisa acadêmica e projetos de código aberto. Uso comercial exige um acordo escrito separado → mishrasachit1@gmail.com