Memex

CLI-first knowledge base for Markdown + YAML frontmatter across project and user scopes, with static publishing and agent-focused workflows.

Start Here

• kb/guides/index.md (published docs landing page)
• kb/guides/quick-start.md (KB quick start)
• kb/guides/ai-integration.md (Claude Code, Codex, and skill-aware harnesses)
• kb/reference/cli.md (full command reference)

Install

# Recommended
uv tool install memex-kb

# Optional semantic search deps
uv tool install 'memex-kb[search]'

# Or pip
pip install memex-kb
pip install 'memex-kb[search]'

# Verify
mx --version

Keyword search is available by default. Semantic search is optional ([search] extra). If dependencies are missing, run mx doctor.

From a repo checkout, prefix with uv run:

uv sync --dev
uv run mx --version

First Run

# Guided check; initialize if missing (non-interactive)
mx onboard --init --yes

# Same check, but only current directory context
mx onboard --init --yes --cwd-only

# Direct project KB initialization
mx init --sample
mx init --path docs/kb --sample

# User KB initialization
mx init --user --sample

Notes:

• mx onboard --init --yes can create a KB when none is configured.
• In onboarding, sample behavior is configurable with --sample/--no-sample.
• When both project and user KBs are active, paths may be scoped (@project/..., @user/...).

Common Commands

# Search (keyword default; semantic optional)
mx search "deployment"
mx search "deployment" --mode=keyword
mx search "deployment" --mode=semantic
mx search "deployment" --scope=project
mx search "deployment" --include-neighbors --neighbor-depth=2

# Create/read/update
mx add --title="Setup" --tags="docs" --category=guides --content="..."
mx quick-add --content="Capture this note"
mx get @project/guides/setup.md
mx replace @project/guides/setup.md --tags="docs,setup"
mx delete @project/guides/setup.md --force

# Multi-KB visibility and context
mx info
mx context show
mx context validate

# Agent session handoffs
mx sessions start --goal "Implement deployment cleanup" --harness codex
mx sessions append --latest --summary "Updated deployment docs" --files README.md
mx sessions append --latest --summary "Linked transcript" --transcript /tmp/session.jsonl
mx sessions finish --latest --summary "Ready for review"
mx sessions recent

# Maintenance
mx health
mx doctor
mx doctor --timestamps
mx doctor --timestamps --fix
mx relations-lint --strict

Publish

# Basic build
mx publish -o _site

# Source selection
mx publish --kb-root ./kb -o _site
mx publish --scope=project -o _site

# Landing page and base URL
mx publish --index guides/index --base-url /my-kb

# Content controls
mx publish --include-drafts --include-archived
mx publish --no-clean

# GitHub Pages workflow
mx publish --setup-github-actions
mx publish --setup-github-actions --dry-run

Agents + Skills

Memex integrates with assistants in two layers:

• mx is the stable interface for any harness with shell access.
• skills/memex-kb/ is the bundled reusable skill for harnesses that support SKILL.md.

# Project-local hooks
mx sessions hook claude --install --path .claude/settings.local.json
mx sessions hook codex --install --path .codex/hooks.json
mx sessions hook claude --install --turns 5

# Claude Code native skill install from a repo checkout
mkdir -p .claude/skills
ln -s "$PWD/skills/memex-kb" .claude/skills/memex-kb

# Codex local skill install from a repo checkout (restart Codex after)
mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
ln -s "$PWD/skills/memex-kb" "${CODEX_HOME:-$HOME/.codex}/skills/memex-kb"

# Installed package: locate the bundled skill first
python3 -c 'from importlib.resources import files; print(files("memex").joinpath("skills", "memex-kb"))'

# Portable helpers for any harness
mx prime
mx session-context
mx sessions hook codex --instructions
mx sessions hook codex --print
mx sessions hook codex --print --turns 5
mx sessions hook claude --print
mx schema --compact
mx batch < commands.txt
mx --json-errors search "query"

Hooks load context at session start. Add --turns N to install a periodic session-log reminder that asks the agent to append only the latest delta, not the whole session.

For the full setup matrix, including Claude permissions, Codex skill conventions, and generic skill installation guidance, see kb/guides/ai-integration.md.

Config

Project config file: .kbconfig at repo root.

# kb_path is canonical; project_kb still appears in some help/output
kb_path: ./kb
primary: inbox
warn_on_implicit_category: true
boost_paths:
  - inbox/*
  - guides/*
default_tags:
  - myproject
publish_base_url: /my-kb
publish_index_entry: guides/index

Environment variables:

Variable	Description
MEMEX_USER_KB_ROOT	Override user KB root (default ~/.memex/kb)
MEMEX_CONTEXT_NO_PARENT	Only consider .kbconfig in current directory
MEMEX_INDEX_ROOT	Override index root
MEMEX_QUIET	Suppress warnings

Useful global flags:

• --json-errors outputs structured errors with error codes.
• -q, --quiet suppresses warnings (same effect as MEMEX_QUIET=1).