VibeXP 开源发布：基于 MCP 的跨 AI 工具共享知识库

Stop re-explaining everything to your AI. 🧠

One shared knowledge base your prompts, rules, memory, and past work live in, that every AI tool can read from and write back to. Claude Code, Cursor, ChatGPT, Gemini, VS Code, Codex, and anything that speaks MCP.

Free, open source, and self-hostable.

🌐 Website · 📚 Docs · ✍️ Blog

⭐ If this solves a problem for you, please star the repo so more people find it.

The problem 😩

The more AI tools you use, the more you lose, and the more your team duplicates:

• 🔁 You rewrite the same prompts in every tool, every session.
• 🗣️ You re-explain your context constantly because your AI starts from scratch every time.
• 🧱 Your knowledge is trapped in silos that never talk to each other, and never reach your teammates.

The concept 🎬

A short walkthrough of the idea behind VibeXP and how it changes the way you work with AI:

vibexp_concept.mp4

How VibeXP solves it ✨

VibeXP is one place for everything your AI relies on, connected to your tools over the Model Context Protocol (MCP) (Claude Code CLI, Cowork, Codex, Gemini CLI, Cursor, VS Code, ChatGPT, and more). It turns one-off chats into a knowledge base that compounds:

1. Before a task your AI reads the relevant prompts, rules, memory, and past work first, so it starts with everything already learned.
2. As it works it saves new lessons, updates memory, and stores outputs back into VibeXP.
3. Every session after that richer knowledge is waiting, for you and your whole team.

What lives in VibeXP

Quick start (self-host) 🚀

You need Docker with Compose. This runs the published combined image (the SPA and API are served from one port) plus PostgreSQL (pgvector).

git clone https://github.com/vibexp/vibexp.git
cd vibexp
docker compose up -d

Then open:

• 🖥️ App: http://localhost:8080
• ⚙️ API health: http://localhost:8080/health
• 📄 OpenAPI spec: http://localhost:8080/openapi.yaml (or /openapi.json) — the full, self-contained API contract, served publicly by every instance for code generators, Postman, and the Swagger editor.

Local evaluation uses a dev-login bypass, so there is nothing to configure to start clicking around.

⚠️ Before exposing it to the internet (required config)

The defaults in docker-compose.yml are for local evaluation only. For any real deployment, edit the app service environment:

