Memcord

What is Memcord about?

Memcord is a self‑hosted MCP server that turns Claude conversations into a searchable, organized knowledge base. It keeps every message on your machine, automatically tags, merges, and summarizes chats so you never lose context.

How to use Memcord?

1. Quick installation – run the one‑liner:

   curl -fsSL https://github.com/ukkit/memcord/raw/main/install.sh | bash
   

   This downloads the repo, creates a Python virtual environment with uv, and updates the Claude Desktop configuration.
2. Manual setup (if you prefer):

   git clone https://github.com/ukkit/memcord.git
   cd memcord
   uv venv
   source .venv/bin/activate
   uv pip install -e .
   

   Then point claude_desktop_config.json to the installation path.
3. Add to Claude Desktop / VSCode – insert the following JSON into the mcpServers section of your Claude config:

   {
     "memcord": {
       "command": "uv",
       "args": ["--directory", "</path/to/memcord>", "run", "memcord"],
       "env": { "PYTHONPATH": "</path/to/memcord>/src" }
     }
   }
   

4. Basic command line workflow:

   memcord_name "project_meeting"
   memcord_save "Discussion about the new API design..."
   memcord_save_progress
   memcord_use "project_meeting"
   memcord_search "API design decisions"
   memcord_query "What did we decide about authentication?"
   memcord_merge ["project_meeting","api_notes"] "consolidated_project"
   

   All commands are available as MCP tools; invoke them through Claude Code or Claude Desktop.

Key Features

• Infinite memory – automatic summarization lets Claude recall unlimited conversations.
• Zero‑cloud privacy – 100 % local storage, no external API calls.
• Smart organization – tags, folders, and auto‑merging keep related chats together.
• Powerful search & query – natural‑language search across the entire history.
• Zero mode – temporarily disable saving for sensitive talks.
• Health monitoring – built‑in diagnostics that report storage health.

Use Cases

• Project retrospectives – keep a running knowledge base of design decisions, meeting notes, and code reviews.
• Research assistants – store literature summaries and query them later.
• Customer support logs – archive and search past interactions without exposing data to the cloud.
• Personal knowledge management – maintain a private diary of ideas and reflections.

FAQ

Q: Do I need an internet connection? A: No. All data stays on your machine; the server runs locally.

Q: Can I use Memcord with other AI models? A: Memcord follows the Model Context Protocol, so any compatible client can connect, though the README focuses on Claude Desktop.

Q: How is data secured? A: Files are stored in a local directory you control. You can encrypt the folder or run the server inside a sandbox.

Q: What if the storage health check reports "UNHEALTHY"? A: Update to v2.3.2; the release fixes async/await issues in the diagnostic tools.

Q: How do I upgrade? A: Pull the latest changes from the GitHub repo and rerun the install script or uv pip install -e . inside the virtual environment.

Never Lose Context Again

Transform your Claude conversations into a searchable, organized knowledge base that grows with you

✨ Core Benefits

• 🧠 Infinite Memory - Claude remembers everything across unlimited conversations with intelligent auto-summarization
• 🔒 Your Data, Your Control - 100% local storage with zero cloud dependencies or privacy concerns
• 🎯 Effortless Organization - Smart tags and folders that organize themselves around your workflow
• 🔗 Intelligent Merging - Automatically combines related conversations while eliminating duplicates

What's new in v2.3.2

Issue:

Storage health reports as UNHEALTHY due to async/await issue.

Fix:

Updated methods to async that were missed earliers

  - DiagnosticTool.run_health_checks()
  - DiagnosticTool._check_storage_health()
  - DiagnosticTool.generate_system_report()
  - StatusMonitoringSystem.get_system_status()
  - StatusMonitoringSystem.generate_full_report()

🚀 Quick Start

curl -fsSL https://github.com/ukkit/memcord/raw/main/install.sh | bash

This will:

• Download and setup memcord
• Set Up Python Virtual Environment using uv
• Update claude_desktop_config.json & README.md with Installation Path

Claude Desktop/VSCode

{
  "mcpServers": {
    "memcord": {
      "command": "uv",
      "args": [
        "--directory",
        "</path/to/memcord>",
        "run",
        "memcord"
      ],
      "env": {
        "PYTHONPATH": "</path/to/memcord>/src"
      }
    }
  }
}

Claude Code MCP (🧪 BETA)

Add MCP server for your project - check README.md for installation path

claude mcp add-json memcord '{"type":"stdio","command":"uv","args":["--directory","</path/to/memcord>","run","memcord"],"env":{"PYTHONPATH":"</path/to/memcord>/src"}}'

Verify installation

claude mcp list
claude mcp get memcord

Add at top of your CLAUDE.md file

memcord_name "NAME_OF_YOUR_PROJECT"

Manual Installaion

# Traditional installation method
git clone https://github.com/ukkit/memcord.git
cd memcord
uv venv
source .venv/bin/activate
uv pip install -e .

# Replace </path/to/memcord/> in claude_desktop_config.json to the path where you installed it manually

Complete Installation Guide - Detailed setup for Claude Code, Claude Desktop, and other MCP applications.

💻 Basic Usage

# Create a memory slot and save conversation
memcord_name "project_meeting"
memcord_save "Our discussion about the new API design..."
memcord_save_progress

# Use existing memory slot
memcord_use "project_meeting" 🆕

# Navigate timeline - select specific entries
memcord_select_entry "2 hours ago"  # or "latest", index, timestamp 🆕

# Privacy control - activate zero mode (no saving)
memcord_zero  # No memory will be saved until switched to another slot

# Search and query your memories
memcord_search "API design decisions"
memcord_query "What did we decide about authentication?"

# Merge related conversations
memcord_merge ["project_meeting", "api_notes"] "consolidated_project" 🆕

Refer to 📖 Complete Tools Reference for Advanced Mode and detailed documentation for all 19 tools with examples and parameters.

📚 Documentation

• 📚 Installation Guide - Complete setup instructions for all MCP applications
• 📃 Feature Guide - Complete list of features
• 📖 Tools Reference - Detailed documentation for all 19 tools
• 📥 Import & Merge Guide - Comprehensive guide for Phase 3 features 🆕
• 🔍 Search & Query Guide - Advanced search features and natural language queries
• 🗂️ Usage Examples - Real-world workflows and practical use cases
• ⚙️ Data Format Specification - Technical details and file formats
• 🛠️ Troubleshooting - Common issues and solutions

---

💎 If you find this project helpful, consider:

• 🌟 Starring the repository on GitHub
• 🤝 Support Development
• 🐛 Reporting bugs and suggesting features

---

MIT License - see LICENSE file for details.