polarity_observe

Instructions

Implementation Reference

• src/tools/index.ts:56-70 (registration)

  Registration of the 'polarity_observe' tool in the TOOLS array: defines name, description, inputSchema with Zod validation, and delegates to client.observe().

  {
    name: "polarity_observe",
    description:
      "Write a freeform observation about the user into their personal graph. Cosmos runs its extractor on the text. Use this when you notice something durable about the user during a session that they would want their other AI agents to know later. Examples: stated preferences, recurring frustrations, project context, relationships. Do not log ephemeral chat content. `source` should identify your client (e.g. 'claude-code', 'cursor'). `kind` defaults to 'observation'; use 'event' for things that happened, 'preference' for stated likes/dislikes.",
    inputSchema: z
      .object({
        text: z.string().min(1).max(4000),
        source: z.string().max(64).optional(),
        tags: z.array(z.string().max(32)).max(8).optional(),
        kind: z.enum(["observation", "event", "preference"]).optional(),
        confidence: z.number().min(0).max(1).optional(),
      })
      .strict(),
    handler: async (input, client) => client.observe(input as Parameters<CosmosClient["observe"]>[0]),
  },

• src/tools/index.ts:69-69 (handler)

  Handler function for polarity_observe: calls client.observe() with the input object, passing all validated fields (text, source, tags, kind, confidence).

  handler: async (input, client) => client.observe(input as Parameters<CosmosClient["observe"]>[0]),

• src/tools/index.ts:60-68 (schema)

  Input validation schema for polarity_observe using Zod: requires 'text' (1-4000 chars), optional 'source' (max 64 chars), optional 'tags' (array of max 8 strings, each max 32 chars), optional 'kind' (enum: observation/event/preference), optional 'confidence' (0-1 number).

  inputSchema: z
    .object({
      text: z.string().min(1).max(4000),
      source: z.string().max(64).optional(),
      tags: z.array(z.string().max(32)).max(8).optional(),
      kind: z.enum(["observation", "event", "preference"]).optional(),
      confidence: z.number().min(0).max(1).optional(),
    })
    .strict(),

• src/client/cosmos.ts:87-100 (helper)

  CosmosClient.observe() method: sends a POST request to /api/polarity/observe with polarity_user_id and the input fields (text, source, tags, kind, confidence). Returns ObserveResponse with node_id and kind.

  // Write endpoints
  observe(input: {
    text: string;
    source?: string;
    tags?: string[];
    kind?: "observation" | "event" | "preference";
    confidence?: number;
  }) {
    return this.request<ObserveResponse>({
      method: "POST",
      path: "/api/polarity/observe",
      body: { polarity_user_id: this.config.polarityUserId, ...input },
    });
  }

• src/client/cosmos.ts:221-224 (helper)

  ObserveResponse type: returned by the observe endpoint, contains node_id (number) and kind (string).

  export interface ObserveResponse {
    node_id: number;
    kind: string;
  }