KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #developer-tools #ai-agent #claude-code #codex #typescript #ai-agents #deepseek-harness #mcp #cli #rust

arrowhead

★ 43 Open GitHub ↗

Fast Obsidian-aware search and discovery that makes AI agents or OpenClaw your true knowledge assistant.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

**Fast Obsidian search and discovery that makes AI agents your true knowledge assistant.**

Arrowhead is a cross-platform CLI and daemon that keeps your Obsidian vault indexed around the clock. It combines fast full-text search, semantic vectors, graph analytics, and a Claude-ready MCP interface so both humans and agents can explore your notes without friction.

## How It Works

```mermaid
flowchart TB
    Vault["Obsidian Vault<br>(markdown + assets)"]

subgraph Core["Arrowhead Core"]
        Daemon[arrowheadd daemon]
        Index["Arrowhead Index<br>FTS + Vector"]

Daemon --manage--> Index
    end

subgraph Clients["Arrowhead clients"]
        CLI[Arrowhead CLI]
        MCP[MCP stdio server]
        MCPHTTP[MCP HTTP service]
    end
    
    Daemon <--watcher--> Vault

TUI["Codex / Claude Code<br>TUI"]
    Client[Claude.app / MCP client]
    RemoteClient[Remote MCP client]

CLI --> Index
    TUI --> CLI

MCP ---> Index 
    Client --> MCP

MCPHTTP ---> Index 
    RemoteClient --> MCPHTTP
```

The Arrowhead Core runtime watches your vault, streams changes into a bounded writer queue, and persists both text and vector indexes without taking ownership of your files. Arrowhead clients—the CLI and the MCP transports—sit on top of that runtime, reading directly from the shared index to serve both local workflows and remote agent requests.

## Features

- Background daemon with live filesystem watching and bounded persistence queue.
- Vault-aware indexing that respects `.obsidian` settings, templates, and ignore lists.
- Generic Markdown workspace support via `.arrowhead/workspace.toml`, with automatic fallbacks to Obsidian settings when present.
- Full-text, semantic, and hybrid search with snippet generation and metadata filters.
- Notes CRUD, graph analytics, and discovery helpers via CLI or MCP tool surface.
- HTTP MCP transport with bearer/link-token authentication, CIDR allowlists, and `/health` readiness probes.
- Semantic embeddings using fastembed with vectors stored in sqlite-vec alongside the primary index.
- Auto-start manifests for macOS (launchd) and Linux (`systemd --user`) with CLI management.

## Quick Start

#### 1. Install Arrowhead.

```bash
brew tap totocaster/tap
brew install totocaster/tap/arrowhead
```

#### 2. Navigate to your Obsidian vault and initialize Arrowhead.

```
arrowhead init
```

This command launches and registers the indexer, which watches your files and keeps the index ready to use. Initial indexing might take some time depending on your vault size. Use `arrowhead index status` for the live TUI, `arrowhead index status --json` for agent-friendly output, and `.arrowhead/daemon/status.json` plus `.arrowhead/logs/daemon.log` for immediate filesystem state while the daemon is still starting.

When you initialise a non-Obsidian workspace, Arrowhead writes `.arrowhead/workspace.toml` to capture attachments, ignored folders, daily note format, and preferred link style. Use flags such as `--attachments-dir`, `--ignore`, `--daily-note-format`, and `--link-style` during `arrowhead init` to pre-populate those values; Obsidian vaults continue to pull the same data from `.obsidian`. You can inspect or tweak these settings later with `arrowhead workspace show` and `arrowhead workspace set`.

#### 3. Start using Arrowhead.

* CLI: Use the CLI when working with coding agents that have terminal access (local Claude Code instances, OpenClaw, Codex CLI) for the best performance.
* MCP: Use the MCP client for local or remote AI agent instances such as Claude.app.

To configure a local MCP client, add this snippet:

```json
{
  "mcpServers": {
    "arrowhead": {
      "command": "arrowhead",
      "args": ["--mcp"]
    }
  }
}
```

