@cerefox/memory

User-owned shared memory for AI agents. The local TypeScript runtime for Cerefox — a persistent, curated knowledge layer that multiple AI tools can read and write.

Cerefox is BYO-storage. This package is the client — the CLI + local MCP server + local web UI. The knowledge base itself lives in your own Supabase project (Postgres + pgvector; free tier works). Installing this npm package does not give you a working KB on its own; you also need a Supabase project + an embedding API key, and a one-time server-side deploy (cerefox server deploy — no repo clone needed). See "Before you install" below.

Why cloud-backed? Cerefox is designed as a cloud-backed memory layer so the same knowledge is reachable from every agent you run — Claude Code on your laptop, Cursor on a second machine, ChatGPT on the web, a script in CI. Postgres + pgvector deliver hybrid (semantic + full-text) search across that shared memory; Supabase provides the always-on endpoint that makes "same memory, any device, any agent" work. You own the data and the endpoint; this package bundles everything you run locally — CLI, MCP server, web UI, and the in-process ingestion + retrieval pipeline — that talks to it.

This package contains a single binary, cerefox:

| Subcommand | What it does | |---|---| | cerefox <command> | CLI — search, ingest, list, version-history, audit-log, lifecycle (init, doctor, configure-agent, self-update). Callable from any directory. | | cerefox mcp | Local stdio MCP server. Drop-in for Claude Code, Cursor, Claude Desktop, Codex CLI, Gemini CLI. Exposes the same 10 MCP tools as the remote cerefox-mcp Edge Function. | | cerefox web | Local web app at http://localhost:8000 — React UI for browsing, searching, editing, and ingesting documents. Backed by an in-process Hono server that exposes the same /api/v1/* REST surface as the bundled Edge Functions. |

What this package isn't: the source of truth for Cerefox's architecture or docs. Those live in the GitHub repo. This README is the npm landing card.

Before you install

Cerefox is a self-hosted memory layer with two halves you set up independently:

Server side (lives in your Supabase project, runs ~24/7):

• Postgres schema + RPCs (search, ingest, audit log, version history)
• Edge Functions (server-side embedding, remote cerefox-mcp MCP server, Custom-GPT actions)

Client side (this npm package, runs on your machine):

