memoreei 0.2.0__tar.gz

memoreei-0.2.0/.env.example

@@ -0,0 +1,50 @@
+# ══════════════════════════════════════════════════════════════
+# Memoreei Configuration
+# Copy to .env and uncomment/fill values you need
+# ══════════════════════════════════════════════════════════════
+
+# ── Core ─────────────────────────────────────────────────────
+MEMOREEI_DB_PATH=./memoreei.db
+EMBEDDING_PROVIDER=fastembed
+# OPENAI_API_KEY=sk-...  # only if EMBEDDING_PROVIDER=openai
+
+# ── Auto Sync (optional) ─────────────────────────────────────
+# MEMOREEI_AUTO_SYNC=false
+# MEMOREEI_SYNC_INTERVAL=300  # seconds between background syncs
+
+# ── Discord (live API sync) ──────────────────────────────────
+# DISCORD_BOT_TOKEN=
+# DISCORD_CHANNEL_ID=
+
+# ── Telegram ─────────────────────────────────────────────────
+# TELEGRAM_BOT_TOKEN=
+# TELEGRAM_CHAT_ID=
+
+# ── Slack ────────────────────────────────────────────────────
+# SLACK_BOT_TOKEN=
+# SLACK_CHANNEL_ID=
+
+# ── Matrix ───────────────────────────────────────────────────
+# MATRIX_HOMESERVER=https://matrix.org
+# MATRIX_ACCESS_TOKEN=
+# MATRIX_ROOM_ID=
+
+# ── Mastodon ─────────────────────────────────────────────────
+# MASTODON_INSTANCE=https://mastodon.social
+# MASTODON_HASHTAG=
+# MASTODON_ACCESS_TOKEN=
+
+# ── Gmail (IMAP) ─────────────────────────────────────────────
+# GMAIL_EMAIL=
+# GMAIL_APP_PASSWORD=
+
+# ── iMessage (macOS only, local DB read) ─────────────────────
+# IMESSAGE_DB_PATH=~/Library/Messages/chat.db
+
+# ── Signal Desktop (local encrypted DB) ──────────────────────
+# SIGNAL_DB_PATH=  # auto-detected if blank
+# SIGNAL_CONFIG_PATH=  # auto-detected if blank
+
+# ── TMDB (for Movie Ring example app) ────────────────────────
+# TMDB_API_KEY=
+# TMDB_READ_TOKEN=

memoreei-0.2.0/.gitignore

@@ -0,0 +1,28 @@
+.env
+*.db
+*.db-shm
+*.db-wal
+__pycache__/
+*.py[cod]
+*.pyo
+.venv/
+venv/
+env/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+*.so
+node_modules/
+.DS_Store
+logs/
+.internal/
+.mcp.json
+ralph.env
+REFACTOR_PLAN.md
+ENTRY.md
+PLAN.md
+TASK.md
+tasks.json

memoreei-0.2.0/CLAUDE.md

