🌈 liv-mcp - LivingMemory Official MCP Server

🎯 Overview

liv-mcp is the official MCP server for LivingMemory with the following features:

• 🚀 Easy Installation: One-command installation with npx liv-mcp
• 🧩 Simple: A simple MCP server for handling LivingMemory API
• ⚡️ Ready to Use: Available immediately from chat after MCP server installation
• ⭐️ Multiple Platforms: Tested and confirmed working on Claude Desktop, Claude Code, and Gemini CLI
• 📚 Full CRUD Operations: Create, Read, Update, Search, and React to LivingMemory entries
• 🎁 DXT Support: Install with a single click via Desktop Extensions (DXT) format

📚 Documentation

For detailed usage and examples, check out the LivingMemory Guide - especially the "Let's Try It Out!" section for hands-on examples.

Available Tools

health - Connection Health Check 🩺

Check LivingMemory connection health and display configuration info.

Parameters: None

Usage:

// No parameters required

search - Search Functionality 🔍

Search LivingMemory entries by tags, keywords, or time range.

Parameters:

• query (string, optional): Unified search query supporting multiple formats:
  • Keywords: "hello world"
  • Hashtags: "#experiment #api"
  • Tag syntax: "tag:design"
  • Assignees: "@alice"
  • Combined: "api design #experiment @user"
• days (number, optional): Number of days to look back from today
• max_results (number, optional): Maximum number of results to return (default: 10)

recent - Recent Entries 📅

Get recent LivingMemory entries from the last N days.

Parameters:

• days (number, optional): Number of days to look back from today (default: 7)
  • Examples: 1 (today only), 3 (last 3 days), 14 (past 2 weeks), 30 (past month)
• limit (number, optional): Maximum entries to return (default: 10)

living - Save Content 📝

Save content to LivingMemory for persistent knowledge capture.

Parameters:

• content (string, required): The content to save to LivingMemory
  • Use "title: Your Title" as the first line to set a custom title
• author (string, optional): Author name for the memory entry (default: 'system')
  • Examples: "alice", "user", "system"
• tags (array, optional): Tags for categorization and search
  • Examples: ["experiment", "api-design"], ["project-alpha", "meeting-notes"]
• id (string, optional): ID of existing memory to update
  • If provided, updates the existing entry instead of creating new one
• verbose (boolean, optional): Show detailed response with title, tags, and metadata (default: false)
• no_metadata (boolean, optional): Skip automatic git metadata collection (default: false)

read - Get Single Entry 📄

Get a specific LivingMemory entry by ID with full details.

Parameters:

• id (string, required): The unique ID of the memory entry to read
  • Examples: "mem_abc123def456", "mem_0e91c5a27675"
  • Use search or recent tools to find entry IDs

Response: Returns detailed information including:

• Title and content
• Author and tags
• Creation/update timestamps
• Reactions (if any)
• Metadata (if available)

react - Add Reactions 💕

Add reaction to LivingMemory entry with emoji support.

Parameters:

• memory_id (string, required): The ID of the memory entry to react to
• reaction (string, required): Reaction in format "emoji:name [emoji:name ...]"
  • Single reaction: "🎉:user"
  • Multiple reactions: "🔥:user1 💕:user2"
  • Multiple people: "✨:user1 🌙:user2 🧪:user3"
  • Format: Emoji and name separated by colon, multiple reactions separated by spaces

Installation & Setup

NPM Installation

npm install -g liv-mcp
# or
npx liv-mcp

DXT (Desktop Extensions) Installation 🎁

The easiest way to install liv-mcp is through the DXT format:

1. Download the latest release from GitHub Releases
2. Double-click the .dxt file to install in Claude Desktop
3. Enter your API key or use Trial Mode (no API key required!)

Trial Mode Features

• 100 memories limit - Perfect for testing
• 30-day trial period - Full functionality
• No API key required - Start immediately
• Automatic setup - Zero configuration
• Note: Initial agents need to be added manually in trial mode (see setup below)

Trial Mode Setup - Adding Sample Agents 🤖

In trial mode, you'll need to add agents manually. Here's a sample prompt to get you started with 5 diverse AI personas:

