memcord

Never Lose Context Again

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

What's new in v4.1.0 — Share a memory slot across devices: point any slot at a custom directory (e.g. a synced Dropbox/OneDrive folder) via memcord_configure, with automatic migration of existing data.

Table of Contents

• Core Benefits
• Prerequisites
• Quick Start
• Keeping Memcord Updated
• Using Memcord
• Custom Storage Path
• Summarizer Backends
• IDE Configuration
• 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

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

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
/memcord-save           # Saves to bound slot
/memcord-save-progress  # Summarizes and saves

Saving, Searching & Querying (Direct Tool Calls)

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

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

memcord_zero                          # Privacy mode — nothing gets saved

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

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.

Custom Storage Path

Point a slot's data file at any directory — e.g. a Dropbox/OneDrive folder — to share it across devices, via memcord_configure.

New memory in an external path:

memcord_name "shared_slot"
memcord_configure action="set" key="custom_storage_path" value="D:\Dropbox\shared"
memcord_save "..."   # writes directly to the external path

Migrate an existing memory:

memcord_configure action="set" key="custom_storage_path" value="D:\Dropbox\shared"
# Existing data is moved automatically — memcord_read/memcord_list keep working

Each device needs to run the set command once with its own local path to the shared folder. See Tools Reference — memcord_configure for migration/collision details.

Summarizer Backends

Memcord supports four pluggable summarizer backends (nltk, sumy, semantic, transformers), switchable per slot via memcord_configure action="set" key="summarizer_backend" value="..." — no restart required. New slots default to sumy (no downloads); existing slots keep nltk for backward compatibility.

See Tools Reference — memcord_configure and Features Guide for the full backend comparison, install instructions, and the MEMCORD_SUMMARIZER env var override.

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.

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