hot.dev/hot-ai / ::ai::memory

Functions

EmbeddingOptions alias

Alias of ::store/EmbeddingOptions

Identity alias

Alias of ::session/Identity

Message alias

Alias of ::ai::message/Message

Role alias

Alias of ::ai::message/Role

Session alias

Alias of ::session/Session

candidate-edge

fn (from: Str, relation: Str, to: Str, provenance: Vec, opts: Map?): MemoryEdge

Build a graph edge candidate with provenance and confidence.

candidate-node

fn (kind: Str, label: Str, provenance: Vec, opts: Map?): MemoryNode

Build a graph node candidate with provenance and confidence.

capsule-from-window

fn (id: Str, summary: Str, entries: Vec, opts: Map?): MemoryCapsule

Build a MemoryCapsule from a summary and source store entries.

capsule-key

fn (id: Str): Str

Return the KB key used for a memory capsule.

citation-from-result

fn (result: Map): Citation

Build a normalized Citation from a search/list result.

create-memory

fn (agent-name: Str, session: ::ai::session/Session, identity: ::ai::session/Identity): AgentMemory

Build an AgentMemory with all three scoped stores.

create-memory-with-options

fn (agent-name: Str, session: ::ai::session/Session, identity: ::ai::session/Identity, opts: MemoryOptions?): AgentMemory

Build an AgentMemory, optionally overriding session/KB embedding configuration.

delete-entries

fn (store: ::hot::store/Map, entries: Vec): Int

Delete store entries and return the count deleted.

entry-record

fn (entry: Map, kind: Str): MemoryRecord

Convert a store entry to a stable MemoryRecord export shape.

export-memory

fn (mem: AgentMemory): MemoryExport
fn (mem: AgentMemory, t: Thread?): MemoryExport

Export session, user, and KB records for this memory scope.

extract-graph-candidates

fn (structured: Map, provenance: Vec): Map

Convert structured extraction output into graph node/edge candidates. Expected shape: {nodes: [{kind,label,...}], edges: [{from,relation,to,...}]}.

forget-by-source-id

fn (mem: AgentMemory, source-id: Str): Int

Delete session memory entries with matching key, metadata.source_id, or metadata.message_id.

forget-kb-key

fn (mem: AgentMemory, key: Str): Bool

Delete one key from the shared KB.

forget-session

fn (mem: AgentMemory): Bool

Clear all entries in session memory.

forget-session-range

fn (mem: AgentMemory, start-ts: Int, end-ts: Int): Int

Delete session memory entries whose timestamp is within the inclusive range.

forget-session-where

fn (mem: AgentMemory, predicate: Fn): Int

Delete session memory entries matching a predicate (key, value) -> Bool.

forget-user-key

fn (mem: AgentMemory, key: Str): Bool

Delete one key from user memory.

get-capsule

fn (mem: AgentMemory, id: Str): Any

Load a stored MemoryCapsule by id.

get-user-data

fn (mem: AgentMemory, key: Str): Any

Read a value from the user's persistent store.

graph-edge-key

fn (id: Str): Str

Return the KB key used for a graph edge.

graph-expand

fn (mem: AgentMemory, seed-node-ids: Vec): Map

Expand seed node ids into neighboring graph edges and citations.

graph-node-key

fn (id: Str): Str

Return the KB key used for a graph node.

hybrid-recall

fn (mem: AgentMemory, query: Str, opts: Map?): Map

Hybrid retrieval: vector recall over raw/capsule/graph text plus graph expansion from explicit seed node ids.

learn

fn (mem: AgentMemory, key: Str, content: Map): Any

Add an entry to the shared knowledge base. Auto-embedded for search.

list-capsules

fn (mem: AgentMemory): Vec

List all memory capsule KB entries.

list-edges

fn (mem: AgentMemory): Vec

List all graph-RAG edges in this memory scope.

list-kb-records

fn (mem: AgentMemory): Vec

Export KB entries as MemoryRecord values.

list-nodes

fn (mem: AgentMemory): Vec

List all graph-RAG nodes in this memory scope.

list-session-records

fn (mem: AgentMemory): Vec

Export session memory entries as MemoryRecord values.

list-user-records

fn (mem: AgentMemory): Vec

Export user-profile entries as MemoryRecord values.

memory-provenance

fn (entry: Map, kind: Str): MemoryProvenance

Build provenance for a store entry returned by ::hot::store/list, filter, or search.

neighbor-edges

fn (mem: AgentMemory, node-id: Str): Vec

Find graph edges touching a node id.

ns alias

Alias of ::ai::memory/

Session-scoped agent memory with three storage levels: session (shared conversation history), user (per-user persistent data), and KB (shared domain knowledge).

recall

fn (mem: AgentMemory, query: Str, opts: Map?): Vec

Semantic search over session memory. Options: limit (default 10), min-score (default 0.5).

recall-with-capsules

fn (mem: AgentMemory, query: Str, opts: Map?): Map

Retrieve raw session memory plus compacted capsules for a query.

recent

fn (mem: AgentMemory, opts: Map?): Vec

Retrieve recent messages from session memory. Options: hours (default 24), limit (default 100).

remember

fn (mem: AgentMemory, message: ::ai::message/Message): Any

Store a Message in session memory. Auto-generates a time-based key.

