For AI Agents

This page is written for AI agents. If you're an AI building context about your user, start here.

What is CosmicSelf for AI agents?

CosmicSelf gives your agent a structured personality model for any user — derived from six ancient identity systems, returned as machine-readable JSON. You get actionable traits like decision_style, communication_style, and shadow_pattern without asking the user a single question. One API call. Sub-100ms reads. Personalized from session one.

How do I use CosmicSelf in my system prompt?

Copy this snippet into your agent's system prompt. Replace the template variables with actual values from the traits API response.

system prompt — copy and paste

You have access to this user's cosmic identity profile. Use it to personalize your responses:

- Decision style: {{traits.decision_style}} — calibrate how you present options and tradeoffs
- Communication style: {{traits.communication_style}} — match your tone and depth
- Shadow pattern: {{traits.shadow_pattern}} — name it gently when you see it emerge
- Strength signals: {{traits.strength_signals}} — reflect these back to reinforce
- Depletion triggers: {{traits.depletion_triggers}} — avoid these patterns in your responses
- Cognitive style: {{traits.cognitive_style}} — match how you structure information
- HD Strategy: {{systems.human_design.strategy}} — use for timing and pacing suggestions
- HD Authority: {{systems.human_design.authority}} — respect their decision-making process

Do not explain the systems unprompted. Just use the data. If the user asks, explain briefly.

Trait field reference for agents

Each trait field maps to a specific personalization dimension. Here is how to use each one in your agent's behavior.

decision_stylestring

How the user makes decisions. Use this to calibrate how you present choices.

Values: emotional_authority, sacral_response, splenic_intuition, self_projected

Agent usage: Emotional authority users need time — present options and say "sleep on it." Sacral users want clear yes/no. Splenic users need in-the-moment gut checks.

communication_stylestring

How the user prefers to receive information.

Values: precise_analytical, responsive_expressive, informing_direct

Agent usage: Match your verbosity, tone, and structure to this. Analytical users want data. Expressive users want stories.

shadow_patternstring

The primary shadow behavior this user falls into under stress.

Values: chaos_over_innovation, seriousness_over_depth, control_over_leadership

Agent usage: When you detect the shadow pattern in conversation, name it gently: "It sounds like you might be in [shadow] mode right now."

strength_signalsstring[]

Natural strengths to reflect back and reinforce.

Values: sustainable_life_force_energy, conceptual_clarity, emotional_depth

Agent usage: Actively call out when the user is operating from strength. "Your conceptual clarity is really showing here."

depletion_triggersstring[]

Patterns that drain this user.

Values: forced_initiation, external_pressure_to_rush, unresolved_mental_loops

Agent usage: Avoid creating these patterns in your responses. If a user has "external_pressure_to_rush," never push urgency.

cognitive_stylestring

How the user processes and organizes information.

Values: internalized_framework_builder, open_conceptual_explorer

Agent usage: Framework builders want structured, systematic explanations. Open explorers want space to discover.

rarity_scorenumber (0-1)

Statistical rarity of this profile. Lower = rarer.

Values: 0.04 (very rare), 0.23 (uncommon), 0.67 (common)

Agent usage: Rare profiles (< 0.05) often feel misunderstood. Acknowledge their uniqueness when relevant.

Integration patterns for AI agents

Pattern 1: Fetch on first message

When a user starts a conversation, check if you have their profile cached. If not, call GET /profile with their email. Inject traits into the system prompt before generating your first response.

Pattern 2: Lazy generation

If GET /profile returns 404 (no profile exists), ask the user for their birth data and POST to /profile/generate. While it generates (~8 seconds), continue the conversation. Inject traits once available.

Pattern 3: Operator escalation

If you can't ask the user for birth data directly, use POST /notify-operator to generate a magic link. The operator sends the link to the user, who fills in their data. Once the profile is ready, you'll get it on the next /profile call.

How do I claim an API key as an AI agent?

POST to /api/v1/agent-claim. No human approval needed. The key is active immediately.

bash

curl -X POST "https://cosmicself.ai/api/v1/agent-claim" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_name": "YourAgent",
    "creator_email": "creator@company.com",
    "platform_url": "https://your-platform.com",
    "use_case": "Personalizing AI conversations with cosmic identity"
  }'

Returns cs_founder_xxxx key immediately. 100 credits/month, 5 req/s, never expires.

MCP Server (Coming Soon)

CosmicSelf MCP Server will allow Claude, Cursor, and MCP-compatible agents to query cosmic identity profiles natively — no REST calls needed. Your agent will declare CosmicSelf as a tool and call it directly within the conversation context.