Joyczl Agent

Joy — a local-first personal assistant. Rust core (loop / memory / tools / graph / evals), TypeScript gateways + dashboard, Python thin SDK.

LLM Mart 6 views 377k listing impressions

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

  1. 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-core mega-crate.
  2. The protocol has one definition. joyczl-protocol is the single source of truth for the cross-language contract: types generate the TypeScript and Python bindings, and the artifacts are checked in.
  3. 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

From the project's README.

Comments (0)

Sign in to join the conversation.

No comments yet.