Memex

CLI-first knowledge base with hybrid search, typed relations, and static site publishing. Stores Markdown with YAML frontmatter across project and user scopes. Built for humans and AI coding agents.

Features

• Hybrid search — BM25 keyword + semantic embeddings, merged with Reciprocal Rank Fusion
• Typed relations — explicit directed links in frontmatter with CLI helpers and linting
• Graph view — wikilinks, relations, and semantic links queryable via CLI and published sites
• Dual scopes — project KB (./kb/) and user KB (~/.memex/kb/) with shared search
• Publishing — static HTML with embedded search, tag pages, and graph visualization
• Agent-friendly — mx prime, mx schema, mx batch for low-token AI workflows

Installation

# With uv (recommended)
uv tool install memex-kb

# With pip
pip install memex-kb

# Verify
mx --version

Semantic search is included. First run downloads the embedding model (~90MB). Requires Python 3.11+.

Quick Start

mx init                                    # Create kb/ and .kbconfig
mx add --title="Setup" --tags="docs" \
       --category=guides --content="..."   # Add an entry
mx search "setup"                          # Search
mx get guides/setup.md                     # Read an entry

Note: mx add requires --category unless primary is set in .kbconfig.

Entries

Markdown files with YAML frontmatter:

---
title: API Guide
tags: [api, docs]
description: Endpoints and auth
---

# API Guide

See [[reference/auth]] for auth details.

Typed relations go in frontmatter:

relations:
  - path: reference/cli.md
    type: documents
  - path: guides/installation.md
    type: depends_on

Types: depends_on, implements, extends, documents, references, blocks, related.

CLI Overview

# Search and browse
mx search "query"                          # Hybrid search (default)
mx search "query" --mode=semantic          # Semantic only
mx search "query" --include-neighbors      # Include linked entries
mx get path/entry.md                       # Read entry
mx list --tags=docs                        # List by tag
mx tree                                    # Directory structure
mx whats-new --days=7                      # Recent changes

# Create and edit
mx add --title="..." --tags="..." --content="..."
mx append "Title" --content="..."          # Append or create
mx patch path.md --find="old" --replace="new"
mx ingest notes.md --directory=guides      # Import file

# Relations
mx relations path/entry.md --depth=2       # Query graph
mx relations-add path.md --relation "other.md=documents"
mx relations-lint --strict                 # Check consistency

# Maintenance
mx health                                  # Audit KB
mx hubs                                    # Find high-connectivity entries
mx suggest-links path.md                   # Semantic link suggestions
mx reindex                                 # Rebuild indices
mx eval                                    # Search quality metrics

# Agent tools
mx prime                                   # Session context for agents
mx schema --compact                        # CLI schema (for LLMs)
mx batch < commands.txt                    # Batch operations

Full reference at kb/reference/cli.md.

Publishing

mx publish -o _site                        # Generate static site
mx publish --base-url /my-kb               # Custom base path
mx publish --setup-github-actions          # Add GH Pages workflow

AI Integration

Claude Code

Add to .claude/settings.json:

{
  "permissions": { "allow": ["Bash(mx:*)"] },
  "hooks": {
    "SessionStart": [{ "hooks": [{ "type": "command", "command": "mx session-context" }] }]
  }
}

Or install automatically:

mx session-context --install

Plugin

/plugin marketplace add ./.claude-plugin/marketplace.json
/plugin install memex@memex

Agent Commands

mx prime              # Context for session start
mx schema --compact   # CLI schema (minimal tokens)
mx batch              # Multiple commands, one invocation

Configuration

.kbconfig at project root:

kb_path: ./kb
primary: guides              # Default category for mx add
boost_paths:
  - guides/*                 # Search ranking boost
default_tags:
  - myproject
publish_base_url: /my-kb

Environment variables:

Variable	Description
MEMEX_USER_KB_ROOT	Override user KB location
MEMEX_INDEX_ROOT	Override index directory
MEMEX_QUIET	Suppress warnings

CLI flags:

• --json-errors — errors as JSON with error codes
• -q, --quiet — suppress warnings

Index Storage

Indices live at {kb}/.indices/:

• whoosh/ — BM25 keyword index
• chroma/ — semantic vectors
• embedding_cache.sqlite — cached embeddings

Development

git clone https://github.com/chriskd/memex.git
cd memex
uv sync --dev
uv run pytest

See CONTRIBUTING.md for guidelines.

License

MIT