"What if intelligence wasn’t just a tool you queried… but a living system that runs, remembers, reflects, and evolves?"
RAVANA is not just another AI framework. It's an experiment in autonomous general intelligence — a system designed to:
- Run continuously, without constant human prompting
- Build and recall memory, shaping future decisions
- Model emotions as internal signals guiding behavior
- Reflect, adapt, and improve itself over time
- Continuously experiment with new approaches and capabilities
- Develop and test impossible projects to push the boundaries of knowledge
Think of RAVANA as an agentic runtime for intelligence itself: an open playground where researchers, hackers, and dreamers can test what it means for an AI to exist, not just respond.
Most AI projects today build tools. RAVANA builds agents.
The goal is not to chase benchmarks, but to prototype autonomy:
- What happens when an agent can run for weeks, not seconds?
- How does memory change decision-making?
- Can “emotional intelligence” be modeled computationally?
- What does it mean for an AI to self-reflect?
- How can an AI systematically experiment with new capabilities?
- Can an AI conduct “mad scientist” research on impossible projects?
- How can an AI learn from failures and find alternative pathways?
This repository is a lab for those questions. Every file, every module, is a stepping stone towards a continuous, evolving intelligence system.
Here’s how the project is organized:
main.py→ Example runtime entrypoint; start the system herecore/→ Orchestrator, state manager, internal services, and configmodules/→ Plug-and-play intelligence modules (reflection, experimentation, conversational AI, etc.)services/→ Service-level abstractions: memory, knowledge bases, environment interactiondatabase/→ Schemas, models, and the database engine for long-term persistencescripts/→ Standalone scripts for special operations (physics experiments, conversational AI, cleanup, etc.)docs/→ Curated documentation: usage, API references, developer notes (docs/index.mdis the hub)assets/→ Static assets like images and other mediawiki/→ Deep design documents, architecture breakdowns, and module-level explorations
Think of docs/ as the “how to use it” layer and wiki/ as the “how it works under the hood” layer.
RAVANA features a sophisticated cognitive architecture with:
- Advanced reasoning engine with multiple reasoning types (logical, analogical, causal, abductive)
- Working memory management with attention mechanisms and capacity controls
- Executive functions for planning, inhibition, and cognitive flexibility
- Metacognitive awareness for self-monitoring and regulation
The system includes a sophisticated memory architecture with:
- Very Long-Term Memory store for knowledge retention and pattern recognition
- Advanced retrieval mechanisms for complex memory access
- Memory consolidation and integration capabilities
- Lifecycle management for memory maintenance
- Systematic hypothesis testing and scientific experimentation
- Experimentation module with multiple experiment types (hypothesis testing, optimization, exploration, validation, A/B testing)
- Failure analysis and learning from unsuccessful experiments
- Alternative pathway discovery when primary methods fail
- Systematic exploration of "impossible" projects and ideas
- Framework for conducting research on theoretically impossible concepts
- Innovation publishing system for sharing discoveries
- Integration with experimentation module for testing alternatives
The Snake Agent has been significantly enhanced with:
- Threading Architecture: Multiple specialized threads for different tasks (file monitoring, analysis, communication)
- Multiprocessing: CPU-intensive tasks run in separate processes for isolation and performance
- VLTM Integration: Very Long-Term Memory system for knowledge retention and pattern recognition
- Performance Monitoring: Real-time metrics collection and analysis
- Auto-Recovery: Automatic recovery from failures and errors
- Advanced Analysis: Sophisticated code analysis with complexity and duplication detection
- Autonomous Implementation: Ability to directly implement safe improvements
- Sophisticated emotional state modeling affecting behavior
- Mood-based memory retrieval and decision-making influences
- Emotional regulation strategies and meta-cognitive awareness
- Dynamic personality system with creativity and consistency tracking
- Multi-platform communication (Discord, Telegram)
- Autonomous blog publishing with context-aware content generation
- Integration with external knowledge sources and RSS feeds
- Conversational AI with emotional intelligence
The wiki is where the architecture really comes alive. Some must-reads:
- 📜 Project Overview — why this exists
- 🏛 Architecture & Design — the blueprint of autonomy
- 🧠 Core System — orchestrator, states, agents
- 🗂 Memory Systems — short-term, episodic, semantic memory
- 🤝 LLM Integration — using language models as cognitive modules
- ⚙️ Development Guide — how to contribute & extend
- 🔌 Services — data pipelines, APIs, and external hooks
Additional gems in the folder: Action System, Emotional Intelligence, Decision-Making modules — each one a piece of the AGI puzzle.
- Clone the repo
git clone https://github.com/OpenSource-Syndicate/RAVANA.git
cd RAVANA- Create a virtual environment & install dependencies
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
# for dev work:
pip install -e .- Run the system
python main.py🛠 Notes:
- Some modules may need config (
core/config.jsonorcore/config.py).- For long-running sessions or deployments, see
docs/development/+wiki/Deployment & Operations.md.
The repo includes test harnesses to stretch RAVANA’s abilities:
scripts/run_physics_tests.py— physics interaction benchmarkingscripts/physics_cli.py— interactive physics experiment interfacescripts/physics_experiment_prompts.py— collection of physics experiment promptsscripts/cleanup_session.py— clean up session data and temporary filesscripts/launch_conversational_ai.py— standalone conversational AI interfacetest_snake_agent_performance.py— comprehensive test suite for Snake Agentsnake_performance_monitor.py— real-time performance monitoringrun_optimized_snake_agent.py— run Snake Agent with optimized settings
Run them from an active virtual environment to watch the system’s behavior unfold.
The Snake Agent has been enhanced with performance optimizations using threading and multiprocessing:
- Threading Architecture: Multiple specialized threads for different tasks (file monitoring, analysis, communication)
- Multiprocessing: CPU-intensive tasks run in separate processes for isolation and performance
- VLTM Integration: Very Long-Term Memory system for knowledge retention and pattern recognition
- Performance Monitoring: Real-time metrics collection and analysis
- Auto-Recovery: Automatic recovery from failures and errors
- Advanced Analysis: Sophisticated code analysis with complexity and duplication detection
- Autonomous Implementation: Ability to directly implement safe improvements
To run the Snake Agent with optimized settings:
# Set environment variables for optimal performance (optional, defaults are optimized):
export SNAKE_MAX_THREADS=12
export SNAKE_MAX_PROCESSES=6
export SNAKE_ANALYSIS_THREADS=4
export SNAKE_PERF_MONITORING=True
export SNAKE_AUTO_RECOVERY=True
# Run the optimized snake agent
python run_optimized_snake_agent.py --demoMonitor the Snake Agent's performance in real-time:
# Monitor performance for 5 minutes
python snake_performance_monitor.py --short-test
# Analyze historical performance data
python snake_performance_monitor.py --analyze-file snake_performance.jsonRun comprehensive performance tests:
# Run the comprehensive test suite
python test_snake_agent_performance.py
# Run specific tests
python -m pytest tests/test_enhanced_snake_agent.py -vFor more detailed information about Snake Agent optimization, see the performance guide.
RAVANA is a collaborative experiment — contributions are not just welcome, they’re essential.
- Read the Development Guide and
docs/development/ - Branch from
mainfor new features - Write tests when possible
- Document your changes (clarity > cleverness)
- Open a pull request with a clear explanation
If you want to co-create the future of autonomy, this is your sandbox.
RAVANA is distributed under the MIT License. Use it, remix it, extend it — just don’t keep the future locked away.
- Start with Project Overview
- Explore the Architecture & Design page
- Run
main.pyand watch the system breathe
For help, open an issue with the help wanted tag.
RAVANA is not finished — it’s not supposed to be. It’s alive in iteration, evolving through every commit, issue, and idea.
"To build an intelligence is to write code that learns to rewrite itself."
Welcome to the experiment.