memex

Memex

A context-aware documentation system for Claude Code. When you ask a question, Memex automatically injects relevant documentation into the conversation based on keywords in your prompt.

Named after Vannevar Bush's 1945 concept of a "memory extender" - a device that stores and retrieves knowledge through associative trails.

What It Does

Memex uses Claude Code hooks to:

1. Auto-inject documentation - When your prompt contains keywords like "database", "api", or "deploy", the matching docs get loaded into context automatically
2. Section-level loading - Load specific sections via anchors (DATABASE.md#schema) instead of entire files
3. Token budget awareness - Stops loading docs when approaching context limits (~10k tokens)
4. Session deduplication - Tracks loaded docs per session to avoid re-injecting the same content
5. Track session state - Shows git status and available docs when you start a session
6. Validate docs - Warns when files exceed 800 lines or sections exceed 150 lines
7. Archive working notes - Cleans up temporary working documents at session end
8. Auto-update - Checks for memex updates on session start and installs them automatically
9. Migrate existing docs - Discovers, deduplicates, and organizes documentation during install

Installation

Memex ships two ways. Both use the same hooks — pick whichever fits your workflow.

Option A: Plugin (recommended)

Install from a marketplace and let Claude Code manage updates:

/plugin marketplace add <your-marketplace>
/plugin install memex

Then scaffold the docs structure in your project once:

/memex-init

The plugin registers the hooks automatically (no edits to your project's settings.json), and /plugin update memex handles upgrades.

Option B: Installer script

Copies the hooks into your project's .claude/ and self-updates on session start:

# Clone the repo
git clone https://github.com/johnpsasser/memex.git

# Run the installer from your project root
cd your-project
/path/to/memex/install.sh

Installer Options

Option	Description
-f, --force	Skip confirmation prompts
-w, --worktree PATH	Specify git worktree path for docs/
--no-migration	Skip automatic documentation migration

What the Installer Does

1. Creates .claude/hooks/ with all hook scripts
2. Creates .claude/settings.json with hook configuration
3. Creates template documentation files in docs/
4. Sets up docs/working/ for temporary notes
5. Migrates existing docs - discovers .md files, deduplicates by content hash, archives originals to docs/archive/
6. Enables auto-updates - stores memex source path for automatic updates on session start

Template Variables

Templates use variable substitution during installation:

Variable	Replaced With
{{PROJECT_NAME}}	Directory name of the project
{{DATE}}	Installation date (YYYY-MM-DD)

Hooks no longer need a {{PROJECT_ROOT}} substitution — they resolve the project root at runtime via $CLAUDE_PROJECT_DIR, so the same scripts work whether installed by the script or loaded as a plugin.

Backup Behavior

When installing over existing files:

File	Behavior
CLAUDE.md	Appends memex section (idempotent, won't duplicate)
GLOSSARY.md	Backs up to GLOSSARY.md.old, installs fresh template
CONTRIBUTING.md	Backs up to CONTRIBUTING.md.old, installs fresh template
Hook scripts	Always overwritten with latest version
settings.json	Merged (memex hooks added, other settings preserved)

How It Works

The system has four hooks that run at different points:

Hook	When	What It Does
session-start.sh	Session begins	Shows git info, lists available docs (read-only; never pulls or auto-updates)
context-enricher.sh	You submit a prompt	Extracts search terms, lexically searches your docs, injects the densest matching sections
validate-docs.sh	After editing docs/*.md	Reminds to update GLOSSARY.md (advisory, never blocks)
session-end.sh	Session ends	Archives docs/working/ — opt-in via MEMEX_ARCHIVE_WORKING=TRUE

The context-enricher hook is the key piece. It extracts terms from your prompt, searches your docs with ripgrep (grep fallback), ranks the densest matches, and injects the relevant sections as additionalContext:

<auto-context>
<!-- Memex auto-retrieved the densest matching excerpts from this repo (read-only, lexical). -->
<!-- docs/core/DATABASE.md : lines 1-24 -->
...section content...
</auto-context>