Up and running in 30 seconds

Step 1 Install

One command. All features — vector search, reranker, REST API, knowledge graph, and the agent skill — are included out of the box.

pip install memorius

For development (adds pytest + pytest-asyncio):

pip install "memorius[dev]"

Step 2 Initialize a vault

Creates the config file and storage. Runs the ONNX model download on first use.

memorius init

If you want to pre-download the bundled ONNX embedding model now (instead of on first search):

memorius setup

The vault engine lives under ~/.memorius/data by default. You can override every setting via the MEMORIUS_* environment variables or the YAML config — see Architecture → Configuration.

Step 3 Store your first memory

Content is embedded automatically and placed in the hierarchy you name.

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

Flags: --vault / --shelf / --folder / --note name the four levels of the hierarchy (all default to main / default). --ttl 30 sets a time-to-live in days.

Step 4 Find it later with semantic search

Relevance-ranked results from the vector store — you don't need the exact words.

memorius search "why is the sky blue"

Useful flags: --n 20 (more results), --expand-graph (pull in 1-hop linked memories), --rerank (cross-encoder precision), --web (fallback to live web when local recall is thin). Full flag reference is on the CLI page.

The Vault → Shelf → Folder → Note hierarchy

Four levels of organization, so a single vault can hold everything from one project to an entire research corpus.

Browse the live structure at any time:

memorius ls

Diaries, mined transcripts, and extracted memories each land in their own shelves, so your vault stays organized without manual filing.

See your vault in 3D

Browse memories the way you'd browse a library: one bookcase, one book per memory, and a librarian who tells you where things live.

memorius bookcase

One command opens the bookcase in your browser on a loopback-only page — no public endpoint, no new server. If the REST API isn't running yet, it starts one for you (and stops it again when you quit the page's process).

Every memory becomes a book on the case: the spine shows its shelf/folder/note path, the thickness tracks how long the memory is, and the colour tracks recency. The librarian greets you, narrates search results with shelf locations, and can even be asked directly — hold the microphone and speak. Toggle the librarian off and every utterance keeps landing as text. Two layouts: by shelf (path order) and by recency (newest on the left). Search the text box and the camera flies to the top match.

Install the agent skill

Memorius ships a pre-built agent skill. One command installs it into your agent's skill directory — no cloning, no build step.

npx skills add github.com/Dream-Pixels-Forge/memorius/tree/main/skills/memorius

The skill teaches any Hermes-compatible agent to use memorius proactively: auto-capture rules, smart context injection, session diaries, and workflow templates. For agents without the skill format, use the MCP server or the CLI directly.

Recommended first-week flow

1. Day 1 — memorius init, store a handful of decisions, search for them. Feel the hierarchy.
2. Day 2 — Mine a real transcript: memorius mine transcript.txt --vault conversations.
3. Day 3 — Wire your agent: add the MCP server to Claude Code / Codex / Gemini, or hook it up so memories capture automatically at session boundaries.
4. Ongoing — Run memorius doctor after big sessions, and memorius consolidate to merge duplicates as the vault grows.