• FRONTEND_BASE_URL — set this to your real public URL (e.g. https://vibexp.example.com) first. It is the single origin serving both the SPA and the API (same-origin: no separate frontend URL, no CORS), and pointing it away from localhost is what turns off the local-eval dev-login bypass and the auto-enabled local MCP server. Leave it at localhost while exposing the app and anyone can sign in as any user.
• ENCRYPTION_KEY — required, exactly 32 bytes. Generate one: openssl rand -base64 24 | cut -c1-32
• DB_PASSWORD — change it from the default (and keep POSTGRES_PASSWORD in sync).
• SESSION_ENCRYPTION_KEY (openssl rand -hex 32) and an identity provider: set AUTH_PROVIDER to google, github, or oidc with the matching *_CLIENT_ID / *_CLIENT_SECRET (and *_REDIRECT_URI if it differs from <FRONTEND_BASE_URL>/api/v1/auth/callback). For several providers at once, mount a config.yaml with auth.providers: [...].
• MCP in production (optional) — set OAUTH_AS_ISSUER_URL (your public HTTPS URL) and MCP_RESOURCE_URI (<url>/mcp/v1/common) to enable the embedded OAuth server that issues MCP tokens.
• Branding / analytics (optional) rebrand the SPA at deploy time with VITE_* env vars (served via /config.js, no rebuild) — see the app service comments in docker-compose.yml.
• Semantic search & file attachments are optional, opt-in services. See the comments in docker-compose.yml and the docs.

Data persists in the pgdata volume.

Deploy anywhere 🌍

VibeXP is one self-contained binary in one image — no hosting-platform assumptions. It reads a single config.yaml; the published image bakes a default (backend/config.docker.yaml) whose every value is a ${VAR:-default} reference, so environment variables alone configure a container. To control every setting instead, mount your own file over /app/config.yaml — start from backend/config.example.yaml.

Every deployment needs: a reachable PostgreSQL with pgvector, plus DB_PASSWORD and a 32-byte ENCRYPTION_KEY. For internet-facing use, also set FRONTEND_BASE_URL (your public origin), SESSION_ENCRYPTION_KEY, and an identity provider (see the section above).

Postgres extensions. Migrations enable vector (semantic search) and pg_trgm (keyword-search typo tolerance). Both ship with PostgreSQL and the bundled image handles them automatically; on managed Postgres the connecting role must be allowed to CREATE EXTENSION for these (most providers list them as pre-approved extensions), or the migrations fail fast at startup.

🐳 docker run (single container)

docker run -p 8080:8080 \
  -e DB_HOST=your-db-host -e DB_PASSWORD=secret \
  -e ENCRYPTION_KEY="$(openssl rand -base64 24 | cut -c1-32)" \
  -e FRONTEND_BASE_URL=https://vibexp.example.com \
  ghcr.io/vibexp/vibexp:latest

To replace the baked config entirely, mount your own and pass only secrets via env:

docker run -p 8080:8080 -v "$PWD/config.yaml:/app/config.yaml:ro" \
  -e DB_PASSWORD=secret -e ENCRYPTION_KEY=... ghcr.io/vibexp/vibexp:latest

The baked FRONTEND_BASE_URL defaults to empty (fail-closed: no dev-login bypass). To evaluate locally with the dev-login shortcut via a bare docker run, add -e FRONTEND_BASE_URL=http://localhost:8080 — or just use docker compose up, which sets it for you.

🧩 Docker Compose

The bundled docker-compose.yml runs the image alongside Postgres. Set your secrets in the app service environment: (or supply them via a .env file that Compose substitutes), then:

docker compose up -d

☸️ Kubernetes

Put secrets in a Secret exposed as env (consumed by the baked config's ${VAR} references), and — when you want full control — mount a config.yaml from a ConfigMap over /app/config.yaml:

env:
  - name: DB_HOST
    value: postgres
  - name: FRONTEND_BASE_URL
    value: https://vibexp.example.com
  - name: DB_PASSWORD
    valueFrom: { secretKeyRef: { name: vibexp, key: db-password } }
  - name: ENCRYPTION_KEY
    valueFrom: { secretKeyRef: { name: vibexp, key: encryption-key } }
# optional full-config override:
volumeMounts:
  - { name: config, mountPath: /app/config.yaml, subPath: config.yaml }
volumes:
  - { name: config, configMap: { name: vibexp-config } }

📦 Bare binary

make build-combined produces a single self-contained backend/bin/vibexp (frontend embedded). It loads ./config.yaml by default; override with --config /path/to/config.yaml or VIBEXP_CONFIG_FILE=.... Copy backend/config.example.yaml to config.yaml and edit it.

⬆️ Upgrading an existing deployment? Check the upgrade guide — it lists the breaking changes that need a config edit before the new image will start.

Connect your AI tools 🔌

VibeXP exposes a single MCP endpoint. Sign in once in the browser, no API keys to copy-paste and babysit. Point your tool at your own deployment's MCP endpoint, for example with Claude Code:

claude mcp add --transport http vibexp http://localhost:8080/mcp/v1/common

Swap localhost:8080 for your deployment's public URL. Full per-tool instructions (Cursor, VS Code, Gemini CLI, ChatGPT, Codex) are in the docs.

For developers 🛠️

VibeXP is a monorepo shipped as a single combined Docker image (the backend embeds and serves the frontend SPA + API from one port):

• backend/ Go REST API. Spec-first OpenAPI, PostgreSQL + pgvector, MCP endpoint, pluggable identity-provider auth (Google/GitHub/generic OIDC). Also embeds and serves the built SPA.
• frontend/ Vite + React + TypeScript SPA. Served by the Vite dev server in development; built and embedded into the backend for release.

Local development

Local development uses the Makefile (not the root docker-compose.yml, which runs the published images).

# Backend: Postgres + hot-reload API
make backend-run-dev

# Frontend: Vite dev server on http://localhost:5173
make frontend-run-dev

Local embedding backend. make backend-run-dev (and a plain docker compose up in backend/) also starts an embeddings service — HuggingFace text-embeddings-inference serving mixedbread-ai/mxbai-embed-large-v1 (1024-dim) with an OpenAI-compatible /v1/embeddings — so semantic search works out of the box with no external endpoint. The first start downloads ~670MB of model weights into the tei_data volume (persisted across restarts); check readiness with curl http://localhost:8000/health. Override the host port with TEI_PORT if 8000 collides. Register it in the app as a team embedding provider:

• Provider type: openai_compatible
• Base URL: http://localhost:8000/v1
• Model: mixedbread-ai/mxbai-embed-large-v1
• API key: any value (or leave empty — TEI ignores it)

The recommended query prefix for this model is Represent this sentence for searching relevant passages: .

Self-hosting this outside local development? The backend refuses outbound requests to loopback and private address ranges (SSRF protection), so a sidecar on localhost or a private Docker subnet is unreachable until you declare its network. Local development is exempt — a localhost frontend.base_url already permits it — but any real deployment must set security.outbound_allowed_cidrs (env OUTBOUND_ALLOWED_CIDRS in the combined image), e.g. 172.16.0.0/12 for Docker bridge networks or 127.0.0.1/32 for a same-host TEI/Ollama. Without it, embedding and semantic search fail with connection to disallowed address range blocked. Link-local (cloud metadata) and multicast can never be allowlisted; an overlapping entry fails startup.

Applying embedding-pipeline improvements to existing data. Changes to how content is embedded (for example, the per-chunk title + description context header) take effect automatically for resources created or edited afterwards, but already-embedded resources keep their old vectors until they are regenerated. The Reprocess action on a team's embedding-provider settings only fills in missing embeddings; a full regeneration of existing vectors is triggered when the team's embedding provider identity changes (model, base URL, or instruction prefix). To adopt a pipeline improvement across a team's existing data, trigger that full re-embed.

Common checks:

make backend-test    make backend-lint    make backend-check
make frontend-test   make frontend-lint   make frontend-type-check

Pre-commit hooks are mandatory. Install them once per clone so every commit is gated on the same checks CI runs:

pre-commit install

See CLAUDE.md for the full contributor guide and conventions.

Contributions are welcome. Branch off main, open a PR, and let CI pass. 💚 Every PR must link an open issue — add Fixes #N to the description or link one from the Development sidebar (a pr-linked-issue check enforces this). The repo also runs stale-issue and project-board automations — see CLAUDE.md.

Always target main, including bug fixes. Patch releases are cut from a release/X.Y.x maintenance branch, but fixes land on main first and maintainers cherry-pick them onto the line — you never need to open a PR against a release branch. Full process: Releases and backports.

License 📄

AGPL-3.0-or-later.