Metadata-Version: 2.4
Name: rag-mem
Version: 0.1.2
Summary: RAG and Memory tools exposed via Model Context Protocol (MCP)
Project-URL: Homepage, https://github.com/MasihMoafi/A-Modular-Kingdom/tree/main/packages/memory-mcp
Project-URL: Repository, https://github.com/MasihMoafi/A-Modular-Kingdom
Project-URL: Documentation, https://github.com/MasihMoafi/A-Modular-Kingdom/tree/main/packages/memory-mcp#readme
Author: Masih
License-Expression: MIT
License-File: LICENSE
Keywords: chromadb,embeddings,llm,mcp,memory,qdrant,rag
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Requires-Dist: chromadb>=0.4.0
Requires-Dist: fastmcp>=0.1.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: langchain-community>=0.3.0
Requires-Dist: langchain>=0.3.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pymupdf>=1.24.0
Requires-Dist: qdrant-client>=1.7.0
Requires-Dist: rank-bm25>=0.2.2
Requires-Dist: tomli>=2.0.0; python_version < '3.11'
Provides-Extra: all
Requires-Dist: anthropic>=0.30.0; extra == 'all'
Requires-Dist: cohere>=5.0.0; extra == 'all'
Requires-Dist: openai>=1.0.0; extra == 'all'
Requires-Dist: sentence-transformers>=3.0.0; extra == 'all'
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.30.0; extra == 'anthropic'
Provides-Extra: cohere
Requires-Dist: cohere>=5.0.0; extra == 'cohere'
Provides-Extra: dev
Requires-Dist: black>=24.0.0; extra == 'dev'
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Provides-Extra: local
Requires-Dist: sentence-transformers>=3.0.0; extra == 'local'
Provides-Extra: openai
Requires-Dist: openai>=1.0.0; extra == 'openai'
Description-Content-Type: text/markdown

# rag-mem

RAG and Memory tools exposed via Model Context Protocol (MCP).

## Features

- **RAG (Retrieval-Augmented Generation)**: Semantic search over your documents
  - Hybrid retrieval (vector + BM25)
  - CrossEncoder reranking (optional)
  - Support for PDF, Markdown, Python, JSON, Jupyter notebooks
- **Memory System**: Persistent fact/memory storage
  - BM25-based fast search
  - ChromaDB vector fallback
  - Simple CRUD operations
- **Multiple Embedding Providers**:
  - Ollama (default, requires Ollama running)
  - SentenceTransformers (`pip install rag-mem[local]`)
  - OpenAI (`pip install rag-mem[openai]`)
  - Anthropic/Voyage (`pip install rag-mem[anthropic]`)
  - Cohere (`pip install rag-mem[cohere]`)
- **LLM-Agnostic**: Works with any LLM client that supports MCP

## Installation

```bash
# Basic install (fast, lightweight ~50MB)
pip install rag-mem

# Then install an embedding provider:
pip install rag-mem[local]    # SentenceTransformers (offline, +2GB PyTorch)
pip install rag-mem[openai]   # OpenAI API
pip install rag-mem[all]      # All providers
```

