AGENTS.md

Project overview

DrugClaw is a Rust multi-channel agent runtime for Telegram, Discord, and Web. It shares one channel-agnostic agent loop (src/agent_engine.rs) and one provider-agnostic LLM layer (src/llm.rs), with channel adapters for ingress/egress.

Core capabilities:

• Tool-using chat agent loop (multi-step tool calls)
• Session resume and context compaction
• Scheduled tasks + background scheduler
• File memory (AGENTS.md) + structured SQLite memory
• Memory reflector, quality gate, and observability metrics
• Skills + MCP tool federation
• ClawHub skill registry integration (search/install/lockfile)

Tech stack

• Language: Rust (edition 2021)
• CLI args: clap
• Async runtime: Tokio
• Telegram: teloxide
• Discord: serenity
• Web API/UI: axum + React (in web/)
• Database: SQLite (rusqlite)
• LLM runtime: provider abstraction with native Anthropic and OpenAI-compatible providers

Source index (src/ + crates/)

Main orchestration files in src/:

• main.rs: CLI entry (start, setup, etc.)
• runtime.rs: app wiring (AppState), provider/tool initialization, channel boot
• agent_engine.rs: shared agent loop (process_with_agent), explicit-memory fast path, compaction, tool loop
• hooks.rs: hooks discovery/runtime/CLI (hooks list/info/enable/disable)
• llm.rs: provider implementations + stream handling + format translation
• otlp.rs: OTLP metrics exporter (HTTP/protobuf)
• web.rs: Web API router, shared web state, stream APIs, config endpoints
• web/auth.rs: auth handlers (session login/logout, password, API key lifecycle)
• web/config.rs: config read/update + config self-check handlers
• web/sessions.rs: session/history/reset/delete/fork/tree handlers
• web/metrics.rs: metrics snapshot/history handlers
• web/stream.rs: streaming send/status/SSE handlers
• scheduler.rs: scheduled-task runner + memory reflector loop
• skills.rs: skill discovery/activation
• mcp.rs: MCP server/tool integration
• gateway.rs: event stream / request lifecycle infra
• setup.rs: interactive setup wizard and provider presets
• doctor.rs: environment diagnostics
• channels/*.rs: concrete channel adapters (Telegram/Discord/Slack/Feishu)
• tools/*.rs: built-in tool implementations and registry assembly

Modularized crates in crates/:

• drugclaw-core: shared error/types/text (error, llm_types, text)
• drugclaw-storage: SQLite DB, memory domain, usage report assembly
• drugclaw-tools: tool runtime primitives, sandbox, path guards, web/todo helpers
• drugclaw-channels: channel abstractions (channel, channel_adapter, delivery boundary)
• drugclaw-app: app-level support modules (logging, builtin skills, transcribe)

Tool system

src/tools/mod.rs assembles built-in tools, while shared runtime primitives live in drugclaw-tools::runtime:

• Tool trait (name, definition, execute)
• ToolRegistry dispatch and auth context injection
• risk/approval gate for high-risk tools in sensitive contexts

Current built-in tools are generated from code to avoid drift:

• docs/generated/tools.md
• website/docs/generated-tools.md

Regenerate docs artifacts with:

node scripts/generate_docs_artifacts.mjs

Skills Storage

• Default skills dir: <data_dir>/skills (default data_dir is ~/.drugclaw)
• Config override: skills_dir in drugclaw.config.yaml (e.g. ~/.drugclaw/skills)
• Compatibility policy: existing configured data_dir / skills_dir / working_dir keep working; new defaults apply only when unset
• ClawHub lockfile: ~/.drugclaw/clawhub.lock.json

Agent loop (high level)

process_with_agent flow:

1. Optional explicit-memory fast path (remember .../记住...) writes structured memory directly
2. Load resumable session from sessions, or rebuild from chat history
3. Build system prompt from file memory + structured memory context + skills catalog
4. Compact old context if session exceeds limits
5. Call provider with tool schemas
6. If tool_use: execute tool(s), append results, loop
7. If end_turn: persist session and return text

Memory architecture

Two layers:

1. File memory:

• Global: runtime/groups/AGENTS.md
• Chat: runtime/groups/{chat_id}/AGENTS.md

1. Structured memory (memories table):

• category, confidence, source, last_seen, archived lifecycle
• explicit remember fast path
• reflector extraction from conversation history
• dedup/supersede handling with memory_supersede_edges

Observability tables:

• memory_reflector_runs
• memory_injection_logs

Surfaces:

• /api/usage summary block
• /api/memory_observability time-window series API
• Web Usage Panel trends/cards

Database

drugclaw-storage::db includes:

• schema creation + schema-version migrations (db_meta, schema_migrations)
• chat/message/session/task persistence
• structured memory CRUD + archive/supersede
• auth/session/api-key persistence (scopes, expiry, rotation)
• audit log persistence (audit_logs)
• usage and memory observability queries
• metrics history persistence (metrics_history)

Web/API

web.rs routes include:

• chat send/send_stream + SSE stream replay
• auth APIs (/api/auth/*) with session cookie + API key scopes
• sessions/history/reset/delete/fork/tree
• config read/update + self-check (/api/config/self_check)
• audit query (/api/audit)
• metrics APIs (/api/metrics, /api/metrics/summary, /api/metrics/history)
• usage text report (/api/usage)
• memory observability series (/api/memory_observability)

Hooks

Hook assets and spec:

• runtime hook dirs: hooks/<name>/HOOK.md
• hook spec doc: docs/hooks/HOOK.md
• sample hooks: hooks/block-bash/, hooks/redact-tool-output/

Hook runtime supports:

• events: BeforeLLMCall, BeforeToolCall, AfterToolCall
• outcomes: allow, block, modify (structured fields only)

ClawHub

• local doc: docs/clawhub/overview.md
• web doc: website/docs/clawhub.md

Observability Docs

• metrics docs: docs/observability/metrics.md
• operations runbook: docs/operations/runbook.md
• PR/release checklist: docs/releases/pr-release-checklist.md
• upgrade guide: docs/releases/upgrade-guide.md
• regression/stability reports: docs/reports/*.md

OTLP exporter supports bounded queue + retry backoff tuning:

• otlp_queue_capacity
• otlp_retry_max_attempts
• otlp_retry_base_ms
• otlp_retry_max_ms

Build and test

cargo build
cargo test
npm --prefix web run build
npm --prefix website run build

Docs drift guard (CI + local):

node scripts/generate_docs_artifacts.mjs --check

Collaboration conventions

• For the separate website repository (drugclaw.github.io), do not open a PR by default; commit/push directly unless explicitly requested otherwise.