Memory Types

Engram implements four cognitive memory types modelled on human memory science.

Engram organises memories into four distinct types. Each type has different storage characteristics, confidence priors, and retrieval behaviour.

The four types

Semantic

Facts, preferences, decisions, constraints.

Semantic memories are the most common type. They represent things the agent knows about the user or world — stable beliefs that persist across sessions.

client.memories.store(
    agent_id=agent.id,
    content="User prefers concise, bullet-point responses over long prose",
    type="preference",  # preference is a sub-type of semantic
)

client.memories.store(
    agent_id=agent.id,
    content="User's billing address is 42 Market St, San Francisco",
    type="fact",
)

Confidence prior: 0.88 for explicit statements, 0.60 for inferences, 0.45 for behavioural signals.

Decay: Slow. Semantic memories decay only when contradicted or left unreinforced for extended periods.

Episodic

Raw experiences with outcome tracking.

Episodic memories capture what happened — conversations, interactions, events. They are linked to outcomes (success, failure, neutral) and are the raw material from which semantic beliefs are derived.

client.episodes.create(
    agent_id=agent.id,
    content="User asked for a Python refactor, approved the PR, merged it same day",
    outcome="success",
    emotion="positive",
)

Confidence prior: 0.75. Episodic memories reflect observed events, not verified facts.

Consolidation: Repeated successful episodes consolidate into semantic memories via the consolidation pipeline.

Procedural

Learned skills and trigger-action patterns.

Procedural memories capture how to do things — patterns the agent has learned work well for this user.

client.procedures.learn(
    agent_id=agent.id,
    content="When user asks about system design: always draw ASCII architecture diagram first",
)

Confidence prior: 0.70. Procedural memories start lower and build confidence through repeated successful application.

Trigger matching: Procedural memories surface when a recall query matches their trigger pattern, even if the semantic similarity to the query content is low.

Schema

Higher-order mental models.

Schema memories are automatically derived by the consolidation pipeline when clusters of related semantic memories reach sufficient density and consistency.

They represent the agent’s model of the user — archetypes like “experienced backend engineer who values efficiency” rather than individual facts.

# Schemas are auto-generated — you don't create them manually
# Access them via:
schemas = client.schemas.list(agent_id=agent.id)

Confidence: Inherited from the cluster of memories that generated them.

Use: Schema memories provide the broadest context in recall — they surface when no specific memory matches but a general model of the user is relevant.

Memory tiers

Every memory sits in one of four tiers based on its current confidence score:

Tier	Confidence	Behaviour
Hot	> 0.85	Injected into every prompt via context injection API
Warm	0.70 – 0.85	Returned on relevant recall queries
Cold	0.40 – 0.70	Returned only on high-relevance queries
Archive	< 0.40	Soft-deleted; recoverable but not retrieved by default

# Get tier distribution
stats = client.agents.get_tier_stats(agent_id=agent.id)
print(f"Hot: {stats.hot}, Warm: {stats.warm}, Cold: {stats.cold}, Archive: {stats.archive}")

# Get hot memories for prompt injection
hot = client.agents.get_hot_memories(agent_id=agent.id)

Evidence types

When you store a memory without an explicit confidence, Engram assigns an initial confidence based on the evidence type:

Evidence Type	Initial Confidence	Example
explicit_statement	0.88	”I prefer dark mode” (user directly stated)
implicit_inference	0.60	Inferred from usage patterns
behavioral_signal	0.45	Detected from indirect signals

client.memories.store(
    agent_id=agent.id,
    content="User appears to prefer async communication over calls",
    source="implicit_inference",  # pass evidence type via source
)