Skip to content

Personal AI, On Personal Devices

Python

docs: add user guides for Deep Research, Code Assistant, Monitor, Chat

Jon Saad-Falcon638d8780a07a
diff --git a/docs/getting-started/quickstart.md b/docs/getting-started/quickstart.md
index 2f5f2ac8..b82c54f3 100644
--- a/docs/getting-started/quickstart.md
+++ b/docs/getting-started/quickstart.md
@@ -54,6 +54,35 @@ OpenJarvis is a modular AI assistant framework. Here's what developers build wit
# Plays a spoken daily briefing with your email, calendar, health, and news
```
+=== "Deep Research"
+
+ ```bash
+ jarvis init --preset deep-research
+ jarvis memory index ~/Documents/papers/
+ jarvis ask "Summarize all documents about transformer architectures"
+ # Multi-hop search across your indexed docs with citations
+ ```
+
+=== "Code Assistant"
+
+ ```bash
+ jarvis init --preset code-assistant
+ jarvis ask "Write a Python script that parses CSV files"
+ # Orchestrator agent with code execution, file I/O, and shell access
+ ```
+
+=== "Scheduled Monitor"
+
+ ```bash
+ jarvis init --preset scheduled-monitor
+ jarvis memory index ~/Documents/
+ jarvis scheduler start
+ jarvis scheduler create \
+ --prompt "Check for new emails about Project X" \
+ --schedule "0 9 * * 1-5" --agent operative
+ # Persistent agent that runs on a cron schedule
+ ```
+
For complete copy-paste patterns, see [Code Snippets](snippets.md).
## Starter Configs
@@ -62,6 +91,10 @@ Copy one of these to `~/.openjarvis/config.toml` to get a pre-configured setup:
| Config | For | What it does |
|--------|-----|-------------|
+| [`chat-simple.toml`](https://github.com/open-jarvis/OpenJarvis/blob/main/configs/openjarvis/examples/chat-simple.toml) | Any machine | Lightweight chat, no tools -- simplest setup |
+| [`code-assistant.toml`](https://github.com/open-jarvis/OpenJarvis/blob/main/configs/openjarvis/examples/code-assistant.toml) | Any machine | Orchestrator agent with code execution, file I/O, shell |
+| [`deep-research.toml`](https://github.com/open-jarvis/OpenJarvis/blob/main/configs/openjarvis/examples/deep-research.toml) | Any machine | Multi-hop research across indexed documents with citations |
+| [`scheduled-monitor.toml`](https://github.com/open-jarvis/OpenJarvis/blob/main/configs/openjarvis/examples/scheduled-monitor.toml) | Any machine | Persistent operative agent on a cron schedule |
| [`morning-digest-mac.toml`](https://github.com/open-jarvis/OpenJarvis/blob/main/configs/openjarvis/examples/morning-digest-mac.toml) | Mac (Apple Silicon) | Daily spoken briefing from email, calendar, health, news |
| [`morning-digest-linux.toml`](https://github.com/open-jarvis/OpenJarvis/blob/main/configs/openjarvis/examples/morning-digest-linux.toml) | Linux / GPU server | Same, with vLLM support |
| [`morning-digest-minimal.toml`](https://github.com/open-jarvis/OpenJarvis/blob/main/configs/openjarvis/examples/morning-digest-minimal.toml) | Any machine | Just Gmail + Calendar |
diff --git a/docs/index.md b/docs/index.md
index 914ebb5e..34fbfa43 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -169,7 +169,7 @@ OpenJarvis is built around five composable layers. Each has a clean interface an
---
- CLI, Python SDK, [Morning Digest](user-guide/morning-digest.md), agents, memory, tools, telemetry, and benchmarks.
+ CLI, Python SDK, and guides for [Morning Digest](user-guide/morning-digest.md), [Deep Research](user-guide/deep-research.md), [Code Assistant](user-guide/code-assistant.md), [Scheduled Monitor](user-guide/scheduled-monitor.md), [Simple Chat](user-guide/chat-simple.md), agents, memory, tools, and telemetry.
- **[Architecture](architecture/overview.md)**
diff --git a/docs/user-guide/chat-simple.md b/docs/user-guide/chat-simple.md
new file mode 100644
index 00000000..eaad5fb4
--- /dev/null
+++ b/docs/user-guide/chat-simple.md
@@ -0,0 +1,154 @@
+# Simple Chat
+
+A lightweight conversational AI with no tools and no agent overhead. This is the simplest possible OpenJarvis setup: just Ollama and a local model. Ideal for general-purpose chat, Q&A, brainstorming, and getting started quickly.
+
+## Quickstart (3 minutes)
+
+### 1. Install Ollama and pull a model
+
+```bash
+# Install Ollama: https://ollama.com
+ollama pull qwen3.5:4b
+```
+
+### 2. Install and initialize OpenJarvis
+
+```bash
+git clone https://github.com/open-jarvis/OpenJarvis.git
+cd OpenJarvis
+uv sync
+jarvis init --preset chat-simple
+```
+
+### 3. Ask a question
+
+```bash
+jarvis ask "What is quantum computing?"
+```
+
+That's it. No API keys, no tools, no cloud -- just a local model answering your questions.
+
+## CLI Commands
+
+```bash
+# Single question
+jarvis ask "Explain the difference between TCP and UDP"
+
+# Interactive chat session (multi-turn conversation)
+jarvis chat
+
+# Start the API server for the browser or desktop app
+jarvis serve
+
+# Override the model for a single query
+jarvis ask -m qwen3.5:9b "Explain general relativity"
+
+# Adjust temperature (0.0 = deterministic, 1.0 = creative)
+jarvis ask -t 0.2 "List the planets in our solar system"
+
+# Output raw JSON
+jarvis ask --json "What is 2+2?"
+```
+
+## Configuration Reference
+
+The preset writes this to `~/.openjarvis/config.toml`:
+
+```toml
+[engine]
+default = "ollama"
+
+[intelligence]
+default_model = "qwen3.5:4b" # Fast and lightweight
+# default_model = "qwen3.5:9b" # Better quality
+# default_model = "llama3.1:8b" # Alternative model
+
+[agent]
+default_agent = "simple" # Single-turn, no tools
+
+[server]
+host = "0.0.0.0"
+port = 8000
+```
+
+### Model options
+
+| Model | Parameters | Speed | Quality | Best for |
+|-------|-----------|-------|---------|----------|
+| `qwen3.5:4b` | 4B | Fast | Good | Quick answers, lightweight hardware |
+| `qwen3.5:9b` | 9B | Balanced | Better | General-purpose chat, explanations |
+| `qwen3.5:35b` | 35B | Slower | Best | Complex reasoning, detailed analysis |
+| `llama3.1:8b` | 8B | Balanced | Good | Alternative if you prefer Meta models |
+
+To switch models, either edit `~/.openjarvis/config.toml` or override per-query:
+
+```bash
+jarvis ask -m qwen3.5:35b "Write a detailed comparison of REST and GraphQL"
+```
+
+To pull a new model:
+
+```bash
+ollama pull qwen3.5:35b
+```
+
+## Using the Browser App
+
+Start the backend server and the React frontend with one command:
+
+```bash
+./scripts/quickstart.sh
+```
+
+This opens [http://localhost:5173](http://localhost:5173) in your browser with a full chat interface, streaming responses, and an energy monitoring dashboard.
+
+To run just the API server (for use with the desktop app or external clients):
+
+```bash
+jarvis serve
+```
+
+The server is OpenAI-compatible, so any client that works with the OpenAI API can point to `http://localhost:8000/v1`.
+
+## Using the Desktop App
+
+1. Start the backend: `jarvis serve` (or `./scripts/quickstart.sh`)
+2. Download and open the desktop app from the [releases page](https://github.com/open-jarvis/OpenJarvis/releases)
+3. The app connects to `http://localhost:8000` automatically
+
+## Switching Models
+
+You can change the default model at any time:
+
+**Edit the config:**
+
+```bash
+# Open the config file
+${EDITOR:-nano} ~/.openjarvis/config.toml
+# Change default_model to your preferred model
+```
+
+**Pull and switch in one step:**
+
+```bash
+ollama pull deepseek-r1:14b
+jarvis ask -m deepseek-r1:14b "Hello"
+```
+
+**Use an environment variable:**
+
+```bash
+OPENJARVIS_MODEL=qwen3.5:9b jarvis ask "Hello"
+```
+
+## Troubleshooting
+
+**"No running engine found"** -- Make sure Ollama is running. Start it with `ollama serve` or open the Ollama desktop app.
+
+**"Model not found"** -- Pull the model first with `ollama pull <model-name>`. List available models with `ollama list`.
+
+**Slow responses** -- Use a smaller model (`qwen3.5:4b`). Check available memory; models need RAM roughly equal to their parameter count in GB (e.g., 9B model needs ~9 GB).
+
+**Want to add tools later?** -- Switch to the [Code Assistant](code-assistant.md) or [Deep Research](deep-research.md) config. Simple chat is intentionally minimal.
+
+**Browser app not loading** -- Make sure both the backend (`jarvis serve`) and frontend are running. The `./scripts/quickstart.sh` script starts both automatically.
diff --git a/docs/user-guide/code-assistant.md b/docs/user-guide/code-assistant.md
new file mode 100644
index 00000000..f124b698
--- /dev/null
+++ b/docs/user-guide/code-assistant.md
@@ -0,0 +1,137 @@
+# Code Assistant
+
+An orchestrator agent with code execution, file I/O, and shell access. It can write scripts, read and explain code, run tests, fix bugs, and execute shell commands -- all locally on your machine.
+
+## Quickstart (5 minutes)
+
+### 1. Install and initialize
+
+```bash
+git clone https://github.com/open-jarvis/OpenJarvis.git
+cd OpenJarvis
+uv sync --extra dev
+jarvis init --preset code-assistant
+```
+
+This writes a pre-configured `~/.openjarvis/config.toml` for the code assistant.
+
+### 2. Start a local LLM via Ollama
+
+```bash
+# Install Ollama: https://ollama.com
+ollama pull qwen3.5:9b
+```
+
+### 3. Ask a coding question
+
+```bash
+jarvis ask "Write a Python script that reads a CSV file and prints the top 5 rows"
+```
+
+The orchestrator agent will plan the approach, write the code, and can execute it if you approve.
+
+## CLI Commands
+
+```bash
+# Ask a coding question (uses orchestrator agent by default with this config)
+jarvis ask "Write a Python script that parses JSON from stdin"
+
+# Read and explain existing code
+jarvis ask "Read main.py and explain the architecture"
+
+# Fix a bug
+jarvis ask "Find and fix the bug in test_utils.py"
+
+# Run tests
+jarvis ask "Run the test suite and summarize any failures"
+
+# Explicitly specify agent and tools
+jarvis ask --agent orchestrator --tools code_interpreter "Calculate the first 20 Fibonacci numbers"
+
+# Interactive chat for iterative coding
+jarvis chat
+```
+
+## Configuration Reference
+
+The preset writes this to `~/.openjarvis/config.toml`:
+
+```toml
+[engine]
+default = "ollama"
+
+[intelligence]
+default_model = "qwen3.5:9b"
+# default_model = "qwen3.5:35b" # Better for complex code tasks
+
+[agent]
+default_agent = "orchestrator" # Multi-turn with tool selection
+max_turns = 10
+
+[tools]
+enabled = ["code_interpreter", "file_read", "file_write", "shell_exec", "web_search", "think", "calculator"]
+```
+
+### Key settings
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `intelligence.default_model` | `qwen3.5:9b` | The model for code generation. Use `qwen3.5:35b` for complex tasks like refactoring or multi-file changes. |
+| `agent.default_agent` | `orchestrator` | Multi-turn agent that picks tools iteratively until it has an answer. |
+| `agent.max_turns` | `10` | Maximum tool-calling iterations. Increase for multi-step tasks. |
+| `tools.enabled` | 7 tools | `code_interpreter` (execute Python), `file_read`, `file_write`, `shell_exec` (run shell commands), `web_search`, `think`, `calculator`. |
+
+### Tools explained
+
+| Tool | What it does |
+|------|-------------|
+| `code_interpreter` | Executes Python code in a sandboxed environment and returns output. |
+| `file_read` | Reads files with path validation. The agent can inspect source code, configs, logs. |
+| `file_write` | Writes or modifies files. The agent can create scripts, patch code, write configs. |
+| `shell_exec` | Runs shell commands (e.g., `git status`, `pytest`, `ls`). |
+| `web_search` | Searches the web for documentation, Stack Overflow answers, etc. |
+| `think` | Internal reasoning scratchpad for planning multi-step solutions. |
+| `calculator` | Evaluates mathematical expressions. |
+
+## Example Tasks
+
+```bash
+# Write a new script
+jarvis ask "Write a Python script that converts YAML to JSON"
+
+# Explain existing code
+jarvis ask "Read src/openjarvis/core/events.py and explain the EventBus pattern"
+
+# Debug a failing test
+jarvis ask "Run pytest tests/test_memory.py -v and fix any failures"
+
+# Refactor code
+jarvis ask "Read utils.py and refactor the parse_config function to use dataclasses"
+
+# Generate tests
+jarvis ask "Read src/openjarvis/tools/calculator.py and write unit tests for it"
+
+# Shell tasks
+jarvis ask "Find all Python files larger than 100KB in this repo"
+```
+
+## Safety Notes
+
+The `shell_exec` and `code_interpreter` tools execute real commands on your machine. Keep these in mind:
+
+- **shell_exec** runs commands in your current user context. It can read, write, and delete files. Avoid running the agent on directories containing sensitive data without reviewing tool calls.
+- **code_interpreter** executes Python code. It has access to your Python environment and installed packages.
+- The agent asks for confirmation before executing potentially destructive commands when running in interactive mode (`jarvis chat`).
+- For stronger isolation, use the sandboxed agent: `jarvis ask --agent sandboxed --tools code_interpreter "..."`, which runs inside a Docker/Podman container.
+
+## Troubleshooting
+
+**"Tool not found: code_interpreter"** -- Make sure your `config.toml` includes `code_interpreter` in the `tools.enabled` list.
+
+**Agent loops without progress** -- Increase `max_turns` if the task is complex, or use a larger model (`qwen3.5:35b`). The 9b model handles most single-file tasks; multi-file refactoring benefits from more parameters.
+
+**Shell command fails** -- The `shell_exec` tool runs commands relative to where you launched `jarvis`. Use `cd /path && command` in your prompt if needed, or run `jarvis` from the project directory.
+
+**Web search not working** -- Install with `uv sync --extra tools-search` and set `TAVILY_API_KEY`.
+
+**Code execution hangs** -- The `code_interpreter` has a default timeout. Long-running scripts will be terminated. Break large tasks into smaller steps.
diff --git a/docs/user-guide/deep-research.md b/docs/user-guide/deep-research.md
new file mode 100644
index 00000000..5d8724c3
--- /dev/null
+++ b/docs/user-guide/deep-research.md
@@ -0,0 +1,165 @@
+# Deep Research
+
+A multi-hop research agent that searches across your indexed documents, cross-references information, and returns answers with citations. It reasons through complex queries step by step, pulling context from multiple sources in your local knowledge base.
+
+## Quickstart (5 minutes)
+
+### 1. Install and initialize
+
+```bash
+git clone https://github.com/open-jarvis/OpenJarvis.git
+cd OpenJarvis
+uv sync --extra dev
+jarvis init --preset deep-research
+```
+
+This writes a pre-configured `~/.openjarvis/config.toml` for the deep research agent.
+
+### 2. Index your documents
+
+```bash
+# Install Ollama: https://ollama.com
+ollama pull qwen3.5:9b
+
+# Index a directory of files
+jarvis memory index ./docs/
+jarvis memory index ~/Documents/papers/
+```
+
+OpenJarvis chunks the content and stores it in a local SQLite/FTS5 database. Supported formats include `.txt`, `.md`, `.pdf`, `.py`, `.json`, `.csv`, and more.
+
+### 3. Ask a research question
+
+```bash
+jarvis ask "Summarize all documents about transformer architectures"
+```
+
+The deep research agent will:
+
+1. Search your indexed documents for relevant chunks
+2. Reason across multiple sources (up to 8 hops)
+3. Synthesize a coherent answer with references to source documents
+
+## CLI Commands
+
+```bash
+# Ask a question (uses deep_research agent by default with this config)
+jarvis ask "What meetings did I have with Alice last month?"
+
+# Explicitly specify the agent
+jarvis ask --agent deep_research "Compare the approaches described in paper-a.pdf and paper-b.pdf"
+
+# Index more documents
+jarvis memory index ~/Downloads/reports/
+jarvis memory index ./notes.md
+
+# Search memory directly
+jarvis memory search "project timeline"
+jarvis memory search -k 20 "budget estimates"
+
+# Check what's indexed
+jarvis memory stats
+```
+
+## Configuration Reference
+
+The preset writes this to `~/.openjarvis/config.toml`:
+
+```toml
+[engine]
+default = "ollama"
+
+[intelligence]
+default_model = "qwen3.5:9b"
+temperature = 0.3 # Low temperature for factual research
+
+[agent]
+default_agent = "deep_research"
+max_turns = 8 # Multi-hop reasoning steps
+
+[tools]
+enabled = ["knowledge_search", "knowledge_sql", "scan_chunks", "think", "web_search"]
+
+[tools.storage]
+default_backend = "sqlite"
+```
+
+### Key settings
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `intelligence.default_model` | `qwen3.5:9b` | The model used for reasoning. Larger models (e.g., `qwen3.5:35b`) give better results on complex queries. |
+| `intelligence.temperature` | `0.3` | Low temperature keeps answers factual. Increase for more creative synthesis. |
+| `agent.max_turns` | `8` | Maximum reasoning hops. Increase for deeply nested research tasks. |
+| `tools.enabled` | 5 tools | `knowledge_search` (semantic), `knowledge_sql` (structured), `scan_chunks` (browse), `think` (reasoning scratchpad), `web_search` (online fallback). |
+| `tools.storage.default_backend` | `sqlite` | FTS5-backed full-text search. Also supports `faiss`, `colbert`, `bm25`, and `hybrid`. |
+
+## Example Queries
+
+```bash
+# Summarize across multiple documents
+jarvis ask "Summarize all emails about the Q3 budget review"
+
+# Cross-reference sources
+jarvis ask "What do papers A and B agree on regarding attention mechanisms?"
+
+# Find specific information
+jarvis ask "What meetings did I have with Alice last month?"
+
+# Extract structured data
+jarvis ask "List all action items from the meeting notes in ~/Documents/meetings/"
+
+# Research with web fallback
+jarvis ask "Compare our internal benchmarks with the latest published results"
+```
+
+## Indexing Different Data Sources
+
+### Local files and directories
+
+```bash
+# Recursively index a directory
+jarvis memory index ~/Documents/
+
+# Single file
+jarvis memory index ./report.pdf
+
+# Custom chunk size for long documents
+jarvis memory index ./paper.pdf --chunk-size 1024 --chunk-overlap 128
+```
+
+### PDFs
+
+PDFs are automatically extracted and chunked. For best results with scanned PDFs, ensure they have been OCR-processed.
+
+```bash
+jarvis memory index ~/Papers/*.pdf
+```
+
+### Web pages
+
+Use the `web_search` tool (enabled by default in this config) to pull in online sources at query time. For persistent indexing of web content, download pages first:
+
+```bash
+curl -s https://example.com/article | jarvis memory index --stdin --source "example.com"
+```
+
+### Code repositories
+
+```bash
+jarvis memory index ./src/ --chunk-size 256
+```
+
+Smaller chunk sizes work better for code, where each function or class is a natural unit.
+
+## Troubleshooting
+
+**"No results found"** -- Make sure you have indexed documents first with `jarvis memory index`. Check indexed content with `jarvis memory stats`.
+
+**Answers are too vague** -- Try increasing `max_turns` in the config (e.g., `12` or `15`) to give the agent more reasoning steps. You can also try a larger model like `qwen3.5:35b`.
+
+**Slow responses** -- The agent makes multiple search passes. Each turn involves a model call. Reduce `max_turns` or use a smaller model (`qwen3.5:4b`) for faster but less thorough results.
+
+**Web search not working** -- The `web_search` tool requires the Tavily API. Install with `uv sync --extra tools-search` and set `TAVILY_API_KEY`.
+
+**Wrong chunks retrieved** -- Try re-indexing with different chunk sizes. For technical documents, smaller chunks (`256`) often retrieve more precisely. For narrative text, larger chunks (`1024`) preserve more context.
diff --git a/docs/user-guide/scheduled-monitor.md b/docs/user-guide/scheduled-monitor.md
new file mode 100644
index 00000000..4b7f91b8
--- /dev/null
+++ b/docs/user-guide/scheduled-monitor.md
@@ -0,0 +1,201 @@
+# Scheduled Monitor
+
+A persistent operative agent that runs on a cron schedule, maintains state across runs, and uses memory to track changes over time. Ideal for daily inbox monitoring, recurring status checks, and long-running research projects.
+
+## Quickstart (5 minutes)
+
+### 1. Install and initialize
+
+```bash
+git clone https://github.com/open-jarvis/OpenJarvis.git
+cd OpenJarvis
+uv sync --extra dev
+jarvis init --preset scheduled-monitor
+```
+
+This writes a pre-configured `~/.openjarvis/config.toml` for the operative agent with scheduling support.
+
+### 2. Start a local LLM via Ollama
+
+```bash
+# Install Ollama: https://ollama.com
+ollama pull qwen3.5:9b
+```
+
+### 3. Index your data
+
+```bash
+jarvis memory index ~/Documents/
+```
+
+The operative agent uses memory to track state across runs, so indexing your data gives it context for the first run.
+
+### 4. Create a scheduled task
+
+```bash
+jarvis scheduler start
+
+jarvis scheduler create \
+ --prompt "Check for new emails about Project X and update your notes" \
+ --schedule "0 9 * * 1-5" \
+ --agent operative \
+ --tools "knowledge_search,knowledge_sql,memory_store,think"
+```
+
+This creates a task that runs at 9 AM every weekday. The operative agent will search your indexed data, process new information, and store notes in memory for the next run.
+
+## How Scheduling Works
+
+The scheduler uses cron expressions to trigger agent runs at specified intervals. Each run is an independent agent session, but the operative agent persists state between sessions.
+
+### Cron expression reference
+
+```
+ .------------ minute (0-59)
+ | .---------- hour (0-23)
+ | | .-------- day of month (1-31)
+ | | | .------ month (1-12)
+ | | | | .---- day of week (0-6, 0=Sunday)
+ | | | | |
+ * * * * *
+```
+
+Common examples:
+
+| Expression | Meaning |
+|------------|---------|
+| `0 9 * * 1-5` | 9 AM, Monday through Friday |
+| `0 6 * * *` | 6 AM every day |
+| `*/30 * * * *` | Every 30 minutes |
+| `0 9,17 * * *` | 9 AM and 5 PM daily |
+| `0 8 1 * *` | 8 AM on the 1st of every month |
+
+### CLI commands
+
+```bash
+# Start the scheduler daemon
+jarvis scheduler start
+
+# Create a new scheduled task
+jarvis scheduler create \
+ --prompt "Summarize any new research papers in my library" \
+ --schedule "0 8 * * *" \
+ --agent operative
+
+# List all scheduled tasks
+jarvis scheduler list
+
+# View task details and run history
+jarvis scheduler status <task-id>
+
+# Pause / resume / delete a task
+jarvis scheduler pause <task-id>
+jarvis scheduler resume <task-id>
+jarvis scheduler delete <task-id>
+
+# Run a task immediately (outside its schedule)
+jarvis scheduler run <task-id>
+
+# Stop the scheduler daemon
+jarvis scheduler stop
+```
+
+## Configuration Reference
+
+The preset writes this to `~/.openjarvis/config.toml`:
+
+```toml
+[engine]
+default = "ollama"
+
+[intelligence]
+default_model = "qwen3.5:9b"
+temperature = 0.3
+
+[agent]
+default_agent = "operative"
+max_turns = 20
+context_from_memory = true # Inject relevant memory into context
+
+[tools]
+enabled = ["knowledge_search", "knowledge_sql", "scan_chunks", "memory_store", "memory_search", "think", "web_search"]
+
+[tools.storage]
+default_backend = "sqlite"
+```
+
+### Key settings
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `intelligence.default_model` | `qwen3.5:9b` | The model used for reasoning. |
+| `intelligence.temperature` | `0.3` | Low temperature for consistent, factual outputs across runs. |
+| `agent.default_agent` | `operative` | Persistent agent that maintains state between sessions. |
+| `agent.max_turns` | `20` | High turn limit for thorough processing of accumulated data. |
+| `agent.context_from_memory` | `true` | Automatically injects relevant memory chunks into the agent's context. |
+| `tools.enabled` | 7 tools | Search, store, scan, and reason tools for reading and writing to the knowledge base. |
+
+### Tools explained
+
+| Tool | What it does |
+|------|-------------|
+| `knowledge_search` | Semantic search across indexed documents. |
+| `knowledge_sql` | Structured queries against the document store. |
+| `scan_chunks` | Browse through document chunks sequentially. |
+| `memory_store` | Write new facts and notes to the knowledge base. |
+| `memory_search` | Search previously stored agent notes. |
+| `think` | Internal reasoning scratchpad for planning. |
+| `web_search` | Search the web for supplementary information. |
+
+## Example Use Cases
+
+### Daily inbox monitor
+
+```bash
+jarvis scheduler create \
+ --prompt "Review my recent emails. Flag anything urgent and summarize the rest. Store a daily summary." \
+ --schedule "0 9 * * 1-5" \
+ --agent operative \
+ --tools "knowledge_search,memory_store,think"
+```
+
+### Research tracker
+
+```bash
+jarvis scheduler create \
+ --prompt "Search for new papers related to 'efficient transformers'. Compare with papers I've already indexed and note what's new." \
+ --schedule "0 8 * * 1" \
+ --agent operative \
+ --tools "knowledge_search,web_search,memory_store,think"
+```
+
+### Status reporter
+
+```bash
+jarvis scheduler create \
+ --prompt "Check the project status documents and generate a weekly progress summary. Note any blockers." \
+ --schedule "0 17 * * 5" \
+ --agent operative \
+ --tools "knowledge_search,knowledge_sql,memory_store,think"
+```
+
+## How State Persistence Works
+
+The operative agent differs from other agents in that it maintains state across runs:
+
+- **Memory storage**: The agent uses the `memory_store` tool to save notes, summaries, and observations. These persist in the local SQLite database and are available in future runs.
+- **Context injection**: With `context_from_memory = true`, the agent automatically receives relevant context from previous runs when it starts a new session.
+- **Accumulated knowledge**: Over time, the agent builds a progressively richer understanding of your data. A Monday run can reference notes from the previous Friday.
+- **All data stays local**: State is stored in `~/.openjarvis/` using the configured memory backend. Nothing leaves your machine.
+
+## Troubleshooting
+
+**"Scheduler not running"** -- Start the scheduler daemon with `jarvis scheduler start`. It must be running for scheduled tasks to execute.
+
+**Task doesn't run on time** -- Check that Ollama is running (`ollama serve`). The scheduler triggers the agent, but the agent needs an inference engine. Verify the schedule with `jarvis scheduler status <task-id>`.
+
+**Agent produces inconsistent results** -- Keep `temperature` at `0.3` or lower for scheduled tasks. Higher temperatures introduce randomness that compounds across runs.
+
+**Memory grows too large** -- Periodically review with `jarvis memory stats`. Clear old entries with `jarvis memory clear --before 2026-01-01` if needed.
+
+**Agent runs too long** -- Reduce `max_turns` or simplify the prompt. The operative agent is thorough and may use all available turns.
diff --git a/mkdocs.yml b/mkdocs.yml
index ac12bea7..c5bec1bc 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -168,6 +168,10 @@ nav:
- CLI: user-guide/cli.md
- Python SDK: user-guide/python-sdk.md
- Morning Digest: user-guide/morning-digest.md
+ - Deep Research: user-guide/deep-research.md
+ - Code Assistant: user-guide/code-assistant.md
+ - Scheduled Monitor: user-guide/scheduled-monitor.md
+ - Simple Chat: user-guide/chat-simple.md
- Agents: user-guide/agents.md
- Channels & Connectors: user-guide/channels-and-connectors.md
- Tools: user-guide/tools.md