# MCP Memory Service - Agent Guidelines
## Available Agents
### amp-bridge
**Purpose**: Leverage Amp CLI capabilities (research, code analysis, web search) without consuming Claude Code credits.
**Usage**: `Use @agent-amp-bridge to research XYZ`
**How it works**:
1. Agent creates concise prompt in `.claude/amp/prompts/pending/{uuid}.json`
2. Shows you command: `amp @{prompt-file}`
3. You run command in your authenticated Amp session (free tier)
4. Amp writes response to `.claude/amp/responses/ready/{uuid}.json`
5. Agent detects, reads, and presents results
**Key principle**: Agent creates SHORT, focused prompts (2-4 sentences) to conserve Amp credits.
**Example**:
- ❌ Bad: "Research TypeScript 5.0 in detail covering: 1. Const params... 2. Decorators... 3. Export modifiers..."
- ✅ Good: "Research TypeScript 5.0's key new features with brief code examples."
## Build/Lint/Test Commands
- **Run all tests**: `pytest tests/`
- **Run single test**: `pytest tests/test_filename.py::test_function_name -v`
- **Run specific test class**: `pytest tests/test_filename.py::TestClass -v`
- **Run with markers**: `pytest -m "unit or integration"`
- **MCP Server startup**: `uv run memory server`
- **HTTP Dashboard startup**: `python run_server.py` or `./start_all_servers.sh`
- **Install dependencies**: `python scripts/installation/install.py`
## Server Management Commands
- **Start all servers**: `./start_all_servers.sh` (both MCP + HTTP Dashboard)
- **Stop all servers**: `./stop_all_servers.sh`
- **Check server status**: `./status_servers.sh`
- **View HTTP logs**: `tail -f http_server.log`
- **View MCP logs**: `tail -f mcp_server.log`
## Memory Cleanup & Auto-Tagging Commands
### Individual Memory Auto-Tagging
- **Auto-retag single memory (replace)**: `python3 auto_retag_memory.py --search "query"` or `python3 auto_retag_memory.py {hash}`
- Analyzes content, generates tags, replaces all old tags
- Best for untagged memories
- **Auto-retag single memory (merge)**: `python3 auto_retag_memory_merge.py --search "query"` or `python3 auto_retag_memory_merge.py {hash}` ⭐ **RECOMMENDED**
- Analyzes content, generates tags, merges with existing (preserves v8.x, project names, tech-specific)
- Best for memories with some existing tags
- Shows diff before applying
### Bulk Memory Operations
- **Bulk retag valuable untagged memories**: `python3 retag_valuable_memories.py`
- Analyzes content, identifies valuable vs. test, applies semantic tags
- Skips test data automatically
- ~340+ memories retagged, ~0 failures per run
- **Bulk delete test memories**: `python3 delete_test_memories.py`
- Identifies test data by pattern matching
- Shows samples before deletion
- Requires confirmation
- ~209 test memories deleted per run
### Manual Editing
- **Dashboard UI retagging**: http://127.0.0.1:8000
- Click memory → Edit Memory → Modify tags → Save
- Perfect for 1-3 memories per session
- Full manual control
### See Also
- Scripts located in `scripts/maintenance/` directory
- Dashboard UI at http://127.0.0.1:8000 for manual editing
## Architecture & Codebase Structure
- **Main package**: `src/mcp_memory_service/` - Core MCP server implementation
- **Storage backends**: `storage/` (SQLite-Vec, Cloudflare, Hybrid) implementing abstract `MemoryStorage` class
- **Web interface**: `web/` - FastAPI dashboard with real-time updates via SSE
- **MCP protocol**: `server.py` - Model Context Protocol implementation with async handlers
- **Memory consolidation**: `consolidation/` - Autonomous memory management and deduplication
- **Document ingestion**: `ingestion/` - PDF/DOCX/PPTX loaders with optional semtools integration
- **CLI tools**: `cli/` - Command-line interface for server management
## Code Style Guidelines
- **Imports**: Absolute imports preferred, conditional imports for optional dependencies
- **Types**: Python 3.10+ type hints throughout, TypedDict for MCP responses
- **Async/await**: All I/O operations use async/await pattern
- **Naming**: snake_case for functions/variables, PascalCase for classes, SCREAMING_SNAKE_CASE for constants
- **Error handling**: Try/except blocks with specific exceptions, logging for debugging
- **Memory types**: Use 24 core types from taxonomy (note, reference, session, implementation, etc.)
- **Documentation**: NumPy-style docstrings, CLAUDE.md for project conventions
## Development Rules (from CLAUDE.md)
- Follow MCP protocol specification for tool schemas and responses
- Implement storage backends extending abstract base class
- Use semantic commit messages with conventional commit format
- Test both OAuth enabled/disabled modes for web interface
- Validate search endpoints: semantic, tag-based, time-based queries
