mirror of
https://github.com/open-jarvis/OpenJarvis.git
synced 2026-07-27 21:05:34 +00:00
docs: add user guides for Deep Research, Code Assistant, Monitor, Chat
Four new docs matching the morning-digest.md pattern: - deep-research.md — multi-hop research with document indexing - code-assistant.md — orchestrator with code execution + file I/O - scheduled-monitor.md — persistent operative on cron schedule - chat-simple.md — lightweight chat, simplest setup Updated quickstart with tabs for all agent types and expanded starter configs table from 3 to 7 presets. Updated MkDocs nav and index page to link all 5 user guides. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Jon Saad-Falcon
co-authored by
Claude Opus 4.6
Claude Opus 4.6
parent
e466b54881
commit
638d8780a0
@@ -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 |
|
||||
|
||||
+1
-1
@@ -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)**
|
||||
|
||||
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user