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 GitHubMCP 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/memorius1 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
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.
| Feature | Memorius | Others |
|---|---|---|
| Agent support | 7 agents (auto-detected) | Usually 1-3 |
| Protocol | Open MCP standard | Proprietary plugins |
| Memory hierarchy | Vault → Shelf → Folder → Note | Flat |
| Obsidian integration | Native import/export | ❌ |
| Self-hosted | ✅ No cloud dependency | Often SaaS |
| Open source | ✅ MIT license | Varies |
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:
| Variable | Overrides |
|---|---|
MEMORIUS_STORAGE_PATH | storage.path |
MEMORIUS_EMBEDDINGS_PROVIDER | embeddings.provider |
MEMORIUS_DEFAULT_VAULT | vault.default |
MEMORIUS_MCP_PORT | server.mcp_port |
MEMORIUS_REST_PORT | server.rest_port |
MEMORIUS_HOST | server.host |
MEMORIUS_OPENAI_API_KEY | embeddings.openai.api_key |
Embedding Providers
| Provider | Requirement | Quality |
|---|---|---|
chroma-default | ChromaDB (bundled ONNX) | Good (384d) |
sentence-transformers | pip install memorius[local-embeddings] | Better (768d+) |
openai | OPENAI_API_KEY env var | Best (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:
| Tool | Description |
|---|---|
memorius_status | Memory vault status |
memorius_store | Store content in vault/shelf/folder/note hierarchy |
memorius_search | Semantic search across vault |
memorius_mine | Extract memories from conversation |
memorius_diary_write | Write session diary entry |
memorius_diary_list | List diary entries |
memorius_vault_ls | Browse 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:
| Agent | Install Command |
|---|---|
| Claude Code | claude mcp add memorius -- memorius serve |
| Codex CLI | codex mcp add memorius -- memorius serve |
| Gemini CLI | gemini mcp add memorius $(which memorius) serve |
| Cursor | Add to .cursor/mcp.json: {"mcpServers": {"memorius": {"command": "memorius", "args": ["serve"]}}} |
| Aider | aider --mcp-servers memorius=memorius serve |
| Continue | Add memorius to .continue/config.json MCP servers |
| OpenClaw | openclaw 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
| Method | Path | Description |
|---|---|---|
| GET | /health | Health check |
| POST | /store | Store a memory |
| POST | /search | Semantic search |
| POST | /mine | Extract memories |
| GET | /status | System status |
| POST | /diary | Write diary entry |
| GET | /palace | Browse 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
| Agent | Hook protocol | Events |
|---|---|---|
| Claude Code (Anthropic) | stop_hook_active / precompact | stop, precompact, session_start |
| Codex CLI (OpenAI) | session_id + context_dir | session_start, session_stop |
| Gemini CLI (Google) | conversation_id + extensions | stop, session_start |
| OpenClaw | openclaw marker in payload | stop, session_stop, precompact, session_start |
| OpenCode (anomalyco/sst) | provider dict + openCodeVersion | stop, session_stop, session_start, precompact |
| Pi (kachow-compatible) | event in Pi event set | session_start, session_shutdown, pre_compact, tool_call, turn_end |
| OpenClaude | OpenClaude marker in payload | stop, 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