From 638d8780a07aec98b4f1305bcd4d21b738d05d4b Mon Sep 17 00:00:00 2001 From: Jon Saad-Falcon <41205309+jonsaadfalcon@users.noreply.github.com> Date: Fri, 3 Apr 2026 15:10:10 -0700 Subject: [PATCH] docs: add user guides for Deep Research, Code Assistant, Monitor, Chat MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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) --- docs/getting-started/quickstart.md | 33 +++++ docs/index.md | 2 +- docs/user-guide/chat-simple.md | 154 ++++++++++++++++++++ docs/user-guide/code-assistant.md | 137 ++++++++++++++++++ docs/user-guide/deep-research.md | 165 ++++++++++++++++++++++ docs/user-guide/scheduled-monitor.md | 201 +++++++++++++++++++++++++++ mkdocs.yml | 4 + 7 files changed, 695 insertions(+), 1 deletion(-) create mode 100644 docs/user-guide/chat-simple.md create mode 100644 docs/user-guide/code-assistant.md create mode 100644 docs/user-guide/deep-research.md create mode 100644 docs/user-guide/scheduled-monitor.md 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 `. 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 + +# Pause / resume / delete a task +jarvis scheduler pause +jarvis scheduler resume +jarvis scheduler delete + +# Run a task immediately (outside its schedule) +jarvis scheduler run + +# 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 `. + +**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