How to use CruxHive

Quick start

From zero to first knowledge entry in under 3 minutes.

Requirements

Setup steps

1. Install the CLI

This gives you the cruxhive command. The Python MCP server (cruxhive-mcp) is installed automatically in the next step.

Want to install the Python server manually first (e.g. with extras)?

2. Init a project

Run from your project root. CruxHive detects your AI tools automatically and wires itself in.

3. Edit CONTEXT.md

Open .llm/CONTEXT.md and fill in your project description, stack, and key conventions. This is the file every AI tool reads at the start of every session.

4. Index and verify

5. Reload your AI tool

Restart Claude Code, OpenCode, Cursor, or Windsurf. The MCP server starts automatically. All CruxHive tools are now available in your AI sessions.

How it works

CruxHive has three moving parts:

• .llm/CONTEXT.md — the canonical context file. Every AI tool reads this. It's a symlink target — CLAUDE.md, AGENT.md, .cursor/rules/cruxhive.mdc all point here. One file, zero drift.
• .llm/cruxhive.db — SQLite knowledge base. Stores all indexed entries with FTS5 full-text search and optional vector embeddings for semantic search.
• cruxhive-mcp — local MCP server. Exposes 11 tools that any MCP-compatible AI tool (Claude Code, OpenCode, Cursor, Windsurf) can call to search, propose, and review knowledge.

The core loop: AI proposes → human approves → knowledge persists → next session starts smarter. Nothing enters the shared base without a human sign-off. That's the quality gate that prevents AI hallucinations from accumulating over time.

Three-tier model

CruxHive organises context across three independent tiers, each with different access control and different consumers.

The org layer lives in a shared git remote. Configure it in cruxhive.config.yaml and run cruxhive sync to pull org context into any project.

Knowledge types

Every entry has a type field. Type determines how long it stays valid, how it's routed for approval, and how the health dashboard weighs it.

Frontmatter spec

Every .llm/ markdown file carries a YAML frontmatter block. CruxHive reads this to populate the search index and drive approval routing.

Rules: source: ai-proposed entries are confidence-capped at medium until approved. invalid_at set means the entry is deprecated — it stays in git history but is excluded from search. supersedes: filename.md links replacements.

Daily workflow

Proposing entries

There are three ways to propose a knowledge entry:

1. CLI (interactive)

2. MCP tool (from your AI session)

Ask your AI tool: "Propose a constraint: never use eval() in our codebase — XSS risk." It calls context_propose automatically.

3. Write directly

Create any .md file under .llm/pending/ with the correct frontmatter. Run cruxhive index to add it to the search index.

All proposals land with source: ai-proposed and approved_by: ~. They are searchable immediately but flagged as pending in cruxhive health.

Reviewing & approving

Proposals need a human to approve before they're treated as trusted knowledge (confidence: high, source: human).

Terminal (recommended)

Web dashboard

MCP tools (from your AI session)

Call context_review to list pending, then context_approve or context_reject with the file path.

Searching

Use natural language. CruxHive combines BM25 keyword matching with optional vector search (Nomic Embed v1.5) fused via Reciprocal Rank Fusion at k=60. Finds relevant entries even when your query doesn't share exact words.

From your AI session

Ask your AI tool: "Search the knowledge base for auth token storage patterns." It calls context_search automatically.

Via MCP tool directly

Enable hybrid search

Slash commands (cross-tool)

cruxhive init writes six slash commands into both .claude/commands/ (Claude Code) and .opencode/commands/ (OpenCode). Same command name, same behaviour, same MCP tool under the hood.

/extract is the auto-capture loop with the approval gate intact: the AI proposes, you approve. Run it at the end of a long conversation to surface durable facts before they're lost.

Cursor and Windsurf don't have a slash command system, but the same MCP tools are reachable via natural language ("run radar", "what's the next slice for auth?") — they'll route to the right tool.

Examples

Weekly health check

Observability — measure what CruxHive is doing for you

Every MCP tool call is logged locally to .llm/cruxhive.db. No data leaves your machine. Disable with CRUXHIVE_ANALYTICS=0.

What gets logged

