mem-box 0.1.1

A personal knowledge base for commands and workflows, accessible via MCP

Memory Box 🧠📦

A personal knowledge base for commands and workflows, designed for people with ADHD or anyone who wants to remember useful commands across projects.

Memory Box is a Model Context Protocol (MCP) server that stores your frequently-used commands in a Neo4j graph database, making them accessible from any AI assistant (Claude Desktop, Cline, etc.) or directly via CLI.

Features

• 🔍 Context-Aware Search: Automatically detects your OS and project type to suggest relevant commands
• 🏷️ Smart Organization: Tag, categorize, and filter commands by OS, project type, and categories
• 🤖 MCP Integration: Use with Claude Desktop or any MCP-compatible AI assistant
• 💻 Powerful CLI: Full command-line interface for quick access
• 📊 Graph Database: Neo4j stores relationships between commands, contexts, and tags
• 📈 Usage Tracking: See which commands you use most frequently

Quick Start

Option 1: Using Dev Container (Recommended)

The easiest way to get started is using the dev container, which automatically sets up Neo4j and all dependencies:

1. Prerequisites:

   • Docker (Docker Engine on Linux, or Docker Desktop on macOS/Windows)
   • VS Code with the Dev Containers extension

2. Open in Dev Container:

   git clone https://github.com/mem-box/mem-box.git
   cd mem-box
   code .
   

   When prompted, click "Reopen in Container" (or use Command Palette: Dev Containers: Reopen in Container)

3. Start using Memory Box: The dev container automatically:

   • Starts Neo4j on port 7687 (credentials: neo4j/devpassword)
   • Installs all Python dependencies
   • Sets up the development environment

   # Add a command
   memory-box add "git log --oneline --graph --all" --desc "Visual git history" --tag git
   
   # Search commands
   memory-box search git
   

Option 2: Manual Setup

If you prefer not to use the dev container:

1. Install Neo4j

You need a Neo4j database running. Using Docker:

docker run \
    --name neo4j \
    -p 7474:7474 -p 7687:7687 \
    -e NEO4J_AUTH=neo4j/devpassword \
    -d neo4j:5-community

The Neo4j browser will be available at http://localhost:7474

Or download from neo4j.com/download

2. Install Memory Box

# Clone the repository
git clone https://github.com/mem-box/mem-box.git
cd mem-box

# Install with uv (recommended)
uv sync

# Or with pip
pip install -e .

3. Configure Environment

cp .env.example .env
# Edit .env with your Neo4j credentials (default: neo4j/devpassword)

4. Start Using!

Via CLI:

# Add a command
memory-box add "git log --oneline --graph --all" --desc "Visual git history" --tag git

# Search commands
memory-box search git

# Get context-aware suggestions
memory-box suggest

MCP Setup

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, or %APPDATA%/Claude/claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "memory-box": {
      "command": "python",
      "args": [
        "-m",
        "memory_box.server"
      ],
      "env": {
        "NEO4J_URI": "bolt://localhost:7687",
        "NEO4J_USER": "neo4j",
        "NEO4J_PASSWORD": "devpassword",
        "NEO4J_DATABASE": "neo4j"
      }
    }
  }
}

On Linux, the config is typically at: ~/.config/Claude/claude_desktop_config.json

After adding this, restart Claude Desktop. You'll see Memory Box tools available in your conversations!

VS Code Extension Setup

Memory Box includes a VS Code extension that automatically captures every command you run in any integrated terminal.

Installation

1. Package the extension:

   cd client/vscode
   npm install
   npm run compile
   npx vsce package
   

2. Install the .vsix file:

   • Open VS Code
   • Go to Extensions view (Cmd+Shift+X / Ctrl+Shift+X)
   • Click the ... menu → "Install from VSIX..."
   • Select memory-box-vscode-0.1.0.vsix

3. Configure settings (optional - uses defaults if not set):

   {
     "memoryBox.neo4jUri": "bolt://localhost:7687",
     "memoryBox.neo4jUser": "neo4j",
     "memoryBox.neo4jPassword": "devpassword",
     "memoryBox.autoCapture": true,
     "memoryBox.captureExitCodeZeroOnly": true
   }
   

How It Works

• Automatic Capture: Every command you run in any VS Code terminal is automatically saved
• Search: Use Cmd+Shift+P → "Memory Box: Search Commands" to find and reuse commands
• Toggle: Use "Memory Box: Toggle Auto-Capture" to temporarily disable/enable

The extension uses VS Code's Shell Integration to capture commands with exit codes, so it only works in VS Code's integrated terminals.

Shell Integration (Bash/Zsh)

For automatic command capture in any terminal (outside of VS Code), use the shell integration scripts.

Easy Installation

Simply run the installer script:

cd /path/to/memory-box
./scripts/install-shell-integration.sh

The installer will:

• Detect your shell (bash/zsh)
• Backup your existing config
• Add Memory Box integration to ~/.bashrc or ~/.zshrc
• Ask if you want to only capture successful commands

