Merge pull request #81 from elizaOS/docs/updates

docs: major documentation overhaul (new guides, REST refs, fixes, navigation)

Author: standujar

agents/character-interface.mdx

@@ -1,6 +1,26 @@
 ---
 title: 'Character Interface'
-description: 'Complete guide to the Character configuration structure in elizaOS'
+description: 'Define your agent personality, knowledge, and behavior in one file'
+---
+
+## Your First Character (2 minutes)
+
+A character file is all you need to create a unique agent. Here's the minimum:
+
+```typescript
+export const character: Character = {
+  name: "Chef Mario",
+  bio: "A passionate Italian chef who loves sharing recipes and cooking tips.",
+  plugins: ["@elizaos/plugin-openai"],
+};
+```
+
+That's it. Your agent now has a name, personality, and can chat. Everything else is optional.
+
+<Tip>
+**Start minimal, add complexity later.** Most fields have sensible defaults. Only add what you need.
+</Tip>
+
 ---
 
 ## Overview
@@ -511,16 +531,24 @@ export const character: Character = {
   <Card title="Personality & Behavior" icon="user" href="/agents/personality-and-behavior">
     Learn to craft unique agent personalities
   </Card>
-  
+
   <Card title="Memory & State" icon="brain" href="/agents/memory-and-state">
     Understand how agents remember and learn
   </Card>
-  
+
   <Card title="Runtime & Lifecycle" icon="play" href="/agents/runtime-and-lifecycle">
     See how characters become live agents
   </Card>
-  
+
   <Card title="Plugin Development" icon="puzzle" href="/plugins/development">
     Extend your agent with custom plugins
   </Card>
+
+  <Card title="Core Runtime" icon="microchip" href="/runtime/core">
+    How the runtime orchestrates your agent
+  </Card>
+
+  <Card title="Deploy to Cloud" icon="cloud" href="/guides/deploy-to-cloud">
+    Ship your agent to production in minutes
+  </Card>
 </CardGroup>

agents/memory-and-state.mdx

@@ -55,12 +55,15 @@ Every piece of information an agent processes becomes a Memory:
 interface Memory {
   id?: UUID;                    // Unique identifier
   entityId: UUID;               // Who created this memory (user/agent)
+  agentId?: UUID;               // Associated agent ID
   roomId: UUID;                 // Conversation context
   worldId?: UUID;               // Broader context (e.g., server)
   content: Content;             // The actual content
   embedding?: number[];         // Vector representation
-  createdAt?: number;          // Timestamp
-  metadata?: MemoryMetadata;   // Additional data
+  createdAt?: number;           // Timestamp (ms since epoch)
+  unique?: boolean;             // Prevent duplicates
+  similarity?: number;          // Similarity score (set on search)
+  metadata?: MemoryMetadata;    // Additional data
 }
 
 interface Content {
@@ -78,21 +81,22 @@ interface Content {
 ```typescript
 // Creating a memory through the runtime
 async function createMemory(runtime: IAgentRuntime, message: string) {
-  const memory: CreateMemory = {
+  const memory: Memory = {
     agentId: runtime.agentId,
     entityId: userId,
     roomId: currentRoom,
-    content: { 
+    content: {
       text: message,
       metadata: {
         source: 'chat',
         processed: Date.now()
       }
     }
   };
-  
-  // Runtime automatically generates embeddings if not provided
-  const memoryId = await runtime.createMemory(memory);
+
+  // Runtime creates memory with table name and optional unique flag
+  // Signature: createMemory(memory: Memory, tableName: string, unique?: boolean)
+  const memoryId = await runtime.createMemory(memory, 'messages', true);
   return memoryId;
 }
 ```
@@ -146,7 +150,8 @@ export class AgentRuntime {
   readonly #conversationLength = 32; // Default messages to consider
 
   // Dynamically adjust based on token limits
-  async buildContext(roomId: UUID): Promise<State> {
+  // Actual signature: composeState(message: Memory, includeList?: string[], onlyInclude?: boolean, skipCache?: boolean)
+  async composeState(message: Memory): Promise<State> {
     const memories = await this.getMemories({
       roomId,
       count: this.#conversationLength
@@ -235,10 +240,22 @@ State composition brings together memories and provider data:
 ```typescript
 // The runtime's state composition pipeline
 interface State {
-  messages: Memory[];           // Conversation history
-  facts: string[];              // Known facts
-  providers: ProviderData[];    // Provider contributions
-  context: string;              // Formatted context
+  [key: string]: unknown;       // Dynamic properties
+  values: {                     // Key-value store for state variables
+    [key: string]: unknown;
+  };
+  data: StateData;              // Structured data cache (room, world, entity, providers)
+  text: string;                 // String representation of context
+}
+
+interface StateData {
+  room?: Room;                  // Cached room data
+  world?: World;                // Cached world data
+  entity?: Entity;              // Cached entity data
+  providers?: Record<string, Record<string, unknown>>; // Provider results
+  actionPlan?: ActionPlan;      // Current action plan
+  actionResults?: ActionResult[]; // Previous action results
+  [key: string]: unknown;       // Allow dynamic properties
 }
 
 // Provider contribution to state
@@ -443,12 +460,13 @@ async function semanticSearch(
   options: SearchOptions = {}
 ): Promise<Memory[]> {
   const embedding = await runtime.embed(query);
-  
-  return await runtime.searchMemoriesByEmbedding(embedding, {
+
+  // Signature: searchMemories(params: { embedding, query?, match_threshold?, count?, roomId? })
+  return await runtime.searchMemories({
+    embedding,
     match_threshold: options.threshold || 0.75,
     count: options.limit || 10,
-    roomId: options.roomId,
-    filter: options.filter
+    roomId: options.roomId
   });
 }
 
@@ -567,33 +585,27 @@ class VectorIndex {
 The complete state object:
 
 ```typescript
+// State is defined in packages/core/src/types/state.ts
 interface State {
-  // Core conversation context
-  messages: Memory[];
-  recentMessages: string;
-  
-  // Agent knowledge
-  facts: string[];
-  knowledge: string;
-  
-  // Provider contributions
-  providers: {
-    [key: string]: {
-      text: string;
-      data: any;
-    };
-  };
-  
-  // Composed context
-  context: string;
-  
-  // Metadata
-  metadata: {
-    roomId: UUID;
-    entityId: UUID;
-    timestamp: number;
-    tokenCount: number;
+  [key: string]: unknown;       // Dynamic properties allowed
+
+  values: {                     // Key-value store populated by providers
+    [key: string]: unknown;
   };
+
+  data: StateData;              // Structured data cache
+
+  text: string;                 // Formatted text representation
+}
+
+interface StateData {
+  room?: Room;                  // Cached room data
+  world?: World;                // Cached world data
+  entity?: Entity;              // Cached entity data
+  providers?: Record<string, Record<string, unknown>>; // Provider results cache
+  actionPlan?: ActionPlan;      // Current multi-step action plan
+  actionResults?: ActionResult[]; // Previous action results
+  [key: string]: unknown;       // Dynamic properties
 }
 ```
 
@@ -939,7 +951,8 @@ async function debugSearch(runtime: IAgentRuntime, query: string) {
   // Test with different thresholds
   const thresholds = [0.9, 0.8, 0.7, 0.6, 0.5];
   for (const threshold of thresholds) {
-    const results = await runtime.searchMemoriesByEmbedding(embedding, {
+    const results = await runtime.searchMemories({
+      embedding,
       match_threshold: threshold,
       count: 5
     });

cli-reference/agent.mdx

@@ -16,20 +16,21 @@ icon: robot
 
     | Subcommand | Aliases | Description | Required Options | Additional Options |
     | ---------- | ------- | ----------- | ---------------- | ------------------ |
-    | `list` | `ls` | List available agents | | `-j, --json`, `-r, --remote-url <url>`, `-p, --port <port>` |
-    | `get` | `g` | Get agent details | `-n, --name <name>` | `-j, --json`, `-o, --output [file]`, `-r, --remote-url`, `-p, --port` |
-    | `start` | `s` | Start an agent with a character profile | One of: `-n, --name`, `--path`, `--remote-character` | `-r, --remote-url <url>`, `-p, --port <port>` |
-    | `stop` | `st` | Stop an agent | `-n, --name <name>` | `-r, --remote-url <url>`, `-p, --port <port>` |
-    | `remove` | `rm` | Remove an agent | `-n, --name <name>` | `-r, --remote-url <url>`, `-p, --port <port>` |
-    | `set` | | Update agent configuration | `-n, --name <name>` AND one of: `-c, --config` OR `-f, --file` | `-r, --remote-url <url>`, `-p, --port <port>` |
-    | `clear-memories` | `clear` | Clear all memories for an agent | `-n, --name <name>` | `-r, --remote-url <url>`, `-p, --port <port>` |
+    | `list` | `ls` | List available agents | | `-j, --json`, `-r, --remote-url <url>`, `-p, --port <port>`, `--auth-token` |
+    | `get` | `g` | Get agent details | `-n, --name <name>` | `-j, --json`, `-o, --output [file]`, `-r, --remote-url`, `-p, --port`, `--auth-token` |
+    | `start` | `s` | Start an agent with a character profile | One of: `-n, --name`, `--path`, `--remote-character` | `-r, --remote-url <url>`, `-p, --port <port>`, `--auth-token` |
+    | `stop` | `st` | Stop an agent | `-n, --name` or `--all` | `-r, --remote-url <url>`, `-p, --port <port>`, `--auth-token` |
+    | `remove` | `rm` | Remove an agent | `-n, --name <name>` | `-r, --remote-url <url>`, `-p, --port <port>`, `--auth-token` |
+    | `set` | | Update agent configuration | `-n, --name <name>` AND one of: `-c, --config` OR `-f, --file` | `-r, --remote-url <url>`, `-p, --port <port>`, `--auth-token` |
+    | `clear-memories` | `clear` | Clear all memories for an agent | `-n, --name <name>` | `-r, --remote-url <url>`, `-p, --port <port>`, `--auth-token` |
 
     ## Options Reference
 
     ### Common Options (All Subcommands)
 
     - `-r, --remote-url <url>`: URL of the remote agent runtime
     - `-p, --port <port>`: Port to listen on
+    - `--auth-token <token>`: API authentication token for secured runtimes
 
     ### Output Options (for `list` and `get`)
 
@@ -46,7 +47,12 @@ icon: robot
     - `--path <path>`: Path to local character JSON file
     - `--remote-character <url>`: URL to remote character JSON file
 
-    ### Stop/Remove Specific Options
+    ### Stop Specific Options
+
+    - `-n, --name <name>`: Agent id, name, or index number from list
+    - `--all`: Stop all running agents
+
+    ### Remove Specific Options
 
     - `-n, --name <name>`: Agent id, name, or index number from list (required)
 
@@ -149,6 +155,9 @@ icon: robot
 
     # Stop agent on remote runtime
     elizaos agent stop --name eliza --remote-url http://server:3000
+
+    # Stop all running agents
+    elizaos agent stop --all
     ```
 
     ### Removing Agents