# Tools Reference

Complete reference for all 23 tools available in Memcord.

## Tool Availability

MemCord offers **two modes** with different tool sets:

### 🔧 Basic Mode (Default - 15 Tools)
Available without configuration:
- Core: `memcord_name`, `memcord_use`, `memcord_save`, `memcord_read`, `memcord_save_progress`, `memcord_list`
- Configuration: `memcord_configure`
- Search: `memcord_search`, `memcord_query`
- Privacy: `memcord_zero`
- Selection: `memcord_select_entry`
- Integration: `memcord_merge`
- Project Binding: `memcord_init`, `memcord_unbind`
- Utility: `memcord_ping`

### ⚡ Advanced Mode (All 23 Tools)
Requires `MEMCORD_ENABLE_ADVANCED=true`:
- **All Basic tools** plus:
- Organization: `memcord_tag`, `memcord_list_tags`, `memcord_group`
- Import: `memcord_import`
- Storage: `memcord_compress`
- Export & Sharing: `memcord_export`, `memcord_share`
- Archival: `memcord_archive`

---

## Basic Tools (Always Available)

### Core Memory Management

### 1. `memcord_name <slot_name>`
Creates or selects a named memory slot.

**Parameters:**
- `slot_name`: Name of the memory slot to create or select

**Examples:**
- "Set memory slot to 'project_alpha'"
- "Create memory slot called 'meeting_notes'"

### 2. `memcord_use <slot_name>`
Activates an existing memory slot (does not create new slots).

**Parameters:**
- `slot_name`: Name of the existing memory slot to activate

**Examples:**
- "Use memory slot 'project_alpha'"
- "Switch to existing slot 'meeting_notes'"

**Note:** This tool only activates existing slots. If the slot doesn't exist, it returns an error suggesting to use `memcord_name` to create new slots or `memcord_list` to see available slots.

### 3. `memcord_save <chat_text>`
Manually saves exact chat text to current memory slot (overwrites existing content).

**Parameters:**
- `chat_text`: The conversation text to save
- `slot_name` (optional): Target memory slot. If not provided, uses current slot

**Slot resolution priority:** explicit `slot_name` → active slot → `.memcord` binding file in cwd. If the bound slot exists, it is also auto-activated for the rest of the session.

**Examples:**
- "Save this conversation to memory"
- "Store our discussion about the API changes"

### 4. `memcord_read [slot_name]`
Retrieves full content from memory slot.

**Parameters:**
- `slot_name` (optional): Name of slot to read. If not provided, uses current slot

**Slot resolution priority:** explicit `slot_name` → active slot → `.memcord` binding file in cwd.

**Examples:**
- "What did we discuss in the last session?"
- "Read from slot 'project_alpha'"

### 5. `memcord_save_progress <chat_text> [compression_ratio]`
Generates a summary and appends it to memory slot with timestamp.

**Parameters:**
- `chat_text`: Text to summarize
- `slot_name` (optional): Target memory slot. If not provided, uses current slot
- `compression_ratio` (optional): Target compression (0.05-0.5). Defaults to the slot's `default_compression_ratio` config value (0.15)

**Slot resolution priority:** explicit `slot_name` → active slot → `.memcord` binding file in cwd. If the bound slot exists, it is also auto-activated for the rest of the session.

**Summarizer backend:** Uses the backend configured for the slot via `memcord_configure`. New slots default to `sumy` (graph-based, zero model files); existing slots default to `nltk` (unchanged prior behavior). Override globally with `MEMCORD_SUMMARIZER` env var.

**Examples:**
- "Summarize our progress and save it"
- "Save progress with 10% compression"

### 6. `memcord_configure`
Get or set per-slot configuration — summarizer backend, consolidation limits, and custom storage location.

