requirements

base install

$ curl -sSL https://getflex.dev/install.sh | bash

Installs flex, creates storage (~/.flex/), and downloads the ONNX embedding model. No sessions are scanned, no services are started, and no MCP server is registered. This is the SDK path — use flex index and flex.sdk to build your own cells.

with claude code module

$ curl -sSL https://getflex.dev/install.sh | bash -s -- claude-code

Installs flex and immediately onboards your Claude Code session history. The installer scans existing sessions, embeds everything, builds the knowledge graph, starts a background worker and MCP server as system services, and wires the MCP endpoint into ~/.claude.json. After install, restart Claude Code and type /mcp to verify.

GNU flex collision? use the python -m escape hatch

$ python -m flex init

what happens

base: flex init

Creates ~/.flex/ storage and downloads the ONNX embedding model (~87 MB). No sessions are scanned, no services are started, no MCP server is registered. Use flex index to index a folder, or connect a data source via flex.sdk.

claude code: flex init --module claude-code

Everything in base, plus a full onboarding pass in one command:

Installs Claude Code assets (slash commands, retrieval agent), scans all existing sessions, embeds chunks, builds the knowledge graph, installs a background worker and MCP server as system services, and wires the MCP endpoint into ~/.claude.json.

After init, restart Claude Code and type /mcp to verify the flex tool is connected.

cli

flex init

Base setup — creates storage and downloads the embedding model. No session indexing, no services, no MCP registration.

$ flex init

flex init --module claude-code

Full Claude Code onboarding — model download, session indexing, knowledge graph, services, and MCP registration.

$ flex init --module claude-code

flex search

Query from the terminal without Claude.

$ flex search "@digest days=7"
$ flex search "@file path=src/worker.py"
$ flex search "SELECT COUNT(*) FROM sessions WHERE project = 'myapp'"

flex sync

Recovery command — reinstalls views, presets, services, and MCP wiring if anything drifts.

$ flex sync
$ flex sync --full       # also re-runs enrichment

files

Everything lives under ~/.flex/. One directory. Portable. Back it up with rsync. Query it directly — it's open format SQLite.

~/.flex/
├── models/              embedding model
├── views/               curated SQL views (user-editable)
└── cells/
    └── claude_code.db   your knowledge base — one file

~/.claude/
├── commands/flex/       slash commands (/flex:agent, /flex:search)
└── agents/trace.md      retrieval sub-agent

A background worker and MCP server are installed as system services (systemd on Linux, launchd on macOS) when using the claude-code module.

how it works

Three components. One direction.

~/.claude/projects/**/*.jsonl
       │
  [worker]  watches for new sessions every 2s, indexes changes automatically
       │
       ▼
  ~/.flex/cells/claude_code.db
       │
  [MCP server]  exposes cell as read-only SQL surface
       │
       ▼
  Claude writes SQL

worker

A system service (flex-worker on systemd/launchd) that scans session files every 2 seconds. For each session where the file size changed: parse the session, extract messages and metadata, embed, and write to the database. Three cycles: file scan (2s), full enrichment (30 min), and backfill + identity heal (24h). On platforms without a service manager, the MCP server's built-in background indexer handles scanning and enrichment.

MCP server

Stateless streamable HTTP server on localhost:7134/mcp. Exposes one tool: flex_search. Claude writes SQL, uses presets, or runs semantic and keyword searches. Read-only — all writes are blocked at the engine level. Claude reads the schema, then writes its own queries. Supports unlimited concurrent sessions. Works with Claude Code, claude.ai, Cursor, or any MCP client.

enrichment

Offline intelligence, computed automatically. The worker runs the full pipeline every 30 minutes:

All enrichment is safe to wipe. Recomputed automatically.

scope exclusion

If you use MCP tools that generate noisy tool calls, you can exclude them from indexing. Add patterns to ~/.flex/config.json:

{
  "scope": {
    "exclude_tools": ["mcp__noisy_server_*", "some_other_tool"]
  }
}

Patterns use fnmatch syntax. Excluded tools are blocked before they enter the database.

troubleshooting

flex command not found or runs the wrong binary

Some systems have flex (the lexer generator) installed at /usr/bin/flex. If it shadows the flex CLI:

# use the python -m escape hatch (works always)
$ python -m flex init

# or fix your PATH
$ export PATH="$HOME/.local/bin:$PATH"

# or add to your shell profile
$ echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc

hdbscan build failure (Arch Linux)

hdbscan requires Cython and numpy headers at build time. On Arch, pipx isolated venvs can't see system Cython.

# create a manual venv instead of pipx
$ python -m venv ~/.local/share/flex-venv
$ source ~/.local/share/flex-venv/bin/activate
$ pip install setuptools wheel cython numpy
$ pip install --no-build-isolation hdbscan
$ pip install getflex

model download fails

The ONNX model (~87 MB) is downloaded from getflex.dev (with GitHub Releases as fallback). If the download fails or the file is corrupt:

# delete and re-download
$ rm -rf ~/.flex/models/
$ flex init

# flex init verifies checksums — corrupt files are deleted and retried

flex init in Docker / CI

All embedding runs locally. No interactive prompts. Works in non-TTY contexts automatically.

MCP server not connected

After flex init --module claude-code, restart Claude Code or open a new session. Then:

# verify MCP is registered — in Claude Code, type:
/mcp

# you should see "flex" with the flex_search tool listed

MCP connection drops mid-session

If Claude stops recognizing the flex tool during a session, the MCP connection may have dropped. Type /mcp in Claude Code to reconnect without restarting the session.

worker not running

The worker is a system service that indexes new sessions in real time.

# Linux (systemd)
$ systemctl --user status flex-worker    # check status
$ systemctl --user restart flex-worker   # restart
$ journalctl --user -u flex-worker -f    # tail logs

# macOS (launchd)
$ launchctl list | grep dev.getflex      # check status

stale data / missing sessions

flex sync is the recovery command. It installs missing views, presets, stubs, and restores systemd services and MCP wiring if absent.

$ flex sync              # views + presets + services
$ flex sync --full       # also re-runs enrichment