{"slug": "phoenix-v2-persistent-memory-emotional-state-self-model-for-ai-mit", "title": "Phoenix V2: persistent memory, emotional state, self-model for AI (MIT)", "summary": "MIT-licensed Phoenix V2, a local-first AI assistant with persistent memory, emotional state, and self-model, has been released as a companion codebase to Cleverson Santos's book 'Building Persistent AI: Designing an Assistant That Remembers, Learns and Belongs to You'. The architecture uses a multi-agent pipeline with five specialized agents, a blackboard system, an emotion engine based on the PAD model, and a SQLite database to store memories and emotional state, ensuring continuity across model swaps and restarts. The companion paper, published on Zenodo in September 2026, formally characterizes the amnesia problem and positions Phoenix V2 against Mem0, MemGPT/Letta, Zep, and Generative Agents.", "body_md": "The companion codebase for the book **[Building Persistent AI: Designing an Assistant That Remembers, Learns and Belongs to You](https://leanpub.com/phoenix-buildingpersistentAI)** by Cleverson Santos.\n\n| 📄 **Companion paper** | [Phoenix V2: A Cognitive Architecture for Persistent, Emotionally-Aware AI Assistants on Consumer Hardware](https://doi.org/10.5281/zenodo.22645361) — Zenodo, September 2026 | \n| 📖 **Book** | [Building Persistent AI: Designing an Assistant That Remembers, Learns and Belongs to You](https://leanpub.com/phoenix-buildingpersistentAI) — Complete implementation guide, 26 chapters, 7 appendices | \n| 💻 **Repository** | This repository — MIT License | \n\nThe paper formally characterizes the amnesia problem, describes the full architecture with equations and a system diagram, and positions Phoenix V2 against Mem0, MemGPT/Letta, Zep, and Generative Agents. The book explains every design decision in detail, chapter by chapter, alongside this codebase.\n\nPhoenix V2 is a local-first AI assistant with a persistent cognitive architecture. It does not rely on the LLM to maintain memory, identity, or emotional state — those live in a local SQLite database and survive any model swap, restart, or conversation reset.\n\nThis repository contains the complete, working source code described chapter by chapter in the book. Every file you see here is explained in detail in the text.\n\n| Concept | What It Means in Phoenix | \n|---|---|\n| Persistent Memory | Conversations are stored in SQLite and retrieved by semantic similarity across sessions | \n| Multi-Agent Pipeline | Five specialized agents (Memory → Planning → Action → Reflection → Personality) process each input in sequence | \n| Blackboard Architecture | Agents communicate through a shared in-memory workspace — no direct coupling between them | \n| Emotion Engine | PAD model (Pleasure-Arousal-Dominance) tracks emotional state continuously based on interaction history | \n| Daydream Engine | Background process that generates reflective thoughts when Phoenix is idle | \n| Subconscious Cycle | Runs during rest periods to consolidate memories and update beliefs | \n| RLHF Feedback | User feedback (+/−) is captured and applied to an internal reinforcement scoring system | \n\n```\nUser Input\n    │\n    ▼\n[ server.ts — Express API Gateway ]\n    │\n    ▼\n[ brain.ts — Central Orchestrator ]\n    │\n    ├──▶ [ MemoryAgent ]     — retrieves relevant past context\n    ├──▶ [ PlanningAgent ]   — generates a raw response draft\n    ├──▶ [ ActionAgent ]     — decides if a real-world tool is needed\n    ├──▶ [ ReflectionAgent ] — reviews the draft for coherence and safety\n    └──▶ [ PersonalityAgent ]— applies Phoenix's voice to the final output\n              │\n              ▼\n    [ Blackboard ] ←─── shared working memory (volatile, per-request)\n              │\n              ▼\n    [ EmotionEngine ]   — updates PAD state after every interaction\n              │\n              ▼\n    [ SQLite Database ] — persists memories, emotional state, self-model\n              │\n    ┌─────────┴──────────┐\n    │                    │\n[ DaydreamEngine ]  [ SubconsciousEngine ]\n  (idle background)   (rest-cycle processing)\n```\n\nFull architecture diagram with all connections: [docs/architecture.md](/cleversonbrsantos-art/Phoenix/blob/main/docs/architecture.md)\n\n```\nphoenix-v2/\n│\n├── server.ts                      ← Express server + API routes\n├── src/\n│   ├── App.tsx                    ← React frontend (chat UI)\n│   ├── main.tsx\n│   └── server/\n│       ├── config/\n│       │   └── settings.ts        ← Environment variables\n│       ├── core/\n│       │   ├── brain.ts           ← Central orchestrator (Ch. 5)\n│       │   ├── blackboard.ts      ← Shared working memory (Ch. 4)\n│       │   ├── consolidation.ts   ← Memory consolidation engine (Ch. 12)\n│       │   ├── backup.ts          ← Data export\n│       │   ├── agents/\n│       │   │   ├── base_agent.ts       ← Abstract base class (Ch. 6)\n│       │   │   ├── memory_agent.ts     ← Memory retrieval (Ch. 6)\n│       │   │   ├── planning_agent.ts   ← Response drafting (Ch. 7)\n│       │   │   ├── action_agent.ts     ← Tool routing (Ch. 8)\n│       │   │   ├── reflection_agent.ts ← Draft validation (Ch. 9)\n│       │   │   └── personality_agent.ts← Voice and persona (Ch. 10)\n│       │   ├── dreams/\n│       │   │   └── daydream_engine.ts  ← Idle background process (Ch. 15)\n│       │   └── evolution/\n│       │       ├── reinforcement.ts    ← RLHF scoring (Ch. 17)\n│       │       └── incremental_learn.ts← Pattern learning (Ch. 18)\n│       ├── memory/\n│       │   ├── memory_manager.ts   ← Retrieval with semantic + priority scoring (Ch. 11)\n│       │   ├── storage.ts          ← SQLite persistence layer (Ch. 11)\n│       │   └── priority.ts         ← Recency × importance scoring (Ch. 11)\n│       ├── psychology/\n│       │   ├── self_model.ts       ← Identity, traits, beliefs, goals (Ch. 16)\n│       │   ├── emotion.ts          ← PAD emotion engine (Ch. 14)\n│       │   └── subconscious.ts     ← Rest-cycle processing (Ch. 15)\n│       ├── scheduler/\n│       │   ├── cron_tasks.ts       ← Timed tasks (Ch. 21)\n│       │   └── background_jobs.ts  ← Batch processing (Ch. 21)\n│       ├── tools/\n│       │   └── tool_registry.ts    ← Tool definitions for ActionAgent (Ch. 8)\n│       ├── users/\n│       │   └── profile_manager.ts  ← Multi-user identity management (Ch. 23)\n│       └── utils/\n│           ├── llm_client.ts       ← Gemini API wrapper (Ch. 19)\n│           ├── embeddings.ts       ← Vector embedding client (Ch. 11)\n│           └── filters.ts          ← Output formatting helpers\n│\n├── docs/\n│   ├── architecture.md            ← Full architecture diagram\n│   ├── chapter-map.md             ← Which file = which chapter\n│   └── SETUP.md                   ← Detailed setup guide (all OS)\n│\n├── .env.example                   ← Copy this to .env and add your API key\n├── .gitignore\n├── package.json\n├── tsconfig.json\n└── vite.config.ts\n```\n\n**Prerequisites:** Node.js 18 or higher · A free Gemini API key\n\n```\n# 1. Clone the repository\ngit clone https://github.com/cleversonbrsantos-art/Phoenix.git\ncd Phoenix\n\n# 2. Install dependencies\nnpm install\n\n# 3. Set your API key\ncp .env.example .env\n# Open .env and replace YOUR_GEMINI_API_KEY with your actual key\n\n# 4. Run\nnpm run dev\n\n# 5. Open in browser\n# http://localhost:3000\n```\n\nFor detailed setup instructions by operating system (Windows, Linux, macOS), see [docs/SETUP.md](/cleversonbrsantos-art/Phoenix/blob/main/docs/SETUP.md).\n\n1. Go to [https://aistudio.google.com/apikey](https://aistudio.google.com/apikey)\n2. Sign in with a Google account\n3. Click **Create API key**\n4. Copy the key into your `.env` file:\n\n```\nGEMINI_API_KEY=\"paste-your-key-here\"\n```\n\nThe free tier is sufficient to run Phoenix V2 for personal use.\n\nThe system starts four parallel processes:\n\n- **Express server** on port 3000 — serves the React UI and handles API calls\n- **Vite dev server** — compiles and hot-reloads the frontend\n- **SubconsciousEngine** — starts a background loop that runs memory consolidation every 5 minutes\n- **DaydreamEngine** — watches for idle periods and generates reflective thoughts after 2 minutes of inactivity\n\nThe SQLite database is created automatically at `.data/vault/phoenix_neural_db.sqlite` on first run. All memories, emotional state, and the self-model are persisted there across restarts.\n\nThis codebase maps directly to the book's structure:\n\n| Book Part | Chapters | Primary Files | \n|---|---|---|\n| Foundations | 1–4 | `blackboard.ts` , project setup | \n| Cognitive Core | 5–10 | `brain.ts` , all agents | \n| Persistence | 11–13 | `memory/` ,`consolidation.ts` | \n| Psychology | 14–16 | `emotion.ts` ,`subconscious.ts` ,`self_model.ts` | \n| Learning | 17–18 | `reinforcement.ts` ,`incremental_learn.ts` | \n| Integration | 19–21 | `server.ts` ,`App.tsx` ,`scheduler/` | \n| Advanced | 22–25 | `users/` , deployment, observability | \n\nFor the complete file-to-chapter mapping: [docs/chapter-map.md](/cleversonbrsantos-art/Phoenix/blob/main/docs/chapter-map.md)\n\nThis is the book version of Phoenix — the version described in the text, built on modest hardware (Intel Core i3, 8 GB RAM), without a GPU or cloud infrastructure.\n\nIt is intentionally designed to run on any modern laptop. It is not production-hardened, does not include authentication, and is not intended for multi-user deployment as-is.\n\nThe architecture, however, is built to evolve. Chapters 23 and 25 discuss how to extend it.\n\nMIT — see [LICENSE](/cleversonbrsantos-art/Phoenix/blob/main/LICENSE) for details.\n\n**Cleverson Santos** — Commercial Manager, Sinop, Brazil.\n\nArchitect of Phoenix. No formal programming background. Built this iteratively using Claude as a cognitive collaborator.\n\n- 📄 **Paper:**[doi.org/10.5281/zenodo.22645361](https://doi.org/10.5281/zenodo.22645361)\n- 📖 **Book:**[Building Persistent AI on Leanpub](https://leanpub.com/phoenix-buildingpersistentAI)\n- 💼 **LinkedIn:**[linkedin.com/in/cleverson-santos](https://www.linkedin.com/in/cleversonsantos2)\n\n*\"The LLM is an external consultant, never the cognitive engine. Identity, memory, and personality live locally — and survive any model swap.\"*", "url": "https://wpnews.pro/news/phoenix-v2-persistent-memory-emotional-state-self-model-for-ai-mit", "canonical_source": "https://github.com/cleversonbrsantos-art/Phoenix", "published_at": "2026-09-09 02:16:55+00:00", "updated_at": "2026-09-09 02:50:29.499497+00:00", "lang": "en", "topics": ["artificial-intelligence", "ai-agents", "ai-research", "ai-products"], "entities": ["Cleverson Santos", "Phoenix V2", "Mem0", "MemGPT/Letta", "Zep", "Generative Agents", "MIT", "Zenodo"], "alternates": {"html": "https://wpnews.pro/news/phoenix-v2-persistent-memory-emotional-state-self-model-for-ai-mit", "markdown": "https://wpnews.pro/news/phoenix-v2-persistent-memory-emotional-state-self-model-for-ai-mit.md", "text": "https://wpnews.pro/news/phoenix-v2-persistent-memory-emotional-state-self-model-for-ai-mit.txt", "jsonld": "https://wpnews.pro/news/phoenix-v2-persistent-memory-emotional-state-self-model-for-ai-mit.jsonld"}}