• Every call to context_search, context_propose, context_approve, context_reject, context_review, context_index, context_check_faithfulness
• Which AI tool called it (detected via env vars — Claude Code, Cursor, OpenCode, Windsurf)
• The search query (truncated to 500 chars), result count, and latency
• Faithfulness check violations (when cruxhive-mcp[full] is installed)

Terminal dashboard

Web dashboard

cruxhive ui opens four tabs at localhost:3847:

What decisions this enables

• Which AI model to use: compare hit rate and proposal approval rate per tool
• What to document next: zero-result queries are your backlog
• When to audit: stale entries list flags knowledge that may give confidently-wrong answers
• Whether the governance loop is healthy: pending queue age > 14 days = review is the bottleneck

Workspace rollup, digest, and trends

Once you've initialized CruxHive in multiple projects, you can get a cross-project view of activity, gaps, and decay without cd-ing into each one.

Cross-project KPIs in the terminal

Reads ~/.cruxhive/config.yaml if present, otherwise auto-discovers projects under ~/Projects_Local/Development/.

Workspace dashboard in the browser

Weekly digest with trend comparison

One-line health for hooks

The 5 KPIs that matter

Memory intelligence (without bypassing approval)

Mem0 / Zep patterns adapted to CruxHive's human-gated model — no auto-write.

Entity-aware search

At index time, CruxHive extracts simple entities from each entry: snake_case identifiers, ALL_CAPS constants, IPv4s, hostnames, filenames with extensions. At search time, queries that mention any of those entities boost matching entries — and pull in entries BM25 would have missed entirely.

Recency boost in search ranking

Banded score multiplier on top of BM25 + vector + entity match: ≤7 days old +0.20, ≤30 days +0.10, ≤90 days +0.05. Recent edits float to the top without burying older but topically-relevant matches.

Confidence decay (computed at search time)

confidence: high entries auto-downgrade as they age — to medium after 60 days, to low after 120 days. The stored frontmatter never changes; the effective confidence is computed live so search results reflect current trust. Decayed entries surface in cruxhive digest with a "revalidate or deprecate" prompt.

Ephemeral entries

Set source: ephemeral in the frontmatter (or pass ephemeral=true to context_propose) for AI-extracted "soft" facts. They auto-expire after 7 days unless explicitly approved and promoted to source: human. Catches Mem0-style decay without an auto-write gate.

Conflict detection at review time

If cruxhive-mcp[full] is installed, each pending entry is scanned by NLI against existing approved constraints. Contradictions are surfaced in both the CLI cruxhive review output and the web UI approval card — so you catch drift before approving, not after.

Automation and hooks

What cruxhive init wires up so CruxHive runs itself in the background.

All logging is local. Opt out with CRUXHIVE_ANALYTICS=0. Rate-limited: repeated cd doesn't spam session events.

CLI commands

MCP tools

Available in any MCP-compatible AI tool (Claude Code, OpenCode, Cursor, Windsurf). Call them by name or ask your AI to use them.

AI tool support

All tools load from the same .llm/CONTEXT.md via symlinks — one file, zero drift. Run bootstrap.sh (from ai-toolkit/) to wire all detected tools at once.

Troubleshooting

MCP tools not appearing in Claude Code

Check .mcp.json in your project root has a cruxhive entry. Restart Claude Code after editing. Verify cruxhive-mcp is on your PATH: which cruxhive-mcp.

context_search returns no results

Run cruxhive index first. The SQLite database (.llm/cruxhive.db) must be built before search works. It's not created automatically on install.

cruxhive-mcp not found

cruxhive ui fails to start

The web UI requires the [ui] extra: pip install "cruxhive-mcp[ui]". This installs FastAPI and uvicorn.

Vector search not working

Install the [full] extra: pip install "cruxhive-mcp[full]". The first run downloads ~270 MB of model weights (cached in ~/.cache/huggingface/). Then run cruxhive index to build vectors.

CONTEXT.md not loading in Cursor

Verify the symlink: ls -la .cursor/rules/cruxhive.mdc. It should point to ../../.llm/CONTEXT.md. Re-run bootstrap.sh if missing.