mozilla-ai/cq: a shared knowledge store for coding agents

The problem cq targets: agents that relearn the same error

A coding agent hits an undocumented API behaviour, tries four fixes, finds one that works, and finishes the task. The next session starts from zero. The README frames this as agents "rediscovering the same failures independently", and cq is the attempt to make that knowledge a shared artifact rather than a private, disposable trace.

The audience is narrow and specific. It is not for someone running a single agent on a single laptop for a one-off script. It is for people who run the same class of agent across several sessions, machines or teammates, and who keep paying for the same debugging work. The README names the kinds of learnings worth capturing: undocumented API behaviour, non-obvious workarounds for known issues, and solutions to errors that took multiple failed attempts. That list is the product definition. If your agents mostly fail on things that are already documented, cq has nothing to store.

There is also a trust dimension. A shared store of agent claims is only useful if bad entries can be marked bad, which is why the tool surface includes confirm and flag alongside query and propose. The project treats knowledge as something that needs endorsement and decay, not just accumulation.

Three runtime boundaries: plugin, local MCP server, remote API

The README describes cq as running across three boundaries. The first is the agent process, where a plugin loads SKILL.md and that file decides when and how the agent reaches for cq tools. The second is a local MCP server, spawned over stdio, which runs the Go CLI and exposes five tools: query, propose, confirm, flag and status. That local process also owns a SQLite store, which the README says defaults to ~/.local/share/cq/local.db. The third boundary is optional: a remote API that runs in a Docker container as a separate FastAPI service, which the README says would be hosted in production with auth, tenancy and RBAC.

So the data flow has two tiers. An agent queries the local store first. Knowledge proposed locally is, per the README, automatically drained to the remote store when the plugin starts, and becomes available to other agents once it has graduated through human review. That graduation step is the interesting design choice: the project does not let one agent's guess propagate to a shared pool without a person approving it. It costs latency and operator attention, and it is the reason the shared pool is worth reading at all.

The README points to docs/architecture.md for diagrams covering knowledge flow, tier graduation, the trust layer, guardrails and the knowledge unit schema. Those details are not in the README itself, so treat the schema as something to read before you write anything that consumes KUs.

Installing the cq CLI and wiring it into a host

The README's installation path is two steps: install the CLI, then install into your coding agent. The CLI is distributed via Homebrew, Scoop or GitHub Releases, and the published Homebrew name is mozilla-ai/tap/cq. Once the binary is on your PATH, the install command takes a target host:

cq install --target claude

The README's table lists the accepted targets: claude, codex, copilot, cursor, devin-desktop, opencode and pi. Repeating --target installs into several hosts in one run. The Makefile's help output also documents --uninstall and --dry-run for the same command, and --dry-run is the one to use first if you are unsure which files the installer touches. Per-host config paths, flags, Windows locations and remote-server setup are in docs/install.md rather than the README.

After installing, the README says to follow docs/quickstart.md to verify it works and add a first knowledge unit. Note the framing there: the README states that you typically do not propose knowledge units manually, because the skill-guided workflow has the agent query before retrying and propose when it learns something. Manual proposal is the fallback, not the intended path.