**Note**: Base install is fast. You must install an embedding provider separately, or use [Ollama](https://ollama.ai) (no extra install needed if Ollama is running).

## Quick Start

### 1. Initialize Configuration

```bash
memory-mcp init
```

This creates `~/.memory-mcp/config.toml` with default settings.

### 2. Start the Server

```bash
# Basic server
memory-mcp serve

# With document paths for RAG
memory-mcp serve --docs ./documents ./notes

# With specific embedding provider
memory-mcp serve --embed-provider openai --embed-model text-embedding-3-small
```

### 3. Connect from Claude Desktop

Add to your Claude Desktop config (`~/.config/claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "memory": {
      "command": "memory-mcp",
      "args": ["serve", "--docs", "/path/to/your/documents"]
    }
  }
}
```

## Configuration

Configuration is loaded from (in order of precedence):
1. Environment variables (prefixed with `MEMORY_MCP_`)
2. Config file (`~/.memory-mcp/config.toml`)
3. Default values

### Environment Variables

```bash
export MEMORY_MCP_EMBED_PROVIDER=openai
export MEMORY_MCP_OPENAI_API_KEY=sk-...
export MEMORY_MCP_QDRANT_MODE=cloud
export MEMORY_MCP_QDRANT_URL=https://your-cluster.qdrant.io
export MEMORY_MCP_QDRANT_API_KEY=...
```

### Config File Example

```toml
# ~/.memory-mcp/config.toml

# Embedding provider (choose one):
# Option 1: SentenceTransformers (requires: pip install rag-mem[local])
embed_provider = "sentence-transformers"
embed_model = "all-MiniLM-L6-v2"

# Option 2: Ollama (requires Ollama running, no extra pip install)
# embed_provider = "ollama"
# embed_model = "nomic-embed-text"

# Option 3: OpenAI (requires: pip install rag-mem[openai])
# embed_provider = "openai"
# openai_api_key = "sk-..."

# Qdrant settings
qdrant_mode = "local"  # local, cloud, or memory

# RAG settings
rag_chunk_size = 700
rag_top_k = 5
rag_rerank = true
```

## Docker

```bash
# Build
docker build -t memory-mcp .

# Run with OpenAI embeddings
docker run -it --rm \
  -v ./documents:/docs:ro \
  -v ./data:/data \
  -e MEMORY_MCP_EMBED_PROVIDER=openai \
  -e MEMORY_MCP_OPENAI_API_KEY=sk-... \
  memory-mcp serve --docs /docs

# Run with Ollama (requires host network for Ollama access)
docker run -it --rm \
  --network host \
  -v ./documents:/docs:ro \
  -v ./data:/data \
  memory-mcp serve --docs /docs
```

## Available Tools

When connected via MCP, these tools are available:

### RAG Tools

- **`query_knowledge_base`**: Search indexed documents
  - `query`: Search query
  - `doc_path`: Optional specific document path
  - `top_k`: Number of results

### Memory Tools

- **`save_memory`**: Store text content
- **`save_fact`**: Store structured fact with metadata
- **`search_memories`**: Search stored memories
- **`delete_memory`**: Delete by ID
- **`list_all_memories`**: List all stored memories

## CLI Commands

```bash
# Initialize config
memory-mcp init

# Show current config
memory-mcp config

# Start MCP server
memory-mcp serve [--docs PATH...] [--embed-provider PROVIDER]

# Index documents (without starting server)
memory-mcp index PATH... [--force]
```

## Python API

```python
from memory_mcp import Settings, create_server
from memory_mcp.rag import RAGPipeline
from memory_mcp.memory import MemoryStore

# Custom settings
settings = Settings(
    embed_provider="openai",
    openai_api_key="sk-...",
)

# Use RAG directly
pipeline = RAGPipeline(
    settings=settings,
    document_paths=["./docs"],
)
pipeline.index()
results = pipeline.search("How does authentication work?")

# Use memory directly
memory = MemoryStore(settings)
memory.add("User prefers dark mode")
memories = memory.search("preferences")
```

## Custom Embedding Providers

Implement the `EmbeddingProvider` interface:

```python
from memory_mcp.embeddings.base import EmbeddingProvider

class MyEmbeddings(EmbeddingProvider):
    @property
    def dimension(self) -> int:
        return 768

    def embed_documents(self, texts: list[str]) -> list[list[float]]:
        # Your implementation
        pass

    def embed_query(self, text: str) -> list[float]:
        # Your implementation
        pass
```

## Architecture

```
memory-mcp/
├── embeddings/     # Pluggable embedding providers
├── rag/            # RAG pipeline (Qdrant + BM25 + reranking)
├── memory/         # Memory store (ChromaDB + BM25)
├── server.py       # FastMCP server
├── config.py       # Pydantic settings
└── cli.py          # CLI entry point
```

## License

MIT
