Provides a persistent, shared knowledge layer that allows multiple AI agents to read and write to a unified memory via MCP, CLI, or HTTP.
Also known as fstamatelopoulos/cerefox, @cerefox/memory
- Stars
- 19
- Tools
- —
- Downloads, 30 days
- 3,336
- Latest version
- —
- Last commit
- Nov 14, 2026
- License
- Apache-2.0
What is Cerefox MCP?
Cerefox provides a persistent, shared knowledge layer that allows multiple AI agents to read and write to a unified memory via MCP, CLI, or HTTP.
Summary generated from the project's README
About Cerefox MCP server
Cerefox provides a persistent, shared memory layer designed for AI agents to maintain context across different sessions and tools. It acts as a centralized knowledge base where information written by one agent, such as Claude or Cursor, becomes immediately available to others. This infrastructure prevents context fragmentation by allowing agents to discover project documents and previous decisions through hybrid search, which combines full-text and semantic vector capabilities.
Developers can deploy Cerefox using a local Docker container for private, on-device memory or connect to a remote Supabase instance via Edge Functions. Access is managed through several interfaces including a command-line interface, a web UI for human curation, and the Model Context Protocol. The system supports local MCP via a TypeScript stdio server or remote MCP using a URL and an access token. Users maintain full ownership of their data, choosing between cloud-based embeddings or fully offline local models like nomic-embed-text-v1.5.
What you can do with it
- 1Synchronize knowledge across multiple agentsAn AI agent can write a technical decision that a different agent on another machine can find later.
- 2Maintain context during tool switchingUsers can move between different AI platforms without losing the accumulated knowledge from previous sessions.
- 3Automated project document discoveryAn agent can find relevant project information through search without the user needing to provide explicit instructions.
- 4Perform granular document updatesDevelopers can use specific tools to append or replace sections of a document instead of resending the entire file.
Written from the project's README. Every use case is checked against a quote from it.
How to install Cerefox MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Cerefox MCP in Claude Code
$ claude mcp add cerefox -- npx -y @cerefox/memoryInstall Cerefox MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"cerefox": {
"command": "npx",
"args": [
"-y",
"@cerefox/memory"
]
}
}
}Install Cerefox MCP in VS Code
.vscode/mcp.json
{
"servers": {
"cerefox": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@cerefox/memory"
]
}
}
}Install Cerefox MCP in VS Code CLI
$ code --add-mcp '{"name":"cerefox","type":"stdio","command":"npx","args":["-y","@cerefox/memory"]}'Install Cerefox MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"cerefox": {
"command": "npx",
"args": [
"-y",
"@cerefox/memory"
]
}
}
}Install Cerefox MCP in Codex
$ codex mcp add cerefox -- npx -y @cerefox/memoryInstall Cerefox MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.cerefox] command = "npx" args = ["-y", "@cerefox/memory"]
Install Cerefox MCP in Gemini CLI
$ gemini mcp add -s user cerefox npx -- -y @cerefox/memoryInstall Cerefox MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"cerefox": {
"command": "npx",
"args": [
"-y",
"@cerefox/memory"
]
}
}
}Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablefstamatelopoulos/cerefox is public and reachablegithub.com/fstamatelopoulos/cerefox ↗Pass
- Package names this repository as its source@cerefox/memory names fstamatelopoulos/cerefox as sourcenpmjs.com/package/@cerefox/memory ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for @cerefox/memorynpmjs.com/package/@cerefox/memory/v/1.23.2#provenance ↗Pass
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-12github.com/fstamatelopoulos/cerefox ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from @cerefox/memoryPass
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubCerefox
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: local MCP (Claude Code, Codex, Cursor, Gemini, Claude Desktop); remote MCP via Supabase Edge Functions; cloud Claude over OAuth; ChatGPT via Custom GPT + GPT Actions until OpenAI retires Custom GPTs on December 11, 2026 (see Connecting AI agents)
- Keep it cheap: Supabase free tier + low-cost cloud embeddings; see
docs/guides/operational-cost.md
Example use cases
Cerefox isn't bound to one tool or one workflow — anything that can run a shell command or speak MCP can read and write your memory, pointed at either a shared cloud deployment or a private local one:
See Connecting AI agents for the how-to per client.
Community
Questions, ideas, or want to follow development? Join the Cerefox Discord — setup & usage help for Cerefox and cf², release news, and a place to share what you're building.
Features
| Feature | Details |
|---|---|
| Hybrid search | Combines full-text (BM25) + semantic (vector) search with a configurable alpha weight |
| Metadata-filtered search | JSONB containment filter (@>) on document metadata; server-side, GIN-indexed; composable with project filter and all search modes; available across all access paths (MCP, CLI, web UI, GPT Actions) |
| Metadata search | Standalone metadata-only search (no text query needed); find documents by key-value criteria, project, and date range; optional content inclusion with byte budget; dedicated MCP tool, CLI command, and web UI page |
| Project discovery | cerefox_list_projects MCP tool for agents to discover available projects; all search results include human-readable project_names alongside UUIDs |
| Heading-aware chunking | Greedy section accumulation — H1/H2/H3 sections accumulate until MAX_CHUNK_CHARS; heading breadcrumb preserved per chunk |
| Embeddings | OpenAI text-embedding-3-small (768-dim) via API — or, on Cerefox Local, an optional fully-offline local model (nomic-embed-text-v1.5, in-container ONNX): no API key, text never leaves your machine |
| Remote MCP endpoint | cerefox-mcp Supabase Edge Function — MCP Streamable HTTP; connect Claude Desktop, Claude Code, or Cursor with just a URL and a Cerefox access token (cerefox token generate); no Python install needed |
| Local MCP server | cerefox mcp stdio server (TypeScript, from @cerefox/memory) -- local alternative with zero Edge Function usage, lower latency, and offline support; npm install -g @cerefox/memory. |
| Runs on your network | Cerefox Local on a NAS or home server (tested on a Synology NAS), used from your other machines: web UI, CLI and coding agents, with the API key required on every request. See docs/guides/setup-lan.md |
| Web UI | React + TypeScript SPA (Mantine UI) at /app/; Hono (TypeScript) JSON API backend served by cerefox web; Markdown viewer, search with 4 modes, document editing, project management |
| Markdown-first ingest | .md / .txt / .docx (Markdown is the storage format; .docx is converted via mammoth on ingest, fidelity varies. PDF is not supported — convert upstream) |
| Batch ingest | cerefox document ingest-dir recurses directories |
| Deduplication | SHA-256 content hash; re-ingesting the same file is a no-op |
| Partial document edits | cerefox_insert / cerefox_edit change part of a document without resending it — append, replace a section, delete one, or rename a heading. Anchors are heading paths; an ambiguous anchor is refused with the options rather than guessed. Multiple operations apply atomically. |
| Read one section | cerefox_get_document(section: "## Heading") returns exactly the text a replace_section would overwrite, resolved by the same code as the write — so an edit need not start with a full read. |
| Metadata writes | cerefox_set_document_metadata changes tags without touching content. Merges by default (a null value removes a key), so concurrent agents setting different keys do not clobber each other. No re-chunk, no re-embed, no new version. |
| Agent delete + restore | cerefox_delete_document (soft, requires the caller's read-hash, reason recorded in audit) and cerefox_restore_document (its audited inverse) — v1.7.0. Permanent purge stays web-UI-only with human confirmation. |
| Link integrity | Every write validates [Text](uuid) document links and rejects links to nonexistent ids (mangled-UUID protection — LLMs regenerating text corrupt long random ids at a structural rate); examples escape via code formatting; [[wikilinks]] may dangle; cerefox document dead-links sweeps for legacy dead links. See docs/guides/linking.md — v1.7.x |
| Concurrency-safe updates | Optimistic locking on content updates (v0.11+): writers pass the content_hash they read; a concurrent change fails with a conflict (re-read → merge → retry) instead of silently overwriting another agent's work. Explicit last_write_wins opt-out for file re-sync flows |
| Backup and restore | JSON snapshots, optional git commit |
| Small-to-big retrieval | cerefox_context_expand RPC returns chunk neighbours for richer context |
| Audit log | Immutable, append-only log of all write operations (create, update, delete, restore, status change). Author attribution with author_type ('user' or 'agent'). Browsable via web UI, queryable via MCP tool and Edge Function |
| Review workflow (optional) | Store-level switch review_workflow_enabled (off on a fresh install). On: agent writes land pending_review for a person to approve; filterable on search. Off: no surface shows or enforces a review status (the status is still recorded, so turning it back on shows what was there). Never gates retrieval |
| Version governance | Version archival (protect specific versions from cleanup), configurable retention (cerefox config set version_cleanup_enabled), version diff viewer |
| Lean version storage | Archived chunks keep their content (the safety copy) but carry no embeddings or FTS (v1.8.0) — typically 30–45% of chunk storage reclaimed |
| Usage tracking | Opt-in logging of all operations (reads and writes) across all access paths. Tracks operation type, access path (remote-mcp, local-mcp, edge-function, webapp, cli), requestor identity, query text, and result count. Controlled via cerefox config set usage_tracking_enabled true/false -- no redeploy needed |
| Analytics dashboard | /app/analytics -- 8 interactive charts: calls per day, access path breakdown, top documents, top readers, operations donut, requestor word cloud, requestor→document access patterns (HEB), and requestor→operation patterns (HEB). Date range + project + path filters. CSV export. |
Project status
As of v0.10.0 Cerefox runs two ways: against a hosted Supabase project,
or fully local / self-hosted in a single Docker container (no cloud, no
account). The whole runtime — CLI, MCP server, web UI, ingestion, and
server-side deploy — ships in the
@cerefox/memory npm package
(no repo clone); the local backend bundles that same runtime plus Postgres +
pgvector into one image.
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. Full release history is in
CHANGELOG.md; the roadmap and iteration log live in
docs/plan.md.
Getting Started
Upgrading to v1.0.0? Two changes need action (a rotatable access token replaces the legacy anon JWT for Edge Functions, and a schema redeploy) and Python is fully removed. One guide covers it:
docs/guides/migration-1.0.md.
Cerefox runs two ways — pick your backend. Both expose the same features, web UI, and MCP tools; they differ only in where your data lives and how you install. (Contributors who want to run from source: see Run from source below.)
Option 1 — Cloud (Supabase)
Your data lives in your own Supabase project (free tier is enough). You use
the cerefox command from the @cerefox/memory
npm package. No git clone, no Python, no build.
# 1. Install (one-liner; detects Bun, falls back to npm):
curl -fsSL https://github.com/fstamatelopoulos/cerefox/releases/latest/download/install.sh | sh
# or: npm install -g @cerefox/memory (Node ≥ 24)
# 2. Configure + stand up the server side (against your own Supabase project):
cerefox init # interactive setup: Supabase URL/keys, embedding key
cerefox server deploy # schema + RPCs + all 9 Edge Functions, from the npm bundle
cerefox token generate # mint the Edge Function access token; sets it on Supabase
# and writes CEREFOX_ACCESS_TOKEN to your .env. Needed for
# GPT Actions / remote MCP + a fully-green doctor; the local
# MCP, cloud Claude (OAuth) and CLI/web don't use it.
cerefox doctor # verify everything is wired up
# 3. Wire up your AI agent(s) — run the ones that apply:
cerefox configure-agent --tool claude-code # local MCP (preferred) — also: claude-desktop | cursor | codex | gemini
# Cloud Claude (claude.ai/app): connect over OAuth (setup-supabase Step 7).
# Custom GPT (ChatGPT): paste the token from step 2 into the Action's
# Authentication → API Key (Bearer). See docs/guides/connect-agents.md.
# Works until 2026-12-11, when OpenAI retires Custom GPTs (see below).
# 4. Use it:
cerefox document ingest my-notes.md --title "My notes"
cerefox search "what did I decide about auth?"
cerefox web # web UI → http://localhost:8000/app/
Prerequisites: Node 24+ or Bun 1.0+ · a Supabase account (free tier) · an
embedding API key (OpenAI text-embedding-3-small).
Full walkthrough:
docs/guides/quickstart.md(~15 min). Supabase specifics:docs/guides/setup-supabase.md.
Option 2 — Local / self-hosted (Docker)
Everything runs in one Docker container on your machine — Postgres + pgvector
- the Cerefox server. No Supabase account, no Node/Bun on the host, just
Docker. You get a
cerefox-localcommand (same KB verbs ascerefox).
# 1. Install (one-liner; pulls the all-in-one image, adds a `cerefox-local` command):
curl -fsSL https://github.com/fstamatelopoulos/cerefox/releases/latest/download/install-local.sh | sh
# Fully offline instead? add `-s -- --local-embedder` — embeddings run
# in-container (no OpenAI key; text never leaves your machine).
# 2. Set your OpenAI key (or pick the local embedder) + wire up an AI agent:
cerefox-local init # OpenAI key or [2] Local embedder (re-creates the container)
cerefox-local configure-agent # wire an MCP client (e.g. Claude Code)
# 3. Use it:
cerefox-local document ingest my-notes.md --title "My notes"
cerefox-local search "what did I decide about auth?"
# web UI → http://localhost:8000/app/ (or the port the installer chose — it auto-steps
# to 8010/… if 8000 is busy; `cerefox-local status` shows the URL. Manage: status | upgrade | stop)
Prerequisites: Docker (Docker Desktop or Colima) · an OpenAI API key (embeddings still use the OpenAI API).
Full walkthrough:
docs/guides/setup-local.md. Cloud and local are independent — different installer, different command name — so they never collide if you happen to run both.
On a NAS or home server (your network)
Cerefox Local also runs on an always-on machine on your home or office network,
such as a NAS, a mini PC or a home server. The data stays on that machine, and
your other machines use it over the network: the web UI in a browser, the
cerefox CLI, and coding agents such as Claude Code and Codex. Tested on a
Synology NAS with Container Manager. Already on Supabase? The cerefox-web
image serves the web UI and API from your network while the data stays in
Supabase.
On a network host every request needs the API key, because a container cannot tell your laptop from any other device on the network. Keep the host on your LAN; it is not meant to be reachable from the internet.
Walkthrough:
docs/guides/setup-lan.md, including a step-by-step Synology section. The CLI and coding agents need v1.22.0 or newer on the host.
Run from source (contributors)
Clone the repo and run from source. bun drives everything.
git clone https://github.com/fstamatelopoulos/cerefox.git && cd cerefox
bun install # workspace deps: root + packages/memory + frontend
cp .env.example .env # fill in Supabase URL/keys + embedding key
bun scripts/db_deploy.ts # schema + RPCs (--dry-run to preview · --reset to wipe first)
npx supabase functions deploy # Edge Functions (or just use `cerefox server deploy`)
cd frontend && bun run build && cd .. # build the SPA `cerefox web` serves at /app/
bun test # run the suite (root + packages/memory + _shared)
Full contributor setup, conventions, and the test matrix are in
CONTRIBUTING.md and the contributor section of
docs/guides/quickstart.md.
Python is gone. As of v1.0.0 the entire runtime (CLI, MCP, web, ingestion) is TypeScript in
@cerefox/memory; the Python implementation — including theuv run cerefox mcpfallback — was removed. Only the SQL schema assets undersrc/cerefox/db/remain (they are not Python). Seedocs/guides/upgrading.md.
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, title-boosted)
Search RPCs (MCP tools): cerefox_hybrid_search, cerefox_fts_search,
cerefox_semantic_search, cerefox_search_docs, cerefox_reconstruct_doc,
cerefox_context_expand
Connecting AI agents
The fastest path is cerefox configure-agent --tool <client> — it writes the
right config for Claude Code, Claude Desktop, Cursor, Codex, or Gemini. There
are several ways an agent can reach Cerefox:
1 — Local stdio MCP (recommended for local agents). cerefox mcp runs the
same 15 core tools in-process (plus 4 document-relation tools, hidden until you enable them with cerefox config set relations_enabled true) — lower latency, no per-call Edge Function billing, and
no Edge Function token needed (it reaches Supabase over the Data API with its own
.env credential). configure-agent wires it up, or point your client at
command: "cerefox", args: ["mcp"].
2 — Remote HTTP MCP (advanced/fallback). The cerefox-mcp Edge Function
speaks MCP Streamable HTTP. Just a URL + a Cerefox access token
(cerefox token generate — see
setup-supabase.md). No local install:
claude mcp add --transport http cerefox \
https://<project-ref>.supabase.co/functions/v1/cerefox-mcp \
--header "Authorization: Bearer <cerefox-access-token>"
3 — OpenAI: Codex today, ChatGPT changing. Codex (the CLI, and Codex
threads in the ChatGPT desktop app) works with the local stdio MCP:
cerefox configure-agent --tool codex. ChatGPT chats connect today through a
Custom GPT with GPT Actions pointing at the Edge Functions (requires ChatGPT
Plus): paste the OpenAPI block from
connect-agents.md and set the Action's Bearer
auth to your Cerefox access token. OpenAI retires Custom GPTs on December 11,
2026, and custom actions do not carry over to its replacement (plugins), so
this path stops working then. ChatGPT will need a new connection: an MCP
connector to cerefox-mcp over OAuth, the way cloud Claude connects below. That
is being validated in
#326
(research and plan).
4 — Shell CLI. Local coding agents with a Bash tool (Claude Code, Codex,
opencode, …) can read and write Cerefox by running the installed cerefox
command directly — no MCP config at all. Point the agent at
AGENT_GUIDE.md and let it use cerefox search /
cerefox document ingest.
5 — Cloud & mobile Claude (optional). claude.ai web and the Claude mobile
app connect to cerefox-mcp over OAuth — memory in your browser and on your
phone, with full hybrid search. It's an opt-in extra: it needs a one-time
Supabase OAuth setup plus a hosted consent page (the repo ships a one-command
Cloudflare Worker for that, free). Nothing else
above requires it. See
setup-supabase.md → Step 7.
Full setup for every client — plus a manual per-client config appendix for when
configure-agent can't reach a tool — is in
docs/guides/connect-agents.md.
Cerefox MCP questions
How do I add Cerefox MCP to Claude Code?
Run claude mcp add cerefox -- npx -y @cerefox/memory in your terminal. Add --scope user to make it available in every project.
How do I add Cerefox MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
Can I run Cerefox locally?
Yes, you can run it fully local or self-hosted in a single Docker container using Postgres and pgvector.
Does Cerefox support hybrid search?
Yes, it combines full-text (BM25) and semantic (vector) search with a configurable alpha weight.
How do AI agents access the memory?
Agents can access memory through local MCP, remote MCP via Supabase Edge Functions, CLI, or HTTP/REST.