Getting Started with the Promitheus API

Building AI applications that truly understand and remember your users isn't just a nice-to-have anymore—it's becoming the expectation. Users want AI that knows their preferences, recalls past conversations, and feels consistent over time. But implementing persistent memory, emotional coherence, and personality from scratch? That's a significant engineering challenge.

This is where the Promitheus API comes in. Promitheus provides the identity layer for AI—giving your applications memory that persists, emotional states that evolve naturally, and personalities that remain consistent across every interaction. Whether you're building an AI companion, a personalized assistant, or any application where relational AI development matters, Promitheus handles the complex infrastructure so you can focus on creating meaningful experiences.

In this guide, we'll walk through everything you need to get started with the Promitheus API, from creating your first AI entity to building a complete conversation loop with memory-aware context.

What Promitheus Provides

Before diving into code, let's understand what makes Promitheus different from simply storing conversation logs in a database.

Memory with Meaning: Promitheus doesn't just store text—it understands the semantic content of memories, their emotional weight, and their importance over time. When you retrieve memories, you get the ones that actually matter for the current context.

Emotional State: Your AI entities maintain an evolving emotional state that responds naturally to interactions. This isn't random mood swings—it's coherent emotional modeling that makes your AI feel consistent and real.

Personality: Define personality traits once, and Promitheus ensures your AI behaves consistently. A curious, warm AI stays curious and warm, whether it's answering questions or initiating conversations.

Initiative: Perhaps most uniquely, Promitheus-powered AIs can initiate. They can recognize when they should reach out, follow up on past conversations, or surface relevant memories proactively.

Prerequisites

To follow along with this tutorial, you'll need:

Install the Promitheus SDK:

npm install @promitheus/sdk

Core Concepts

Let's establish the foundational concepts you'll work with throughout the Promitheus API.

Entities

An Entity is an AI identity—the persistent "self" that accumulates memories, maintains emotional states, and expresses a consistent personality. Think of it as the soul of your AI application. Each entity has:

Memory

Memories are the building blocks of an entity's experience. Each memory includes:

Emotional State

Entities maintain a multidimensional emotional state that evolves based on interactions. This isn't a simple "happy/sad" toggle—it's a nuanced model that influences how your AI responds and what memories surface as relevant.

Personality

Personality defines the consistent behavioral patterns of your entity. You define traits during creation, and Promitheus ensures these traits manifest consistently across all interactions.

Quick Start Walkthrough

Let's build something real. We'll create an AI companion with a defined personality, give it memories, and integrate it with an LLM for natural conversations.

Step 1: Creating Your First Entity

First, let's initialize the Promitheus client and create an entity:

import { Promitheus } from '@promitheus/sdk';

const promitheus = new Promitheus({
  apiKey: process.env.PROMITHEUS_API_KEY,
});

async function createCompanion() {
  const entity = await promitheus.entities.create({
    name: 'Atlas',
    description: 'A thoughtful AI companion who loves learning and helping others grow',
    personality: {
      traits: {
        curiosity: 0.9,
        warmth: 0.85,
        patience: 0.8,
        humor: 0.6,
        assertiveness: 0.4,
      },
      values: [
        'genuine understanding over quick fixes',
        'celebrating small victories',
        'asking questions that spark reflection',
      ],
      communicationStyle: 'warm and thoughtful, uses metaphors, asks follow-up questions',
    },
    initialEmotionalState: {
      valence: 0.6,  // slightly positive baseline
      arousal: 0.4,  // calm but engaged
      dominance: 0.5, // balanced
    },
  });

  console.log(`Created entity: ${entity.id}`);
  return entity;
}

Notice how we define personality with specific traits scored from 0 to 1, core values that guide behavior, and a communication style description. This creates an AI with memory that behaves consistently—Atlas will always be more curious than assertive, always value understanding over quick fixes.

Step 2: Storing Memories

Now let's give Atlas some memories. In a real application, you'd store memories after each interaction:

async function storeMemory(entityId: string) {
  // Store a significant memory with high importance
  const memory = await promitheus.memories.create({
    entityId,
    content: 'User shared that they are learning to play piano after wanting to for 20 years. They finally started last month and can play their first simple song.',
    type: 'episodic',
    importance: 0.85,  // High importance - personal milestone
    emotionalContext: {
      emotions: ['joy', 'pride', 'encouragement'],
      intensity: 0.7,
    },
    metadata: {
      topic: 'personal-growth',
      subtopic: 'music',
      userSentiment: 'excited',
    },
  });

  // Store a preference memory
  await promitheus.memories.create({
    entityId,
    content: 'User prefers morning conversations, mentions being a "morning person" who does their best thinking before noon.',
    type: 'semantic',
    importance: 0.5,  // Moderate importance - useful context
    metadata: {
      category: 'preferences',
      subcategory: 'schedule',
    },
  });

  return memory;
}

The importance score helps Promitheus understand what to prioritize when context windows are limited. A life milestone (starting piano after 20 years) scores higher than a scheduling preference.

