How fstamatelopoulos/cerefox works
Cerefox is user-owned, persistent knowledge memory shared across AI agents and people. The main workflow is to ingest or curate documents through the CLI, web UI, or MCP; documents are normalized, chunked, embedded, and stored in user-controlled Postgres. Agents and people then retrieve knowledge through hybrid or metadata search and manage projects, versions, and document lifecycle. The graph includes the documented access surfaces and core processing stages; some backend routing and storage details are unsampled, so uncertain implementation-level links are omitted.
Main entry points: mcp-tools/index.ts MCP tools · pipeline.ts Ingest pipeline · App.tsx Web UI · embeddings/index.ts Embeddings
Components 20
Access surfaces
- Web UI
frontend/src/App.tsx - Web API
packages/memory/src/web/server.ts - CLI
packages/memory/src/cli/program.ts - Local MCP
packages/memory/src/server.ts - Remote MCP
supabase/functions/cerefox-mcp/index.ts
Ingestion
- Web ingest
packages/memory/src/web/routes/ingest.ts - Ingest pipeline
packages/memory/src/ingestion/pipeline.ts - File conversion
packages/memory/src/ingestion/file-to-markdown.ts - Chunking
_shared/ingest/chunker.ts - Embeddings
_shared/embeddings/index.ts
Knowledge services
- MCP tools
_shared/mcp-tools/index.ts - Hybrid search
_shared/mcp-tools/search.ts - Metadata search
_shared/mcp-tools/metadata-search.ts - Document tools
_shared/mcp-tools/ingest.ts - Project discovery
_shared/mcp-tools/_projects.ts
Persistence
- Postgres + pgvector
Other components
- People
- AI agents
- OpenAI embeddings
- Local ONNX model
_shared/embeddings/onnx-embedder.ts
Connections 24
- People → Web UI: curates with
README.md - People → CLI: manages via
README.md - AI agents → Local MCP: connects via
README.md - AI agents → Remote MCP: connects via
README.md - AI agents → CLI: reads and writes
README.md - Web UI → Web API: uses
README.md - Local MCP → MCP tools: dispatches
packages/memory/src/server.ts - Remote MCP → MCP tools: dispatches
_shared/mcp-tools/index.ts - Web UI → Web ingest: submits content
README.md - Web ingest → Ingest pipeline: invokes
packages/memory/src/web/routes/ingest.ts - Ingest pipeline → File conversion: converts files
packages/memory/src/ingestion/pipeline.ts - Ingest pipeline → Chunking: chunks content
packages/memory/src/ingestion/pipeline.ts - Ingest pipeline → Embeddings: embeds chunks
packages/memory/src/ingestion/pipeline.ts - Embeddings → OpenAI embeddings: requests vectors
- Embeddings → Local ONNX model: uses optionally
_shared/embeddings/index.ts - MCP tools → Hybrid search: offers search
_shared/mcp-tools/index.ts - MCP tools → Metadata search: offers metadata search
_shared/mcp-tools/index.ts - MCP tools → Document tools: offers ingest
_shared/mcp-tools/index.ts - MCP tools → Project discovery: offers discovery
_shared/mcp-tools/index.ts - Hybrid search → Postgres + pgvector: queries knowledge
README.md - Metadata search → Postgres + pgvector: queries metadata
README.md - Document tools → Postgres + pgvector: writes documents
README.md - Ingest pipeline → Postgres + pgvector: stores chunks
README.md - Project discovery → Postgres + pgvector: discovers projects
README.md