airkjw/claude-mem

Fork 0

Files

T

Alex Newman 723f1f5374 refactor: update plugin installation guide and add MCP server configuration

2025-10-16 15:18:48 -04:00

6.8 KiB

Raw Blame History

Plugin Installation Guide

Claude-mem can be installed as a Claude Code plugin, which provides a streamlined installation experience.

Plugin Structure

The claude-mem plugin includes:

Hooks: Automatic memory capture via SessionStart, UserPromptSubmit, PostToolUse, and Stop hooks
Commands: /claude-mem, /save, and /remember slash commands
MCP Integration: Chroma vector database for semantic memory search

Installation Methods

Option 1: From Git Repository (Recommended)

If the plugin is published to GitHub:

Add the marketplace from GitHub:

/plugin marketplace add thedotmack/claude-mem-marketplace

Install the plugin:

/plugin install claude-mem@marketplace-name

The plugin will automatically:

Configure all hooks in your Claude settings
Set up slash commands
Register plugin components

Note: You still need to install the CLI globally for hooks to work:

npm install -g claude-mem

Option 2: Local Development Installation

If you're testing locally during development:

Create a development marketplace structure:

mkdir dev-marketplace
cd dev-marketplace
mkdir .claude-plugin

Create marketplace manifest (.claude-plugin/marketplace.json):

{
  "name": "dev-marketplace",
  "owner": {
    "name": "Developer"
  },
  "plugins": [
    {
      "name": "claude-mem",
      "source": "./claude-mem-plugin",
      "description": "Persistent memory system for Claude Code"
    }
  ]
}

Create or symlink your plugin directory:

# Symlink to your working directory (recommended)
ln -s /path/to/claude-mem ./claude-mem-plugin

# Or copy the directory
cp -r /path/to/claude-mem ./claude-mem-plugin

Start Claude Code and add your development marketplace:

/plugin marketplace add /absolute/path/to/dev-marketplace

Install your plugin:

/plugin install claude-mem@dev-marketplace

Option 3: Interactive Installation

You can also use the interactive plugin interface:

Open plugin management:
```
/plugin
```
Select "Browse Plugins" to see available plugins with descriptions and installation options
Follow the prompts to install and configure

Option 4: Traditional CLI Installation

You can still use the traditional CLI-based installation:

npm install -g claude-mem
claude-mem install

This method uses an interactive wizard to guide you through setup and works independently of the plugin system.

Verify Installation

After installing the plugin, verify it's working correctly:

Check available commands:
```
/help
```
You should see /claude-mem, /save, and /remember commands listed.
Test plugin features:
```
/claude-mem help
```
This should show all memory system commands and features.
Review plugin details:
```
/plugin
```
Select "Manage Plugins" to see what the plugin provides and its current status.
Check hooks are registered: View your ~/.claude/settings.json to confirm hooks are configured.

Managing the Plugin

Check Plugin Status

/plugin list

Disable Plugin (temporarily)

/plugin disable claude-mem

Enable Plugin

/plugin enable claude-mem

Uninstall Plugin

/plugin uninstall claude-mem

Development Iteration

When making changes to your plugin during development:

Uninstall current version:

/plugin uninstall claude-mem@dev-marketplace

Make your changes to the plugin code

Reinstall to test changes:

/plugin install claude-mem@dev-marketplace

Restart Claude Code if hooks or commands don't update immediately

Tip: When using a symlink in your dev marketplace, changes to commands may be reflected without reinstalling, but hook changes typically require a reinstall.

Plugin Components

Hooks Configuration

The plugin registers these hooks automatically (defined in hooks/hooks.json):

SessionStart: Loads recent session context when Claude Code starts
UserPromptSubmit: Initializes memory session and background worker
PostToolUse: Captures tool observations for memory system
Stop: Finalizes and saves session summary

Commands

The plugin includes these slash commands (in commands/ directory):

/claude-mem help - Show all memory commands and features
/save [message] - Quick save of current conversation overview
/remember [context] - Search your saved memories

MCP Server

The plugin automatically installs and configures the Chroma MCP server for vector-based memory storage.

Troubleshooting

Plugin Not Found

If the plugin isn't found, ensure:

The repository contains .claude-plugin/plugin.json
The plugin is in the correct directory
You've refreshed the plugin marketplace: /plugin marketplace refresh

Hooks Not Running

Check that:

The plugin is enabled: /plugin list
The claude-mem CLI is installed: which claude-mem
Check Claude logs for hook errors

CLI Not Found

If hooks fail with "command not found", install the CLI:

npm install -g claude-mem

The plugin hooks call the claude-mem CLI commands, which must be globally available.

Creating Your Own Marketplace

To distribute claude-mem via a custom marketplace:

Create a marketplace repository with this structure:

my-marketplace/
├── .claude-plugin/
│   └── marketplace.json
└── plugins/
    └── claude-mem/  (symlink or submodule to claude-mem)

Define .claude-plugin/marketplace.json:

{
  "name": "thedotmack",
  "owner": {
    "name": "Alex Newman"
  },
  "plugins": [
    {
      "name": "claude-mem",
      "source": "./plugins/claude-mem",
      "description": "Persistent memory system for Claude Code"
    }
  ]
}

Publish to GitHub and users can add it with:

/plugin marketplace add username/repo-name

Users install the plugin:

/plugin install claude-mem@marketplace-name

Benefits of Plugin Installation

✅ One-command install: No complex setup scripts ✅ Easy management: Enable/disable without modifying settings ✅ Version control: Update plugins with /plugin update ✅ Team sharing: Distribute via marketplace ✅ Standard format: Follows Claude Code best practices

6.8 KiB Raw Blame History