Metadata-Version: 2.4
Name: memorius
Version: 0.1.3
Summary: Self-contained memory vault for any AI agent — vector search, session diaries, and agent-agnostic hooks.
Author-email: dimonapatrick243 <dimona.patrick@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/Dream-Pixels-Forge/memorius
Project-URL: Repository, https://github.com/Dream-Pixels-Forge/memorius
Project-URL: Issues, https://github.com/Dream-Pixels-Forge/memorius/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: No Input/Output (Daemon)
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyyaml>=6.0
Requires-Dist: chromadb>=0.4.0
Requires-Dist: httpx>=0.24.0
Provides-Extra: rest
Requires-Dist: fastapi>=0.104.0; extra == "rest"
Requires-Dist: uvicorn[standard]>=0.24.0; extra == "rest"
Requires-Dist: pydantic>=2.0.0; extra == "rest"
Requires-Dist: sse-starlette>=1.0.0; extra == "rest"
Provides-Extra: local-embeddings
Requires-Dist: sentence-transformers>=2.2.0; extra == "local-embeddings"
Provides-Extra: openai
Requires-Dist: openai>=1.0.0; extra == "openai"
Provides-Extra: all
Requires-Dist: memorius[local-embeddings,openai,rest]; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Dynamic: license-file

# Memorius

**Universal memory vault for any AI agent.**

Memorius is a self-contained, agent-agnostic memory system that gives LLMs and AI
agents persistent, searchable memory with a hierarchical knowledge organization.
Drop-in with multi-backend vector storage, pluggable embeddings, built-in MCP + REST
servers, and auto-detecting agent hooks for **7 different AI coding agents**.

```bash
pip install memorius
```

## Quick Start

```bash
# 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`):

```yaml
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

```bash
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

```bash
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:

```json
{
  "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 |

## REST API

```bash
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:

```bash
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:

```bash
# 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`:

```bash
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)

```bash
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)

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

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

## Development

```bash
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
