cowork-db

cowork-db is a memory proxy for LLM conversations built around the Model Context Protocol (MCP).

It is implemented as a BYODB (Bring Your Own Database) MCP service with zero-SSH CI/CD deploys, designed to persist, retrieve, and inspect structured memories derived from LLM chats.

At its core, cowork-db is a tool for thinking — not an autonomous agent and not a black box.

---

What cowork-db does

cowork-db provides a structured, inspectable way to:

• Store human-readable memories derived from LLM conversations
• Link those memories to entities (people, projects, tools, concepts)
• Retrieve relevant context to ground future conversations
• Keep humans in control of what is remembered and why
• Run your own database locally while connecting to the cloud API
• Manage databases from a local dashboard with an AI-powered setup wizard
• Bring your own AI provider (OpenAI, Anthropic, Google, Groq, or local Ollama) via Bifrost

All memory interaction happens through explicit MCP tools. There are no hidden background writes or implicit memory mutation.

---

Architecture (BYODB)

flowchart LR
    subgraph User["User's Machine"]
        direction TB
        Arcade["ArcadeDB containers<br/>(Apache 2.0)<br/>Graph + HNSW vectors"]
        Bifrost["Bifrost Proxy (Docker)<br/>LLM Provider Gateway"]
        Dashboard["Local Dashboard (Docker)<br/>DB Mgmt + Wizard +<br/>Proxy + Embeddings +<br/>Staging Reconciler"]
        Tailscale["Tailscale Sidecar<br/>(Docker)"]
        Arcade --- Bifrost
        Bifrost --- Dashboard
        Dashboard --- Tailscale
    end

    subgraph Cloud["Cloud Infrastructure"]
        direction TB
        API["FastAPI MCP API<br/>(cowork-db.com)"]
        Headscale["Headscale Control Plane<br/>(Self-hosted)"]
        API --> Headscale
    end

    Tailscale <-- "Encrypted Mesh" --> Cloud

Key characteristics

• BYODB: Your database runs locally, you own your data
• MCP-first: LLMs interact via tools, not internal APIs
• Graph-backed: ArcadeDB stores entities, memories, relationships, staging
• Inspectable: every memory has provenance and confidence; LLM-proposed writes pass through an auditable staging reconciler before they commit
• Secure: Tailscale mesh provides encrypted, isolated access
• Deployable: containerized, CI/CD-driven, no manual SSH
• AI-assisted: local dashboard includes a wizard agent for database setup and schema design
• Multi-provider: Bifrost gateway supports OpenAI, Anthropic, Google, Groq, and Ollama

---

Documentation (3-min reads)

Read in order:

1. Architecture - System overview and BYODB design
2. ArcadeDB Setup - Database configuration and connection
3. MCP Tools - API tool reference and usage patterns
4. Vector Search - How semantic search works
5. Cypher Queries - Example queries for inspection
6. Tool Schemas - Complete MCP tool schema definitions
7. BYODB Architecture - How user-owned databases work
8. Frontend Setup - Web dashboard and Auth0
9. Headscale Setup - Private networking setup
10. Onboarding API - User registration endpoints
11. API Key Auth - PASETO-based API key authentication
12. AI Model Integration - MCP protocol and REST integration

---

CI/CD philosophy (IMPORTANT)

cowork-db follows a container-first, zero-SSH deployment model.

There are no manual server mutations.

CI/CD flow

1. Push to main
2. GitHub Actions builds and pushes:

ghcr.io/<owner>/mcp-api:latest

3. Watchtower on the VM pulls the new image and restarts mcp-api

This ensures:

• Reproducible deployments
• No configuration drift
• Clear rollback paths

---

Configure production compose

Edit deploy/docker-compose.prod.yml and set:

• YOUR_GITHUB_USER_OR_ORG for container image
• GRAPH_STORE_BACKEND (defaults to arcadedb)

See 02_ArcadeDBSetup.md for connection details.

---

Local development (venv)

For local iteration without containers:

cd api
python3 -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt -r requirements-dev.txt
fastapi dev app/main.py --host 0.0.0.0 --port 8080

This runs the MCP API locally while pointing to a reachable local dashboard (and through it, the ArcadeDB backend). ArcadeDB connectivity notes live in docs/02_ArcadeDBSetup.md.

---

MCP tool endpoints (POC)

See 02_ArcadeDBSetup.md for connection configuration.

• POST /mcp/coworkdb_upsert_entities
• POST /mcp/coworkdb_write_memory
• POST /mcp/coworkdb_link_entities
• POST /mcp/coworkdb_delete_entities
• POST /mcp/coworkdb_search
• POST /mcp/coworkdb_context
• POST /mcp/coworkdb_recent
• POST /mcp/coworkdb_stats

These routes proxy through the local dashboard's POST /api/sync/query endpoint to the user's ArcadeDB container.

Optional auth

Set AUTH_TOKEN in the environment to require a bearer token on MCP routes. Clients can send either:

• Authorization: Bearer <token>
• X-Auth-Token: <token>

---

Tests

cd api
. .venv/bin/activate
PYTHONPATH=api pytest api/tests

Tests focus on:

• MCP tool behavior
• Memory writes and retrieval
• Deterministic, inspectable outputs

---

Design principles (TL;DR)

• Explicit over implicit
• Inspectable over magical
• Structured over clever
• Reversible over permanent

If a memory can’t be explained later, it doesn’t belong in the database.

---

Project status

cowork-db is under active development.

Current capabilities:

• MCP-based memory ingestion and retrieval
• Deterministic vector search and context retrieval
• Local dashboard with AI-powered database setup wizard
• Multi-provider LLM support via Bifrost (OpenAI, Anthropic, Google, Groq, Ollama)
• User account authentication with password management
• Multi-database management from the local dashboard
• API key management for external agent access

For deeper design rules, see:

• AGENTS.md
• CONTRIBUTING.md

---

What cowork-db is NOT

• ❌ An autonomous agent brain
• ❌ A hidden surveillance memory
• ❌ A black-box vector store
• ❌ A rigid ontology experiment

cowork-db exists to help humans and LLMs think together, not to replace human judgment.

---

License

TBD