vektori-cortex 1.0.0

package/README.md

@@ -0,0 +1,46 @@
+# Vektori Cortex
+
+Sync your AI coding decisions across Claude, Cursor, and other MCP tools.
+
+## Quick Setup
+
+### 1. Add to Claude Desktop
+
+Open config file:
+- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+- **Mac:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+
+Paste this:
+```json
+{
+  "mcpServers": {
+    "vektori-cortex": {
+      "command": "npx",
+      "args": ["-y", "vektori-cortex"],
+      "env": {
+        "VEKTORI_TOKEN": "YOUR_TOKEN"
+      }
+    }
+  }
+}
+```
+
+### 2. Get Your Token
+
+Copy your JWT from the Vektori browser extension (Settings → Copy Token).
+
+### 3. Restart Claude Desktop
+
+Done. Claude now remembers your decisions across sessions.
+
+---
+
+## What It Does
+
+| You say | Claude does |
+|---------|-------------|
+| "Let's use PostgreSQL" | Saves the decision |
+| "What did we decide about auth?" | Searches your memory |
+| *(new session starts)* | Loads recent context |
+
+Decisions sync across all your MCP tools.

package/dist/api.d.ts

@@ -0,0 +1,9 @@
+import { SaveDecisionRequest, SaveDecisionResponse, SearchMemoryRequest, SearchMemoryResponse, ContextResponse } from "./types.js";
+export declare class VektoriAPI {
+    private token;
+    constructor(token: string);
+    private request;
+    saveDecision(data: SaveDecisionRequest): Promise<SaveDecisionResponse>;
+    searchMemory(data: SearchMemoryRequest): Promise<SearchMemoryResponse>;
+    getContext(projectId?: string, limit?: number): Promise<ContextResponse>;
+}

package/dist/api.js

