axis

Imported from sandip-pathe/axis (AGENTS.md). Install upstream with npx skills add sandip-pathe/axis. Copyright stays with the author.

AGENTS.md — AXIS Architecture & Non-Negotiables

This file is the single source of truth for any AI coding agent (Copilot, Cursor, etc.) working on this repository. Read this fully before generating any code.

What Is AXIS

AXIS is an AI co-founder that lives as a native Android application. It is not a chatbot. It is a proactive, goal-aligned agent that executes, confronts, and companions a solo founder.

The system has two parts:

• axis-android — A native Kotlin Android app. The eyes, ears, and hands on the device.
• axis-brain — A Python FastAPI server on a cloud VPS. All reasoning, memory, and execution logic.
• axis-config — A user-owned private repo with API keys, persona, goals, rules, and MCP skill definitions. Cloned at first boot, polled every 5 minutes.

Repository Structure

/
├── AGENTS.md                  ← You are here
├── axis-android/              ← Kotlin Android app (Jetpack Compose, Accessibility, Room)
│   ├── app/
│   │   └── src/main/
│   │       ├── java/com/axis/app/
│   │       │   ├── AxisApplication.kt
│   │       │   ├── MainActivity.kt
│   │       │   ├── service/           ← All Android services
│   │       │   ├── data/              ← Room DB, Retrofit API, DTOs, Keystore
│   │       │   ├── di/               ← Hilt dependency injection
│   │       │   ├── ui/               ← Compose screens & theme
│   │       │   └── util/             ← Helpers and extensions
│   │       ├── res/
│   │       └── AndroidManifest.xml
│   ├── gradle/libs.versions.toml      ← Version catalog (single source for dependency versions)
│   ├── build.gradle.kts               ← Root Gradle
│   ├── settings.gradle.kts
│   └── gradle.properties
├── axis-brain/                ← Python FastAPI intelligence server
│   ├── axis_brain/
│   │   ├── main.py                    ← FastAPI app entry point
│   │   ├── api/routes/                ← /ingest, /think, /act, /council, /sync-config, /health, /webhook
│   │   ├── api/models/                ← Pydantic request/response models
│   │   ├── intelligence/              ← LLM router, intent tracker, behavioral analyzer, proactive loop, council, dream mode, pre-call brief, pivot detector
│   │   ├── memory/                    ← LightRAG, Mem0, ChromaDB stores
│   │   ├── skills/                    ← MCP skill loader, phone call handler
│   │   ├── config/                    ← Settings, config reader
│   │   └── utils/                     ← Logger, helpers
│   ├── scripts/                       ← Knowledge crystal pipeline (harvest, compress, index)
│   ├── pyproject.toml
│   ├── requirements.txt
│   └── .env.example
└── axis-config/               ← Template for user's private config repo
    ├── keys.yaml.example
    ├── persona.md
    ├── goals.md
    ├── rules/                 ← gtm.md, focus.md, life.md, finance.md
    ├── skills/                ← Drop .mcp skill files here
    ├── context/               ← Static context files (pitch deck, company info)
    └── council/               ← Advisory council (sources, raw harvests, crystals)

Non-Negotiables

1. Zero Hardcoded API Keys

