English | 中文

Memex

A session history management system for Claude Code. Never lose your conversations again.

Why Memex?

Claude Code's local conversation data expires after 30 days, causing:

• Loss of important technical decision records

• Difficulty searching historical conversations

• Knowledge cannot be accumulated and reused

Memex solves these problems:

• ✅ Automatic backup of all Claude Code sessions

• ✅ Powerful full-text and semantic search

• ✅ MCP protocol support for searching history directly in Claude

• ✅ Web UI for browsing and managing sessions

Features

Data Collection & Backup

• Automatically scans all sessions under ~/.claude/projects/

• Parses JSONL format conversation content

• Stores in SQLite database

• Supports daily incremental backups

Search Capabilities

• Full-text Search: Fast keyword search based on SQLite FTS5

• Semantic Search: Semantic understanding using Ollama + LanceDB

• Hybrid Retrieval: RRF fusion ranking combining keyword and semantic relevance

• Advanced Filtering: Filter by project, time range, Session ID prefix

MCP Integration

Search historical conversations in Claude Code via MCP protocol:

• search_history - Search historical conversations

• get_session - Get session details (supports pagination and in-session search)

• get_recent_sessions - Get recent sessions

• list_projects - List all projects

Web UI

• Cyberpunk-style interface

• Project list and session browsing

• Quick lookup by Session ID prefix

• Supports full-text/semantic/hybrid search

Tech Stack

• Backend: NestJS (DDD architecture)

• Database: SQLite + FTS5 (full-text search)

• Vector Store: LanceDB

• LLM Runtime: Ollama (local)

• Frontend: Vue 3

• Communication: HTTP + JSON-RPC (MCP)

Quick Start (Docker)

The fastest way to get started - no Node.js or build tools required.

Then visit http://localhost:3000

What's included

• Web UI for browsing sessions

• Full-text search (FTS5)

• MCP endpoint at /api/mcp

• Auto-import from ~/.claude/projects/

Optional: Enable Semantic Search

For semantic search and RAG, you need Ollama running on your host:

Installation (From Source)

If you want to build from source or do development, follow these steps.

Prerequisites

1. Node.js >= 18

2. pnpm (recommended)

3. Ollama (required for semantic search and RAG)

Ollama Models

Note: Without Ollama models, full-text search still works. Semantic search and RAG require the models above.

Install Project

Configuration

Copy and edit the configuration file:

Main configuration options:

Running

Development Mode

Production Mode

MCP Configuration

Memex provides MCP service via HTTP protocol with simple configuration.

Option 1: mcp-router Configuration (Recommended)

Edit mcp-router configuration file:

Option 2: Claude Code Direct Configuration

Add to Claude Code's MCP settings:

Verify MCP Connection

After starting Claude Code, verify with:

If MCP is configured correctly, Claude will call the memex/search_history tool.

API Endpoints

Project Management

• GET /api/projects - Get all projects list

• GET /api/projects/:id - Get project details (including session list)

Session Management

• GET /api/sessions/:id - Get session details (full conversation content)

• GET /api/sessions/search?idPrefix=xxx - Search by Session ID prefix

Search

• GET /api/search?q=xxx&projectId=yyy - Full-text search

  • Query parameters:

    • q: Search keywords

    • projectId: Project filter (optional)

    • startDate: Start date (optional)

    • endDate: End date (optional)

    • limit: Result limit, default 20

• GET /api/search/semantic?q=xxx&mode=hybrid - Semantic search

  • Query parameters:

    • q: Search content

    • mode: Search mode

      • semantic: Pure semantic search

      • hybrid: Hybrid search (keyword + semantic)

    • projectId: Project filter (optional)

    • limit: Result limit, default 10

RAG Q&A

• POST /api/ask - Ask questions based on history

  • Request body:

    • question: The question to ask

    • cwd: Current working directory for project filtering (optional)

    • contextWindow: Context messages before/after, default 3 (optional)

    • maxSources: Max source references, default 5 (optional)

  • Response: { answer, sources, model, tokensUsed }

MCP

• POST /api/mcp - MCP JSON-RPC endpoint

• GET /api/mcp/info - Get MCP tools information

Usage Examples

Web UI

Visit http://localhost:10013 to use the web interface.

Main features:

• Browse all projects and sessions

• Quick lookup by Session ID prefix

• Full-text search conversation content

• Semantic search related discussions

• Filter by project and time

Command Line Search

MCP Usage

Ask directly in Claude Code:

Data Directory Structure

FAQ

Q: How to trigger initial data import?

A: The service automatically scans ~/.claude/projects/ and imports all sessions on startup. You can also trigger manually via API:

Q: Semantic search not working?

A: Ensure:

1. Ollama service is running: ollama serve

2. Model is downloaded: ollama pull bge-m3

3. OLLAMA_API is configured correctly in .env

Q: How to clear and rebuild index?

A: Delete the data directory and restart the service:

Q: MCP connection failed?

A: Check:

1. Memex service is running at http://localhost:10013

2. MCP configuration path is correct

3. Node.js version is >= 18

Development

Project Structure

Running Tests

Roadmap

• Phase 0: Data collection and backup

• Phase 1: SQLite + FTS5 full-text search

• Phase 2: Semantic search (Ollama + LanceDB)

• Phase 3: MCP integration

• Web UI

• Phase 4: RAG Q&A

• Phase 5: Knowledge distillation (Not planned - RAG already covers most use cases)

Possible Future Enhancements

• Session export (Markdown/PDF)

• Bookmark/tagging system

• Claude Hooks integration (near real-time indexing)

License

MIT

Acknowledgments

Thanks to Claude Code for providing such an excellent development experience.