@ekkos/mcp-server 1.2.1 → 1.2.2

package/README.md

@@ -1,231 +1,312 @@
-# Echo Memory MCP Server
+# ekkOS™ Memory MCP Server
 
-Provides Claude (in Cursor) with direct access to Echo's memory systems.
+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.
 
-## What This Does
+## Quick Start
 
-Bridges the gap between Echo's built memory infrastructure and AI agent access during conversations.
+### 1. Install
 
-### Memory Systems Exposed
+```bash
+npm install -g @ekkos/mcp-server
+```
 
-1. **Semantic Search** (REFLEX_LOG.md patterns)
-   - Fast BM25 + embedding search
-   - Proven patterns and solutions
-   - Implementation examples
+### 2. Get Your API Key
 
-2. **Knowledge Graph** (Graphiti/Neo4j)
-   - Permanent preferences
-   - Established patterns  
-   - Semantic relationships
-   - Forever memory
+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. **Recent Signals** (asi_signals table)
-   - User corrections
-   - Pattern applications
-   - Recent failures
-   - Last 72h activity
+### 3. Configure Your IDE
 
-4. **Auto-Scan Directives**
-   - MUST/NEVER/PREFER/AVOID rules
-   - Derived from both short-term + long-term memory
-   - Updated in real-time
+**For Cursor:** Add to `~/.cursor/mcp.json`
 
-## Tools Available
+**For Windsurf:** Add to `~/.codeium/windsurf/mcp_config.json`
 
-### `search_memory`
-Search all memory systems at once.
+**For Claude Code:** Add to `~/.claude_code/mcp.json`
 
-```typescript
-search_memory({
-  query: "auth loop fix",
-  limit: 10,
-  sources: ["all"] // or ["patterns", "graph", "signals"]
-})
+```json
+{
+  "mcpServers": {
+    "ekkos-memory": {
+      "command": "npx",
+      "args": ["-y", "@ekkos/mcp-server"],
+      "env": {
+        "EKKOS_API_KEY": "your-api-key-here",
+        "EKKOS_USER_ID": "your-user-id-here"
+      }
+    }
+  }
+}
 ```
 
-**Returns**: Combined results from patterns, knowledge graph, and signals.
+### 4. Restart Your IDE
 
-### `get_directives`
-Get current behavioral directives from auto-scan.
+The MCP server will be available in all chat sessions. Your AI can now remember!
 
-```typescript
-get_directives({
-  userId: "system",
-  windowHours: 72
-})
-```
+## How It Works
 
-**Returns**: MUST/NEVER/PREFER/AVOID + permanent knowledge + hot patterns.
+Your AI agent can now access a 10-layer memory system that stores:
 
-### `recall_pattern`
-Get full details on a specific pattern.
+- **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
 
-```typescript
-recall_pattern({
-  pattern: "auth-timeout-mitigation"
-})
-```
+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.
 
-**Returns**: Pattern description, implementation, examples, success rate.
+**Example:**
 
-### `query_signals`
-Query recent learning signals by type.
+```
+You: "How did we fix the auth timeout issue?"
 
-```typescript
-query_signals({
-  signalType: "user_correction_observed",
-  hours: 24,
-  limit: 20
-})
+AI: [Searches memory automatically]
+    "Found it! We used the auth-timeout-mitigation pattern
+     from last week. Here's the solution..."
 ```
 
-**Returns**: Recent signals of the specified type.
+**What you get back:**
+
+- Relevant patterns with success rates
+- Past conversations about similar problems
+- Code examples that worked
+- Solutions sorted by how well they worked
+
+---
+
+### `forge_pattern` 🔥
 
-### `search_knowledge_graph`
-Search Graphiti knowledge graph directly.
+**What it does:** Saves a solution that worked as a reusable pattern. Future AI agents (including yourself) will find it automatically.
 
-```typescript
-search_knowledge_graph({
-  query: "gateway routing preference",
-  searchType: "nodes", // or "facts" or "both"
-  limit: 10
-})
+**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."
 ```
 
