convez.ai
MCP ServerIntegração & APIsIntermediário
Dream-Pixels-Forge

Memorius — Sistema de Memória Persistente para Agentes IA

Dream-Pixels-Forge/memorius

Cofre universal de memória para qualquer agente IA, com busca semântica e organização hierárquica

Ver no GitHub
InicialPluginScore · de 0 a 100

MCP server que fornece memória persistente, pesquisável e organizada hierarquicamente para agentes IA e LLMs. Funciona de forma agnóstica com 7 diferentes agentes (Claude Code, Gemini CLI, etc.), oferecendo armazenamento vetorial multi-backend, embeddings plugáveis e integração nativa com Obsidian — tudo self-hosted sem lock-in de vendor.

Instalação

$npx convez-ai Dream-Pixels-Forge/memorius

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
1
Acompanhando
0
Saúde
42%
Último commit
há 2 dias
Versão
v0.9.9
Issues abertas
1
Contribuidores
1

Casos de uso

  • Persistir contexto e aprendizados entre sessões de agentes IA
  • Busca semântica em base de conhecimento acumulado
  • Mineração de memórias a partir de transcrições e conversas
  • Integração nativa com fluxos Obsidian para gestão de conhecimento

Veredito

Memorius resolve um problema real: agentes IA sem memória persistente. A arquitetura agnóstica (suporta 7 agentes via MCP) e self-hosted evita lock-in. Implementação sólida com ChromaDB + SQLite, CLI intuitiva e suporte a Obsidian fazem dele uma escolha técnica madura para quem precisa de memória estruturada e portável.

README

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

Memorius

🧠 Works with Claude Code, Codex CLI, Gemini CLI, OpenClaude, OpenCode, Pi, and any MCP-compatible agent.

🌐 Landing page: https://dream-pixels-forge.github.io/memorius/

Why Memorius?

Most AI memory tools lock you into one agent ecosystem. Memorius is agent-agnostic by design — the same memory vault works whether you use Claude Code, Codex CLI, Gemini CLI, or any MCP-compatible agent. No vendor lock-in.

FeatureMemoriusOthers
Agent support7 agents (auto-detected)Usually 1-3
ProtocolOpen MCP standardProprietary plugins
Memory hierarchyVault → Shelf → Folder → NoteFlat
Obsidian integrationNative import/export❌
Self-hosted✅ No cloud dependencyOften SaaS
Open source✅ MIT licenseVaries
pip install memorius

Quick Start

# Initialize a vault
memorius init

# Store a memory
memorius store "The sky is blue because Rayleigh scattering scatters shorter wavelengths more" --vault main --shelf science --folder physics

# Semantic search
memorius search "why is the sky blue"

# Mine memories from a conversation
memorius mine transcript.txt --vault conversations

# Check status
memorius status

# Write a diary entry
memorius diary --session "session-001" --title "Research findings"

Architecture

┌────────────────────────────────────────────────────────────┐
│                       Memorius                             │
├────────────────────────────────────────────────────────────┤
│  CLI        memorius init | store | search | mine | ...    │
│  MCP        JSON-RPC protocol server (stdin/stdout)        │
│  REST       FastAPI HTTP server (optional)                 │
│  Hooks      Auto-detect: Claude Code, Codex, Gemini, ...  │
│  Obsidian   Import / export notes from Obsidian vaults     │
├────────────────────────────────────────────────────────────┤
│  Vault Engine                                              │
│  ├── ChromaStore    Vector search (ChromaDB)               │
│  ├── SQLiteStore    Metadata & hierarchy (SQLite)          │
│  └── Embeddings     Pluggable providers (ONNX / SF / OA)   │
├────────────────────────────────────────────────────────────┤
│  Vault  >  Shelf  >  Folder  >  Note  hierarchy            │
│  Diaries          Session diary entries                    │
│  Mine             Extract memories from transcripts        │
├────────────────────────────────────────────────────────────┤
│  Plugin Gen    →  Generate per-agent plugins               │
│  Normalizers   →  Import Discord/Telegram/WhatsApp/etc     │
│  Obsidian      →  Bidirectional vault sync                 │
└────────────────────────────────────────────────────────────┘