• cerefox CLI + cerefox mcp (local stdio MCP) + cerefox web (local UI at http://localhost:8000)

You deploy the server side with this package's CLI — cerefox server deploy stands up the schema, RPCs, and all 9 Edge Functions from bundled assets (no repo clone). Both halves are required for a working install.

What you need

| Prerequisite | Why | How | |---|---|---| | A Supabase project | Hosts Postgres + pgvector + Edge Functions. Free tier is enough for most personal use. | supabase.com → New project | | An embedding API key | OpenAI text-embedding-3-small (default) or Fireworks AI. Pennies/month for typical personal use (see operational-cost.md). | Get an OpenAI API key. | | Node ≥ 20 or Bun ≥ 1.0 | Runtime for the cerefox bin (and the bundled cerefox mcp server). | nodejs.org · bun.sh. The one-line installer below bootstraps Bun if neither is present. |

One-time server-side setup (~10 min — no clone needed)

The CLI stands up the whole server side — schema, RPCs, and all 9 Edge Functions — from bundled assets:

cerefox init             # enter your Supabase URL/keys + embedding key
cerefox server deploy    # schema + RPCs + Edge Functions

Details (Supabase login/linking, connection-pooling quirks, API-key flavors, troubleshooting, and the contributor clone-and-deploy path) live in the quickstart and setup-supabase.md.

If you don't yet have Supabase + an OpenAI key, the Cerefox quickstart walks through the whole setup in one place.

Install

Once you have the prerequisites above in hand:

# One-line install (recommended on a fresh machine; bootstraps Bun if needed):
curl -fsSL https://github.com/fstamatelopoulos/cerefox/releases/latest/download/install.sh | sh

# Or direct (any of these):
bun install -g @cerefox/memory
npm install -g @cerefox/memory
pnpm add -g @cerefox/memory
yarn global add @cerefox/memory

First-run setup

cerefox init        # 5-step interactive bootstrap (asks for Supabase URL,
                    # Supabase key, OpenAI key, optional Postgres URL, identity)
cerefox doctor      # end-to-end health check against the live services

cerefox init prompts for the credentials you collected above, validates them against the live services, writes ~/.cerefox/.env (chmod 0600), and optionally wires up an MCP client. It does not create the Supabase project for you — you'll be asked for the URL + key, so make sure those are already provisioned (see "Before you install").

Already ran the server-side setup above? Then your schema is in place and cerefox init only needs the URL + keys. If you skipped that step, cerefox doctor will flag it and point you back to cerefox server deploy.

Upgrading from the Python cerefox CLI? If you have a working .env in your repo clone, init detects it and offers to copy it to ~/.cerefox/.env so the TS CLI uses the new home while Python keeps reading the repo file unchanged (cerefox init walks you through the choice). Existing users with no ~/.cerefox/.env see zero behavior change until they opt in.

Connect an AI agent

# Run the configure-agent commands that apply to your setup:
cerefox configure-agent --tool claude-code          # ~/.claude.json via `claude mcp add`
cerefox configure-agent --tool claude-desktop       # Claude Desktop config
cerefox configure-agent --tool cursor               # ~/.cursor/mcp.json
cerefox configure-agent --tool codex                # ~/.codex/config.toml
cerefox configure-agent --tool gemini               # ~/.gemini/settings.json

All five writers landed in v0.6. For manual configuration, the canonical MCP entry is:

{
  "mcpServers": {
    "cerefox": {
      "command": "npx",
      "args": ["-y", "--package=@cerefox/memory", "cerefox", "mcp"]
    }
  }
}

Once configured, any of these clients can search + write your Cerefox KB via the 10 MCP tools (cerefox_search, cerefox_ingest, cerefox_get_document, cerefox_list_versions, cerefox_list_projects, cerefox_list_metadata_keys, cerefox_metadata_search, cerefox_set_document_projects, cerefox_get_audit_log, cerefox_get_help).

Common commands

cerefox search "second brain"                          # hybrid (FTS + semantic)
cerefox document ingest notes.md --project "Personal"  # add a doc
cerefox project list                                   # discover projects
cerefox metadata search --metadata-filter '{"type":"decision-log"}'
cerefox audit list --since 2026-05-01                  # immutable history
cerefox doctor                                         # diagnose your install
cerefox upgrade                                        # alias for self-update

Run cerefox --help for the full command surface — a resource-verb shape (document …, project …, metadata …, server …) plus flat commands like search and the lifecycle verbs.

Why install the CLI when I already have MCP wired up?

You don't have to. cerefox mcp (started as a stdio subprocess by any MCP client) gives your AI agent full access to the knowledge base on its own. The rest of the cerefox CLI is useful for:

• One-off shell operations: search, ingest, list, audit-log.
• Power-user workflows: cerefox document ingest-dir ./meeting-notes, cerefox metadata search --metadata-filter …, cerefox backup create.
• Setup + diagnostics: cerefox init, cerefox doctor, cerefox configure-agent, cerefox self-update.
• Agents via local Bash tool: some coding agents prefer running cerefox <subcommand> from a shell rather than configuring MCP.

Architecture, design, docs

• Project README + roadmap: https://github.com/fstamatelopoulos/cerefox
• Architecture overview: CLAUDE.md
• Setup guides: docs/guides/
• Upgrading: docs/guides/upgrading.md
• For AI agents using Cerefox: AGENT_GUIDE.md, AGENT_QUICK_REFERENCE.md, or run cerefox guides list.
• Changelog: CHANGELOG.md

License

Apache-2.0 — see LICENSE in the repo.

Cerefox is a single-maintainer open-source project. Bug reports and PRs welcome at github.com/fstamatelopoulos/cerefox/issues.