Quick Start

First memory in 5 minutes.

Table of contents

1. Prerequisites
2. Step 1: Create a character
   1. curl
   2. Java (RestClient)
   3. Python
   4. Response
3. Step 2: Store a memory
   1. curl
   2. Java (RestClient)
   3. Python
   4. Response
4. Step 3: Search memories
   1. curl
   2. Java (RestClient)
   3. Python
   4. Response
5. What’s next?

---

Prerequisites

• A HippoDid API key (hd_key_...) — sign up at hippodid.com
• curl, Java 17+, or Python 3.8+

---

Step 1: Create a character

A character is the memory context for one agent, user, or persona. You can have multiple characters (limit depends on tier).

curl

curl -X POST https://api.hippodid.com/v1/characters \
  -H "Authorization: Bearer hd_key_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Agent",
    "categoryPreset": "developer"
  }'

Java (RestClient)

import org.springframework.web.client.RestClient;

record CreateCharacterRequest(String name, String categoryPreset) {}
record CharacterResponse(String id, String name, String status) {}

var client = RestClient.builder()
    .baseUrl("https://api.hippodid.com")
    .defaultHeader("Authorization", "Bearer hd_key_...")
    .build();

var character = client.post()
    .uri("/v1/characters")
    .body(new CreateCharacterRequest("My Agent", "developer"))
    .retrieve()
    .body(CharacterResponse.class);

System.out.println("Character ID: " + character.id());

Python

import requests

resp = requests.post(
    "https://api.hippodid.com/v1/characters",
    headers={"Authorization": "Bearer hd_key_..."},
    json={"name": "My Agent", "categoryPreset": "developer"},
)
character = resp.json()
character_id = character["id"]
print(f"Character ID: {character_id}")

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "My Agent",
  "status": "ACTIVE",
  "categoryPreset": "developer",
  "createdAt": "2024-01-15T10:30:00Z"
}

Field	Description
id	UUID — save this, you need it for all memory operations
name	Display name for the character
status	ACTIVE or ARCHIVED
categoryPreset	Memory category layout — developer sets up skills, decisions, preferences, events, goals, relationships
createdAt	ISO-8601 timestamp (UTC)

---

Step 2: Store a memory

Memories are stored as free-text content and automatically categorized (if AI extraction is enabled on your tier).

curl

curl -X POST https://api.hippodid.com/v1/characters/550e8400-e29b-41d4-a716-446655440000/memories \
  -H "Authorization: Bearer hd_key_..." \
  -H "Content-Type: application/json" \
  -d '{
    "content": "User prefers dark mode and vim keybindings"
  }'

Java (RestClient)

record AddMemoryRequest(String content) {}
record MemoryResponse(String id, String content, String category, double salience) {}

var memory = client.post()
    .uri("/v1/characters/{id}/memories", characterId)
    .body(new AddMemoryRequest("User prefers dark mode and vim keybindings"))
    .retrieve()
    .body(MemoryResponse.class);

System.out.println("Memory ID: " + memory.id());
System.out.println("Category: " + memory.category());

Python

resp = requests.post(
    f"https://api.hippodid.com/v1/characters/{character_id}/memories",
    headers={"Authorization": "Bearer hd_key_..."},
    json={"content": "User prefers dark mode and vim keybindings"},
)
memory = resp.json()
print(f"Memory stored: {memory['id']} [{memory['category']}]")

Response

{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "content": "User prefers dark mode and vim keybindings",
  "category": "preferences",
  "salience": 0.7,
  "importance": "NORMAL",
  "createdAt": "2024-01-15T10:31:00Z"
}

Field	Description
id	UUID for this memory
content	The stored text
category	Auto-detected or manually specified category
salience	0.0–1.0 relevance score (higher = more important)
importance	CRITICAL, HIGH, NORMAL, or LOW
createdAt	When the memory was stored

On FREE tier, memories are stored as-is without AI categorization. Paid tiers get automatic category detection and semantic embedding for search.

---

Step 3: Search memories

Semantic search finds relevant memories even when the query doesn’t exactly match the stored text.

curl

curl -X POST https://api.hippodid.com/v1/characters/550e8400-e29b-41d4-a716-446655440000/memories/search \
  -H "Authorization: Bearer hd_key_..." \
  -H "Content-Type: application/json" \
  -d '{
    "query": "UI preferences",
    "limit": 5
  }'

Java (RestClient)

record SearchRequest(String query, int limit) {}
record SearchResult(List<MemoryResponse> memories, int total) {}

var results = client.post()
    .uri("/v1/characters/{id}/memories/search", characterId)
    .body(new SearchRequest("UI preferences", 5))
    .retrieve()
    .body(SearchResult.class);

results.memories().forEach(m ->
    System.out.printf("[%.2f] %s%n", m.salience(), m.content()));

Python

resp = requests.post(
    f"https://api.hippodid.com/v1/characters/{character_id}/memories/search",
    headers={"Authorization": "Bearer hd_key_..."},
    json={"query": "UI preferences", "limit": 5},
)
for m in resp.json()["memories"]:
    print(f"[{m['salience']:.2f}] {m['content']}")

Response

{
  "memories": [
    {
      "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "content": "User prefers dark mode and vim keybindings",
      "category": "preferences",
      "salience": 0.92,
      "importance": "NORMAL",
      "createdAt": "2024-01-15T10:31:00Z"
    }
  ],
  "total": 1
}

Field	Description
memories	List of matched memories, sorted by relevance descending
salience	Relevance score for this search query (0.0–1.0)
total	Total number of matching memories (before limit)

---

What’s next?

• MCP clients: Set up Claude Desktop, Cursor, or OpenClaw →
• File sync: Use the sync_file MCP tool to keep markdown files in sync automatically
• Import existing docs: import_document ingests .md and .txt files and extracts memories
• BYOK AI: Configure your own AI provider key →
• Full API: See all endpoints →