DIGEST! REMEMBER! RECALL!
Copepod is the institutional memory layer for GitHub repositories, powered by Cognee.
Every engineering team accumulates invisible context over time—why a bug-like line is actually a critical workaround, or why a simple approach was rejected. When developers leave or production breaks at 2 AM, this context vanishes. Copepod solves developer amnesia.
It ingests your repository's entire history (PRs, issues, AST code structure), builds a semantic knowledge graph using Cognee, and exposes it through three intuitive interfaces: a Web Studio, an MCP Server, and an interactive VS Code Graph Sidebar.
Web Studio · FastAPI Backend · MCP Server · VS Code Extension · Docs · Cognee Engine
New install? Start here: Docker Quick Start or run the setup locally with docker compose up --build.
Deploy the entire stack (FastAPI Backend + SQLite + Cognee DBs + Studio Web UI) locally in a single command:
# 1. Clone the project
git clone https://github.com/your-org/copepod.git
cd copepod
# 2. Configure credentials
cp backend/.env.example backend/.env
# Open backend/.env and populate your GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET, and GROQ_API_KEY.
# 3. Launch with Docker Compose
docker compose up --build- Web Studio: Access at
http://localhost:3000 - FastAPI Backend Docs: Access at
http://localhost:8000/docs
To include the MCP server in your compose stack, run:
docker compose --profile mcp up --build- 🖥️ Web Studio (Next.js): A Next.js frontend built with a minimalist, grid-based engineering blueprint aesthetic. Track repository ingestion progress in real-time using Server-Sent Events (SSE), chat with your repository's history, and view source citations linking answers back to PR numbers, issues, or code symbols.
- 🔌 MCP Bridge (Model Context Protocol): Exposes the repository's institutional memory directly to your local AI coding assistants (like Claude Code, Cursor, Cline, or Copilot). Features tools like
ask(question)andfile_context(file_path)to query decision history before rewriting code. - 📐 VS Code Extension (Decision Graph): A custom sidebar containing an interactive SVG-based node hierarchy graph. Includes auto-detection of the active repository, visual traces connecting files to PRs and issues, and a Code Trust Scorer (0.0 - 1.0) calculating code stability based on commit recency and regression history.
- 🧠 Cognitive Memory Lifecycle — Full structured lifecycle operations using Cognee's
remember(),recall(),improve(), andforget()mechanisms. - 🔒 Isolated Datasets — Deterministic namespace mapping (
copepod_{user_id}_{owner}_{repo}) to ensure strict data separation per repository. - ⚙️ Zero-Cost Embedded DBs — Runs local, embedded KuzuDB (graph) and LanceDB (vector) instances requiring $0 infrastructure cost.
- 🧩 Python AST Parser — Extracts functions, classes, decorators, docstrings, and call-graphs as declarative memory statements automatically.
- ⚡ Granular Payload Formatter — Converts raw GitHub webhook and API JSON payloads into structured English sentences for high entity-extraction accuracy.
Copepod implements a complete memory lifecycle using Cognee's four core operations:
┌───────────────────────────────┐
│ REMEMBER │
│ Ingest PRs, Issues, AST │
└───────────────┬───────────────┘
│
▼
┌───────────────┐ ┌───────────────┐ ┌───────────────┐
│ IMPROVE │◄───────┤ RECALL ├───────►│ FORGET │
│ Reinforce on │ │ Ask Studio, │ │ Prune deleted │
│ merged PRs │ │ MCP, VS Code │ │ files/repos │
└───────────────┘ └───────────────┘ └───────────────┘
remember()(Ingestion): Triggers during initial repository setup and incremental GitHub webhook events (PR merges, issue closures).recall()(Retrieval): Executes during search and chat queries from the Web Studio, VS Code Sidebar, MCP tools, and automated triage.improve()(Refinement): Triggers when a pull request referencing Copepod context is successfully merged. It validates that the recalled context was accurate, reinforcing the knowledge graph.forget()(Pruning): Cleans up memory when a repository is disconnected or when file deletion events are received via push webhooks.
Copepod runs entirely self-hosted:
┌───────────────────────┐
│ VS Code / MCP / Web │
└───────────┬───────────┘
│ HTTPS (X-API-Key / JWT)
▼
┌───────────────────────┐
│ FastAPI Backend │
└───────────┬───────────┘
│
┌──────────────┴──────────────┐
▼ ▼
┌─────────────────────────┐ ┌─────────────────────────┐
│ GitHub Webhooks │ │ Cognee Engine │
│ Delta updates & │ │ Isolated datasets │
│ Automated Triage │ │ per repository │
└─────────────────────────┘ └────────────┬────────────┘
│
┌────────────────┬────────────────┬───────────────┐
▼ ▼ ▼ ▼
┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ LiteLLM / │ │ fastembed │ │ KuzuDB │ │ LanceDB │
│ Groq API │ │ (Local CPU) │ │ (Graph DB) │ │ (Vector DB) │
│ (Free LLM) │ │ (Embeddings)│ │ (Embedded) │ │ (Embedded) │
└─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘
- Embedded DBs: Utilizes local KuzuDB and LanceDB inside the container.
- Python AST Parser: Parses files syntax-by-syntax (
app/services/code_parser.py) to map codebase relationships. - Payload Formatter: Translates webhook JSONs to semantic statements (
app/services/formatter.py).
If you prefer to run components individually outside of Docker:
- Go to your GitHub profile → Settings → Developer Settings → OAuth Apps → New OAuth App.
- Set Homepage URL to
http://localhost:3000. - Set Authorization callback URL to
http://localhost:8000/auth/github/callback. - Copy the Client ID and generate a Client Secret.
cd backend
python -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
# Install package in editable mode
pip install -e .
# Run migrations/startup tables and launch server
uvicorn app.main:app --reload --port 8000cd studio
npm install
npm run dev
# The website will spin up at http://localhost:3000- Open the
vscode-extensiondirectory in VS Code. - Run
npm installinside the extension directory. - Compile the TypeScript:
npm run compile. - Press
F5to open a new Extension Development Host window. - In VS Code Settings, configure:
copepod.apiKey: Obtain this API key from the Web Studio's profile settings.copepod.repoId: The UUID of the repository created in the Studio database.
Add the Copepod MCP server to your local desktop agent (e.g., Claude Desktop) by editing your configuration file:
- Location (MacOS/Linux):
~/Library/Application Support/Claude/claude_desktop_config.json - Location (Windows):
%APPDATA%\Claude\claude_desktop_config.json
Add this entry to your config:
{
"mcpServers": {
"copepod": {
"command": "python",
"args": [
"-m",
"copepod_mcp.server"
],
"env": {
"COPEPOD_CONFIG": "/absolute/path/to/your/project/.copepod/config.json"
}
}
}
}Where .copepod/config.json inside your project root contains:
{
"api_url": "http://localhost:8000",
"api_key": "your-copepod-api-key",
"repo_id": "your-repo-uuid"
}Contributions are what make the open-source community an amazing place to learn, inspire, and create.
- Fork the Project.
- Create your Feature Branch (
git checkout -b feature/AmazingFeature). - Commit your Changes (
git commit -m 'Add some AmazingFeature'). - Push to the Branch (
git push origin feature/AmazingFeature). - Open a Pull Request.
AI/vibe-coded PRs welcome! 🤖
This project is licensed under the MIT License - see the LICENSE file for details.
Built with 💜 using Cognee for the Cognee Hackathon 🧠