getting started

Add source-backed AI memory without a vector database.

ContextFit can be used directly from the CLI, exposed to Claude Desktop through MCP, or called by local agents and scripts through JSON output. Start with one local knowledge base, then add named vaults when your memory grows.

Start in 5 minutes Claude Desktop config

Local MCP quickstart

Get started in 5 minutes.

ContextFit's MCP server runs on your Mac. Install ContextFit, build a local knowledge base, then point Claude Desktop at the local command.

Install ContextFit

Create a Python virtualenv and install the local contextfit command with pip.

Create a local KB

Ingest a folder from your Mac into ~/contextfit_kb. ContextFit indexes files locally.

Add Claude Desktop MCP

Put the absolute contextfit path into Claude's MCP config, restart Claude, then ask it to search.

Best first path

Claude Desktop

Local MCP clients

CursorWindsurfVS CodeClaude Code

Agent / CLI

OpenClawHermescron jobsshell scripts

Note: browser-only apps generally cannot launch a local stdio MCP server directly. Start with Claude Desktop or another local MCP-capable client.

Install

Run ContextFit locally.

Install from the repo, then create a local knowledge base from a folder of documents.

Install the package

mkdir -p ~/contextfit
cd ~/contextfit
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install contextfit

Contributing from source? Clone the GitHub repo and run python -m pip install -e . from the project root.

Ingest a folder

contextfit --kb ~/contextfit_kb ingest ~/Documents/project-orion-notes \
  --defer-index-build \
  --rebuild-index-after-ingest

Ask a question

contextfit --kb ~/contextfit_kb query "What are the open launch risks?" --json

Use the absolute executable path for Claude

which contextfit
# Example: /Users/YOU/contextfit/.venv/bin/contextfit

CLI

Use it as a memory command line.

The CLI is the fastest path for local development, scripts, and agent tooling.

Default knowledge base

contextfit --kb ~/contextfit_kb stats --json
contextfit --kb ~/contextfit_kb query "Acme renewal audit" \
  --method hybrid \
  --top-k 8 \
  --json

Named vault commands

contextfit vaults list --json
contextfit search "Acme renewal audit" --vault work --json
contextfit search-all "website tokenization" --json
contextfit chunk 42 --vault work --json

Claude Desktop MCP

Give Claude a local memory tool.

Claude Desktop becomes the chat UI. ContextFit stays local and serves source-backed search results through MCP.

New MacBook checklist

Claude Desktop works best when the config uses absolute paths. First run which contextfit, then open the config file:

mkdir -p "$HOME/Library/Application Support/Claude"
open -e "$HOME/Library/Application Support/Claude/claude_desktop_config.json"

Claude Desktop config

{
  "mcpServers": {
    "contextfit": {
      "command": "/Users/YOU/contextfit/.venv/bin/contextfit",
      "args": [
        "--kb",
        "/Users/YOU/contextfit_kb",
        "mcp",
        "--top-k",
        "8",
        "--method",
        "hybrid"
      ]
    }
  }
}

Important: replace /Users/YOU/contextfit/.venv/bin/contextfit with the output from which contextfit, then quit and reopen Claude Desktop with Cmd+Q. Privacy model: ContextFit reads the local KB path you configure. Claude only sees the snippets returned as tool results.

Vault registry

Keep memory separated by source.

`~/.contextfit/vaults.json`

{
  "vaults": {
    "work": {
      "kb_path": "/Users/YOU/contextfit_work_kb",
      "description": "Work docs, notes, and project memory"
    },
    "research": {
      "kb_path": "/Users/YOU/contextfit_research_kb",
      "description": "Papers, references, and experiments"
    },
    "personal": "/Users/YOU/contextfit_personal_kb"
  }
}

Local agents

Call ContextFit from your runtime.

For OpenClaw, Hermes, shell scripts, and cron jobs, JSON CLI output is often simpler than MCP.

Search then fetch

contextfit search "Project Orion unresolved decisions" \
  --vault work \
  --top-k 5 \
  --json

contextfit chunk 42 --vault work --json

When to use what

Use MCP for interactive desktop clients like Claude Desktop.

Use CLI JSON for local agents, background jobs, tests, and automation.

Use vaults when different memory sources should stay explicit and opt-in.