convez.ai
MCP ServerAutomaçãoIntermediário
cccadet

myMem0ry

cccadet/myMem0ry

Memória compartilhada offline para agentes de IA com busca semântica

Ver no GitHub
InicialPluginScore · de 0 a 100

Sistema de memória persistente para agentes de IA codificadores, totalmente offline e sem necessidade de chaves de API. Permite handoffs entre diferentes agentes (Claude Code, OpenCode, Codex, Cursor) com busca semântica e estrutura de memória em camadas (sessão, contexto, projeto, global).

Instalação

$npx convez-ai cccadet/myMem0ry

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 4 meses
Versão
v0.30.0
Issues abertas
0
Contribuidores
1

Casos de uso

  • Continuar tarefas de codificação entre diferentes agentes IA
  • Manter histórico estruturado de decisões e próximos passos
  • Buscar semanticamente informações em memória de projetos

Veredito

Solução sólida e bem-arquitetada para persistência de memória entre agentes. Offline e sem custos com tokens LLM para gravação tornam viável para fluxos densos; implementação com spaCy + sqlite-vec é técnicamente competente, embora exija alguns pré-requisitos (uv, ripgrep, git).

README

A tradução para o português deste README ainda está na fila.

myMem0ry

Personal memory for AI coding agents. Offline. Zero API keys. Works with any agent.

CI Publish PyPI Python License: MIT


Persistent memory that any AI agent can read and write. Quit Claude Code mid-task, open Codex in the same directory — it picks up where you left off.

Features

  • Scoped memory — session → context (branch) → project → global, resolved automatically from cwd
  • Cross-agent handoffs — typed records with summary, open questions, next steps
  • Semantic search — spaCy + sqlite-vec + BM25/FTS5/hybrid RRF fusion
  • Lifecycle hooks — fire-and-forget HTTP endpoint, payload sanitization, immutable observations
  • Zero LLM tokens for writes — bulk writes (conversation archiving, logging) via hooks only
  • Retention — salience-based decay with tiers (working/procedural/semantic), pin/unpin
  • Auth — Bearer token, host allowlisting, CORS
  • Web UI — dark mode read-only viewer (dashboard, projects, search, audit log)
  • Backup/restore — tarball CLI commands
  • Multi-agent — Claude Code, OpenCode, Codex, Cursor, Gemini CLI, VS Code, Docker

Prerequisites

ToolWhyInstall
uvPackage manager (installs myMem0ry + dependencies)curl -LsSf https://astral.sh/uv/install.sh | sh
ripgrep (rg)Default search backend for mymem0ry searchsudo apt install ripgrep / brew install ripgrep / winget install BurntSushi.ripgrep.MSVC
gitProject & context resolution (branch, remote URL)Usually pre-installed

mymem0ry doctor checks all prerequisites and auto-downloads the spaCy language model if missing.

Install

uv tool install mymem0ry
mymem0ry doctor

The default spaCy model is English (en_core_web_lg). For Portuguese, set SPACY_MODEL=pt_core_news_lg in .env before running mymem0ry doctor.

Zero config: after install, just add the MCP server + hooks to your agent config below. The HTTP server auto-starts when the MCP server runs — no separate serve command needed.

Agent Setup

Claude Code

claude mcp add --scope user mymem0ry -- mymem0ry-mcp

MCP + hooks in ~/.claude/settings.json:

First get the correct hooks paths:

mymem0ry hooks --config

Then copy the printed snippet into your settings.json. Example result:

{
  "mcpServers": {
    "mymem0ry": {
      "type": "stdio",
      "command": "mymem0ry-mcp"
    }
  },
  "hooks": {
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [{"type": "command", "command": "/home/user/.local/share/mymem0ry/hooks/claude-code/session-start.sh"}]
      }
    ],
    "SessionEnd": [
      {
        "matcher": "",
        "hooks": [{"type": "command", "command": "/home/user/.local/share/mymem0ry/hooks/claude-code/session-end.sh"}]
      }
    ]
  }
}

OpenCode

Add to ~/.config/opencode/opencode.json (global) or ./opencode.json (project):

