Mnemosyne MCP

# Phase 1: Token Optimization Results ## Overview Optimized the `list_graphs` MCP tool for maximum token efficiency while preserving essential information for the AI model. ## Implementation ### Created Utilities 1. **`src/neem/mcp/utils/response_filters.py`** - `filter_graph_list()` - Reduces graph list from 10 fields to 5 essential fields - `filter_graph_metadata()` - Flexible filtering for individual graphs - `filter_job_status()` - Strips verbose job metadata - `extract_result_from_job_detail()` - Extracts inline results - `filter_query_results()` - For future SPARQL query optimization 2. **`src/neem/mcp/utils/token_utils.py`** - `render_compact_json()` - Zero-whitespace JSON (use for all data responses) - `render_pretty_json()` - Human-readable JSON (use only for errors) - `estimate_tokens()` - Rough token estimation (1 token ≈ 4 chars) ### Updated Tool - **`list_graphs`** in `src/neem/mcp/tools/basic.py` - Now returns only essential fields: `graph_id`, `title`, `status`, `triple_count`, `updated_at` - Uses compact JSON rendering (no whitespace) - Logs token savings to stderr for monitoring - Pretty-prints only error responses for readability ## Token Reduction Results ### Benchmark (2 graphs) ``` Raw API Response (10 fields): - Pretty JSON: 796 chars, ~199 tokens - Compact JSON: 663 chars, ~165 tokens Filtered Response (5 fields): - Pretty JSON: 322 chars, ~80 tokens - Compact JSON: 249 chars, ~62 tokens Optimized MCP Response: - Compact JSON: 270 chars, ~67 tokens ``` ### Savings - **62.4% token reduction** (165 → 67 tokens) - **~52 tokens saved per graph** - **~414 fewer characters** transmitted ### Scaling With 10 graphs: - Before: ~825 tokens - After: ~335 tokens - **Savings: ~490 tokens** (59% reduction) With 100 graphs: - Before: ~8,250 tokens - After: ~3,350 tokens - **Savings: ~4,900 tokens** (59% reduction) ## Design Principles Applied ### ✅ Field Filtering Removed 5 unnecessary fields per graph: - `graph_uri` (redundant URN, ID is sufficient) - `description` (moved to verbose mode only) - `created_at` (keep `updated_at` for recency) - `last_query_at` (internal metadata) - `last_update_at` (redundant with `updated_at`) ### ✅ Compact JSON Rendering - No whitespace (`separators=(',', ':')`) - No key sorting (preserves insertion order for consistency) - UTF-8 encoding without escape sequences ### ✅ Progressive Detail - List operations: minimal fields (token-efficient) - Error responses: pretty-printed (human-readable) - Future: verbose flag for detailed queries ### ✅ Observability - Logs token savings to stderr - Tracks reduction percentage - Monitors graph count ## Next Steps (Phase 2) Add core query tools: - `query_graph(sparql, max_results)` - Execute SPARQL with result filtering - `update_graph(sparql)` - SPARQL INSERT/DELETE operations - `manage_graph(graph_id, action)` - Polymorphic graph management Estimated additional token savings: 40-70% per response across all tools. ## Files Changed - `src/neem/mcp/utils/__init__.py` (new) - `src/neem/mcp/utils/response_filters.py` (new) - `src/neem/mcp/utils/token_utils.py` (new) - `src/neem/mcp/tools/basic.py` (updated) ## Testing Run `uv run python /tmp/test_filters.py` to verify optimization benchmarks.