AI Agent Integration

Memex is designed for AI coding assistants. The CLI is the recommended interface.

Claude Code

Permission Setup

Add to .claude/settings.local.json:

{
  "permissions": {
    "allow": ["Bash(mx:*)"]
  }
}

This grants Claude Code permission to run any mx command without prompting.

Session Hooks

For automatic context injection, use hooks:

{
  "hooks": {
    "SessionStart": [{ "hooks": [{ "type": "command", "command": "mx session-context" }] }]
  }
}

Write the hook into .claude/settings.json:

mx session-context --install

The mx session-context command:

• Injects project-relevant KB context at session start
• Provides a concise workflow reminder plus related entries

Claude Code Plugin (Optional)

This repo ships a Claude Code plugin manifest in .claude-plugin/. From the repo root, add the local marketplace and install the plugin:

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

Restart Claude Code after installing or updating the plugin.

Workflow Pattern

# Before implementing: search KB for existing patterns
mx search "authentication patterns"

# During work: add discoveries for future sessions
mx add --title="OAuth2 Setup" --tags="auth,patterns" --category=patterns \
  --content="..."

JSON Output vs JSON Errors (Important for Agents)

Many mx subcommands support --json, which controls success output formatting. Errors are still human-readable text by default.

For machine-parseable errors with stable error codes, use the global flag:

# JSON error on stderr (with {"error": "...", "code": 1234, "message": "..."}):
mx --json-errors get nonexistent.md

# Success JSON on stdout, JSON errors on stderr:
mx --json-errors add --title="Entry" --tags="a,b" --content="..." --json

Notes:

• --json-errors is global, so it is best placed before the subcommand (the CLI also accepts it later and normalizes it).
• --json-errors implies a quieter "machine mode" (warnings are suppressed) to keep stderr parseable.

Codex CLI

Codex can use memex via shell commands in AGENTS.md:

## Knowledge Base

Search organizational knowledge before implementing:
- `mx search "query"` - Find existing patterns
- `mx get path/entry.md` - Read specific entry
- `mx add --title="..." --tags="..." --category=... --content="..."` - Add discoveries

Codex Skills (Optional)

This repo includes a Memex skill at skills/memex-kb-usage/. Codex loads skills from $CODEX_HOME/skills (defaults to ~/.codex/skills). Copy or symlink the skill into that directory and restart Codex.

Example:

mkdir -p ~/.codex/skills
cp -r skills/memex-kb-usage ~/.codex/skills/

Other AI Agents

Any agent with shell access can use the mx CLI.

Common Patterns

# Check for relevant knowledge before implementing
mx search "deployment strategies"

# Add discoveries for future sessions
mx add --title="API Rate Limiting" \
  --tags="api,patterns" \
  --category=patterns \
  --content="..."

# View recent project KB updates
mx whats-new --scope=project --days=7

# Quick status check
mx info

Search Strategy

1. Before implementing: Search for existing patterns
2. When stuck: Search for troubleshooting guides
3. After solving: Add solution to KB

When to Search KB

• Looking for organizational patterns or guides
• Before implementing something that might exist
• Understanding infrastructure or deployment
• Troubleshooting known issues

When to Contribute

• Discovered reusable pattern or solution
• Troubleshooting steps worth preserving
• Infrastructure or deployment knowledge
• Project-specific conventions

Project Configuration

Configure project-specific KB settings in .kbconfig:

# In your project directory
cat <<'EOF' > .kbconfig
kb_path: ./kb
primary: design
boost_paths:
  - design/*
default_tags:
  - memex
EOF

This .kbconfig file:

• Points mx at the project KB (kb_path)
• Routes new entries to projects/<name> by default (primary)
• Boosts project entries in search results (boost_paths)
• Suggests project-specific tags (default_tags)

Best Practices

1. Search before creating - Avoid duplicate entries
2. Tag consistently - Use mx tags to see existing tags
3. Link related entries - Use [[path/to/entry]] syntax
4. Keep entries focused - One topic per entry
5. Update, don't duplicate - Append to existing entries

See Also

• CLI Reference
• Entry Format