Your knowledge, in your own store,for every AI agent you use.
Cerefox is user-owned shared memory for AI agents: a persistent, curated knowledge base that Claude, ChatGPT, Cursor, Codex and your own agents can all read and write. It lives in a Postgres database you control.
curl -fsSL https://github.com/fstamatelopoulos/cerefox/releases/latest/download/install.sh | sh
Or run everything locally in one Docker container. Both options
The problem
Your agents keep forgetting, and none of them share.
Context is fragmented across AI tools. Cerefox is asynchronous shared memory, not a message bus: knowledge written in one context is findable in any other, across agents, sessions, machines and time.
01
Every session starts from zero
Knowledge from a coding session is invisible to your research chat. Preferences told to one assistant have to be explained again to the next.
02
Memory is locked to one vendor
Most agent memory lives inside one product or one runtime. Switch tools, models or machines and the context stays behind.
03
Agent writes are hard to trust
When several agents write to the same store, you need to see who wrote what, recover from mistakes and stop one writer silently overwriting another.
What Cerefox is
One memory layer, two ways to use it.
An owned knowledge base for your AI agents
Write something once, in any agent or by hand, and recall it from every other. Your knowledge lives in your own store, searchable by meaning and by keyword.
Your data, in your own Supabase project (free tier is enough) or one local Docker container
Markdown documents are the source of truth; embeddings and indexes are derived
Hybrid search with read and write access over MCP, CLI, web UI and GPT Actions
Not a note-taking app: keep authoring in your editor, Cerefox handles indexing and agent access
The memory layer under your agent harness
Building an agent system? Use Cerefox as its persistent memory and knowledge backend, instead of writing your own storage, search and governance.
Protocol-native: MCP (stdio or Streamable HTTP), REST Edge Functions, the /api/v1 HTTP API, Postgres RPCs
Callers identify themselves, so the audit trail says which harness wrote what
Conflict-guarded updates, soft delete with audited restore, version history
Vendor-neutral: agents on different machines, models and runtimes share one store
Capabilities
Built for agents that write, and humans who curate.
Hybrid search
Full-text (BM25) and semantic vector search in one query, with a configurable weight. Finds the right note from fuzzy or conceptual questions.
Agents read and write
15 core MCP tools: search, ingest, partial edits, metadata, projects, versions and the audit log. Agents are first-class on both sides.
Partial edits
Append, replace, delete or rename a section by its heading path without resending the document. Several operations apply atomically.
Safe concurrent writers
Optimistic locking on content: a writer passes the hash it read, and a concurrent change fails with a conflict instead of overwriting.
Versions and audit log
Immutable, append-only log of every write, attributed to a user or an agent. Version history, diffs and archived versions.
Optional review workflow
Switch it on and agent writes land as pending review for a person to approve. It never gates retrieval.
Metadata and projects
Filter any search by JSONB metadata and project, or search by metadata and date alone. Agents can discover projects and keys.
Markdown is the source of truth
Ingest .md, .txt and .docx. Heading-aware chunking, SHA-256 deduplication, and small-to-big retrieval for richer context.
Offline embeddings, if you want
OpenAI text-embedding-3-small by default. On Cerefox Local, an optional in-container model: no API key, text never leaves your machine.
Use cases
Anything that speaks MCP or runs a shell command.
Cerefox is not bound to one tool or one workflow. Point any client at a shared cloud deployment or a private local one.
Interactive coding
Your coding agent searches for past decisions before it starts, and records new ones when it is done.
Who
Claude Code, Cursor, Codex, opencode
Via
local or remote MCP, or the shell CLI
Across agents and machines
An agent writes a decision during a coding session. A different agent, on a different machine, running a different model, finds it days later.
Who
any mix of vendors and models
Via
a shared cloud deployment
Harnesses, agents and scripts
Give an autonomous harness persistent memory: shared across all your agentic systems in the cloud, or private on-device memory with Cerefox Local.
Who
unattended harnesses, your code, cron, curl
Via
MCP, HTTP API, REST Edge Functions, CLI
Chat and research
Research findings land in the knowledge base, ready for the coding agent that needs them next week.
Who
ChatGPT, Claude Desktop, claude.ai
Via
GPT Actions, remote MCP, optional OAuth
Decision logs
Agents record decisions, experiment outcomes and lessons learned. Future sessions load the log instead of re-deriving the rationale.
Who
any agent, any session
Via
a living document
Curate and review by hand
Ingest a folder of notes, browse and edit documents, and scan what agents wrote through the audit log and version history.
Who
you
Via
web UI and the cerefox CLI
How it works
Many clients. Several doors. One store you own.
Both backends run the same codebase and expose the same features, web UI and MCP tools. They differ only in where your data lives.
Chat assistantsChatGPT · Claude Desktop · claude.ai
Harnesses & scriptscustom agents · cron · curl
Access paths
Local MCPcerefox mcp (stdio)
Remote MCPStreamable HTTP
RESTEdge Functions · GPT Actions
HTTP API/api/v1, attributed callers
Shell CLIcerefox · cerefox-local
Cerefox
Heading-aware chunking
Embeddings
Hybrid search
Versions + audit log
Review workflow
Your store
Postgres + pgvector
Cloudyour own Supabase project
Localone Docker container
Embeddings: OpenAI text-embedding-3-small, or an optional fully offline model on Cerefox Local. Details: access paths.
Get started
Pick your backend. Be running in minutes.
The whole runtime (CLI, MCP server, web UI, ingestion, server-side deploy) ships in the@cerefox/memory npm package. No repository clone, no build.
Cloud (Supabase)
Your data lives in your own Supabase project. Needs Node 24+ or Bun 1.0+, a Supabase account (free tier) and an OpenAI API key for embeddings.
cerefox
# 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
cerefox doctor # verify everything is wired up# 3. Wire up your AI agent(s):
cerefox configure-agent --tool claude-code # also: claude-desktop | cursor | codex | gemini# 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/
Postgres, pgvector and the Cerefox server in one container. No Supabase account, no Node or Bun on the host. Needs Docker and an OpenAI key, unless you choose the local embedder.
cerefox-local
# 1. Install (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
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/ (`cerefox-local status` shows the URL)
Just a URL and a Cerefox access token from cerefox token generate. ChatGPT connects through a Custom GPT with GPT Actions; claude.ai and the Claude mobile app through optional OAuth. See connect agents.
A comparison with other agentic knowledge-base and memory systems is being written. Until then, the vision document explains the principles behind Cerefox.
