# OX

> OX is a methodology — and two parallel implementations — for developers who think and build in the same place. It co-locates **knowledge** (an Obsidian vault) and **code** (your git repos) in one directory tree, then indexes both into a single searchable knowledge graph that humans and AI agents navigate the same way.

Two trees, one workspace: `o/` is for thinking (knowledge, decisions, people, history), `x/` is for doing (code, infrastructure, deployments). The power is the bridge between them — a `CLAUDE.md` in `x/` cross-references notes in `o/`, and a project doc in `o/` points to its repo in `x/`. The workspace *is* the context, and agents are first-class citizens who receive the same context humans get.

**⚠️ Work in progress.** OX is an early, opinionated tool developed in the open — not a polished product. It began as one developer's personal workflow, and adopting it currently means adopting that workflow. Notably, keeping the search index current is **manual**: if you don't re-run `ox index` after changing notes, you get stale/degraded results. Don't use OX unless you're comfortable running and updating it yourself. See [Status & Known Issues](https://iamox.ai/docs/known-issues.md).

This site is intentionally bot-friendly. The pages below are Markdown, meant to be read by LLMs and crawlers as well as people.

## Documentation

- [Overview & Methodology](https://iamox.ai/docs/methodology.md): The "two trees, one workspace" philosophy and why co-locating knowledge and code matters.
- [Installation](https://iamox.ai/docs/installation.md): Install the `ox` binary (one curl command) and bootstrap a workspace with `ox init`.
- [CLI Reference](https://iamox.ai/docs/cli.md): Every `ox` command — init, clone, index, search, serve, status, kb, workspace, version.
- [Workspace Structure](https://iamox.ai/docs/workspace-structure.md): The full `o/` and `x/` directory tree and the who/what/when/where convention.
- [Knowledge Graph & RAG](https://iamox.ai/docs/knowledge-graph-rag.md): Hybrid BM25 + vector search, the SQLite graph, and pluggable backends.
- [Code Indexing](https://iamox.ai/docs/code-indexing.md): Indexing repos alongside notes so searches return decisions *and* implementations.
- [MCP Server](https://iamox.ai/docs/mcp-server.md): `ox serve` exposes the vault as Model Context Protocol tools for Claude Code, Cursor, and any MCP agent.
- [Two Implementations](https://iamox.ai/docs/two-implementations.md): v0.3.0 ships two parallel implementations — the Go CLI and ox-rs (Rust port). Learn which to use.
- [Status & Known Issues](https://iamox.ai/docs/known-issues.md): WIP disclaimer, the manual-indexing caveat, and the tracked list of known issues.

## Optional

- [Full documentation (single file)](https://iamox.ai/llms-full.txt): All of the above concatenated for one-shot ingestion.
- [Source on GitHub](https://github.com/icewaterlabs/ox): The `ox` CLI source, releases, and issues.
- [Install script](https://iamox.ai/install.sh): The shell installer invoked by the one-line install command.
# OX — Overview & Methodology

> A methodology for developers who think and build in the same place. Co-locate knowledge and code in a single directory tree.

> ⚠️ **Work in progress.** OX is early and opinionated — a personal tool developed in the open, not a finished product. Read [Status & Known Issues](https://iamox.ai/docs/known-issues.md) before adopting it.

## The idea

Most developers keep their thinking in one place (a notes app, a wiki, scattered docs) and their code in another (git repos on disk). The context that connects the two — *why* a decision was made, *who* asked for it, *which* code implements it — lives only in your head, and evaporates.

OX collapses that gap. It puts **knowledge** and **code** in one workspace and indexes both into a single knowledge graph, so the link between a decision and its implementation is a first-class, queryable edge — not tribal memory.

## Two trees, one workspace

```
~/ox/
├── o/   # Knowledge — an Obsidian vault. Thinking.
└── x/   # Code — your git repositories. Doing.
```

- **`o/` is for Thinking.** Knowledge, context, decisions, relationships, history. Obsidian's graph connects people to projects to timelines. This is your institutional memory.
- **`x/` is for Doing.** Code, deployments, infrastructure. Each repo is self-contained with its own git history. This is where ideas become running software.

The power is in the **bridge** between them. A `CLAUDE.md` in `x/` cross-references notes in `o/`. A project doc in `o/` points to its repo in `x/`. Context flows both directions.

## Core principles

- **Craft over code.** Elegance through deliberate documentation and architecture. Every file, note, and commit reflects intentionality.
- **Ruthless simplification.** Eliminate unnecessary complexity. Three similar lines are better than a premature abstraction. Don't design for hypothetical futures.
- **Single source of truth.** Each fact exists in exactly one location. Don't duplicate.
- **Progressive disclosure.** The workspace structure tells you where to look; the file tells you what you need; cross-references tell you where to go deeper.
- **Agent-agnostic.** The methodology works with any AI tool — Claude, Gemini, Cursor, Copilot. The workspace *is* the context. Agents are first-class citizens who receive the same context humans get.

## Why agents love it

Because the workspace is a plain directory tree of Markdown and code — navigable by construction — an AI agent traverses it exactly the way a human does. No special API, no wrapper. `.agents/AGENTS.md` provides universal instructions to any AI agent that opens the workspace. And `ox serve` exposes the indexed vault over the Model Context Protocol so agents can search it as a tool.

When your agent searches for "auth migration," it finds the *decision* (a daily note in `o/`) **and** the *implementation* (the auth middleware in `x/`), ranked together.

## Next steps

- [Installation](https://iamox.ai/docs/installation.md)
- [Workspace Structure](https://iamox.ai/docs/workspace-structure.md)
- [CLI Reference](https://iamox.ai/docs/cli.md)
# Installing OX

> ⚠️ **Work in progress.** OX is an early, opinionated personal tool, not a polished product. Don't install it unless you're comfortable running and updating it yourself — including re-running `ox index` manually to keep results fresh. See [Status & Known Issues](https://iamox.ai/docs/known-issues.md) first.

OX v0.3.0 ships two implementations, both producing a binary named `ox`. The one-liner below installs the **Go CLI**. See [Two Implementations](https://iamox.ai/docs/two-implementations.md) for the Rust port (ox-rs).

## One-line install

```bash
curl -fsSL https://iamox.ai/install.sh | bash
```

The installer detects your platform, fetches the latest release from [`icewaterlabs/ox`](https://github.com/icewaterlabs/ox), installs the binary to `~/.local/bin/ox`, and offers to add that directory to your `PATH`.

> **Note:** The installer downloads the **Go CLI** (`ox` v0.3.0). The Rust implementation (`ox-rs` v0.2.0) is available as a separate binary on the releases page — see [Two Implementations](https://iamox.ai/docs/two-implementations.md).

> **Platform note for ox-rs:** ox-rs Linux binaries require GLIBC 2.39+ (Ubuntu 24.04+, Fedora 40+). macOS and Windows are unaffected. The Go CLI has no GLIBC restriction.

## Bootstrap a workspace

```bash
ox init
```

`ox init` creates the directory tree, installs CLI dependencies, authenticates with GitHub, clones your organization's repos, and configures MCP servers — idempotent and safe to re-run.

```
$ ox init
  [1/9] Pre-flight checks... ok
  [2/9] Creating ~/ox directory tree... ok
  [3/9] Installing dependencies... ok
  [4/9] Configuring git... ok
  [5/9] Cloning org repos... 12 repos cloned
  [6/9] Syncing dotfiles... ok
  [7/9] Generating .ox/config.json... ok
  [8/9] Setting up MCP server... ok
  [9/9] Post-init verification... ok

  OX workspace ready at ~/ox
  Knowledge: o/o/ (0 notes)
  Code: x/code/ (12 repos)
  Agents: .agents/ configured
```

### Useful `ox init` flags

| Flag | Purpose |
|------|---------|
| `--path` | Workspace path (default: `~/ox`) |
| `--org` | GitHub organization to clone |
| `--dotfiles` | Dotfiles repo, e.g. `yourname/ox-dotfiles` |
| `--branch` | Dotfiles repo branch (default `main`) |
| `--parallel` | Max parallel git clones (default 4) |
| `--skip-clone` | Skip repository cloning |
| `--skip-deps` | Skip CLI dependency installation |
| `--skip-dotfiles` | Skip dotfiles sync |
| `--skip-mcp` | Skip MCP server configuration |

## Verify

```bash
ox version
ox status      # workspace health and status
```

## Next steps

- [CLI Reference](https://iamox.ai/docs/cli.md) — every command
- [Two Implementations](https://iamox.ai/docs/two-implementations.md) — Go CLI vs ox-rs
- [Knowledge Graph & RAG](https://iamox.ai/docs/knowledge-graph-rag.md) — run `ox index` then `ox search`
- [MCP Server](https://iamox.ai/docs/mcp-server.md) — connect your AI agent
# OX CLI Reference

> **Scope:** This reference covers the **Go CLI** (v0.3.0). For the Rust implementation's CLI, see [Two Implementations](https://iamox.ai/docs/two-implementations.md).

`ox` is a CLI tool for bootstrapping and managing OX workspaces. One binary, every platform, zero dependencies.

```
Usage:
  ox [command]
```

## Commands

| Command | Description |
|---------|-------------|
| `ox init` | Initialize a new ox workspace on this machine |
| `ox clone [org]` | Clone or update all repos for a GitHub organization |
| `ox index` | Index the knowledge base and code for search and graph queries |
| `ox search <query>` | Search using hybrid text + vector search |
| `ox serve` | Start the MCP server for AI agent integration |
| `ox status` | Show workspace health and status |
| `ox kb` | Manage knowledge bases (create, info, list, switch) |
| `ox workspace` | Start the ox workspace web UI |
| `ox version` | Print the ox version |
| `ox completion` | Generate a shell autocompletion script |

Run `ox [command] --help` for details on any command.

## ox init

Creates the directory structure, installs CLI dependencies, authenticates with GitHub, clones organization repos, and configures MCP servers. See [Installation](https://iamox.ai/docs/installation.md) for the full flag list.

## ox clone

```bash
ox clone [org] [--parallel N]
```

Clones all non-archived repos for a GitHub organization into `x/code/remote/github/<org>/`. Existing repos are skipped (not force-updated).

## ox index

```bash
ox index [flags]
```

Parses all Markdown notes and code repositories, builds a knowledge graph, generates embeddings, and creates full-text search indexes. By default indexes **both** the knowledge base (`o/o/`) and code repos (`x/code/`). Incremental by default via SHA-256 content hashing.

| Flag | Purpose |
|------|---------|
| `--kb-only` | Only index the knowledge base |
| `--code-only` | Only index code repos |
| `--full` | Force a full re-index (ignore the content-hash cache) |
| `--no-embed` | Skip embedding generation (no Ollama needed) |
| `--model` | Embedding model (default `nomic-embed-text`) |
| `--ollama-url` | Ollama API URL (default `http://localhost:11434`) |

## ox search

```bash
ox search <query> [-n LIMIT] [--text-only]
```

Combines BM25 full-text search with semantic vector similarity for ranked results across knowledge **and** code.

| Flag | Purpose |
|------|---------|
| `-n, --limit` | Maximum results (default 20) |
| `--text-only` | BM25 text search only (no embeddings) |

## ox serve

```bash
ox serve [flags]
```

Starts a Model Context Protocol (MCP) server on stdio, exposing knowledge-base search and graph tools to Claude Code and other MCP clients. Add to `.mcp.json` to auto-connect:

```json
{ "ox": { "type": "stdio", "command": "ox", "args": ["serve"] } }
```

| Flag | Purpose |
|------|---------|
| `--no-embed` | Disable embeddings; use BM25 + graph only (no Ollama required) |

See [MCP Server](https://iamox.ai/docs/mcp-server.md).

## ox kb

Manage one or more knowledge bases (directories of Markdown using the who/what/when/where convention). Subcommands: `create`, `info`, `list`, `switch`. Use any editor — Obsidian, VS Code, or the ox web UI.

## ox status

Shows workspace health and status — note counts, indexed repos, and configuration state.
# Workspace Structure

The ox workspace follows the "two trees, one workspace" pattern: `o/` for knowledge, `x/` for code.

```
~/ox/                                    # Workspace root (NOT a git repo)
├── .agents/                             # Universal agent context
│   ├── workspace-structure.md           # This document
│   ├── philosophy.md                    # Team values & principles
│   ├── SOUL.md                          # Identity & behavioral core
│   ├── IDENTITY.md                      # Agent behavioral guidelines
│   ├── AGENTS.md                        # Agent workspace rules
│   └── shared/                          # Operational state
│       ├── deployments.md               # Live deployment map
│       └── infrastructure.yaml          # Single source of truth for infra
│
├── o/                                   # Obsidian vault (knowledge layer)
│   ├── .obsidian/                       # Vault configuration
│   └── o/                               # Vault content root
│       ├── who/                         # People — every person gets a linked note
│       ├── what/                        # Projects, orgs, tools, topics
│       │   ├── orgs/
│       │   │   ├── COM/                 # Commercial organizations
│       │   │   ├── EDU/                 # Educational institutions
│       │   │   └── FAM/                 # Family organizations
│       │   ├── bots/                    # AI agent notes & shared memory
│       │   │   └── memory/              # Cross-device synced memory
│       │   └── [topics]/                # Skills, tools, career, essays, etc.
│       ├── when/                        # Temporal — daily notes, cycles, events
│       │   ├── days/                    # Daily notes
│       │   ├── weeks/  months/  quarters/  years/
│       │   ├── cycles/                  # Sprint/project cycles
│       │   └── events/                  # Calendar events
│       └── where/                       # Geolocation only (physical places)
│
└── x/                                   # Code layer
    └── code/
        └── remote/
            └── github/
                └── <org>/               # One directory per GitHub org
                    └── <repo>/          # Each repo keeps its own .git history
```

## Conventions

- **Two trees:** `o/` is for thinking (knowledge), `x/` is for doing (code).
- **Repository paths mirror the remote:** `x/code/remote/{host}/{org}/{repo}/`. All code repos are checked out under `x/code/`.
- **Wikilinks use absolute vault-root paths:** `[[o/who/John Doe]]`, `[[o/what/orgs/COM/iwl/infrastructure]]`.
- **`o/where/` is reserved for geolocation only** — infrastructure notes live under `o/what/orgs/...`.
- **Every repo includes a `CLAUDE.md`** for agent onboarding, cross-referencing the relevant notes in `o/`.
- **The who/what/when/where convention** organizes the vault: people, things, time, and place.

See also: [Methodology](https://iamox.ai/docs/methodology.md) · [Code Indexing](https://iamox.ai/docs/code-indexing.md)
# Knowledge Graph & RAG

OX indexes your vault into a searchable knowledge graph with hybrid retrieval — BM25 full-text search combined with vector similarity — so both exact terms and semantic meaning rank together.

## Hybrid search

- **BM25 full-text** via Bleve for precise keyword matching.
- **Vector similarity** via Ollama embeddings (default model: `nomic-embed-text`) for semantic recall.
- Results from both are merged and ranked.

```
$ ox index
  Indexing vault at ~/ox/o/o/...
  Parsed 847 notes, 2,341 links, 892 tags
  Generated 847 embeddings (nomic-embed-text)
  Graph: 1,739 nodes, 3,233 edges
  Index time: 12.4s (incremental: 0.8s)

$ ox search "auth migration decision"
  0.94  o/when/days/2026.March.16.Monday.md
        "discussed auth migration with Alice..."
  0.87  o/what/orgs/COM/iwl/maxre/auth-decisions.md
        "JWT refresh token rotation strategy..."
  0.81  x/code/.../crm-api/CLAUDE.md
        "Auth middleware uses Supabase JWT..."
  Results: 3 (0.04s)
```

## The graph

A SQLite knowledge graph stores **nodes** (notes, tags) and **edges** (`LINKS_TO`, `HAS_TAG`). Wikilinks between notes and tags become traversable relationships, so you can ask not just "what matches" but "what's related."

## Pluggable backends

OX is built around clean interfaces — `GraphStore`, `VectorStore`, `TextSearchStore`, and `Embedder` — so the storage and retrieval stack is swappable.

- **Default stack:** SQLite + Bleve + Ollama (zero cloud dependencies, runs fully local).
- **Planned backends:** Neo4j, Qdrant, Pinecone, and OpenAI embeddings.

## Incremental & safe

- **Incremental indexing** with SHA-256 change detection — only re-index what changed (`ox index` re-runs in well under a second on an unchanged vault; use `--full` to force).
- **Read-only search mode** — no file-lock conflicts with your editor.
- **No embeddings needed?** `ox index --no-embed` skips Ollama and runs text-only.

## Next steps

- [Code Indexing](https://iamox.ai/docs/code-indexing.md) — index repos alongside notes
- [MCP Server](https://iamox.ai/docs/mcp-server.md) — expose search to AI agents
- [CLI Reference](https://iamox.ai/docs/cli.md#ox-index)
# Code Indexing

OX indexes your **code** alongside your **notes** — both land in the same knowledge graph, so a single search returns decisions *and* the implementations that satisfy them.

## Your notes AND your repos, in one graph

`ox index` walks the repos in `x/code/` together with the vault notes in `o/o/`. File trees, symbols, git metadata, and dependencies all become nodes and edges in the same graph as your knowledge.

The result: a note about an "auth migration" links to the actual auth code. When your AI agent searches, it finds the *decision* in `o/` **and** the *implementation* in `x/`, ranked together.

```
o/when/days/2026.March.16.md ──LINKS_TO──▶ o/what/orgs/.../auth-decisions.md
                                                   │
                                              cross-reference
                                                   ▼
x/code/.../crm-api/CLAUDE.md ──DESCRIBES──▶ x/code/.../crm-api/auth/middleware.ts
```

## Why it matters

Most tools index either your knowledge **or** your code. OX co-locates them, so the bridge between *why* and *how* is a queryable edge rather than something you reconstruct from memory. Think of it like a code-graph tool (e.g. GitNexus) — but co-located with your knowledge base instead of standing apart from it.

## Selective indexing

```bash
ox index             # both knowledge and code (default)
ox index --kb-only   # notes only
ox index --code-only # repos only
```

Indexing is incremental (SHA-256 change detection), so re-runs are fast. See the [CLI Reference](https://iamox.ai/docs/cli.md#ox-index) for all flags.

## Next steps

- [Knowledge Graph & RAG](https://iamox.ai/docs/knowledge-graph-rag.md)
- [MCP Server](https://iamox.ai/docs/mcp-server.md) — let agents query the combined graph
# MCP Server

`ox serve` turns your workspace into a tool for AI agents. It starts a Model Context Protocol (MCP) server on stdio, exposing knowledge-base search and graph tools to Claude Code, Cursor, Windsurf, and any MCP-compatible agent.

Both the Go CLI and ox-rs include an MCP server. The `.mcp.json` snippet below works with either — they expose the same 6 tools.

## Connect

Add ox to your `.mcp.json` to auto-connect:

```json
{
  "mcpServers": {
    "ox": {
      "type": "stdio",
      "command": "ox",
      "args": ["serve"]
    }
  }
}
```

## Tools exposed

| Tool | Purpose |
|------|---------|
| `search_vault` | Hybrid BM25 + vector search across notes and repo docs |
| `get_note` | Read a note's full text by path |
| `find_related` | Graph neighbors + semantic similarity from a note |
| `get_backlinks` | Inbound wikilinks to a note |
| `vault_stats` | Index statistics (note count, edge count, tags) |
| `find_path` | Shortest graph path between two notes (requires optional Neo4j backend) |

## In practice

```
# Agent query (via Claude Code):
> Search vault for "deployment checklist"

search_vault("deployment checklist")
-> 3 results in 0.04s
-> o/what/orgs/COM/iwl/deploy-checklist.md (0.96)
-> o/when/days/2026.March.20.Thursday.md (0.84)
-> x/code/.../infra/docs/DEPLOY.md (0.79)
```

## Agent-navigable by construction

The agent traverses the same tree humans do — no special API, no wrapper. Two things make the workspace agent-ready out of the box:

- **`.agents/AGENTS.md`** provides universal instructions for any AI agent that opens the workspace.
- **The MCP server** gives agents fast, ranked retrieval over the indexed graph.

Agents are first-class citizens in OX: they receive the same context humans get.

## Next steps

- [CLI Reference](https://iamox.ai/docs/cli.md#ox-serve)
- [Two Implementations](https://iamox.ai/docs/two-implementations.md)
- [Knowledge Graph & RAG](https://iamox.ai/docs/knowledge-graph-rag.md)
# Two Implementations

OX v0.3.0 ships two parallel implementations. Both produce a binary named `ox` — they are separate release artifacts, not the same binary.

## The Go CLI (v0.3.0)

The original implementation. The one-liner installer downloads this one.

- Full-featured and stable
- Web UI (`ox workspace`)
- Docker mode
- `ox init` / `ox clone` for workspace bootstrapping
- Requires `ox init` before `ox index`
- Runs on macOS, Linux, and Windows (no GLIBC restriction)

## ox-rs (v0.2.0)

A Rust port that emphasizes graph performance and a tighter dependency footprint.

- Faster graph engine (CozoDB)
- tantivy BM25 full-text search
- SQLite persistence
- MCP server (same 6 tools as the Go CLI)
- ratatui TUI (`ox tui`)
- Takes `--vault /path` or `OX_VAULT` env variable — no `ox init` required
- **Linux requires GLIBC 2.39+** (Ubuntu 24.04+, Fedora 40+). macOS and Windows are unaffected.

## Which to use

| Use case | Recommendation |
|----------|---------------|
| First install, want everything to just work | Go CLI (`curl -fsSL https://iamox.ai/install.sh \| bash`) |
| Need `ox init` / `ox clone` workspace bootstrapping | Go CLI |
| Need the web UI | Go CLI |
| Want faster graph traversal (CozoDB) | ox-rs |
| Already have a vault directory, no bootstrap needed | ox-rs |
| Need a ratatui TUI | ox-rs |
| On Linux older than Ubuntu 24.04 / Fedora 40 | Go CLI (no GLIBC restriction) |
| Running MCP server for AI agents | Either — both expose the same 6 tools |

## Installation

**Go CLI (default):**

```bash
curl -fsSL https://iamox.ai/install.sh | bash
```

**ox-rs:**

Download the `ox-rs-*` binary for your platform from the [releases page](https://github.com/icewaterlabs/ox/releases/latest). Rename it to `ox` and place it on your `PATH`, or run it directly with `--vault /path/to/your/vault`.

```bash
# Example: point ox-rs at an existing vault
export OX_VAULT=~/ox/o/o
ox serve   # starts the MCP server against that vault
```

## Relationship

The two implementations are maintained in the same repository (`icewaterlabs/ox`). The Go CLI lives in `cli/`; ox-rs lives in `ox-rs/`. They share the same MCP tool contract (6 tools, same names and signatures) so `.mcp.json` configuration is identical for either.

Both are released as separate artifacts on the same GitHub release. Version numbers track independently (Go CLI at v0.3.x, ox-rs at v0.2.x).
# Status & Known Issues

> ⚠️ **OX is a work in progress.** It is an early, opinionated tool developed in the open — not a polished product. It began as one developer's personal workflow, and adopting it currently means adopting that workflow. **Don't use OX unless you're comfortable running and updating it yourself.** Expect rough edges.

## The big caveat: indexing is manual

Keeping the search index current is **a manual step**. `ox search` and the MCP tools only reflect the vault/code state as of the last `ox index` run. If you add or edit notes and don't re-index, you silently get **stale or degraded results** — no error, just missing or outdated hits.

```bash
ox index      # re-run this after changing notes/code, or results drift
```

If results look wrong or incomplete, re-index first.

## Known issues

These are tracked on GitHub. See the live list:
**[github.com/icewaterlabs/ox · label:known-issue](https://github.com/icewaterlabs/ox/issues?q=is%3Aissue+is%3Aopen+label%3Aknown-issue)**

| # | Issue | Status |
|---|-------|--------|
| [#70](https://github.com/icewaterlabs/ox/issues/70) | `ox index` is manual — a stale index silently degrades search/MCP results | Open |
| [#71](https://github.com/icewaterlabs/ox/issues/71) | `ox index` can appear to hang near the tail on large vaults | Open |
| [#72](https://github.com/icewaterlabs/ox/issues/72) | `ox tui` (Go CLI): removed. ox-rs ships a ratatui TUI (Phase 6). | Closed — resolved in ox-rs |
| [#73](https://github.com/icewaterlabs/ox/issues/73) | Workspace structure is rigid / not pluggable (`~/ox` + `o/o/who-what-when-where` + Obsidian) | Open |
| [#74](https://github.com/icewaterlabs/ox/issues/74) | Embeddings require a running Ollama; silent fallback to text-only (use `ox serve --no-embed` to opt out explicitly) | Open |
| [#75](https://github.com/icewaterlabs/ox/issues/75) | bbolt CVE (CVE-2026-33817, indirect via Bleve) | Closed — resolved in v0.3.0 (bbolt v1.4.0) |

## ox-rs dependency advisories

Two upstream RUSTSEC advisories affect ox-rs v0.2.0's graph engine dependency chain (cozo → swapvec):

- **lz4_flex** (HIGH): memory-safety issue in older lz4 flex bindings
- **lru** (LOW): algorithmic complexity issue in LRU cache

Both are upstream-blocked — fixes depend on swapvec and tantivy releasing updated versions. Both are documented in CI with ignore justifications. Monitor when swapvec and tantivy release updates.

Found something not listed? Open an issue: <https://github.com/icewaterlabs/ox/issues/new>.

## What's solid

For balance — the parts that are genuinely good today:

- **Hybrid search engine** — BM25 + vector similarity over a SQLite graph is fast and the ranking is useful (once the index is current).
- **MCP server** — all six tools (`search_vault`, `get_note`, `find_related`, `get_backlinks`, `vault_stats`, `find_path`) work well against real agent sessions.
- **Co-located knowledge + code** — the core idea (one graph over notes *and* repos) holds up.

See [Methodology](https://iamox.ai/docs/methodology.md) for the philosophy and [CLI Reference](https://iamox.ai/docs/cli.md) for commands.