# fstamatelopoulos/cerefox architecture

> Architecture diagram of the GitHub repository fstamatelopoulos/cerefox, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/fstamatelopoulos/cerefox
- Repository: https://github.com/fstamatelopoulos/cerefox

## Overview

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: [`_shared/mcp-tools/index.ts`](https://github.com/fstamatelopoulos/cerefox/blob/main/_shared/mcp-tools/index.ts) (MCP tools), [`packages/memory/src/ingestion/pipeline.ts`](https://github.com/fstamatelopoulos/cerefox/blob/main/packages/memory/src/ingestion/pipeline.ts) (Ingest pipeline), [`frontend/src/App.tsx`](https://github.com/fstamatelopoulos/cerefox/blob/main/frontend/src/App.tsx) (Web UI), [`_shared/embeddings/index.ts`](https://github.com/fstamatelopoulos/cerefox/blob/main/_shared/embeddings/index.ts) (Embeddings)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Access surfaces"]
  node_web["Web UI<br/>[App.tsx]"]
  node_webapi["Web API<br/>[server.ts]"]
  node_cli["CLI<br/>[program.ts]"]
  node_localmcp["Local MCP<br/>[server.ts]"]
  node_remotemcp["Remote MCP<br/>[index.ts]"]
end

subgraph group_ingestion["Ingestion"]
  node_webingest["Web ingest<br/>[ingest.ts]"]
  node_pipeline["Ingest pipeline<br/>[pipeline.ts]"]
  node_format["File conversion"]
  node_chunking["Chunking<br/>[chunker.ts]"]
  node_embeddings["Embeddings<br/>[index.ts]"]
end

subgraph group_memory["Knowledge services"]
  node_tools["MCP tools<br/>[index.ts]"]
  node_search["Hybrid search<br/>[search.ts]"]
  node_metadata["Metadata search<br/>[metadata-search.ts]"]
  node_document["Document tools<br/>[ingest.ts]"]
  node_projects["Project discovery<br/>[_projects.ts]"]
end

subgraph group_storage["Persistence"]
  node_db[("Postgres + pgvector")]
end

node_human(("People"))
node_agent(("AI agents"))
node_openai["OpenAI embeddings"]
node_localmodel["Local ONNX model<br/>[onnx-embedder.ts]"]

node_human -->|"curates with"| node_web
node_human -->|"manages via"| node_cli
node_agent -->|"connects via"| node_localmcp
node_agent -->|"connects via"| node_remotemcp
node_agent -->|"reads and writes"| node_cli
node_web -->|"uses"| node_webapi
node_localmcp -->|"dispatches"| node_tools
node_remotemcp -->|"dispatches"| node_tools
node_web -->|"submits content"| node_webingest
node_webingest -->|"invokes"| node_pipeline
node_pipeline -->|"converts files"| node_format
node_pipeline -->|"chunks content"| node_chunking
node_pipeline -->|"embeds chunks"| node_embeddings
node_embeddings -.->|"requests vectors"| node_openai
node_embeddings -->|"uses optionally"| node_localmodel
node_tools -->|"offers search"| node_search
node_tools -->|"offers metadata search"| node_metadata
node_tools -->|"offers ingest"| node_document
node_tools -->|"offers discovery"| node_projects
node_search -->|"queries knowledge"| node_db
node_metadata -->|"queries metadata"| node_db
node_document -->|"writes documents"| node_db
node_pipeline -->|"stores chunks"| node_db
node_projects -->|"discovers projects"| node_db

click node_web "https://github.com/fstamatelopoulos/cerefox/blob/main/frontend/src/App.tsx"
click node_webapi "https://github.com/fstamatelopoulos/cerefox/blob/main/packages/memory/src/web/server.ts"
click node_cli "https://github.com/fstamatelopoulos/cerefox/blob/main/packages/memory/src/cli/program.ts"
click node_localmcp "https://github.com/fstamatelopoulos/cerefox/blob/main/packages/memory/src/server.ts"
click node_remotemcp "https://github.com/fstamatelopoulos/cerefox/blob/main/supabase/functions/cerefox-mcp/index.ts"
click node_tools "https://github.com/fstamatelopoulos/cerefox/blob/main/_shared/mcp-tools/index.ts"
click node_webingest "https://github.com/fstamatelopoulos/cerefox/blob/main/packages/memory/src/web/routes/ingest.ts"
click node_pipeline "https://github.com/fstamatelopoulos/cerefox/blob/main/packages/memory/src/ingestion/pipeline.ts"
click node_format "https://github.com/fstamatelopoulos/cerefox/blob/main/packages/memory/src/ingestion/file-to-markdown.ts"
click node_chunking "https://github.com/fstamatelopoulos/cerefox/blob/main/_shared/ingest/chunker.ts"
click node_embeddings "https://github.com/fstamatelopoulos/cerefox/blob/main/_shared/embeddings/index.ts"
click node_search "https://github.com/fstamatelopoulos/cerefox/blob/main/_shared/mcp-tools/search.ts"
click node_metadata "https://github.com/fstamatelopoulos/cerefox/blob/main/_shared/mcp-tools/metadata-search.ts"
click node_document "https://github.com/fstamatelopoulos/cerefox/blob/main/_shared/mcp-tools/ingest.ts"
click node_projects "https://github.com/fstamatelopoulos/cerefox/blob/main/_shared/mcp-tools/_projects.ts"
click node_localmodel "https://github.com/fstamatelopoulos/cerefox/blob/main/_shared/embeddings/onnx-embedder.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_web,node_webapi,node_cli,node_localmcp,node_remotemcp toneBlue
class node_webingest,node_pipeline,node_format,node_chunking,node_embeddings toneAmber
class node_tools,node_search,node_metadata,node_document,node_projects toneMint
class node_db toneRose
class node_human,node_agent,node_openai,node_localmodel toneIndigo
```

## Components

### Access surfaces

- [Web UI](https://github.com/fstamatelopoulos/cerefox/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Web API](https://github.com/fstamatelopoulos/cerefox/blob/main/packages/memory/src/web/server.ts): `packages/memory/src/web/server.ts`
- [CLI](https://github.com/fstamatelopoulos/cerefox/blob/main/packages/memory/src/cli/program.ts): `packages/memory/src/cli/program.ts`
- [Local MCP](https://github.com/fstamatelopoulos/cerefox/blob/main/packages/memory/src/server.ts): `packages/memory/src/server.ts`
- [Remote MCP](https://github.com/fstamatelopoulos/cerefox/blob/main/supabase/functions/cerefox-mcp/index.ts): `supabase/functions/cerefox-mcp/index.ts`

### Ingestion

- [Web ingest](https://github.com/fstamatelopoulos/cerefox/blob/main/packages/memory/src/web/routes/ingest.ts): `packages/memory/src/web/routes/ingest.ts`
- [Ingest pipeline](https://github.com/fstamatelopoulos/cerefox/blob/main/packages/memory/src/ingestion/pipeline.ts): `packages/memory/src/ingestion/pipeline.ts`
- [File conversion](https://github.com/fstamatelopoulos/cerefox/blob/main/packages/memory/src/ingestion/file-to-markdown.ts): `packages/memory/src/ingestion/file-to-markdown.ts`
- [Chunking](https://github.com/fstamatelopoulos/cerefox/blob/main/_shared/ingest/chunker.ts): `_shared/ingest/chunker.ts`
- [Embeddings](https://github.com/fstamatelopoulos/cerefox/blob/main/_shared/embeddings/index.ts): `_shared/embeddings/index.ts`

### Knowledge services

- [MCP tools](https://github.com/fstamatelopoulos/cerefox/blob/main/_shared/mcp-tools/index.ts): `_shared/mcp-tools/index.ts`
- [Hybrid search](https://github.com/fstamatelopoulos/cerefox/blob/main/_shared/mcp-tools/search.ts): `_shared/mcp-tools/search.ts`
- [Metadata search](https://github.com/fstamatelopoulos/cerefox/blob/main/_shared/mcp-tools/metadata-search.ts): `_shared/mcp-tools/metadata-search.ts`
- [Document tools](https://github.com/fstamatelopoulos/cerefox/blob/main/_shared/mcp-tools/ingest.ts): `_shared/mcp-tools/ingest.ts`
- [Project discovery](https://github.com/fstamatelopoulos/cerefox/blob/main/_shared/mcp-tools/_projects.ts): `_shared/mcp-tools/_projects.ts`

### Persistence

- **Postgres + pgvector**

### Other components

- **People**
- **AI agents**
- **OpenAI embeddings**
- [Local ONNX model](https://github.com/fstamatelopoulos/cerefox/blob/main/_shared/embeddings/onnx-embedder.ts): `_shared/embeddings/onnx-embedder.ts`

## Connections

- People → Web UI: curates with (evidence: `README.md`)
- People → CLI: manages via (evidence: `README.md`)
- AI agents → Local MCP: connects via (evidence: `README.md`)
- AI agents → Remote MCP: connects via (evidence: `README.md`)
- AI agents → CLI: reads and writes (evidence: `README.md`)
- Web UI → Web API: uses (evidence: `README.md`)
- Local MCP → MCP tools: dispatches (evidence: `packages/memory/src/server.ts`)
- Remote MCP → MCP tools: dispatches (evidence: `_shared/mcp-tools/index.ts`)
- Web UI → Web ingest: submits content (evidence: `README.md`)
- Web ingest → Ingest pipeline: invokes (evidence: `packages/memory/src/web/routes/ingest.ts`)
- Ingest pipeline → File conversion: converts files (evidence: `packages/memory/src/ingestion/pipeline.ts`)
- Ingest pipeline → Chunking: chunks content (evidence: `packages/memory/src/ingestion/pipeline.ts`)
- Ingest pipeline → Embeddings: embeds chunks (evidence: `packages/memory/src/ingestion/pipeline.ts`)
- Embeddings → OpenAI embeddings: requests vectors
- Embeddings → Local ONNX model: uses optionally (evidence: `_shared/embeddings/index.ts`)
- MCP tools → Hybrid search: offers search (evidence: `_shared/mcp-tools/index.ts`)
- MCP tools → Metadata search: offers metadata search (evidence: `_shared/mcp-tools/index.ts`)
- MCP tools → Document tools: offers ingest (evidence: `_shared/mcp-tools/index.ts`)
- MCP tools → Project discovery: offers discovery (evidence: `_shared/mcp-tools/index.ts`)
- Hybrid search → Postgres + pgvector: queries knowledge (evidence: `README.md`)
- Metadata search → Postgres + pgvector: queries metadata (evidence: `README.md`)
- Document tools → Postgres + pgvector: writes documents (evidence: `README.md`)
- Ingest pipeline → Postgres + pgvector: stores chunks (evidence: `README.md`)
- Project discovery → Postgres + pgvector: discovers projects (evidence: `README.md`)