@@ -0,0 +1,47 @@
+const BASE_URL = "https://vektori-memory.vektori-cloud.workers.dev";
+export class VektoriAPI {
+    token;
+    constructor(token) {
+        this.token = token;
+    }
+    async request(endpoint, options = {}) {
+        const url = `${BASE_URL}${endpoint}`;
+        const response = await fetch(url, {
+            ...options,
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: `Bearer ${this.token}`,
+                ...options.headers,
+            },
+        });
+        if (!response.ok) {
+            const error = await response.text();
+            throw new Error(`API Error ${response.status}: ${error}`);
+        }
+        return response.json();
+    }
+    async saveDecision(data) {
+        return this.request("/api/cortex/save", {
+            method: "POST",
+            body: JSON.stringify(data),
+        });
+    }
+    async searchMemory(data) {
+        return this.request("/api/cortex/search", {
+            method: "POST",
+            body: JSON.stringify(data),
+        });
+    }
+    async getContext(projectId, limit) {
+        const params = new URLSearchParams();
+        if (projectId)
+            params.set("project_id", projectId);
+        if (limit)
+            params.set("limit", limit.toString());
+        const query = params.toString();
+        const endpoint = `/api/cortex/context${query ? `?${query}` : ""}`;
+        return this.request(endpoint, {
+            method: "GET",
+        });
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,223 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { VektoriAPI } from "./api.js";
+// Get auth token from environment
+const VEKTORI_TOKEN = process.env.VEKTORI_TOKEN;
+if (!VEKTORI_TOKEN) {
+    console.error("Error: VEKTORI_TOKEN environment variable is required");
+    process.exit(1);
+}
+const api = new VektoriAPI(VEKTORI_TOKEN);
+// Create MCP server
+const server = new Server({
+    name: "vektori-cortex",
+    version: "1.0.0",
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+// Define available tools
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+        tools: [
+            {
+                name: "save_decision",
+                description: "Save a technical decision or insight to Vektori memory. Use this when the user makes an important architectural choice, picks a technology, or establishes a pattern.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        content: {
+                            type: "string",
+                            description: "The decision in one clear sentence, e.g. 'Use Redis for session caching'",
+                        },
+                        topic: {
+                            type: "string",
+                            description: "Single word topic, e.g. 'caching', 'auth', 'database'",
+                        },
+                        reasoning: {
+                            type: "string",
+                            description: "Brief explanation of why this decision was made",
+                        },
+                        type: {
+                            type: "string",
+                            enum: ["decision", "fact", "insight"],
+                            description: "Type of memory: decision (choice made), fact (established truth), insight (learned observation)",
+                        },
+                        project_id: {
+                            type: "string",
+                            description: "Optional project identifier to scope this decision",
+                        },
+                    },
+                    required: ["content", "topic", "type"],
+                },
+            },
+            {
+                name: "search_memory",
+                description: "Search the user's past decisions, facts, and insights from previous sessions. Use this to recall what was decided before or to check for existing patterns.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        query: {
+                            type: "string",
+                            description: "Natural language search query, e.g. 'authentication decisions'",
+                        },
+                        project_id: {
+                            type: "string",
+                            description: "Optional project ID to scope search",
+                        },
+                        types: {
+                            type: "array",
+                            items: {
+                                type: "string",
+                                enum: ["decision", "fact", "insight"],
+                            },
+                            description: "Filter by memory types",
+                        },
+                        limit: {
+                            type: "number",
+                            description: "Maximum results to return (default 5)",
+                        },
+                    },
+                    required: ["query"],
+                },
+            },
+            {
+                name: "get_context",
+                description: "Get recent decisions and active features for a project. Call this at the start of a session to understand what the user has been working on.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        project_id: {
+                            type: "string",
+                            description: "Project identifier to get context for",
+                        },
+                        limit: {
+                            type: "number",
+                            description: "Maximum number of recent decisions to return",
+                        },
+                    },
+                    required: [],
+                },
+            },
+        ],
+    };
+});
+// Handle tool calls
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    if (!args) {
+        return {
+            content: [{ type: "text", text: "Error: No arguments provided" }],
+            isError: true,
+        };
+    }
+    try {
+        switch (name) {
+            case "save_decision": {
+                const result = await api.saveDecision({
+                    content: args.content,
+                    topic: args.topic,
+                    reasoning: args.reasoning,
+                    type: args.type,
+                    project_id: args.project_id,
+                });
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `✓ Saved ${args.type}: "${args.content}" (ID: ${result.id})`,
+                        },
+                    ],
+                };
+            }
+            case "search_memory": {
+                const result = await api.searchMemory({
+                    query: args.query,
+                    project_id: args.project_id,
+                    types: args.types,
+                    limit: args.limit,
+                });
+                if (result.results.length === 0) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: "No matching memories found.",
+                            },
+                        ],
+                    };
+                }
+                const formatted = result.results
+                    .map((r, i) => `${i + 1}. [${r.topic}] ${r.content}${r.reasoning ? `\n   Reason: ${r.reasoning}` : ""}`)
+                    .join("\n\n");
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Found ${result.results.length} memories:\n\n${formatted}`,
+                        },
+                    ],
+                };
+            }
+            case "get_context": {
+                const result = await api.getContext(args.project_id, args.limit);
+                let text = `Project: ${result.project_id || "default"}\n\n`;
+                if (result.warnings.length > 0) {
+                    text += `⚠️ Warnings:\n${result.warnings.map((w) => `- ${w}`).join("\n")}\n\n`;
+                }
+                if (result.active_features.length > 0) {
+                    text += `Active Features:\n`;
+                    text += result.active_features
+                        .map((f) => `- ${f.name} (${f.status})`)
+                        .join("\n");
+                    text += "\n\n";
+                }
+                if (result.recent_decisions.length > 0) {
+                    text += `Recent Decisions:\n`;
+                    text += result.recent_decisions
+                        .map((d) => `- [${d.topic}] ${d.decision}`)
+                        .join("\n");
+                }
+                if (result.active_features.length === 0 &&
+                    result.recent_decisions.length === 0) {
+                    text += "No context available yet for this project.";
+                }
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text,
+                        },
+                    ],
+                };
+            }
+            default:
+                throw new Error(`Unknown tool: ${name}`);
+        }
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Error: ${message}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+// Start server
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("Vektori Cortex MCP server running");
+}
+main().catch((error) => {
+    console.error("Fatal error:", error);
+    process.exit(1);
+});

package/dist/types.d.ts

@@ -0,0 +1,51 @@
+export interface SaveDecisionRequest {
+    content: string;
+    topic: string;
+    reasoning?: string;
+    type: "decision" | "fact" | "insight";
+    project_id?: string;
+}
+export interface SaveDecisionResponse {
+    success: boolean;
+    id: string;
+    message: string;
+}
+export interface SearchMemoryRequest {
+    query: string;
+    project_id?: string;
+    types?: ("decision" | "fact" | "insight")[];
+    limit?: number;
+}
+export interface SearchResult {
+    id: string;
+    content: string;
+    topic: string;
+    reasoning?: string;
+    score: number;
+    created_at: string;
+}
+export interface SearchMemoryResponse {
+    results: SearchResult[];
+}
+export interface Decision {
+    topic: string;
+    decision: string;
+    reasoning?: string;
+    created_at: string;
+}
+export interface ActiveFeature {
+    name: string;
+    status: "planning" | "in_progress" | "completed" | "abandoned";
+    files?: string[];
+    last_updated: string;
+}
+export interface ContextResponse {
+    project_id: string;
+    recent_decisions: Decision[];
+    active_features: ActiveFeature[];
+    warnings: string[];
+}
+export interface ApiError {
+    error: string;
+    message: string;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "vektori-cortex",
+  "version": "1.0.0",
+  "description": "MCP server for syncing AI coding decisions across tools",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "vektori-cortex": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "vektori",
+    "ai",
+    "memory",
+    "claude",
+    "cursor",
+    "context"
+  ],
+  "author": "Vektori",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vektori-ai/vektori-cortex"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "@qdrant/js-client-rest": "^1.9.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "tsx": "^4.7.0",
+    "typescript": "^5.3.0"
+  }
+}