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+ — python.org
-
uv (Python package manager) — install with:
macOS / Linux:
curl -LsSf https://astral.sh/uv/install.sh | shWindows (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
Re-run the same installer command from Quick Start from the same folder where memcord is installed — it detects an existing installation and updates it in place instead of cloning a fresh copy:
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:
- ✅ Pull the latest changes (fast-forward only — aborts safely if you have local edits)
- ✅ Reuse your existing virtual environment and upgrade dependencies
- ✅ Regenerate MCP configuration files
- ✅ Leave your memory data (
memory_slots/) and generated configs untouched
cd /path/to/memcord
git pull
uv pip install -e . --upgrade
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.
Switching an Existing Install to Global Scope
Fresh installs register memcord globally (~/.claude.json) by default — available in every project. If you have an older install that's still project-scoped (a local .mcp.json), switch it explicitly — re-running the updater alone won't do this for you, since it auto-detects and preserves an existing project-scoped setup on purpose:
cd /path/to/memcord
uv run python scripts/generate-config.py --scope user
Verify from a different project directory: claude mcp list should now show memcord. The original .mcp.json is left in place and still works (harmless, just redundant) — delete it only if you want that directory to stop pinning its own local copy instead of falling through to the global one.
Installing Slash Commands Globally
The 17 memcord-* slash commands ship in .claude/commands/ and are already usable from inside the memcord checkout the moment you clone it. To use them from any project directory, install them globally into ~/.claude/commands/:
uv run python scripts/generate-config.py --manage-commands # interactive picker
uv run python scripts/generate-config.py --commands all # non-interactive: install all
Fresh installs prompt for this automatically (skipped when non-interactive, e.g. curl | bash). Re-run anytime to change your selection — only memcord's own command files are ever added or removed.
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
Searching & Querying (Direct Tool Calls)
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
See Complete Tools Reference for all 23 tools with full parameters and examples.
How Auto-Detection Works
All read and write operations follow the same slot resolution priority:
- Explicit
slot_nameargument (always wins) - Currently active slot (set by
memcord_useormemcord_name) .memcordbinding 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. Once linked, the slot's settings (summarizer backend, etc.) travel with the data too, so every device sharing the folder sees the same configuration.
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:
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
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.
