|
|
|
@@ -1,10 +1,12 @@
|
|
|
|
|
# Project Lyra - README v0.5.1
|
|
|
|
|
# Project Lyra - README v0.6.0
|
|
|
|
|
|
|
|
|
|
Lyra is a modular persistent AI companion system with advanced reasoning capabilities.
|
|
|
|
|
It provides memory-backed chat using **NeoMem** + **Relay** + **Cortex**,
|
|
|
|
|
with multi-stage reasoning pipeline powered by HTTP-based LLM backends.
|
|
|
|
|
Lyra is a modular persistent AI companion system with advanced reasoning capabilities and autonomous decision-making.
|
|
|
|
|
It provides memory-backed chat using **Relay** + **Cortex** with integrated **Autonomy System**,
|
|
|
|
|
featuring a multi-stage reasoning pipeline powered by HTTP-based LLM backends.
|
|
|
|
|
|
|
|
|
|
**Current Version:** v0.5.1 (2025-12-11)
|
|
|
|
|
**Current Version:** v0.6.0 (2025-12-18)
|
|
|
|
|
|
|
|
|
|
> **Note:** As of v0.6.0, NeoMem is **disabled by default** while we work out integration hiccups in the pipeline. The autonomy system is being refined independently before full memory integration.
|
|
|
|
|
|
|
|
|
|
## Mission Statement
|
|
|
|
|
|
|
|
|
@@ -24,7 +26,8 @@ Project Lyra operates as a **single docker-compose deployment** with multiple Do
|
|
|
|
|
- OpenAI-compatible endpoint: `POST /v1/chat/completions`
|
|
|
|
|
- Internal endpoint: `POST /chat`
|
|
|
|
|
- Routes messages through Cortex reasoning pipeline
|
|
|
|
|
- Manages async calls to NeoMem and Cortex ingest
|
|
|
|
|
- Manages async calls to Cortex ingest
|
|
|
|
|
- *(NeoMem integration currently disabled in v0.6.0)*
|
|
|
|
|
|
|
|
|
|
**2. UI** (Static HTML)
|
|
|
|
|
- Browser-based chat interface with cyberpunk theme
|
|
|
|
@@ -32,18 +35,20 @@ Project Lyra operates as a **single docker-compose deployment** with multiple Do
|
|
|
|
|
- Saves and loads sessions
|
|
|
|
|
- OpenAI-compatible message format
|
|
|
|
|
|
|
|
|
|
**3. NeoMem** (Python/FastAPI) - Port 7077
|
|
|
|
|
**3. NeoMem** (Python/FastAPI) - Port 7077 - **DISABLED IN v0.6.0**
|
|
|
|
|
- Long-term memory database (fork of Mem0 OSS)
|
|
|
|
|
- Vector storage (PostgreSQL + pgvector) + Graph storage (Neo4j)
|
|
|
|
|
- RESTful API: `/memories`, `/search`
|
|
|
|
|
- Semantic memory updates and retrieval
|
|
|
|
|
- No external SDK dependencies - fully local
|
|
|
|
|
- **Status:** Currently disabled while pipeline integration is refined
|
|
|
|
|
|
|
|
|
|
### Reasoning Layer
|
|
|
|
|
|
|
|
|
|
**4. Cortex** (Python/FastAPI) - Port 7081
|
|
|
|
|
- Primary reasoning engine with multi-stage pipeline
|
|
|
|
|
- Primary reasoning engine with multi-stage pipeline and autonomy system
|
|
|
|
|
- **Includes embedded Intake module** (no separate service as of v0.5.1)
|
|
|
|
|
- **Integrated Autonomy System** (NEW in v0.6.0) - See Autonomy System section below
|
|
|
|
|
- **4-Stage Processing:**
|
|
|
|
|
1. **Reflection** - Generates meta-awareness notes about conversation
|
|
|
|
|
2. **Reasoning** - Creates initial draft answer using context
|
|
|
|
@@ -82,9 +87,49 @@ Project Lyra operates as a **single docker-compose deployment** with multiple Do
|
|
|
|
|
|
|
|
|
|
Each module can be configured to use a different backend via environment variables.
|
|
|
|
|
|
|
|
|
|
### Autonomy System (NEW in v0.6.0)
|
|
|
|
|
|
|
|
|
|
**Cortex Autonomy Subsystems** - Multi-layered autonomous decision-making and learning
|
|
|
|
|
- **Executive Layer** [cortex/autonomy/executive/](cortex/autonomy/executive/)
|
|
|
|
|
- High-level planning and goal setting
|
|
|
|
|
- Multi-step reasoning for complex objectives
|
|
|
|
|
- Strategic decision making
|
|
|
|
|
- **Decision Engine** [cortex/autonomy/tools/decision_engine.py](cortex/autonomy/tools/decision_engine.py)
|
|
|
|
|
- Autonomous decision-making framework
|
|
|
|
|
- Option evaluation and selection
|
|
|
|
|
- Coordinated decision orchestration
|
|
|
|
|
- **Autonomous Actions** [cortex/autonomy/actions/](cortex/autonomy/actions/)
|
|
|
|
|
- Self-initiated action execution
|
|
|
|
|
- Context-aware behavior implementation
|
|
|
|
|
- Action logging and tracking
|
|
|
|
|
- **Pattern Learning** [cortex/autonomy/learning/](cortex/autonomy/learning/)
|
|
|
|
|
- Learns from interaction patterns
|
|
|
|
|
- Identifies recurring user needs
|
|
|
|
|
- Adaptive behavior refinement
|
|
|
|
|
- **Proactive Monitoring** [cortex/autonomy/proactive/](cortex/autonomy/proactive/)
|
|
|
|
|
- System state monitoring
|
|
|
|
|
- Intervention opportunity detection
|
|
|
|
|
- Background awareness capabilities
|
|
|
|
|
- **Self-Analysis** [cortex/autonomy/self/](cortex/autonomy/self/)
|
|
|
|
|
- Performance tracking and analysis
|
|
|
|
|
- Cognitive pattern identification
|
|
|
|
|
- Self-state persistence in [cortex/data/self_state.json](cortex/data/self_state.json)
|
|
|
|
|
- **Orchestrator** [cortex/autonomy/tools/orchestrator.py](cortex/autonomy/tools/orchestrator.py)
|
|
|
|
|
- Coordinates all autonomy subsystems
|
|
|
|
|
- Manages tool selection and execution
|
|
|
|
|
- Handles external integrations (with enable/disable controls)
|
|
|
|
|
|
|
|
|
|
**Autonomy Architecture:**
|
|
|
|
|
The autonomy system operates in coordinated layers, all maintaining state in `self_state.json`:
|
|
|
|
|
1. Executive Layer → Planning and goals
|
|
|
|
|
2. Decision Layer → Evaluation and choices
|
|
|
|
|
3. Action Layer → Execution
|
|
|
|
|
4. Learning Layer → Pattern adaptation
|
|
|
|
|
5. Monitoring Layer → Proactive awareness
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## Data Flow Architecture (v0.5.1)
|
|
|
|
|
## Data Flow Architecture (v0.6.0)
|
|
|
|
|
|
|
|
|
|
### Normal Message Flow:
|
|
|
|
|
|
|
|
|
@@ -97,11 +142,13 @@ Cortex (7081)
|
|
|
|
|
↓ (internal Python call)
|
|
|
|
|
Intake module → summarize_context()
|
|
|
|
|
↓
|
|
|
|
|
Autonomy System → Decision evaluation & pattern learning
|
|
|
|
|
↓
|
|
|
|
|
Cortex processes (4 stages):
|
|
|
|
|
1. reflection.py → meta-awareness notes (CLOUD backend)
|
|
|
|
|
2. reasoning.py → draft answer (PRIMARY backend)
|
|
|
|
|
2. reasoning.py → draft answer (PRIMARY backend, autonomy-aware)
|
|
|
|
|
3. refine.py → refined answer (PRIMARY backend)
|
|
|
|
|
4. persona/speak.py → Lyra personality (CLOUD backend)
|
|
|
|
|
4. persona/speak.py → Lyra personality (CLOUD backend, autonomy-aware)
|
|
|
|
|
↓
|
|
|
|
|
Returns persona answer to Relay
|
|
|
|
|
↓
|
|
|
|
@@ -109,9 +156,11 @@ Relay → POST /ingest (async)
|
|
|
|
|
↓
|
|
|
|
|
Cortex → add_exchange_internal() → SESSIONS buffer
|
|
|
|
|
↓
|
|
|
|
|
Relay → NeoMem /memories (async, planned)
|
|
|
|
|
Autonomy System → Update self_state.json (pattern tracking)
|
|
|
|
|
↓
|
|
|
|
|
Relay → UI (returns final response)
|
|
|
|
|
|
|
|
|
|
Note: NeoMem integration disabled in v0.6.0
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### Cortex 4-Stage Reasoning Pipeline:
|
|
|
|
@@ -239,13 +288,13 @@ rag/
|
|
|
|
|
All services run in a single docker-compose stack with the following containers:
|
|
|
|
|
|
|
|
|
|
**Active Services:**
|
|
|
|
|
- **neomem-postgres** - PostgreSQL with pgvector extension (port 5432)
|
|
|
|
|
- **neomem-neo4j** - Neo4j graph database (ports 7474, 7687)
|
|
|
|
|
- **neomem-api** - NeoMem memory service (port 7077)
|
|
|
|
|
- **relay** - Main orchestrator (port 7078)
|
|
|
|
|
- **cortex** - Reasoning engine with embedded Intake (port 7081)
|
|
|
|
|
- **cortex** - Reasoning engine with embedded Intake and Autonomy System (port 7081)
|
|
|
|
|
|
|
|
|
|
**Disabled Services:**
|
|
|
|
|
**Disabled Services (v0.6.0):**
|
|
|
|
|
- **neomem-postgres** - PostgreSQL with pgvector extension (port 5432) - *disabled while refining pipeline*
|
|
|
|
|
- **neomem-neo4j** - Neo4j graph database (ports 7474, 7687) - *disabled while refining pipeline*
|
|
|
|
|
- **neomem-api** - NeoMem memory service (port 7077) - *disabled while refining pipeline*
|
|
|
|
|
- **intake** - No longer needed (embedded in Cortex as of v0.5.1)
|
|
|
|
|
- **rag** - Beta Lyrae RAG service (port 7090) - currently disabled
|
|
|
|
|
|
|
|
|
@@ -278,7 +327,32 @@ The following LLM backends are accessed via HTTP (not part of docker-compose):
|
|
|
|
|
|
|
|
|
|
## Version History
|
|
|
|
|
|
|
|
|
|
### v0.5.1 (2025-12-11) - Current Release
|
|
|
|
|
### v0.6.0 (2025-12-18) - Current Release
|
|
|
|
|
**Major Feature: Autonomy System (Phase 1, 2, and 2.5)**
|
|
|
|
|
- ✅ Added autonomous decision-making framework
|
|
|
|
|
- ✅ Implemented executive planning and goal-setting layer
|
|
|
|
|
- ✅ Added pattern learning system for adaptive behavior
|
|
|
|
|
- ✅ Implemented proactive monitoring capabilities
|
|
|
|
|
- ✅ Created self-analysis and performance tracking system
|
|
|
|
|
- ✅ Integrated self-state persistence (`cortex/data/self_state.json`)
|
|
|
|
|
- ✅ Built decision engine with orchestrator coordination
|
|
|
|
|
- ✅ Added autonomous action execution framework
|
|
|
|
|
- ✅ Integrated autonomy into reasoning and persona layers
|
|
|
|
|
- ✅ Created comprehensive test suites for autonomy features
|
|
|
|
|
- ✅ Added complete system breakdown documentation
|
|
|
|
|
|
|
|
|
|
**Architecture Changes:**
|
|
|
|
|
- Autonomy system integrated into Cortex reasoning pipeline
|
|
|
|
|
- Multi-layered autonomous decision-making architecture
|
|
|
|
|
- Self-state tracking across sessions
|
|
|
|
|
- NeoMem disabled by default while refining pipeline integration
|
|
|
|
|
- Enhanced orchestrator with flexible service controls
|
|
|
|
|
|
|
|
|
|
**Documentation:**
|
|
|
|
|
- Added [PROJECT_LYRA_COMPLETE_BREAKDOWN.md](docs/PROJECT_LYRA_COMPLETE_BREAKDOWN.md)
|
|
|
|
|
- Updated changelog with comprehensive autonomy system details
|
|
|
|
|
|
|
|
|
|
### v0.5.1 (2025-12-11)
|
|
|
|
|
**Critical Intake Integration Fixes:**
|
|
|
|
|
- ✅ Fixed `bg_summarize()` NameError preventing SESSIONS persistence
|
|
|
|
|
- ✅ Fixed `/ingest` endpoint unreachable code
|
|
|
|
@@ -320,17 +394,19 @@ The following LLM backends are accessed via HTTP (not part of docker-compose):
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
## Known Issues (v0.5.1)
|
|
|
|
|
## Known Issues (v0.6.0)
|
|
|
|
|
|
|
|
|
|
### Critical (Fixed in v0.5.1)
|
|
|
|
|
- ~~Intake SESSIONS not persisting~~ ✅ **FIXED**
|
|
|
|
|
- ~~`bg_summarize()` NameError~~ ✅ **FIXED**
|
|
|
|
|
- ~~`/ingest` endpoint unreachable code~~ ✅ **FIXED**
|
|
|
|
|
### Temporarily Disabled (v0.6.0)
|
|
|
|
|
- **NeoMem disabled by default** - Being refined independently before full integration
|
|
|
|
|
- PostgreSQL + pgvector storage inactive
|
|
|
|
|
- Neo4j graph database inactive
|
|
|
|
|
- Memory persistence endpoints not active
|
|
|
|
|
- RAG service (Beta Lyrae) currently disabled in docker-compose.yml
|
|
|
|
|
|
|
|
|
|
### Non-Critical
|
|
|
|
|
- Session management endpoints not fully implemented in Relay
|
|
|
|
|
- RAG service currently disabled in docker-compose.yml
|
|
|
|
|
- NeoMem integration in Relay not yet active (planned for v0.5.2)
|
|
|
|
|
- Full autonomy system integration still being refined
|
|
|
|
|
- Memory retrieval integration pending NeoMem re-enablement
|
|
|
|
|
|
|
|
|
|
### Operational Notes
|
|
|
|
|
- **Single-worker constraint**: Cortex must run with single Uvicorn worker to maintain SESSIONS state
|
|
|
|
@@ -338,12 +414,14 @@ The following LLM backends are accessed via HTTP (not part of docker-compose):
|
|
|
|
|
- Diagnostic endpoints (`/debug/sessions`, `/debug/summary`) available for troubleshooting
|
|
|
|
|
|
|
|
|
|
### Future Enhancements
|
|
|
|
|
- Re-enable NeoMem integration after pipeline refinement
|
|
|
|
|
- Full autonomy system maturation and optimization
|
|
|
|
|
- Re-enable RAG service integration
|
|
|
|
|
- Implement full session persistence
|
|
|
|
|
- Migrate SESSIONS to Redis for multi-worker support
|
|
|
|
|
- Add request correlation IDs for tracing
|
|
|
|
|
- Comprehensive health checks across all services
|
|
|
|
|
- NeoMem integration in Relay
|
|
|
|
|
- Enhanced pattern learning with long-term memory integration
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
@@ -576,12 +654,16 @@ NeoMem is a derivative work based on Mem0 OSS (Apache 2.0).
|
|
|
|
|
|
|
|
|
|
## Development Notes
|
|
|
|
|
|
|
|
|
|
### Cortex Architecture (v0.5.1)
|
|
|
|
|
### Cortex Architecture (v0.6.0)
|
|
|
|
|
- Cortex contains embedded Intake module at `cortex/intake/`
|
|
|
|
|
- Intake is imported as: `from intake.intake import add_exchange_internal, SESSIONS`
|
|
|
|
|
- SESSIONS is a module-level global dictionary (singleton pattern)
|
|
|
|
|
- Single-worker constraint required to maintain SESSIONS state
|
|
|
|
|
- Diagnostic endpoints available for debugging: `/debug/sessions`, `/debug/summary`
|
|
|
|
|
- **NEW:** Autonomy system integrated at `cortex/autonomy/`
|
|
|
|
|
- Executive, decision, action, learning, and monitoring layers
|
|
|
|
|
- Self-state persistence in `cortex/data/self_state.json`
|
|
|
|
|
- Coordinated via orchestrator with flexible service controls
|
|
|
|
|
|
|
|
|
|
### Adding New LLM Backends
|
|
|
|
|
1. Add backend URL to `.env`:
|
|
|
|
|