Cognitive API

The Cognitive API gives you access to extracted beliefs, learnings, and the user profile. These are automatically derived from memories - you don't need to create them manually.

How It Works

When you add a memory, Cortex automatically:

Extracts Beliefs - Stable facts about preferences, opinions, and characteristics
Discovers Learnings - Patterns and insights from multiple memories
Builds Profile - A continuously updated summary of who the user is

This happens asynchronously. After adding a memory, these will appear within a few seconds.

Beliefs

Beliefs are stable facts extracted from memories. They represent what Cortex "believes" about the user.

List Beliefs

const beliefs = await cortex.beliefs.list();
 
for (const belief of beliefs) {
  console.log(belief.content);     // "User prefers React over Angular"
  console.log(belief.confidence);  // 0.85
  console.log(belief.category);    // "preference"
}

Response

{
  "beliefs": [
    {
      "id": "belief_abc123",
      "content": "User prefers React over Angular for frontend development",
      "category": "preference",
      "confidence": 0.85,
      "sourceMemoryIds": ["mem_1", "mem_2", "mem_3"],
      "validFrom": "2024-01-15T10:00:00Z",
      "validTo": null,
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ],
  "total": 15
}

Belief Categories

Category	Description	Example
`preference`	User likes/dislikes	"Prefers dark mode"
`characteristic`	Personal traits	"Detail-oriented"
`opinion`	Views and stances	"Thinks AI will transform healthcare"
`knowledge`	What they know	"Expert in distributed systems"
`behavior`	How they act	"Usually responds to emails in the morning"

Filter Beliefs

// Get only preference beliefs
const preferences = await cortex.beliefs.list({
  category: "preference"
});
 
// Get high-confidence beliefs
const confident = await cortex.beliefs.list({
  minConfidence: 0.8
});

Learnings

Learnings are insights discovered from patterns across multiple memories. They're higher-level than beliefs - more like "aha" moments.

List Learnings

const learnings = await cortex.learnings.list();
 
for (const learning of learnings) {
  console.log(learning.content);
  console.log(learning.source);  // How it was discovered
}

Response

{
  "learnings": [
    {
      "id": "learn_xyz789",
      "content": "User tends to overcommit on project timelines",
      "source": "pattern_analysis",
      "confidence": 0.72,
      "supportingMemoryCount": 8,
      "createdAt": "2024-01-20T14:00:00Z"
    }
  ],
  "total": 7
}

Learning Sources

Source	Description
`pattern_analysis`	Discovered from repeated patterns
`consolidation`	Emerged during memory consolidation
`contradiction_resolution`	Resolved from conflicting information
`explicit`	User explicitly stated something

Profile

The profile is a continuously updated summary of the user. It's regenerated as new memories are added.

Get Profile

const profile = await cortex.profile.get();
 
console.log(profile.summary);
console.log(profile.traits);
console.log(profile.interests);

Response

{
  "summary": "Senior product manager with 8+ years of experience. Focused on mobile-first development and user research. Based in San Francisco. Works closely with Sarah (engineering lead) and Mike (design lead).",
  "traits": [
    "detail-oriented",
    "data-driven",
    "collaborative"
  ],
  "interests": [
    "mobile development",
    "user research",
    "product analytics"
  ],
  "communication_style": "concise, bullet-points preferred",
  "lastUpdated": "2024-01-22T09:00:00Z"
}

Commitments

Commitments are promises, tasks, or obligations extracted from memories. Cortex tracks them with due dates and status.

List Commitments

// Get pending commitments
const pending = await cortex.commitments.list({
  status: "pending"
});
 
// Get overdue commitments
const overdue = await cortex.commitments.list({
  status: "overdue"
});

Response

{
  "commitments": [
    {
      "id": "commit_abc",
      "title": "Send Q4 roadmap to Sarah",
      "description": "Draft roadmap document and share for review",
      "status": "pending",
      "dueDate": "2024-01-25T17:00:00Z",
      "relatedEntityId": "ent_sarah",
      "sourceMemoryId": "mem_meeting",
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ],
  "total": 3
}

Commitment Status

Status	Description
`pending`	Not yet completed
`completed`	Marked as done
`overdue`	Past due date and not completed
`cancelled`	No longer relevant

Update Commitment

await cortex.commitments.update("commit_abc", {
  status: "completed"
});

Using Cognitive Data in AI Prompts

Here's how to use cognitive data to build better AI interactions:

const context = await cortex.recall({
  query: userMessage,
  includeProfile: true,
  includeBeliefs: true
});
 
const systemPrompt = `
You are helping ${context.profile.summary}
 
Key beliefs about this user:
${context.beliefs.map(b => `- ${b.content}`).join('\n')}
 
Relevant context:
${context.memories.map(m => m.content).join('\n\n')}
`;
 
const response = await openai.chat.completions.create({
  model: "gpt-4",
  messages: [
    { role: "system", content: systemPrompt },
    { role: "user", content: userMessage }
  ]
});

This creates AI interactions that truly understand the user.

Memories Entities & Knowledge Graph