Skip to main content

Documentation Index

Fetch the complete documentation index at: https://doc.ambientsoul.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Soul Kernel Developer Onboarding

Welcome to the Soul Kernel project! This guide will help you get started with contributing to the Companion Intelligence Core.

​
🎯 Project Overview

Soul Kernel is a portable, open-core platform that embeds identity, memory, personality, and proactivity into any surface—mobile, AR/VR, or physical robots. Think of it as the “Unity for AI companions” or “ROS for emotional intelligence.”

​
Key Concepts

  • Soul: An AI companion with persistent identity and memory
  • Digital Twin: A Soul that maintains consistent identity across multiple devices
  • Kernel: The core runtime that manages Soul lifecycle
  • Skills: Plugin capabilities (vision, voice, actuators)
  • Shells: Platform-specific hosts (iOS, Unity, Physical AI)

​
🚀 Quick Start

​
Prerequisites

  1. Rust 1.79+ - Our core runtime language 
    curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env"
  2. Git - For version control
  3. GitHub Account - For contributing

​
First Steps

  1. Clone the repository 
    git clone https://github.com/soul-kernel/soul-kernel.git
cd soul-kernel
  2. Build and test 
    cd kernel
cargo test
cargo run
  3. Read the architecture

​
📚 Learning Path

​
Week 1: Foundations

  • Complete Rust basics (if new to Rust)
  • Run the Soul Kernel locally
  • Read through the codebase structure
  • Understand the Skill ABI concept

​
Week 2: Deep Dive

  • Implement a simple Skill
  • Explore the memory graph design
  • Review the gRPC API surface
  • Join our Discord community

​
Week 3: Contributing

  • Pick a “good first issue”
  • Submit your first PR
  • Participate in code reviews
  • Update documentation

​
🏗️ Development Workflow

​
1. Agile Process

We follow an Agile workflow with:
  • Epics: Large features (one active at a time)
  • Stories: Implementable units with clear acceptance criteria
  • Tasks: Technical steps within stories

​
2. Code Standards

  • Use cargo fmt before committing
  • Run cargo clippy for linting
  • Write tests for new functionality
  • Keep binary size minimal

​
3. Git Workflow

# Create feature branch
git checkout -b feature/your-feature

# Make changes and test
cargo test
cargo fmt
cargo clippy

# Commit with conventional commits
git commit -m "feat: add new skill interface"

# Push and create PR
git push origin feature/your-feature

​
🛠️ Development Environment

  • IDE: VS Code with rust-analyzer or IntelliJ IDEA with Rust plugin
  • Debugging: lldb or gdb with Rust support
  • Profiling: cargo-flamegraph for performance analysis

​
VS Code Setup

{
  "rust-analyzer.cargo.features": "all",
  "rust-analyzer.checkOnSave.command": "clippy"
}

​
🤝 Getting Help

  • Discord: Join #soul-kernel-dev channel
  • GitHub Discussions: For design questions
  • Issue Tracker: For bugs and features
  • Weekly Office Hours: Thursdays 2pm PT

​
📖 Key Resources

​
🎉 Your First Contribution

  1. Look for issues labeled good-first-issue
  2. Comment on the issue to claim it
  3. Fork the repository
  4. Create a branch from main
  5. Make your changes with tests
  6. Submit a PR referencing the issue
Welcome aboard! We’re excited to have you join the Soul Kernel community. 🚀