PAI: Building a Personal AI Agent System with File System at Its Core

PAI is an innovative personal AI agent project that uses a Linux-like file system architecture as its core data organization method, replacing traditional database or vector storage solutions. This design follows the Unix philosophy (plain text over databases, symbolic links over copies), bringing higher observability, maintainability, and scalability to AI systems. This article will cover aspects such as background, architecture design, configuration management, toolchain, evolution path, and design insights.

In AI agent system design, data organization and management are core issues. Traditional solutions mostly use databases or vector storage, but PAI chooses a Linux-like file system architecture—not out of nostalgia, but as a well-considered engineering decision: plain text files make system states fully transparent (viewable with any editor, searchable via grep, monitorable via tail), symbolic links ensure the single source of truth principle, avoid data inconsistency, and greatly improve debugging and diagnosis efficiency.

PAI simulates a complete Linux file system hierarchy with the root directory at ~/.pai:

• /boot/ stores the supervision process implemented in pure Python (core scheduler, responsible for agent lifecycle, event routing, and configuration synchronization);
• /usr/ stores extension components such as drivers, skill modules, and AI agent packages, ensuring kernel stability and flexible function expansion.

In the event-driven architecture, drivers (e.g., message, email, calendar drivers) connect external services to the kernel and maintain private states (/sys/drivers/<name>/); the kernel manages process lifecycles via /proc/<slug>/ and routes events to corresponding agent instances, achieving loose coupling.

The agent lifecycle has three layers: Package (/usr/lib/pais/<name>/ defines code dependencies) → Instance (paiadd creates a configuration instance with independent state and home directory) → Process (kernel maintains running state).

PAI follows the configuration-as-code principle:

• /etc/config.yaml is the single source of truth for system configuration, declaring the agent fleet (name, provider, model, prompt, etc.), supporting version control (Git), atomic changes (loadable without restart), and audit rollback.

The development toolchain is complete:

• paiman manages software packages, paiadd/paidel manages instances, paictl controls runtime, paicron schedules cron jobs;
• Developed with Python3.14, using uv for dependency management, paifs-init initializes the environment;
• Kernel and user-space code are separated (kernel in the main repository, drivers/skills in the pairegistry repository), ensuring kernel stability and independent evolution of the ecosystem.

PAI currently runs as a terminal application (to reduce maintenance burden before core contracts stabilize). Trigger conditions for evolving to a native application:

1. TUI becomes the main daily interface instead of a debugging tool;
2. Need for native notifications, persistent menu bar presence, global shortcuts, and other features hard to implement in terminals;
3. Target users expand to non-technical people. Migration will start when two of these conditions are met.

Transition plan: Package the kernel and TUI as a background agent (managed by launchd), provide a lightweight SwiftUI menu bar app as the frontend, retain the terminal interface, balancing native features and core logic reuse.

PAI presents an AI system design approach different from the mainstream: while pursuing complex functions, it emphasizes the value of simplicity and observability. Although its Linux-like file system architecture may be less efficient than databases in some scenarios, the transparency and debuggability it brings are more valuable in operation and maintenance.

This design demonstrates the modern application of the Unix philosophy: components with single responsibilities, collaboration via clear interfaces, and system behavior emerging naturally. For developers, PAI is not just a tool but also a thought experiment—it inspires a system design approach where AI agents are treated as processes, events as signals, and configurations as code, which is worth in-depth research and reference.