Memox 🧠

Store your mind — A personal knowledge storage system using RAG and Graph Database.

Memox lets you save quotes, images, and web content as interconnected knowledge nodes. Search your memory semantically using natural language queries.

✨ Features

• Semantic Search — Find knowledge by meaning, not just keywords (powered by LEANN)
• Graph Storage — Store knowledge as nodes in Neo4j for future relationship queries
• Web Scraping — Automatically extract content from URLs via Firecrawl
• Image Storage — Store images in Cloudflare R2 (S3-compatible)
• RESTful API — Simple FastAPI endpoints with OpenAPI docs

🏗️ Architecture

┌─────────────┐     ┌──────────────────────────────────────────┐
│   Client    │────▶│              FastAPI                     │
└─────────────┘     └──────────────────────────────────────────┘
                                      │
        ┌─────────────────────────────┼─────────────────────────────┐
        ▼                             ▼                             ▼
┌───────────────┐           ┌─────────────────┐           ┌─────────────────┐
│   Firecrawl   │           │     Neo4j       │           │   Cloudflare    │
│   (Scraper)   │           │   (Graph DB)    │           │   R2 (Storage)  │
└───────────────┘           └─────────────────┘           └─────────────────┘
                                      │
                                      ▼
                            ┌─────────────────┐
                            │     LEANN       │
                            │   (Vector DB)   │
                            └─────────────────┘

📦 Installation

Prerequisites

• Python 3.11+
• uv package manager
• Neo4j (local or cloud)
• Firecrawl API key (optional, for URL scraping)
• Cloudflare R2 credentials (optional, for image storage)

Quick Start

# Clone the repository
git clone <your-repo-url>
cd memox

# Install dependencies
uv sync

# Configure environment
cp .env.example .env
# Edit .env with your credentials

# Start Neo4j (using Docker)
docker run -d --name neo4j \
  -p 7474:7474 -p 7687:7687 \
  -e NEO4J_AUTH=neo4j/password \
  neo4j:latest

# Run the server
uv run uvicorn memox.main:app --reload

The API will be available at http://localhost:8000

⚙️ Configuration

Create a .env file from the example:

Variable	Description	Required
NEO4J_URI	Neo4j connection URI	Yes
NEO4J_USER	Neo4j username	Yes
NEO4J_PASSWORD	Neo4j password	Yes
FIRECRAWL_API_KEY	Firecrawl API key for web scraping	No
R2_ENDPOINT	Cloudflare R2 endpoint URL	No
R2_ACCESS_KEY	R2 access key ID	No
R2_SECRET_KEY	R2 secret access key	No
R2_BUCKET	R2 bucket name	No
LEANN_INDEX_PATH	Path to store LEANN vector index	No

🚀 API Usage

Interactive Docs

Visit http://localhost:8000/docs for Swagger UI.

Endpoints

Health Check

GET /health

{"status": "ok"}

---

Store Knowledge

POST /knowledge
Content-Type: application/json

Request Body:

Field	Type	Description
quote	string	Text/quote to store (optional)
image_url	string	Image URL to download and store (optional)
url	string	Source URL to scrape for context (optional)

At least one field must be provided.

Example:

curl -X POST http://localhost:8000/knowledge \
  -H "Content-Type: application/json" \
  -d '{
    "quote": "The only way to do great work is to love what you do.",
    "url": "https://example.com/article"
  }'

Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "quote": "The only way to do great work is to love what you do.",
  "context": "Extracted content from the URL...",
  "image_url": null,
  "source_url": "https://example.com/article",
  "created_at": "2026-01-02T10:00:00Z"
}

---

Search Knowledge

GET /knowledge/search?q={query}&top_k={limit}

Query Parameters:

Param	Type	Default	Description
q	string	required	Search query
top_k	integer	10	Number of results (1-100)

Example:

curl "http://localhost:8000/knowledge/search?q=great+work&top_k=5"

Response:

{
  "query": "great work",
  "results": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "quote": "The only way to do great work is to love what you do.",
      "context": "...",
      "image_url": null,
      "source_url": "https://example.com/article",
      "score": 0.92
    }
  ]
}

🗂️ Project Structure

memox/
├── pyproject.toml              # Project dependencies
├── .env.example                # Environment template
└── src/memox/
    ├── __init__.py
    ├── main.py                 # FastAPI application
    ├── config.py               # Settings management
    ├── models.py               # Pydantic schemas
    ├── routers/
    │   └── knowledge.py        # API endpoints
    └── services/
        ├── scraper.py          # Firecrawl HTTP client
        ├── storage.py          # R2 (S3) operations
        ├── graph.py            # Neo4j operations
        └── vector.py           # LEANN vector search

🔧 Development

# Run with auto-reload
uv run uvicorn memox.main:app --reload

# Run on specific port
uv run uvicorn memox.main:app --port 3000

# Type checking (install mypy first)
uv run mypy src/memox

📝 How It Works

1. Store Knowledge

   • If url is provided: Scrape content via Firecrawl API
   • If image_url is provided: Download and upload to R2
   • Create a node in Neo4j with all metadata
   • Index the combined text (quote + context) in LEANN

2. Search Knowledge

   • Convert query to vector using LEANN
   • Find similar nodes by semantic similarity
   • Return ranked results from Neo4j

🧪 Tech Stack

Component	Technology
Web Framework	FastAPI
Vector DB	LEANN
Graph DB	Neo4j
Object Storage	Cloudflare R2
Web Scraping	Firecrawl
Package Manager	uv

📄 License

MIT