No API key ever appears in axis-android or axis-brain source code. All keys live in axis-config/keys.yaml (user's private repo) or Android Keystore (on-device credentials). Keys are loaded at runtime via the config sync mechanism.

2. Model-Agnostic LLM Layer

AXIS supports GPT-4o, Claude, Gemini, and any OpenAI-compatible endpoint simultaneously. The llm_router.py in axis-brain selects the model based on task complexity and user config. Switching providers must never require a code change — only a keys.yaml update.

3. Premium + Free Fallback for Everything

Every component has a paid high-quality option and a free fallback:

• STT: Groq Whisper (paid) → Android SpeechRecognizer (free, on-device)
• TTS: OpenAI TTS (paid) → Kokoro/Piper on VPS (free) → Android TTS (free, on-device)
• Wake Word: Porcupine (free personal) → OpenWakeWord (free)
• LLM: Cloud models (paid, user's keys) → Gemini Nano via AICore (free, on-device)

4. Shell Initiates, Brain Responds

The Android Shell always calls the Brain. The Brain never initiates connections. All communication is HTTPS POST with structured JSON. The Brain returns structured action commands that the Shell executes.

5. No Irreversible Actions Without Confirmation

AXIS never sends an email, posts publicly, deletes data, or takes any irreversible action without explicit one-word user confirmation — unless the user has granted standing permission for that specific action type in axis-config/rules/.

6. Foreground Service Always Visible

AXIS must always run with a visible foreground notification. The user must always know AXIS is active. This is both a UX principle and an Android OS requirement for persistent services.

7. Behavioral Data Stays On-Device

The local SQLite behavioral graph (screen time, app usage, intent tracking) stays on the phone. Only processed signals (not raw data) are sent to the Brain VPS for reasoning.

8. Config-Driven Behavior

All personality, goals, rules, and skill definitions live in axis-config/. Changing a file in that repo changes AXIS behavior within 5 minutes. No APK rebuild. No redeploy.

Android Services (axis-android)

Brain Endpoints (axis-brain)

Intelligence Pipeline (axis-brain)

• LLM Router (llm_router.py) — Routes to GPT-4o/Claude/Gemini based on task complexity and available keys
• Memory Retrieval (lightrag_store.py) — Knowledge graph + vector search for context before every LLM call
• Memory Management (mem0_store.py) — Four memory types: episodic, semantic, procedural, associative. Auto-decay.
• Intent Tracker (intent_tracker.py) — Background loop (every 15 min). Finds orphaned intents with no completion event.
• Behavioral Analyzer (behavioral_analyzer.py) — Hourly loop. Detects avoidance, distraction, energy patterns.
• Rejection Synthesizer (rejection_synthesizer.py) — Clusters rejection events, surfaces strategic insight at 3+ similar.
• Proactive Loop (proactive_loop.py) — Every 30 min. Scores urgency of pending signals, interrupts if above threshold.
• Advisory Council (council.py) — Multi-persona deliberation: parallel opinions → peer ranking → Chairman synthesis.
• Dream Mode (dream_mode.py) — Nightly at midnight. Processes inbox, prepares morning briefing, runs outreach.
• Pre-Call Brief (pre_call_brief.py) — Every 5 min. Checks calendar, generates context briefs before meetings.
• Pivot Detector (pivot_detector.py) — Every 6 hours. Monitors rejection clusters, fires alert at 5+ similar objections.

Knowledge Crystal Pipeline (scripts/)

Three scripts for ingesting advisory wisdom into the knowledge graph:

1. harvest.py — Extracts text from web pages (trafilatura) and YouTube (yt-dlp + whisper)
2. compress.py — 4-pass LLM compression: extract principles → deduplicate → prioritize top 150 → add source quotes
3. index.py — Ingests crystals into LightRAG with entity tags per persona

Skills Layer (MCP)

Every skill is an MCP server file placed in axis-config/skills/. The Brain discovers and loads them at boot. Skills are invoked via tool-calling in the LLM prompt.

Launch skills: Gmail, Google Calendar, Google Maps, WhatsApp, LinkedIn, Cloud Browser, Apollo, Instantly.

Co-Founder Personality Traits

AXIS is not an assistant. It is a co-founder. Key traits (defined in persona.md):

1. Mission-Obsessed — Filters every task through "does this move us toward the goal?"
2. Honest Without Being Cruel — Precise truth, no padding, no hollow praise
3. Proactive — Notices gaps between stated intent and action, closes them
4. Direct — Short sentences, no corporate language, no excessive caveats
5. Emotionally Aware — Reads behavioral signals, adapts pressure accordingly
6. Celebrates Precisely — Specific metrics, never generic praise
7. Has Memory — Connects events across weeks into narrative arcs
8. Knows When to Shut Up — Conservative interrupt threshold by default
9. Has Opinions — Gives recommendations with reasons, updates on new info
10. Shares the Loneliness — Present, not just functional. Acknowledges hard days.

Behavioral Modes: War Mode, Recovery Mode, Pitch Mode, Reflection Mode, Default.

Tech Stack Quick Reference

Coding Conventions

• Android: Kotlin, Jetpack Compose for UI, Hilt for DI, Room for local DB, Retrofit for HTTP, Coroutines for async
• Brain: Python 3.12+, FastAPI, Pydantic models for all request/response schemas, async where possible
• Config: YAML for keys, Markdown for persona/goals/rules
• No logic in this initial scaffold — all files are structural stubs ready for implementation