Memorius
Universal memory vault for any AI agent.
Works with Claude Code, Codex CLI, Gemini CLI, OpenClaude, OpenCode, Pi, OpenClaw, and any MCP-compatible agent.
📚 Documentation: https://dream-pixels-forge.github.io/memorius/ — install, CLI reference, MCP server, hooks, REST API, architecture, and the memory engine, all on the site.
If you find this project useful, leaving a star ⭐ on the repository is the best way to support my work!
Memorius is a self-contained, agent-agnostic memory system with hierarchical knowledge organization, pluggable embeddings, and neuroscience-inspired consolidation. One vault, many frontends — CLI, MCP, REST, and auto-detecting agent hooks. No cloud, no API keys, no lock-in.
Install
pip install memorius
All features — vector search, cross-encoder reranker, REST API server, SQLite-vec backend, OpenAI embeddings, knowledge graph, and the agent skill — are included out of the box. No extra install flags needed.
Verify:
memorius --version
memorius init # creates ~/.memorius/config.yaml + storage dir
CLI Reference
memorius stats
Show vault + memory + graph statistics --json Output as JSON
memorius status
Show vault status --json Output as JSON
memorius bookcase
Launch the 3D walkable vault bookcase (browser opens automatically, loopback only). --port REST API port (default: 8912) --static-port Static asset port for the bookcase page (default: 8400) --no-browser Don't open the browser; just serve the page
Vault Bookcase (3D walkable)
Run the bookcase:
memorius bookcase
It starts the REST API on http://127.0.0.1:8912, serves the bookcase page on
http://127.0.0.1:8400/bookcase.html, and opens your browser. Everything is
loopback-only — nothing leaves your machine.
Use memorius bookcase --no-browser to serve without opening a tab, then open
the printed URL yourself. Use --port / --static-port if the defaults are
taken.
Once the page is open:
- Walk: WASD or arrow keys at eye height. You can't pass through shelves.
- Look: click-drag to look around (pointer-lock if available).
- Vault: pick a vault from the dropdown (options come from
GET /vaults). - Layout: switch between "by shelf" and "by recency" to re-arrange cases.
- Search: type in the vault search bar and hit Enter/Go — the camera flies to the matching book and marks it.
- Book click: click a book to open its detail panel (content + librarian speech when the Librarian toggle is on).
- Mic: hold the mic button to speak your search (Chromium only).
- Reset view: click ⟲ view to return to the starting camera position.
The librarian reads each book aloud when toggled on; all utterances are also logged in the guidance panel on the page.
For development
pip install "memorius[dev]" # adds pytest + pytest-asyncio
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
That's the whole loop: store → embed → search. Read the Getting Started guide for the vault hierarchy, the agent skill, and a recommended first-week flow.
Documentation
The full docs live on the site — each concern on its own page:
| Page | What's on it |
|---|---|
| Getting Started | Install, init, first memory, the Vault→Shelf→Folder→Note hierarchy, agent skill |
| CLI Reference | Every subcommand and flag (incl. repair and --json) |
| MCP Server | All 29 tools + per-agent client config snippets |
| Agent Hooks | Auto-detecting lifecycle hooks, 10 actions, normalizers, security |
| REST API | Full endpoint table, auth, rate limits, daemon mode, TLS |
| Architecture | Search pipeline, embeddings, vector backends, graph, configuration |
| Agent Compatibility | Which agents, detection priority, how to plug in your own |
| Memory Engine | Decay, consolidation, pruning, fact-checking, reranking, doctor, repair |
Command cheat sheet (details on the CLI reference)
memorius store "text" [--vault/--shelf/--folder/--note/--ttl]
memorius search "query" [--n/--expand-graph/--rerank/--web/--tag]
memorius mine file.txt [--vault/--text]
memorius extract file.txt [--backend openai|ollama|regex]
memorius diary "session" [--title/--summary]
memorius ls [vault]
memorius consolidate [--threshold/--dry-run]
memorius factcheck "stmt" [--web]
memorius profile "session"
memorius prune [--threshold/--dry-run/--delete]
memorius graph [view|export-html|stats|json]
memorius learn "text" --category bug_fix
memorius recall "query"
memorius obsidian [list|import|export]
memorius export ./backup [--format json|markdown]
memorius import ./backup.json [--replace]
memorius doctor # 6 health checks
memorius repair [--reindex/--dry-run] # fix vector/meta drift (v0.8.6)
memorius stats [--json] # vault + memory + graph + doctor summary
memorius status [--json] # vault + embeddings + recent diaries
memorius serve # MCP server (stdio)
memorius serve-rest [--daemon/--stop] # FastAPI server
License
MIT · Full release history in CHANGELOG.md.
1 maintainer
Metadata
1 maintainer
Release files for memorius 0.9.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| memorius-0.9.2.tar.gz | 249.5 kB | With provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| memorius-0.9.2-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 443.5 kB
Release files / memorius-0.9.2.tar.gz
| Download URL | memorius-0.9.2.tar.gz |
|---|---|
| Size | 249.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
f6ea56db8df810942818e345a77d04a52139efe8a3379ee1672f9ab288bd2598
|
|
BLAKE2b-256 checksum How to use checksums |
36f2d98f9892d2349841ae0683bf4834658eb2526090edd692e5cd13bfafcaf8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 19, 2026.
Transparency logRelease files / memorius-0.9.2-py3-none-any.whl
| Download URL | memorius-0.9.2-py3-none-any.whl |
|---|---|
| Size | 194.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
3670baef6e93c8260e0253604b4b3d4cd4d4af82f61fcdd2170fd1a5be3a8348
|
|
BLAKE2b-256 checksum How to use checksums |
a7ffb034fa5afddc4214361ddee1486e73c5d95e5a41582ea1a2e3a37d17fcea
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 19, 2026.
Transparency logSecurity for memorius 0.9.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
All 2 files in this release have been uploaded with provenance metadata.
Attestation for memorius-0.9.2.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 19, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