-**Returns**: Semantic nodes/facts from permanent memory.
+**What happens:**
 
-## Installation
+- Pattern is stored in memory
+- Becomes searchable immediately
+- Success rate tracked over time
+- Automatically suggested for similar problems
 
-### 1. Install Dependencies
+---
+
+### `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:**
 
-```bash
-cd mcp-servers/echo-memory
-npm install
-npm run build
 ```
+You: "Always use TypeScript strict mode"
 
-### 2. Configure Cursor
+AI: [Creates directive]
+    "Rule saved. I'll always use strict mode going forward."
+```
 
-Add to your Cursor settings (`.cursor/mcp_settings.json` or global settings):
+**Types of rules:**
 
-```json
-{
-  "mcpServers": {
-    "echo-memory": {
-      "command": "node",
-      "args": [
-        "/Volumes/MacMiniPort/DEV/echo/mcp-servers/echo-memory/build/index.js"
-      ],
-      "env": {
-        "ECHO_API_URL": "http://localhost:3000",
-        "ECHO_API_KEY": "your-api-key-here"
-      }
-    }
-  }
-}
+- **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:**
+
+```
+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..."
 ```
 
-### 3. Restart Cursor
+**What you get back:**
 
-The MCP server will be available in all Cursor chat sessions.
+- Relevant excerpts from past conversations
+- Context about decisions made
+- Solutions you've tried before
+- Semantic matches (finds related topics, not just keywords)
 
-## Usage in Cursor
+---
 
-Once configured, Claude can use these tools during conversations:
+### `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:**
 
 ```
-You: "How did we fix the auth timeout issue?"
+AI: [Before deleting files]
+    "I want to delete /tmp files. Let me check if this
+     violates any rules..."
 
-Claude: [Calls search_memory("auth timeout fix")]
-        "Found it! We used the auth-timeout-mitigation pattern
-         from Oct 15. Here's the solution..."
+    [Checks conflicts]
+    "⚠️ CONFLICT: This violates NEVER rule: 'Never delete
+     files without user confirmation'. I'll ask first."
 ```
 
-**Instant pattern recall** during active development! ⚡
+**What you get back:**
 
-## Configuration
+- List of violated rules (if any)
+- Conflicting patterns
+- Recommendations to proceed safely
+- Clear explanation of why it conflicts
 
-### Environment Variables
+---
 
-- `ECHO_API_URL`: Echo API base URL (default: `http://localhost:3000`)
-- `ECHO_API_KEY`: API key for authentication (optional, for production)
+## How to Use It Day-to-Day
 
-### Development
+### When Starting Work
 
-```bash
-# Watch mode (rebuilds on changes)
-npm run watch
+Your AI automatically searches memory when you ask questions. You don't need to do anything special - just ask:
 
-# Test the server
-node build/index.js
+```
+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."
 ```
 
-## Architecture
+If it doesn't, you can remind it:
 
 ```
-┌─────────────────────────────────────────────────────────┐
-│  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)             │
-└─────────────────────────────────────────────────────────┘
+You: "Save this solution as a pattern"
 ```
 
-## Why This Matters
+### When Setting Rules
 
-### Before (Memory Exists But Not Accessible)
+Tell your AI what you want it to always/never do:
 
 ```
-User: "Fix this auth bug"
-Claude: "Let me implement a solution..."
-         [Might repeat past mistakes]
-         [Might not use proven patterns]
+You: "Never use `any` type in TypeScript"
+AI: [Creates directive] "Rule saved. I'll avoid `any` going forward."
 ```
 
-### After (Memory Accessible via MCP)
+### When Checking Past Work
+
+Ask about past conversations:
 
 ```
