The State service provides comprehensive AI agent memory and cognition capabilities.
// Focus - Store in short-term working memory (Flux)
await client.state.focus("Current task context");
// Drift - Read current working memory items
const driftItems = await client.state.drift();
// Commit - Store in long-term episodic memory (Echoes)
await client.state.commit("User asked about weather", "Provided forecast", {
action: "weather_lookup",
agent_id: "assistant",
});
// Reminisce - Recall relevant memories
const memories = await client.state.reminisce("weather questions", 5);
# Focus - Store in short-term working memory (Flux)
client.state.focus("Current task context")
# Drift - Read current working memory items
drift_items = client.state.drift()
# Commit - Store in long-term episodic memory (Echoes)
client.state.commit(
"User asked about weather",
"Provided forecast",
action="weather_lookup",
agent_id="assistant"
)
# Reminisce - Recall relevant memories
memories = client.state.reminisce("weather questions", 5)
Store and manage structured state for your agent's reasoning process.
// Set a variable (supports any JSON-serializable value)
await client.state.setVariable("user_name", "Alice", "explicit");
await client.state.setVariable(
"session_context",
{
task: "code review",
language: "TypeScript",
},
"system",
);
// Get a variable
const userVar = await client.state.getVariable("user_name");
console.log(userVar.value); // "Alice"
// List all variables
const allVars = await client.state.listVariables();
// Delete a variable
await client.state.deleteVariable("user_name");
# Set a variable (supports any JSON-serializable value)
client.state.set_variable("user_name", "Alice", "explicit")
client.state.set_variable(
"session_context",
{
"task": "code review",
"language": "Python",
},
"system",
)
# Get a variable
user_var = client.state.get_variable("user_name")
print(user_var.value) # "Alice"
# List all variables
all_vars = client.state.list_variables()
# Delete a variable
client.state.delete_variable("user_name")
Variable sources: "system", "reasoning", "retrieval", "perception", "explicit"
Manage hierarchical goals for goal-directed agent behavior.
// Add a goal
const mainGoal = await client.state.addGoal("Complete project", "high");
// Add a sub-goal (with parent)
const subGoal = await client.state.addGoal(
"Review authentication module",
"medium",
mainGoal.id,
);
// List goals (optionally filter by status)
const allGoals = await client.state.listGoals();
const activeGoals = await client.state.listGoals("active");
// Update goal status
await client.state.updateGoal(subGoal.id, "achieved");
# Add a goal
main_goal = client.state.add_goal("Complete project", "high")
# Add a sub-goal (with parent)
sub_goal = client.state.add_goal(
"Review authentication module",
"medium",
parent_id=main_goal.id,
)
# List goals (optionally filter by status)
all_goals = client.state.list_goals()
active_goals = client.state.list_goals("active")
# Update goal status
client.state.update_goal(sub_goal.id, "achieved")
Goal priorities: "low", "medium", "high", "critical"
Goal statuses: "active", "suspended", "achieved", "abandoned", "failed"
Define structured concepts for Level 4 agency and semantic understanding.
// Define a concept with JSON Schema
await client.state.defineConcept("Task", {
type: "object",
properties: {
id: { type: "string" },
title: { type: "string" },
status: { type: "string", enum: ["pending", "in_progress", "completed"] },
priority: { type: "number", minimum: 1, maximum: 5 },
},
required: ["id", "title", "status"],
});
// List defined concepts
const concepts = await client.state.listConcepts();
# Define a concept with JSON Schema
client.state.define_concept("Task", {
"type": "object",
"properties": {
"id": {"type": "string"},
"title": {"type": "string"},
"status": {"type": "string", "enum": ["pending", "in_progress", "completed"]},
"priority": {"type": "number", "minimum": 1, "maximum": 5}
},
"required": ["id", "title", "status"],
})
# List defined concepts
concepts = client.state.list_concepts()
Log and track agent actions for auditing and learning.
// Submit an action
const result = await client.state.submitAction("agent-1", "reason", {
thought: "Analyzing the code structure",
conclusion: "Start with main entry point",
});
// Get action log
const actionLog = await client.state.getActionLog(100);
// Filter by action type
const reasonActions = await client.state.getActionLog(50, "reason");
# Submit an action
result = client.state.submit_action("agent-1", "reason", {
"thought": "Analyzing the code structure",
"conclusion": "Start with main entry point",
})
# Get action log
action_log = client.state.get_action_log(100)
# Filter by action type
reason_actions = client.state.get_action_log(50, "reason")
Action types: "reason", "retrieve", "learn", "ground"
Run autonomous decision cycles with scored action candidates.
// Run a decision cycle with candidates
const cycleResult = await client.state.runCycle("agent-1", [
{
actionType: "reason",
action: { thought: "Should analyze data first" },
score: 0.8,
rationale: "Data analysis is foundational",
},
{
actionType: "retrieve",
action: { query: "relevant documentation" },
score: 0.6,
rationale: "Documentation might help",
},
]);
console.log(cycleResult.selectedAction);
console.log(cycleResult.planningTimeMs);
// Get cycle history
const history = await client.state.getCycleHistory(10);
# Run a decision cycle with candidates
cycle_result = client.state.run_cycle("agent-1", [
{
"actionType": "reason",
"action": {"thought": "Should analyze data first"},
"score": 0.8,
"rationale": "Data analysis is foundational",
},
{
"actionType": "retrieve",
"action": {"query": "relevant documentation"},
"score": 0.6,
"rationale": "Documentation might help",
},
])
print(cycle_result.selected_action)
print(cycle_result.planning_time_ms)
# Get cycle history
history = client.state.get_cycle_history(10)