opencode-rag-plugin 2.12.0 → 2.12.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/ReadMe.md CHANGED
@@ -1,62 +1,89 @@
1
1
  # OpenCodeRAG
2
2
 
3
- **Semantic code search for AI coding agents — local-first, token-efficient, and fast.**
4
-
5
- OpenCodeRAG indexes your repository as AST-aware chunks with embeddings, then answers natural-language queries with the most relevant code, so an agent no longer has to read whole files to find one function. It installs as an [OpenCode](https://opencode.ai) plugin and also runs as an MCP server or a standalone CLI for other AI harnesses. Everything works locally with [Ollama](https://ollama.ai) by default, and small embedding models run fine on a modern CPU — no dedicated GPU required.
3
+ **A local-first toolkit that gives AI coding agents search, memory, judgment, and guardrails.**
6
4
 
7
5
  [![npm version](https://img.shields.io/npm/v/opencode-rag-plugin.svg)](https://www.npmjs.com/package/opencode-rag-plugin)
6
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
7
+
8
+ AI coding agents are capable, but they have four recurring weaknesses: they read whole files to find one function, they forget everything between sessions, they interrupt you with questions they could settle themselves, and they may run risky shell commands without a second opinion.
9
+
10
+ OpenCodeRAG addresses all these problems and more in one package:
11
+
12
+ - **Semantic Search**: retrieval tools that find relevant code parts by a rough description only
13
+ - **Persistent Memory**: vectorized memory, which keeps gotchas and decisions across sessions and automatically injects them into the context when necessary
14
+ - **Knowledge Base**: agents use and maintain a project wiki to understand the code base better
15
+ - **Basic Judgment**: a small local decision model that answers classification and routing questions
16
+ - **Guardrails**: shell guard, which evaluates shell commands for malignancy before they run
17
+ - **Image Description**: describes images with a local vision model for non-multimodal LLMs
18
+ - **Documentation Assistant**: maintains and adds code documentation where it is still missing or unclear
8
19
 
9
- > **Package name:** install `opencode-rag-plugin`. The npm package `opencode-rag` is an unrelated, discontinued project by a different author.
20
+ OpenCodeRAG is primarily built as an [OpenCode](https://opencode.ai) plugin. But it can also be run as a MCP server for other AI coding platforms or used as a standalone command-line tool. By default it works fully locally via Ollama, but it can also use OpenAI-compatible APIs.
10
21
 
11
- > **Shell Guard (optional):** every `shell`/`bash` command is classified by the local decision model *before it runs*. Flagged commands ask for confirmation with the full verdict (destructive/malicious probabilities plus a risk category); clean commands run unchanged. See [Shell Guard](#shell-guard-optional).
22
+ No GPU is required, although it is recommended when using code and image descriptions. Smaller embedding models can still run fine on a modern CPU.
23
+
24
+ ---
12
25
 
13
26
  ## Contents
14
27
 
15
- - [Why OpenCodeRAG](#why-opencoderag)
16
- - [Quick Start](#quick-start)
17
- - [How It Works](#how-it-works)
18
- - [Features](#features)
19
- - [Using OpenCodeRAG](#using-opencoderag)
20
- - [MCP Tools](#mcp-tools)
21
- - [Plugin-Only Tools](#plugin-only-tools)
22
- - [With OpenCode](#with-opencode)
23
- - [With Other MCP Clients](#with-other-mcp-clients)
24
- - [From the CLI](#from-the-cli)
25
- - [Quirk Memory](#quirk-memory)
26
- - [Decision Model](#decision-model-make_decision)
27
- - [Shell Guard (Optional)](#shell-guard-optional)
28
- - [Documentation and Wiki Modes](#documentation-and-wiki-modes)
29
- - [Image Indexing](#image-indexing)
30
- - [Web UI](#web-ui)
31
- - [Evaluation and Calibration](#evaluation-and-calibration)
28
+ - [What you get](#what-you-get)
29
+ - [Quick start](#quick-start)
30
+ - [How it works](#how-it-works)
31
+ - [Ways to use it](#ways-to-use-it)
32
+ - [Capabilities in detail](#capabilities-in-detail)
33
+ - [1. Semantic code search](#1-semantic-code-search)
34
+ - [2. Quirk memory](#2-quirk-memory)
35
+ - [3. Decision model](#3-decision-model)
36
+ - [4. Shell Guard](#4-shell-guard)
37
+ - [5. Documentation and wiki modes](#5-documentation-and-wiki-modes)
38
+ - [6. Image indexing](#6-image-indexing)
39
+ - [7. Web UI, evaluation, and calibration](#7-web-ui-evaluation-and-calibration)
40
+ - [Tool reference](#tool-reference)
32
41
  - [Configuration](#configuration)
33
- - [Documentation Index](#documentation-index)
34
- - [Privacy and Security](#privacy-and-security)
35
- - [Limitations and Non-Goals](#limitations-and-non-goals)
36
- - [Contributing and Support](#contributing-and-support)
42
+ - [Privacy and security](#privacy-and-security)
43
+ - [Limitations](#limitations)
44
+ - [Documentation index](#documentation-index)
45
+ - [Contributing and support](#contributing-and-support)
37
46
  - [License](#license)
38
47
 
39
- ## Why OpenCodeRAG
48
+ ---
49
+
50
+ ## What you get
51
+
52
+ | Capability | What it does for your agent | On by default |
53
+ |---|---|:---:|
54
+ | **Search** | Finds the relevant code by meaning and by exact symbol name, instead of reading whole files | Yes |
55
+ | **Memory** | Remembers gotchas, decisions, and past tool failures across sessions | Yes |
56
+ | **Decisions** | Classifies, routes, and scores short text locally, without spending agent tokens | No |
57
+ | **Protection** | Checks every shell command for destructive or malicious intent before it runs | No |
58
+ | **Documentation** | Drives the agent to document undocumented code (`/doc`) and to maintain a project wiki (`/wiki`) | Wiki: yes, Doc: no |
59
+ | **Vision** | Makes screenshots and diagrams searchable through generated descriptions | Yes |
60
+ | **Measurement** | Tracks token use, retrieval quality, and decision accuracy, with a web dashboard | Tools, always available |
40
61
 
41
- - **Fewer tokens.** Retrieval returns the handful of relevant chunks instead of whole files, so the agent spends its context on the code that actually matters.
42
- - **Search the way code is written.** AST-aware chunking keeps functions and classes intact, and hybrid vector + keyword search catches both meaning ("where is auth handled?") and exact symbol names.
43
- - **Local by default.** Embeddings, the vector store, and the optional decision model run on your machine. No source code leaves the workspace unless you explicitly configure a hosted provider.
44
- - **Scales with the repository.** Incremental indexing, a background watcher, and an optional shared ClickHouse store keep large or multi-machine workspaces searchable.
62
+ **Why it is built this way**
45
63
 
46
- ## Quick Start
64
+ - **Fewer tokens.** The agent gets the handful of relevant chunks, not entire files.
65
+ - **Search the way code is written.** AST-aware chunking keeps functions and classes intact. Hybrid vector and keyword search catches both meaning ("where is auth handled?") and exact names.
66
+ - **Local by default.** Embeddings, the vector store, and the optional decision model run on your machine. No source code leaves the workspace unless you configure a hosted provider.
67
+ - **Scales with the repository.** Incremental indexing and a background watcher keep the index current. An optional shared ClickHouse store supports large or multi-machine workspaces.
47
68
 
48
- **Prerequisites:** Node.js v22+ and [Ollama](https://ollama.ai) (default provider). [OpenCode](https://opencode.ai) is optional — the CLI and MCP server work without it.
69
+ ---
70
+
71
+ ## Quick start
72
+
73
+ > **Package name:** only install `opencode-rag-plugin`. The npm package `opencode-rag` is an unrelated, discontinued project by a different author.
74
+
75
+ **Prerequisites:** Node.js v22+ and [Ollama](https://ollama.ai) (the default provider). OpenCode is optional; the CLI and MCP server work without it.
49
76
 
50
77
  ```bash
51
78
  # 1. Install the plugin and the CLI
52
79
  npm install -g opencode-rag-plugin
53
80
 
54
81
  # 2. Set up the runtime, the workspace, and your models
55
- # (a short interactive wizard asks which models to use)
82
+ # (a short interactive wizard guides you through the configuration)
56
83
  cd /path/to/your/project
57
84
  opencode-rag setup
58
85
 
59
- # 3. Build the index
86
+ # 3. Build the index (may take a while)
60
87
  opencode-rag index
61
88
 
62
89
  # 4. Search from the terminal
@@ -65,7 +92,7 @@ opencode-rag query "authentication middleware"
65
92
 
66
93
  Example output:
67
94
 
68
- ```text
95
+ ```
69
96
  Querying: "authentication middleware"
70
97
  Top-K: 10
71
98
  Searching 1240 indexed chunks...
@@ -77,30 +104,43 @@ Searching 1240 indexed chunks...
77
104
  ...
78
105
  ```
79
106
 
80
- That is the whole setup. Open OpenCode in the same directory and the agent can use the retrieval tools right away.
107
+ Open OpenCode in the same directory and the agent can use the tools right away.
108
+
109
+ <details>
110
+ <summary><strong>What does <code>opencode-rag setup</code> do?</strong></summary>
111
+
112
+ It handles the whole onboarding in one command:
113
+
114
+ - installs or verifies the machine-level runtime in `~/.opencode/`
115
+ - scaffolds the current workspace (`.opencode/` config, plugin entries, skill files)
116
+ - on the first run, or with `--reconfigure`, starts a **model wizard** for the embedding, description, vision, and decision models
81
117
 
82
- `opencode-rag setup` does the whole onboarding in one command: it installs or verifies the machine-level runtime in `~/.opencode/`, scaffolds the current workspace (`.opencode/` config, plugin entries, skill files), and — on the first run, or whenever you pass `--reconfigure` — walks you through a **model wizard** for the embedding, description, vision, and decision models. A plain re-run just syncs the workspace files. The wizard is scriptable (`--yes`, `--provider`, `--base-url`, `--embedding-model`, `--no-description`, …), and `--skip-runtime` limits the run to the workspace. Use `opencode-rag update` to upgrade the runtime to a newer release.
118
+ A plain re-run only syncs the workspace files. The wizard is scriptable (`--yes`, `--provider`, `--base-url`, `--embedding-model`, `--description off`, and more), and `--skip-runtime` limits the run to the workspace. Use `opencode-rag update` to upgrade the runtime to a newer release.
83
119
 
84
- **Other package managers:** `pnpm add -g opencode-rag-plugin`, `yarn global add opencode-rag-plugin`, and `bun add -g opencode-rag-plugin` work as drop-in replacements. Setup and update detect the package manager that owns the install, so npm does not need to be on `PATH`.
120
+ `pnpm add -g`, `yarn global add`, and `bun add -g` work as drop-in replacements for npm. Setup and update detect which package manager owns the install.
121
+
122
+ </details>
85
123
 
86
124
  ### Optional add-ons
87
125
 
88
- These switchers are off by default and can be turned on later:
126
+ These are off by default and can be enabled later:
127
+
128
+ | Add-on | Enable with | Requires |
129
+ |---|---|---|
130
+ | [Shell Guard](#4-shell-guard) | `shellGuard.enabled` or `setup --shell-guard on` | tev1 via Ollama ≥ 0.35 |
131
+ | [Decision model](#3-decision-model) | `decision.enabled` or `setup --decision on` | tev1 via Ollama ≥ 0.35 |
132
+ | [Documentation mode](#documentation-mode-doc) | `documentationMode.enabled` | nothing extra |
133
+ | [Shared ClickHouse Vector Database](doc/clickhouse.md) | `vectorStore.provider: "clickhouse"` or `setup --vector-store clickhouse` | a ClickHouse server |
89
134
 
90
- | Add-on | Default | Enable with | Requires |
91
- |---|---|---|---|
92
- | [Shell Guard](#shell-guard-optional) | off | `shellGuard.enabled` (or `setup --shell-guard on`) | tev1 via Ollama ≥ 0.35 |
93
- | [Decision model](#decision-model-make_decision) | off | `decision.enabled` (or `setup --decision on`) | tev1 via Ollama ≥ 0.35 |
94
- | [Documentation mode](#documentation-mode-doc) | off | `documentationMode.enabled` | nothing extra |
95
- | [Shared ClickHouse store](doc/clickhouse.md) | off | `vectorStore.provider: "clickhouse"` (or `setup --vector-store clickhouse`) | a ClickHouse server |
135
+ Two features are **on** by default and worth disabling if they do not fit your setup: [image descriptions](#6-image-indexing) (`imageDescription.enabled`, needs a vision model) and [wiki mode](#wiki-mode-wiki) (`wikiMode.enabled`).
96
136
 
97
- Two more are on by default and worth switching off if they do not fit your setup: [image descriptions](#image-indexing) (`imageDescription.enabled`, needs a vision model) and [wiki mode](#wiki-mode-wiki) (`wikiMode.enabled`, no extra setup).
137
+ > **Contributors:** clone the repo and run `npm install --legacy-peer-deps; npm run build`. See the [development docs](doc/development.md).
98
138
 
99
- > **Contributors / developers:** clone the repo and run `npm install --legacy-peer-deps; npm run build` — see the [development docs](doc/development.md).
139
+ ---
100
140
 
101
- ## How It Works
141
+ ## How it works
102
142
 
103
- ```text
143
+ ```
104
144
  Workspace files
105
145
  │ tree-sitter chunking (AST-aware)
106
146
  ▼
@@ -111,84 +151,37 @@ Chunks ─────► embeddings ─────► vector store (LanceDB by
111
151
  Query ─► vector search + keyword search ─► weighted fusion ─► top-K chunks
112
152
  ```
113
153
 
114
- 1. **Index** — files are split into semantic chunks, optionally described by a local LLM, embedded, and stored alongside a TF×IDF keyword index. A file-hash manifest means only changed files are reprocessed, and a background watcher keeps the index current while you work.
115
- 2. **Retrieve** — the query is embedded and matched against both signals. The scores are fused and post-processed (dedup, per-file chunk limits, adjacent-chunk merging) to fit the context window.
116
- 3. **Use** — the agent calls `search_semantic`, `get_file_skeleton`, or `find_usages` instead of reading entire files.
117
-
118
- ## Features
119
-
120
- **Retrieval**
121
-
122
- - AST chunking for 26 languages via tree-sitter, plus documents (Markdown, LaTeX, PDF, DOCX, Excel) and images.
123
- - Hybrid search combining vector similarity with TF×IDF keyword matching; the keyword index is repaired from the store whenever it drifts behind it, so the BM25 half never covers only part of the corpus.
124
- - Retrieval calibration with `opencode-rag eval:tune` against a labelled golden set.
125
- - Context optimization: dedup, per-file chunk limits, adjacent-chunk merging.
126
- - Configurable parsers — remap file extensions to any parser via `chunking.parsers` (e.g. `.c` → `cpp`); the override applies to chunking, `get_file_skeleton`, and read labels ([docs](doc/chunking.md#parser-overrides-per-extension-chunkingparsers)).
127
-
128
- **Agent integration**
129
-
130
- - OpenCode plugin with three discovery paths: skill files, system-prompt guidance, and on-demand RAG context on `Ctrl+Enter` / `Ctrl+Alt+Enter`.
131
- - MCP server for Claude Desktop, Cursor, and any other MCP-compatible client.
132
- - Read-tool override that adds supplementary RAG chunks to normal file reads.
133
- - TUI settings panel for models, retrieval options, and keybindings.
134
- - `AGENTS.md` directive: workspace setup merges a tool-usage directive into `AGENTS.md` via sentinel markers.
135
-
136
- **Memory and decisions**
137
-
138
- - [Quirk memory](#quirk-memory): persistent, cross-session gotchas and decisions with automatic injection into the agent's context.
139
- - [Decision model](#decision-model-make_decision): local classification, routing, and scoring of short text — no agent tokens spent.
140
- - Failed tool calls are recorded as quirks, so a later session starts with the fix already known.
141
-
142
- **Operations**
143
-
144
- - Incremental indexing with a file-hash manifest, background watcher, and automatic rebuild on corruption.
145
- - Optional ClickHouse backend for one shared index across many machines and workspaces, with HNSW ANN, epoch rebuilds, and state sync ([docs](doc/clickhouse.md)).
146
- - Session-level token and cost analysis: RAG-on vs RAG-off comparison with tiktoken BPE counting.
147
- - Alternate providers: embedding via Ollama, OpenAI-compatible endpoints, or Cohere; description and vision via Anthropic, Google Gemini, or OpenAI-compatible endpoints, with API-key auto-resolution.
148
- - Proxy-aware HTTP with a raw-socket localhost bypass.
154
+ 1. **Index.** Files are split into semantic chunks, optionally described by a local LLM, embedded, and stored next to a TF×IDF keyword index. A file-hash manifest means only changed files are reprocessed, and a background watcher keeps the index current while you work.
155
+ 2. **Retrieve.** The query is embedded and matched against both signals. The scores are fused and post-processed (deduplication, per-file chunk limits, adjacent-chunk merging) to fit the context window.
156
+ 3. **Use.** The agent calls `search_semantic`, `get_file_skeleton`, or `find_usages` instead of reading entire files.
149
157
 
150
- ## Using OpenCodeRAG
158
+ The other capabilities build on the same foundation. For example, quirk memories are embedded and stored in the same vector store as your code.
151
159
 
152
- ### MCP Tools
160
+ ---
153
161
 
154
- These five tools are the whole retrieval surface. Inside OpenCode the plugin registers them in-process; over MCP they are served by `opencode-rag mcp`.
162
+ ## Ways to use it
155
163
 
156
- | Tool | What it does | When the agent uses it |
164
+ | Mode | Best for | How to start |
157
165
  |---|---|---|
158
- | `search_semantic` | Hybrid vector + keyword search over the indexed code | Before a code task, instead of reading whole files |
159
- | `get_file_skeleton` | AST outline of a file (functions, classes, methods) | To orient in a large file before reading it |
160
- | `find_usages` | Every reference to a symbol | Before editing a function, class, or variable |
161
- | `describe_image` | Describes an image with the configured vision model | When the task involves a screenshot, diagram, or other asset |
162
- | `make_decision` | Classifies, routes, or scores short text (needs `decision.enabled`) | When the answer reduces to a choice, a yes/no check, or a rubric score |
163
-
164
- ### Plugin-Only Tools
165
-
166
- The quirk tools are registered by the OpenCode plugin (not served over MCP):
167
-
168
- | Tool | What it does |
169
- |---|---|
170
- | `recall_quirks` | Recalls stored gotchas, preferences, and decisions from past sessions |
171
- | `add_quirk` | Stores a new non-obvious fact, workaround, or convention |
172
- | `update_quirk` | Corrects a stored quirk that is outdated or wrong |
173
- | `delete_quirk` | Removes a quirk that is fixed, obsolete, or no longer applies |
166
+ | **OpenCode plugin** | Day-to-day agent work with the full feature set (hotkeys, memory, Shell Guard, `/doc`, `/wiki`) | `opencode-rag setup`, then open OpenCode |
167
+ | **MCP server** | Claude Desktop, Cursor, and any other MCP-compatible client | `opencode-rag mcp` |
168
+ | **CLI** | Scripts, CI, and manual exploration | `opencode-rag <command>` |
174
169
 
175
170
  ### With OpenCode
176
171
 
177
- **Discovery.** Workspace setup creates `.opencode/skills/opencode-rag/SKILL.md` (tool workflow) and `.opencode/skills/make-decision/SKILL.md` (decision-model guidance). Agents load them on demand, so idle sessions pay almost no token cost. When the index contains chunks, a brief tool list is also prepended to the system prompt so agents know the tools exist — skipped when nothing is indexed, to save tokens.
172
+ - **Discovery.** Workspace setup creates `.opencode/skills/opencode-rag/SKILL.md` (tool workflow) and `.opencode/skills/make-decision/SKILL.md` (decision-model guidance). Agents load them on demand, so idle sessions pay almost no token cost. When the index contains chunks, a brief tool list is also added to the system prompt. It is skipped when nothing is indexed.
173
+ - **Hotkeys.** `Ctrl+Enter` appends a relevant file list to the prompt you are typing. `Ctrl+Alt+Enter` appends full code chunks. The query is taken from your typed text; if the prompt is empty, a toast reminds you to type first. Results land directly in the prompt as code blocks with file paths, line ranges, and relevance scores.
174
+ - **Read override.** A normal `read` can return the file plus supplementary RAG chunks relevant to the surrounding work.
175
+ - **Settings.** Models, retrieval options, and keybindings are configurable in the TUI settings panel (`Alt+S` or `/rag-settings`).
176
+ - **`AGENTS.md` directive.** Workspace setup merges a tool-usage directive into `AGENTS.md` using sentinel markers.
178
177
 
179
- **Hotkeys.** `Ctrl+Enter` appends a relevant file list to the prompt you are typing; `Ctrl+Alt+Enter` appends full code chunks. The query is taken from your typed text — if the prompt is empty, a toast reminds you to type first. Results land directly in the prompt as code blocks with file paths, line ranges, and relevance scores; no dialog is opened. Keybindings are configurable in the settings menu (Alt+S, or type `/rag-settings`).
180
-
181
- **Read override.** A normal `read` can return the file plus supplementary RAG chunks that are relevant to the surrounding work.
182
-
183
- ### With Other MCP Clients
184
-
185
- <a id="mcp-server"></a>
178
+ ### With other MCP clients
186
179
 
187
180
  ```bash
188
181
  opencode-rag mcp
189
182
  ```
190
183
 
191
- The MCP server is optional and only needed when an *external* client connects. Inside OpenCode the tools are registered in-process and the hotkey hook runs in-process too. The plugin auto-starts the server only when `mcp.enabled` is `true` (default `false`); clients can also configure it manually, and workspace setup can register it for you.
184
+ The MCP server is only needed when an *external* client connects. Inside OpenCode the tools are registered in-process. The plugin auto-starts the server only when `mcp.enabled` is `true` (default `false`). Clients can also configure it manually, and workspace setup can register it for you.
192
185
 
193
186
  ### From the CLI
194
187
 
@@ -200,11 +193,26 @@ opencode-rag status # index health and coverage
200
193
  opencode-rag ui # open the web dashboard
201
194
  ```
202
195
 
203
- Further commands: `list`, `show <file>`, `dump`, `clear`, `describe-image`, `decide`, `mcp`, `update`, `clickhouse`, `quirk`, and the `eval:*` family. Run `opencode-rag --help` or see the [CLI reference](doc/cli.md) for every command, flag, and example.
196
+ Further commands: `list`, `show <file>`, `dump`, `clear`, `describe-image`, `decide`, `mcp`, `update`, `clickhouse`, `quirk`, and the `eval:*` family. Run `opencode-rag --help` or see the [CLI reference](doc/cli.md).
197
+
198
+ ---
199
+
200
+ ## Capabilities in detail
201
+
202
+ ### 1. Semantic code search
203
+
204
+ The core of the project. It answers natural-language queries with the most relevant code.
204
205
 
205
- ## Quirk Memory
206
+ - **Languages and formats.** AST chunking for 26 languages via tree-sitter, plus documents (Markdown, LaTeX, PDF, DOCX, Excel) and images.
207
+ - **Hybrid search.** Vector similarity combined with TF×IDF keyword matching. The keyword index is repaired from the store whenever it drifts behind, so the keyword half never covers only part of the corpus.
208
+ - **Context optimization.** Deduplication, per-file chunk limits, and adjacent-chunk merging.
209
+ - **Configurable parsers.** Remap file extensions to any parser via `chunking.parsers` (for example `.c` → `cpp`). The override applies to chunking, `get_file_skeleton`, and read labels ([docs](doc/chunking.md#parser-overrides-per-extension-chunkingparsers)).
210
+ - **Alternate providers.** Embeddings via Ollama, OpenAI-compatible endpoints, or Cohere. Descriptions and vision via Anthropic, Google Gemini, or OpenAI-compatible endpoints.
211
+ - **Scale.** Incremental indexing, a background watcher, and automatic rebuild on corruption. The optional ClickHouse backend provides one shared index across machines and workspaces, with HNSW ANN, epoch rebuilds, and state sync ([docs](doc/clickhouse.md)).
206
212
 
207
- Quirk memory gives your agent a **persistent, cross-session memory** of non-obvious facts — gotchas, preferences, decisions, and environment constraints. Quirks are embedded and stored in the same vector store as your code, then injected into the agent's context whenever their relevance clears a configurable threshold. The agent stops repeating the same mistake and accumulates project knowledge over time.
213
+ ### 2. Quirk memory
214
+
215
+ Quirk memory gives the agent a **persistent, cross-session memory** of non-obvious facts: gotchas, preferences, decisions, and environment constraints. Quirks are embedded in the same vector store as your code and injected into the agent's context when their relevance clears a configurable threshold. The agent stops repeating the same mistake and accumulates project knowledge over time.
208
216
 
209
217
  **Enabled by default.** Configure it in `opencode-rag.json`:
210
218
 
@@ -226,35 +234,36 @@ Quirk memory gives your agent a **persistent, cross-session memory** of non-obvi
226
234
  }
227
235
  ```
228
236
 
229
- **How injection works.** On every user message the plugin searches for quirks related to the combined agent response and user query, and injects only those whose raw vector similarity clears `autoInjectMinScore` (default 0.75). Manual `recall_quirks` calls use the slightly looser `recallMinScore` (default 0.72) — raise it to 0.85 to keep only strongly related quirks out of unrelated tasks. A latency budget (`autoInjectLatencyBudgetMs`, default 2000 ms) keeps a slow embedder from blocking message processing, and each quirk is injected **at most once per session**. Every `add_quirk` and every content-changing `update_quirk` passes an immutable trust monitor that rejects destructive patterns (`rm -rf`, `force push`, `bypass security`).
237
+ **Three ways memory works**
230
238
 
231
- **Failed tool calls become memory.** When a tool call fails, the plugin looks for a stored quirk that covers the failure and injects it into the next request (`memory.injectOnToolError`). If no quirk covers it, it writes one (`memory.autoCreateOnToolError`) from a deterministic template built from the tool name and the error text — no LLM involved. The new quirk is tagged `tool-error` and recorded for *future* sessions; it is deliberately excluded from the generic auto-injection, so a raw error dump never leaks into an unrelated turn. Creation is bounded by a per-session budget (2) and a per-error cooldown (10 minutes), and it is suppressed when a quirk for the same tool and cause class already exists.
239
+ | Mechanism | What happens |
240
+ |---|---|
241
+ | **Auto-injection** | On every user message, quirks related to the query and the agent's last response are injected if their vector similarity reaches `autoInjectMinScore` (0.75). Each quirk is injected at most once per session. A latency budget (`autoInjectLatencyBudgetMs`, 2000 ms) keeps a slow embedder from blocking messages. |
242
+ | **Learning from failures** | When a tool call fails, the plugin looks for a matching quirk and injects it into the next request (`injectOnToolError`). If none exists, it writes one from a deterministic template built from the tool name and error text, with no LLM involved (`autoCreateOnToolError`). These quirks are tagged `tool-error`, kept for *future* sessions, and excluded from generic auto-injection. Creation is limited to 2 per session, with a 10-minute cooldown per error, and is skipped if a quirk for the same tool and cause already exists. |
243
+ | **Prevention** | Known durable failure patterns are injected into the system prompt *before* the model picks a tool (`toolErrorProactiveInject`), scoped to the tools the session can actually call. Transient causes such as rate limits are never warned about in advance. The first occurrence of a failure is unavoidable; every later session is warned up front. |
232
244
 
233
- **Prevention, not just learning.** Known failure patterns are also injected into the **system prompt before the model picks a tool** (`memory.toolErrorProactiveInject`), scoped to the tools the session can actually call and to durable failure causes only — a rate limit is never warned about in advance, because the next call will not fail the same way. The first occurrence of a failure is unavoidable; every later session is warned up front.
245
+ **Safety.** Every `add_quirk` and every content-changing `update_quirk` passes an immutable trust monitor that rejects destructive patterns (`rm -rf`, `force push`, `bypass security`).
234
246
 
235
- **CLI — manage quirks directly:**
247
+ **Manual control from the CLI**
236
248
 
237
249
  ```bash
238
250
  opencode-rag quirk add "npm needs --legacy-peer-deps" --type gotcha --tag installation
239
251
  opencode-rag quirk list
240
252
  opencode-rag quirk update <id> --content "..." --type decision
241
253
  opencode-rag quirk rm <id>
242
- opencode-rag quirk lint # flag low-confidence / stale / duplicate quirks
254
+ opencode-rag quirk lint # flag low-confidence, stale, or duplicate quirks
243
255
  opencode-rag quirk test "npm needs --legacy-peer-deps"
244
- # ✓ Quirk has been appended:
245
- # [gotcha] npm needs --legacy-peer-deps (installation)
246
- # 99% confidence
247
256
  ```
248
257
 
249
- See [Plugin documentation](doc/plugin.md#9-quirk-memory-experiential-memory) and [CLI reference: `quirk`](doc/cli.md#quirk).
258
+ Manual `recall_quirks` calls use the looser `recallMinScore` (0.72). Raise it to 0.85 to keep unrelated quirks out of unrelated tasks. See the [plugin docs](doc/plugin.md#9-quirk-memory-experiential-memory) and the [CLI reference](doc/cli.md#quirk).
250
259
 
251
- ## Decision Model (`make_decision`)
260
+ ### 3. Decision model
252
261
 
253
- OpenCodeRAG answers fast **classification, routing, policy, and scoring questions** with a local decision model — Together AI's [tev1](https://ollama.com/library/tev1) via Ollama's `/v1/systemone` endpoint. Unlike chat models, tev1 scores a short `state` against 1–64 named questions and returns the chosen option with probabilities — typically in **40–150 ms warm**, without spending agent tokens.
262
+ A small local model answers fast **classification, routing, policy, and scoring questions**, so the agent does not spend its own tokens on them. OpenCodeRAG uses Together AI's [tev1](https://ollama.com/library/tev1) via Ollama's `/v1/systemone` endpoint. Unlike chat models, tev1 scores a short `state` against 1 to 64 named questions and returns the chosen option with probabilities, typically in **40 to 150 ms warm**.
254
263
 
255
264
  | Question type | Use it for | Example |
256
265
  |---|---|---|
257
- | `choice` | Pick one of 2–24 options | "Which support intent is this?" → duplicate_charge / cancel / none |
266
+ | `choice` | Pick one of 2 to 24 options | "Which support intent is this?" → duplicate_charge / cancel / none |
258
267
  | `noul` | True/false probability | "Does the customer explicitly ask for a refund?" |
259
268
  | `score` | Place the input on a rubric | "How severe is this incident?" → cosmetic … critical |
260
269
 
@@ -271,21 +280,21 @@ One call, two questions:
271
280
  }
272
281
  ```
273
282
 
274
- ```text
275
- **Decision** — ollama/tev1:0.8b
283
+ ```
284
+ Decision — ollama/tev1:0.8b
276
285
 
277
- - **intent** = `duplicate_charge` (confidence 0.97)
278
- - **refund** = true (p=0.96)
286
+ - intent = duplicate_charge (confidence 0.97)
287
+ - refund = true (p=0.96)
279
288
  ```
280
289
 
281
- **Prerequisites:** Ollama ≥ 0.35 and a pulled model:
290
+ **Setup**
282
291
 
283
292
  ```bash
284
- ollama pull tev1:0.8b # 812 MB, fast — good for quick labels and CI
285
- ollama pull tev1:4b # 4.4 GB, more accurate — recommended when scoring
293
+ ollama pull tev1:0.8b # 812 MB, fast: good for quick labels and CI
294
+ ollama pull tev1:4b # 4.4 GB, more accurate: recommended for scoring
286
295
  ```
287
296
 
288
- **Disabled by default** — opt in via `decision.enabled`:
297
+ Requires Ollama ≥ 0.35. **Disabled by default.** Opt in via `decision.enabled`:
289
298
 
290
299
  ```json
291
300
  {
@@ -299,15 +308,20 @@ ollama pull tev1:4b # 4.4 GB, more accurate — recommended when scoring
299
308
  }
300
309
  ```
301
310
 
302
- **Using it well:** always include a `none` / "cannot be determined" option; keep `state` to the relevant excerpt (the effective context is ~2k tokens); treat `confidence < ~0.3` as undecided; do not use it for factual recall or as the only check for high-stakes decisions.
311
+ **Using it well**
303
312
 
304
- **Pre-ask routing (optional):** with `decision.routeBeforeAsking: true`, the injected agent guidance tells the agent to resolve option choices through `make_decision` before asking you — proceeding on a confident answer and asking only when the model is undecided or the choice is preference-based. Off by default.
313
+ - Always include a `none` / "cannot be determined" option.
314
+ - Keep `state` to the relevant excerpt (effective context is about 2k tokens).
315
+ - Treat `confidence < ~0.3` as undecided.
316
+ - Do not use it for factual recall, or as the only check for high-stakes decisions.
305
317
 
306
- `opencode-rag decide` exposes the same engine from the CLI, and workspace setup creates a dedicated `make-decision` agent skill. See [Plugin documentation](doc/plugin.md#make_decision) and [Configuration](doc/configuration.md#decision).
318
+ **Pre-ask routing (optional).** With `decision.routeBeforeAsking: true`, the agent is told to resolve option choices through `make_decision` before asking you. It proceeds on a confident answer and asks only when the model is undecided or the choice is a matter of preference. Off by default.
307
319
 
308
- ## Shell Guard (Optional)
320
+ `opencode-rag decide` exposes the same engine from the CLI, and workspace setup creates a dedicated `make-decision` agent skill. See the [plugin docs](doc/plugin.md#make_decision) and the [configuration reference](doc/configuration.md#decision).
309
321
 
310
- The same local decision model can vet **every shell command before it runs**. With `shellGuard.enabled: true`, each `shell`/`bash` call is classified for destructive and malicious intent; a command whose `p(destructive)` or `p(malicious)` reaches the threshold is escalated to OpenCode's confirmation prompt with the full verdict — otherwise it executes unchanged.
322
+ ### 4. Shell Guard
323
+
324
+ The same decision model can vet **every shell command before it runs**. With `shellGuard.enabled: true`, each `shell` / `bash` call is classified for destructive and malicious intent. If `p(destructive)` or `p(malicious)` reaches the threshold, the command is escalated to OpenCode's confirmation prompt together with the full verdict (probabilities plus a risk category). Otherwise it runs unchanged.
311
325
 
312
326
  ```json
313
327
  {
@@ -320,74 +334,64 @@ The same local decision model can vet **every shell command before it runs**. Wi
320
334
  }
321
335
  ```
322
336
 
323
- - **Off by default** — enabling adds one local model call to the critical path of every shell command.
324
- - **Fast** — a warm verdict costs ~200–230 ms (`rm -rf ./dist` → 0.96 destructive, `delete_files`; `ls -la src` → 0.23, allowed). Repeated identical commands hit the 10-minute cache.
325
- - **Machine-wide** — put the block in `~/.config/opencode/opencode-rag.json` (the global layer, see [Configuration](doc/configuration.md#config-file-discovery)) and every workspace inherits it; a workspace config can still override or disable it.
326
- - **Fail-open by default** (`onError: "allow"`) — if the classifier is down or times out, the command runs and a warning is logged. Set `onError: "ask"` to require confirmation instead.
327
- - **Verdict cache** (10 min, 256 entries) — repeated identical commands are answered instantly; the key includes the provider/model, so switching models invalidates it, and cached probabilities are re-scored against the current threshold on every call.
328
- - **Config edits apply without a restart** — the guard re-reads `opencode-rag.json` when it changes.
329
- - **Backend** defaults to the `decision` section, and any `/v1/systemone` endpoint works — e.g. llama-swap with `"baseUrl": "http://localhost:11437", "model": "Clef-Flash"`.
337
+ | Aspect | Behavior |
338
+ |---|---|
339
+ | **Default** | Off. Enabling it adds one local model call to every shell command. |
340
+ | **Speed** | A warm verdict takes about 200 to 230 ms. Example: `rm -rf ./dist` → 0.96 destructive; `ls -la src` → 0.23, allowed. |
341
+ | **On failure** | Fail-open by default (`onError: "allow"`): if the classifier is down or times out, the command runs and a warning is logged. Set `"ask"` to require confirmation instead. |
342
+ | **Cache** | Verdicts are cached for 10 minutes (256 entries). The key includes the provider and model, and cached probabilities are re-scored against the current threshold on every call. |
343
+ | **Scope** | Put the block in `~/.config/opencode/opencode-rag.json` to apply it to every workspace. A workspace config can still override or disable it. |
344
+ | **Live config** | Edits to `opencode-rag.json` apply without a restart. |
345
+ | **Backend** | Defaults to the `decision` section. Any `/v1/systemone` endpoint works, for example llama-swap with `"baseUrl": "http://localhost:11437", "model": "Clef-Flash"`. |
346
+
347
+ Every verdict is logged under `scope: shell.guard`, so you can tune the threshold against real commands. Shell Guard is a safety net, not a sandbox. See the [configuration reference](doc/configuration.md#shellguard) and the [plugin docs](doc/plugin.md#shell-guard-command-vetting).
330
348
 
331
- Every verdict is logged under `scope: shell.guard`, so you can tune the threshold against real commands. See [Configuration](doc/configuration.md#shellguard) and [Plugin documentation](doc/plugin.md#shell-guard-command-vetting).
349
+ ### 5. Documentation and wiki modes
332
350
 
333
- ## Documentation and Wiki Modes
351
+ Two optional modes turn the agent into a documentation maintainer.
334
352
 
335
- ### Documentation Mode (`/doc`)
353
+ #### Documentation mode (`/doc`)
336
354
 
337
- When `documentationMode.enabled` is `true`, the plugin exposes a `/doc` slash command that drives the agent to add JSDoc/TSDoc comments to undocumented source files. No agent tools are registered — documentation is driven entirely through the slash command and the documentation system prompt.
355
+ Off by default. When `documentationMode.enabled` is `true`, the plugin adds a `/doc` slash command that drives the agent to add JSDoc/TSDoc comments to undocumented source files. No agent tools are registered; it works entirely through the slash command and a documentation system prompt.
338
356
 
339
357
  ```json
340
- {
341
- "documentationMode": {
342
- "enabled": true,
343
- "batchSize": 5
344
- }
345
- }
358
+ { "documentationMode": { "enabled": true, "batchSize": 5 } }
346
359
  ```
347
360
 
348
- **Workflow:** type `/doc` to list all undocumented files grouped by subdirectory. The agent picks a subdirectory, documents every public symbol (preserving existing comments and implementation code), then types `/doc src/auth/` to mark that subdirectory complete. Progress is persisted in `.opencode/rag_db/doc-mode-progress.json`, so later sessions resume where you left off.
361
+ **Workflow**
349
362
 
350
- See [Plugin documentation](doc/plugin.md#5-documentation-mode--slash-command-doc) for details.
363
+ 1. Type `/doc` to list all undocumented files, grouped by subdirectory.
364
+ 2. The agent picks a subdirectory and documents every public symbol, preserving existing comments and implementation code.
365
+ 3. Type `/doc src/auth/` to mark that subdirectory complete.
351
366
 
352
- ### Wiki Mode (`/wiki`)
367
+ Progress is saved in `.opencode/rag_db/doc-mode-progress.json`, so later sessions resume where you left off. See the [plugin docs](doc/plugin.md#5-documentation-mode--slash-command-doc).
353
368
 
354
- When `wikiMode.enabled` is `true` (on by default), the plugin injects a wiki-maintainer system prompt that instructs the agent to build and maintain a persistent knowledge wiki at `.opencode/wiki/` — a structured, interlinked collection of markdown pages synthesizing knowledge from the codebase, docs, and conversations.
369
+ #### Wiki mode (`/wiki`)
355
370
 
356
- ```json
357
- {
358
- "wikiMode": {
359
- "enabled": true
360
- }
361
- }
362
- ```
371
+ On by default. When `wikiMode.enabled` is `true`, the plugin injects a wiki-maintainer system prompt. The agent builds and maintains a persistent knowledge wiki in `.opencode/wiki/`: interlinked markdown pages that synthesize knowledge from the codebase, docs, and conversations.
363
372
 
364
373
  | Command | Action |
365
374
  |---|---|
366
- | `/wiki` | Show wiki status (page count, subdirectories, index/log presence, latest log entry) |
375
+ | `/wiki` | Show wiki status (page count, subdirectories, index and log presence, latest log entry) |
367
376
  | `/wiki seed` | Generate the initial wiki from the README, file structure, and code patterns |
368
- | `/wiki lint` | Health-check for orphan pages, stale source refs, contradictions, missing cross-links |
369
-
370
- The agent maintains all wiki pages during normal coding sessions; you never write wiki pages yourself. The wiki is git-trackable in `.opencode/`, so every edit is a diff. See [Plugin documentation](doc/plugin.md#6-wiki-mode--slash-command-wiki) for the full protocol.
371
-
372
- ## Image Indexing
377
+ | `/wiki lint` | Health-check for orphan pages, stale source references, contradictions, and missing cross-links |
373
378
 
374
- OpenCodeRAG can index image files (PNG, JPEG, WebP, and others) by sending them to a vision-capable LLM and storing the generated text descriptions as searchable vector chunks. This makes visual assets discoverable through natural-language queries (e.g. "login screen screenshot", "architecture diagram").
379
+ The agent maintains the pages during normal coding sessions; you do not write them yourself. The wiki lives in `.opencode/`, so it is git-trackable and every edit is a diff. See the [plugin docs](doc/plugin.md#6-wiki-mode--slash-command-wiki).
375
380
 
376
- **Supported providers:** Ollama, OpenAI, Anthropic, Google Gemini, and OpenCode Zen (`opencode`/`opencode-go`) compatible providers.
381
+ ### 6. Image indexing
377
382
 
378
- **Enabled by default** — set `imageDescription.enabled: false` in `opencode-rag.json` to skip image files entirely (recommended if you have no vision model or no GPU).
383
+ Image files (PNG, JPEG, WebP, and others) are sent to a vision-capable LLM, and the generated descriptions are stored as searchable chunks. Visual assets then become discoverable with natural-language queries such as "login screen screenshot" or "architecture diagram". The `describe_image` tool also lets an agent inspect an image on demand.
379
384
 
380
- ## Web UI
385
+ - **Providers:** Ollama, OpenAI, Anthropic, Google Gemini, and OpenCode Zen (`opencode` / `opencode-go`) compatible providers.
386
+ - **On by default.** Set `imageDescription.enabled: false` to skip image files entirely. This is recommended if you have no vision model or no GPU.
381
387
 
382
- A browser-based dashboard for exploring the indexed vector database — browse, visualize, and inspect chunks, and evaluate OpenCode sessions in terms of retrieved chunks and consumed tokens.
388
+ ### 7. Web UI, evaluation, and calibration
383
389
 
384
- ![OpenCodeRAG Web UI](doc/assets/webui-3d.png)
390
+ **Web UI.** A browser dashboard for exploring the vector database: browse, visualize, and inspect chunks, and evaluate OpenCode sessions by retrieved chunks and consumed tokens. Launch it with `opencode-rag ui`. See the [Web UI docs](doc/webui.md).
385
391
 
386
- Launch with `opencode-rag ui`. See the [Web UI documentation](doc/webui.md) for details.
392
+ [![OpenCodeRAG Web UI](doc/assets/webui-3d.png)](doc/assets/webui-3d.png)
387
393
 
388
- ## Evaluation and Calibration
389
-
390
- OpenCodeRAG tracks token usage, RAG injection overhead, and costs across sessions, so you can measure whether semantic retrieval actually saves tokens.
394
+ **Does it actually save tokens?** Session-level analysis compares RAG-on against RAG-off, using tiktoken BPE (`cl100k_base`) for code tokenization:
391
395
 
392
396
  ```bash
393
397
  opencode-rag eval:sessions # list sessions
@@ -395,17 +399,69 @@ opencode-rag eval:analyze <id> # detailed breakdown
395
399
  opencode-rag eval:compare <A> <B> # side-by-side comparison
396
400
  ```
397
401
 
398
- Token counting uses tiktoken BPE (cl100k_base) for accurate code tokenization. See the [Evaluation documentation](doc/evaluation.md) for details.
402
+ **Is retrieval good enough?** A separate harness measures quality:
403
+
404
+ | Command | Purpose |
405
+ |---|---|
406
+ | `opencode-rag eval:gate` | Runs the labelled golden set and fails when Hit@5, MRR, or nDCG@10 drop below the documented floors |
407
+ | `opencode-rag eval:decide` | Measures the decision model's accuracy, ECE, and Brier score on a labelled calibration set |
408
+ | `opencode-rag eval:tune` | Sweeps the retrieval fusion weights against the golden set and reports the best configuration for your setup |
409
+
410
+ The shipped `keywordWeight=0.4` is a default, not an optimum (on a code embedder it costs about 8 Hit@5 points), so measure instead of guessing. See the [evaluation docs](doc/evaluation.md).
411
+
412
+ ---
413
+
414
+ ## Tool reference
415
+
416
+ ### MCP tools (plugin and MCP server)
417
+
418
+ Inside OpenCode the plugin registers these in-process. Over MCP they are served by `opencode-rag mcp`.
419
+
420
+ | Tool | What it does | When the agent uses it |
421
+ |---|---|---|
422
+ | `search_semantic` | Hybrid vector and keyword search over the indexed code | Before a code task, instead of reading whole files |
423
+ | `get_file_skeleton` | AST outline of a file (functions, classes, methods) | To orient in a large file before reading it |
424
+ | `find_usages` | Every reference to a symbol | Before editing a function, class, or variable |
425
+ | `describe_image` | Describes an image with the configured vision model | When the task involves a screenshot, diagram, or other asset |
426
+ | `make_decision` | Classifies, routes, or scores short text (needs `decision.enabled`) | When the answer reduces to a choice, a yes/no check, or a rubric score |
427
+
428
+ ### Plugin-only tools (OpenCode)
399
429
 
400
- Retrieval quality has its own harness:
430
+ Registered by the OpenCode plugin, not served over MCP.
401
431
 
402
- - `opencode-rag eval:gate` runs the labelled golden set and fails when Hit@5 / MRR / nDCG@10 drop below the documented floors.
403
- - `opencode-rag eval:decide` measures tev1's accuracy, ECE, and Brier score on a labelled calibration set.
404
- - `opencode-rag eval:tune` sweeps the retrieval fusion weights against the same golden set and reports the best configuration for your setup. The shipped `keywordWeight=0.4` is a default, not an optimum (on a code embedder it costs ~8 Hit@5 points) — measure it instead of guessing.
432
+ | Tool | What it does |
433
+ |---|---|
434
+ | `recall_quirks` | Recalls stored gotchas, preferences, and decisions from past sessions |
435
+ | `add_quirk` | Stores a new non-obvious fact, workaround, or convention |
436
+ | `update_quirk` | Corrects a stored quirk that is outdated or wrong |
437
+ | `delete_quirk` | Removes a quirk that is fixed, obsolete, or no longer applies |
438
+
439
+ ### Slash commands and hotkeys (OpenCode)
440
+
441
+ Default hotkeys and slash commands:
442
+
443
+ | Input | Action |
444
+ |---|---|
445
+ | `Ctrl+Enter` | Append a relevant file list to the prompt |
446
+ | `Ctrl+Alt+Enter` | Append full code chunks to the prompt |
447
+ | `/rag-settings` or `Alt+S` | Open the settings panel |
448
+ | `/doc` | Documentation mode (if enabled) |
449
+ | `/wiki`, `/wiki seed`, `/wiki lint` | Wiki mode |
450
+
451
+ Hotkeys can be changed via /rag-settings.
452
+
453
+ ---
405
454
 
406
455
  ## Configuration
407
456
 
408
- Settings live in JSON (no comments). The workspace file `.opencode/opencode-rag.json` is canonical; the global file `~/.config/opencode/opencode-rag.json` holds machine-wide settings (Shell Guard, provider choices) that every workspace inherits. Shown below are the shipped defaults:
457
+ Settings are stored as JSON (no comments).
458
+
459
+ | File | Purpose |
460
+ |---|---|
461
+ | `.opencode/opencode-rag.json` | Workspace config (canonical) |
462
+ | `~/.config/opencode/opencode-rag.json` | Machine-wide settings (Shell Guard, provider choices) inherited by every workspace |
463
+
464
+ Shipped defaults:
409
465
 
410
466
  ```json
411
467
  {
@@ -420,49 +476,59 @@ Settings live in JSON (no comments). The workspace file `.opencode/opencode-rag.
420
476
  }
421
477
  ```
422
478
 
423
- The [Configuration reference](doc/configuration.md) documents every option — embedding, indexing, retrieval, description, image description, decision, shell guard, and plugin settings — and how the global and workspace layers merge.
479
+ The [configuration reference](doc/configuration.md) documents every option (embedding, indexing, retrieval, description, image description, decision, Shell Guard, plugin) and how the global and workspace layers merge.
480
+
481
+ ---
482
+
483
+ ## Privacy and security
484
+
485
+ - **100% local by default.** Embeddings are generated locally via Ollama, and the vector database stays in your project directory. No source code or embeddings leave your machine unless you explicitly configure a third-party API.
486
+ - **Shell Guard** sends command text only to the decision-model endpoint you configure (local Ollama or a local proxy).
487
+ - **Decision model** is only asked about short excerpts that you or the agent pass in.
488
+ - **Quirk memory** writes pass an immutable trust monitor that rejects destructive patterns.
489
+
490
+ ---
491
+
492
+ ## Limitations
493
+
494
+ - **Retrieval quality depends on the embedding model.** Small CPU-friendly models trade accuracy for speed. Measure with `eval:gate` and `eval:tune` rather than assuming a default.
495
+ - **Image descriptions need a vision model.** This is a feature that meaningfully wants a GPU to be pleasant. Disable it with `imageDescription.enabled: false` if you have none.
496
+ - **Shell Guard costs one model call per shell command** (about 200 ms warm) and fails open by default. It is a safety net, not a sandbox.
497
+ - **The decision model supports only Ollama's `/v1/systemone` endpoint** for now.
498
+ - **ClickHouse is opt-in** and needs a running server. LanceDB is the default and needs no separate installation.
424
499
 
425
- ## Documentation Index
500
+ ---
501
+
502
+ ## Documentation index
503
+
504
+ This README is the entry point. Deep dives live in [`doc/`](doc).
426
505
 
427
506
  | Document | Contents |
428
507
  |---|---|
429
508
  | [Architecture](doc/architecture.md) | Module design, data flow, tech stack |
430
509
  | [Installation](doc/installation.md) | Full install guide, global setup, uninstall |
431
- | [Configuration](doc/configuration.md) | All options: embedding, indexing, retrieval, description, image description, decision, shell guard, plugin |
510
+ | [Configuration](doc/configuration.md) | All options |
432
511
  | [Chunking](doc/chunking.md) | Language matrix, adding new chunkers, custom chunkers |
433
512
  | [Embedding](doc/embedding.md) | Providers, model recommendations, proxy, dimension probing |
434
- | [ClickHouse store](doc/clickhouse.md) | Central vector store backend: setup, epochs, ANN, multi-machine sync |
513
+ | [ClickHouse store](doc/clickhouse.md) | Central vector store: setup, epochs, ANN, multi-machine sync |
435
514
  | [Retrieval](doc/retrieval.md) | Pipeline, hybrid search, score fusion, caching |
436
515
  | [Plugin](doc/plugin.md) | OpenCode integration, tools, hooks, TUI, troubleshooting |
437
- | [CLI Reference](doc/cli.md) | All commands, options, examples |
516
+ | [CLI reference](doc/cli.md) | All commands, options, examples |
438
517
  | [Web UI](doc/webui.md) | Dashboard, chunk browser, file explorer, compare view |
439
518
  | [Evaluation](doc/evaluation.md) | Token analysis, session logging, benchmark runner, accuracy guide |
440
519
  | [Development](doc/development.md) | Setup, testing, conventions, adding providers |
441
520
  | [Troubleshooting](doc/troubleshooting.md) | Common issues, logging, debugging |
442
- | [Roadmap](doc/roadmap.md) | Completed items, short/mid/long-term plans |
443
-
444
- ## Privacy and Security
445
-
446
- **100% local by default.** Embeddings are generated locally via Ollama, and the vector database stays in your project directory. **No source code or embeddings leave your machine** unless you explicitly configure a third-party API. The optional [Shell Guard](#shell-guard-optional) likewise sends command text only to the decision-model endpoint you configure (local Ollama or a local proxy).
447
-
448
- Every quirk written to memory passes an immutable trust monitor that rejects destructive patterns, and the decision model is only ever asked about short excerpts you (or the agent) pass in.
449
-
450
- ## Limitations and Non-Goals
521
+ | [Roadmap](doc/roadmap.md) | Completed items, short-, mid-, and long-term plans |
451
522
 
452
- - **This README is the entry point, not the manual.** Deep dives live in [`doc/`](doc/); the project does not aim to duplicate API references here.
453
- - **Retrieval quality depends on the embedding model.** Small CPU-friendly models trade accuracy for speed; measure with `eval:gate` and `eval:tune` rather than assuming a default.
454
- - **Image descriptions need a vision model.** They are on by default; set `imageDescription.enabled: false` if you have none — it is the one feature that meaningfully wants a GPU to be pleasant.
455
- - **Shell Guard costs one model call per shell command** (~200 ms warm) and fails open by default; it is a safety net, not a sandbox.
456
- - **The decision model currently supports Ollama's `/v1/systemone` endpoint only.**
457
- - **The ClickHouse backend is opt-in** and requires a running ClickHouse server; LanceDB is the default and needs no server.
523
+ ---
458
524
 
459
- ## Contributing and Support
525
+ ## Contributing and support
460
526
 
461
- - **Development setup, conventions, and testing:** [doc/development.md](doc/development.md)
527
+ - **Development setup, conventions, testing:** [doc/development.md](doc/development.md)
462
528
  - **Troubleshooting and logging:** [doc/troubleshooting.md](doc/troubleshooting.md)
463
- - **Bug reports and feature requests:** [GitHub Issues](https://github.com/MrDoe/OpenCodeRAG/issues)
529
+ - **Bugs and feature requests:** [GitHub Issues](https://github.com/MrDoe/OpenCodeRAG/issues)
464
530
  - **Roadmap:** [doc/roadmap.md](doc/roadmap.md)
465
531
 
466
532
  ## License
467
533
 
468
- MIT
534
+ [MIT](LICENSE)