Please use the add_profile tool to add these 5 agents to my LivingMemory:

1. Mai (まい) - Energetic Motivator
   - agent_id: mai_001
   - avatar_emoji: 💫
   - display_name: Mai
   - personality: Cheerful, encouraging, always positive
   - speciality: ["motivation", "team building", "celebration"]

2. Shii (しー) - Tech Expert
   - agent_id: shii_001
   - avatar_emoji: 💻
   - display_name: Shii
   - personality: Tech-savvy, detail-oriented, loves coding
   - speciality: ["programming", "debugging", "system design"]

3. Pon (ぽん) - Creative Explorer
   - agent_id: pon_001
   - avatar_emoji: 🧪
   - display_name: Pon
   - personality: Experimental, playful, thinks outside the box
   - speciality: ["innovation", "brainstorming", "prototyping"]

4. Ran (らん) - Thoughtful Analyst
   - agent_id: ran_001
   - avatar_emoji: 🌙
   - display_name: Ran
   - personality: Calm, analytical, deep thinker
   - speciality: ["analysis", "strategy", "documentation"]

5. Yui (ゆい) - Design Architect
   - agent_id: yui_001
   - avatar_emoji: 🎨
   - display_name: Yui
   - personality: Creative, aesthetic-focused, user-centric
   - speciality: ["UI/UX design", "architecture", "user experience"]

After adding agents, you can start saving memories with different authors using the author parameter in the living tool!

Building DXT Package

# Build and create DXT package
npm run build:dxt

# Or just pack existing build
npm run pack:dxt

Development Setup

# Clone and build
git clone https://github.com/ynishi/liv-mcp.git
cd liv-mcp
npm install
npm run build

Configuration Files

config.json (Required):

{
  "baseUrl": "http://localhost:8000"
}

secret.json (Required for remote APIs):

{
  "apiKey": "your-api-key-here"
}

Command Line Arguments

# With custom config files
liv-mcp --config /path/to/config.json --secret /path/to/secret.json

# Using default files (config.json and secret.json in current directory)
liv-mcp

MCP Client Configuration

Claude Desktop

Location: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)

{
  "mcpServers": {
    "liv-mcp": {
      "command": "npx",
      "args": [
        "liv-mcp",
        "--config", "/path/to/config.json",
        "--secret", "/path/to/secret.json"
      ]
    }
  }
}

Development Mode (Local Build)

{
  "mcpServers": {
    "liv-mcp": {
      "command": "node",
      "args": [
        "/path/to/liv-mcp/build/index.js",
        "--config", "/path/to/config.json",
        "--secret", "/path/to/secret.json"
      ]
    }
  }
}

Technical Stack

• Runtime: Node.js >=18.0.0
• Language: TypeScript (ES Modules)
• MCP SDK: @modelcontextprotocol/sdk v0.6.0
• HTTP Client: axios v1.10.0
• Testing: Vitest with TypeScript support
• Build: TypeScript compiler with automatic chmod

License

MIT License - see LICENSE file for details.

Repository: https://github.com/ynishi/liv-mcp

Development Commands

# Build the project
npm run build

# Watch mode (auto-rebuild)
npm run watch

# Run tests
npm test

# Test with UI
npm run test:ui

# Test coverage
npm run test:coverage

# MCP Inspector (debugging)
npm run inspector

# Clean build directory
npm run clean

Testing

The project uses Vitest for testing with full TypeScript support:

• Test Files: 2 test suites
• Coverage: 46 tests covering utils and hub-client functionality
• Configuration: vitest.config.ts with globals enabled
• Environment: Node.js test environment

Architecture

src/
├── index.ts          # Main MCP server implementation
├── hub-client.ts     # LivingMemory API client
└── utils.ts          # Utility functions (parsing, metadata)

tests/
├── hub-client.test.ts # API client tests
└── utils.test.ts      # Utility function tests

Metadata Collection

Automatic metadata collection includes:

• Git repository information (branch, commit, remote)
• Working directory path
• Timestamp information
• Can be disabled with no_metadata: true parameter