Configuration

Config lives at ~/.memorius/config.yaml (auto-created on memorius init):

storage:
  path: ~/.memorius/data

embeddings:
  provider: chroma-default  # chroma-default | sentence-transformers | openai
  model: all-MiniLM-L6-v2

vault:
  default: main

server:
  mcp_port: 8910
  rest_port: 8912
  host: 127.0.0.1

Environment variable overrides:

VariableOverrides
MEMORIUS_STORAGE_PATHstorage.path
MEMORIUS_EMBEDDINGS_PROVIDERembeddings.provider
MEMORIUS_DEFAULT_VAULTvault.default
MEMORIUS_MCP_PORTserver.mcp_port
MEMORIUS_REST_PORTserver.rest_port
MEMORIUS_HOSTserver.host
MEMORIUS_OPENAI_API_KEYembeddings.openai.api_key

Embedding Providers

ProviderRequirementQuality
chroma-defaultChromaDB (bundled ONNX)Good (384d)
sentence-transformerspip install memorius[local-embeddings]Better (768d+)
openaiOPENAI_API_KEY env varBest (1536d)

CLI Reference

Core commands

memorius init                Initialize a new vault
memorius status              Show vault status
memorius store <text>        Store a memory
  --vault, -v                  Vault name (default: main)
  --shelf, -s                  Shelf name (default: default)
  --folder, -f                 Folder name (default: default)
  --note, -n                   Note name (default: default)
memorius search <query>      Semantic search
  --vault, -v                  Filter by vault
  --shelf, -s                  Filter by shelf
  --limit, -l                  Max results (default: 10)
memorius mine <file|text>    Extract memories from transcript
  --vault, -v                  Target vault (default: main)
memorius diary <session>     Write a diary entry
  --title, -t                  Entry title
  --summary, -s                Entry summary
  --vault, -v                  Vault name (default: main)
memorius diaries              List recent diary entries
memorius ls                   Explore vault hierarchy
memorius serve                Start MCP server (stdio)
memorius serve-rest           Start REST API server
memorius --version            Show version
memorius config               Show current configuration

Obsidian integration

memorius obsidian list                Explore vault structure
  --vault, -v                           Path to Obsidian vault directory
                                        (default: $OBSIDIAN_VAULT_PATH or
                                         ~/Documents/Obsidian Vault)

memorius obsidian import              Import Obsidian notes as memorius memories
  --vault, -v                           Path to Obsidian vault
  --target-vault                        Target memorius vault (default: main)
  --target-shelf                        Target memorius shelf (default: obsidian)
  --tag                                 Only import notes with this tag
  --dry-run                             Preview without importing

memorius obsidian export              Export memorius memories as Obsidian notes
  --vault, -v                           Path to Obsidian vault
  --source-vault                        Source memorius vault (default: main)
  --source-shelf                        Filter by shelf (default: all)
  --dry-run                             Preview without exporting

Import preserves the file hierarchy: vault/Subfolder/note.md maps to vault/Subfolder/vault > shelf > folder > note. YAML frontmatter is parsed and stored as memory attributes.

MCP Protocol

MCP is the primary interface for AI agents to interact with Memorius. Connect any MCP-compatible client by pointing it at the MCP server:

{
  "mcpServers": {
    "memorius": {
      "command": "memorius",
      "args": ["serve"]
    }
  }
}

Available MCP tools:

ToolDescription
memorius_statusMemory vault status
memorius_storeStore content in vault/shelf/folder/note hierarchy
memorius_searchSemantic search across vault
memorius_mineExtract memories from conversation
memorius_diary_writeWrite session diary entry
memorius_diary_listList diary entries
memorius_vault_lsBrowse vault hierarchy

Agent Skill Installation

