Assistant Core

Last updated: April 25, 2026

Assistant Core

The Assistant Core consists of the primary Go files that implement the agentic behavior and session management.

📁 Key Files

assistant.go

The primary engine file (~7,872 lines). It contains:

  • AssistantService: The central struct that manages the whole framework.
  • ChatSession: The stateful object representing an ongoing conversation.
  • ExecuteTool / ExecuteInternalTool: Functions for translating agent requests into tool executions.
  • ReAct Implementation: The core Thinking -> Action -> Observation loop logic.
  • Logging Integration: Structured JSONL logging for every session event.

assutils.go

Utility functions for the assistant:

  • LoadConfig: Loads configuration from .ini files.
  • LoadTools / LoadAgents: Dynamically loads markdown-based tool and agent persona definitions.
  • RepairJSON: A robust middleware that extracts and fixes malformed JSON output from LLMs, ensuring reliability for tool calls.
  • RBAC Logic: Defines user roles (MasterAdmin, Partner, Friend, etc.) and permission checks.

multillm.go

The provider abstraction layer. It defines a unified interface for multiple LLM backends:

  • localai: For local models (Ollama/llama-server).
  • OpenRouter: For a vast array of remote models.
  • Gemini / Anthropic / DeepSeek: Direct API integrations.
  • Model Discovery: Dynamically picks the best model based on agent metadata (Model: / FallBackModel: headers in agent .md files).

chat_persistence.go

Handles saving and loading session history, ensuring agents have memory of previous interactions.

  • Storage: Persists ChatSession objects into individual .json files.
  • Rehydration: Restores metadata, KnownFacts, and parent-child relationships after a system restart.

scheduler.go

A robust, SQLite-backed task runner.

  • Cron Specs: Supports both standard 5-field and precise 6-field (with seconds) cron expressions.
  • Zombie Recovery: Automatically identifies and fixes "executing" tasks that were interrupted by a system restart.
  • Persistent Audit: Logs every task execution's outcome (success/failure) for historical analysis.

🛠️ Internal Data Structures

  • ChatSession: Tracks Messages, Tools, KnownFacts, LastToolStatus, and ParentSessionID.
  • KnownFacts: A map[string]string used to store high-level discoveries that persist throughout a session's lifetime.
  • PendingTasks: Tracks asynchronous delegations that have not yet completed.

See Architecture for how these files interact.