Get Started

Run your first context in 5 minutes. Choose your path below.

Choose Your Path

Desktop App

Personal knowledge/notes management
CLI + Cursor

AI agent loads & persists context
CLI Only

Command-line management & search
A

Desktop App

Recommended

Manage contexts like a normal notes app — browse, search, and edit. No CLI required.

1 Download & Install

Download for macOS / Windows

Redirects to GitHub Releases

2 First Time Setup (1 min)

  • Create a folder (e.g., personal/ or project-x/)
  • Create your first doc

Recommended doc types: Project background, Known pitfalls, API contracts, Acceptance criteria

3 Search Your Content

  • Shortcut: Cmd/Ctrl + K
  • Searches all folder/doc titles, descriptions, and content
  • Semantic search: Configure API Key in Settings → Embedding (auto-indexed)

4 Cite to Cursor / Agent Optional

If you use Cursor or other AI assistants, you can directly cite content from the Desktop app — no CLI needed.

Action Steps Effect
Cite text snippet Select text → Right-click → "Copy Citation" Agent reads snippet + source
Cite document Click citation icon next to doc title Agent gets full doc + stable_id
Cite folder Right-click folder → "Copy Folder Citation" Agent batch-reads all docs inside

5 When Do I Need CLI?

Desktop is enough for:

  • Manually managing and editing docs
  • Manually copying citations to Cursor/Agent

You need CLI if you want:

  • Give Agent the ability to search & read context autonomously (Tool Use)
  • Persist insights directly from chat via slash commands
  • Full bi-directional interaction via MCP protocol

→ Continue to Path B below for CLI setup

B

CLI + Cursor / Agent

For Developers

Let Cursor or coding agents call OpenContext as MCP tools, with beginner-friendly slash commands.

Prerequisites

  • Node.js installed (npm / npx available)
  • Cursor (or other MCP-compatible agent platform)

Step 1: Install CLI

$ npm install -g @aicontextlab/cli
# or use npx: npx @aicontextlab/cli <command>

Step 2: Initialize in Your Repo

Run this inside the repo where you want Cursor features:

$ oc init
What oc init does:
  • Prepares global context store (if first time)
  • Generates Cursor artifacts (AGENTS.md, .cursor/mcp.json, .cursor/commands/)
  • Safe to run multiple times (idempotent)

Default Paths

  • Contexts: ~/.opencontext/contexts
  • Database: ~/.opencontext/opencontext.db

Override with environment variables:

export OPENCONTEXT_CONTEXTS_ROOT="/path/to/contexts"
export OPENCONTEXT_DB_PATH="/path/to/opencontext.db"

Step 3: Use Beginner Commands

Ordered from "safe default" to "powerful" — start from the top:

/opencontext-help Not sure which to use? Start here
/opencontext-context (Safe default) Load background before working
/opencontext-search Discover existing docs (no auto index build)
/opencontext-create Draft a new doc/idea
/opencontext-iterate Persist conclusions & citations

These commands read/write your global OpenContext library (~/.opencontext/contexts), not the current repo.

C

CLI Only (No Cursor)

Use OpenContext purely from the command line for management and search.

# Minimal example
oc folder ls --all
oc folder create project-a -d "My project"
oc doc create project-a design.md -d "Design doc"
# Search & manifest
oc search "your query" --mode keyword --format json
oc context manifest project-a --limit 10

Search & Embedding Config

Desktop App: Auto Index

The Desktop app automatically builds and updates the search index in the background. No manual oc index build needed — just configure your embedding provider in Settings.

Search Modes

--mode keyword

No embeddings needed

--mode vector

Requires embeddings + index

--mode hybrid

Requires embeddings + index (default)

CLI Index Cost Policy

When using CLI, semantic search requires oc index build which may use paid APIs. AI assistants are NOT allowed to auto-run it by default.

For CLI users: To enable hybrid/vector search, configure your embedding provider:

# 1. Set sensitive API Key
oc config set EMBEDDING_API_KEY "<your_key>"
# 2. (Optional) Set base URL
oc config set EMBEDDING_API_BASE "https://api.openai.com/v1"
# 3. (Optional) Set Model
oc config set EMBEDDING_MODEL "text-embedding-3-small"
# 4. Build Index
oc index build

Recommended Daily Workflow

Before Work (1 min)
/opencontext-context

Load project background + known pitfalls

During Work
/opencontext-search

Search existing conclusions when uncertain

After Work (2 min)
/opencontext-iterate

Record decisions, pitfalls & next steps

Pro tip: Persist "acceptance criteria / common pitfalls / API contracts / dependency versions" as docs — highest ROI.

MCP Server

OpenContext runs as a standard MCP server (stdio).

  • Start manually: oc mcp
  • Cursor: Auto-configured via oc init

Web UI (Experimental)

Browse and edit contexts in your browser without the desktop app.

$ oc ui

Default address: http://127.0.0.1:4321

FAQ

Why can I see docs from Project A in Project B?

By design. Contexts are stored in a global shared library (~/.opencontext/contexts) for cross-repo reuse.

How do I change the default storage path?

Set environment variables before running oc commands:

export OPENCONTEXT_CONTEXTS_ROOT="/path/to/contexts"
export OPENCONTEXT_DB_PATH="/path/to/opencontext.db"

Why is semantic search unavailable?

Index may not be built or embeddings not configured. Use keyword search/manifest first; configure embeddings and run oc index build when ready.