Core Concepts

State & Memory

Comprehensive AI agent memory and cognition capabilities.

State Features

The State service provides comprehensive AI agent memory and cognition capabilities.

Core Memory Operations

// 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);

Working Memory (Structured Variables)

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");

Variable sources: "system", "reasoning", "retrieval", "perception", "explicit"

Goals

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");

Goal priorities: "low", "medium", "high", "critical" Goal statuses: "active", "suspended", "achieved", "abandoned", "failed"

Concepts (Schema Definitions)

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();

Actions

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");

Action types: "reason", "retrieve", "learn", "ground"

Decision Cycles

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);