Memorius ships with a ready-to-use agent skill (skills/memorius/SKILL.md) for agents that support the Hermes Agent skill format. The skill provides auto-capture rules, smart context injection, session diary templates, and workflow patterns — so agents can use memorius proactively without being told.

Skill Structure

skills/
  memorius/
    SKILL.md              # Full skill definition (auto-capture, context injection, diary rules)
    README.md             # Quick command reference
    .memorius_version     # Version tracker

Installing for Hermes Agent

The skill is designed for Hermes Agent — copy it into your Hermes skills directory:

# Copy the skill
cp -r skills/memorius ~/.hermes/skills/

# Verify it's loaded
hermes skills list | grep memorius

Once installed, Hermes will automatically detect it and follow the skill's workflows.

Installing for Other Agents

Agents that don't use the Hermes skill format can still use memorius via MCP or CLI:

AgentInstall Command
Claude Codeclaude mcp add memorius -- memorius serve
Codex CLIcodex mcp add memorius -- memorius serve
Gemini CLIgemini mcp add memorius $(which memorius) serve
CursorAdd to .cursor/mcp.json: {"mcpServers": {"memorius": {"command": "memorius", "args": ["serve"]}}}
Aideraider --mcp-servers memorius=memorius serve
ContinueAdd memorius to .continue/config.json MCP servers
OpenClawopenclaw mcp set memorius '{"command":"memorius","args":["serve"]}'

See manifest.yaml for the full list of supported agents and their install commands.

Copying the SKILL.md file directly may also work for agents with their own skills directory (e.g. ~/.claude/skills/, ~/.codex/skills/) — check your agent's documentation.

REST API

memorius serve-rest
MethodPathDescription
GET/healthHealth check
POST/storeStore a memory
POST/searchSemantic search
POST/mineExtract memories
GET/statusSystem status
POST/diaryWrite diary entry
GET/palaceBrowse hierarchy

Agent Hooks

Memorius includes universal agent lifecycle hooks — auto-detecting, agent-agnostic, and framework-free. Hook scripts are generated per agent:

memorius-plugin-gen init
# Edit universal-manifest.yaml
memorius-plugin-gen generate

Supported agents

AgentHook protocolEvents
Claude Code (Anthropic)stop_hook_active / precompactstop, precompact, session_start
Codex CLI (OpenAI)session_id + context_dirsession_start, session_stop
Gemini CLI (Google)conversation_id + extensionsstop, session_start
OpenClawopenclaw marker in payloadstop, session_stop, precompact, session_start
OpenCode (anomalyco/sst)provider dict + openCodeVersionstop, session_stop, session_start, precompact
Pi (kachow-compatible)event in Pi event setsession_start, session_shutdown, pre_compact, tool_call, turn_end
OpenClaudeOpenClaude marker in payloadstop, precompact, session_start

Auto-detection (no config needed)

Hooks are auto-detected from stdin — no --agent flag required. Just pipe agent hook JSON to the memorius hook engine and it figures out which agent sent the event:

# Hook engine auto-detects the agent
cat hook-payload.json | memorius-hook mine
cat hook-payload.json | memorius-hook diary

You can also force a specific agent with --agent:

memorius-hook mine --agent claude-code
memorius-hook diary --agent opencode

Detection priority (most-specific first): OpenClaude → Claude Code → Codex → Gemini CLI → OpenClaw → OpenCode → Pi → Generic

Plugin Generator (optional)

memorius-plugin-gen list          # Show supported agents
memorius-plugin-gen init          # Create universal-manifest.yaml
memorius-plugin-gen generate      # Generate plugins for all agents

Conversation Normalizers (optional)

memorius-normalize input.json     # Auto-detect and normalize
memorius-normalize input.json --format discord

Supported formats: Discord, Telegram, WhatsApp, generic JSON, plain text.

Development

git clone https://github.com/Dream-Pixels-Forge/memorius.git
cd memorius
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

# Run tests
pytest

# Run end-to-end
memorius init
memorius store "test memory"
memorius search "test"

License

MIT

Ver o original no GitHub

Bom para

Relacionados