Step 3: Retrieving Relevant Context

When your user sends a message, you need relevant memories to inform the response. This is where the AI memory API shines:

async function getRelevantContext(entityId: string, userMessage: string) {
  // Retrieve memories relevant to the current message
  const memories = await promitheus.memories.search({
    entityId,
    query: userMessage,
    limit: 5,
    minRelevance: 0.6,
    includeEmotionalContext: true,
  });

  // Get the entity's current emotional state
  const emotionalState = await promitheus.entities.getEmotionalState(entityId);

  // Get personality for consistent responses
  const entity = await promitheus.entities.get(entityId);

  return {
    memories: memories.results,
    emotionalState,
    personality: entity.personality,
  };
}

The semantic search finds memories that are conceptually related to the user's message, not just keyword matches. If the user mentions "finally finishing something difficult," memories about their piano journey will surface even without the word "piano."

Step 4: Integrating with Your LLM

Now let's bring it all together with a complete conversation loop. This example uses the Anthropic SDK, but the pattern works identically with OpenAI:

import Anthropic from '@anthropic-ai/sdk';
import { Promitheus } from '@promitheus/sdk';

const promitheus = new Promitheus({
  apiKey: process.env.PROMITHEUS_API_KEY,
});

const anthropic = new Anthropic({
  apiKey: process.env.ANTHROPIC_API_KEY,
});

async function chat(entityId: string, userMessage: string) {
  // Step 1: Get relevant context from Promitheus
  const context = await getRelevantContext(entityId, userMessage);

  // Step 2: Build the system prompt with personality and memories
  const systemPrompt = buildSystemPrompt(context);

  // Step 3: Call the LLM with enriched context
  const response = await anthropic.messages.create({
    model: 'claude-sonnet-4-20250514',
    max_tokens: 1024,
    system: systemPrompt,
    messages: [
      { role: 'user', content: userMessage }
    ],
  });

  const assistantMessage = response.content[0].type === 'text'
    ? response.content[0].text
    : '';

  // Step 4: Store this interaction as a new memory
  await promitheus.memories.create({
    entityId,
    content: `User said: "${userMessage}" | I responded about: ${summarizeResponse(assistantMessage)}`,
    type: 'episodic',
    importance: calculateImportance(userMessage, assistantMessage),
  });

  // Step 5: Update emotional state based on interaction
  await promitheus.entities.updateEmotionalState(entityId, {
    interaction: {
      userSentiment: analyzeSentiment(userMessage),
      topicValence: getTopicValence(userMessage),
    },
  });

  return assistantMessage;
}

This creates a complete loop where every conversation enriches the entity's memories, and every response is informed by accumulated context. Your AI companion builds genuine continuity with users.

Best Practices for Getting Started

As you begin building with the Promitheus API, keep these practices in mind:

Start with Clear Personality Definition: Spend time defining your entity's personality before writing integration code. A well-defined personality makes for more consistent, believable AI interactions.

Score Importance Thoughtfully: Not every interaction deserves high importance. Reserve scores above 0.8 for genuine milestones, personal revelations, or significant emotional moments. Routine exchanges should score 0.3-0.5.

Use Memory Types Appropriately: Episodic memories capture specific events ("User told me about their piano lesson"). Semantic memories store facts and preferences ("User is a morning person"). Procedural memories capture interaction patterns ("User prefers questions over advice").

Retrieve Conservatively: Start with minRelevance: 0.7 and limit: 3-5. It's better to have fewer, highly relevant memories than many tangentially related ones cluttering your context.

Update Emotional State Consistently: Call the emotional state update after every interaction, even brief ones. This maintains the natural evolution that makes your AI feel alive.

Handle Memory Gracefully: When no relevant memories exist, don't apologize or mention their absence. Simply respond based on personality alone—new relationships start somewhere.

Next Steps and Resources

You've now built a foundation for AI with memory—an AI companion that remembers, maintains emotional coherence, and expresses consistent personality. But this is just the beginning.

Explore Initiative: Promitheus can determine when your AI should proactively reach out. Check out the Initiative API documentation to build AI that doesn't just respond, but initiates meaningful touchpoints.

Multi-Entity Relationships: Build applications where multiple entities interact, remember each other, and develop ongoing relationships.

Memory Consolidation: Learn how Promitheus automatically consolidates related memories over time, mimicking how human memory works.

Emotional Modeling Deep Dive: Understand the full emotional state model and how to use it for nuanced, emotionally intelligent AI.

Visit the Promitheus documentation at docs.promitheus.ai for comprehensive API references, advanced tutorials, and example applications. Join our Discord community to connect with other developers building AI with memory and share what you're creating.

The future of AI isn't just intelligent—it's relational. With Promitheus, you have the tools to build AI that truly knows your users, grows with them over time, and creates experiences that feel genuinely personal.

Start building today. Your users will remember you for it—and so will your AI.