memcord

MEMCORD v3.4.1 (mcp server)

This privacy-first, self-hosted MCP server helps you organize chat history, summarize messages, search across past chats with AI — and keeps everything secure and fully under your control.

Never Lose Context Again

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

What's new in v3.4.1 — MCP spec 2025-11-25 compliance fixes: isError=true on all tool execution errors for LLM self-correction, SDK bump to mcp 1.27.1, and tightened inputSchema for no-parameter tools.

Table of Contents

• Core Benefits
• Prerequisites
• Quick Start
• Demo
• IDE Configuration
• Keeping Memcord Updated
• Using Memcord in a Project
• Basic Usage
• Summarizer Backends
• Documentation

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 - Per-project memory slots with timeline navigation and smart tagging
• Intelligent Merging - Automatically combines related conversations while eliminating duplicates

Prerequisites

Quick Start

macOS / Linux:

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

Windows (PowerShell):

irm https://github.com/ukkit/memcord/raw/main/install.ps1 | iex

This will:

• ✅ Download and setup memcord
• ✅ Set up Python virtual environment using uv
• ✅ Generate platform-specific MCP configuration files
• ✅ Configure Claude Desktop, Claude Code, VSCode, and Antigravity IDE

Demo

A demo GIF or terminal recording will be added here. Contributions welcome!

IDE Configuration

The installer auto-configures all supported IDEs. For manual setup or troubleshooting, see the detailed guides:

Manual Installation

git clone https://github.com/ukkit/memcord.git
cd memcord
uv venv && uv pip install -e .
uv run python scripts/generate-config.py

See the Complete Installation Guide for updating, advanced options, and custom commands.

Keeping Memcord Updated

cd /path/to/memcord
git pull
uv pip install -e .
uv run python scripts/generate-config.py  # Regenerate configs

# Optional: Enable auto-save hooks (new in v2.5.0)
uv run python scripts/generate-config.py --install-hooks

The --install-hooks flag is idempotent — it merges into existing .claude/settings.json without overwriting other settings or hooks.

Using Memcord in a Project

First-Time Setup (New Project)

# 1. Once you are in claude code, initialize the project with a memory slot (one-time setup)
memcord_init "." "my-project-name"
# OR
memcord_init "my_project_name"
# Creates .memcord file containing "my-project-name"

# 2. Start saving your conversations
/memcord-save-progress  # Auto-detects slot from .memcord file

Subsequent Sessions (Returning to Project)

# Just use slash commands - no slot name needed!
/memcord-read           # Reads from bound slot automatically

/memcord-save           # Saves to bound slot automatically
/memcord-save-progress  # Summarizes and saves automatically

Enable Auto-Save (Optional)

uv run python scripts/generate-config.py --install-hooks

Automatically saves conversation progress before context compaction and on session end. See config-templates/README.md for details.

How Auto-Detection Works

All read and write operations follow the same slot resolution priority:

1. Explicit slot_name argument (always wins)
2. Currently active slot (set by memcord_use or memcord_name)
3. .memcord binding file in the current working directory

When the .memcord binding is used and the slot already exists, it is also auto-activated for the rest of the session — so subsequent operations skip re-detection automatically.

This means after memcord_init, a fresh session (no memcord_use call needed) will correctly route memcord_save, memcord_save_progress, memcord_configure, and memcord_read to the bound slot.

Basic Usage

Saving & Retrieving

memcord_name "project_meeting"          # Create or select a slot
memcord_save "Our discussion about..."  # Save exact text
memcord_save_progress                   # Save a compressed summary
memcord_read                            # Read the slot

Navigating & Searching

memcord_select_entry "2 hours ago"    # Jump to a point in the timeline
memcord_list                          # List all slots
memcord_search "API design"           # Full-text search
memcord_query "What did we decide?"   # Natural language query

Project & Privacy

memcord_init "." "my-project"  # Bind a memory slot to this directory
memcord_zero                   # Privacy mode — nothing gets saved

See Complete Tools Reference for all 23 tools with full parameters and examples.

Summarizer Backends

Memcord supports four summarizer backends. New slots default to sumy (graph-based, no downloads required). Existing slots keep nltk to preserve prior behavior.

Switching Backends

Use memcord_configure to change the backend for any slot — no restart required:

# Check current config
memcord_configure action="get"

# Switch to the BART abstractive summarizer (best for conversations)
memcord_configure action="set" key="summarizer_backend" value="transformers"

# Switch to embedding-based semantic summarizer
memcord_configure action="set" key="summarizer_backend" value="semantic"

# Switch sumy algorithm (lexrank / lsa / edmundson)
memcord_configure action="set" key="sumy_algorithm" value="lsa"

# Reset to defaults
memcord_configure action="reset"

To apply one backend to all slots (e.g. in Docker or CI), set the environment variable:

export MEMCORD_SUMMARIZER=transformers

See Tools Reference — memcord_configure for the full parameter list.

Documentation

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.

Star History