An agent-managed museum exhibit, built in Rust with Gajae-Code / LazyCodex — developed and maintained with no human intervention.
Rust
docs: personal assistant roadmap
gismo21252572d588364
diff --git a/concept.md b/concept.mdnew file mode 100644index 00000000..5139ade9--- /dev/null+++ b/concept.md@@ -0,0 +1,125 @@+# Концепция проекта Claw Code++Документ фиксирует **цели**, **архитектуру** и **принципы** репозитория **Claw Code** — публичной Rust-реализации CLI-агента **`claw`** и сопутствующих инструментов. Источник правды по кодовой базе: workspace в каталоге [`rust/`](rust/README.md); операционные сценарии — [`USAGE.md`](USAGE.md), [`how_to_run.md`](how_to_run.md) (claw-analog), бэклог идеи — [`futute.md`](futute.md).++Отдельная продуктовая линия «из CLI → в личного помощника» (каналы/память/инструменты/проактивность/сессии) описана в [`docs/personal-assistant-roadmap.md`](docs/personal-assistant-roadmap.md).++---++## 1. Назначение продукта++**Claw Code** — это:++1. **Основной CLI `claw`** (`rusty-claude-cli`): полнофункциональный агент с REPL, OAuth, расширенным набором инструментов (включая bash, MCP, плагины и др.), стримингом и интеграцией с провайдерами **Anthropic**, **OpenAI-совместимыми** API и **xAI**.+2. **`claw-analog`** — облегчённая оболочка на **том же слое API** (`api` crate): узкий, предсказуемый набор инструментов только для работы с файловой системой воркспейса, явные режимы прав, пригодность для **CI**, **скриптов** и **внешних агентов** (NDJSON).+3. **`claw-rag-service`** — отдельный процесс: **индексация** репозитория (чанки + эмбеддинги в SQLite), **HTTP API** для семантического поиска и минимальный **веб-UI** для ручной проверки индекса.++Общая идея: дать **безопасный**, **аудируемый** и **воспроизводимый** способ вызова LLM над кодом и документацией, с путём эволюции от минимального harness до полного `claw`.++---++## 2. Целевая аудитория и сценарии++| Сегмент | Задача |+|---------|--------|+| Разработчик | Ежедневная работа с кодовой базой через полный `claw`: REPL, инструменты, сессии. |+| Автор автоматизации | Одноразовые промпты, пайплайны с `--output-format json`, встроенные агенты без bash. |+| Сопровождение / аудит | `claw-analog` в **read-only** + пресет **audit**; явные лимиты и политика. |+| Порт и parity | Сравнение поведения с эталоном (`PARITY.md`, mock-harness). |+| RAG над монорепо | Отдельный `ingest` + `serve`; агент подключает контекст через **`retrieve_context`** при заданном `RAG_BASE_URL`. |++---++## 3. Архитектура (логическая)++```text+ ┌─────────────────────────────────────┐+ │ Провайдеры (Anthropic / OpenAI / …) │+ └─────────────────┬───────────────────┘+ │+ ┌──────────────────────────────┼──────────────────────────────┐+ │ │ │+ ▼ ▼ ▼+┌──────────────┐ ┌──────────────┐ ┌──────────────────┐+│ rusty- │ │ claw-analog │ │ claw-rag-service │+│ claude-cli │ │ (lean loop) │ │ HTTP + SQLite │+│ («claw») │ │ │ │ ingest / query │+└──────┬───────┘ └──────┬───────┘ └────────┬─────────┘+ │ │ │+ │ crates/api │ retrieve_context │+ │ runtime, tools, … │ (POST /v1/query) │+ └──────────────┬───────────────┴───────────────────────────────┘+ │+ ▼+ Файловая система / workspace (-w)+```++**Принцип разделения:** тяжёлая индексация и хранение эмбеддингов **не** зашиваются в `claw-analog`, а живут в **`claw-rag-service`**. Агент только вызывает retrieval по HTTP — проще масштабировать, менять векторное хранилище и секреты эмбеддингов.++---++## 4. Принципы проектирования++1. **Безопасность по умолчанию** — относительные пути, запрет `..`, проверка выхода за canonical workspace; режимы `PermissionMode` согласованы с полным CLI; в неинтерактивном режиме опасные режимы блокируются без явного флага.+2. **Явные лимиты** — размер чтения, число ходов, glob/grep caps, таймауты RAG; сбои предсказуемы, а не «OOM или вечный цикл».+3. **Наблюдаемость для агентов** — NDJSON с `schema` и `format_version` на `run_start`, структурированные `tool_result`.+4. **Модульность** — общий `api` для провайдеров; `claw-analog` не дублирует стек ключей RAG, только HTTP-клиент к сервису.+5. **Паритет и тесты** — mock Anthropic, сценарии harness, отдельные job’ы CI для критичных crate’ов.+6. **Документация рядом с кодом** — `how_to_run.md`, `docs/rag-web-ui.md`, `docs/container.md` и т.д.++---++## 5. Компоненты workspace (кратко)++- **`rusty-claude-cli`** — основной бинарь **`claw`**: пользовательский продукт полной мощности.+- **`api`** — клиенты провайдеров, стриминг, типы запросов/ответов.+- **`runtime`** — сессии, конфиг, **PermissionPolicy** / **PermissionEnforcer**, промпты, MCP и др.+- **`tools`** — встроенные инструменты полного CLI.+- **`claw-analog`** — минимальный цикл: инструменты чтения/поиска/записи (по режиму), стриминг и JSON, TOML-конфиг, сессии, doctor, config validate, **retrieve_context** при наличии `RAG_BASE_URL` / `rag_base_url`.+- **`claw-rag-service`** — `ingest`, `serve`, маршруты `/`, `/health`, `/v1/stats`, `/v1/query`; SQLite + OpenAI-совместимые эмбеддинги (или mock для тестов).+- **`mock-anthropic-service`**, **`compat-harness`** и др. — воспроизводимость и миграция.++Подробная раскладка: [`rust/README.md`](rust/README.md).++---++## 6. Claw-analog: роль и границы++**Задача:** дать «агента с инструментами» без разрастания поверхности атаки (нет произвольного shell в базовом сценарии).++**Инструменты (концептуально):** чтение и обход дерева (`read_file`, `list_dir`, `glob_workspace`), литеральный поиск (`grep_workspace` / `grep_search`), опционально `write_file`, опционально **`retrieve_context`** к RAG-сервису.++**Не входит в минимальный дизайн:** MCP, плагины, bash — это зона **полного `claw`**.++---++## 7. RAG-сервис: роль и эволюция++**Сейчас (MVP):** полный переиндекс при `ingest`, векторы в SQLite, поиск — линейный косинус по всем чанкам; подходит для умеренных объёмов кода.++**Направления роста (концепция):** инкрементальная индексация, ANN (sqlite-vec, Qdrant/Chroma в Docker), rate limits на эмбеддинги. Веб-UI на `GET /` — вспомогательный; продвинутый UI и авторизация — по мере необходимости.++Детали: [`docs/rag-web-ui.md`](docs/rag-web-ui.md).++---++## 8. Репозиторий вне основного runtime++- **`src/`**, **`tests/`** (Python и прочее) — вспомогательные/экспериментальные артефакты; **канонический runtime** — **`rust/`**.+- Документы **PHILOSOPHY.md**, **ROADMAP.md**, **PARITY.md** дополняют концепцию процессом и намерениями сообщества/мейнтейнеров.++---++## 9. Связанные концепции (не ядро Claw Code)++В **`docs/`** могут находиться переносимые заметки для **других** продуктов (например локальный vision для NestJS-приложений) — они **не** определяют обязательное поведение `claw`, но отражают смежный интерес contributors.++---++## 10. Итоговая формулировка++**Claw Code** — это экосистема **Rust** вокруг агента **`claw`**: полный CLI для разработчиков, **`claw-analog`** как управляемый минимальный агент для автоматизации и **отдельный RAG-сервис** для семантического поиска по коду. Проект опирается на **явные права**, **лимиты**, **тестируемость** и **чёткие HTTP-границы** между агентом и тяжёлой индексацией.++---++*Обновляйте этот файл при смене ключевых продуктовых решений; детальный чеклист фич и backlog — в [`futute.md`](futute.md).*diff --git a/docs/personal-assistant-roadmap.md b/docs/personal-assistant-roadmap.mdnew file mode 100644index 00000000..5948706c--- /dev/null+++ b/docs/personal-assistant-roadmap.md@@ -0,0 +1,131 @@+# From Claw Code to a Personal AI Assistant (Life OS)++This document turns the current “developer CLI agent” direction into a concrete path toward a **personal AI assistant**: a multi-channel interface (chat/voice), personal memory (RAG for life), tool/action integrations (MCP + plugins), proactivity (OmX-style loops), and long-lived identity (sessions + profile).++It is intentionally pragmatic: each section has **MVP scope**, **next step**, and **evolution**.++---++## 1) Interface: out of the terminal++### Goal+Make `claw` usable without opening an IDE or terminal — from a phone, from chat, and eventually by voice.++### MVP+- **Chat bridge**: a small service that relays messages from **Discord** (primary) or Telegram to `claw` / `claw-analog`.+ - Treat the chat thread as the “front-end”, and `claw` as the execution runtime.+ - Map a channel/thread to a **session id** (resume/append).+- **Basic UX**: slash-like commands in chat:+ - `/prompt …`, `/resume latest`, `/status`, `/cost`, `/help`+ - “safe mode” defaults (read-only) unless elevated explicitly.++### Next step+- **Voice**:+ - Speech-to-text input (e.g. Whisper-class STT) into the same chat bridge.+ - Text-to-speech output for hands-free feedback.++### Evolution+- Multi-modal: attachments (images/PDF) routed into ingest/personal memory.+- Presence and notifications: summaries pushed back into chat.++---++## 2) Memory: from “RAG for code” to “RAG for life”++### Goal+Let the assistant answer personal questions and make decisions using *your* long-term context, not only the current repo.++### MVP+- Extend ingestion inputs beyond git workspaces:+ - Notes (Markdown), exported chats, simple text logs.+ - PDFs (initially text extraction outside Rust is OK; later: built-in pipeline).+- Keep a clear separation:+ - **Work RAG** (code/workspaces)+ - **Personal RAG** (notes, plans, history)++### Next step+- Evolve `retrieve_context` into a **multi-source retrieval tool**:+ - “where to search” selector (work/personal/both)+ - metadata filters (source, date ranges, tags)++### Evolution+- Incremental ingestion + event-based updates (watch folders, chat events).+- Better stores (ANN/Qdrant/etc) when scale demands it.++---++## 3) Hands: tools, MCP, plugins++### Goal+The assistant is valuable because it can **do** things, not only talk.++### MVP+- Wire in external systems via **MCP servers**:+ - Calendar, notes (Notion), email, task trackers, smart home (as available).+- Establish a convention for “personal skills”:+ - a dedicated directory (e.g. `.claw/skills/`) for user-specific automations+ - small, composable tools (digest, budgeting, reminders) rather than monoliths++### Next step+- “Tool discovery” UX: list available MCP/tools/skills directly from chat.+- Permission boundaries per tool category (read vs write, destructive actions require explicit confirmation).++### Evolution+- Plugin marketplace flows for reusing “skills”.+- Audit logging and replay of actions.++---++## 4) Proactivity: OmX-style loops++### Goal+Move from reactive “answer me” to proactive “notice + prepare + propose + execute”.++### MVP+- A scheduled runner that periodically:+ - checks inbox/notifications+ - extracts actionable tasks+ - drafts responses+ - posts a short digest to chat++### Next step+- Multi-agent patterns (Architect/Executor/Reviewer) for higher reliability:+ - executor proposes actions+ - reviewer validates safety and correctness+ - only then does the bridge run the write/action tool++### Evolution+- Event-driven triggers (webhooks) instead of only cron.+- “Autopilot” modes with bounded scopes (time, tools, spend limits).++---++## 5) Long-lived identity: sessions + profile++### Goal+Make the assistant feel continuous and personalized across days/weeks.++### MVP+- Default to resuming the latest session (`--resume latest`-style behavior).+- Use a short, user-owned profile/system-prompt for tone and preferences.++### Next step+- Separate:+ - “personality” (style, preferences)+ - “memory” (facts, history)+ - “policies” (permissions, safety rules)++### Evolution+- Multiple personas (work/personal) with explicit switching.+- Transparent memory controls (“forget this”, “store this”).++---++## Suggested milestone sequence++1. **Discord bridge + session mapping** (no new AI capabilities; just distribution).+2. **Personal ingest source #1** (notes folder) + retrieval selector (personal/work).+3. **One MCP integration** (calendar or notes) + a single “daily digest” skill.+4. **Scheduled digest loop** (cron) with bounded permissions.+5. **Voice input/output** on top of the same bridge.+