Orion: Self-hosted AI Agent for Personal Workflows—On-demand Tool Loading, File-level Memory, and Traceable Forking

Orion is an open-source self-hosted AI agent framework designed to address the challenges of context management, cost control, and auditability faced by traditional AI agents in long-running workflows. Its core features include: on-demand tool loading, file-level long-term memory, context compression, and session forking mechanisms. Developed by the Micro-Mood team, this framework uses Python 3.10+ and Vue 3 + FastAPI tech stack, supporting local maintenance and extension.

As AI agents evolve into long-running personal assistants, traditional agents face three major engineering challenges:

1. Toolset bloat leads to heavy context usage; full tool registration wastes tokens and dilutes attention;
2. Long-term memory is stored in server-side databases, making it difficult for users to access, migrate, or modify;
3. State reconstruction during session forking is challenging, and sliding window truncation easily loses early information. These issues are particularly prominent in personal workflow scenarios.

Orion uses a "directory + registration" two-layer architecture to optimize tool calls:

• System prompts only retain a compact tool directory (e.g., read_file: Read file content);
• The model needs to call register_tool to load the full tool schema, supporting TTL automatic unloading;
• Benefits: Unused tools do not occupy tokens, implicit security boundaries, session-bound states, and prevention of tool accumulation bloat. Tool execution follows the OpenAI-compatible protocol, and dangerous tools require user confirmation by default.

Orion's context compression does not rely on sliding windows; instead, it generates three types of outputs:

1. Detailed Markdown archive: human-readable conversation flow, key facts, etc.;
2. Handover prompt: the [Compressed History Handover] system prompt retained in the current context;
3. Machine-readable sidecar (.ctx.json): stores metadata such as original entries and message IDs. The archive uses a standard directory structure (.orion/index.json, .md, .ctx.json). The compression strategy protects the current round and reduces the risk of tool sequence truncation. By default, it uses the file system to store memory, supporting direct inspection and migration.

Orion implements session forking through an ID system and metadata tracking:

• Reconstructs context using message IDs, round IDs, archive sidecars, and covered_msg_ids;
• Retains the context before the target message, inherits fully covered archives, and recursively restores partially overlapping archives;
• Context after the target message does not enter the new branch. The forking result has inspectable context boundaries instead of simply copying chat records.

Orion is suitable for various personal workflow scenarios:

• Note organization: read files, categorize, generate indexes;
• Reading research: save discussions as Markdown, support resuming from breakpoints;
• Personal assistant: maintain to-do lists, bills, plans;
• Programming development: read code, run commands, iterative fixes;
• Data processing: analyze CSV/JSON, generate reports. It has built-in 15 Notion integration tools and supports Windows, Linux, and macOS platforms.

Orion's architecture embodies "local-first" and "auditability":

• The file system serves as the memory layer, providing transparency and portability;
• Context compression trigger conditions, budget, and tool TTL are configurable to balance resources and costs;
• Forking relies on a strict ID system (unique identifiers for messages, rounds, archives) and metadata records to ensure accurate restoration of historical states.

Orion represents a pragmatic path for AI agent engineering: no reliance on external services, transparent and auditable, balancing functionality and efficiency. Its design provides a reference architecture for long-term personal AI assistants. Recommendations:

• Self-hosted users can use Orion as a fully functional starting point;
• Utilize open-source features and standard tech stack for customized extensions;
• Pay attention to community contributions to enrich tool sets and scenario support.