@@ -0,0 +1,42 @@
+# CLAUDE.md — Memoreei Project Context
+
+## What This Is
+Memoreei is an MCP server for personal memory search. It ingests messages from Discord, WhatsApp, Telegram, Matrix, Slack, Gmail, and more — stores them in a hybrid search database (keyword + vector) — and exposes them via MCP tools.
+
+## MCP Tools Available
+You have these tools via the `memoreei` MCP server:
+
+| Tool | What it does |
+|------|-------------|
+| `sync_discord` | Pull messages from Discord channel into memory DB |
+| `search_memory` | Hybrid keyword + semantic search across all sources |
+| `get_context` | Get surrounding messages around a search hit |
+| `add_memory` | Manually store a note or fact |
+| `list_sources` | Show all ingested sources with message counts |
+| `ingest_whatsapp` | Import a WhatsApp chat export .txt file |
+
+## How to Use
+- **To search:** Use `search_memory` with a natural language query. It does hybrid BM25 + vector search with RRF fusion.
+- **To sync Discord:** Use `sync_discord` — it reads the bot token and channel from .env automatically.
+- **To get context around a result:** Use `get_context` with the memory ID from search results.
+- **To see what's ingested:** Use `list_sources`.
+
+## DO NOT
+- Do NOT try to access Discord APIs directly or unlock Bitwarden — the MCP tools handle everything.
+- Do NOT use `bw` commands. The server has its own credentials in `.env`.
+
+## Project Structure
+```
+src/memoreei/
+├── server.py              # MCP server (FastMCP, stdio)
+├── storage/database.py    # SQLite + FTS5 + vector search
+├── search/hybrid.py       # Hybrid search with RRF fusion
+├── connectors/            # Discord, WhatsApp, Telegram, Matrix, Slack, Email
+└── tools/memory_tools.py  # MCP tool implementations
+```
+
+## Key Paths
+- **DB:** `./memoreei.db` (SQLite + FTS5)
+- **Venv:** `.venv/bin/python`
+- **Config:** `.env` (tokens, channel IDs)
+- **MCP config:** `.mcp.json` (also in `~/.claude/settings.json`)

memoreei-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,61 @@
+# Contributing to Memoreei
+
+Welcome! Memoreei is a personal memory search server that ingests messages from Discord, WhatsApp, Telegram, Matrix, Slack, and Gmail into a hybrid search database. Contributions are appreciated.
+
+## Dev Environment Setup
+
+```bash
+git clone https://github.com/your-fork/memoreei.git
+cd memoreei
+python -m venv .venv
+source .venv/bin/activate
+pip install -e '.[dev]'
+```
+
+Copy `.env.example` to `.env` and fill in any credentials you want to test with:
+
+```bash
+cp .env.example .env
+```
+
+## Running Tests
+
+```bash
+pytest
+```
+
+With coverage:
+
+```bash
+pytest --cov=src/memoreei --cov-report=term-missing
+```
+
+Tests use `pytest-asyncio` (auto mode). All tests run against a fresh in-memory SQLite database per test — no external services required.
+
+## Code Style
+
+- **Type hints** on all function signatures
+- **Docstrings** on public classes and non-trivial methods
+- **Async** throughout — all I/O is async
+- Keep functions focused; prefer small composable pieces over large methods
+
+No formatter is enforced yet, but aim for PEP 8 style. A simple `ruff check src/` before submitting is appreciated.
+
+## Adding a New Connector
+
+See [docs/connectors.md](docs/connectors.md) for a step-by-step guide. The short version:
+
+1. Create `src/memoreei/connectors/yourplatform_connector.py` implementing `BaseConnector`
+2. Register it in `src/memoreei/connectors/__init__.py`
+3. Add config fields to `src/memoreei/config.py`
+4. Add an MCP tool in `src/memoreei/server.py`
+5. Write tests in `tests/test_yourplatform.py`
+
+## PR Process
+
+1. Fork the repo and create a branch: `git checkout -b feat/my-feature`
+2. Make your changes and add tests
+3. Ensure `pytest` passes
+4. Open a pull request with a clear description of what it does and why
+
+Keep PRs focused — one feature or fix per PR makes review easier. If you're unsure about scope or approach, open an issue first.

memoreei-0.2.0/DEMO.md

