multis 0.1.0

package/.env.example

@@ -0,0 +1,19 @@
+# Telegram Bot Token (get from @BotFather)
+TELEGRAM_BOT_TOKEN=your_bot_token_here
+
+# LLM Provider (anthropic, openai, ollama, gemini)
+LLM_PROVIDER=anthropic
+
+# API Keys (only needed for cloud providers)
+ANTHROPIC_API_KEY=sk-ant-...
+OPENAI_API_KEY=sk-...
+GEMINI_API_KEY=...
+
+# LLM Model
+LLM_MODEL=claude-sonnet-4-5-20250929
+
+# Ollama URL (if using local Ollama)
+OLLAMA_URL=http://localhost:11434
+
+# Pairing Code (generated during init)
+PAIRING_CODE=

package/CLAUDE.md

@@ -0,0 +1,66 @@
+# multis
+
+Personal chatbot/assistant that runs locally. Control your laptop and query your documents from Telegram, Beeper, or Matrix. Local-first, LLM-agnostic, governance-first.
+
+## Tech Stack
+
+- Node.js >= 20, vanilla (minimal deps)
+- Telegraf (Telegram), better-sqlite3 (SQLite + FTS5), pdf-parse, mammoth
+- Beeper Desktop API on localhost:23373 (opt-in)
+- LLM: Anthropic, OpenAI, Ollama (configurable via .env)
+
+## Commands
+
+```
+npm install          # install deps
+npm start            # node src/index.js
+npm run dev          # node --watch src/index.js
+npm test             # node --test test/**/*.test.js
+```
+
+## Project Layout
+
+| Path | Purpose |
+|------|---------|
+| src/index.js | Entry point, starts platforms |
+| src/config.js | Load ~/.multis/config.json + .env |
+| src/bot/handlers.js | Message router, all command handlers |
+| src/platforms/ | Platform adapters (telegram.js, beeper.js, base.js, message.js) |
+| src/governance/ | Allowlist/denylist validation + audit log |
+| src/skills/executor.js | Shell exec, file read |
+| src/indexer/ | Doc parsing, chunking, SQLite FTS5 store |
+| src/llm/ | LLM providers + RAG prompt builder |
+| ~/.multis/ | Runtime data: config.json, governance.json, multis.db, audit.log |
+
+## Key Patterns
+
+1. **Platform abstraction**: All platforms implement base.js, emit normalized Message objects to a shared router in handlers.js
+2. **Command routing**: Telegram uses `/` prefix, Beeper uses `//`. Plain text routes to implicit `/ask` (RAG pipeline)
+3. **Owner model**: First paired user becomes owner. Owner-only commands: exec, read, index. Check with `isOwner(userId, config)`
+
+## Config and Secrets
+
+- API keys in `.env` (TELEGRAM_BOT_TOKEN, ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY, LLM_PROVIDER, LLM_MODEL)
+- Runtime config auto-created at ~/.multis/config.json from .multis-template/
+- Pairing code auto-generated, printed on startup
+
+## POC Status
+
+POC 1-4 done (bot, skills, indexing, RAG). POC 5 next (memory + ACT-R). POC 6 (daemon), POC 7 (multi-platform) planned.
+
+## Constraints
+
+- Each POC < 500 lines
+- No frameworks beyond Telegraf
+- Single user, no shared hosting
+- Telegraf: `bot.on('text')` fires for ALL messages including commands -- filter with `text.startsWith('/')`
+
+## Adding Features
+
+- New command: add handler in handlers.js, add case to createMessageRouter switch, update help text
+- New LLM provider: extend LLMProvider in llm/base.js, add to llm/client.js factory, add env var to config.js
+- New platform: extend platforms/base.js, add to index.js startup
+
+## Deep Reference
+
+-> docs/KNOWLEDGE_BASE.md (topic index with links to full docs)

package/README.md

