The Voice in the Trees

Overview

At her core, Melian is an agent: a loop that receives input, decides what to do, uses tools, and responds. The agent router orchestrates this cycle, managing tool calls, streaming responses, and maintaining conversational state across all integrations.

The Router

The agent router is the main loop. It takes a user message, constructs the full prompt (system instructions + core memory + conversation history), calls the LLM, and processes the response, including any tool calls.

Tool calls are executed in sequence. Each tool returns a result that feeds back into the conversation, allowing Melian to chain actions: search memory, read an email, check the calendar, and synthesize a response. The router streams chunks as they arrive, yielding typed events the caller can consume.

export interface AgentRouterConfig {
  llm: LLMProvider;
  tools: ToolRegistry;
  coreMemory: CoreMemory;
  recall: RecallMemory;
  personality: PersonalityLoader;
  spirit: SpiritLoader;
  maxContextTokens: number;
  metrics?: MetricsCollector;
  user?: { name: string; interests?: string[] };
}

Streaming Response

The router yields a typed stream rather than a single response. Consumers receive chunks as the LLM and tools produce them:

export type RouterChunk =
  | { type: "text"; content: string }
  | { type: "tool_call"; name: string; args: Record<string, any> }
  | { type: "tool_result"; name: string; result: string }
  | { type: "spirit"; action: "formed" | "reinforced"; category: string }
  | { type: "done" };

Chat messages in the conversation thread follow the OpenAI-compatible format:

export interface ChatMessage {
  role: "system" | "user" | "assistant" | "tool";
  content: string | null;
  tool_call_id?: string;
  tool_calls?: ToolCall[];
}

Tool Registry

Tools are registered as ToolDefinition objects and loaded into the LLM's tool list on each turn:

export interface ToolDefinition {
  type: "function";
  function: {
    name: string;
    description: string;
    parameters: Record<string, unknown>;
  };
}

Melian has 50+ tools across these categories:

Model Routing

Melian routes each request to a light or heavy model based on a complexity score from 0 to 1. The score is computed before the LLM call:

When the score meets or exceeds the configured threshold, the request routes to the heavy model. Simple queries stay on the fast path for lower latency and cost.

Spirit & Personality

Melian's personality is not static. The spirit_evolve tool updates her character over time based on observed interactions. Each spirit entry tracks a trait, a category, its strength on a 1–10 scale, and when it was first formed and last reinforced:

export interface SpiritEntry {
  trait: string;
  category: string;
  strength: number;      // 1–10
  formed: string;        // ISO date YYYY-MM-DD
  reinforced: string;    // ISO date YYYY-MM-DD
}

When spirit_evolve fires, the new trait embedding is compared against existing entries using cosine similarity. A score ≥ 0.85 reinforces the existing entry rather than creating a duplicate. The spirit store is capped at 100 entries; when the cap is exceeded, the entry with the lowest retention score (a function of strength, recency, and reinforcement frequency) is pruned.

Personality and spirit are loaded alongside core memory at router startup and injected into the system prompt, shaping every response Melian gives.