Keyoku

Client API

Complete reference for all 35 public methods on KeyokuClient. Every method returns a Promise unless noted otherwise.

Memory Operations

remember(entityId, content, options?)

Store memories from natural-language content. The engine auto-extracts individual facts.

entityId (string) — Entity identifier. content (string) — Natural-language text to extract memories from. options.session_id (string?) — Session context. options.agent_id (string?) — Agent that created the memory. options.source (string?) — Source identifier. options.team_id (string?) — Team scope. options.visibility (string?) — Visibility level. Returns: RememberResult — { memories_created, memories_updated, memories_deleted, skipped }.

POST /remember

search(entityId, query, options?)

Semantic search over an entity's memories using HNSW vector similarity.

entityId (string) — Entity to search within. query (string) — Search query. options.limit (number?) — Max results. options.mode (string?) — Search mode. options.agent_id (string?) — Agent filter. options.team_aware (boolean?) — Include team-scoped memories. options.min_score (number?) — Minimum similarity score. Returns: SearchResult[] — each with memory, similarity, and score.

POST /search

listMemories(entityId, limit?)

List all memories for an entity.

entityId (string) — Entity identifier. limit (number?) — Max results (default: 100). Returns: Memory[].

GET /memories

getMemory(id)

Get a single memory by ID.

Returns: Memory.

GET /memory/:id

deleteMemory(id)

Delete a specific memory.

Returns: { status: string }.

DELETE /memory/:id

deleteAllMemories(entityId)

Wipe all memories for an entity.

Returns: { status: string }.

DELETE /memories

getStats(entityId)

Get memory statistics for an entity.

Returns: MemoryStats — { total_memories, active_memories, by_type, by_state }.

GET /stats

getGlobalStats()

Get system-wide memory statistics across all entities.

Returns: GlobalStats — { total_memories, active_memories, entity_count, by_type, by_state }.

GET /stats/global

seed(memories)

Bulk-create memories without LLM extraction. Useful for migrations and bootstrapping.

memories (SeedMemoryInput[]) — Array of memories to create (see Types page). Returns: SeedResult — { created: number, ids: string[] }.

POST /seed

updateTags(id, tags)

Update tags on a specific memory.

Returns: UpdateTagsResult — { status, memory_id, tags }.

PATCH /memory/:id/tags

listEntities()

List all entity IDs in the system.

Returns: string[].

GET /entities

sampleMemories(options?)

Sample random memories, optionally filtered by entity.

options.entity_id (string?) — Filter by entity. options.limit (number?) — Max results. Returns: Memory[].

GET /memories/sample

consolidate()

Trigger memory consolidation — merges duplicates, resolves conflicts, strengthens patterns.

Returns: { status: string }.

POST /consolidate

Heartbeat Operations

heartbeatCheck(entityId, options?)

Pure SQL signal scan. Checks for deadlines, decaying memories, conflicts, and scheduled items.

entityId (string) — Entity to check. options.deadline_window (string?) — Time window for deadlines (e.g. "1h"). options.decay_threshold (number?) — Decay score threshold. options.importance_floor (number?) — Minimum importance filter. options.max_results (number?) — Max results per signal category. options.agent_id (string?) — Agent filter. options.team_id (string?) — Team filter. Returns: HeartbeatResult — includes should_act, signal arrays, summary, urgency.

POST /heartbeat/check

heartbeatContext(entityId, options?)

Combined heartbeat + context retrieval in a single call.

entityId (string) — Entity to analyze. options.query (string?) — Context query for relevant memory retrieval. options.top_k (number?) — Number of relevant memories to return. options.min_score (number?) — Minimum similarity score. options.analyze (boolean?) — Enable LLM analysis. options.autonomy ("observe" | "suggest" | "act") — Autonomy level for analysis. options.in_conversation (boolean?) — Whether user is currently in conversation. options.activity_summary (string?) — Summary of recent user activity. options.agent_id (string?) — Agent filter. options.team_id (string?) — Team filter. Returns: HeartbeatContextResult — signals + relevant memories + optional analysis with recommended actions.

POST /heartbeat/context

recordHeartbeatMessage(entityId, message, options?)

Log a heartbeat message for deduplication. Prevents the engine from repeating the same nudge.

entityId (string) — Entity identifier. message (string) — Message content. options.agent_id (string?) — Agent context. options.action_id (string?) — Action context. Returns: { status: string, id: string }.

POST /heartbeat/record

Schedule Operations

createSchedule(entityId, agentId, content, cronTag)

Create a recurring reminder. Supports cron expressions and presets like daily, weekly, monthly.

entityId (string) — Entity identifier. agentId (string) — Agent scheduling the reminder. content (string) — Reminder content. cronTag (string) — Cron expression or preset tag. Returns: Memory.

POST /schedule

listSchedules(entityId, agentId?)

List active schedules, optionally filtered by agent.

Returns: Memory[].

GET /schedules

ackSchedule(memoryId)

Acknowledge a schedule — marks it as processed for the current cycle.

Returns: { status: string, memory_id: string }.

POST /schedule/ack

updateSchedule(id, cronTag, newContent?)

Update a schedule's cron expression and optionally its content.

Returns: Memory.

PATCH /schedule/:id

cancelSchedule(id)

Cancel a schedule.

Returns: { status: string, memory_id: string }.

DELETE /schedule/:id

Watcher Operations

watcherStatus()

Get current watcher status — running state, watched entities, interval, tick count.

Returns: WatcherStatus.

GET /watcher/status

watcherHistory(options?)

Retrieve watcher tick history.

options.limit (number?) — Max ticks to return. Returns: WatcherTickHistory — { ticks: WatcherTick[], total: number }.

GET /watcher/history

watcherStart(entityIds, options?)

Start the watcher on specified entities.

entityIds (string[]) — Entities to watch. options.interval_ms (number?) — Custom tick interval in milliseconds. Returns: { status: string }.

POST /watcher/start

watcherStop()

Stop the watcher.

Returns: { status: string }.

POST /watcher/stop

watcherWatch(entityId)

Add an entity to the watcher's observation list.

Returns: { status: string, entity_id: string }.

POST /watcher/watch

watcherUnwatch(entityId)

Remove an entity from the watcher's observation list.

Returns: { status: string, entity_id: string }.

POST /watcher/unwatch

Team Operations

createTeam(name, description)

Create a new team for shared memory scoping.

Returns: Team.

POST /teams

getTeam(id)

Retrieve team details.

Returns: Team.

GET /teams/:id

deleteTeam(id)

Delete a team.

Returns: { status: string }.

DELETE /teams/:id

addTeamMember(teamId, agentId)

Add an agent to a team.

Returns: { status, team_id, agent_id }.

POST /teams/:id/members

listTeamMembers(teamId)

List all members of a team.

Returns: TeamMember[].

GET /teams/:id/members

removeTeamMember(teamId, agentId)

Remove an agent from a team.

Returns: { status: string }.

DELETE /teams/:id/members/:agentId

Event Streaming

subscribeEvents(options?)

Subscribe to the server-sent events (SSE) stream. Returns an unsubscribe function immediately.

options.onEvent ((event: SSEEvent) => void) — Callback for each received event. options.onError ((error: Error) => void) — Callback for errors. options.signal (AbortSignal?) — Signal for cancellation. Returns: () => void — call to unsubscribe.

GET /events
const unsub = client.subscribeEvents({
  onEvent: (e) => console.log(e.event, e.entity_id, e.data),
  onError: (err) => console.error(err),
});

// Later...
unsub();

Health Check

health()

Check server health and active SSE client count.

Returns: { status: string, timestamp: string, sse_clients: number }.

GET /health