@ekkos/mcp-server 1.0.0 → 1.2.1

package/CHANGELOG.md

@@ -0,0 +1,136 @@
+# Changelog
+
+All notable changes to the ekkOS Memory MCP Server will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.1.0] - 2025-12-07
+
+### Added
+
+- **Fallback Mechanism**: Direct Supabase queries when unified-context API fails
+- **Improved Error Handling**: Better resilience for API connection issues
+- **Enhanced Logging**: More detailed error messages and debugging output
+
+### Changed
+
+- **API Integration**: Now uses unified-context API as primary path
+- **Response Format**: Improved transformation of unified-context responses to MCP format
+- **Tool Reliability**: Better handling of partial failures
+
+### Fixed
+
+- **Connection Issues**: Fallback ensures tools remain functional even if API is down
+- **Error Propagation**: Better error messages for debugging
+
+## [1.0.0] - 2025-12-05
+
+### Added
+
+- Initial release of ekkOS Memory MCP Server
+- MCP Protocol 2025-06-18 support
+- Tools:
+  - `search_memory` - Query all memory layers
+  - `get_context` - Get unified context
+  - `capture_event` - Store learning episodes
+  - `forge_pattern` - Create new patterns
+  - `track_application` - Track pattern usage
+  - `record_outcome` - Record pattern outcomes
+  - `get_memory_stats` - Get system statistics
+- HTTP/SSE transport support
+- Cloud deployment support
+
+---
+
+## Version History
+
+- `1.1.0` - Improved reliability with fallback mechanisms
+- `1.0.0` - Initial release
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+

package/PUBLISH.md

