PAIAgent // DOCUMENTATION

Technical blueprint and system integration instructions for Open Personal AI Agent

1. Introduction

Open Personal AI Agent (PAIAgent) is a state-of-the-art, hyper-lightweight local agent framework. Built with Node.js, Fastify, and TypeScript, it is designed for developers and power users who want a customized local AI assistant without the resource overhead of heavyweight enterprise solutions.

Unlike solutions that require complex virtualization or multi-gigabyte container clusters, Open PAIAgent boots in less than a second and operates within a tiny memory footprint of 50-100 MB RAM.

💡 Core Architecture Goal

Maintain total data privacy. Everything from system prompts to memory states and file workspaces is stored locally on your own machine. No external telemetry or cloud-forced databases.

2. Quick Start

Get your local agent up and running in less than a minute. Follow these simple steps to install and start the server locally.

Prerequisites

System Requirements
  • Node.js: Version 20.x or later.
  • npm: Version 9.x or later.
  • Git: For cloning the repository.

Installation Command Sequence

Clone the repository and install npm packages:

BASH // PROJECT SETUP 
                            
                                git clone https://github.com/nordevelopment/OpenPAIAgent.git
cd OpenPAIAgent
npm install

Running The Agent

To start the agent in production mode (which automatically builds and starts the application):

BASH // PRODUCTION START 
npm start

For active development with hot reloading enabled, run the development server:

BASH // DEV ENVIRONMENT 
npm run dev

3. Configuration & APIs

PAIAgent features a built-in Setup Wizard. When you launch the server for the first time, simply navigate to http://127.0.0.1:3000. You will be automatically redirected to a web settings page.

If no .env file exists, your settings are saved securely in a local, git-ignored file named config.json in your project root.

Optional: Manual .env Configuration

If you prefer using traditional environment variables instead of the web setup wizard, you can manually copy the environment template and edit the resulting .env file:

BASH // ENV SETUP 
cp .env.example .env

Configurable API Providers

  • OpenRouter / Gemini / OpenAI (or any OpenAI-compatible API): The LLM provider for chat interactions, code writing, and image analysis (Vision).
  • Together AI / Grok X.AI: Used as API providers for the image generation tool. Features automatic fallback if one service is offline.
  • Telegram Bot Token: Connects your local server to the Telegram Bot API for remote agent interactions.
⚠️ Security Warning

Do NOT commit your config.json or .env files to public Git repositories. They contain raw API keys and private tokens. Both files are listed in .gitignore by default.

4. Modular Prompts

PAIAgent compiles the system prompt dynamically on application boot. Instead of maintaining a single massive string, system instructions are divided into clean, readable Markdown documents located under your prompt workspace directory.

Prompts structure:

  • Identity.md: The persona, tone, and character definitions of the assistant.
  • User.md: Contextual information about the user (preferences, environment settings).
  • Agent.md: The main ruleset defining how tools are structured and how responses should be formatted.
  • Memory.md: Guidelines on how the agent should structure memory summaries and search triggers.

This modular layout allows you to easily edit agent behaviors using any Markdown editor without touching the core codebase.

5. Tool Execution (Function Calling)

The agent has native capability to execute Javascript/Node.js functions as tools. These tools are exposed to the LLM model using structured JSON schemas.

File System Manager

Allows the AI to perform CRUD operations on files. For safety, this tool is restricted to a dedicated workspace/ directory.

🔒 Sandbox Restriction & Size Limits

The file system manager uses strict path resolution to prevent directory traversal attacks. Additionally, the agent enforces a safe file reading size limit (configured via AI_MAX_FILE_READ_SIZE in config.ts, defaulting to 1 MB) to prevent Out of Memory (OOM) failures and API context token spikes. Files exceeding the limit are cleanly truncated with a warning.

Web Scraper

Accepts a URL, downloads the markup, and strips out bloated HTML, script tags, and CSS using cheerio. This supplies the agent with clean, token-efficient text for real-time analysis.

Office Document Generator

Allows the AI to generate natively-formatted spreadsheets and documents directly in the workspace folder.

  • Excel Spreadsheets (generate_excel): The model receives a structured JSON schema mapping sheets, columns, and rows (including formulas like SUM). It compiles a stylized workbook using exceljs with custom colors, borders, and auto-adjusted columns.
  • Word Documents (generate_docx): The agent compiles paragraphs with alignments (left, center, right, justify), text styling (bold, italics), hierarchical headings, and layout tables into formatted .docx binaries using the docx builder.

Background Task Scheduler

Enables autonomous agent executions. Users can schedule tasks to run at a specific timestamp or continuously on a background interval. Automated tasks (is_auto = 1) run on the server, log actions, and send status notifications (started, completed, or failed with logs) directly to the Telegram bot owner.

Image Generation

Triggers text-to-image models. The system automatically routes requests through **Together AI** or **Grok X.AI** depending on which credentials are valid, ensuring highly available media generation.

6. Semantic Memory & Database

PAIAgent features a hybrid memory engine powered by **better-sqlite3** and the **sqlite-vec** extension.

When a chat session runs, the agent saves conversation turns. During queries, contextually relevant historic logs are matched using vector embeddings. This local semantic search feeds the prompt with relevant long-term memories.

To completely wipe the database and reset the system:

BASH // RESET DATABASE 
npm run db:reset