If you want a shared store instead of a local one, set two environment variables for your assistant. CQ_ADDR is the remote API URL (https://cq.exchange for the hosted service, or your own server's URL), and CQ_API_KEY is the key for authenticated writes. The README notes the key is optional for read-only use of query and status, and that it is generated in the server's UI dashboard.

Self-hosting the server with docker compose

The repository ships a docker-compose.yml that builds ./server and publishes a single port. Two environment variables are required and have no defaults: CQ_JWT_SECRET, used to sign JWTs issued by POST /auth/login, and CQ_API_KEY_PEPPER, an HMAC pepper combined with every API key plaintext under HMAC-SHA256. The .env.example file is explicit that the pepper should be rotated only via a coordinated mass-revoke, which tells you the blast radius of getting it wrong.

The compose file exposes CQ_PORT with a default of 3000, matches the Dockerfile healthcheck, and mounts a named volume at /data for the SQLite database at CQ_DB_PATH (default /data/cq.db). The Makefile provides a shortcut for a local run:

make compose-up
make seed-users USER=demo PASS=demo123

Both commands come from the README's quick local setup section; seed-users creates a login you can use against the dashboard. The .env.example also documents CQ_DATABASE_URL as a SQLAlchemy URL that wins over CQ_DB_PATH when set, though the compose file leaves it commented out.

Semantic search is off by default. TOKEN_EMBEDDING_URL is empty in the example, and the comment says semantic search is enabled when it is set and disabled when it is empty or unset. If you enable it, SEMSEARCH_EMBEDDING_DIM must match the model served at that URL; the default is 768. This is a real operational coupling: point the dimension at the wrong model and the failure will not be obvious from the config file alone.

Where cq is the wrong tool

The README is upfront that this is 0.x and that breaking changes are expected, with migration guides in DEVELOPMENT.md. That is the first limitation and it is not cosmetic: the published components are versioned independently, with release tag prefixes such as cli/vX.Y.Z, server/vX.Y.Z, sdk/go/vX.Y.Z and sdk/python/X.Y.Z. The Go SDK is imported as github.com/mozilla-ai/cq/sdk/go and the Python SDK is on PyPI as cq-sdk, so an upgrade can move one of those without moving the others. If you cannot absorb that, wait.

Second, the local-first default is a trap for exactly the users who would benefit most. With no remote configured, the README states that knowledge stays local on the machine running the plugin. A team of five engineers on five laptops gets five isolated stores and no shared learning at all. The feature that makes cq interesting is the one that requires either cq.exchange or a self-hosted server, and self-hosting means owning auth, tenancy and access.

Third, the human review step is a cost, not a feature you can ignore. KUs proposed locally become available to other agents once graduated via human review. If nobody reviews, the shared pool does not grow. cq does not remove the work of curating knowledge; it moves it from each agent's debugging loop to a queue that someone has to clear.

Finally, the README does not document rollback for a bad KU beyond the flag tool, and it does not document what happens to a local store if you uninstall the plugin. If those matter to you, verify them in docs/ before committing a team.

cq against a plain shared notes repository

The obvious alternative is what most teams already do: a shared repository of markdown notes, a wiki page, or a file of gotchas that engineers paste into a prompt. The difference is not storage, it is invocation. A wiki page is read when a person remembers to read it. cq's mechanism is a SKILL.md that directs the agent to query the store when it starts a task or hits an error, before it retries. The retrieval happens inside the agent loop, not in a human's memory.

That difference cuts both ways. A notes repository has no schema, no MCP server, no SQLite file and no server to run, so it costs nothing to start and nothing to maintain. cq asks you to install a binary, install it into a host, and optionally run a FastAPI service with a JWT secret and an API key pepper. You are buying automatic retrieval and a confirm/flag trust layer, and paying for it in operational surface.

A second alternative is to do nothing and let each agent keep its own context. That is genuinely correct when your agents work on disjoint problems, or when the same failure is cheap to rediscover. The README's own examples of valuable KUs are all cases where rediscovery was expensive: undocumented behaviour, non-obvious workarounds, multi-attempt fixes. Use that as the test. If your agents' errors do not fit those categories, the store will stay empty and the plugin will be overhead.

Licence and what upgrades cost

cq is Apache-2.0. That is a permissive licence, and it matters here because you may be running the server yourself and possibly modifying it. The repository also carries CONTRIBUTOR_AGREEMENT.md and CONTRIBUTING.md at the top level, and SECURITY.md, which is where you would look before reporting a vulnerability in the server or CLI. Nothing in the repository layout suggests a separate commercial licence or a closed component, but that is a description of the files present, not legal advice; read LICENSE and the contributor agreement if you plan to redistribute or run this for a regulated workload.

The upgrade cost is the part to plan for. Because the CLI, server, Go SDK, Python SDK and schema are tagged separately, you should expect to track at least the CLI (cli/v0.17.0) and the server (server/v0.12.1) as distinct upgrade units, with docs (docs/v0.3.0) moving on its own cadence. The README's status note points at DEVELOPMENT.md for migration guides, which implies migrations are expected rather than exceptional. A reasonable posture for a team is to pin the CLI and server versions you have tested and read DEVELOPMENT.md before moving either, rather than tracking the default branch.

Editorial conclusion

Adopt cq if you run coding agents across more than one machine or more than one person and you are willing to run the server or use cq.exchange, because the value only appears once KUs travel between agents. Do not adopt it if you need stable interfaces: the README labels the project 0.x and points to DEVELOPMENT.md for migration guides, and the release tags are versioned per component (cli/v0.17.0, server/v0.12.1, docs/v0.3.0) rather than as one product. Before installing, verify two things: that your host is in the supported target list (claude, codex, copilot, cursor, devin-desktop, opencode, pi), and where your KUs will live, since with no CQ_ADDR set they stay in the local SQLite store at ~/.local/share/cq/local.db and never leave the machine.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. mozilla-ai/cq on GitHub
3. Project website
4. README
5. Releases