memcord

Never Lose Context Again

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

> **What's new in v4.3.6** — removes two unnecessary dependencies (`pandas`, `python-magic`) from a fresh install; CSV/TSV import now uses the standard library instead of pandas.

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

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

Manual update

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:

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`. 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:

MIT License - see LICENSE file for details.