-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] ✅
+You: "What did we decide about the API structure?"
+AI: [Searches conversations] "We discussed this last week..."
 ```
 
-**Result**: Claude has persistent memory across sessions! 🧠♾️
+## The Golden Loop
+
+ekkOS uses a continuous learning cycle that makes your AI smarter:
+
+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
+
+This creates a self-improving system. Every problem solved makes future problems easier.
 
-## Next Steps
+## Troubleshooting
 
-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
+### 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
+
+### Authentication Errors
+
+- Verify your API key at https://platform.ekkos.dev
+- Check the key hasn't expired
+- Make sure the key has correct permissions
+
+## What Gets Stored
+
+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
 
-- 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`
+- **Platform Dashboard**: https://platform.ekkos.dev
+- **Documentation**: https://docs.ekkos.dev
+- **GitHub**: https://github.com/ekkos-ai/ekkos
+
+## License
+
+MIT
+
+---
 
+**ekkOS™** - The memory substrate for AI agents. Making AI smarter, one pattern at a time. 🧠♾️

package/build/index.d.ts

@@ -1,13 +1,15 @@
 #!/usr/bin/env node
 /**
- * Echo Memory MCP Server
+ * ekkOS™ 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
+ * 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 built infrastructure and AI access.
+ * This bridges the gap between ekkOS's built memory infrastructure and AI agent access.
  */
 export {};

package/build/index.js

@@ -1,14 +1,16 @@
 #!/usr/bin/env node
 /**
- * Echo Memory MCP Server
+ * ekkOS™ 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
+ * 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 built infrastructure and AI access.
+ * This bridges the gap between ekkOS's built memory infrastructure and AI agent access.
  */
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
@@ -34,11 +36,11 @@ const ECHO_API_KEY = process.env.ECHO_API_KEY; // For authentication
 const EKKOS_USER_ID = process.env.EKKOS_USER_ID; // User ID for tracking retrievals
 const EKKOS_API_KEY = process.env.EKKOS_API_KEY; // User's API key
 // Debug: Log configuration on startup (to stderr so it doesn't interfere with MCP protocol)
-console.error(`[MCP:echo-memory] Using DIRECT Supabase connection`);
-console.error(`[MCP:echo-memory] SUPABASE_URL: ${SUPABASE_URL}`);
-console.error(`[MCP:echo-memory] SUPABASE_KEY: ${SUPABASE_KEY ? 'set (' + SUPABASE_KEY.length + ' chars)' : 'NOT SET'}`);
-console.error(`[MCP:echo-memory] EKKOS_USER_ID: ${EKKOS_USER_ID || 'NOT SET (Golden Loop tracking disabled)'}`);
-console.error(`[MCP:echo-memory] EKKOS_API_KEY: ${EKKOS_API_KEY ? 'set' : 'NOT SET'}`);
+console.error(`[MCP:ekkos-memory] Using DIRECT Supabase connection`);
+console.error(`[MCP:ekkos-memory] SUPABASE_URL: ${SUPABASE_URL}`);
+console.error(`[MCP:ekkos-memory] SUPABASE_KEY: ${SUPABASE_KEY ? 'set (' + SUPABASE_KEY.length + ' chars)' : 'NOT SET'}`);
+console.error(`[MCP:ekkos-memory] EKKOS_USER_ID: ${EKKOS_USER_ID || 'NOT SET (Golden Loop tracking disabled)'}`);
+console.error(`[MCP:ekkos-memory] EKKOS_API_KEY: ${EKKOS_API_KEY ? 'set' : 'NOT SET'}`);
 // In-memory store for tracking pattern applications (maps application_id -> pattern_ids)
 // This bridges track_memory_application and record_memory_outcome
 const applicationStore = new Map();