For remote or headerless clients, launch the HTTP transport instead (keep
Arrowhead bound to localhost and put a TLS reverse proxy—or a zero-config mesh
like Tailscale—in front if you expose it beyond your machine):

```bash
# Generate a new token (digest stored in config, raw token printed once)
arrowhead --mcp-server --generate-token

# Start the server on an explicit bind address, allowing a CIDR range
arrowhead --mcp-server --bind 0.0.0.0:3911 --allow 10.0.0.0/8 --token $ARROWHEAD_TOKEN
```

The server enforces bearer headers by default. In link-token mode
(`--auth-mode link-token`) clients without header support can call
`POST /rpc/<token>`; combine with HTTPS via a reverse proxy for production.

### Agent compatibility

Arrowhead’s CLI and MCP transports integrate cleanly with [OpenClaw](https://openclaw.ai/), so you can point its workspace runner at your local vault and get semantic search plus graph tooling without extra glue code. Local Claude Code sessions benefit as well: launch `arrowhead init` inside the vault, keep the daemon running, and the agent inherits fast search + discovery commands out of the box.

## Workspace configuration

Arrowhead still prefers `.obsidian` metadata when it exists, but any plain Markdown directory can be configured by editing `.arrowhead/workspace.toml`. The file stores the same levers we usually read from Obsidian:

- `attachments_dir`: relative folder where binary assets live.
- `ignored_folders`: directories that should be skipped during indexing.
- `daily_note_format`: file-name template for daily notes (e.g., `YYYY-MM-DD`).
- `link_style`: preferred link behaviour (e.g., `relative`, `absolute`, `shortest`).

Running `arrowhead init --attachments-dir Assets --ignore Drafts --daily-note-format "YYYY-MM-DD"` populates these values automatically. Later adjustments don’t require a destructive re-initialisation—use `arrowhead workspace set --ignore Drafts --ignore Private` (and optional `--clear-*` flags) to update the TOML in place. If both `.obsidian` and `.arrowhead/workspace.toml` exist, Arrowhead logs a warning and sticks with the Obsidian settings so you always match what the editor expects.

### Memory footprint

The daemon keeps semantic search ready by loading the `fastembed` model into an embedding pool sized to your CPU count (up to eight concurrent model handles). Each handle pulls the ~90 MB ONNX weights plus ONNX Runtime state, so full semantic mode typically consumes around 1 GB of RAM even when idle.  
If you only need full-text indexing or want a lighter runtime, disable embeddings:

```bash
# Initialize the vault without semantic embeddings
arrowhead init --fts-only

# Or launch manually with embeddings disabled
ARROWHEAD_EMBEDDING_MODEL=none arrowhead index start
```

This keeps FTS indexing and search working while skipping the model downloads and heap allocations that normally dominate the daemon's memory footprint.

## Architecture

```
arrowhead/
├── crates/
│   ├── arrowhead-core/     # Vault I/O, indexer engine, search & graph primitives
│   ├── arrowhead-daemon/   # Background runtime (watcher, queue, control socket, binary)
│   ├── arrowhead-mcp/      # MCP protocol (stdio runtime, handlers, tooling)
│   └── arrowhead-cli/      # CLI (clap commands, config, runtime bootstrap)
├── docs/                   # Specs, protocol references, development guides
└── tests/                  # Integration harness and fixture vaults
```

### Library Surface

- `arrowhead-core` exposes vault discovery, indexing, embeddings, search, and graph primitives (`Vault`, `Indexer`, `SearchService`, `GraphService`, etc.).
- `arrowhead-mcp` implements the stdio and HTTP transports plus shared tool handlers.
- `arrowhead-cli` wraps the runtime with `clap` commands under `crates/arrowhead-cli/src/commands/`.
- All public crates use `anyhow::Result<T>` for fallible operations and share data types via `arrowhead_core::types`.

## Technology Stack

- **Language**: Rust 1.88 (2024 edition) with `anyhow`/`thiserror` for rich errors.
- **CLI**: `clap` 4.5+, `tracing` for structured diagnostics.
- **Daemon runtime**: `tokio` 1.40+ with `notify`-backed filesystem watching.
- **Database**: SQLite (`rusqlite`) with FTS5 and JSON metadata columns.
- **Vectors**: `fastembed` embeddings persisted via sqlite-vec inside the SQLite index.
- **MCP**: Standards-compliant stdio and Axum-based HTTP transports with shared request handlers.

## Building

```bash
# Uses `Cargo.lock` by default. Set `LOCKED=0` only if you intentionally want
# unlocked dependency resolution.

# Build all crates
cargo build

# Build release version
cargo build --release

# Install CLI + daemon (installs `arrowhead` + `arrowheadd`)
make install PREFIX=$HOME/.local FORCE=1

# Run CLI
arrowhead --help
arrowhead --version

# Run tests
cargo test
```

## Usage overview

```bash
# Initialize a vault (creates .arrowhead/, prepares index DB, offers auto-start)
arrowhead init --vault /path/to/vault [--embeddings fast|good|better|none] [--fts-only]
# (Subsequent commands reuse the stored vault path.)

# Launch or check the background indexer
arrowhead index start
arrowhead index status
# Interactive TUI output.
arrowhead index status --json
# Machine-readable status frames for agents/automation.
cat /path/to/vault/.arrowhead/daemon/status.json
# Immediate startup snapshot if the control socket is still coming up.

# Manage auto-start registration (per-user launchd/systemd)
arrowhead index autostart enable
arrowhead index autostart status
arrowhead index autostart disable

# Search (FTS, semantic, or hybrid)
arrowhead search fts "project roadmap"
arrowhead search semantic "notes about embeddings"
arrowhead search hybrid "mixed query"

# Pipe-friendly search output
arrowhead search fts "project roadmap" --format paths
arrowhead search semantic "notes about embeddings" --format ids

For boolean syntax, field scoping, and date filters, see [`docs/query_syntax.md`](docs/query_syntax.md).

# Graph pipelines
arrowhead graph orphans --format ids | head -20
arrowhead graph backlinks "Project Hub" --format ids

# CRUD helpers + graph analytics
arrowhead notes list --category project --limit 20
arrowhead graph context "Project Hub"
# Exploration-oriented context leads
arrowhead context day 2026-04-14
arrowhead context week --this
arrowhead context month --this
arrowhead context changed --days 3
arrowhead context note "Project Hub"
# Compatibility aliases retained pre-1.0
arrowhead graph context "Project Hub"
arrowhead notes similar "Photography Equipment"
arrowhead notes surprise "Project Hub" --limit 3 --json
arrowhead context metric body.weight
arrowhead context metric body.weight --range past30d
arrowhead context source withings --range past30d
# JSON/MCP context payloads now expose evidence tiers and inferred confidence on leads/pivots
# Window/source contexts also surface metric trends and aggregate pivots when available
arrowhead metrics search "key:nutrition.energy_intake date:past7d" --aggregate sum

# Tail structured logs
tail -f /path/to/vault/.arrowhead/logs/cli.log
tail -f /path/to/vault/.arrowhead/logs/daemon.log

# Stop the indexer or clean up Arrowhead artifacts
arrowhead index stop
arrowhead vault reset

# Run the MCP stdio server for Claude or other clients
arrowhead --mcp

# Launch the HTTP MCP transport (bearer auth by default)
arrowhead --mcp-server --bind 127.0.0.1:3911 --token $ARROWHEAD_TOKEN

# Run with a Tailscale funnel (after enabling funnel for your node)
tailscale serve https / http://127.0.0.1:3911

# Generate a token (digest persisted, token printed once)
arrowhead --mcp-server --generate-token
```

Semantic-only matches surface `"N/A"` in the BM25 column of the human-readable output to clarify that no lexical score is available. Graph listings pick up the same pipe-friendly `--format ids` option for backlinks, forward-links, orphans, and unresolved link reports.
Context commands are exploration-first: day views emphasise notes added or edited, metrics recorded, link activity in changed notes, adjacent days, and concrete next pivots instead of count-heavy summaries.

## CLI Reference

- `arrowhead init` — bootstrap a vault, seed configuration, and offer auto-start registration when requested.
- `arrowhead index <subcommand>` — manage the background indexer (`start`, `stop`, `restart`, `status`, `autostart`).
- `arrowhead vault <subcommand>` — inspect filesystem state or reset Arrowhead caches (`status`, `reset`).
- `arrowhead search` — execute FTS, semantic, or hybrid searches with pipe-friendly output formats.
- `arrowhead notes` — perform note CRUD operations plus compatibility aliases that forward `notes similar` / `notes surprise` to `context note`.
- `arrowhead metrics <subcommand>` — inspect metrics files and records and mutate metric rows.
- `arrowhead context` — retrieve richer day, week, changed, note, metric, and source context views with stable JSON sections.
- `arrowhead graph` — inspect backlinks, forward links, orphans, unresolved links, or the `graph context` compatibility alias for `context note` (`--json` emits machine-readable payloads).
- `arrowhead --mcp[(-server)]` — launch the stdio or HTTP MCP transport with shared handlers, token auth, CIDR filtering, and `/health` readiness probes.

### MCP transport options

- `--bind <ADDR>` overrides the default bind address (`127.0.0.1:3911`); `ARROWHEAD_MCP_BIND` mirrors the flag.
- `--auth-mode <bearer|link-token>` switches between header-based and path-embedded tokens.
- `--token`, `--token-file`, `--token-hash` supply raw or hashed credentials; `ARROWHEAD_MCP_TOKEN` adds a raw token from the environment.
- `--allow` / `--allow-file` append CIDR ranges to the default localhost allowlist.
- `--generate-token` mints a random token, persists its digest, prints usage snippets, then exits.

## MCP Tool Surface

- After initialization, call `mcp.discovery.get_vault_conventions` so agents load vault naming rules, metadata expectations, and the bundled playbook before mutating notes.
- Graph: `mcp.graph.get_context`, `mcp.graph.get_backlinks`, `mcp.graph.get_forward_links`, `mcp.graph.find_orphans`, `mcp.graph.find_unresolved`
- Context: `mcp.context.get_day`, `mcp.context.get_week`, `mcp.context.get_month`, `mcp.context.get_changed`, `mcp.context.get_note`, `mcp.context.get_metric`, `mcp.context.get_source`
- Search: `mcp.search.fts`, `mcp.search.semantic`, `mcp.search.hybrid`
- Notes: `mcp.notes.list`, `mcp.notes.read`, `mcp.notes.metadata`, `mcp.notes.create`, `mcp.notes.update`, `mcp.notes.delete`
- Discovery: `mcp.discovery.get_related_notes`, `mcp.discovery.get_vault_stats`, `mcp.discovery.get_vault_conventions`
- Vault: `mcp.vault.status`
- Protocol: `mcp.protocol.initialize`, `mcp.protocol.tools/list`

Semantic and hybrid tools require embeddings; discovery fallbacks lean on graph heuristics when embeddings are disabled. Place vault-level guidance in `ARROWHEAD.md` at the root—the conventions tool returns its contents alongside the bundled `AGENTS.md` playbook so Claude/Codex agents inherit both global instructions and vault-specific preferences.

## MCP Protocol Details

### Transport modes

- **stdio (`arrowhead --mcp`)**: newline-delimited JSON-RPC 2.0 over stdin/stdout with a bounded request queue (64 pending by default). When the queue or worker pool is saturated the server returns a `RateLimited` error and logs summary metrics on shutdown.
- **HTTP (`arrowhead --mcp-server`)**: JSON-RPC 2.0 on `POST /rpc` with identical handler logic, request limits, and error mapping; malformed JSON produces `400`, authentication failures produce `401`/`403`, and backpressure surfaces as HTTP 429. `GET /health` offers a readiness probe.

Both transports share the handlers defined in `crates/arrowhead-mcp`, so behaviour is consistent regardless of client wiring.

### Authentication & network policy

- Tokens are hashed with SHA-256 before persistence; raw strings never touch disk or logs.
- Bearer mode (default) expects `Authorization: Bearer <token>` headers; link-token mode accepts `/rpc/<token>` paths while still honouring bearer headers. Prefer HTTPS when using link-token to keep credentials out of plaintext URLs.
- `--generate-token` prints a one-time secret and stores only the digest; record the raw value immediately.
- The HTTP transport allows only localhost traffic by default (`127.0.0.0/8`, `::1/128`). Extend access with `--allow`, `--allow-file`, or corresponding config entries so that non-local clients are admitted intentionally.

### Example request

```json
{"jsonrpc":"2.0","id":1,"method":"mcp.notes.create","params":{"title":"Projects/Test Plan","content":"# Test Plan"}}
```

```json
{"jsonrpc":"2.0","id":1,"result":{"noteId":"Projects/Test Plan","title":"Projects/Test Plan","metadata":{"title":"Projects/Test Plan"},"content":"# Test Plan","relativePath":"Projects/Test Plan.md","fileModifiedAt":"2024-01-18T08:53:00Z"}}
```

### Reverse proxy guidance

Terminate TLS in a reverse proxy (nginx, Caddy, Traefik, Cloudflare Tunnel, Tailscale Funnel, etc.) and forward traffic to the loopback-bound MCP server. A minimal nginx snippet:

```
server {
    listen 443 ssl http2;
    server_name arrowhead.example.com;

ssl_certificate     /etc/letsencrypt/live/arrowhead.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/arrowhead.example.com/privkey.pem;

location / {
        proxy_pass       http://127.0.0.1:3911;
        proxy_set_header Host              $host;
        proxy_set_header X-Real-IP         $remote_addr;
        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto https;
    }
}
```

Keep the Arrowhead allowlist scoped to loopback so all external traffic is funneled through the proxy. Layer OAuth/OIDC (e.g., oauth2-proxy, Cloudflare Access) in front when you need user-facing authentication.

## Roadmap

Active roadmap items are tracked on GitHub and currently include:

- Adding MCP transport metrics with TLS/reverse-proxy guidance.
- Expanding graph diagnostics for large vaults.
- Hardening semantic and hybrid search scoring.
- Improving embedding model management UX.
- Tracking sqlite-vec dependency health and minimum supported Rust version updates.

## Release Process

- Tag the commit you want to ship with `vX.Y.Z`; pushing the tag triggers the `Release` workflow.
- The workflow re-runs formatting, clippy, and tests on Ubuntu, then builds macOS Intel and Apple Silicon binaries with `cargo build --release`.
- Binaries are packaged as `arrowhead-<version>-<target>.tar.gz` with `bin/arrowhead`, `bin/arrowheadd`, and the project README.
- The GitHub release body includes install instructions, artifact SHA256 sums, and conventional-commit changelog notes since the previous tag.
- Set a personal access token with `repo` scope as the `HOMEBREW_TAP_TOKEN` repository secret so the workflow can push tap updates to `totocaster/homebrew-tap`.
- The tap formula is rewritten automatically to point at the new release URLs and SHA256 sums for both macOS architectures.

## License

Distributed under the MIT License. See [`LICENSE`](LICENSE) for details.

## Contributing

We welcome issues and pull requests once the Arrowhead foundation is fully stabilized. Start by reading this README and the [feature development guide](docs/feature_development_guide.md). Make sure `cargo fmt`, `cargo clippy`, `cargo check`, and `cargo test` pass before submitting changes.

## Acknowledgments

Arrowhead is the Rust rewrite of [Synapse-Obsidian](https://github.com/totocaster/Synapse-Obsidian), originally a macOS Swift app. Huge thanks to the early users and contributors whose feedback shaped the new CLI-first architecture.

arrowhead

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README