sem-ctx

CLI

Find your files in plain english.

sem-ctx is a lightweight, local, location-agnostic semantic search utility for agents. It runs a local vector embedding model to surface the notes that match your plain english query, and resolves templates and target folders so agents know where new markdown files belong.

View on GitHub

zsh — sem-ctx

# point it at your notes once
$ sem-ctx set-default ~/notes

# search by meaning, not keywords
$ sem-ctx search "authentication workflow"
  notes/auth/login-flow.md        0.84
  notes/security/session-mgmt.md  0.71

# find a template + where new items belong
$ sem-ctx template "work item" --json

// what it does

Local semantic search

Fast vector search powered by BAAI/bge-small-en-v1.5 running locally via fastembed. Nothing leaves your machine.

Template lookup

Resolve the best template, target folder, nearby examples, and naming conventions for a new item, so your agent can create the file in the right place with the right shape.

Talk to your Agent like a Human.

No more keyword gymnastics or passing in file paths to find the right file. Just ask for what you need in plain english, and sem-ctx will help your agent figure out the rest.

// setup

Install (editable)

# with uv (recommended)
cd sem-ctx
uv tool install --editable .

Prefer a venv? python -m pip install -e . inside an activated virtual environment works too.

Set your directory

sem-ctx set-default \
  path/to/your/notes

Or override per-run with --dir, the SEM_CTX_DIR env var, or a local .sem-ctx.json.

Search

sem-ctx search \
  "login issues"

The index builds on first run; force a rebuild any time with sem-ctx reindex.

// commands

search "<query>"

Semantic vector search over your markdown. Add --json for structured results.

template "<kind>"

Find the best template, target folder, nearby files, and ranked candidates for a new item.

set-default <dir>

Set the global default target directory so you can skip --dir on every call.

install-protocol

Add (or update) the Semantic Context agent protocol block in an AGENTS.md.

reindex

Re-scan the directory and force-rebuild the embedding index from scratch.