Import AITURK IDE 1.0.0-beta.1 from Hermes 63279301; preserve MIT license

plugins/memory/mem0/README.md

@@ -0,0 +1,187 @@
+# Mem0 Memory Provider
+
+Server-side LLM fact extraction with semantic search and hybrid multi-signal retrieval via the Mem0 Platform v3 API.
+
+## Requirements
+
+- `pip install mem0ai`
+- Mem0 API key from [app.mem0.ai](https://app.mem0.ai)
+
+## Setup
+
+```bash
+hermes memory setup    # select "mem0"
+```
+
+Or manually:
+```bash
+hermes config set memory.provider mem0
+echo "MEM0_API_KEY=your-key" >> ~/.hermes/.env
+```
+
+## Config
+
+Behavioral settings live in `$HERMES_HOME/mem0.json` (set them via `hermes memory setup`). Only the secret `MEM0_API_KEY` belongs in `~/.hermes/.env`.
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `mode` | `platform` | `platform` (Mem0 Cloud) or `oss` (self-managed, in-process) |
+| `host` | — | Self-hosted Mem0 server URL (the Docker dashboard). When set, connects over HTTP with `X-API-Key`. Don't combine with `mode: oss` |
+| `user_id` | `hermes-user` | User identifier on Mem0 |
+| `agent_id` | `hermes` | Agent identifier |
+| `rerank` | `false` | Rerank search results for relevance (platform mode only) |
+
+The plugin has three connection modes:
+
+- **Platform** — Mem0's hosted cloud (`api.mem0.ai`). Set `MEM0_API_KEY`. (default)
+- **Self-hosted dashboard** — a Mem0 server you run yourself via Docker. Set `host`. See below.
+- **OSS** — run Mem0 in-process with your own LLM + vector store. Set `mode: oss`. See below.
+
+## Self-Hosted Dashboard (Server) Mode
+
+Connect the plugin to a standalone Mem0 server you run yourself — the Docker-shipped Mem0 dashboard/server with its own REST API. Unlike OSS mode (which runs `mem0ai` in-process with your own vector store), here the plugin just talks HTTP to your server.
+
+1. Run the Mem0 server (FastAPI + pgvector) from its Docker image and note its URL and `ADMIN_API_KEY`.
+2. Point the plugin at it — via the setup wizard:
+   ```bash
+   hermes memory setup    # select "mem0" → "Self-hosted server"
+   # Or non-interactive:
+   hermes memory setup mem0 --mode selfhosted --host http://localhost:8888 --api-key your-admin-api-key
+   ```
+   or via env vars:
+   ```bash
+   echo "MEM0_HOST=http://localhost:8888" >> ~/.hermes/.env
+   echo "MEM0_API_KEY=your-admin-api-key" >> ~/.hermes/.env
+   ```
+   or in `$HERMES_HOME/mem0.json`:
+   ```json
+   {
+     "host": "http://localhost:8888",
+     "api_key": "your-admin-api-key"
+   }
+   ```
+3. Start a fresh Hermes session and call `mem0_search` — it connects to your server.
+
+The plugin authenticates with `X-API-Key` and uses the server's `/search` and `/memories` routes. `api_key` is optional — omit it only for servers running with `AUTH_DISABLED`.
+
+> Setting `host` routes to the self-hosted server automatically. Don't set `mode: oss` — OSS takes precedence and ignores `host`.
+
+## OSS (Self-Hosted) Mode
+
+Run Mem0 locally with your own LLM, embedder, and vector store. This is the in-process SDK mode. To instead connect to a Mem0 server you run via Docker, see [Self-Hosted Dashboard (Server) Mode](#self-hosted-dashboard-server-mode) above.
+
+### Interactive Setup
+
+```bash
+hermes memory setup
+# Select "mem0" → "Open Source (self-hosted)"
+# Follow prompts for LLM, embedder, and vector store
+```
+
+### Agent-Driven Setup (Flags)
+
+```bash
+hermes memory setup mem0 --mode oss \
+  --oss-llm openai --oss-llm-key sk-... \
+  --oss-vector qdrant
+```
+
+### Supported Providers
+
+| Component | Providers |
+|-----------|-----------|
+| LLM | openai, ollama |
+| Embedder | openai, ollama |
+| Vector Store | qdrant (local/server), pgvector |
+
+### Flags Reference
+
+| Flag | Description |
+|------|-------------|
+| `--mode` | `platform` or `oss` |
+| `--oss-llm` | LLM provider (default: openai) |
+| `--oss-llm-key` | LLM API key |
+| `--oss-embedder` | Embedder provider (default: openai) |
+| `--oss-vector` | Vector store (default: qdrant) |
+| `--oss-vector-path` | Qdrant local path |
+| `--user-id` | User identifier |
+
+## Switching Modes
+
+### Platform to OSS
+
+```bash
+hermes memory setup mem0 --mode oss --oss-llm-key sk-...
+```
+
+Or edit `$HERMES_HOME/mem0.json` directly:
+```json
+{
+  "mode": "oss",
+  "oss": {
+    "llm": {"provider": "openai", "config": {"model": "gpt-5-mini", "is_reasoning_model": true}},
+    "embedder": {"provider": "openai", "config": {"model": "text-embedding-3-small"}},
+    "vector_store": {"provider": "qdrant", "config": {"path": "~/.hermes/mem0_qdrant"}}
+  }
+}
+```
+
+### OSS to Platform
+
+```bash
+hermes memory setup mem0 --mode platform --api-key sk-...
+```
+
+### Dry Run (preview without writing)
+
+```bash
+hermes memory setup mem0 --mode oss --oss-llm-key sk-... --dry-run
+```
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `mem0_search` | Semantic search by meaning |
+| `mem0_add` | Store a fact verbatim (no LLM extraction) |
+| `mem0_update` | Update a memory's text by ID |
+| `mem0_delete` | Delete a memory by ID |
+
+## Troubleshooting
+
+### "Mem0 temporarily unavailable"
+
+Circuit breaker tripped after 5 consecutive failures. Resets after 2 minutes.
+
+- **Platform mode**: Check API key and internet connectivity.
+- **OSS mode**: Check that your vector store (qdrant/pgvector) is running.
+
+### OSS: Qdrant connection refused
+
+```bash
+# If using local Qdrant, check the storage path is writable:
+ls -la ~/.hermes/mem0_qdrant
+
+# If using Qdrant server, check it's reachable:
+curl http://localhost:6333/healthz
+```
+
+### OSS: PGVector connection refused
+
+```bash
+# Verify PostgreSQL is running and accepting connections:
+pg_isready -h localhost -p 5432
+```
+
+### OSS: Ollama not reachable
+
+```bash
+# Check Ollama is running:
+curl http://localhost:11434/api/tags
+```
+
+### Memories not appearing
+
+- `mem0_add` stores verbatim (no extraction). Use `sync_turn` for LLM extraction.
+- Search uses semantic matching — try broader queries.
+- Check `user_id` matches between sessions (`$HERMES_HOME/mem0.json`).