Context0 Quick Start

1. Install

npm install -g @polardbx/ctxdb0

2. Configure

First establish a connection, then install to the target AI tool:

printf '%s' "$CTXDB0_API_KEY" | ctxdb0 connect \
  --profile default \
  --endpoint http://<your-endpoint> \
  --user-id <end-user-identifier> \
  --api-key-stdin \
  --json

ctxdb0 attach --host claude --json
ctxdb0 doctor --host claude --json

--host values:

3. Verify

ctxdb0 doctor --host claude --json

doctor checks the connection profile and API reachability, host installation status, and managed asset integrity. If all checks pass, the setup is complete.

4. How it works

The plugin consists of three components:

• Lifecycle Hooks (automatic): Injects historical context at session start; automatically submits each completed round to the backend for asynchronous long-term memory extraction.

• Explicit CLI (manual): Agents call ctxdb0 memory / knowledge / sessions / skills and other commands on demand to read/write memories and search the knowledge base.

• Static Skill (guidance): Installs the ctxdb0-context Skill with the plugin. Agents automatically select appropriate CLI commands based on user natural language.

5. Command reference

All commands support --json. Agents should always include this flag.

# Connection and diagnostics
ctxdb0 connect --profile <name> --endpoint <url> --user-id <id> --api-key-stdin --json
ctxdb0 setup --host <host> --endpoint <url> --user-id <id> --api-key-stdin --json
ctxdb0 attach  --host <host> --json
ctxdb0 doctor  --host <host> --json
ctxdb0 config show --json
ctxdb0 refresh --host <host> --json

# Memory
printf '%s' 'Project uses TypeScript + Prisma' | ctxdb0 memory remember --stdin --json
ctxdb0 memory recall 'tech stack selection' --limit 5 --json
ctxdb0 memory browse --offset 0 --limit 20 --json
ctxdb0 memory show <memory-id> --json
printf '%s' 'replacement content' | ctxdb0 memory revise <memory-id> --stdin --json
ctxdb0 memory forget <memory-id> --confirm-id <memory-id> --json

# Knowledge base
ctxdb0 knowledge sources --json
ctxdb0 knowledge sources create --name <name> --description '<description>' --json
ctxdb0 knowledge query 'canary release requirements' --source <source> --json
ctxdb0 knowledge documents --source <source> --json
ctxdb0 knowledge documents show <document-id> --source <source> --json
ctxdb0 knowledge import --source <source> --file ./docs/adr.md --json

# Sessions and managed Skills
ctxdb0 sessions browse --page 0 --limit 20 --json
ctxdb0 sessions restore <session-id> --json
ctxdb0 skills search 'incident response' --json
ctxdb0 skills fetch <skill-id> --json

# Migration and cleanup
ctxdb0 migrate --plan --json
ctxdb0 migrate --apply --confirm <confirmation-token> --json
ctxdb0 purge --plan --json
ctxdb0 purge --confirm <confirmation-token> --json

# Uninstall
ctxdb0 detach --host <host> --json

6. Configuration

connect writes non-sensitive configuration to ~/.ctxdb0/plugin/config.json. The API Key is stored separately in credentials.json with 0600 permissions. Default behavior configuration:

Behavior configuration is modified via CLI:

ctxdb0 config set recall-mode intent --json
ctxdb0 config set session-batch off --json
ctxdb0 config set prompt-knowledge-recall off --json

# Enable Prompt-KB recall (specify knowledge source name)
ctxdb0 config set prompt-knowledge-recall on --source <name> --json

# Use all currently accessible knowledge sources (snapshot fixed to configuration)
ctxdb0 config set prompt-knowledge-recall on --all-accessible --json

Project-level override: place .ctxdb0.json in the project root directory. It can only tighten global configuration (reduce recall mode, disable session batch, disable Prompt-KB recall), and cannot select profiles, endpoints, or relax behavior. No credential fields are allowed.

Prerequisites

All requests must include the X-API-Key header. Set environment variables first:

export API_KEY="<YOUR_API_KEY>"
export HOST="http://<your-endpoint>"

Authentication supports three equivalent header formats:

-H "X-API-Key: $API_KEY"              # recommended
-H "Authorization: Token $API_KEY"
-H "Authorization: Bearer $API_KEY"

1. Verify connectivity (whoami)

curl "$HOST/v1/auth/whoami" \
  -H "X-API-Key: $API_KEY"

Response:

{
  "code": 0,
  "msg": "ok",
  "data": {
    "authenticated": true,
    "workspace_id": 1,
    "member_id": 1,
    "key_type": "USER",
    "bound_user_id": "user_001"
  }
}

data.authenticated being true means the connection is successful.

2. Write conversations (ingest)

Write conversations to a session. The server asynchronously extracts memories:

curl -X POST "$HOST/v1/context/ingest" \
  -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{
    "session_id": "sess_789",
    "user_id": "user_001",
    "agent_id": "my-agent",
    "messages": [
      {"role": "user", "content": "I want to deploy my app with Docker"},
      {"role": "assistant", "content": "You can use Docker Compose to start the stack with one command"}
    ]
  }'

Response:

{
  "code": 0,
  "data": {
    "session_id": "sess_789",
    "session_internal_id": 1234,
    "message_ids": [{"id": 1001, "seq": 1}, {"id": 1002, "seq": 2}],
    "event_id": 99001
  }
}

3. Assemble context (assemble)

Recall relevant memories and knowledge by query, select the best within the token_budget, and output prompt_blocks that can be directly appended to the system prompt:

curl -X POST "$HOST/v1/context/assemble" \
  -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{
    "session_id": "sess_789",
    "user_id": "user_001",
    "query": "How to deploy the app?",
    "token_budget": 4000,
    "recall": {"top_k": 8}
  }'

Response (excerpt):

{
  "code": 0,
  "data": {
    "prompt_blocks": [
      {"role": "system", "tag": "user_profile", "content": "User prefers Docker deployment", "tokens": 20, "sources": []}
    ],
    "token_used": 255,
    "token_budget": 4000,
    "trace_id": "550e8400-..."
  }
}

4. Search memories (search)

Search long-term memories by semantics (vector + BM25 hybrid):

curl -X POST "$HOST/v2/memories/search" \
  -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{
    "query": "tech stack selection",
    "user_id": "user_001",
    "limit": 10
  }'

Response (raw JSON array):

[
  {"id": "mem_123", "memory": "Project uses TypeScript + Prisma", "score": 0.92, "user_id": "user_001"},
  {"id": "mem_124", "memory": "Auth solution: NextAuth", "score": 0.85, "user_id": "user_001"}
]