search-kb

fn (mem: AgentMemory, query: Str, opts: Map?): Vec

Semantic search over the shared knowledge base. Options: limit (default 5).

set-user-data

fn (mem: AgentMemory, key: Str, value: Any): Any

Write a value to the user's persistent store.

store-capsule

fn (mem: AgentMemory, capsule: MemoryCapsule): Any

Persist a MemoryCapsule in the KB store with provenance and embedding-friendly content.

store-edge

fn (mem: AgentMemory, edge: MemoryEdge): Any

Persist a graph-RAG edge in the KB store.

store-graph-candidates

fn (mem: AgentMemory, candidates: Map): Map

Persist graph node and edge candidates into memory stores.

store-node

fn (mem: AgentMemory, node: MemoryNode): Any

Persist a graph-RAG node in the KB store.

thread

fn (agent-name: Str, session: ::ai::session/Session, identity: ::ai::session/Identity, opts: Map?): Thread

Create or get a per-(session, user) thread store for multi-turn interactions. Options: max-turns (default 20).

The thread is scoped to (session, identity) so the same user in a different session has an independent thread. Pass the same session you used to build AgentMemory so memory and thread stay aligned.

thread-add

fn (t: Thread, role: ::ai::message/Role, content: Str): Any

Append a message to a conversation thread.

thread-clear

fn (t: Thread): Bool

Reset a conversation thread.

thread-history

fn (t: Thread, opts: Map?): Vec

Get the recent thread history as ChatMessages. Options: limit (default all).

Types

AgentMemory

AgentMemory type {
    agent-name: Str,
    session-store: ::hot::store/Map,
    user-store: ::hot::store/Map,
    kb-store: ::hot::store/Map
}

Bundles three scoped stores for an agent + session + identity combination.

Citation

Citation type {
    id: Str,
    label: Str?,
    excerpt: Str?,
    score: Dec?,
    provenance: MemoryProvenance?
}

Normalized citation returned by retrieval and graph expansion.

MemoryCapsule

MemoryCapsule type {
    id: Str,
    summary: Str,
    start-ts: Int?,
    end-ts: Int?,
    source-ids: Vec,
    facts: Vec?,
    decisions: Vec?,
    tasks: Vec?,
    open-questions: Vec?,
    provenance: Vec?,
    metadata: Map?
}

Durable compacted summary of a source memory window.

MemoryDecision

MemoryDecision type {
    id: Str,
    decision: Str,
    owner: Str?,
    rationale: Str?,
    decided-at: Int?,
    confidence: Dec?,
    provenance: Vec?,
    metadata: Map?
}

Structured decision extracted from team or personal memory.

MemoryEdge

MemoryEdge type {
    id: Str,
    from: Str,
    to: Str,
    relation: Str,
    weight: Dec?,
    confidence: Dec?,
    provenance: Vec?,
    metadata: Map?
}

Graph-RAG edge persisted in a memory graph.

MemoryExport

MemoryExport type {
    agent-name: Str,
    session: Vec,
    user: Vec,
    kb: Vec,
    thread: Vec?,
    metadata: Map?
}

Portable export bundle for an AgentMemory scope.

MemoryFact

MemoryFact type {
    id: Str,
    subject: Str,
    predicate: Str,
    object: Str,
    confidence: Dec?,
    provenance: Vec?,
    metadata: Map?
}

Structured long-term fact extracted from raw memory or a capsule.

MemoryNode

MemoryNode type {
    id: Str,
    kind: Str,
    label: Str,
    summary: Str?,
    confidence: Dec?,
    provenance: Vec?,
    metadata: Map?
}

Graph-RAG node persisted in a memory graph.

MemoryOptions

MemoryOptions type {
    embedding: ::hot::store/::hot::store/EmbeddingOptions?,
    session-embedding: ::hot::store/::hot::store/EmbeddingOptions?,
    kb-embedding: ::hot::store/::hot::store/EmbeddingOptions?
}

Optional store configuration for create-memory-with-options.

embedding is the default for session and KB memory stores. session-embedding and kb-embedding override that default for their specific stores. Pass ::hot::store/EmbeddingOptions.Default for system defaults, ::hot::store/EmbeddingOptions.Off to disable, or ::hot::store/Embedding({...}) for Hot-level providers.

MemoryProvenance

MemoryProvenance type {
    source: Str?,
    source-id: Str?,
    session-id: Str?,
    user-id: Str?,
    message-id: Str?,
    key: Str?,
    timestamp: Int?,
    score: Dec?,
    metadata: Map?
}

Evidence pointer for remembered, compacted, or graph-extracted memory.

MemoryRecord

MemoryRecord type {
    id: Str,
    kind: Str,
    content: Str?,
    timestamp: Int?,
    metadata: Map?,
    provenance: MemoryProvenance?
}

Stable export shape for one memory store entry.

MemoryTask

MemoryTask type {
    id: Str,
    title: Str,
    owner: Str?,
    due-at: Int?,
    status: Str?,
    confidence: Dec?,
    provenance: Vec?,
    metadata: Map?
}

Structured task or commitment extracted from memory.

Thread

Thread type {
    store: ::hot::store/Map,
    turn-limit: Int
}

A per-user conversation thread for multi-turn interactions.