{
  "mcp": {
    "mymem0ry": {
      "type": "local",
      "command": ["mymem0ry-mcp"],
      "timeout": 30000,
      "enabled": true
    }
  }
}

Note: timeout: 30000 (30s) is recommended because loading the spaCy model on first run can exceed the default 5s timeout.

If mymem0ry-mcp is not on PATH (e.g. installed via uv sync in a project), use the full path:

{
  "mcp": {
    "mymem0ry": {
      "type": "local",
      "command": ["uv", "run", "--directory", "/path/to/myMem0ry", "mymem0ry-mcp"],
      "timeout": 30000,
      "enabled": true
    }
  }
}

Codex CLI

codex mcp add mymem0ry -- mymem0ry-mcp

VS Code

code --add-mcp '{"name":"mymem0ry","command":"mymem0ry-mcp"}'

Cursor

cursor --add-mcp '{"name":"mymem0ry","command":"mymem0ry-mcp"}'

Gemini CLI

Same stdio pattern. Add to Gemini CLI MCP config with command: mymem0ry-mcp.

Docker

docker compose -f docker/docker-compose.yml up -d
curl http://127.0.0.1:49374/health

For detailed per-agent instructions: docs/install.md

Lifecycle Hooks

Hooks POST lifecycle events to POST /hook on the myMem0ry HTTP server. The server auto-starts when the MCP server runs — no manual serve step needed.

AgentHooksHow
OpenCodeMCP onlyNo hook support — context via MCP tools (get_context, save_memory)
Claude CodeNativehooks in ~/.claude/settings.json — scripts receive full payload via stdin
Codex CLIHook scriptscodex hook add session-end ./hook-session-end.sh
GenericManualcurl -X POST http://127.0.0.1:49374/hook ...

Hook payload fields:

