@ekkos/mcp-server 1.0.0 → 1.2.2

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,12 +1,29 @@
-# @ekkos/mcp-server
+# ekkOS™ 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).
+Give your AI agent (Claude, GPT-4, etc.) in Cursor, Windsurf, or VS Code a persistent memory. It remembers solutions, learns from mistakes, and gets smarter over time.
 
 ## Quick Start
 
-### Claude Code
+### 1. Install
 
-Add to `~/.claude/settings.json`:
+```bash
+npm install -g @ekkos/mcp-server
+```
+
+### 2. Get Your API Key
+
+1. Visit https://platform.ekkos.dev
+2. Sign in or create an account
+3. Copy your API key from the dashboard
+4. Copy your User ID from your profile
+
+### 3. Configure Your IDE
+
+**For Cursor:** Add to `~/.cursor/mcp.json`
+
+**For Windsurf:** Add to `~/.codeium/windsurf/mcp_config.json`
+
+**For Claude Code:** Add to `~/.claude_code/mcp.json`
 
 ```json
 {
@@ -15,109 +32,281 @@ Add to `~/.claude/settings.json`:
       "command": "npx",
       "args": ["-y", "@ekkos/mcp-server"],
       "env": {
-        "EKKOS_API_KEY": "your_api_key_here"
+        "EKKOS_API_KEY": "your-api-key-here",
+        "EKKOS_USER_ID": "your-user-id-here"
       }
     }
   }
 }
 ```
 
-### Cursor
+### 4. Restart Your IDE
 
-Add to `.cursor/mcp.json` in your project:
+The MCP server will be available in all chat sessions. Your AI can now remember!
+
+## How It Works
+
+Your AI agent can now access a 10-layer memory system that stores:
+
+- **Patterns** - Proven solutions that worked
+- **Conversations** - Past discussions and problem-solving sessions
+- **Directives** - Rules your AI must follow (MUST/NEVER/PREFER/AVOID)
+- **Codebase** - Semantic search across your project
+- **And more** - Episodic memory, procedural workflows, collective knowledge
+
+When you ask a question, your AI searches this memory first, finds relevant solutions, and applies them automatically.
+
+## Core Tools
+
+### `search_memory` 🔍
+
+**What it does:** Searches all your memory layers to find relevant patterns, solutions, and past conversations.
+
+**When to use:** Your AI calls this automatically before answering technical questions. It's the primary way your AI remembers.
+
+**Example:**
 
-```json
-{
-  "mcpServers": {
-    "ekkos-memory": {
-      "command": "npx",
-      "args": ["-y", "@ekkos/mcp-server"],
-      "env": {
-        "EKKOS_API_KEY": "your_api_key_here"
-      }
-    }
-  }
-}
 ```
+You: "How did we fix the auth timeout issue?"
 
-### Get Your API Key
+AI: [Searches memory automatically]
+    "Found it! We used the auth-timeout-mitigation pattern
+     from last week. 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"**
+**What you get back:**
 
-## Environment Variables
+- Relevant patterns with success rates
+- Past conversations about similar problems
+- Code examples that worked
+- Solutions sorted by how well they worked
 
-| 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 |
+---
 
-## How It Works
+### `forge_pattern` 🔥
+
+**What it does:** Saves a solution that worked as a reusable pattern. Future AI agents (including yourself) will find it automatically.
+
+**When to use:** After you solve a problem, fix a bug, or discover a better approach. Your AI should call this automatically, but you can also trigger it.
+
+**Example:**
+
+```
+AI: [After fixing a bug]
+    "I've saved this solution as a pattern. Next time we
+     encounter this issue, I'll remember the fix instantly."
+```
+
+**What happens:**
+
+- Pattern is stored in memory
+- Becomes searchable immediately
+- Success rate tracked over time
+- Automatically suggested for similar problems
+
+---
+
+### `forge_directive` 📜
+
+**What it does:** Creates a rule your AI must follow. These are MUST/NEVER/PREFER/AVOID rules that guide behavior.
+
+**When to use:** When you want to establish permanent rules for how your AI should behave.
+
+**Example:**
+
+```
+You: "Always use TypeScript strict mode"
+
+AI: [Creates directive]
+    "Rule saved. I'll always use strict mode going forward."
+```
+
+**Types of rules:**
+
+- **MUST** - Always do this (highest priority)
+- **NEVER** - Never do this (high priority)
+- **PREFER** - Prefer this approach (medium priority)
+- **AVOID** - Try to avoid this (lower priority)
+
+**What happens:**
+
+- Rule is enforced in all future interactions
+- AI checks against rules before taking actions
+- Rules can be project-specific or global
+
+---
+
+### `recall_conversation` 💬
+
+**What it does:** Finds past conversations about a topic, even from days or weeks ago.
+
+**When to use:** When you want to remember what you discussed before, or check if you've already solved a problem.
+
+**Example:**
 