@@ -1774,7 +1776,7 @@ Future agents will find it when facing similar problems.
             case 'get_memory_layer_info': {
                 try {
                     const stats = await fetchMemory('/api/v1/memory/metrics');
-                    const formatted = `**Echo Memory Layer Statistics** (10-Layer Architecture)
+                    const formatted = `**ekkOS Memory Layer Statistics** (10-Layer Architecture)
 
 **Core Memory Layers:**
 - 🧠 Layer 2 (Episodic): ${stats.episodic || 0} episodes
@@ -1831,7 +1833,7 @@ The memory metrics endpoint may not be available. Check that:
 This is ekkOS, the memory substrate for AI agents. 
 
 **Connection Status:** ✅ MCP server is running and responding
-**Server:** echo-memory MCP Server v1.0.0
+**Server:** ekkOS Memory MCP Server v1.2.1
 **Time:** ${new Date().toISOString()}
 
 You've successfully connected to ekkOS via the Model Context Protocol. This proves that:

package/index.ts

@@ -1,14 +1,16 @@
 #!/usr/bin/env node
 /**
- * Echo Memory MCP Server
+ * ekkOS™ 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
+ * 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 built infrastructure and AI access.
+ * This bridges the gap between ekkOS's built memory infrastructure and AI agent access.
  */
 
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
@@ -44,11 +46,11 @@ const EKKOS_USER_ID = process.env.EKKOS_USER_ID; // User ID for tracking retriev
 const EKKOS_API_KEY = process.env.EKKOS_API_KEY; // User's API key
 
 // Debug: Log configuration on startup (to stderr so it doesn't interfere with MCP protocol)
-console.error(`[MCP:echo-memory] Using DIRECT Supabase connection`);
-console.error(`[MCP:echo-memory] SUPABASE_URL: ${SUPABASE_URL}`);
-console.error(`[MCP:echo-memory] SUPABASE_KEY: ${SUPABASE_KEY ? 'set (' + SUPABASE_KEY.length + ' chars)' : 'NOT SET'}`);
-console.error(`[MCP:echo-memory] EKKOS_USER_ID: ${EKKOS_USER_ID || 'NOT SET (Golden Loop tracking disabled)'}`);
-console.error(`[MCP:echo-memory] EKKOS_API_KEY: ${EKKOS_API_KEY ? 'set' : 'NOT SET'}`);
+console.error(`[MCP:ekkos-memory] Using DIRECT Supabase connection`);
+console.error(`[MCP:ekkos-memory] SUPABASE_URL: ${SUPABASE_URL}`);
+console.error(`[MCP:ekkos-memory] SUPABASE_KEY: ${SUPABASE_KEY ? 'set (' + SUPABASE_KEY.length + ' chars)' : 'NOT SET'}`);
+console.error(`[MCP:ekkos-memory] EKKOS_USER_ID: ${EKKOS_USER_ID || 'NOT SET (Golden Loop tracking disabled)'}`);
+console.error(`[MCP:ekkos-memory] EKKOS_API_KEY: ${EKKOS_API_KEY ? 'set' : 'NOT SET'}`);
 
 // In-memory store for tracking pattern applications (maps application_id -> pattern_ids)
 // This bridges track_memory_application and record_memory_outcome
@@ -1897,7 +1899,7 @@ Future agents will find it when facing similar problems.
         try {
           const stats = await fetchMemory('/api/v1/memory/metrics');
 
-          const formatted = `**Echo Memory Layer Statistics** (10-Layer Architecture)
+          const formatted = `**ekkOS Memory Layer Statistics** (10-Layer Architecture)
 
 **Core Memory Layers:**
 - 🧠 Layer 2 (Episodic): ${stats.episodic || 0} episodes
@@ -1955,7 +1957,7 @@ The memory metrics endpoint may not be available. Check that:
 This is ekkOS, the memory substrate for AI agents. 
 
 **Connection Status:** ✅ MCP server is running and responding
-**Server:** echo-memory MCP Server v1.0.0
+**Server:** ekkOS Memory MCP Server v1.2.1
 **Time:** ${new Date().toISOString()}
 
 You've successfully connected to ekkOS via the Model Context Protocol. This proves that:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ekkos/mcp-server",
-  "version": "1.2.1",
+  "version": "1.2.2",
   "description": "ekkOS Memory MCP Server - Universal AI memory across Cursor, Windsurf, VS Code, Claude Code via stdio transport",
   "type": "module",
   "bin": {