ukkit/memcord

Never Lose Context Again

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

What's new in v3.4.0 — Full MCP spec 2025-03-26 / 2025-11-25 compliance: tool annotations (readOnly/destructive/idempotent hints) on all 28 tools, Anthropic result-size extension on read/query tools, enriched resource metadata, ResourceTemplate registration with slot-name autocompletion, and progress notifications with message field in long-running handlers.

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

Python 3.10+ and uv are required. The installer handles both — click to expand manual instructions.

• Python 3.10+ — python.org

• uv (Python package manager) — install with:

  macOS / Linux:

  curl -LsSf https://astral.sh/uv/install.sh | sh
  

  Windows (PowerShell):

  powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
  

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:

IDE / Client	Guide
Claude Code CLI	Installation Guide — Claude Code
Claude Desktop	Installation Guide — Claude Desktop
VSCode + GitHub Copilot	VSCode Setup Guide
Google Antigravity	Installation Guide — Other MCP Apps
Configuration templates	config-templates/ (README)

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.

Backend	Type	Speed	Quality	Extra install
nltk	Extractive	Fast	Good	None (built-in)
sumy	Extractive (graph)	Fast	Better	None (built-in)
semantic	Extractive (embeddings)	Medium	Best extractive	uv pip install "memcord[semantic]" (~80 MB)
transformers	Abstractive (BART)	Slow	Best overall	uv pip install "memcord[transformers]" (~400 MB)

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

Guide	Description
Installation Guide	Complete setup instructions for all MCP applications
Feature Guide	Complete list of features
Tools Reference	Detailed documentation for all 23 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
Version History	Changelog for all releases

---

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