**Parameters:**
- `action`: `get` (show config), `set` (update a key), or `reset` (restore defaults)
- `key` (required for `set`): Config key to update. Valid keys:
  - `summarizer_backend` — `"sumy"` | `"semantic"` | `"transformers"` | `"nltk"`
  - `sumy_algorithm` — `"lexrank"` | `"lsa"` | `"edmundson"`
  - `semantic_model` — sentence-transformers model name (default: `"all-MiniLM-L6-v2"`)
  - `transformers_model` — HuggingFace model name (default: `"philschmid/bart-large-cnn-samsum"`)
  - `hf_device` — `"auto"` | `"cpu"` | `"cuda"` | `"mps"`
  - `default_compression_ratio` — float between 0.05 and 0.5
  - `max_auto_summaries` — int ≥ 0; max combined `auto_summary`/`rolled_summary` entries before consolidation (`0` disables)
  - `custom_storage_path` — absolute directory where this slot's data and settings live (e.g. a synced Dropbox/OneDrive folder); empty string or `"none"` reverts to the default location
- `value` (required for `set`): New value for the key
- `slot_name` (optional): Target slot. Uses current slot if not specified

**Slot resolution priority:** explicit `slot_name` → active slot → `.memcord` binding file in cwd.

**Config is per-slot** and stored as a sidecar JSON file (`{slot}_config.json`) that lives alongside the slot's data — in the default memory directory, or in the slot's custom storage directory once linked. Changes take effect on the very next `memcord_save_progress` call — no restart required.

**Auto-creation rules:**
- New slot (no `.json` file yet) → `summarizer_backend = "sumy"` (smarter default)
- Existing slot (`.json` file present) → `summarizer_backend = "nltk"` (preserves prior behavior)

**`custom_storage_path` behavior:**
- Setting it on a slot that already has data **automatically migrates** the slot's `.json` (and `.bak`) file *and* its settings sidecar (`{slot}_config.json`, with its own `.bak`) to the new directory — nothing is left behind.
- Setting it on a slot with no data yet just records the redirect; the next save writes straight to the custom location.
- If data already exists at *both* the old and new locations, the call is refused (no overwrite) so you can resolve the conflict manually. The same protection applies to the settings sidecar: an existing sidecar at the destination is never overwritten.
- The redirect itself is **local to this machine**, recorded in a `_storage_links.json` registry file in the local memory directory — each device pointing at a shared folder (e.g. Dropbox) needs to run its own `set` once, using whatever path that folder resolves to locally.
- Once linked, the settings sidecar lives at the custom location too, so `summarizer_backend`, `sumy_algorithm`, and the other config keys above are shared across every device pointing at that folder — not just the slot's content. Derived data (search index, cache, archives) stays local and is rebuilt lazily.

**Examples:**
- `memcord_configure action="get"` — Show current slot config
- `memcord_configure action="set" key="summarizer_backend" value="transformers"` — Switch to abstractive BART
- `memcord_configure action="set" key="default_compression_ratio" value="0.25"` — Set compression to 25%
- `memcord_configure action="set" key="custom_storage_path" value="D:\Dropbox\shared"` — Move/link this slot to a synced folder
- `memcord_configure action="set" key="custom_storage_path" value=""` — Revert to the default storage location
- `memcord_configure action="reset"` — Restore defaults for current slot

**Env var override:** `MEMCORD_SUMMARIZER=nltk` overrides per-slot config for all slots (useful for Docker/CI).

### 7. `memcord_list`
Lists all available memory slots with metadata.

**Parameters:** None

**Examples:**
- "Show me all my memory slots"
- "List all available memories"

### 8. `memcord_ping`
Lightweight health check for server warm-up. Returns minimal response to confirm server is running.

**Parameters:** None

**Returns:** "pong"

**Use Cases:**
- Warm up the server at session start to avoid cold start delays
- Health check to verify server is responsive
- Configure in Claude Code hooks for automatic warm-up

**Examples:**
- Call `memcord_ping` at the start of a session
- Add to `UserPromptSubmit` hook for automatic warm-up