Then reload your shell or open a new terminal, and you're done!

Manual Setup (Alternative)

If you prefer manual installation:

Bash - Add to your ~/.bashrc:

# Memory Box - Auto-capture commands
source /path/to/memory-box/scripts/shell/bash-integration.sh

Zsh - Add to your ~/.zshrc:

# Memory Box - Auto-capture commands
source /path/to/memory-box/scripts/shell/zsh-integration.zsh

Optionally configure:

# Only capture successful commands (exit code 0)
export MEMORY_BOX_CAPTURE_SUCCESS_ONLY=1

# Use specific Python executable
export MEMORY_BOX_PYTHON=/path/to/python3

How It Works

• Bash: Uses DEBUG trap and PROMPT_COMMAND to capture commands and exit codes
• Zsh: Uses preexec and precmd hooks for command capture
• Async: Runs in background so it doesn't slow down your prompt
• Smart filtering: Skips empty commands and internal shell operations

After installation, every command you run in your terminal will be automatically saved to Memory Box!

Uninstalling

To remove shell integration, simply delete the Memory Box block from your ~/.bashrc or ~/.zshrc (the installer creates a backup for safety).

CLI Commands

Add Commands

# Basic add
memory-box add "docker ps -a" -d "List all containers"

# With context
memory-box add "pytest -v" -d "Run tests verbosely" \
  --tag python --tag testing \
  --category testing \
  --project python

# Without auto-context detection
memory-box add "ls -la" -d "List all files" --no-auto-context

Search Commands

# Text search
memory-box search docker

# Filter by OS
memory-box search --os linux

# Filter by project type
memory-box search --project python

# Filter by category
memory-box search --category git

# Filter by tags (all must match)
memory-box search --tag git --tag branch

# Use current context
memory-box search --current

# Limit results
memory-box search docker --limit 5

Other Commands

# Get specific command
memory-box get <command-id>

# Delete command
memory-box delete <command-id>

# List all tags
memory-box tags

# List all categories
memory-box categories

# Show current context
memory-box context

# Get suggestions for current context
memory-box suggest

MCP Tools

When using Memory Box via MCP, you have access to these tools:

• add_command: Add a new command to your memory box
• search_commands: Search for commands with various filters
• get_command_by_id: Retrieve a specific command (increments use count)
• delete_command: Remove a command
• list_tags: See all available tags
• list_categories: See all categories
• get_context_suggestions: Get commands for your current OS/project

Example Workflow

# You're working on a Python project and forgot the uvicorn command
memory-box search uvicorn --current

# Add a new command you just learned
memory-box add "ruff check --fix ." \
  -d "Auto-fix linting issues with Ruff" \
  --tag python --tag linting \
  --category python

# Later, in a different project
memory-box suggest  # Shows relevant commands for current context

Project Structure

memory-box/
├── memory_box/
│   ├── __init__.py
│   ├── cli.py           # Typer-based CLI
│   ├── config.py        # Configuration management
│   ├── context.py       # OS/project detection
│   ├── database.py      # Neo4j client
│   ├── models.py        # Pydantic models
│   └── server.py        # FastMCP server
├── pyproject.toml
├── .env.example
└── README.md

Development

Setup

# Clone and enter the repository
git clone https://github.com/mem-box/mem-box.git
cd mem-box

# Start Neo4j database
docker-compose -f .devcontainer/docker-compose.yml up -d neo4j

# Install in development mode with dev dependencies
pip install -e ".[dev]"

# Copy environment configuration
cp .env.example .env

Testing

# Run all tests (unit + integration)
pytest

# Run only unit tests
pytest tests/unit

# Run only integration tests (requires Neo4j running)
pytest tests/integration

# Run with coverage
pytest --cov=memory_box --cov-report=html

Code Quality

# Format code
ruff format memory_box/

# Lint
ruff check memory_box/

# Type check
mypy memory_box/

Docker Compose

The project includes a docker-compose.yml for development:

services:
  neo4j:
    image: neo4j:5-community
    ports:
      - "7474:7474"  # Browser UI
      - "7687:7687"  # Bolt protocol
    environment:
      - NEO4J_AUTH=neo4j/devpassword
    volumes:
      - neo4j-data:/data

Access Neo4j Browser at http://localhost:7474 (user: neo4j, password: devpassword)

Why Memory Box?

If you have ADHD or just work with lots of different tools, you know the struggle:

• "What was that docker command again?"
• "How do I create a git branch?"
• "What's the syntax for pytest fixtures?"

Instead of:

• Searching Stack Overflow for the 100th time
• Digging through old Slack messages
• Looking at random notepad files

Now you can:

• Save commands once with context
• Search them instantly from anywhere
• Let AI assistants access your personal command library
• Get smart suggestions based on what you're working on

License

MIT

Contributing

Issues and pull requests welcome!