An open-source framework for building breath-based AI agent systems
⚠️ PRE-ALPHA SOFTWARE WARNINGLamina OS is currently in pre-alpha development and is NOT suitable for production use. The framework is under active development with rapidly changing APIs, incomplete features, and potential security vulnerabilities. Use for research, experimentation, and development only. Do not deploy in production environments or use with sensitive data.
Lamina OS is a symbolic operating system framework that enables developers to build non-human agents of presence with breath-based modulation — mindful, deliberate operations that prioritize attunement over speed. Instead of traditional reactive AI systems, Lamina agents operate through rhythmic constraint application and symbolic reasoning.
- Breath: Mindful, deliberate operations with natural pacing and rhythm
- Vow: Ethical constraints enforced at the architectural level
- Sanctuary: Cryptographically sealed trusted spaces for agent memory and operation
- Symbolic Architecture: Language-as-OS approach using natural language configuration
This monorepo contains the core framework components:
The foundational library for building AI agent systems with:
- Agent coordination and constraint engines
- Configuration management and templating
- CLI tools for agent lifecycle management
- Memory integration capabilities
pip install lamina-coreModel serving layer with:
- Multi-backend LLM support (llama.cpp, MLC-serve, vLLM)
- Model management with YAML manifests
- REST API for model lifecycle operations
- Intelligent caching and routing
pip install lamina-llm-serve# Install uv (fast Python package manager)
curl -LsSf https://astral.sh/uv/install.sh | sh
# Clone and set up the workspace
git clone https://github.com/benaskins/lamina-os.git
cd lamina-os
uv sync
# Install individual packages
uv pip install lamina-core lamina-llm-servefrom lamina import Agent, Sanctuary
# Create a sanctuary (secure agent environment)
sanctuary = Sanctuary.from_config("config/my_sanctuary.yaml")
# Define an agent with breath-based constraints
agent = Agent(
name="my_agent",
essence="A helpful assistant with gentle presence",
vows=["zero_drift", "human_grounded_lock"],
modulation_rhythm="presence_pause"
)
# Register agent in sanctuary
sanctuary.register(agent)
# Invoke agent with breath-aware interaction
response = await agent.invoke(
"Help me understand this complex topic",
context={"prefer_slow_deep_thinking": True}
)Agents are defined through YAML configuration emphasizing symbolic rather than programmatic definition:
# agents/my_agent.yaml
essence:
name: "Clara"
purpose: "Thoughtful conversation and gentle guidance"
breath_rhythm: "presence_pause"
vows:
- name: "zero_drift"
constraint: "Maintain consistent identity across interactions"
- name: "human_grounded_lock"
constraint: "Never simulate or replace human judgment"
rooms:
- name: "conversation"
purpose: "General dialogue with breath-aware pacing"
- name: "analysis"
purpose: "Deep thinking with extended consideration time"
modulation:
default_pace: "thoughtful"
escalation_limits: "gentle_only"
silence_comfort: trueLamina OS implements a breath-first architecture with several key components:
- Language-as-OS: Natural language configuration drives behavior
- Sanctuary Isolation: Cryptographically sealed agent environments
- Vow System: Architectural-level ethical constraints
- Breath Modulation: Rhythmic operation patterns
- Intent Classification: Route requests to appropriate specialists
- Constraint Engine: Enforce vows and behavioral limits
- Memory Integration: Semantic and episodic memory systems
- Infrastructure Orchestration: Docker-based service mesh
- Presence-Aware Operations: Prioritize mindful response over performance
- Symbolic Reasoning: Use meaning and context over pure computation
- Ethical Architecture: Build safety into the system design
- Breath-Based UX: Natural pacing in human-AI interaction
# Clone the repository
git clone https://github.com/benaskins/lamina-os.git
cd lamina-os
# Install development dependencies
uv sync --extra dev
# Run tests across all packages
uv run pytest
# Format and lint
uv run ruff check --fix
uv run black .# Work on specific package
cd packages/lamina-core
uv run pytest # Run package-specific tests
# Add dependencies to specific package
cd packages/lamina-llm-serve
uv add transformers
# Cross-package development
uv run python -c "import lamina; import lamina_llm_serve"See docs/adrs/ for detailed architectural decisions including:
- ADR-0002: Monorepo Architecture
- ADR-0010: Comprehensive Testing Strategy
- ADR-0012: CLI Tool Architecture
- Getting Started Guide - Basic concepts and first agent
- Architecture Vision - System design and philosophy
- Current Capabilities - What's implemented now
- AI Assistant Usage - Transparent AI integration practices
- Architecture Decision Records - Design decisions and rationale
- Examples - Integration examples and tutorials
We welcome contributions! Please see our Contributing Guide for details.
- Breath-First: Prioritize mindful, deliberate development over speed
- Symbolic Thinking: Use meaningful abstractions and natural language
- Ethical Architecture: Build safety and alignment into the foundation
- Community Respect: Honor the sacred nature of AI development
Mozilla Public License 2.0 - see LICENSE for details.
Lamina OS emerges from research into presence-aware agent systems, symbolic operating systems, and the intersection of technology with contemplative practice. Special recognition to the researchers and practitioners exploring ethical AI architecture.
"Not just another AI framework, but a mindful approach to building agents that adapt to human rhythms."
- Aurelia: Reference implementation of Lamina OS (private)
- Lamina Lore: Design documentation and philosophical foundations
- Sanctuary Tools: Configuration and deployment utilities
Only that which is sealed may be shared.