@@ -0,0 +1,105 @@
+# Memoreei — Live Demo Script (3 minutes)
+
+## Pre-Demo Setup
+
+Run this before going on screen:
+
+```bash
+bash scripts/demo_setup.sh
+```
+
+It will seed the database if empty, verify the MCP server starts, and print a readiness checklist.
+
+**What should be visible:**
+- Claude Code open with Memoreei MCP server connected (`.mcp.json` in project root)
+- Discord `#memoreei-demo` channel visible
+- Terminal ready for ad-hoc commands if needed
+
+---
+
+## The Demo
+
+### Opening (15 sec)
+
+> "This is Memoreei — a personal memory server. It ingests your conversations from anywhere — Discord, Telegram, WhatsApp, email — and makes them searchable by any AI model through MCP."
+
+### Architecture (15 sec)
+
+> "It's not a chatbot. It's infrastructure. Any MCP client connects to it — Claude Code, Cursor, your own apps. Your data stays local. Embeddings run locally via ONNX. No cloud, no API keys required."
+
+### Live Discord Demo (60 sec)
+
+1. Switch to Discord — show `#memoreei-demo` with existing bot conversation
+2. **Type a new message** in the channel:
+   > *"Hey everyone, I just found out that the secret ingredient in grandma's cookies is actually cardamom"*
+3. Switch to Claude Code
+4. Say: **"Sync my Discord and tell me what people have been talking about"**
+   - Claude calls `sync_discord` → picks up all messages including the one just typed
+   - Claude calls `search_memory` → summarizes the conversation
+5. Say: **"What was the secret ingredient I just mentioned?"**
+   - Returns: *"cardamom"* — with the exact message and timestamp
+   - *This is the money shot — real-time memory from a message typed 30 seconds ago*
+
+### Multi-Source Search (45 sec)
+
+6. Say: **"Search all my memories for anything about movies"**
+   - Returns results across Discord, WhatsApp, and manual notes — multiple sources, one query
+7. Say: **"Who have I been talking to the most this week?"**
+   - Returns participant stats fused across sources
+
+### Show Sources (15 sec)
+
+8. Say: **"List all my memory sources"**
+   - Shows each source with message counts: `discord:...`, `whatsapp:...`, `manual`
+   > *"One server. Every conversation. Any AI client."*
+
+### Use Case Flash (if time — 15 sec)
+
+- Quick flash of the Movie Ring web app or Memory Search UI
+> "Because it's an MCP server, anything can build on top of it. This web app scans conversations for movie mentions and shows what my friends are recommending."
+
+### Close (15 sec)
+
+> "Memoreei. Your AI's long-term memory. Local-first, open source, and on GitHub right now."
+>
+> Drop the repo link.
+
+---
+
+## Backup Plans
+
+| Problem | Recovery |
+|---------|----------|
+| Claude Code is slow | Have pre-run query results ready to paste |
+| Discord sync fails | WhatsApp data is already seeded — search `whatsapp:printer_conspiracy` |
+| Embeddings slow on first sync | "First sync downloads the model — here's one I prepared earlier" → show pre-populated results |
+| MCP server not connected | Run `bash scripts/demo_setup.sh` and reconnect in Claude Code settings |
+
+---
+
+## MCP Tools Reference
+
+| Tool | What it does |
+|------|-------------|
+| `sync_discord` | Pull new messages from Discord channel into memory |
+| `search_memory` | Hybrid keyword + semantic search across all sources |
+| `get_context` | Fetch surrounding messages around a memory hit |
+| `add_memory` | Manually store a note or fact |
+| `list_sources` | Show all ingested sources with message counts |
+| `ingest_whatsapp` | Import a WhatsApp chat export `.txt` file |
+
+---
+
+## Key Phrases to Hit
+
+- "Not a chatbot — it's infrastructure"
+- "Any MCP client can connect"
+- "Your data stays local"
+- "Real-time ingestion"
+- "Open source"
+
+## Words to Avoid
+
+- "RAG" — just show it working
+- "Basic" anything
+- Explaining vector databases — the demo speaks for itself

memoreei-0.2.0/Dockerfile

@@ -0,0 +1,10 @@
+FROM python:3.12-slim
+WORKDIR /app
+COPY pyproject.toml .
+COPY src/ src/
+COPY data/ data/
+RUN pip install --no-cache-dir .
+ENV MEMOREEI_DB_PATH=/data/memoreei.db
+VOLUME /data
+ENTRYPOINT ["memoreei"]
+CMD ["serve"]