Entity Memory

Facts about companies, projects, and people.

The Entity Memory Store captures structured knowledge about external entities: companies, people, projects, and systems. Think of it as your agent's professional rolodex that accumulates knowledge over time.

Aspect	Value
Scope	Configurable (global, user, or custom namespace)
Persistence	Long-term
Default mode	Always
Supported modes	Always, Agentic

Basic Usage

1from kern.agent import Agent
2from kern.db.postgres import PostgresDb
3from kern.learn import LearningMachine
4from kern.models.openai import OpenAIResponses
5
6agent = Agent(
7    model=OpenAIResponses(id="gpt-5.2"),
8    db=PostgresDb(db_url="postgresql+psycopg://ai:ai@localhost:5532/ai"),
9    learning=LearningMachine(entity_memory=True),
10)
11
12# Entities are extracted automatically
13agent.print_response(
14    "Just met with Acme Corp. They're a fintech startup in SF, "
15    "50 employees. CTO is Jane Smith. They use Python and Postgres.",
16    user_id="sales@example.com",
17    session_id="session_1",
18)
19
20# Later, entity knowledge is recalled
21agent.print_response(
22    "What do we know about Acme Corp?",
23    user_id="sales@example.com",
24    session_id="session_2",
25)

Three Types of Knowledge

Facts

Timeless truths: "Uses PostgreSQL", "Headquarters in San Francisco", "50 employees"

Events

Time-bound occurrences: "Launched v2.0 on January 15", "Closed $50M Series B", "Had 4-hour outage"

Relationships

Entity connections: Jane Smith → CEO → Acme Corp, Acme Corp → competitor_of → Beta Inc

Always Mode

Entities are extracted automatically from conversations.

1from kern.learn import LearningMachine, LearningMode, EntityMemoryConfig
2
3agent = Agent(
4    model=OpenAIResponses(id="gpt-5.2"),
5    db=db,
6    learning=LearningMachine(
7        entity_memory=EntityMemoryConfig(mode=LearningMode.ALWAYS),
8    ),
9)

Tradeoff: extra LLM call per interaction.

Agentic Mode

The agent receives tools to manage entities explicitly.

1from kern.learn import LearningMachine, LearningMode, EntityMemoryConfig
2
3agent = Agent(
4    model=OpenAIResponses(id="gpt-5.2"),
5    db=db,
6    learning=LearningMachine(
7        entity_memory=EntityMemoryConfig(mode=LearningMode.AGENTIC),
8    ),
9)
10
11agent.print_response(
12    "Create an entry for Acme Corp - they're a fintech startup with 50 employees.",
13    user_id="sales@example.com",
14)

Available tools: search_entities, create_entity, update_entity, add_fact, update_fact, delete_fact, add_event, add_relationship

Data Model

Field	Description
`entity_id`	Unique identifier (e.g., "acme_corp")
`entity_type`	Category: "company", "person", "project"
`name`	Display name
`description`	Brief description
`properties`	Key-value metadata
`facts`	Timeless truths
`events`	Time-bound occurrences
`relationships`	Connections to other entities

Accessing Entity Memory

1lm = agent.get_learning_machine()
2
3# Search for entities
4entities = lm.entity_memory_store.search(
5    query="acme",
6    entity_type="company",
7    limit=10
8)
9
10for entity in entities:
11    print(f"{entity.name}: {entity.facts}")
12
13# Debug output
14lm.entity_memory_store.print(entity_id="acme_corp", entity_type="company")

Context Injection

Relevant entities are injected into the system prompt:

1<entity_memory>
2**Acme Corp** (company)
3Properties: industry: fintech, size: 50 employees
4
5Facts:
6  - Uses PostgreSQL and Redis for their data layer
7  - Headquarters in San Francisco
8
9Events:
10  - Launched v2.0 with new ML features (2025-01-15)
11  - Closed $50M Series B led by Sequoia (2024-Q3)
12
13Relationships:
14  - CEO: jane_smith
15  - competitor_of: beta_inc
16</entity_memory>

Namespaces

Control who can access entity data:

1from kern.learn import EntityMemoryConfig
2
3# Global: shared with everyone (default)
4entity_memory=EntityMemoryConfig(namespace="global")
5
6# User: private per user
7entity_memory=EntityMemoryConfig(namespace="user")
8
9# Custom: explicit grouping
10entity_memory=EntityMemoryConfig(namespace="sales_team")

Facts vs Events

Use facts for	Use events for
Tech stack	Product launches
Headquarters location	Funding rounds
Employee count	Outages or incidents
Industry/domain	Partnerships announced
Pricing model	Key meetings

Relationship Types

Common patterns for linking entities:

People: CEO, CTO, engineer_at, founder, reports_to
Companies: competitor_of, partner_of, acquired_by, subsidiary_of
Projects: uses, depends_on, integrates_with, owned_by