Skip to content

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.md
new file mode 100644
index 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.md
new file mode 100644
index 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.
+