{
  "schema": "cortexdb.agent-manifest/v1",
  "manifest_version": "1.0.0",
  "generated_at": "2026-08-22T08:43:31+00:00",
  "freshness": {
    "max_age_seconds": 3600,
    "stale_behavior": "refetch_then_fail_closed",
    "revalidate_url": "https://cortexdb.ai/agent/manifest.json"
  },
  "source_of_truth": {
    "release_manifest_digest": "sha256:cbb6e8faa43ec6d4cd63c6ef77dfb82160b6bd8511856c2de33899e683a565b9",
    "generator": "scripts/agent_manifest.py",
    "repository": "https://github.com/pmalik/cortexdb"
  },
  "routing": {
    "human": "/agent",
    "manifest": "/agent/manifest.json",
    "skill": "/agent/SKILL.md",
    "support": "/docs/sdks/cli",
    "discovery": [
      "/agent",
      "/agent/manifest.json",
      "/llms.txt",
      "/.well-known/llms.txt"
    ]
  },
  "endpoints": {
    "api_base": "https://api-v1.cortexdb.ai",
    "health": {
      "method": "GET",
      "path": "/v1/admin/health",
      "auth": false,
      "note": "Liveness ONLY. Returns 200 while the process is up even with unreadable storage or mock providers (audit H-13) \u2014 never gate traffic on it."
    },
    "ready": {
      "method": "GET",
      "path": "/v1/admin/ready",
      "auth": false,
      "note": "Readiness. 503 with the SAME body shape when a required check fails. `degraded:true` means the corpus is pinned to MOCK embeddings \u2014 recall quality is not representative."
    },
    "openapi": {
      "method": "GET",
      "path": "/v1/openapi.json",
      "auth": false
    },
    "signup": {
      "method": "POST",
      "path": "/v1/auth/signup",
      "auth": false,
      "note": "Empty body is accepted."
    },
    "whoami": {
      "method": "GET",
      "path": "/v1/auth/whoami",
      "auth": true,
      "note": "Returns EFFECTIVE capabilities after the policy stack. The cheapest way to tell an expired token (401) from an under-privileged one (403)."
    },
    "write": {
      "method": "POST",
      "path": "/v1/experience",
      "auth": true
    },
    "recall": {
      "method": "POST",
      "path": "/v1/recall",
      "auth": true
    },
    "forget": {
      "method": "POST",
      "path": "/v1/forget",
      "auth": true
    }
  },
  "release_profile": {
    "server": {
      "version": "0.9.6",
      "image": "cortexdb/cortexdb",
      "tag": "v0.9.6",
      "digests": {
        "note": "Pin the VERSIONED tag. `latest` is a moving pointer, so a digest resolved through it is not a reproducible release identity. Verify with `docker buildx imagetools inspect cortexdb/cortexdb:v0.9.6`."
      }
    },
    "artifacts": [
      {
        "id": "sdk-python",
        "package": "cortexdbai",
        "registry": "pypi",
        "published_version": "0.11.0",
        "repo_version": "0.11.0",
        "health": {
          "state": "ok"
        },
        "install": "pip install cortexdbai",
        "digests": {
          "files": [
            {
              "filename": "cortexdbai-0.11.0-py3-none-any.whl",
              "packagetype": "bdist_wheel",
              "sha256": "7b0ab813935dc508da313ff28ea95000844d69aa9380e3e8cecb7b132f7db34a"
            },
            {
              "filename": "cortexdbai-0.11.0.tar.gz",
              "packagetype": "sdist",
              "sha256": "97c9452433100476679b72b18d211691c482282db2db5a58bc57ee11a84b361e"
            }
          ]
        }
      },
      {
        "id": "sdk-typescript",
        "package": "cortexdbai",
        "registry": "npm",
        "published_version": "0.9.1",
        "repo_version": "0.9.1",
        "health": {
          "state": "ok"
        },
        "install": "npm install cortexdbai",
        "digests": {
          "integrity": "sha512-p3bFhBNC6jjl4uqPozojM/I2eO6dioCh/DJ6WgptyQmi0/8SJShVpmLGm4zFPef77slDr6IbNUegNvEUoD6AYw==",
          "shasum": "9247dbc4757e90952706148b5ae484dafe92b417"
        }
      },
      {
        "id": "cli",
        "package": "cortexdb-cli",
        "registry": "pypi",
        "published_version": "0.5.0",
        "repo_version": "0.5.0",
        "health": {
          "state": "ok"
        },
        "install": "pip install cortexdb-cli",
        "digests": {
          "files": [
            {
              "filename": "cortexdb_cli-0.5.0-py3-none-any.whl",
              "packagetype": "bdist_wheel",
              "sha256": "eb5fe82cc98d48a579fd0ec7634d3bb7f92156bfeb3d0db150eb4b65cd10e3fc"
            },
            {
              "filename": "cortexdb_cli-0.5.0.tar.gz",
              "packagetype": "sdist",
              "sha256": "938ff281bc48d93be0d82fc7375edb56b64016520ef772ef26316f9a530a7614"
            }
          ]
        }
      },
      {
        "id": "mcp",
        "package": "cortexdb-mcp",
        "registry": "pypi",
        "published_version": "0.7.1",
        "repo_version": "0.7.1",
        "health": {
          "state": "ok"
        },
        "install": "pip install cortexdb-mcp",
        "digests": {
          "files": [
            {
              "filename": "cortexdb_mcp-0.7.1-py3-none-any.whl",
              "packagetype": "bdist_wheel",
              "sha256": "00ed0b1ee456e68e268d8640532121b6d40ed947da69f86d798c2162be50292b"
            },
            {
              "filename": "cortexdb_mcp-0.7.1.tar.gz",
              "packagetype": "sdist",
              "sha256": "f7834fa4b8febf3301c82fa68780d17242edfe3e68635bbfbd7962fdeb01a5ce"
            }
          ]
        }
      },
      {
        "id": "connectors",
        "package": "cortexdb-connectors",
        "registry": "pypi",
        "published_version": "0.2.20",
        "repo_version": "0.2.20",
        "health": {
          "state": "ok"
        },
        "install": "pip install cortexdb-connectors",
        "digests": {
          "files": [
            {
              "filename": "cortexdb_connectors-0.2.20-py3-none-any.whl",
              "packagetype": "bdist_wheel",
              "sha256": "61ab3c2df1349b5249861f0054df747c883ae2f073ad465fd212a40634e68937"
            },
            {
              "filename": "cortexdb_connectors-0.2.20.tar.gz",
              "packagetype": "sdist",
              "sha256": "487328da53743190dcff3fcf2a4a373e427e13d836d773fb922ccdfcc9057cc9"
            }
          ]
        }
      }
    ]
  },
  "package_identity": {
    "npm": {
      "official": "cortexdbai",
      "not_ours": [
        "cortexdb"
      ],
      "install": "npm install cortexdbai"
    },
    "pypi": {
      "official": [
        "cortexdbai",
        "cortexdb-cli",
        "cortexdb-mcp",
        "cortexdb-connectors"
      ],
      "not_ours": []
    },
    "docker": {
      "official": "cortexdb/cortexdb"
    }
  },
  "profiles": {
    "hosted_evaluation": {
      "state": "tested",
      "default": true,
      "requires_human_approval": false,
      "description": "Anonymous, low-quota, TTL-bound identity from /v1/auth/signup. The correct starting point for every agent-driven install."
    },
    "hosted_production": {
      "state": "not_tested",
      "requires_human_approval": true,
      "description": "Production authority, billing and ownership. An agent must never assign this to an identity it created itself.",
      "reason": "No clean-agent matrix has been run against a frozen hosted profile.",
      "tracking": "KAN-145, KAN-148"
    },
    "self_hosted": {
      "state": "blocked",
      "requires_human_approval": true,
      "description": "Operator-run server from the published image.",
      "reason": "No isolated Docker execution environment has been restored since Phase 0.",
      "tracking": "KAN-150"
    },
    "connectors": {
      "state": "not_tested",
      "requires_human_approval": true,
      "description": "Third-party source sync. Each connector carries its own readiness verdict; hosted results say nothing about them.",
      "reason": "Per-connector readiness verdicts do not exist yet.",
      "tracking": "KAN-150"
    }
  },
  "recall_views": [
    {
      "view": "raw",
      "requires_capability": null,
      "available_to_anonymous": true,
      "description": "Layer arrays, no composed context block.",
      "on_denied": "n/a"
    },
    {
      "view": "granular",
      "requires_capability": null,
      "available_to_anonymous": true,
      "description": "Per-event hits. The least-privilege default for verification.",
      "on_denied": "n/a"
    },
    {
      "view": "holistic",
      "requires_capability": "scope.read.holistic",
      "available_to_anonymous": false,
      "description": "Synthesised context block across layers.",
      "on_denied": "403 POLICY_DENIED naming scope.read.holistic. This is a documented capability boundary, NOT a recall outage \u2014 do not report it as a failure, and do not retry it."
    },
    {
      "view": "structured",
      "requires_capability": "scope.read.holistic",
      "available_to_anonymous": false,
      "description": "Structured synthesis over the pack.",
      "on_denied": "Same as holistic."
    }
  ],
  "write_semantics": {
    "wait_levels": [
      {
        "value": "captured",
        "returns_when": "Durable at WAL append; indexing continues in the background.",
        "bounded": true,
        "typical_latency": "~10ms, flat in payload size"
      },
      {
        "value": "indexed",
        "returns_when": "BM25 + HNSW insert confirmed; recall can see it.",
        "bounded": true,
        "typical_latency": "~100-500ms"
      },
      {
        "value": "consolidated",
        "returns_when": "Beliefs/Understanding touched.",
        "bounded": false,
        "typical_latency": "provider-bound, typically ~0.5-6s",
        "warning": "Blocks on an out-of-process LLM call. Do NOT set a fixed SLO on it or treat a slow ack as a defect (KAN-29). The server's own ceiling is a 30s wait budget."
      }
    ],
    "read_your_writes": {
      "required_wait": "indexed",
      "why": "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."
    },
    "idempotency": {
      "header_or_field": "idempotency_key (envelope field)",
      "max_length": 64,
      "conflict_behavior": "Reusing a key with a DIFFERENT body returns 409 IDEMPOTENCY_CONFLICT and is not retriable. Version the key when the content can change."
    }
  },
  "cleanup": {
    "modes": [
      {
        "id": "selector_scoped",
        "selector": "non-empty",
        "confirm_all": false,
        "deletes": "Exactly the selected memories. The default for undoing a test write."
      },
      {
        "id": "scope_wide",
        "selector": "empty",
        "confirm_all": true,
        "deletes": "Everything in the scope. Requires an approval gate."
      }
    ],
    "forbidden_combination": {
      "description": "A non-empty selector together with confirm_all:true is REFUSED, not resolved. confirm_all authorizes a scope-wide operation and would otherwise silently widen 'delete these ids' into 'delete everything'.",
      "error_code": "AMBIGUOUS_SELECTOR_CONFIRM_ALL"
    }
  },
  "actuator": {
    "package": "cortexdb-cli",
    "executable": "cortexdb",
    "diagnostic_schema": "cortexdb.cli.diagnostic/v1",
    "verbs": [
      "apply",
      "cleanup",
      "doctor",
      "plan",
      "preflight",
      "resume",
      "status",
      "verify"
    ],
    "exit_codes": {
      "ok": 0,
      "error": 1,
      "usage": 2,
      "retriable": 10,
      "failed": 11,
      "blocked": 12
    }
  },
  "first_value_flow": [
    {
      "step": "preflight",
      "command": "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."
    },
    {
      "step": "identity",
      "command": "cortexdb init",
      "success_when": "~/.cortexdb/state.json holds a token and actor",
      "on_failure": "Retry once; signup is unauthenticated and should not need approval."
    },
    {
      "step": "plan",
      "command": "cortexdb plan --json",
      "success_when": "The stage list is shown; nothing is written",
      "on_failure": "n/a \u2014 plan performs no writes."
    },
    {
      "step": "verify",
      "command": "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."
    },
    {
      "step": "cleanup",
      "command": "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."
    }
  ],
  "approval_gates": [
    {
      "id": "production_credentials",
      "description": "Using or minting credentials with production authority."
    },
    {
      "id": "billing",
      "description": "Anything that creates a charge or changes a plan."
    },
    {
      "id": "external_oauth",
      "description": "Authorizing against a third-party system."
    },
    {
      "id": "expanded_scopes",
      "description": "Requesting capabilities beyond the least-privilege default."
    },
    {
      "id": "destructive_actions",
      "description": "Any forget/erasure outside the agent's own verify subtree."
    },
    {
      "id": "ownership_transfer",
      "description": "Claiming or reassigning an identity to a real owner."
    },
    {
      "id": "self_hosting",
      "description": "Standing up a server the user will have to operate."
    }
  ],
  "error_contract": [
    {
      "error_code": "MISSING_TOKEN",
      "http": 401,
      "retriable": false,
      "meaning": "No credential presented.",
      "action": "Run signup/init."
    },
    {
      "error_code": "EXPIRED_TOKEN",
      "http": 401,
      "retriable": false,
      "meaning": "The identity's TTL elapsed.",
      "action": "Mint a new identity; do not retry."
    },
    {
      "error_code": "ACTOR_MISMATCH",
      "http": 401,
      "retriable": false,
      "meaning": "The X-Cortex-Actor header disagrees with the token subject.",
      "action": "Send the actor the token was minted for."
    },
    {
      "error_code": "POLICY_DENIED",
      "http": 403,
      "retriable": false,
      "meaning": "Valid token, insufficient capability.",
      "action": "Use a view the profile allows, or request an approval gate. Never retry."
    },
    {
      "error_code": "AMBIGUOUS_SELECTOR_CONFIRM_ALL",
      "http": 400,
      "retriable": false,
      "meaning": "A selector was combined with scope-wide confirmation.",
      "action": "Pick one of the two cleanup modes."
    },
    {
      "error_code": "EMPTY_SELECTOR_WITHOUT_CONFIRMATION",
      "http": 422,
      "retriable": false,
      "meaning": "A scope-wide delete was requested without confirmation.",
      "action": "This is a guard against an accidental total wipe. Confirm deliberately or add a selector."
    },
    {
      "error_code": "IDEMPOTENCY_CONFLICT",
      "http": 409,
      "retriable": false,
      "meaning": "The key was reused with a different body.",
      "action": "Version the key by content; do not retry the same request."
    },
    {
      "error_code": "RATE_LIMITED",
      "http": 429,
      "retriable": true,
      "meaning": "Quota exceeded for this identity.",
      "action": "Back off using Retry-After."
    },
    {
      "error_code": "INVALID_SCOPE_GRAMMAR",
      "http": 422,
      "retriable": false,
      "meaning": "The scope string is not a valid path.",
      "action": "Use colon-delimited segments joined by '/'."
    }
  ],
  "limits": {
    "anonymous_identity_ttl_seconds": 604800,
    "on_expiry": "The token stops working with 401 EXPIRED_TOKEN. Mint a new identity; data written under the old one stays in its scope.",
    "rate_limit": {
      "status": 429,
      "honor_header": "Retry-After",
      "strategy": "Exponential backoff bounded by Retry-After; never tight-loop."
    },
    "blob_max_bytes": 33554432,
    "scope_grammar": {
      "form": "colon-delimited segments joined by '/'",
      "example": "org:acme/user:alice/source:slack",
      "note": "A bare actor id such as `user:alice` is a valid scope. This is an SDK-side validation contract as well as a server one \u2014 a malformed scope fails before the request is sent."
    }
  },
  "evidence": {
    "openapi_route_drift": {
      "state": "tested",
      "gate": ".github/workflows/ci.yml :: openapi-route-drift"
    },
    "mcp_clean_install": {
      "state": "tested",
      "gate": ".github/workflows/ci.yml :: mcp-clean-install"
    },
    "connector_unit_suites": {
      "state": "tested",
      "gate": "connectors/tests"
    },
    "sdk_python_suite": {
      "state": "tested",
      "gate": "sdks/python/tests"
    },
    "sdk_typescript_suite": {
      "state": "tested",
      "gate": "sdks/typescript/tests"
    },
    "hosted_golden_path": {
      "state": "not_tested",
      "reason": "No clean-agent matrix has been run against a frozen hosted profile (KAN-148/KAN-156)."
    },
    "cli_onboarding_contracts": {
      "state": "tested",
      "gate": "cli/tests/test_onboarding.py",
      "note": "Clean run, rerun/idempotence, interruption+resume, cleanup, and the side-effect-free help/version contract are pinned. Not yet exercised against a live hosted target by a clean agent -- that is KAN-148/KAN-156."
    },
    "agent_entry_point": {
      "state": "blocked",
      "reason": "/agent, /agent/manifest.json, /agent/SKILL.md and /llms.txt are unpublished; they live in the frontend repo (KAN-143/153/154, DISC-031)."
    },
    "google_workspace_e2e": {
      "state": "blocked",
      "reason": "No synthetic tenant credentials (KAN-150)."
    },
    "local_docker_profile": {
      "state": "blocked",
      "reason": "No isolated Docker execution environment restored since Phase 0 (KAN-150)."
    }
  }
}