@@ -0,0 +1,98 @@
+# multis
+
+**A personal and business AI agent that lives in your chat apps** — answering questions from your documents, running commands on your machine, and auto-responding to contacts when you want it to.
+
+Runs locally with persistent memory, governed by allowlists and audit logs.
+
+## Why multis?
+
+- **Local-first:** Your data never leaves your machine
+- **All your chats, one config:** Telegram, WhatsApp, Signal, Discord — via Beeper bridges or self-hosted Matrix
+- **LLM agnostic:** Anthropic, OpenAI, Ollama — swap providers without code changes
+- **Persistent memory:** ACT-R activation decay keeps recent context hot, old conversations fade naturally
+- **Document-aware:** Indexes PDFs and DOCX with hierarchical section-aware chunking, answers with citations
+- **Governed:** Command allowlist/denylist + append-only audit logs
+
+## Quick Start
+
+```bash
+npm install
+cp .env.example .env    # add your bot token + LLM API key
+node src/index.js       # start the bot
+```
+
+Pair with your bot on Telegram using the pairing code shown on startup.
+
+## How It Works
+
+```
+┌──────────────┐  ┌──────────────┐
+│  Telegram    │  │  Beeper      │  (WhatsApp, Signal, Discord, ...)
+│  Bot API     │  │  Desktop API │
+└──────┬───────┘  └──────┬───────┘
+       │                 │
+┌──────▼─────────────────▼──────────────────────┐
+│            Message Router                      │
+│  commands · RAG ask · chat modes · doc upload  │
+└──────┬─────────┬──────────┬───────────────────┘
+       │         │          │
+┌──────▼──┐ ┌───▼────┐ ┌───▼──────────┐
+│ Skills  │ │  LLM   │ │  Indexer     │
+│ (shell, │ │ (any   │ │ (PDF, DOCX,  │
+│  files) │ │ provider│ │  MD → FTS5)  │
+└─────────┘ └────────┘ └──────────────┘
+       │         │          │
+┌──────▼─────────▼──────────▼───────────────────┐
+│  SQLite (FTS5 search · activation decay)       │
+│  Governance (allowlist · denylist · audit log)  │
+└────────────────────────────────────────────────┘
+```
+
+## Why Not openclaw?
+
+Borrowed the good parts — daemon architecture, pairing flow, skill.md pattern — but made it simpler:
+
+- **One config, all chats.** openclaw needs a separate API integration per channel (WhatsApp Baileys, Discord bot, Signal, etc). multis uses one config block and talks to Telegram + Beeper bridges + Matrix — all your networks through one setup.
+- **Persistent activation-decay memory.** ACT-R model (ported from Aurora) means recent context stays hot, old conversations fade naturally. Not just a chat log — a memory with priorities.
+- **Structured document chunking.** Hierarchical section-aware chunking for PDFs and DOCX (also from Aurora). The bot knows which chapter and section a chunk came from, not just raw text.
+- **No gateway, no plugin system.** openclaw has a complex gateway + plugin architecture. multis is a flat router with skills — add a command in one file, done.
+
+## Features
+
+- **Ask questions** — `/ask` or just type naturally. RAG pipeline searches your docs, passes context to the LLM, answers with citations.
+- **Run commands** — `/exec ls ~/Documents` with governance enforcement (allowlist/denylist)
+- **Index documents** — Upload PDFs and DOCX files, or `/index <path>`. Hierarchical chunking preserves document structure.
+- **Chat modes** — Set any Beeper chat to `personal` (self-use) or `business` (auto-respond to incoming messages)
+- **Audit everything** — Append-only tamper-evident log of all commands and actions
+
+## Roadmap
+
+- [x] POC 1: Telegram bot + pairing
+- [x] POC 2: Skills (shell exec, file read, governance)
+- [x] POC 3: Document indexing (PDF/DOCX → FTS5)
+- [x] POC 4: LLM RAG + chat modes
+- [ ] POC 5: Memory (ACT-R activation decay + memory.md)
+- [ ] POC 6: Daemon + CLI onboarding
+- [ ] POC 7: Multi-platform (Beeper Desktop + self-hosted Matrix)
+
+## Tech Stack
+
+Node.js (vanilla, minimal deps) · Telegraf · better-sqlite3 · pdf-parse · mammoth
+
+## Project Structure
+
+```
+src/
+├── bot/handlers.js       # Message router + all command handlers
+├── platforms/            # Telegram + Beeper adapters, normalized Message
+├── llm/                  # Anthropic, OpenAI, Ollama providers + RAG prompts
+├── indexer/              # PDF/DOCX parsing, chunking, SQLite FTS5 store
+├── governance/           # Command validation + audit logging
+├── skills/               # Shell exec, file read
+├── config.js             # ~/.multis/config.json + .env loader
+└── index.js              # Entry point
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "multis",
+  "version": "0.1.0",
+  "description": "A personal chatbot and assistant that runs on your computer",
+  "main": "src/index.js",
+"scripts": {
+    "start": "node src/index.js",
+    "dev": "node --watch src/index.js",
+    "test": "node --test test/**/*.test.js"
+  },
+  "keywords": [
+    "chatbot",
+    "personal-assistant",
+    "telegram",
+    "llm",
+    "rag",
+    "local-first"
+  ],
+  "author": "",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "dependencies": {
+    "@matrix-org/matrix-sdk-crypto-nodejs": "^0.4.0",
+    "better-sqlite3": "^11.7.0",
+    "mammoth": "^1.8.0",
+    "matrix-bot-sdk": "^0.8.0",
+    "pdf-parse": "^1.1.1",
+    "telegraf": "^4.16.3"
+  }
+}

package/skills/capture.md

@@ -0,0 +1,60 @@
+---
+name: capture
+description: Extract durable notes from conversation history for per-chat memory
+---
+
+# Conversation Capture
+
+You are reviewing a conversation from a chat. Extract only what's worth remembering long-term. Skip small talk, greetings, and filler.
+
+## What to extract
+
+**Decisions made**
+- What was decided, by whom, when
+- "We agreed to..." or "Let's go with..."
+
+**Action items**
+- Who needs to do what, by when
+- Follow-ups, next steps, deadlines
+
+**Preferences stated**
+- "I prefer...", "Always do X", "Don't ever..."
+- Communication style, formatting preferences
+
+**Key facts**
+- Names, roles, relationships
+- Dates, numbers, amounts
+- Products, services, accounts mentioned
+
+**Context that would be lost**
+- Why a decision was made (not just what)
+- Constraints or blockers mentioned
+- Emotional tone if relevant (frustrated, happy, urgent)
+
+## Output format
+
+Bullet points, concise, present tense. Group by category. Skip categories with nothing to report.
+
+```
+## Decisions
+- Using Anthropic for LLM provider (chosen over OpenAI for cost)
+
+## Action items
+- Alice to send contract by Friday
+- Follow up on invoice #1234 next week
+
+## Preferences
+- Prefers formal tone in customer messages
+- Wants responses under 3 sentences
+
+## Key facts
+- Alice is the project lead at Acme Corp
+- Budget is $50k for Q1
+```
+
+## What NOT to capture
+
+- Greetings, sign-offs, pleasantries
+- Questions that were fully answered (capture the answer, not the question)
+- Repeated information already in memory
+- Technical debugging back-and-forth (capture the resolution only)

package/skills/files.md

@@ -0,0 +1,38 @@
+---
+name: files
+description: List and read files in allowed directories
+---
+
+# File Operations
+
+List and read files within allowed directories.
+
+## Allowed Directories
+
+By default, you can access:
+- `~/Documents`
+- `~/Downloads`
+- `~/Projects`
+- `~/Desktop`
+
+## Usage
+
+```bash
+# List PDF files
+/files ~/Documents/*.pdf
+
+# List all files in directory
+/files ~/Downloads
+
+# Read a file
+/read ~/Documents/notes.txt
+```
+
+## Denied Directories
+
+These directories are off-limits:
+- `/etc` - System configuration
+- `/var` - System data
+- `/usr` - System binaries
+- `/System` - macOS system files
+- `/bin`, `/sbin` - System binaries

package/skills/shell.md

@@ -0,0 +1,53 @@
+---
+name: shell
+description: Execute safe shell commands (allowlisted by governance)
+---
+
+# Shell Commands
+
+Execute shell commands that are allowed by the governance policy.
+
+## Allowed Commands
+
+By default, these commands are allowed:
+- `ls` - List files
+- `pwd` - Print working directory
+- `cat` - Display file contents
+- `grep` - Search text
+- `find` - Find files
+- `df` - Disk usage
+- `du` - Directory usage
+- `ps` - Process list
+- `curl` - Make HTTP requests
+- `git` - Git operations (safe ones)
+
+## Usage
+
+```bash
+# List files
+/exec ls -la ~/Documents
+
+# Search for text
+/exec grep -r "TODO" ~/Projects
+
+# Check disk space
+/exec df -h
+```
+
+## Denied Commands
+
+These commands are explicitly denied for safety:
+- `rm` - Remove files (too dangerous)
+- `sudo` - Superuser (security risk)
+- `dd` - Disk operations (destructive)
+- `mkfs` - Format disk (destructive)
+- `shutdown` - System control
+- `reboot` - System control
+
+## Confirmation Required
+
+These commands require user confirmation:
+- `mv` - Move files
+- `cp` - Copy files
+- `git push` - Push to remote
+- `npm publish` - Publish package

package/skills/weather.md

@@ -0,0 +1,32 @@
+---
+name: weather
+description: Get current weather (no API key required)
+---
+
+# Weather
+
+Get weather using wttr.in (free, no API key needed).
+
+## Usage
+
+```bash
+# Quick weather
+/exec curl -s "wttr.in/London?format=3"
+# Output: London: ⛅️ +8°C
+
+# Detailed weather
+/exec curl -s "wttr.in/London"
+# Shows full forecast
+
+# Specific location
+/exec curl -s "wttr.in/NewYork?format=%l:+%c+%t"
+# Output: New York: ⛅️ +15°C
+```
+
+## Format Options
+
+- `%l` - Location name
+- `%c` - Weather emoji
+- `%t` - Temperature
+- `%h` - Humidity
+- `%w` - Wind speed