Aivena

Personal AI assistant powered by Pi — a terminal-first coding agent with persistent memory, cron scheduling, and multi-channel communication.

What is this?

Aivena is a zero-code configuration project for Pi. There is no custom source code — just a workspace directory with configuration, skills, and memory. All capabilities come from pi extensions. The Telegram chat interface is provided by pi-channels with its chat bridge.

Quick Start

Prerequisites

• Pi installed
• Extensions symlinked into workspace/.pi/extensions/
• Secrets in ~/.pi/agent/.env (see Environment Variables)

Run

npm start       # TUI (cd workspace && pi)
npm run tui     # TUI (same)

Project Structure

├── package.json                # Launch scripts (no deps)
├── AGENTS.md                   # Agent identity + conventions
├── CHANGELOG.md                # Release history
└── workspace/                  # Pi working directory
    ├── .pi/
    │   ├── settings.json       # Extension config (channels, webserver, heartbeat, etc.)
    │   ├── extensions/         # Symlinked extensions (see below)
    │   └── memory/             # Pi memory system (daily.md)
    ├── skills/                 # Custom skills (workon, etc.)
    ├── MEMORY.md               # Long-term memory
    ├── HEARTBEAT.md            # Health check checklist
    ├── memory/                 # Daily logs
    ├── log/                    # Session logs
    └── aivena.db               # SQLite database (jobs, CRM, etc.)

Extensions

Extensions are not included in this repo. They are part of the pi repository.

Aivena uses two sets of extensions:

• Workspace (workspace/.pi/extensions/) — symlinked, loaded only for Aivena
• Global (~/.pi/agent/extensions/) — auto-loaded for every pi session

Setup

Clone the pi repo and symlink the extensions you need:

git clone https://github.com/espennilsen/pi.git ~/Dev/pi

cd workspace/.pi/extensions
ln -s ~/Dev/pi/extensions/pi-channels .
ln -s ~/Dev/pi/extensions/pi-webserver .
# ... etc

Global extensions go in ~/.pi/agent/extensions/ and are available to all pi projects.

Workspace Extensions

Symlinked from ~/Dev/pi/extensions/:

Extension	Purpose	Settings key	Config
pi-channels	Telegram adapter + chat bridge	pi-channels	Required
pi-webserver	Shared HTTP server for web extensions	pi-webserver	Required
pi-heartbeat	Periodic health checks via subprocess	pi-heartbeat	Required
pi-vault	Obsidian vault integration	pi-vault	Required
pi-memory	Persistent memory (long-term + daily logs)	pi-memory	Optional
pi-personal-crm	Contact/relationship management	—	None
pi-calendar	Calendar events and reminders	—	None
pi-jobs	Agent run telemetry and cost tracking	—	None
pi-projects	Git project scanning and tracking	pi-projects	Optional
pi-td-webui	Task management web UI	tdWebui	Optional
pi-web-dashboard	Web dashboard home page	—	None
pi-webnav	Navigation bar for web extensions	—	None
pi-kysely	Shared SQLite (used by other extensions)	pi-kysely	Optional

Global Extensions

Installed in ~/.pi/agent/extensions/:

Extension	Purpose	Config
pi-cron	Scheduled background jobs	Required
pi-npm	npm tool for the agent	None
pi-subagent	Isolated subprocess agents	None
pi-telemetry	Run telemetry and cost tracking	None
pi-workon	Project context switching	Optional
web-fetch	URL fetching tool	None

Minimal Settings

The required extensions need configuration in workspace/.pi/settings.json:

{
  "pi-webserver": {
    "autostart": true,
    "port": 4110
  },
  "pi-channels": {
    "adapters": {
      "telegram": {
        "type": "telegram",
        "botToken": "<TELEGRAM_BOT_TOKEN>",
        "polling": true,
        "allowedChatIds": ["<chat-id>"]
      }
    },
    "routes": {
      "ops": { "adapter": "telegram", "recipient": "<chat-id>" },
      "cron": { "adapter": "telegram", "recipient": "<chat-id>" }
    },
    "bridge": {
      "enabled": true
    }
  },
  "pi-cron": {
    "autostart": true,
    "activeHours": { "start": "08:00", "end": "22:00" },
    "route": "cron",
    "showOk": false
  },
  "pi-heartbeat": {
    "autostart": true,
    "intervalMinutes": 60,
    "activeHours": { "start": "08:00", "end": "22:00" },
    "route": "ops",
    "showOk": false
  },
  "pi-vault": {
    "apiKey": "<OBSIDIAN_API_KEY>",
    "apiUrl": "http://127.0.0.1:27123"
  }
}

See each extension's README for the full set of options.

Environment Variables

Secrets in ~/.pi/agent/.env (loaded automatically by pi-dotenv):

ANTHROPIC_API_KEY=sk-ant-...
TELEGRAM_BOT_TOKEN=...
OBSIDIAN_API_KEY=...

History

Version	Description
0.3.0	0 LOC — pure Pi configuration project (pi-channels bridge replaces custom adapters)
0.2.0	1,058 LOC — adapter bridge (everything moved to pi extensions)
0.1.0	11,589 LOC — monolith (custom job tracking, cron, calendar, subagents)

License

MIT