@@ -0,0 +1,125 @@
+# Publishing @ekkos/mcp-server to npm
+
+## Pre-Publish Checklist
+
+- [x] Package renamed to @ekkos/mcp-server
+- [x] Version updated to 1.2.0
+- [x] Built successfully
+- [x] README updated
+- [ ] npm login completed
+- [ ] Published to npm
+- [ ] Tested with npx
+
+## Publishing Steps
+
+### 1. Login to npm
+
+```bash
+cd /Volumes/MacMiniPort/DEV/EKKOS/mcp-servers/ekkos-memory
+npm login
+```
+
+**Note:** You'll need to authenticate via browser. npm will open a login page.
+
+### 2. Publish Package
+
+```bash
+npm publish --access public
+```
+
+**Important:** Scoped packages (@ekkos/*) default to private. Use `--access public` to make it publicly available.
+
+### 3. Verify Publication
+
+```bash
+npm view @ekkos/mcp-server
+```
+
+Should show version 1.2.0 and package details.
+
+### 4. Test with npx
+
+```bash
+npx -y @ekkos/mcp-server
+```
+
+Should download and start the server (will fail without env vars, but that's expected).
+
+## Post-Publish
+
+### Update Documentation
+
+- [ ] Update Windsurf integration guide
+- [ ] Update Cursor integration guide  
+- [ ] Update platform dashboard wizard
+- [ ] Add to ekkOS Connect extension templates
+
+### Test Configurations
+
+**Windsurf:**
+```json
+{
+  "mcpServers": {
+    "ekkos-memory": {
+      "command": "npx",
+      "args": ["-y", "@ekkos/mcp-server"],
+      "env": {
+        "EKKOS_API_KEY": "test_key",
+        "EKKOS_USER_ID": "test_user"
+      }
+    }
+  }
+}
+```
+
+**Cursor:**
+```json
+{
+  "mcpServers": {
+    "ekkos-memory": {
+      "command": "npx",
+      "args": ["-y", "@ekkos/mcp-server"],
+      "env": {
+        "EKKOS_API_KEY": "test_key",
+        "EKKOS_USER_ID": "test_user"
+      }
+    }
+  }
+}
+```
+
+## Troubleshooting
+
+**"npm ERR! 402 Payment Required"**
+- Scoped packages require paid account OR use `--access public`
+
+**"npm ERR! 403 Forbidden"**
+- Package name already taken
+- Try alternate name or check npm account permissions
+
+**"npm ERR! E401 Unauthorized"**
+- Run `npm login` again
+- Verify npm account is active
+
+## Package Contents
+
+Verify what's included:
+```bash
+npm pack --dry-run
+```
+
+Should include:
+- build/index.js (compiled server)
+- package.json
+- README.md
+- tsconfig.json
+
+Should NOT include:
+- node_modules/
+- src/ (only build artifacts)
+- .git/
+
+---
+
+**Status:** Ready to publish  
+**Waiting for:** npm login completion

package/README.md

@@ -1,123 +1,231 @@
-# @ekkos/mcp-server
+# Echo Memory MCP Server
 
-Stdio-to-SSE bridge for [ekkOS](https://ekkos.dev) Memory substrate. Enables AI tools like Claude Code and Cursor to access your persistent memory via the Model Context Protocol (MCP).
+Provides Claude (in Cursor) with direct access to Echo's memory systems.
 
-## Quick Start
+## What This Does
 
-### Claude Code
+Bridges the gap between Echo's built memory infrastructure and AI agent access during conversations.
 
-Add to `~/.claude/settings.json`:
+### Memory Systems Exposed
 
-```json
-{
-  "mcpServers": {
-    "ekkos-memory": {
-      "command": "npx",
-      "args": ["-y", "@ekkos/mcp-server"],
-      "env": {
-        "EKKOS_API_KEY": "your_api_key_here"
-      }
-    }
-  }
-}
+1. **Semantic Search** (REFLEX_LOG.md patterns)
+   - Fast BM25 + embedding search
+   - Proven patterns and solutions
+   - Implementation examples
+
+2. **Knowledge Graph** (Graphiti/Neo4j)
+   - Permanent preferences
+   - Established patterns  
+   - Semantic relationships
+   - Forever memory
+
+3. **Recent Signals** (asi_signals table)
+   - User corrections
+   - Pattern applications
+   - Recent failures
+   - Last 72h activity
+
+4. **Auto-Scan Directives**
+   - MUST/NEVER/PREFER/AVOID rules
+   - Derived from both short-term + long-term memory
+   - Updated in real-time
+
+## Tools Available
+
+### `search_memory`
+Search all memory systems at once.
+
+```typescript
+search_memory({
+  query: "auth loop fix",
+  limit: 10,
+  sources: ["all"] // or ["patterns", "graph", "signals"]
+})
+```
+
+**Returns**: Combined results from patterns, knowledge graph, and signals.
+
+### `get_directives`
+Get current behavioral directives from auto-scan.
+
+```typescript
+get_directives({
+  userId: "system",
+  windowHours: 72
+})
+```
+
+**Returns**: MUST/NEVER/PREFER/AVOID + permanent knowledge + hot patterns.
+
+### `recall_pattern`
+Get full details on a specific pattern.
+
+```typescript
+recall_pattern({
+  pattern: "auth-timeout-mitigation"
+})
 ```
 
-### Cursor
+**Returns**: Pattern description, implementation, examples, success rate.
+
+### `query_signals`
+Query recent learning signals by type.
+
+```typescript
+query_signals({
+  signalType: "user_correction_observed",
+  hours: 24,
+  limit: 20
+})
+```
 
-Add to `.cursor/mcp.json` in your project:
+**Returns**: Recent signals of the specified type.
+
+### `search_knowledge_graph`
+Search Graphiti knowledge graph directly.
+
+```typescript
+search_knowledge_graph({
+  query: "gateway routing preference",
+  searchType: "nodes", // or "facts" or "both"
+  limit: 10
+})
+```
+
+**Returns**: Semantic nodes/facts from permanent memory.
+
+## Installation
+
+### 1. Install Dependencies
+
+```bash
+cd mcp-servers/echo-memory
+npm install
+npm run build
+```
+
+### 2. Configure Cursor
+
+Add to your Cursor settings (`.cursor/mcp_settings.json` or global settings):
 
 ```json
 {
   "mcpServers": {
-    "ekkos-memory": {
-      "command": "npx",
-      "args": ["-y", "@ekkos/mcp-server"],
+    "echo-memory": {
+      "command": "node",
+      "args": [
+        "/Volumes/MacMiniPort/DEV/echo/mcp-servers/echo-memory/build/index.js"
+      ],
       "env": {
-        "EKKOS_API_KEY": "your_api_key_here"
+        "ECHO_API_URL": "http://localhost:3000",
+        "ECHO_API_KEY": "your-api-key-here"
       }
     }
   }
 }
 ```
 
-### Get Your API Key
+### 3. Restart Cursor
+
+The MCP server will be available in all Cursor chat sessions.
+
+## Usage in Cursor
+
+Once configured, Claude can use these tools during conversations:
+
+```
+You: "How did we fix the auth timeout issue?"
+
+Claude: [Calls search_memory("auth timeout fix")]
+        "Found it! We used the auth-timeout-mitigation pattern
+         from Oct 15. Here's the solution..."
+```
 
-1. Go to [platform.ekkos.dev](https://platform.ekkos.dev)
-2. Sign up or log in
-3. Navigate to **Settings → API Keys**
-4. Click **"Generate New Key"**
+**Instant pattern recall** during active development! ⚡
 
-## Environment Variables
+## Configuration
 
-| Variable | Required | Description |
-|----------|----------|-------------|
-| `EKKOS_API_KEY` | ✅ Yes | Your ekkOS API key from platform.ekkos.dev |
-| `EKKOS_USER_ID` | ❌ No | Your user ID (optional, for better tracking) |
-| `EKKOS_MCP_URL` | ❌ No | Custom MCP gateway URL (default: https://mcp.ekkos.dev/api/v1/mcp/sse) |
-| `EKKOS_DEBUG` | ❌ No | Set to `true` for debug logs |
+### Environment Variables
 
-## How It Works
+- `ECHO_API_URL`: Echo API base URL (default: `http://localhost:3000`)
+- `ECHO_API_KEY`: API key for authentication (optional, for production)
 
-This package creates a bridge between:
-- **Stdio transport** (used by AI tools like Claude Code)
-- **SSE transport** (used by ekkOS cloud memory substrate)
+### Development
 
-When your AI tool starts the MCP server, this bridge:
-1. Connects to ekkOS cloud via SSE using your API key
-2. Exposes a stdio interface for your AI tool
-3. Forwards all MCP messages between stdio and SSE
-4. Handles authentication, reconnection, and error handling
+```bash
+# Watch mode (rebuilds on changes)
+npm run watch
 
-## Available Memory Tools
+# Test the server
+node build/index.js
+```
 
-Once connected, your AI will have access to these ekkOS memory tools:
+## Architecture
 
-### The 5 Verbs
-- `ekko` - Search memory for patterns and solutions
-- `crystallize` - Save important decisions permanently
-- `reflex` - Validate suggestions against your history
-- `trace` - Explain why a suggestion was made
-- `consolidate` - Get summary of recent memory activity
+```
+┌─────────────────────────────────────────────────────────┐
+│  Claude in Cursor                                       │
+└───────────────────┬─────────────────────────────────────┘
+                    ↓
+┌─────────────────────────────────────────────────────────┐
+│  Echo Memory MCP Server                                 │
+│    • search_memory                                      │
+│    • get_directives                                     │
+│    • recall_pattern                                     │
+│    • query_signals                                      │
+│    • search_knowledge_graph                             │
+└───────────────────┬─────────────────────────────────────┘
+                    ↓
+┌─────────────────────────────────────────────────────────┐
+│  Echo API (localhost:3000)                              │
+│    ├─ /api/asi/semantic-search (REFLEX_LOG)           │
+│    ├─ /api/asi/scan (Auto-Scan)                       │
+│    ├─ /api/graphiti (Knowledge Graph)                 │
+│    └─ /api/asi/log-signal (Signals)                   │
+└───────────────────┬─────────────────────────────────────┘
+                    ↓
+┌─────────────────────────────────────────────────────────┐
+│  Memory Stores                                          │
+│    ├─ REFLEX_LOG.md (Patterns)                        │
+│    ├─ Supabase asi_signals (Short-term, 72h)          │
+│    └─ Graphiti/Neo4j (Long-term, forever)             │
+└─────────────────────────────────────────────────────────┘
+```
 
-### Core Operations
-- `search_memory` - Search across all 10 memory layers
-- `forge_pattern` - Create new patterns from learnings
-- `forge_directive` - Set MUST/NEVER/PREFER/AVOID rules
-- `get_context` - Get relevant context for a task
-- `recall_conversation` - Recall what was discussed at a specific time
-- `search_codebase` - Search project code embeddings
+## Why This Matters
 
-### Golden Loop Tracking
-- `track_application` - Track when memories are applied
-- `record_outcome` - Record if applied memories helped
-- `detect_usage` - Auto-detect pattern usage via semantic similarity
-- `check_conflict` - Check for conflicts with directives
+### Before (Memory Exists But Not Accessible)
 
-[See full MCP tools reference](https://docs.ekkos.dev/api-reference/mcp-tools)
+```
+User: "Fix this auth bug"
+Claude: "Let me implement a solution..."
+         [Might repeat past mistakes]
+         [Might not use proven patterns]
+```
 
-## Troubleshooting
+### After (Memory Accessible via MCP)
 
-### "EKKOS_API_KEY environment variable is required"
-You need to set your API key in the MCP config. Get one at [platform.ekkos.dev](https://platform.ekkos.dev/dashboard/settings/api-keys).
+```
+User: "Fix this auth bug"
+Claude: [search_memory("auth fix")]
+        "Found 3 proven solutions from past work!
+         Applying the highest-success pattern..."
+         [Uses established solution instantly] ✅
+```
 
-### MCP server not loading
-1. Check Node.js version: `node --version` (must be 18+)
-2. Verify config JSON is valid
-3. Try running manually: `EKKOS_API_KEY=xxx npx @ekkos/mcp-server`
-4. Enable debug mode: `EKKOS_DEBUG=true` in env
+**Result**: Claude has persistent memory across sessions! 🧠♾️
 
-### Connection errors
-1. Check your internet connection
-2. Verify API key is correct and active
-3. Check https://status.ekkos.dev for service status
+## Next Steps
 
-## Support
+1. ✅ Build MCP server (done)
+2. Configure in Cursor
+3. Test memory queries
+4. Add signal GET endpoint for full signal querying
+5. Add caching for frequently accessed patterns
 
-- 📚 [Documentation](https://docs.ekkos.dev)
-- 💬 [Discord Community](https://discord.gg/ekkos)
-- 🐛 [Report Issues](https://github.com/ekkos-ai/ekkos/issues)
-- 📧 [Email Support](mailto:support@ekkos.dev)
+## Related
 
-## License
+- Two-Tier Memory Architecture: `/TWO_TIER_MEMORY.md`
+- Auto-Scan Implementation: `/apps/web/app/lib/asi/autoScan.ts`
+- Memory Problem Documentation: `/THE_MEMORY_PROBLEM.md`
 
-MIT License - see [LICENSE](LICENSE) for details

package/build/index.d.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+/**
+ * Echo Memory MCP Server
+ *
+ * Provides Claude (in Cursor) with direct access to Echo's memory systems:
+ * - Semantic search of patterns (REFLEX_LOG.md)
+ * - Knowledge graph queries (Graphiti)
+ * - Recent signals (asi_signals)
+ * - Auto-scan directives
+ *
+ * This bridges the gap between built infrastructure and AI access.
+ */
+export {};