zlaw

README

zlaw

Work in progress. This project is under active development and not ready for everyday use. Expect breaking changes, missing features, and rough edges.

Your personal AI assistant powered by a fleet of specialized agents — runs on your machine, works with any LLM, and gets more useful the longer you use it.

---

Goals

A platform for autonomous agents that work for you. zlaw is built around the idea that a fleet of specialized agents — each with its own personality, model, and toolset — can handle complex, multi-step tasks better than a single monolithic assistant.

Agents that don't forget. Memory stored as plain files, searchable by meaning. Tell the agent something once, it recalls it in future sessions.

You own your data. Everything — config, memory, history — is a plain file you can read, edit, and version-control. No proprietary storage.

Any model, any endpoint. Native Anthropic API with prompt caching, or any OpenAI-compatible endpoint. Swap models without changing behaviour.

---

Non-Goals

Minimal resource footprint. Go is chosen for performance and developer experience, not to run on a Raspberry Pi. If you need a lightweight agent, look elsewhere.

General-purpose AI infrastructure. zlaw is a personal assistant platform, not a replacement for enterprise AI infrastructure or observability tools.

Agent-to-agent direct communication. All inter-agent communication routes through the hub (NATS broker). No peer-to-peer networking.

Local skills only. Skills are Markdown files executed locally — no IPC, no gRPC, no external integrations. Agents use built-in tools for external services.

---

Why zlaw

zlaw is a multi-agent platform built around a hub model: zlaw hub start supervises a fleet of agents over an embedded NATS bus, each with its own personality, model, and toolset. A manager agent routes tasks to specialists automatically.

Each agent runs as a separate process. Planned: configurable isolation per agent — shared user, dedicated OS user, or Docker container.

Everything runs on your machine. Config, memory, and conversation history are plain files — readable, editable, and git-trackable. Single Go binary, no extra runtime required.

---

What you can do with it

Have an assistant that actually knows you.

zlaw builds a memory of facts, preferences, and context as you talk. With proactive saving on, it decides what's worth keeping on its own. You can also be explicit:

you: remember that we deploy every Tuesday and I prefer squash merges

Later, ask anything and it finds the right memory by meaning — not just keyword matching.

Set reminders and recurring tasks by just asking.

you: remind me every Monday morning to review the backlog
you: check my inbox daily at 9am and summarize anything urgent

The agent creates and manages its own scheduled jobs. You can also list or cancel them the same way:

you: what recurring tasks do you have set up?
you: cancel the inbox check

For bulk setup or version-controlled schedules, cron.toml is also supported.

Talk to it from your phone via Telegram.

Connect a Telegram bot and your assistant is always a message away. Each conversation thread keeps its own context — separate sessions for work, personal, and side projects.

Run a fleet of specialist agents.

Start zlaw hub start and it supervises a group of agents, each with its own personality, model, and toolset. Your manager agent takes the request and delegates automatically — the code agent handles the diff, the research agent handles the search, the calendar agent books the meeting. All on your machine, no extra infrastructure.

you: research the top open-source vector databases, then draft a comparison doc

The manager figures out who does what. You just get the result.

Adapters are optional.

Each agent can have zero or more adapters — CLI, Telegram, or others. A common pattern is a headless specialist fleet (no adapters) that only responds to delegation from the manager. But you're also free to give agents their own Telegram bots for direct human interaction, or mix and match as needed.

Manage your session without touching the agent.

Slash commands are handled directly — no LLM call, no cost:

/clear      — start a fresh conversation
/history    — review what's been said this session
/help       — list all available commands

Personality and behaviour files hot-reload on save — no restart needed for those either.

---

Features

Personal assistant

• Any LLM — Anthropic, or any OpenAI-compatible endpoint (Minimax, OpenRouter, Ollama, self-hosted)
• Long-term memory — saved as plain Markdown; recalled by semantic search; human-readable and git-trackable
• Proactive memory saving — agent decides what's worth keeping without being asked; or tell it explicitly
• Scheduled tasks — create, list, and cancel cron jobs by talking to the agent; or define them in cron.toml
• Telegram — session-aware; independent threads per conversation
• Slash commands — /clear, /history, /help handled client-side with no LLM call
• Streaming — tokens arrive as they're generated
• Session persistence — conversations stored as JSONL; resume any session by ID

