Documentation

What is cowork-db?

cowork-db is a bring-your-own-database memory layer for LLM conversations, built around the Model Context Protocol (MCP).

It 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

At its core, cowork-db is a tool for thinking — not an autonomous agent and not a black box. All memory interaction happens through explicit MCP tools. There are no hidden background writes or implicit memory mutation.

How It Works

┌─────────────────┐
│   Your LLM      │  (Claude, GPT, etc.)
│   Application   │
└────────┬────────┘
         │ MCP Tools
         ▼
┌─────────────────┐
│  cowork-db API  │  (Hosted service)
│   api.cowork-db.com
└────────┬────────┘
         │ Tailscale (encrypted)
         ▼
┌─────────────────┐
│   Your Server   │  (Your hardware)
│   ArcadeDB      │  (Apache 2.0)
└─────────────────┘
                        

The BYODB Model

"Bring Your Own Database" means your data stays on your hardware. We provide the API service that connects to your self-hosted ArcadeDB instance over a secure Tailscale network.

• Your data, your hardware — ArcadeDB runs on your machine
• Secure connection — Tailscale creates an encrypted mesh network
• Simple setup — One install script gets everything running
• Open source — ArcadeDB is Apache 2.0, Cypher on top of a standard HTTP API

Getting Started

curl -fsSL https://cowork-db.com/install.sh | bash -s -- --key YOUR_KEY

irm cowork-db.com/install.ps1 | iex

Invoke-WebRequest -Uri https://cowork-db.com/install.ps1 -OutFile install.ps1
.\install.ps1 -Key "YOUR_KEY"

# List available tools
curl -X POST "https://api.cowork-db.com/mcp/v1/" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

# List available tools
curl -X GET "https://api.cowork-db.com/mcp/tools" \
  -H "X-API-Key: YOUR_API_KEY"

Create Multiple Databases

You can run multiple ArcadeDB databases on one BYODB machine and bind separate API keys to each one. This is useful for splitting work/personal contexts, environments, or teams.

1) Open your Local Dashboard and create a database

1. From cowork-db.com/dashboard, click Open Local Dashboard
2. In Create Database, enter database_id and display name
3. Leave port empty to auto-assign the next free HTTP port (2480+)
4. Click Create Database

The local dashboard will create a new ArcadeDB container, wait for /api/v1/ready, run the bootstrap DDL (vertex/edge types + HNSW vector indexes), and append it to your local registry automatically.

2) Advanced/manual fallback (optional)

If you prefer manual container management, keep the existing cowork-tailscale sidecar and run additional ArcadeDB containers in the same network namespace using unique ports.

# Example: second database on port 2481
docker run -d \
  --name cowork-arcadedb-personal \
  --restart unless-stopped \
  --network container:cowork-tailscale \
  -e "JAVA_OPTS=-Darcadedb.server.httpIncoming.port=2481" \
  -v cowork-arcadedb-personal-data:/home/arcadedb/databases \
  -v cowork-arcadedb-personal-log:/home/arcadedb/log \
  arcadedata/arcadedb:latest

Typical port pattern: 2480 (default), 2481, 2482, ...

3) Verify local registry entries

Local registry file locations:

• Linux/macOS: ~/.cowork-db/databases.json
• Windows: %USERPROFILE%\.cowork-db\databases.json

If you use the Local Dashboard create flow, entries are added automatically.

{
  "version": 1,
  "databases": [
    {
      "database_id": "default",
      "name": "Default",
      "container_name": "cowork-arcadedb",
      "backend": "arcadedb",
      "host": "127.0.0.1",
      "port": 2480,
      "embedding_model": "harrier-270m",
      "embedding_dimension": 640,
      "profile_id": "memory-default",
      "profile_version": 1
    },
    {
      "database_id": "personal-db",
      "name": "Personal",
      "container_name": "cowork-arcadedb-personal",
      "backend": "arcadedb",
      "host": "127.0.0.1",
      "port": 2481,
      "embedding_model": "harrier-270m",
      "embedding_dimension": 640,
      "profile_id": "memory-default",
      "profile_version": 1
    }
  ]
}

database_id is the key identifier you will use in API key creation.

4) Create one API key per database ID

1. Go to cowork-db.com/dashboard → Create API Key
2. Expand Database Target (Optional)
3. Set Database ID (example: personal-db)
4. Leave host/port/auth fields at defaults to use local registry sync

On key creation, cowork-db pulls the target route from your local dashboard over the private Tailnet and binds that key to the resolved database target.

5) Verify routing

Create two keys with different database IDs, then issue the same MCP read call with each key. You should see results from different ArcadeDB instances.

Available Tools

Your AI model can discover and call these tools automatically. All tools are designed to be:

• Explicit — No hidden behavior
• Deterministic — Same input → same effect
• Inspectable — Results can be audited
• Composable — Do one thing well

Note: When using Claude.ai Custom Connectors or the official MCP protocol, these tools are automatically discovered via the tools/list method with full JSON Schema definitions.

For complete tool schemas, examples, and integration code, see the API Reference →

Updating Your Installation

When we release updates, you can update your local installation without losing any data:

curl -fsSL https://cowork-db.com/update.sh | bash

The update script:

• Backs up your current docker-compose.yml
• Pulls the latest container images
• Restarts services with zero data loss
• Preserves your Tailscale authentication

ArcadeDB Studio

Each ArcadeDB container ships with ArcadeDB Studio, a visual interface for exploring your graph database.

Access it at http://localhost:<db-port>/ on your database host machine. Login as root with the password from LOCAL_DASHBOARD_ARCADEDB_ROOT_PASSWORD.

With Studio you can:

• Run Cypher (or SQL / Gremlin) queries directly
• Visualize entity relationships as a graph
• Inspect Memory, Entity, and Staging vertices and their HNSW-indexed embeddings
• Export query results

Security Model

• Data stays local — Your ArcadeDB instance runs on your hardware
• Encrypted transport — Tailscale provides end-to-end encryption
• No public exposure — Database is only accessible via private Tailscale network
• Auth0 authentication — API access requires valid JWT tokens
• User isolation — Each user's data is namespaced and isolated

FAQ

Getting Help

Need assistance? Here are your options:

• Email: support@cowork-db.com
• GitHub: Open an issue