FieldRequiredDescription
kindyessession-start, session-end, log, user-prompt, post-tool-use, pre-compact
session_idyesUnique session identifier (max 64 chars)
agentnoopencode, claude-code, codex, manual, hook
cwdnoWorking directory for context resolution
transcript_pathnoPath to a Claude Code transcript JSONL — on session-end the server parses it and archives the conversation (zero LLM tokens)
titlenoShort label (max 500 chars)
bodynoContent (max 10,000 chars)
messagesno`[{"role": "user"

All payloads are sanitized: secrets redacted, home paths stripped, fields truncated.

Configuration

All via environment variables (or .env file in the project root):

VariableDefaultDescription
CONVERSATIONS_DIRdata/conversationsWhere archived conversation .md files are stored
MEMORIES_DIRdata/memoriesWhere curated memory .md exports are stored (kept separate so general search doesn't bury them)
DB_PATHdata/memories.dbSQLite memories database (source of truth)
VECTOR_DB_PATHdata/conversations/.vec.dbsqlite-vec index
SPACY_MODELen_core_web_lgspaCy model for embeddings and search (set pt_core_news_lg for Portuguese)
MEM0RY_HOST127.0.0.1Host for HTTP transport
MEM0RY_PORT49374Port for HTTP transport
MEM0RY_TOKEN(empty)Bearer token for HTTP auth (skip = no auth)
MEM0RY_ALLOWED_HOSTSlocalhost,127.0.0.1Host allowlist (DNS rebinding protection)
MEM0RY_CORS_ORIGINS(empty)CORS origins for web UI
# Custom storage location
export DB_PATH=/path/to/shared/memories.db
export CONVERSATIONS_DIR=/path/to/shared/conversations

# Portuguese language support
export SPACY_MODEL=pt_core_news_lg
mymem0ry doctor

Import Conversations

myMem0ry auto-detects the format. Supports ChatGPT, Gemini, and Claude exports.

mymem0ry split                                    # Auto-detect
mymem0ry split --source path/to/chatgpt-export    # Specific source
mymem0ry split --source path/to/data --type claude-code  # Force parser

mymem0ry index                                    # Build indexes
mymem0ry migrate                                  # Migrate to structured memory

CLI Commands

# Context & search
mymem0ry context --cwd .                          # Load context for current project
mymem0ry save "Title" "Content" --scope project   # Save a memory
mymem0ry log "message"                            # Quick session log
mymem0ry search "query"                           # ripgrep search
mymem0ry search "query" --backend hybrid --expand # BM25+vector RRF fusion

# Overview
mymem0ry stats                                    # Database overview
mymem0ry projects                                 # List projects with memories
mymem0ry doctor                                   # System health check

# Retention
mymem0ry decay --days 90 --dry-run                # Preview decay
mymem0ry pin <memory_id>                          # Pin memory (exempt from decay)
mymem0ry unpin <memory_id>
mymem0ry forget-sweep --dry-run                   # Preview salience-based sweep

# Handoffs
mymem0ry handoff begin --summary "..."            # Create handoff for next agent
mymem0ry handoff accept                           # Accept pending handoff
mymem0ry handoff status                           # Check server status

# Hooks
mymem0ry hooks --config                       # Print settings.json snippet
mymem0ry hooks --path                         # Print hooks directory path
mymem0ry hooks --install                      # Install hooks for detected agent

# Server & backup
mymem0ry serve                                    # Start HTTP server
mymem0ry serve --detach                           # Start in background
mymem0ry backup --to backup.tar.gz                # Backup DB + conversations
mymem0ry restore --from backup.tar.gz             # Restore from backup

Memory Scopes

Resolved automatically from cwd — no manual configuration needed:

ScopeIdentifierWhat it storesExample
sessionauto UUIDCurrent session state"Trying to fix auth bug"
contextgit branchDecisions for a branch"On feat/auth, using JWT"
projectgit remote URLProject architecture"Uses FastAPI + SQLite"
global—User preferences"Prefer conventional commits"

get_context() aggregates all 4 levels in priority order.

Retention & Pinning

Memories decay based on their type:

Memory typeRetention tierBehaviour
logworking30–90 day decay
patternproceduralfrequency-based decay (up to 365d)
factsemanticindefinite (pinned by default)
decisionsemanticindefinite (pinned by default)

Pinning exempts a memory from decay — pinned memories are never deleted by forget-sweep. Use memory_pin / memory_unpin (or CLI mymem0ry pin / mymem0ry unpin) to protect important memories.

Fact evolution (evolve_fact) consolidates contradictory facts. When information changes (e.g. "Uses Postgres" → "Migrated to SQLite"), the old fact is soft-deleted and a new evolved fact replaces it, keeping the memory clean and current.

MCP Tools + Hook Writes

MCP Tools (low token cost — reads + selective writes)

ToolDescription
get_contextAggregate context from all scopes, ranked by salience (also auto-injected at session start)
save_memorySave a memory with scope, type, and auto-resolved context (returns its id)
search_memorySearch your curated memories — scope/type/tags-aware, returns ids
search_conversationsBroad full-text/semantic search across archived transcripts
read_memoryFetch full content by memory id or conversation path
memory_statsDatabase statistics
memory_handoff_beginCreate handoff for next agent
memory_handoff_acceptPeek at the pending handoff (non-destructive; the hook consumes it)
memory_pinPin a memory (exempt from decay)
memory_unpinUnpin a memory
memory_forget_sweepSweep stale memories
evolve_factConsolidate contradictory facts (old facts soft-deleted, new evolved fact created)

Hook writes (zero LLM tokens)

Hook kindDescription
session-end with messagesArchives full conversation to .md + auto-handoff
logQuick session log (creates session-scoped memory)
session-startRecords session start observation
user-prompt / post-tool-use / pre-compactLifecycle observations

Web UI

When running in HTTP mode (MCP_TRANSPORT=streamable-http), a read-only web UI is available:

  • / — Dashboard with stats and recent memories
  • /projects — List of projects with memory counts
  • /project/{id} — Project detail with memories
  • /memory/{id} — Single memory detail
  • /search — Full-text search with scope/type filters
  • /audit — Audit log of all mutations

Documentation

Development

git clone https://github.com/cccadet/myMem0ry.git
cd myMem0ry
bin/setup
uv run python -m pytest
uv run ruff check .

License

MIT

Ver o original no GitHub

Bom para

Relacionados