AI Search Engine Open Source: Deploy MemFree (Self-Host Guide)

The #1 mistake people make deploying an AI search engine open source stack like MemFree: they clone the repo, run bun i in the project root, point Vercel at it, and wonder why uploaded PDFs return nothing. The reason is structural – MemFree isn’t one app. It’s two. Miss the second one and your knowledge base is dead weight.

This guide walks through deploying MemFree the way the repo actually expects, with the real env keys, the real failure modes, and a workaround for the Bun version trap that’s burned several first-time installers in 2025.

What MemFree actually is (and what “open source” buys you)

MemFree is a hybrid AI search engine – it pulls answers from your personal knowledge base and the public internet in a single query, MIT-licensed. The codebase is TypeScript and as of mid-2025 sits at 1,487 stars across the main repo with active commits.

Early on: “open source” here means the source code is open. Not that self-hosting is free. The README (via the official install section at github.com/memfreeme/memfree) requires an OpenAI API key, an Upstash Redis URL, and a Serper API key before anything works. Three paid or quota-capped external services. Plan for that before you start.

Why two services – and why that matters more than the features list

The repo splits into a frontend directory and a vector directory. The frontend is the chat UI and search orchestrator. The vector service is what actually indexes your local documents and handles retrieval. They run as separate processes with separate .env files, as the official README spells out explicitly with two separate cd-and-install blocks.

Think of it like a library with two staff: one at the front desk answering questions from the public catalog, one in the back room managing your private collection. The desk worker can function without the back-room one – but ask about anything from your private shelves and you’ll just get silence. That’s exactly the failure mode most misconfigured installs hit.

System requirements

No formal hardware spec exists in the repo, so this is the realistic baseline based on what the stack pulls in:

Windows users: native Bun on Win32 isn’t supported. WSL2 works fine – run the entire setup inside a WSL2 Ubuntu instance and you won’t hit platform issues.

Get the source

Skip the zip download. Clone it so upgrades are one git pull away.

git clone https://github.com/memfreeme/memfree.git
cd memfree
ls
# You should see two directories that matter: frontend/ and vector/

Those two directories are the entire reason this tutorial exists. They’re independent services. The frontend is the chat UI and search orchestrator. The vector service is what actually indexes and retrieves your local documents. The README shows them as separate setup steps, each with its own env file and start command – not a single root install.

Install MemFree (both services)

Install Bun first if you don’t have it:

curl -fsSL https://bun.sh/install | bash
# Reload your shell, then verify
bun --version # should print 1.3.0 or newer

Now the two-service install. Run these in separate terminals – they need to stay alive together:

# Terminal 1 - frontend
cd frontend
bun i
cp env-example .env
# Edit .env: add OPENAI_API_KEY, UPSTASH_REDIS_REST_URL, SERPER_API_KEY
bun run dev

# Terminal 2 - vector service
cd vector
bun i
cp env-example .env
# Edit .env: same OpenAI key, same Upstash URL
bun run index.ts

Straight from the official README – two separate cd-and-install blocks, not a single root install. The Upstash URL must be identical across both: the frontend writes session state there, the vector service reads it.

One rate-limit trap to avoid: Don’t share the OpenAI key you use here with other dev projects. During document indexing, the vector service hammers the embeddings endpoint – and that quota hit lands on whatever else is sharing that key. Dedicated key, hard monthly cap in the OpenAI dashboard.

First-run config: the minimum to get a real answer back

Both services running? Open http://localhost:3000. Three things to configure before you run a real query:

Pick a default model. As of mid-2025, MemFree ships with GPT-4o-mini, Claude 3.5 Sonnet, and Gemini 1.5 Pro as defaults, plus O1 and O3-mini per the product page – check the repo for current options, since model support updates without fanfare. Then pick a search provider: Google, Exa, and Vector are the listed options; the open-source path defaults to Serper (a Google SERP API wrapper). Optionally, point the frontend at a self-hosted SearXNG instance using the MemFree org’s searxng fork – useful if you’d rather not pay per Serper query.

Verify it works

Two checks. The first is obvious – run a web search query like “latest Bun release notes.” Streamed answer with citations? The frontend + Serper pipeline is alive.

The second check is the real one. Upload a PDF, then ask something whose answer only exists inside that file. “I don’t have information about that” means the vector service isn’t reachable from the frontend – it’s running in your terminal but the two services aren’t talking. Same Upstash URL in both .env files? Vector terminal still alive? If yes to both, restart in order: vector first, frontend second.

Common errors and the fixes that actually work

Error: bun: command not found – Almost never a failed download. Bun’s installation docs call out that ~/.bun/bin may not get patched into your shell profile automatically. Fix:

echo 'export PATH="$HOME/.bun/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Error: git clone failed during bun i – Bun 1.2.10 specifically had a regression where git-based dependencies triggered this. Upgrade and retry: bun upgrade. Bun 1.3.0 fixed it (tracked in community issue reports from early 2025).

Error: web search works but PDF uploads return nothing – Vector service down, or the Upstash URLs don’t match. Restart vector first, then frontend.

Error: 401 from OpenAI mid-query – The vector.env has a stale or different key. Both services call OpenAI independently. Sync them.

Should you self-host this at all?

Honest question, worth sitting with. The hosted version at memfree.me is real – as of mid-2025, the free tier caps you at 5 basic AI searches per day, 1,024 output tokens per answer, and 4 MB per uploaded file. Those limits are tight for anything beyond light personal use. Self-hosting removes them but shifts the bill to OpenAI plus Serper plus Upstash. A hobby instance answering ~50 queries a day runs a few dollars a month. A team using it as a daily research tool – that math gets murkier fast, and at some point the hosted Pro tier might just be cheaper than the ops overhead.

Upgrade and uninstall

To upgrade:

cd memfree
git pull
cd frontend && bun i && cd ..
cd vector && bun i && cd ..

After pulling, check the env-example files in each directory. New required keys appear there before they appear in any release note.

To uninstall: kill both bun processes, delete the cloned directory, rotate the OpenAI and Serper keys (they’ve been sitting in plaintext .env files). The Upstash database won’t delete itself – do it manually from the Upstash console, or it’ll keep charging for storage even with zero traffic.

FAQ

Is MemFree really an open source AI search engine, or is the good stuff paywalled?

Full source, MIT-licensed, on GitHub. No enterprise edition hiding features. What costs money is the hosted convenience tier and the third-party APIs (OpenAI, Serper) that MemFree calls regardless of where you run it.

Can I run MemFree fully offline with a local LLM like Ollama?

Not out of the box – and this is where people get tripped up. The default config wires to OpenAI for both chat completions and embeddings. The vector service in particular calls OpenAI’s embeddings endpoint directly during document indexing; swap that out and you also need to swap the retrieval logic. Community PRs have explored local embedding models, but as of mid-2025 there’s no first-class Ollama path in the official repo. Expect a fork, not a config change.

Why two services instead of one?

Indexing is brutal on resources – lots of embedding API calls, chunking logic, and writes to the vector store – while the frontend mostly orchestrates and streams. Splitting them means you can run the vector service once to index a batch of documents, then kill it. The frontend keeps serving queries off the already-indexed data in Upstash. You’re not paying embedding costs on every search, only on ingestion.

Clone the repo, get Terminal 2 running. That’s the difference between a demo and a tool you’ll actually use.