Entities

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

Prerequisites

Make sure you've completed the Quick Start and understand how retain works.

Why Entities Matter

Entities improve recall quality in two ways:

1. Co-occurrence tracking — When entities appear together in facts, Hindsight builds a graph of relationships. This enables graph-based recall to find indirect connections.

2. Observations — Hindsight synthesizes high-level summaries about each entity from multiple facts. Including entity observations in recall provides richer context.

Include Entities in Recall

Use include_entities=True in your recall calls to get entity observations alongside fact results. See Recall for details.

What Are Entities?

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

Python

from hindsight_client import Hindsight

client = Hindsight(base_url="http://localhost:8888")

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

Node.js

import { HindsightClient } from '@vectorize-io/hindsight-client';

const client = new HindsightClient({ baseUrl: 'http://localhost:8888' });

await client.retain('my-bank', '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:

Python

# Using the low-level API
from hindsight_client_api import ApiClient, Configuration
from hindsight_client_api.api import DefaultApi

config = Configuration(host="http://localhost:8888")
api_client = ApiClient(config)
api = DefaultApi(api_client)

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

for entity in response.items:
    print(f"{entity.canonical_name}: {entity.mention_count} mentions")

# List with pagination
response = api.list_entities(
    bank_id="my-bank",
    limit=50,
    offset=0
)

Node.js

import { sdk, createClient, createConfig } from '@vectorize-io/hindsight-client';

const apiClient = createClient(createConfig({ baseUrl: 'http://localhost:8888' }));

// List all entities
const response = await sdk.listEntities({
    client: apiClient,
    path: { bank_id: 'my-bank' }
});

for (const entity of response.data.items) {
    console.log(`${entity.canonical_name}: ${entity.mention_count} mentions`);
}

// List with pagination
const paginated = await sdk.listEntities({
    client: apiClient,
    path: { bank_id: 'my-bank' },
    query: { limit: 50, offset: 0 }
});

CLI

# 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:

Python

# Get entity details with observations
entity = api.get_entity(
    bank_id="my-bank",
    entity_id="entity-uuid"
)

print(f"Entity: {entity.canonical_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}")

Node.js

// Get entity details
const entity = await sdk.getEntity({
    client: apiClient,
    path: { bank_id: 'my-bank', entity_id: 'entity-uuid' }
});

console.log(`Entity: ${entity.data.canonical_name}`);
console.log(`First seen: ${entity.data.first_seen}`);
console.log(`Mentions: ${entity.data.mention_count}`);

// Observations
for (const obs of entity.data.observations) {
    console.log(`  - ${obs.text}`);
}

CLI

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

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.

Regenerate Observations

Force regeneration of entity observations:

Python

# Regenerate observations for an entity
api.regenerate_entity_observations(
    bank_id="my-bank",
    entity_id="entity-uuid"
)

Node.js

// Regenerate observations
await sdk.regenerateEntityObservations({
    client: apiClient,
    path: { bank_id: 'my-bank', entity_id: 'entity-uuid' }
});

Entity Response Format

{
  "id": "entity-uuid",
  "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",
      "mentioned_at": "2024-03-20T15:00:00Z"
    }
  ]
}

Next Steps

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