Multi-agent

Hub supervisor

• zlaw hub start spawns, monitors, and auto-restarts a fleet of agent processes
• Configurable restart policy per agent: always, on-failure, or never
• Per-agent credential injection at spawn time — no secrets in config files

Agent registry & discovery

• Agents register on connect and send heartbeats every 30s
• Hub maintains a live registry of connected agents with their capabilities and roles
• All agents can query the registry to discover peers for delegation

A2A delegation

• Manager agent routes tasks to specialist peers via the agent_delegate tool
• Tasks are wrapped in a structured envelope with result schema
• Messages are durable — JetStream persists them until acknowledged
• Manager agents can stop or restart peer agents via agent_stop / agent_restart

Security model

• Each agent gets a scoped NATS token at spawn time
• Permissions enforced at the broker: specialists can only publish to manager inbox and registry; managers can publish to any agent inbox
• No agent can create or remove other agents — those operations are hub CLI-only
• Lifecycle tools include self-protection: manager cannot stop/restart itself

Durable messaging

• All inter-agent messages flow through JetStream streams
• Unacked messages are redelivered on reconnect — no lost tasks
• WorkQueue retention: messages are deleted after successful processing

Under the hood

• Embedded NATS — agent-to-agent messaging over a local message bus; no external broker needed
• Context window management — token budget with automatic summarisation and layered pruning (thinking → tool results → turns)
• Prompt caching — Anthropic backends cache stable system prompt layers to cut latency and cost
• Hot-reload — personality, scheduled jobs, and runtime config update live on file save

---

Quick start

# Bootstrap workspace (creates zlaw.toml, credentials.toml, manager agent)
zlaw init

# Add LLM credentials
zlaw auth login --profile anthropic --type apikey

# Run a single agent interactively
zlaw agent run -a myagent

# Run as a background daemon (enables Telegram + scheduled tasks)
zlaw agent serve -a myagent

To create an additional named agent:

zlaw init -a myagent

Run multiple agents with a hub

zlaw hub start

# zlaw.toml
[hub]
name = "main"

[nats]
listen = "127.0.0.1:4222"

[[agents]]
name     = "manager"
manager  = true   # receives user input, delegates to peers
workspace = "workspaces/manager"

[[agents]]
name     = "coder"
workspace = "workspaces/coder"

Each agent gets its own agent.toml, SOUL.md, IDENTITY.md, and credentials.toml under agents/<id>/.

---

Configuration

zlaw.toml (hub config)

[hub]
name = "main"              # hub display name
description = "..."        # optional

[nats]
listen = "127.0.0.1:4222"  # NATS server listen address

[[agents]]
name      = "manager"
manager   = true            # receives user input, delegates to peers
workspace = "workspaces/manager"  # agent's working directory
# dir = "agents/manager"     # optional, defaults to agents/<id>

Minimal agent.toml

[agent]
id = "myagent"

[llm]
backend      = "openrouter"
model        = "openai/gpt-4o"
auth_profile = "openrouter"
max_tokens   = 4096

[[adapter]]
type = "cli"    # cli, telegram, or omit for headless

Multi-channel adapters

[[adapter]]
type         = "telegram"
auth_profile = "telegram"

[[adapter]]
type         = "cli"

Memory

[sticky]
proactive_memory_save = true   # agent saves facts without being asked

[memory.embedder]
backend = "openrouter"
model   = "openai/text-embedding-3-small"

Memory files live under $ZLAW_HOME/memories/<id>/ as plain Markdown — readable and editable. The vector index is a local cache; delete it to rebuild.

Context management

[llm]
context_token_budget        = 80000
context_summarize_threshold = 0.8
context_summarize_turns     = 10
context_summarize_model     = "openai/gpt-4o-mini"
context_prune_levels        = ["strip_thinking", "strip_tool_results", "drop_pairs"]
max_memory_tokens           = 2000

---

Docs

• Configuration reference — full agent.toml reference, backends, credentials, context tuning
• Built-in tools — tool reference, allowlist, result limits