English | 简体中文
Joyczl-agent
A local-first personal assistant: Rust owns logic and state, TypeScript covers the browser and chat gateways, Python stays a thin SDK. The state store, reasoning, and tools all run on the user's own machine. Codename Joy — the assistant's persona is Joy too.
Design principles
- Rust owns logic and state. The agent loop, memory, tools, and
state.db live in Rust; crates are split by responsibility (target <500
lines per module), with no
joy-coremega-crate. - The protocol has one definition.
joyczl-protocolis the single source of truth for the cross-language contract: types generate the TypeScript and Python bindings, and the artifacts are checked in. - Clients only translate. The CLI, dashboard, chat gateways, and Python
SDK are all clients of
joy app-server(JSON-RPC over stdio); state.db is opened by exactly one process.
Quick start
cd joy-rs && cargo build
JOY_PROVIDER=deepseek DEEPSEEK_API_KEY=… ./target/debug/joy # terminal REPL
JOY_PROVIDER=deepseek DEEPSEEK_API_KEY=… ./target/debug/joy dashboard # → http://localhost:7777
A turn over raw protocol:
ANTHROPIC_API_KEY=sk-… JOY_HOME=/tmp/joy-demo ./target/debug/joy app-server <<'JSONRPC'
{"jsonrpc":"2.0","id":1,"method":"turn/start","params":{"message":"Remember that Alex likes morning meetings"}}
JSONRPC
The response follows a notification stream: turnStarted → gateDecided → textDelta* → toolStarted → toolCompleted* → turnCompleted. turnCompleted.meta
records the gate ruling, tool timing, which model answered, and token usage —
persisted with the conversation.
What Joy can do
- Converse on the terminal, in the dashboard, or through chat gateways (Telegram, Discord, WeChat, Lark — see docs/gateways.md)
- Remember: semantic facts (FTS5, CJK-capable), dated episodes, and procedural Skills — with a retrieval gate so memory is consulted only when relevant (docs/architecture.md)
- Act: 11 built-in tools plus MCP servers (docs/configuration.md)
- Plan as a graph: the triage front door answers small talk cheaply; the gather workflow writes a morning brief (docs/architecture.md)
- Be examined: deterministic evals gate every release; a judge grades answer quality (docs/testing.md)
- Be observed: every turn lands a trace line and a usage row (docs/architecture.md)
Built-in tools
| Tool | Purpose |
|---|---|
save_note / forget_note / search_memory / list_memory / manage_memory |
memory CRUD |
create_event / list_events |
calendar (idempotent, ICS + optional Apple Calendar sync) |
send_message |
message drafts into the outbox — never actually sends |
search_web |
DuckDuckGo HTML, or Tavily with TAVILY_API_KEY |
read_file |
read a text file: paginated (2000 lines / 50KB, never mid-line), line numbers, a continuation protocol, and a re-read short-circuit; on by default |
list_dir |
list a directory: directories first, files with sizes, 500-entry cap; on by default |
fetch_url |
fetch a page's text (HTML→plain, 50k cap); SSRF guard + external-content-is-data declaration |
No comments yet.