Cerefox

User-owned shared memory for AI agents. A persistent, curated knowledge layer that multiple AI tools can read and write, backed by Postgres + pgvector.

What is Cerefox?

Cerefox is a user-owned knowledge memory layer: a persistent, curated knowledge base that sits between you and the AI tools you use.

The primary use case is shared memory across AI agents: knowledge written by one tool (Claude, ChatGPT, Cursor, or a custom agent) becomes immediately available to all others. This prevents context fragmentation, so the same information doesn't have to be re-explained in every session.

Cerefox is asynchronous shared memory, not a message bus. It solves the persistent context problem: knowledge written in one context is findable in any other. A user curates project documents and an AI agent discovers them through search without being told they exist. An agent writes a decision during a coding session and a different agent, on a different machine, running a different model, finds it days later. A user switches from one AI tool to another and the accumulated knowledge carries over without manual transfer. The boundaries that Cerefox dissolves are between agents, between sessions, between human and machine, and across time.

For the full project vision, principles, and roadmap direction, see docs/research/vision.md.

• Agent-first, not human-first: AI agents are first-class citizens on both sides: they read and write; humans curate and validate

• Own your data: everything lives in a Postgres database you control (Supabase free tier or self-hosted)

• Cross-agent coordination: agents on separate machines and runtimes coordinate through persistent shared context (see docs/guides/agent-coordination.md)

• Not a note-taking app: Cerefox is knowledge infrastructure, not a replacement for Obsidian, Notion, or Bear; those tools handle authoring, Cerefox handles indexing and agent access

• Hybrid search: full-text + semantic search finds relevant knowledge even with fuzzy or conceptual queries

• Any agent, anywhere: remote MCP via Supabase Edge Functions; ChatGPT via Custom GPT + GPT Actions

• Keep it cheap: Supabase free tier + low-cost cloud embeddings; see docs/guides/operational-cost.md

Features

Project status

Cerefox is a single-maintainer open-source project, currently at v0.7.0 and in its "Polish & Distribution" arc — the work that takes it from "runnable from a git clone" to "installable like any other modern CLI". Highlights of what's already shipped (full history in CHANGELOG.md):

• A complete Cerefox feature surface: hybrid search, metadata-filtered search, small-to-big retrieval, implicit versioning with a per-document audit log, soft-delete with a trash bin, multi-project membership.

• Three integration paths for AI agents: local stdio MCP, remote MCP via Supabase Edge Functions, and a Custom GPT via GPT Actions. Plus a CLI fallback for local coding agents.

• A React + Mantine web UI at /app/ with full read/write coverage of the knowledge base.

Where the project is headed is captured in docs/specs/polish-and-distribution-design.md (also tracked iteration-by-iteration in docs/plan.md):

Until v1.0.0 the SemVer policy in CONTRIBUTING.md is aspirational — breaking changes can land in minor versions when there's a good reason. After v1.0.0 it's binding.

