akosha

Akosha

Universal memory aggregation and cross-system analytics for the Bodai ecosystem.

Version: 0.3.0 Status: Active pilot deployment for the current phase

Quick Links

• Overview
• Quick Start
• Installation
• Usage Examples
• Architecture
• Development

Quality & CI

Crackerjack is the standard quality-control and CI/CD gate for Akosha changes. Local verification should mirror the Crackerjack workflow used across the ecosystem.

---

What is Akosha?

Akosha is a universal memory aggregation system that collects, processes, and analyzes memories from multiple Session Buddy instances. It provides:

• Semantic Search: Find relevant conversations across all systems using vector embeddings
• Time-Series Analytics: Detect trends, anomalies, and correlations
• Knowledge Graph: Cross-system entity relationships and path finding
• Three-Tier Storage: Hot (in-memory) → Warm (on-disk) → Cold (Cloudflare R2)

Key Capabilities

✅ Privacy-First: Local ONNX embeddings, no external API calls required ✅ Scalable: Handles 100 to 100,000+ Session-Buddy instances ✅ Real-Time Analytics: Trend detection, anomaly spotting, cross-system correlation ✅ MCP Protocol: Exposes all capabilities via Model Context Protocol ✅ Operational Baseline: Tests, graceful degradation, and type-safe code

---

Quick Start

Prerequisites

• Python 3.13+ (required for modern type hints)
• UV package manager (recommended) or pip
• DuckDB (automatically installed)
• Optional: sentence-transformers for real embeddings (fallback available)
• Optional (serverless/production): PostgreSQL + pgvector extension for persistent hot-store storage across cold-starts

pgvector note: If using pgvector-backed storage, your PostgreSQL instance must have the vector extension enabled: CREATE EXTENSION vector;. See Deployment Guide for full serverless setup instructions.

5-Minute Setup

# 1. Clone repository
git clone https://github.com/lesleslie/akosha.git
cd akosha

# 2. Install dependencies
uv sync --group dev

# 3. Start Akosha MCP server
uv run python -m akosha.mcp

# 4. Verify installation
uv run python -c "from akosha.processing.embeddings import get_embedding_service; print('✅ Akosha ready!')"

That's it! Akosha is now running and ready to aggregate memories.

Production Deployment

For deployment details, operational setup, and metrics configuration:

# 1. Review deployment guide
cat docs/DEPLOYMENT_GUIDE.md

# 2. Deploy to Kubernetes
kubectl apply -f kubernetes/

# 3. Verify deployment
kubectl get pods -n akosha
kubectl port-forward -n akosha svc/akosha-api 8000:8000

# 4. Check metrics
curl http://localhost:8000/metrics

See Deployment Guide for complete production setup.

---

Installation

Using UV (Recommended)

# Install all dependencies (development + production)
uv sync --group dev

# Install minimal dependencies only (production)
uv sync

# Verify installation
uv run pytest tests/unit/ -v

Using Pip

# Create virtual environment
python3.13 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -e ".[dev]"

# Verify installation
pytest tests/unit/ -v

Optional Dependencies

For real semantic embeddings (recommended):

# Using UV
uv add --optional embeddings sentence-transformers onnxruntime

# Using pip
pip install "akosha[embeddings]"

Note: Akosha works without these dependencies using deterministic fallback embeddings. Real embeddings provide better semantic search.

---

Configuration

Environment Variables

Create a .env file in the Akosha directory:

# Cloudflare R2 Configuration (Cold Storage)
AKOSHA_COLD_BUCKET=your-bucket-name
AKOSHA_COLD_ENDPOINT=https://your-account.r2.cloudflarestorage.com
AKOSHA_COLD_REGION=auto