Memex MCP

🚀 MEMEX

MEMEX is a Model Context Protocol (MCP) server that combines "MEM"ory and ind"EX" to manage your knowledge base of guides and contexts, inspired by Vannevar Bush's visionary Memex.

🚀 Quick Start

make install                    # Install dependencies
ollama pull nomic-embed-text   # Setup Ollama for semantic search
make build                      # Build binary
./memex server                  # Run server

Complete setup instructions: USAGE.md

✨ Features

• 📚 Dual Knowledge Base: Manage both technical guides and reusable contexts
  • Guides: Step-by-step implementation instructions
  • Contexts: Personas, conventions, and prompts for AI interactions
• ✍️ Write Tools: Create and update guides/contexts directly from Claude
• 🔍 Search Tools: Retrieve guides and contexts with semantic search
• 🗑️ Delete Tools: Clean up obsolete content
• 📋 List Tools: Browse all available guides and contexts
• 🔍 Vector Search: Semantic search powered by Ollama embeddings
• 🚀 Claude AI Integration: Compatible with Claude 3.7+ via MCP protocol
• 📁 Flexible Storage: Use custom knowledge base paths, shareable across projects

📦 Installation

Download Latest Release

curl -L https://github.com/jacquesbh/memex-mcp/releases/latest/download/memex -o memex
chmod +x memex
./memex --version

Self-Update

Once installed, keep MEMEX up-to-date:

./memex self-update

📚 Documentation

• USAGE.md (complete guide)
• AGENTS.md (for AI agents)

🔧 Technical Details

Requirements

• PHP 8.3+
• Composer
• Ollama with nomic-embed-text model (for semantic search) - Install Ollama
• Node.js 20+ (for MCP Inspector integration tests)
• Built with Symfony MCP SDK (official Symfony AI SDK)

Supported Operating Systems

• macOS ✅
• Linux ✅
• Windows ❌ (not supported)

Default knowledge base location: ~/.memex/knowledge-base

Configuration

Knowledge Base Path

Configure your knowledge base location in three ways (priority: CLI > Local config > Global config > Default):

1. CLI Flag: ./memex server --kb=/path/to/kb
2. Local Config: ./memex.json (project-specific)
3. Global Config: ~/.memex/memex.json (user-wide)

Config file format:

{
  "knowledgeBase": "/absolute/path/to/kb"
}

Default: ~/.memex/knowledge-base (if no config provided)

Claude Desktop

{
  "mcpServers": {
    "memex": {
      "command": "/absolute/path/to/memex-mcp/memex",
      "args": ["server"]
    }
  }
}

Custom KB: Add "--kb=/path" to args array (optional if using config file).

All configuration options (OpenCode, custom KB, etc.): USAGE.md

MCP Tools

Guides: get_guide, list_guides, write_guide, delete_guide Contexts: get_context, list_contexts, write_context, delete_context

Knowledge Base Structure

knowledge-base/
├── guides/      # Technical how-to docs
├── contexts/    # AI personas/prompts
└── .vectors/    # SQLite database with embeddings

Files use Markdown with YAML frontmatter. Details: USAGE.md

Building from Source

make build

This creates a standalone ./memex binary with all dependencies included.

Manual build:

symfony composer install
vendor/jolicode/castor/bin/castor repack --app-name=memex --logo-file=.castor.logo.php
mv memex.linux.phar memex
chmod +x memex

Verification:

./memex server
./memex stats

Distribution: Copy memex binary. Requires PHP 8.3+ and Ollama.

Architecture

Built with PHP 8.3+ and Symfony MCP SDK, MEMEX uses:

• Services: Guide/Context management, Markdown→JSON compilation, semantic search (Ollama embeddings)
• Tools: 8 MCP tools (get, list, write, delete for guides/contexts)
• CLI: Castor framework, compiled to PHAR binary
• Security: Input validation, path traversal protection, 1MB content limit

Testing

make test          # PHPUnit
make test-mcp      # MCP integration tests (requires Node.js)

See AGENTS.md for CI/CD details.

📄 License

License: MIT - Use freely in any project.

Created by Jacques Bodin-Hullin @ MonsieurBiz with OpenCode, a bit of AI, and a lot of time mastering AI