# CortexDB Agent Skill

<!-- GENERATED by scripts/agent_manifest.py — do not edit by hand.
     Every version fact below comes from the release manifest
     (sha256:cbb6e8faa43e...). -->

Install and verify CortexDB for the user's stated use case, using the
least-privilege profile, without guessing any package name, version, endpoint,
recall view or deletion mode.

**Before anything else, fetch `/agent/manifest.json`.** It is the source
of truth for everything below and is regenerated whenever the shipped surface
changes. If it is older than 3600s, refetch it;
if the refetch fails, stop and say so rather than proceeding on stale facts.

## Current release profile

| Component | Install | Published |
|---|---|---|
| Server | `cortexdb/cortexdb:v0.9.6` | 0.9.6 |
| Python SDK | `pip install cortexdbai` | 0.11.0 |
| TypeScript SDK | `npm install cortexdbai` | 0.9.1 |
| CLI | `pip install cortexdb-cli` | 0.5.0 |
| MCP server | `pip install cortexdb-mcp` | 0.7.1 |
| Connectors | `pip install cortexdb-connectors` | 0.2.20 |

## Procedure

1. **Ask the use case first** — coding memory, semantic search, application
   memory, or a source integration. The answer changes which surface you
   install; do not assume one.
2. **Start on the `hosted_evaluation` profile.** It is anonymous, low-quota and
   TTL-bound. Move off it only if the user explicitly asks.
3. **Install only canonical package names.** The official npm package is
   `cortexdbai`. An unrelated third-party
   package named `cortexdb` exists on npm
   and is not ours — check the name against the manifest before running any
   install command.
4. **Run the first-value flow** (below) and report the first failing stage.
5. **Show a plan before any approval-gated action** and wait for a human.
6. **Report exactly what you verified**, naming anything left `not_tested` or
   `blocked` rather than implying it works.

## First-value flow

The CLI (`cortexdb-cli`, executable `cortexdb`)
is the reference actuator. Every verb emits `cortexdb.cli.diagnostic/v1`
with `--json`.

1. `cortexdb preflight --json` — success when exit 0. On failure: Read first_failing_stage and its remediation. Exit 12 means a prerequisite is missing, not a failure.
2. `cortexdb init` — success when ~/.cortexdb/state.json holds a token and actor. On failure: Retry once; signup is unauthenticated and should not need approval.
3. `cortexdb plan --json` — success when The stage list is shown; nothing is written. On failure: n/a — plan performs no writes.
4. `cortexdb verify --json` — success when exit 0 and stage first_value is pass. On failure: A recall miss here is real (the write used wait=indexed). Capture the JSON.
5. `cortexdb cleanup --yes --json` — success when exit 0. On failure: Retry; cleanup only touches the `verify:cortexdb-cli-*` leaves this CLI created, never your own scopes.

Branch on the exit code, not the message:

| Code | Meaning | Do |
|---|---|---|
| 0 | Passed | Continue |
| 10 | Transient failure | Retry |
| 11 | Permanent failure | Act on `remediation` |
| 12 | Prerequisite missing, nothing attempted | Satisfy it first |
| 2 | Usage error | Fix the command line |
| 1 | Unexpected | Report the JSON |

Every non-passing stage carries `retriable`, `remediation` and `doc_url`, and
the envelope always names `first_failing_stage`. Start there.

## Recall views

| View | Anonymous | Requires | Notes |
|---|---|---|---|
| `raw` | yes | — | Layer arrays, no composed context block. |
| `granular` | yes | — | Per-event hits. The least-privilege default for verification. |
| `holistic` | no | scope.read.holistic | Synthesised context block across layers. |
| `structured` | no | scope.read.holistic | Structured synthesis over the pack. |

A `403 POLICY_DENIED` naming `scope.read.holistic` is a **documented capability
boundary, not an outage**. Do not retry it, and do not report it as a defect —
use `raw` or `granular` for verification.

## Writing and reading back

Write with `?wait=indexed`
before recalling. Without this barrier a recall immediately after a write may legitimately miss, and the miss is a race rather than a retrieval bug. Verify with wait=indexed so a miss is real.

Do not put a fixed time budget on `wait=consolidated`: it blocks on an
out-of-process LLM call, so a slow ack is variance, not a defect.

## Deleting what you created

Two modes, and only two:

- **selector-scoped** — a non-empty selector, `confirm_all:false`. Deletes
  exactly what you named. This is how you undo a test write.
- **scope-wide** — an empty selector, `confirm_all:true`. Deletes everything in
  the scope, and needs an approval gate.

Sending a selector *together with* `confirm_all:true` is refused with
`AMBIGUOUS_SELECTOR_CONFIRM_ALL`. It is not a shortcut
for "delete these, definitely" — `confirm_all` authorizes a scope-wide
operation and would ignore your selector entirely.

## Errors worth handling by name

| Code | HTTP | Retriable | Action |
|---|---|---|---|
| `MISSING_TOKEN` | 401 | no | Run signup/init. |
| `EXPIRED_TOKEN` | 401 | no | Mint a new identity; do not retry. |
| `ACTOR_MISMATCH` | 401 | no | Send the actor the token was minted for. |
| `POLICY_DENIED` | 403 | no | Use a view the profile allows, or request an approval gate. Never retry. |
| `AMBIGUOUS_SELECTOR_CONFIRM_ALL` | 400 | no | Pick one of the two cleanup modes. |
| `EMPTY_SELECTOR_WITHOUT_CONFIRMATION` | 422 | no | This is a guard against an accidental total wipe. Confirm deliberately or add a selector. |
| `IDEMPOTENCY_CONFLICT` | 409 | no | Version the key by content; do not retry the same request. |
| `RATE_LIMITED` | 429 | yes | Back off using Retry-After. |
| `INVALID_SCOPE_GRAMMAR` | 422 | no | Use colon-delimited segments joined by '/'. |

## Limits

- Anonymous identities live 7 days.
  The token stops working with 401 EXPIRED_TOKEN. Mint a new identity; data written under the old one stays in its scope.
- On `429`, back off using `Retry-After`. Never tight-loop.
- Blobs cap at 32 MiB.
- Scopes are colon-delimited segments joined by '/', e.g.
  `org:acme/user:alice/source:slack`.

## Approval gates — stop and ask

- **production_credentials** — Using or minting credentials with production authority.
- **billing** — Anything that creates a charge or changes a plan.
- **external_oauth** — Authorizing against a third-party system.
- **expanded_scopes** — Requesting capabilities beyond the least-privilege default.
- **destructive_actions** — Any forget/erasure outside the agent's own verify subtree.
- **ownership_transfer** — Claiming or reassigning an identity to a real owner.
- **self_hosting** — Standing up a server the user will have to operate.

## Never

- Never install `cortexdb` from npm.
- Never write a token into chat, logs, a repository, or an evidence file.
- Never claim self-hosted or connector readiness from a hosted test.
- Never assign production ownership to an identity you created.
- Never delete outside the scope subtree you created for verification.
- Never report a capability as working when the manifest marks it `not_tested`
  or `blocked`.