added readme and install script

2026-02-14 00:02:22 -05:00
parent ec8bd80a3d
commit e708dd2a8e
4 changed files with 505 additions and 1 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,249 @@
+<p align="center">
+  <h1 align="center">⚔️ Aetheel</h1>
+  <p align="center">
+    <strong>A personal AI assistant that lives in Slack — with persistent memory, dual runtimes, and zero cloud dependencies.</strong>
+  </p>
+  <p align="center">
+    <a href="#quick-start">Quick Start</a> •
+    <a href="#features">Features</a> •
+    <a href="#architecture">Architecture</a> •
+    <a href="#configuration">Configuration</a>
+  </p>
+</p>
+
+---
+
+## Quick Start
+
+### One-line install
+
+```bash
+curl -fsSL http://10.0.0.59:3051/tanmay/Aetheel/raw/branch/main/install.sh | sh
+```
+
+This will clone the repo, set up a Python virtual environment, install dependencies, and walk you through configuration.
+
+### Manual install
+
+```bash
+git clone http://10.0.0.59:3051/tanmay/Aetheel.git
+cd Aetheel
+uv sync           # or: pip install -r requirements.txt
+cp .env.example .env
+# Edit .env with your Slack tokens
+```
+
+### Run
+
+```bash
+# Default — OpenCode runtime
+uv run python main.py
+
+# Claude Code runtime
+uv run python main.py --claude
+
+# Test mode (echo handler, no AI)
+uv run python main.py --test
+
+# Custom model
+uv run python main.py --model anthropic/claude-sonnet-4-20250514
+
+# Debug logging
+uv run python main.py --log DEBUG
+```
+
+---
+
+## Features
+
+### 🧠 Persistent Memory System
+- **Identity files** — `SOUL.md` (personality), `USER.md` (user profile), `MEMORY.md` (long-term notes)
+- **Hybrid search** — 0.7 vector + 0.3 BM25 keyword scoring over all memory files
+- **Local embeddings** — `fastembed` (ONNX, BAAI/bge-small-en-v1.5, 384-dim), zero API calls
+- **SQLite storage** — FTS5 full-text search + JSON vector embeddings
+- **Session logs** — Conversations auto-saved to `daily/YYYY-MM-DD.md`
+- **File watching** — Memory re-indexes when you edit `.md` files
+
+### 🤖 Dual AI Runtimes
+| Runtime | Flag | System Prompt | Session Continuity |
+|---------|------|---------------|--------------------|
+| **OpenCode** (default) | `--cli` / `--sdk` | XML-injected into message | `--continue --session <id>` |
+| **Claude Code** | `--claude` | Native `--system-prompt` flag | `--continue --session-id <id>` |
+
+Both return the same `AgentResponse` — zero code changes needed to switch.
+
+### 💬 Slack Integration
+- **Socket Mode** — no public URL or webhook needed
+- **DMs + @mentions** — responds in both
+- **Thread isolation** — each thread gets its own AI session
+- **Chunked replies** — auto-splits long responses at Slack's 4000-char limit
+
+### ⏰ Action Tags
+The AI can perform actions by including tags in its response:
+
+```
+[ACTION:remind|2|Time to drink water! 💧]
+```
+
+The system strips the tag from the visible response and schedules the action.
+
+### 🔒 Local-First
+- Embeddings run locally (no OpenAI/Gemini API for memory)
+- Memory stored in `~/.aetheel/` — your data stays on your machine
+- Only the AI runtime (OpenCode/Claude) makes external API calls
+
+---
+
+## Architecture
+
+```
+┌──────────────┐
+│    Slack      │  Socket Mode (no public URL)
+│  Workspace   │
+└──────┬───────┘
+       │ Events (DM, @mention)
+       ▼
+┌──────────────┐     ┌──────────────────┐
+│    Slack     │────▶│   main.py        │
+│   Adapter    │     │   (ai_handler)   │
+└──────────────┘     └────────┬─────────┘
+                              │
+                    ┌─────────┴─────────┐
+                    ▼                   ▼
+           ┌──────────────┐   ┌──────────────┐
+           │  Memory      │   │  AI Runtime   │
+           │  Manager     │   │  (OpenCode    │
+           │              │   │   or Claude)  │
+           │  • SOUL.md   │   │              │
+           │  • USER.md   │   │  subprocess  │
+           │  • MEMORY.md │   │  execution   │
+           │  • search    │   └──────────────┘
+           │  • session   │
+           │    logs      │
+           └──────────────┘
+```
+
+### Project Structure
+
+```
+aetheel/
+├── main.py                    # Entry point — handler, memory init, action tags
+├── adapters/
+│   └── slack_adapter.py       # Slack Socket Mode adapter
+├── agent/
+│   ├── opencode_runtime.py    # OpenCode CLI/SDK runtime
+│   └── claude_runtime.py      # Claude Code CLI runtime
+├── memory/
+│   ├── manager.py             # MemoryManager — sync, search, identity files
+│   ├── embeddings.py          # Local embeddings via fastembed
+│   ├── hybrid.py              # Hybrid search (vector + BM25)
+│   ├── schema.py              # SQLite schema (files, chunks, FTS5)
+│   ├── internal.py            # Hashing, chunking, file discovery
+│   └── types.py               # Config, result types
+├── docs/
+│   ├── memory-system.md       # Memory architecture docs
+│   ├── opencode-setup.md      # OpenCode install & config guide
+│   ├── slack-setup.md         # Slack app setup guide
+│   └── opencode-integration-summary.md
+├── .env.example               # Template for secrets
+├── pyproject.toml             # Dependencies (uv/pip)
+└── install.sh                 # One-click installer
+```
+
+---
+
+## Configuration
+
+### Required: Slack Tokens
+
+| Variable | Where to get it |
+|----------|----------------|
+| `SLACK_BOT_TOKEN` | [api.slack.com/apps](https://api.slack.com/apps) → OAuth & Permissions → Bot Token (`xoxb-...`) |
+| `SLACK_APP_TOKEN` | [api.slack.com/apps](https://api.slack.com/apps) → Basic Info → App-Level Tokens (`xapp-...`) |
+
+See [`docs/slack-setup.md`](docs/slack-setup.md) for full Slack app creation instructions.
+
+### AI Runtime
+
+#### OpenCode (default)
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `OPENCODE_MODE` | `cli` | `cli` (subprocess) or `sdk` (server API) |
+| `OPENCODE_MODEL` | auto | Model, e.g. `anthropic/claude-sonnet-4-20250514` |
+| `OPENCODE_TIMEOUT` | `120` | CLI timeout in seconds |
+| `OPENCODE_SERVER_URL` | `http://localhost:4096` | SDK mode server URL |
+| `OPENCODE_WORKSPACE` | `.` | Working directory for OpenCode |
+
+#### Claude Code (`--claude`)
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `CLAUDE_MODEL` | auto | Model, e.g. `claude-sonnet-4-20250514` |
+| `CLAUDE_TIMEOUT` | `120` | CLI timeout in seconds |
+| `CLAUDE_MAX_TURNS` | `3` | Max agentic tool-use turns |
+| `CLAUDE_NO_TOOLS` | `true` | Disable tools for pure chat |
+
+### Memory System
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `AETHEEL_WORKSPACE` | `~/.aetheel/workspace` | Path to memory files (SOUL.md, etc.) |
+| `AETHEEL_MEMORY_DB` | `~/.aetheel/memory.db` | SQLite database path |
+
+### General
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `LOG_LEVEL` | `INFO` | `DEBUG`, `INFO`, `WARNING`, `ERROR` |
+
+---
+
+## Memory Files
+
+Aetheel auto-creates three identity files in `~/.aetheel/workspace/`:
+
+| File | Purpose |
+|------|---------|
+| `SOUL.md` | Personality, values, communication style |
+| `USER.md` | User preferences, context, background |
+| `MEMORY.md` | Long-term notes, facts, things to remember |
+
+Edit these files directly — changes are picked up automatically via file watching.
+
+Session logs are saved to `~/.aetheel/workspace/daily/YYYY-MM-DD.md` and indexed for search.
+
+---
+
+## Prerequisites
+
+- **Python 3.14+** (managed via [uv](https://docs.astral.sh/uv/))
+- **Slack workspace** with bot + app tokens
+- **One of:**
+  - [OpenCode](https://opencode.ai) CLI — `curl -fsSL https://opencode.ai/install | bash`
+  - [Claude Code](https://docs.anthropic.com/en/docs/claude-code) — `npm install -g @anthropic-ai/claude-code`
+
+---
+
+## Development
+
+```bash
+# Run tests
+uv run python test_memory.py    # Memory system smoke test
+uv run python test_slack.py     # Slack adapter unit tests
+
+# Check help
+uv run python main.py --help
+```
+
+---
+
+## Inspired By
+
+Built with inspiration from [OpenClaw](https://github.com/nichochar/openclaw) — a TypeScript AI agent framework. Aetheel reimplements the core concepts (memory, hybrid search, session management) in Python with a local-first philosophy.
+
+---
+
+<p align="center">
+  <sub>Made with ❤️ and a lot of Claude</sub>
+</p>