-This package creates a bridge between:
-- **Stdio transport** (used by AI tools like Claude Code)
-- **SSE transport** (used by ekkOS cloud memory substrate)
+```
+You: "What did we decide about the database schema?"
+
+AI: [Searches past conversations]
+    "We discussed this 2 weeks ago. You decided to use
+     PostgreSQL with JSONB for flexible fields..."
+```
+
+**What you get back:**
+
+- Relevant excerpts from past conversations
+- Context about decisions made
+- Solutions you've tried before
+- Semantic matches (finds related topics, not just keywords)
+
+---
+
+### `check_conflict` ⚖️
+
+**What it does:** Validates an action against your rules and patterns before executing it. Prevents your AI from doing something that violates your preferences.
+
+**When to use:** Before executing destructive operations, deploying changes, or modifying critical configs.
+
+**Example:**
+
+```
+AI: [Before deleting files]
+    "I want to delete /tmp files. Let me check if this
+     violates any rules..."
+
+    [Checks conflicts]
+    "⚠️ CONFLICT: This violates NEVER rule: 'Never delete
+     files without user confirmation'. I'll ask first."
+```
+
+**What you get back:**
+
+- List of violated rules (if any)
+- Conflicting patterns
+- Recommendations to proceed safely
+- Clear explanation of why it conflicts
+
+---
+
+## How to Use It Day-to-Day
+
+### When Starting Work
+
+Your AI automatically searches memory when you ask questions. You don't need to do anything special - just ask:
+
+```
+You: "Fix the authentication bug"
+AI: [Searches memory] "Found 3 solutions from past work..."
+```
+
+### When Solving Problems
+
+After your AI solves something, it should automatically save it as a pattern:
+
+```
+AI: [After fixing bug]
+    "Solution saved. Future agents will find this automatically."
+```
 
-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
+If it doesn't, you can remind it:
 
-## Available Memory Tools
+```
+You: "Save this solution as a pattern"
+```
+
+### When Setting Rules
+
+Tell your AI what you want it to always/never do:
+
+```
+You: "Never use `any` type in TypeScript"
+AI: [Creates directive] "Rule saved. I'll avoid `any` going forward."
+```
 
-Once connected, your AI will have access to these ekkOS memory tools:
+### When Checking Past Work
 
-### 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
+Ask about past conversations:
 
-### 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
+```
+You: "What did we decide about the API structure?"
+AI: [Searches conversations] "We discussed this last week..."
+```
+
+## The Golden Loop
+
+ekkOS uses a continuous learning cycle that makes your AI smarter:
 
-### 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
+1. **Retrieve** - `search_memory` finds relevant patterns
+2. **Apply** - AI uses patterns to solve problems
+3. **Measure** - System tracks if solutions worked
+4. **Learn** - `forge_pattern` saves new solutions
 
-[See full MCP tools reference](https://docs.ekkos.dev/api-reference/mcp-tools)
+This creates a self-improving system. Every problem solved makes future problems easier.
 
 ## Troubleshooting
 
-### "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).
+### MCP Server Not Appearing
+
+- Make sure Node.js 18+ is installed
+- Check your API key is correct in the config file
+- Restart your IDE after adding the config
+- Check IDE logs for connection errors
+
+### No Patterns Found
+
+- You need to forge some patterns first (solve problems and save them)
+- Check your API key has access to your memory
+- Make sure `EKKOS_USER_ID` is set for user-scoped patterns
 
-### 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
+### Authentication Errors
 
-### Connection errors
-1. Check your internet connection
-2. Verify API key is correct and active
-3. Check https://status.ekkos.dev for service status
+- Verify your API key at https://platform.ekkos.dev
+- Check the key hasn't expired
+- Make sure the key has correct permissions
 
-## Support
+## What Gets Stored
 
-- 📚 [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)
+Your memory includes:
+
+- **Patterns** - Solutions that worked, with success rates
+- **Conversations** - Past discussions, searchable semantically
+- **Directives** - Rules your AI follows (MUST/NEVER/PREFER/AVOID)
+- **Codebase** - Semantic search across your project files
+- **Episodic** - Problem-solving sessions and workflows
+- **Procedural** - Step-by-step processes that worked
+- **Collective** - Knowledge shared across AI agents
+- **Code** - Code embeddings for finding similar code
+
+All of this is searchable instantly when your AI needs it.
+
+## Example Workflow
+
+```
+1. You: "Fix the login bug"
+
+2. AI: [Calls search_memory("login bug fix")]
+    "Found 2 patterns from past work. Applying the
+     highest-success solution..."
+
+3. AI: [Fixes bug using pattern]
+    "Fixed! This solution has worked 8 times before."
+
+4. AI: [Calls forge_pattern automatically]
+    "Saved this fix as a pattern for next time."
+
+5. Next time: AI remembers instantly and applies the fix
+```
+
+## Related
+
+- **Platform Dashboard**: https://platform.ekkos.dev
+- **Documentation**: https://docs.ekkos.dev
+- **GitHub**: https://github.com/ekkos-ai/ekkos
 
 ## License
 
-MIT License - see [LICENSE](LICENSE) for details
+MIT
+
+---
+
+**ekkOS™** - The memory substrate for AI agents. Making AI smarter, one pattern at a time. 🧠♾️

package/build/index.d.ts

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+/**
+ * ekkOS™ Memory MCP Server
+ *
+ * Provides AI agents (Claude, GPT-4, etc.) in Cursor, Windsurf, VS Code, and Claude Code
+ * with direct access to ekkOS's 10-layer memory architecture:
+ * - Layer 1-10 memory systems (working, episodic, semantic, patterns, procedural, collective, meta, codebase, directives, conflicts)
+ * - Unified context retrieval via Memory Orchestrator
+ * - Pattern search and forging (Golden Loop)
+ * - Knowledge graph queries (Graphiti/Neo4j)
+ * - Behavioral directives (MUST/NEVER/PREFER/AVOID)
+ *
+ * This bridges the gap between ekkOS's built memory infrastructure and AI agent access.
+ */
+export {};