Phoenix — A local first AI assistant with persistent…

Pitch

Description

Comments

About this project

Phoenix V2 offers a revolutionary approach to AI assistance, focusing on persistent memory and emotional awareness. By utilizing a local SQLite database, it enhances user interaction by remembering past conversations, allowing for a more personalized experience. This repository serves as the foundation for understanding and implementing a sophisticated, multi-agent AI system.

Phoenix V2 — Persistent Cognitive AI

Phoenix V2 represents a state-of-the-art local-first AI assistant built on a robust persistent cognitive architecture. This codebase, designed as a companion to the book Building Persistent AI: Designing an Assistant That Remembers, Learns and Belongs to You authored by Cleverson Santos, allows developers to create an AI assistant that effectively maintains memory, identity, and emotional context, all stored securely in a local SQLite database. This architecture guarantees continuity through model swaps, session resets, and application restarts.

Key Features

Persistent Memory: Retains conversations in an SQLite database, enabling retrieval based on semantic similarity across different sessions.
Multi-Agent Pipeline: Processes input through five distinct specialized agents, ensuring a comprehensive approach to interaction: Memory, Planning, Action, Reflection, and Personality.
Blackboard Architecture: Promotes communication among agents via a shared in-memory workspace, enhancing modularity and scalability.
Emotion Engine: Implements the PAD (Pleasure-Arousal-Dominance) model to continuously monitor emotional states informed by historical interactions.
Daydream Engine: Automatically generates reflective thoughts during idle periods, enhancing user engagement.
Subconscious Cycle: Operates during downtime to consolidate memories and update cognitive beliefs, mimicking a human-like processing cycle.
RLHF Feedback: Efficiently captures user feedback (+/−) to enhance learning through a reinforcement scoring system, allowing the assistant to adapt over time.

Architecture Overview

User Input
    │
    ▼
[ server.ts — Express API Gateway ]
    │
    ▼
[ brain.ts — Central Orchestrator ]
    │
    ├──▶ [ MemoryAgent ]     — retrieves relevant past context
    ├──▶ [ PlanningAgent ]   — generates a raw response draft
    ├──▶ [ ActionAgent ]     — decides if a real-world tool is needed
    ├──▶ [ ReflectionAgent ] — reviews the draft for coherence and safety
    └──▶ [ PersonalityAgent ]— applies Phoenix's voice to the final output
              │
              ▼
    [ Blackboard ] ←─── shared working memory (volatile, per-request)
              │
              ▼
    [ EmotionEngine ]   — updates PAD state after every interaction
              │
              ▼
    [ SQLite Database ] — persists memories, emotional state, self-model
              │
    ┌─────────┴──────────┐
    │                    │
[ DaydreamEngine ]  [ SubconsciousEngine ]
  (idle background)   (rest-cycle processing)

Project Structure

phoenix-v2/
│
├── server.ts                      ← Express server + API routes
├── src/
│   ├── App.tsx                    ← React frontend (chat UI)
│   ├── main.tsx
│   └── server/
│       ├── config/
│       │   └── settings.ts        ← Environment variables
│       ├── core/
│       │   ├── brain.ts           ← Central orchestrator (Ch. 5)
│       │   ├── blackboard.ts      ← Shared working memory (Ch. 4)
│       │   ├── consolidation.ts   ← Memory consolidation engine (Ch. 12)
│       │   ├── backup.ts          ← Data export
│       │   ├── agents/
│       │   │   ├── base_agent.ts       ← Abstract base class (Ch. 6)
│       │   │   ├── memory_agent.ts     ← Memory retrieval (Ch. 6)
│       │   │   ├── planning_agent.ts   ← Response drafting (Ch. 7)
│       │   │   ├── action_agent.ts     ← Tool routing (Ch. 8)
│       │   │   ├── reflection_agent.ts ← Draft validation (Ch. 9)
│       │   │   └── personality_agent.ts← Voice and persona (Ch. 10)
│       │   ├── dreams/
│       │   │   └── daydream_engine.ts  ← Idle background process (Ch. 15)
│       │   └── evolution/
│       │       ├── reinforcement.ts    ← RLHF scoring (Ch. 17)
│       │       └── incremental_learn.ts← Pattern learning (Ch. 18)
│       ├── memory/
│       │   ├── memory_manager.ts   ← Retrieval with semantic + priority scoring (Ch. 11)
│       │   ├── storage.ts          ← SQLite persistence layer (Ch. 11)
│       │   └── priority.ts         ← Recency × importance scoring (Ch. 11)
│       ├── psychology/
│       │   ├── self_model.ts       ← Identity, traits, beliefs, goals (Ch. 16)
│       │   ├── emotion.ts          ← PAD emotion engine (Ch. 14)
│       │   └── subconscious.ts     ← Rest-cycle processing (Ch. 15)
│       ├── scheduler/
│       │   ├── cron_tasks.ts       ← Timed tasks (Ch. 21)
│       │   └── background_jobs.ts  ← Batch processing (Ch. 21)
│       ├── tools/
│       │   └── tool_registry.ts    ← Tool definitions for ActionAgent (Ch. 8)
│       ├── users/
│       │   └── profile_manager.ts  ← Multi-user identity management (Ch. 23)
│       └── utils/
│           ├── llm_client.ts       ← Gemini API wrapper (Ch. 19)
│           ├── embeddings.ts       ← Vector embedding client (Ch. 11)
│           └── filters.ts          ← Output formatting helpers
│
├── docs/
│   ├── architecture.md            ← Full architecture diagram
│   ├── chapter-map.md             ← Which file = which chapter
│   └── SETUP.md                   ← Detailed setup guide (all OS)
│
├── .env.example                   ← Copy this to .env and add your API key
├── .gitignore
├── package.json
├── tsconfig.json
└── vite.config.ts

Limitations and Scope

Phoenix V2, as demonstrated in this codebase, operates on modest hardware without GPU or cloud support, intended to be run on standard laptops. It is designed not as a production-ready solution but as a foundational framework for enhancing and evolving future versions. Extensions are discussed in the later chapters of the accompanying book, allowing users to adapt the architecture for broader applications.