flowdb 0.1.0

The AI-Native Database: JSON + Vectors + MCP

FlowDB

The AI-Native Database for Agents, Automations, and Speed.

FlowDB is a Hybrid Vector-JSON Database designed for the age of AI. It replaces the complex "Postgres + Pinecone + Docker + Glue Code" stack with a single, lightweight Python package.

It is MCP-Native, meaning LLMs (like Claude) can read, write, and search your database directly without you writing a single line of API wrapper code.

---

The Philosophy: "SQLite for Agents"

Traditional databases (SQL) are built for accounting. They require rigid schemas, migrations, and complex setup. FlowDB is built for Agents. It assumes that:

1. Data is messy: You want to store JSON documents, not rows.
2. Meaning matters: Everything should be vector-searchable by default.
3. Speed is life: You shouldn't need 3 containers just to save a user preference.

✅ When to use FlowDB

• AI Agents & Assistants: Give Claude/OpenAI long-term memory in 5 minutes.
• Local-First Automation (n8n): Pipe raw JSON from webhooks directly into storage without schema errors.
• Rapid Prototyping: Build backend APIs in minutes using Pydantic models.
• RAG Applications: "Chat with your data" apps where setup speed > complex relations.

❌ When NOT to use FlowDB

• Fintech / High-Stakes Transactional Systems: If you need complex ACID compliance across multiple tables (e.g., bank transfers), use Postgres.
• Massive Relational Data: If you need 10-way JOINs, use a SQL database.

---

Features

• JSON Native: No schemas. No migrations. Just upsert Pydantic models or raw JSON.
• Auto-Vectorization: Automatically embeds your data using OpenAI (or custom models) on write. No separate embedding pipeline required.
• Hybrid Architecture: Runs as a local background process (for dev) or a Docker container (for production).
• MCP Ready: Exposes a Model Context Protocol (MCP) interface, turning your database into a "Long Term Memory" tool for AI Agents or giving you AI assistance with your data.
• Fast: Built on LMDB (Lightning Memory-Mapped Database) and USearch (HNSW Vector Search).

---

📦 Installation

pip install flowdb

---

Configuration

FlowDB is configured via a .env file in your project root or via Environment Variables.

Variable	Description	Required?	Default
OPENAI_API_KEY	Your OpenAI Key for auto-vectorization.	Yes	None
FLOWDB_API_KEY	Secures the DB. If set, clients must provide this key.	No	None (Open Access)
FLOWDB_PATH	Where data files are stored on disk.	No	./flow_data
FLOWDB_VECTORIZER	Provider to use (openai or mock).	No	auto

Example .env file:

OPENAI_API_KEY=sk-proj-12345...
FLOWDB_API_KEY=my-super-secret-password
FLOWDB_PATH=./my_db_storage
FLOWDB_VECTORIZER=openai

---

Server Usage

You need a running server to store data. You have two ways to run it.

Option A: The CLI (Local Dev)

The easiest way to start developing locally.

# Starts the API at http://localhost:8000
flowdb start

Option B: Docker (Production)

The robust way to deploy to DigitalOcean, Railway, or AWS.

docker-compose.yml

services:
  flowdb:
    image: python:3.11-slim
    # We use 'sh -c' so we can chain commands with &&
    command: >
      sh -c "pip install flowdb-ai && flowdb start --host 0.0.0.0"
    ports:
      - "8000:8000"
    volumes:
      - ./flow_data:/app/flow_data
    environment:
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - FLOWDB_API_KEY=${FLOWDB_API_KEY}

---

Client SDK Usage

FlowDB comes with a Pythonic Client SDK. It feels like using a local dictionary, but it talks to your high-performance server.

1. Connection

from flowdb import FlowDB
from pydantic import BaseModel

# Connects to localhost:8000 by default
# Reads FLOWDB_API_KEY from env automatically if present
db = FlowDB()

# Or connect to a remote production server
# db = FlowDB(url="http://164.x.x.x:8000", api_key="secret")

2. Define Data Model

FlowDB uses Pydantic to validate your data on read/write.

class Ticket(BaseModel):
    id: str
    title: str
    status: str
    description: str

3. Upsert (Write)

This saves the JSON AND automatically generates a vector embedding for the description and title.

tickets = db.collection("tickets", Ticket)

# Upsert (Insert or Update)
new_ticket = Ticket(
    id="t-100", 
    title="Login Broken", 
    status="open", 
    description="User cannot reset password on mobile."
)
tickets.upsert(new_ticket)

4. Semantic Search (RAG)

Find records by meaning, not just keywords.

# Finds the ticket above because "password reset" is related to "login"
results = tickets.search("Issues with authentication", limit=1)

print(results[0].title) 
# Output: "Login Broken"

5. Management

# Get by ID
ticket = tickets.read("t-100")

# Delete
tickets.delete("t-100")

# List all collections
print(db.list_collections())
# Output: ['tickets', 'users']

---

AI Agent Integration (Claude / MCP)

FlowDB is MCP-Native. This allows Claude Desktop to natively "see", "search", and "edit" your database without any custom glue code.

What this enables: You can ask Claude: "Check the 'tickets' collection for any high-priority bugs regarding login issues, and summarize them for me."

Step 1: Install the Bridge Tool

We use fastmcp to bridge Claude (Stdio) to FlowDB (HTTP).

pip install fastmcp

Step 2: Configure Claude

Edit your config file:

• Mac: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Update it like this:

{
  "preferences": {
    "menuBarEnabled": false,
    "quickEntryShortcut": "off"
  },
  "mcpServers": {
    "flowdb": {
      "command": "/Users/<user>/.pyenv/shims/fastmcp", // path-to-fastmcp
      "args": [
        "run",
        "http://:<API_KEY>@localhost:8000/mcp/sse"
      ]
    }
  }
}

Note on Security: We pass the API Key in the URL format http://:PASSWORD@HOST (Basic Auth style). Replace YOUR_API_KEY with the key from your .env file. If you haven't set a key (Dev Mode), just use http://localhost:8000/mcp/sse.

---

N8n & Automation Integration

FlowDB is perfect for low-code automation because it accepts raw JSON. It acts as the "Long Term Memory" for your workflows.

In N8n:

1. Use the HTTP Request node.
2. Method: POST
3. URL: http://your-server:8000/v1/users/upsert
4. Auth: Header Auth (Authorization: Bearer YOUR_KEY).
5. Body: Pass your raw JSON from Typeform/Gmail directly into the data field.

---

Architecture

• Storage Engine: LMDB (Lightning Memory-Mapped Database). A transactional key-value store that runs at the speed of RAM.
• Vector Engine: USearch. A high-performance HNSW implementation for semantic search.
• API Layer: FastAPI. Handles concurrent reads and serialized writes.
• Protocol: MCP. Native agentic interface.

---

License

Apache 2.0 License. Built for the AI Community.