See [Server Warm-up](claude-code-guide.md#server-warm-up-avoid-cold-start-delays) for hook configuration.

### 9. `memcord_search <query> [options]`
Search across all memory slots with advanced filtering.

**Parameters:**
- `query`: Search query string
- `include_tags` (optional): Only include slots with these tags
- `exclude_tags` (optional): Exclude slots with these tags
- `max_results` (optional): Maximum number of results (default: 20)
- `case_sensitive` (optional): Whether search is case sensitive (default: false)

**Examples:**
- "Search for 'API integration'"
- "Search for 'database' excluding tag 'archived'"

### 10. `memcord_query <question>`
Ask natural language questions about your stored memories.

**Parameters:**
- `question`: Natural language question
- `max_results` (optional): Maximum number of results to consider (default: 5)

**Examples:**
- "What decisions were made about the API design?"
- "What issues were discussed in the last meeting?"

### Privacy Control

### 11. `memcord_zero`
Activate zero mode - no memory will be saved until switched to another slot.

**Parameters:**
- None

**Behavior:**
- Activates "zero mode" where all save operations are blocked
- Clear notifications inform user when zero mode is active
- `memcord_list` shows zero mode status prominently
- Mode persists until user switches to another memory slot with `memcord_name`

**Examples:**
- `memcord_zero` - Activate zero mode
- After activation, any `memcord_save` or `memcord_save_progress` will be blocked with helpful guidance

**Use Cases:**
- **Privacy conversations**: Ensure sensitive discussions aren't accidentally saved
- **Testing scenarios**: Prevent test conversations from polluting memory
- **Temporary usage**: Use Claude without building permanent memory
- **Guest access**: Allow others to use your setup without saving their conversations

**Exit Zero Mode:**
- Use `memcord_name [slot_name]` to select any memory slot and resume saving

### Entry Selection & Timeline Navigation

### 12. `memcord_select_entry`
Select and retrieve a specific memory entry by timestamp, relative time, or index within a memory slot.

**Parameters:**
- `slot_name` (optional): Target memory slot (uses current if not specified)
- `timestamp` (optional): Exact timestamp in ISO format (e.g., '2025-07-21T17:30:00')
- `relative_time` (optional): Human descriptions like 'latest', 'oldest', '2 hours ago', 'yesterday'
- `entry_index` (optional): Direct numeric index (0-based, negative for reverse indexing)
- `entry_type` (optional): Filter by entry type ('manual_save' or 'auto_summary')
- `show_context` (optional): Include timeline position and adjacent entries info (default: true)

**Selection Methods (choose exactly one):**
- **Timestamp Selection**: Exact timestamp matching with 30-minute tolerance
- **Relative Time**: Natural language expressions for temporal navigation
- **Index Selection**: Direct numeric access to entries in chronological order

**Examples:**
- `memcord_select_entry timestamp="2025-07-21T17:30:00"` - Select entry closest to specific time
- `memcord_select_entry relative_time="latest"` - Get the most recent entry
- `memcord_select_entry relative_time="2 hours ago"` - Get entry from approximately 2 hours ago
- `memcord_select_entry entry_index=0` - Get the oldest entry (first in timeline)
- `memcord_select_entry entry_index=-1` - Get the newest entry (last in timeline)
- `memcord_select_entry relative_time="oldest" entry_type="manual_save"` - Get oldest manual save

**Relative Time Expressions:**
- **Simple**: 'latest', 'newest', 'oldest', 'earliest', 'first'
- **Ordinal**: '2nd latest', 'third oldest', 'second newest'
- **Time Deltas**: '2 hours ago', '30 minutes ago', 'yesterday', 'last week'

**Features:**
- **Timeline Context**: Shows position and adjacent entries for navigation
- **Flexible Matching**: Tolerant timestamp matching for approximate selection
- **Type Filtering**: Filter by manual saves vs auto summaries
- **Error Guidance**: Helpful messages with available options when selection fails
- **Index Support**: Both positive (0=oldest) and negative (-1=newest) indexing

**Use Cases:**
- **Timeline Navigation**: Jump to specific points in conversation history
- **Content Retrieval**: Access specific decisions or discussions by time
- **Version Comparison**: Compare different versions of content over time
- **Context Building**: Select relevant entries for current discussion

### Memory Integration

### 13. `memcord_merge <source_slots> <target_slot> [options]`
Merge multiple memory slots into one with intelligent duplicate detection.

**Parameters:**
- `source_slots`: Array of memory slot names to merge (minimum 2)
- `target_slot`: Name for the merged memory slot
- `action` (optional): `preview` (default) or `merge`
- `similarity_threshold` (optional): Duplicate detection threshold 0.0-1.0 (default 0.8)
- `delete_sources` (optional): Delete source slots after successful merge (default false)

**Actions:**
- **Preview**: Shows merge statistics and content preview without executing
- **Merge**: Executes the merge operation with duplicate removal

**Examples:**
- "Preview merge: `memcord_merge source_slots=['meeting1','meeting2','meeting3'] target_slot='project_meetings' action='preview'`"
- "Execute merge: `memcord_merge source_slots=['draft1','draft2'] target_slot='final_document' action='merge' similarity_threshold=0.7`"
- "Merge with cleanup: `memcord_merge source_slots=['temp1','temp2'] target_slot='consolidated' action='merge' delete_sources=true`"

**Features:**
- **Duplicate Detection**: Configurable similarity threshold for content deduplication
- **Chronological Ordering**: Maintains timeline of merged content
- **Metadata Consolidation**: Merges tags and groups from all source slots
- **Preview Mode**: See merge results before execution
- **Source Cleanup**: Optional deletion of source slots after successful merge
- **Merge Statistics**: Detailed information about content and duplicates removed

**Use Cases:**
- **Project Consolidation**: Combine related project discussions into single slot
- **Meeting Summaries**: Merge multiple meeting notes into comprehensive overview
- **Research Organization**: Consolidate scattered research into organized collection
- **Content Cleanup**: Remove duplicates while preserving unique information

### Project Binding

### 14. `memcord_init <project_path> [slot_name]`
Initialize memcord for a project directory by binding it to a memory slot. Creates a `.memcord` file in the project root.

**Parameters:**
- `project_path`: Path to the project directory to initialize
- `slot_name` (optional): Memory slot name to bind. If not specified, uses directory name

**Behavior:**
- Creates a `.memcord` file in the project directory containing the slot name
- Auto-generates slot name from directory name if not specified (spaces replaced with underscores)
- Creates the memory slot if it doesn't exist
- If `.memcord` file already exists, reads and uses the existing slot name (unless new slot_name is specified)

**Examples:**
- `memcord_init project_path="/path/to/my-project"` - Initializes with slot named "my-project"
- `memcord_init project_path="/path/to/project" slot_name="custom-slot"` - Initializes with specified slot
- `memcord_init project_path="."` - Initializes current directory

**Use Cases:**
- **Project-specific memory**: Each project automatically uses its own memory slot
- **Team collaboration**: `.memcord` file can be committed to version control
- **Auto-detection**: Claude Code slash commands automatically use the bound slot

### 15. `memcord_unbind <project_path>`
Remove the `.memcord` binding file from a project directory.

**Parameters:**
- `project_path`: Path to the project directory to unbind

**Behavior:**
- Removes the `.memcord` file from the project directory
- Does NOT delete the memory slot itself (data is preserved)
- Returns helpful message if no `.memcord` file exists

**Examples:**
- `memcord_unbind project_path="/path/to/my-project"` - Removes binding
- `memcord_unbind project_path="."` - Unbinds current directory

---

## Advanced Tools (Requires MEMCORD_ENABLE_ADVANCED=true)

### Storage Optimization

### 16. `memcord_compress`
Compress memory slot content to save storage space with intelligent gzip compression.

**Parameters:**
- `action`: Action to perform (`analyze`, `compress`, `decompress`, `stats`)
- `slot_name` (optional): Memory slot name to compress. Processes all slots if not specified
- `force` (optional): Force compression even for already compressed content (default: false)

**Actions:**
- **`analyze`**: Preview compression potential without making changes
- **`compress`**: Apply compression to memory slot content 
- **`decompress`**: Restore compressed content to original form
- **`stats`**: View detailed compression statistics

**Examples:**
- `memcord_compress action="analyze"` - Preview compression for all slots
- `memcord_compress action="compress" slot_name="project_alpha"` - Compress specific slot
- `memcord_compress action="stats"` - View overall compression statistics
- `memcord_compress action="decompress" slot_name="project_alpha"` - Restore original content

**Features:**
- Automatic compression threshold (1KB minimum)
- 30-70% typical storage reduction
- Maintains search functionality on compressed content
- Transparent decompression when reading content

### Organization Tools

### 17. `memcord_tag <action> [tags]`
Manage tags for memory slots.

**Parameters:**
- `action`: Action to perform (`add`, `remove`, `list`)
- `tags` (optional): Space-separated list of tags (required for add/remove)

**Examples:**
- "Add tags 'project', 'meeting' to current slot"
- "Remove tag 'draft' from current slot"
- "List all tags for current slot"

**Tag Features:**
- Multiple tags per slot
- Case-insensitive (stored in lowercase)
- Hierarchical tags using dot notation (e.g., "project.alpha.backend")
- Auto-completion suggestions

### 18. `memcord_list_tags`
List all tags used across all memory slots.

**Parameters:** None

**Examples:**
- "Show me all available tags"
- "What tags are being used?"

**Output includes:**
- Tag name
- Usage count
- Associated memory slots

### 19. `memcord_group <action> [group_path]`
Manage memory slot groups and folders.

**Parameters:**
- `action`: Action to perform (`set`, `remove`, `list`)
- `group_path` (optional): Hierarchical path (required for set)

**Examples:**
- "Set group 'projects/alpha' for current slot"
- "Remove group assignment from current slot"
- "List all memory groups"

**Group Features:**
- Hierarchical folder structure
- Unlimited nesting depth
- Path-based navigation
- Bulk operations on group members

### Import & Integration

### 20. `memcord_import <source> [options]`
Import content from various sources including files, PDFs, web URLs, and structured data.

**Parameters:**
- `source`: Source to import from (file path, URL, etc.)
- `slot_name` (optional): Target memory slot name. Uses current slot if not specified
- `description` (optional): Description for the imported content
- `tags` (optional): Array of tags to apply to the imported content
- `group_path` (optional): Group path for organization

**Supported Sources:**
- **Text Files**: `.txt`, `.md`, `.markdown`, `.rst`, `.log`
- **PDF Documents**: Extracts text content page by page
- **Web URLs**: Extracts clean article content from web pages
- **Structured Data**: `.json`, `.csv`, `.tsv` files

**Examples:**
- "Import PDF document: `memcord_import source='/path/to/document.pdf' slot_name='research_docs' tags=['pdf','research']`"
- "Import web article: `memcord_import source='https://example.com/article' slot_name='web_content' group_path='articles/tech'`"
- "Import CSV data: `memcord_import source='/data/export.csv' slot_name='analytics_data' description='Sales data Q1 2025'`"
- "Import markdown file: `memcord_import source='./notes.md' tags=['notes','draft']`"

**Features:**
- Automatic source type detection
- Import metadata preservation
- Rich content headers with source information
- Support for large files (up to 50MB)
- Comprehensive error handling

### Archival & Long-term Storage

### 21. `memcord_archive <action> [options]`
Archive or restore memory slots for long-term storage with automatic compression.

**Parameters:**
- `action`: Action to perform (`archive`, `restore`, `list`, `stats`, `candidates`)
- `slot_name` (optional): Memory slot name to archive/restore (required for `archive` and `restore`)
- `reason` (optional): Reason for archiving (default: "manual")
- `days_inactive` (optional): Days of inactivity for finding candidates (default: 30)

**Actions:**
- **`archive`**: Move a memory slot to compressed archive storage
- **`restore`**: Restore an archived slot back to active memory
- **`list`**: Browse all archived memory slots with metadata
- **`stats`**: View archive storage statistics and space savings
- **`candidates`**: Find slots suitable for archiving based on inactivity

**Examples:**
- `memcord_archive action="candidates" days_inactive=30` - Find slots inactive for 30+ days
- `memcord_archive action="archive" slot_name="old_project" reason="project_completed"` - Archive specific slot
- `memcord_archive action="list"` - View all archived slots
- `memcord_archive action="restore" slot_name="old_project"` - Restore from archive
- `memcord_archive action="stats"` - View archive statistics

**Features:**
- **Automatic Compression**: Archives are compressed for maximum space savings
- **Preserved Metadata**: All tags, groups, and timestamps maintained
- **Search Integration**: Archived content remains searchable (future enhancement)
- **Safe Operations**: Archives preserve original data with restoration capability
- **Usage Analytics**: Identifies inactive slots for archival recommendations

### Export & Sharing

### 22. `memcord_export <slot_name> <format>`
Exports memory slot as an MCP file resource.

**Parameters:**
- `slot_name`: Name of the memory slot to export
- `format`: Export format (`md`, `txt`, `json`)

**Examples:**
- "Export project_alpha as markdown"
- "Export meeting_notes as JSON"

### 23. `memcord_share <slot_name> [formats]`
Generates shareable files in multiple formats.

**Parameters:**
- `slot_name`: Name of the memory slot to share
- `formats` (optional): Comma-separated list of formats (default: all)

**Examples:**
- "Share project_alpha in markdown and text formats"
- "Share meeting_notes in all formats"

## Advanced Usage Patterns

### Combining Tools
```
1. Create and organize:
   memcord_name "api_review" → memcord_tag add "technical review urgent" → memcord_group set "projects/backend"

2. Search and analyze:
   memcord_search "database performance" → memcord_query "What performance issues were identified?"

3. Export and share:
   memcord_export "api_review" "md" → memcord_share "api_review" "md,txt"
```

### Workflow Integration
```
1. Daily standup workflow:
   memcord_name "standup_2024_01_15" → memcord_save [conversation] → memcord_tag add "standup daily" → memcord_group set "meetings/daily"

2. Project documentation:
   memcord_name "project_specs" → memcord_save_progress [content] 0.1 → memcord_tag add "specs documentation" → memcord_export "project_specs" "md"

3. Research and analysis:
   memcord_search "security audit" → memcord_query "What security recommendations were made?" → memcord_name "security_summary" → memcord_save [findings]
```

## Tool Chaining

Many tools can be chained together for complex operations:

```
# Complete project setup
memcord_name → memcord_tag add → memcord_group set → memcord_save → memcord_export

# Research workflow  
memcord_search → memcord_query → memcord_name → memcord_save_progress

# Organization review
memcord_list → memcord_list_tags → memcord_group list → memcord_search [tag filter]
```

## Error Handling

Common error messages and solutions:

- **"No memory slot selected"**: Use `memcord_name` first
- **"Memory slot not found"**: Check spelling with `memcord_list`
- **"Invalid compression ratio"**: Use value between 0.05 and 0.5
- **"Unknown config key"**: Run `memcord_configure action="get"` to see valid keys
- **"Unknown action"**: Use `get`, `set`, or `reset` for `memcord_configure`
- **"No search results"**: Try broader terms or check spelling
- **"Tag not found"**: Verify with `memcord_list_tags`
- **"Invalid group path"**: Use forward slashes for hierarchy