# CortexDB Agent Skill

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

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.11.0` | 0.11.0 |
| Python SDK | `pip install cortexdbai` | 0.12.0 |
| TypeScript SDK | `npm install cortexdbai` | 0.10.1 |
| CLI | `pip install cortexdb-cli` | 0.6.0 |
| MCP server | `pip install cortexdb-mcp` | 0.8.0 |
| Connectors | `pip install cortexdb-connectors` | 0.2.22 |

## 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`.

**Before you install:** every published Python artifact requires
`>=3.10`. Check the interpreter first; a
resolution error is a worse first experience than being told.

**State lives in `~/.cortexdb`.** Override it
with `--config-dir` or
`CORTEXDB_HOME`.
Controls config.toml, state.json, history and onboarding checkpoints. --profile selects config VALUES only and does NOT isolate identity; use this for a separate brain. The resolved directory is reported as config_dir in every diagnostic envelope.

**Identity is not a retry.** init reuses an existing identity and changes nothing. It refuses to remint over one (including an expired one) without --force, because a new identity is a new brain and memories under the old actor stay where they are.

**Wiring a harness:** `cortexdb wire --harness=<harness>` — supported:
`agents`, `claude-code`, `copilot`, `cursor`, `cursor-legacy`, `windsurf`.
Writes the standing-rule file at the path that harness actually reads and registers the MCP server where applicable. --dry-run shows the change first.

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 state.json in the config directory holds a token and actor. Re-running init on a directory that already has one REUSES it and changes nothing. On failure: Do NOT re-run init hoping for a different result, and never pass --force to get past an error: a new identity is a new brain, and memories written under the old actor stay where they are. If a config already exists, reuse it. If the token has expired, stop and request explicit human approval to reset or rotate. For a genuinely separate brain, use --config-dir / CORTEXDB_HOME instead.
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 | Stop and request human approval to reset or rotate. Do NOT auto-mint: a new identity is a new brain and the old data stays under the old actor. |
| `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. |
| `NOT_A_MEMBER` | 403 | no | Ask a scope owner to grant Writer-or-higher membership. Do not retry unchanged. |
| `SCOPE_REGISTRATION_REQUIRED` | 403 | no | Register the standalone scope and delegate membership, enable an authorized parent child policy, or use the caller's owned scope. |
| `UNREGISTERED_SCOPE_TYPE` | 422 | no | Use an allowed scope type or ask an operator to add the intended custom type; do not retry unchanged. |
| `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. |
| `AUTHORIZATION_STATE_CHANGED` | 409 | yes | Wait Retry-After (1 s), then re-send the identical request, with the same idempotency_key if it had one. |
| `WAIT_TIMEOUT` | 408 | yes | Poll details.status_url (or each id in details.event_ids for a bulk). Resend only with the same idempotency_key: a capture sent without one is written again. |
| `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`.