The npm install path is now complete as of v0.7.0: the entire runtime surface (CLI, MCP, web server, ingestion pipeline) ships in @cerefox/memory with no Python required. End users install via the one-liner below or npm install -g @cerefox/memory. Schema deploy / migrations / backup restore still use the Bun-run scripts/*.ts from a repo clone — those are ops scripts, not part of the runtime. (v0.4–v0.5.0 also shipped a dedicated cerefox-mcp bin; dropped in v0.5.1 as redundant with cerefox mcp.)

Getting Started

Full walkthrough: docs/guides/quickstart.md -- zero to first ingested document and connected agent in 15 minutes.

Upgrading from v0.4.x? See docs/guides/migration-v0.5.md — it now covers v0.5 → v0.7. Your existing MCP configs keep working; the npm-installed cerefox CLI is opt-in.

Quickstart (npm path — recommended)

# One-line install (detects Bun or installs it, falls back to npm):
curl -fsSL https://github.com/fstamatelopoulos/cerefox/releases/latest/download/install.sh | sh

# Or direct:
npm install -g @cerefox/memory      # Node ≥ 20
# bun install -g @cerefox/memory    # alternative — faster

cerefox init                         # interactive 5-step setup
cerefox doctor                       # verify the install

# Wire up your MCP client(s) — run the ones that apply to your setup:
cerefox configure-agent --tool claude-code      # Claude Code (~/.claude.json via `claude mcp add`)
cerefox configure-agent --tool claude-desktop   # Claude Desktop config
cerefox configure-agent --tool cursor           # Cursor (~/.cursor/mcp.json)
cerefox configure-agent --tool codex            # OpenAI Codex CLI (~/.codex/config.toml)
cerefox configure-agent --tool gemini           # Gemini CLI (~/.gemini/settings.json)

That's the path for end users who don't need to hack on Cerefox itself. The entire runtime surface (CLI, MCP, web server, ingestion pipeline) is in this single npm package as of v0.7.0. The schema deploy and migration scripts under scripts/ still need a repo clone — see "Building from source" below.

Prerequisites for the npm install path

Building from source / Contributors

For schema deploy + migrations, or contributing to Cerefox itself:

Full contributor setup in CONTRIBUTING.md.

1. Clone and install

git clone https://github.com/fstamatelopoulos/cerefox.git
cd cerefox
bun install              # workspace deps (root + packages/memory + frontend)
uv sync                  # only if you need the Python MCP server / pytest

2. Set up Supabase (free)

1. Sign up at supabase.com — a GitHub login works fine.

2. Create a new project. Give it a name (e.g. cerefox) and set a database password (store it somewhere safe — you'll need it once).

3. On the project creation screen leave the defaults:

   • Enable Data API ✅ — required (the Python client uses this)

   • Enable automatic RLS — leave unchecked (single-user app, not needed)

3. Configure .env

cp .env.example .env

Open .env and fill in these values:

CEREFOX_DATABASE_URL notes:

• Use the Session Pooler (port 5432), not the Transaction Pooler (6543, no DDL) or the Direct Connection (IPv6-only on free tier).

• The Session Pooler may not be a first-class option in the new "Connect" dialog; either find it under Connection pooling, or take the Transaction Pooler URI and change :6543 → :5432.

• The username must include your project ref: postgres.your-project-ref — not just postgres. Without the suffix Supabase returns "Tenant or user not found".

• Append ?sslmode=require to enforce TLS.

• Full reference: docs/guides/setup-supabase.md → Connection pooling (2026).

4. Deploy the schema

bun scripts/db_deploy.ts            # full schema + RPCs (`--dry-run` to preview, `--reset` to drop first)
# bun scripts/db_migrate.ts         # apply incremental migrations on an already-deployed instance

5. Deploy the Edge Functions

Edge Functions handle server-side embedding so AI agents never need a local model. Requires the Supabase CLI.

npx supabase functions deploy cerefox-search
npx supabase functions deploy cerefox-ingest
npx supabase functions deploy cerefox-mcp

Set your OpenAI key as a Supabase secret (used by the functions at runtime):

npx supabase secrets set OPENAI_API_KEY=sk-...your-key...

6. Build the web UI (only when working from a repo clone)

The web UI is a React + Vite SPA. The bundled @cerefox/memory npm package already includes the built SPA — you only need to build it yourself if you cloned the repo and are running cerefox web from source or have edited frontend/ files:

cd frontend
bun install
bun run build
cd ..

This produces frontend/dist/, which cerefox web serves at /app/.

7. Ingest a document and open the web UI

cerefox ingest my-notes.md --title "My notes"
cerefox web                       # → http://localhost:8000

Optional: ingest the Cerefox docs themselves so AI agents can look up project details:

# Create a "cerefox" project first, then sync README + all docs/ into it.
cerefox create-project cerefox
bun scripts/sync_docs.ts

Re-run sync_docs.ts any time after updating documentation to keep the knowledge base current.

Try with sample data: the test-data/ directory contains six diverse markdown documents you can ingest to experiment with search before adding your own content:

cerefox ingest-dir test-data/ --recursive

Architecture

cerefox_documents     cerefox_chunks
─────────────────     ───────────────────────────────
id, title, source     id, document_id, chunk_index
content_hash          heading_path, heading_level
project_id            content, char_count
metadata (JSONB)      embedding_primary (VECTOR 768)
chunk_count           fts (TSVECTOR, generated)

Search RPCs (MCP tools): cerefox_hybrid_search, cerefox_fts_search, cerefox_semantic_search, cerefox_search_docs, cerefox_reconstruct_doc, cerefox_context_expand, cerefox_save_note

Connecting AI agents

Option 1 — Remote MCP (recommended) — just a URL, a legacy anon JWT (Supabase → Project Settings → API Keys → Legacy → anon, not the new sb_publishable_… key — see setup-supabase.md), and npx:

The cerefox-mcp Supabase Edge Function speaks MCP Streamable HTTP. No Python, no local repo clone — works from any machine with Node.js installed.

# Claude Code (native HTTP transport)
claude mcp add --transport http cerefox \
  https://<project-ref>.supabase.co/functions/v1/cerefox-mcp \
  --header "Authorization: Bearer <anon-key>"

For Claude Desktop, use supergateway as a stdio-to-HTTP bridge in claude_desktop_config.json:

{
  "mcpServers": {
    "cerefox": {
      "command": "npx",
      "args": [
        "-y", "supergateway",
        "--streamableHttp", "https://<project-ref>.supabase.co/functions/v1/cerefox-mcp",
        "--header", "Authorization: Bearer <anon-key>"
      ]
    }
  }
}

For Cursor, use url + headers.Authorization in mcp.json.

Option 2 — ChatGPT (web + desktop) via Custom GPT + GPT Actions (requires ChatGPT Plus):

Create a Custom GPT and add an Action pointing at the Supabase Edge Functions — no local install, no MCP config, works from both ChatGPT web and desktop. Uses the Supabase anon key as Bearer auth.

Option 3 — Local stdio MCP — runs the same 10 tools in-process; no Edge Function billing per call. Install once with npm install -g @cerefox/memory, then either run cerefox configure-agent --tool <client> (see Option 1's command list) or hand-write the config:

{
  "mcpServers": {
    "cerefox": {
      "command": "cerefox",
      "args": ["mcp"]
    }
  }
}

If you'd rather not install globally, npx --package=@cerefox/memory cerefox mcp works as a one-off. A clone-and-uv run cerefox mcp Python fallback also still works for repo contributors through v0.9.

Option 4 — Shell CLI for local coding agents — no MCP setup at all:

Modern local coding agents (Claude Code, OpenAI Codex CLI, opencode, OpenClaw, Hermes, …) have a Bash tool. If you've already got Cerefox checked out and your .env configured for the CLI, you can simply point the agent at the repo path in its system prompt / project memory, and tell it to read AGENT_GUIDE.md. The agent reads and writes Cerefox by running uv run cerefox …. No .mcp.json, no claude mcp add, no Claude Desktop edit. Useful when you want one Cerefox checkout to serve any number of local agents in the same project with zero per-agent configuration.

Full setup for all options: docs/guides/connect-agents.md

Documentation

License

Apache 2.0 — see LICENSE.