memex Quickstart

Three commands to install. Two to verify. Pick your OS, paste, done.

1 · Install

macOS

brew install python@3.12 pipx
pipx ensurepath
pipx install https://github.com/queflyhq/memex/releases/latest/download/memex-1.0.3-py3-none-any.whl

Windows (PowerShell)

winget install Python.Python.3.12
winget install Microsoft.VCRedist.2015+.x64
python -m pip install --user pipx
python -m pipx ensurepath
# close + reopen PowerShell
pipx install https://github.com/queflyhq/memex/releases/latest/download/memex-1.0.3-py3-none-any.whl

Windows note: the VC++ Redistributable is required by onnxruntime (memex’s embedding backend). Without it, the daemon refuses to start. The winget line above installs it.

Linux

sudo apt install python3 python3-pip pipx     # or: dnf install python3 python3-pip pipx
pipx install https://github.com/queflyhq/memex/releases/latest/download/memex-1.0.3-py3-none-any.whl

2 · First-run wizard

memex init

memex init is a three-step interactive wizard. It will:

1. Detect your AI editors (Claude Code, Cursor, Windsurf, Cline) and offer to wire memex into each one’s MCP config. Claude Code also gets all 9 lifecycle hooks wired so memex captures every prompt, tool call, and session.
2. Install the always-on service so memex starts on login — launchd on macOS, Task Scheduler on Windows, systemd --user on Linux.
3. Seed memex from a repo (optional). Point at any git repo and memex extracts decisions from commit history, ADRs, README, manifests. Solves the day-1 empty-graph problem.

Each step is skippable with --skip-hooks, --skip-service, or by pressing N at the prompt.

3 · Connect to Claude Code (or verify it auto-connected)

memex init auto-wires Claude Code if it’s installed. If you skipped that step, or you installed Claude Code after memex, run:

memex hooks-install --apply

This merges the memex hook block into ~/.claude/settings.json (atomic — your other hooks are untouched). Nine lifecycle events get wired so memex sees everything Claude Code does:

The memex MCP server (memex serve) is also wired into ~/.claude.json so the AI can call mcp__memex__recall, mcp__memex__add_node, etc. directly. Hooks fire on every event regardless; MCP tools are how the AI talks back.

Verify the hooks are wired:

memex doctor

The “Claude Code hooks” line should say wired: PostToolUse, PreToolUse, SessionStart, Stop, UserPromptSubmit, ... — all 9 names listed.

Cursor / Windsurf / Cline

These editors don’t have lifecycle hooks. memex init still wires the MCP server into their config, and also drops a memex-rules.md file at the editor’s convention path that tells the AI to call mcp__memex__* aggressively. The behavior approximates Claude Code’s auto-capture but depends on the AI choosing to follow the rules.

Locations:

• Cursor — ~/.cursor/rules/memex.mdc
• Windsurf — ~/.codeium/windsurf/memories/memex_global_rules.md
• Cline — alongside the Cline MCP config in VS Code’s globalStorage

4 · Open the UI

http://127.0.0.1:7777

You’ll land on the Home dashboard. Seven sections in the sidebar:

• Home — today’s activity, project health, AFK toggle, service + team-sync status, token savings
• Memory — recall + browse concepts (decisions, facts, constraints, tasks, people, projects)
• Code — sources / files / symbols / cross-repo same_as links / dead-code candidates
• Work — Jira-style task Kanban + safety rules + recent denials + AFK mode
• Skills — installable validation contracts the AI self-attests against
• System — events, maintenance triggers, SLO board, doctor, export
• Settings — service install, team-mode setup, AI editor hooks, secrets, codebases

5 · Install the safety baseline

memex install rules:safety-baseline

Ships 15 production-grade rules that block the most common ways an AI can wreck a developer’s day: force-push to main, recursive deletes of / or ~, secrets in committed files, DROP TABLE without WHERE, kubectl delete --context prod, terraform apply -auto-approve on prod, npm publish without confirmation, and more. You can disable any rule with one click in Work → Rules.

6 · Try a recall

In the UI, click the Recall box on Home and ask:

what did we decide about auth?

Or from the CLI:

memex recall "auth flow"

Either returns the top semantically-relevant concepts — decisions, code symbols, facts — across every repo and session memex has indexed. Default latency is ~700ms; opt into the cross-encoder reranker via --rerank (slower, marginal precision gain).

7 · Connect a team repo (optional)

To share durable knowledge with teammates, point memex at a shared git repo:

memex team init ~/code/team-memex
cd ~/code/team-memex
git remote add origin git@github.com:your-org/team-memex.git
git push -u origin main

# Each teammate clones + adds to their environment:
git clone git@github.com:your-org/team-memex.git ~/code/team-memex
export MEMEX_TEAM_REPO=~/code/team-memex

The scheduler auto-syncs every 10 minutes; force with memex team push / memex team pull. Only durable knowledge syncs (decisions, facts, projects, tasks). Code symbols, episodic events, and vectors stay local.

8 · Verify

memex stats

Should show concept counts, vector count, embedding model, data directory. If the embedding tier is unavailable, the daemon refuses to start — fix with pip install --force-reinstall onnxruntime==1.19.2 fastembed and restart the service via memex service install.

What memex captures

• Every Claude Code event — UserPromptSubmit, PreToolUse, PostToolUse, SessionStart, Stop, SessionEnd, SubagentStop, PreCompact, Notification (9 of 9 lifecycle hooks)
• Voluntary AI calls in Cursor / Windsurf / Cline — those editors lack hooks, but memex drops a rules file telling the AI to call mcp__memex__* aggressively
• TodoWrite items — automatically synced as tasks
• File edits — Edit/Write/MultiEdit calls become touches edges from the active task to the modified file (change provenance)
• Manual additions — memex add from CLI, “Tell memex something” form in the UI

What’s next

• Editors → Claude Code — wire-level hooks reference
• Concepts — types, kinds, edges, decay
• Skills — write your own validation bundles
• API — HTTP endpoints (OMP §4 verbs)
• Contributing — repo layout, dev install

Built on the Open Memory Protocol. v1.0.3 ships now.