Types

All TypeScript interfaces exported by @keyoku/memory. Core types come from @keyoku/types and are re-exported for convenience.

Core Types

Memory

The fundamental memory object stored in the engine.

id (string), entity_id (string), agent_id (string), team_id (string), visibility (string), content (string), type (string — "fact" | "preference" | "event" | "relationship" | ...), state (string — "active" | "decayed" | "archived" | "deleted"), importance (number 0.0-1.0), confidence (number 0.0-1.0), sentiment (number -1.0-1.0), tags (string[]), access_count (number), created_at (string ISO 8601), updated_at (string), last_accessed_at (string), expires_at (string | null).

SearchResult

A single search result containing the memory and its similarity scores.

memory (Memory), similarity (number — raw cosine similarity), score (number — weighted composite score).

RememberResult

Result from storing memories via natural-language content.

memories_created (number), memories_updated (number), memories_deleted (number), skipped (number).

Heartbeat Types

HeartbeatResult

Returned by heartbeatCheck(). Contains signal arrays and urgency assessment.

should_act (boolean), pending_work (Memory[]), deadlines (Memory[]), scheduled (Memory[]), decaying (Memory[]), conflicts (Array<{ memory: Memory; reason: string }>), stale_monitors (Memory[]), summary (string), priority_action (string?), action_items (string[]?), urgency ("immediate" | "soon" | "can_wait").

HeartbeatContextResult

Returned by heartbeatContext(). Extends the basic heartbeat with context and optional LLM analysis.

should_act (boolean), scheduled (Memory[]), deadlines (Memory[]), pending_work (Memory[]), conflicts (Array<{ memory: Memory; reason: string }>), relevant_memories (SearchResult[]), summary (string), analysis (HeartbeatAnalysis?), decision_reason (string?), highest_urgency_tier (string?), nudge_context (string?). Extended signals: goal_progress (GoalProgress[]?), continuity (SessionContinuity?), sentiment_trend (SentimentTrend?), relationship_alerts (RelationshipAlert[]?), knowledge_gaps (KnowledgeGap[]?), behavioral_patterns (BehavioralPattern[]?), positive_deltas (PositiveDelta[]?), graph_context (string[]?), recent_messages (string[]?). Decision metadata: in_conversation (boolean?), time_period (string?), escalation_level (number?), response_rate (number?), confluence_score (number?).

HeartbeatAnalysis

LLM-generated analysis included when analyze: true is passed to heartbeatContext().

Signal Detail Types

GoalProgress

Tracks progress toward a goal or plan.

plan (Memory), activities (Memory[]), progress (number 0.0-1.0), days_left (number), status ("on_track" | "at_risk" | "stalled" | "no_activity").

SessionContinuity

Information about session state for resumption.

last_memories (Memory[]), session_age_hours (number), was_interrupted (boolean), resume_suggestion (string).

SentimentTrend

Tracks sentiment direction over time.

recent_avg (number), previous_avg (number), direction ("improving" | "declining" | "stable"), delta (number), notable (Memory[]).

RelationshipAlert

Alert about relationship status changes.

entity_name (string), days_silent (number), related_plans (Memory[]), urgency ("info" | "attention" | "urgent").

KnowledgeGap

An unanswered question tracked by the engine.

question (string), asked_at (string ISO 8601).

BehavioralPattern

A detected behavioral pattern with confidence score.

description (string), confidence (number), day_of_week (number? — 0 = Sunday), topics (string[]).

PositiveDelta

A positive change or achievement detected.

type (string), description (string), entity_id (string?).

Memory Operation Types

SeedMemoryInput

Input shape for bulk-creating memories via seed().

content (string), type (string?), importance (number?), entity_id (string), agent_id (string?), tags (string[]?), expires_at (string?), sentiment (number?), confidence_factors (string[]?), created_at (string?).

SeedResult

Result from bulk memory creation.

created (number), ids (string[]).

UpdateTagsResult

Result from updating tags on a memory.

status (string), memory_id (string), tags (string[]).

MemoryStats

Memory statistics for a single entity.

total_memories (number), active_memories (number), by_type (Record<string, number>), by_state (Record<string, number>).

GlobalStats

System-wide memory statistics across all entities.

total_memories (number), active_memories (number), entity_count (number), by_type (Record<string, number>), by_state (Record<string, number>).

Team Types

Team

A team for shared memory scoping.

id (string), name (string), description (string), default_visibility (string), created_at (string), updated_at (string).

TeamMember

A member of a team.

team_id (string), agent_id (string), role (string), joined_at (string).

Watcher Types

WatcherStatus

Current status of the heartbeat watcher.

running (boolean), entity_ids (string[]), interval_ms (number), tick_count (number), last_tick (string?), adaptive (boolean).

WatcherTick

A single watcher tick record.

tick_number (number), timestamp (string), entity_id (string), signals_found (number), should_act (boolean), decision_reason (string), urgency (string?), interval_ms (number).

WatcherTickHistory

Collection of watcher tick records.

ticks (WatcherTick[]), total (number).

Event Types

SSEEvent

Shape of events received via subscribeEvents().

event (string), type (string?), entity_id (string?), agent_id (string?), data (unknown?), timestamp (string?). Additional fields vary by event type.

Error Types

KeyokuError

Custom error class thrown on non-2xx HTTP responses.

Extends Error. status (number — HTTP status code), path (string — API path that failed), message (string — error description).