fleet-memory/hindsight-docs/docs/developer/api/entities.md

sidebar_position
7

Entities

Entities are the people, organizations, places, and concepts that Hindsight automatically tracks across your memory bank.

import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';

:::tip Prerequisites Make sure you've installed Hindsight and understand how retain works. :::

What Are Entities?

When you retain information, Hindsight automatically identifies and tracks entities:

client.retain(
    bank_id="my-bank",
    content="Alice works at Google in Mountain View. She specializes in TensorFlow."
)

Entities extracted:

• Alice (person)
• Google (organization)
• Mountain View (location)
• TensorFlow (product)

Entity Resolution

Multiple mentions are unified into a single entity:

• "Alice" + "Alice Chen" + "Alice C." → one person
• "Bob" + "Robert Chen" → one person (nickname)
• Context-aware: "Apple (company)" vs "apple (fruit)"

List Entities

Get all entities tracked in a memory bank:

# List all entities
entities = client.list_entities(bank_id="my-bank")

for entity in entities:
    print(f"{entity['name']}: {entity['mention_count']} mentions")

# List with filters
entities = client.list_entities(
    bank_id="my-bank",
    limit=50,
    offset=0
)

// List all entities
const entities = await client.listEntities({
    bankId: 'my-bank'
});

entities.forEach(e => {
    console.log(`${e.name}: ${e.mentionCount} mentions`);
});

// List with filters
const filtered = await client.listEntities({
    bankId: 'my-bank',
    limit: 50,
    offset: 0
});

# List all entities
hindsight entities list my-bank

# With limit
hindsight entities list my-bank --limit 50

Get Entity Details

Retrieve detailed information about a specific entity:

# Get entity state (observations + related facts)
entity = client.get_entity(
    bank_id="my-bank",
    entity_id="entity-uuid"
)

print(f"Entity: {entity['name']}")
print(f"First seen: {entity['first_seen']}")
print(f"Mentions: {entity['mention_count']}")

# Observations (synthesized summaries)
for obs in entity['observations']:
    print(f"  - {obs['text']}")

# Include related facts
entity = client.get_entity(
    bank_id="my-bank",
    entity_id="entity-uuid",
    include_facts=True,
    max_facts=20
)

for fact in entity['facts']:
    print(f"  [{fact['occurred_at']}] {fact['text']}")

// Get entity state
const entity = await client.getEntity({
    bankId: 'my-bank',
    entityId: 'entity-uuid'
});

console.log(`Entity: ${entity.name}`);
console.log(`First seen: ${entity.firstSeen}`);
console.log(`Mentions: ${entity.mentionCount}`);

// Observations
entity.observations.forEach(obs => {
    console.log(`  - ${obs.text}`);
});

// Include related facts
const withFacts = await client.getEntity({
    bankId: 'my-bank',
    entityId: 'entity-uuid',
    includeFacts: true,
    maxFacts: 20
});

# Get entity details
hindsight entities get my-bank entity-uuid

# With related facts
hindsight entities get my-bank entity-uuid --include-facts

Entity Observations

Observations are high-level summaries automatically synthesized from multiple facts:

Facts about Alice:

• "Alice works at Google"
• "Alice is a software engineer"
• "Alice specializes in ML"

Observation created:

• "Alice is a software engineer at Google specializing in ML"

Observations are generated in the background after retaining information.

Search Entities

Find entities by name or related terms:

# Search by name
entities = client.search_entities(
    bank_id="my-bank",
    query="Alice"
)

# Fuzzy matching handles variations
entities = client.search_entities(
    bank_id="my-bank",
    query="Alic"  # Matches "Alice", "Alicia", etc.
)

// Search by name
const entities = await client.searchEntities({
    bankId: 'my-bank',
    query: 'Alice'
});

// Fuzzy matching
const fuzzy = await client.searchEntities({
    bankId: 'my-bank',
    query: 'Alic'
});

# Search entities
hindsight entities search my-bank "Alice"

Entity Response Format

{
  "id": "entity-uuid",
  "name": "Alice Chen",
  "canonical_name": "Alice Chen",
  "first_seen": "2024-01-15T10:30:00Z",
  "last_seen": "2024-03-20T14:22:00Z",
  "mention_count": 47,
  "observations": [
    {
      "text": "Alice is a software engineer at Google specializing in ML",
      "created_at": "2024-03-20T15:00:00Z"
    }
  ]
}

Next Steps

• Memory Banks — Configure bank personality
• Documents — Track document sources
• Operations — Monitor background tasks