openContext
Open workspace

Resources

Install OpenContext

Clone and run the local OpenContext app, configure a model, ingest documents, and connect the CLI or an MCP client.

Start here

Explore the interactive demo without an account, or open your workspace to create an account or sign in. No invitation or app installation is required. Local setup is also available for developers with repository access.

The demo uses fictional example data and runs in your browser. Opening a workspace takes you to the app, where you can create an account or sign in and start with your own sources.

The installation guide below is for developers and testers who have separately been given access to the local app through the private repository.

Already installed?

From your openContext checkout, run npm run dev and leave the terminal open. Once it reports that the app is ready, open your local workspace. This link works only on the computer where the local app is running.

Installation guide

Install the local app by downloading the source from GitHub and running the commands below. The repository is currently private, so your GitHub account needs access before you can clone it. A public downloadable package is not available yet. For the hosted app, use the browser access above; these instructions create a separate local installation.

This setup also installs the command-line tool (CLI) and Model Context Protocol (MCP) server for connecting agents. The agent setup guide covers the complete command-line workflow, file ingestion, graph reads, and MCP configuration.

Prerequisites

  • Node 22 or newer (node --version; the repo ships an .nvmrc) and the npm that comes with it.
  • git installed where your shell can find it. Vault versioning, rollback, and repository ingestion all shell out to it.
  • A model credential, one of: an Anthropic API key (the credential that identifies your account with Anthropic), an OpenRouter key, or a logged-in Claude Code CLI (claude, then /login). Nothing yet? Demo mode below runs the whole pipeline on a simulator.
  • macOS and Linux are supported. Windows is best effort: the scripts avoid shell-specific syntax (npm run dev, npm run demo, npm start work), but npm run free-ports relies on lsof and does nothing there.
  • Disk: about 520 MB of node_modules after setup, as observed on one macOS machine; it varies by platform. Roughly 320 MB of that is the Claude runtime the Agent SDK (Anthropic's software development kit) downloads for your platform from the npm registry as an optional dependency at install time; no separate Claude Code install is needed.

Quick start

Download the application from GitHub, then install the app and its command-line tools:

git clone https://github.com/Alec-Merle/OpenContext.git
cd OpenContext
npm run setup          # npm install + web install + web build, in one go
npm link               # installs opencontext and opencontext-mcp from this checkout
npm run doctor         # free: names anything missing (Node, git, credential, ...)
npm run dev            # web on http://localhost:8080, API on loopback port 4477

Leave the terminal running and open http://localhost:8080. Configure a model in Settings, Models, choose the vault in Settings, Environment, and drop a document onto the Intake page. The Activity feed shows ingestion progress.

npm link uses this checkout rather than a public registry package. Keep the checkout in place. The npm package named opencontext belongs to another project; do not install it as a shortcut. If npm cannot create global links, use node /absolute/path/to/OpenContext/cli/opencontext.js in place of opencontext.

npm run doctor writes nothing, spends nothing, and kills nothing: it checks the Node version, git, the Agent SDK's bundled runtime, the web build, .env, which model credential the server would see (presence only, never a value), the vault, and whether the ports are free, and exits 1 only on a hard failure. npm run doctor:live spends one small model call to prove the SDK authenticates with the credential and model the server would actually use.

Credentials

The ingestion agent runs on the Claude Agent SDK, which uses whichever credential it finds, in this order:

  1. an Anthropic API key pasted in Settings, Models, kept in vault/_state/anthropic.json (readable only by your own user account, never returned by the server, unreadable to the agents) and used by the next run, no restart; or
  2. ANTHROPIC_API_KEY in <repo>/.env. The server reads .env itself at boot, so restart after editing it. cp .env.example .env to begin; the example file lists every setting; or
  3. a logged-in Claude Code CLI: run claude in a terminal once and /login.

Prefer OpenRouter? Settings, Models can route every run through openrouter.ai instead: paste an OpenRouter key, flip the provider, and pick any model they serve. Or in .env: OPENROUTER_API_KEY=sk-or-... plus OPENCONTEXT_PROVIDER=openrouter. Vault-building leans on tool use, so models that support tool use are recommended.

Demo mode

No credential yet? Demo mode runs the full pipeline with a deterministic simulator instead of the model, spending no tokens:

npm run demo                         # any platform, disposable vault

The demo uses a temporary vault and cannot switch into your personal vault. Restart normally to return to your own files. The low-level OPENCONTEXT_FAKE_AGENT=1 test flag does not provide this isolation by itself and should only be used with an explicitly configured scratch vault.

Point your coding agents at it

After the quick start, open a second terminal and check the CLI's connection:

opencontext status --json

If the app requires sign-in, run opencontext login --email you@example.com and enter the account password at its hidden prompt. Then run these commands from a repository you work in:

cd /absolute/path/to/your-project
opencontext link --yes
opencontext context "What should I know about this project?"

link writes managed guidance into the repository's agent instruction files and installs Claude Code and Codex context hooks. Review the changes with git diff, then enable or trust the hooks in the client. To undo the connection, run opencontext unlink --yes. Linking alone does not index source code: add the repository in Projects to build its graph.

For MCP, open Settings, Connect your AI tools and copy your client's configuration. The MCP setup guide also provides JSON and Codex examples with explicit Node, checkout, and vault paths.

Add documents from the terminal

Replace the example path below with an existing document:

opencontext contribute "/absolute/path/to/project-brief.pdf" --wait --json
opencontext capture "The team chose weekly releases so support can prepare customer updates." --label "Release cadence" --wait --json
opencontext search "release cadence" --json

The app must be running to ingest files or notes. Check the returned job status before treating the contribution as complete; review a held result in the app's Privacy pane or Activity feed. Search returns entity paths you can read with opencontext get <path>. Use the agent guide for batch limits, stdin input, following relationships, and MCP tool calls.

Where the vault lives

The vault is a plain folder of markdown. At boot the server resolves it in this order: a vault chosen in the app (Settings, Environment, Switch vault), then OPENCONTEXT_VAULT from the environment or .env, then <repo>/vault. The default lives inside the app checkout, and the server says so at every boot: keep it elsewhere by setting OPENCONTEXT_VAULT to a folder outside the checkout, or switch in Settings. Boot refuses to scaffold a vault into a folder that already holds files OpenContext did not create unless OPENCONTEXT_VAULT_ADOPT=1 grants it.

Upgrade

git pull
npm run setup      # dependencies may have changed, and the web build must be redone
npm run typecheck
npm test
npm run dev

Nothing in the vault is migrated by an upgrade; the vault format is markdown and stays readable across versions. If the distillation logic changed, the app may report already-ingested sources as stale and offer to re-distill them. It never does so on its own.

Back up and restore

The vault is a git repository with one commit per operation, so local history is already a backup against your own mistakes. For an off-machine copy, connect a GitHub or GitLab account in Settings, Environment, point the vault at an empty remote repository, and push; or press Download my vault for a zip of every knowledge file, the _sources/ originals, and the full git history. Restore is a clone plus a pointer:

git clone <the vault remote> ~/opencontext-vault
# then set OPENCONTEXT_VAULT=/Users/you/opencontext-vault in .env and restart,
# or use Settings > Environment > Switch vault to point at it

A restore from the remote brings back the knowledge graph, not the secrets: reconnect Drive, Gmail, X, and the forges, and re-enter the model key in Settings, Models.

Development

npm run dev           # tsx watch server (4477) + vite (8080, proxies /api)
npm run typecheck     # server + web
npm test              # the whole offline suite - no network, no tokens, no spend

Every push and pull request runs the same three on Node 22 in GitHub Actions, with every model credential blanked so a green continuous-integration run can never have spent anything. This is release 0.2.0; the changelog has what changed.