# Go SDK

Go SDK for [cq](https://github.com/mozilla-ai/cq) — the shared agent knowledge commons. It stores knowledge units locally in SQLite and optionally syncs them remotely for shared learning.

## Installation

```bash
go get github.com/mozilla-ai/cq/sdk/go
```

## Quick Start

```go
import cq "github.com/mozilla-ai/cq/sdk/go"

// Create a client (auto-discovers config, falls back to local-only).
c, err := cq.NewClient()
if err != nil {
    log.Fatal(err)
}
defer c.Close()

// Query.
result, _ := c.Query(ctx, cq.QueryParams{
    Domains:   []string{"api", "stripe"},
    Languages: []string{"go"},
})

// Propose.
ku, _ := c.Propose(ctx, cq.ProposeParams{
    Summary: "Stripe 402 means card_declined",
    Detail:  "Check error.code, not error.type.",
    Action:  "Handle card_declined explicitly.",
    Domains: []string{"api", "stripe"},
})

// Confirm / flag.
c.Confirm(ctx, ku)
c.Flag(ctx, ku, cq.Stale)
c.Flag(ctx, ku, cq.Duplicate, cq.WithDuplicateOf("ku_..."))

// Get the canonical agent prompts.
import "github.com/mozilla-ai/cq/sdk/go/prompts"

skillPrompt := prompts.Skill()
reflectPrompt := prompts.Reflect()
```

## Configuration

The client works out of the box in local-only mode with no configuration.

| Variable           | Description           | Default                      |
| ------------------ | --------------------- | ---------------------------- |
| `CQ_ADDR`          | Remote cq API address | None (local-only)            |
| `CQ_API_KEY`       | API key               | None                         |
| `CQ_LOCAL_DB_PATH` | Local SQLite path     | `~/.local/share/cq/local.db` |

Or pass directly:

```go
c, err := cq.NewClient(
    cq.WithAddr("http://localhost:3000"),
    cq.WithLocalDBPath("~/.local/share/cq/local.db"),
)
```

The default database path follows the [XDG Base Directory spec](https://specifications.freedesktop.org/basedir/latest/).

## Knowledge tiers

Every knowledge unit has a tier: `cq.Local` (on-disk SQLite, never leaves the machine), `cq.Private` (stored on the remote API at `CQ_ADDR`, visible to every client pointing at the same remote), or `cq.Public` (open commons; not yet available).

With a remote configured, `Propose` sends the unit to the remote and returns it tagged `cq.Private`; with no remote, or if the remote is unreachable, it writes the unit locally as `cq.Local`.

See the [top-level README](/cq/index.md) for the full description.

## Storage Format

Knowledge units are stored as JSON in SQLite. The database schema is shared with the [cq Python SDK](/cq/components/python.md) — both SDKs read and write the same `local.db` file. The [JSON Schema definitions](https://github.com/mozilla-ai/cq/tree/main/schema) are the source of truth.

## Development

See [DEVELOPMENT.md](/cq/components/go/development.md) for build requirements and setup.

## License

[Apache-2.0](https://github.com/mozilla-ai/cq/blob/gitbook-docs/LICENSE/README.md)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.mozilla.ai/cq/components/go.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.