cogmemai-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 HiFriendbot
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,158 @@
+# CogmemAi — Cognitive Memory for Claude Code
+
+**Claude Code forgets everything between sessions. CogmemAi fixes that.**
+
+One command. One env var. Claude Code remembers your architecture, patterns, decisions, bugs, and preferences — permanently.
+
+```
+npx -y cogmemai-mcp
+```
+
+## The Problem
+
+Every time you start a new Claude Code session, you lose context. You re-explain your tech stack, your architecture decisions, your coding preferences. Claude Code's built-in memory is a 200-line flat file with no search, no structure, and no intelligence.
+
+CogmemAi gives Claude Code a real memory system:
+
+- **Semantic search** — finds relevant memories by meaning, not keywords
+- **Ai-powered extraction** — automatically identifies facts worth remembering from your conversations
+- **Project scoping** — memories tied to specific repos, plus global preferences that follow you everywhere
+- **Time-aware surfacing** — recent and important memories rank higher
+- **Zero setup** — no databases, no Docker, no Python, no vector stores
+
+## Why Not Local Memory?
+
+Every local memory solution has the same problems: database corruption, memory leaks, version conflicts, complex setup. [claude-mem](https://github.com/nicobailon/claude-mem) (13K+ stars) leaks 15GB+ of RAM. [mcp-memory-service](https://github.com/doobidoo/mcp-memory-service) released v10.0.0 marked "BROKEN."
+
+CogmemAi runs extraction and search server-side. Your MCP server is a thin HTTP client — **zero local databases, zero RAM issues, zero crashes.**
+
+## Quick Start
+
+### 1. Get your API key
+
+Sign up at [hifriendbot.com/developer](https://hifriendbot.com/developer/) and generate an API key.
+
+### 2. Add to Claude Code
+
+Add to your project's `.mcp.json` (or `~/.claude.json` for global):
+
+```json
+{
+  "mcpServers": {
+    "memory": {
+      "command": "npx",
+      "args": ["-y", "cogmemai-mcp"],
+      "env": {
+        "COGMEMAI_API_KEY": "cm_your_api_key_here"
+      }
+    }
+  }
+}
+```
+
+### 3. Done
+
+Claude Code now has persistent memory. It will remember your architecture, preferences, and decisions across every session.
+
+## Tools
+
+CogmemAi provides 8 tools that Claude Code can use automatically:
+
+| Tool | Description |
+|------|-------------|
+| `save_memory` | Store a fact explicitly (architecture decision, preference, etc.) |
+| `recall_memories` | Search memories using natural language (semantic search) |
+| `extract_memories` | Ai extracts facts from a conversation exchange automatically |
+| `get_project_context` | Load all relevant memories at session start |
+| `list_memories` | Browse all memories with filters |
+| `update_memory` | Update a memory's content, importance, or scope |
+| `delete_memory` | Permanently delete a memory |
+| `get_usage` | Check your usage stats and tier info |
+
+## Memory Types
+
+Memories are categorized for better organization and retrieval:
+
+- **identity** — Who you are, your role, team
+- **preference** — Coding style, tool choices, conventions
+- **architecture** — System design, tech stack, file structure
+- **decision** — Why you chose X over Y
+- **bug** — Known issues, fixes, workarounds
+- **dependency** — Version constraints, package notes
+- **pattern** — Reusable patterns, conventions
+- **context** — General project context
+
+## Scoping
+
+- **Project memories** — Architecture, decisions, bugs specific to one repo. Auto-detected from `git remote`.
+- **Global memories** — Your coding preferences, identity, tool choices. Available in every project.
+
+## Pricing
+
+| | Free | Pro | Team |
+|---|---|---|---|
+| **Price** | $0 | $14.99/mo | $39.99/seat/mo |
+| **Memories** | 50 | 2,000 | 10,000 |
+| **Extractions/mo** | 100 | 2,000 | 5,000 |
+| **Projects** | 2 | 20 | 50 + Shared |
+
+Start free. Upgrade when you need more.
+
+## Privacy & Security
+
+- **No source code leaves your machine.** We store extracted facts (short sentences), never raw code.
+- **API keys hashed** with SHA-256 (irreversible) server-side.
+- **All traffic over HTTPS.**
+- **No model training** on your data. Ever.
+- **Delete everything** instantly via dashboard or MCP tool.
+- **No cross-user data sharing.**
+
+Read our full [privacy policy](https://hifriendbot.com/privacy-policy/).
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `COGMEMAI_API_KEY` | Yes | Your API key (starts with `cm_`) |
+| `COGMEMAI_API_URL` | No | Custom API URL (default: hifriendbot.com) |
+
+## How It Works
+
+```
+Your Terminal                          CogmemAi Cloud
+┌──────────────┐                     ┌─────────────────────┐
+│ Claude Code  │                     │ 3-Layer Memory      │
+│              │                     │                     │
+│ cogmemai-mcp │ ──── HTTPS ────►    │ 1. Ai Extraction    │
+│ (MCP Server) │ ◄──── JSON ────    │ 2. Semantic Search  │
+│              │                     │ 3. Time-Aware Rank  │
+└──────────────┘                     └─────────────────────┘
+```
+
+1. **Extraction** — When Claude Code works on your project, CogmemAi's Ai identifies important facts (architecture decisions, preferences, bugs) and stores them.
+2. **Embedding** — Each memory gets a semantic embedding vector for meaning-based search.
+3. **Surfacing** — When you start a new session, relevant memories are surfaced by meaning, importance, and recency.
+
+## Works Everywhere
+
+CogmemAi works in any terminal that runs Claude Code:
+
+- PowerShell
+- bash / zsh
+- Windows Terminal
+- macOS Terminal / iTerm2
+- VS Code terminal
+- Any SSH session
+
+## Support
+
+- Issues: [GitHub Issues](https://github.com/hifriendbot/cogmemai-mcp/issues)
+- Docs: [hifriendbot.com/developer](https://hifriendbot.com/developer/)
+
+## License
+
+MIT — see [LICENSE](./LICENSE)
+
+---
+
+Built by [HiFriendbot](https://hifriendbot.com) — Better Friends, Better Memories, Better Ai.

package/build/api.d.ts

@@ -0,0 +1,7 @@
+/**
+ * CogmemAi API client — thin HTTP wrapper for the HiFriendbot REST API.
+ */
+/**
+ * Make an authenticated API request to the CogmemAi backend.
+ */
+export declare function api(path: string, method?: 'GET' | 'POST' | 'PATCH' | 'DELETE', body?: Record<string, unknown>): Promise<unknown>;

package/build/api.js

@@ -0,0 +1,54 @@
+/**
+ * CogmemAi API client — thin HTTP wrapper for the HiFriendbot REST API.
+ */
+const API_BASE = process.env.COGMEMAI_API_URL?.replace(/\/+$/, '') ||
+    'https://hifriendbot.com/wp-json/hifriendbot/v1';
+const API_KEY = process.env.COGMEMAI_API_KEY || '';
+if (!API_KEY) {
+    console.error('Warning: COGMEMAI_API_KEY not set. Get your key at https://hifriendbot.com/developer/');
+}
+/**
+ * Make an authenticated API request to the CogmemAi backend.
+ */
+export async function api(path, method = 'GET', body) {
+    const url = `${API_BASE}${path}`;
+    const headers = {
+        'Content-Type': 'application/json',
+        'User-Agent': 'CogmemAi-MCP/1.0',
+    };
+    if (API_KEY) {
+        headers['Authorization'] = `Bearer ${API_KEY}`;
+    }
+    const options = { method, headers };
+    if (body && method !== 'GET') {
+        options.body = JSON.stringify(body);
+    }
+    // For GET with query params, append to URL
+    if (body && method === 'GET') {
+        const params = new URLSearchParams();
+        for (const [key, value] of Object.entries(body)) {
+            if (value !== undefined && value !== null && value !== '') {
+                params.set(key, String(value));
+            }
+        }
+        const qs = params.toString();
+        if (qs) {
+            const separator = url.includes('?') ? '&' : '?';
+            const fullUrl = `${url}${separator}${qs}`;
+            const res = await fetch(fullUrl, { method, headers });
+            const data = await res.json();
+            if (!res.ok) {
+                const error = data.error || `HTTP ${res.status}`;
+                throw new Error(error);
+            }
+            return data;
+        }
+    }
+    const res = await fetch(url, options);
+    const data = await res.json();
+    if (!res.ok) {
+        const error = data.error || `HTTP ${res.status}`;
+        throw new Error(error);
+    }
+    return data;
+}

package/build/index.d.ts

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+/**
+ * CogmemAi — Cognitive Memory for Claude Code
+ *
+ * MCP server that gives Claude Code persistent memory across sessions.
+ * Developers install with one command, set one env var, and Claude Code
+ * remembers architecture, patterns, decisions, bugs, and preferences.
+ *
+ * Run: npx -y cogmemai-mcp
+ * Docs: https://hifriendbot.com/developer/
+ */
+export {};

package/build/index.js

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+/**
+ * CogmemAi — Cognitive Memory for Claude Code
+ *
+ * MCP server that gives Claude Code persistent memory across sessions.
+ * Developers install with one command, set one env var, and Claude Code
+ * remembers architecture, patterns, decisions, bugs, and preferences.
+ *
+ * Run: npx -y cogmemai-mcp
+ * Docs: https://hifriendbot.com/developer/
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { registerTools } from './tools.js';
+const server = new McpServer({
+    name: 'cogmemai',
+    version: '1.0.0',
+});
+registerTools(server);
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error('CogmemAi MCP server running on stdio');
+}
+main().catch((err) => {
+    console.error('Fatal:', err);
+    process.exit(1);
+});

package/build/project.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Auto-detect the current project identifier.
+ *
+ * Tries `git remote get-url origin` first (e.g., "user/repo").
+ * Falls back to the current working directory basename.
+ */
+export declare function detectProjectId(): string;

package/build/project.js

@@ -0,0 +1,31 @@
+/**
+ * Auto-detect the current project identifier.
+ *
+ * Tries `git remote get-url origin` first (e.g., "user/repo").
+ * Falls back to the current working directory basename.
+ */
+import { execSync } from 'child_process';
+let cachedProjectId = null;
+export function detectProjectId() {
+    if (cachedProjectId !== null) {
+        return cachedProjectId;
+    }
+    try {
+        const remote = execSync('git remote get-url origin', {
+            encoding: 'utf-8',
+            timeout: 3000,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        }).trim();
+        // Normalize: remove .git suffix, extract org/repo
+        cachedProjectId = remote
+            .replace(/\.git$/, '')
+            .replace(/^https?:\/\/[^/]+\//, '')
+            .replace(/^git@[^:]+:/, '');
+    }
+    catch {
+        // No git remote — use directory name
+        const parts = process.cwd().split(/[\\/]/);
+        cachedProjectId = parts[parts.length - 1] || 'unknown';
+    }
+    return cachedProjectId;
+}

package/build/tools.d.ts

@@ -0,0 +1,8 @@
+/**
+ * CogmemAi MCP tool definitions — 8 tools for developer memory.
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/**
+ * Register all 8 CogmemAi tools on the MCP server.
+ */
+export declare function registerTools(server: McpServer): void;

package/build/tools.js

@@ -0,0 +1,260 @@
+/**
+ * CogmemAi MCP tool definitions — 8 tools for developer memory.
+ */
+import { z } from 'zod';
+import { api } from './api.js';
+import { detectProjectId } from './project.js';
+const MEMORY_TYPES = [
+    'identity',
+    'preference',
+    'architecture',
+    'decision',
+    'bug',
+    'dependency',
+    'pattern',
+    'context',
+];
+const CATEGORIES = [
+    'frontend',
+    'backend',
+    'database',
+    'devops',
+    'testing',
+    'security',
+    'performance',
+    'tooling',
+    'api',
+    'general',
+];
+/**
+ * Register all 8 CogmemAi tools on the MCP server.
+ */
+export function registerTools(server) {
+    // ─── 1. save_memory ──────────────────────────────────────
+    server.tool('save_memory', 'Store a developer memory (fact, preference, decision, architecture detail). Memories persist across all Claude Code sessions and are available in future conversations.', {
+        content: z
+            .string()
+            .min(5)
+            .max(500)
+            .describe('The fact to remember (complete sentence)'),
+        memory_type: z
+            .enum(MEMORY_TYPES)
+            .default('context')
+            .describe('Type: identity, preference, architecture, decision, bug, dependency, pattern, context'),
+        category: z
+            .enum(CATEGORIES)
+            .default('general')
+            .describe('Category: frontend, backend, database, devops, testing, security, performance, tooling, api, general'),
+        subject: z
+            .string()
+            .max(100)
+            .default('')
+            .describe('What this is about, e.g. "auth_system", "react_version", "tab_width"'),
+        importance: z
+            .number()
+            .int()
+            .min(1)
+            .max(10)
+            .default(5)
+            .describe('1-10 (10 = core architecture, 1 = trivial)'),
+        scope: z
+            .enum(['global', 'project'])
+            .default('project')
+            .describe('global = applies everywhere, project = specific to this codebase'),
+    }, async ({ content, memory_type, category, subject, importance, scope }) => {
+        const projectId = detectProjectId();
+        const result = await api('/cogmemai/store', 'POST', {
+            content,
+            memory_type,
+            category,
+            subject,
+            importance,
+            scope,
+            project_id: projectId,
+        });
+        return {
+            content: [
+                { type: 'text', text: JSON.stringify(result, null, 2) },
+            ],
+        };
+    });
+    // ─── 2. recall_memories ──────────────────────────────────
+    server.tool('recall_memories', 'Search stored memories using semantic search. Returns memories ranked by relevance, importance, and recency. Use this to find relevant context from past sessions.', {
+        query: z
+            .string()
+            .min(2)
+            .max(500)
+            .describe('What to search for (natural language)'),
+        scope: z
+            .enum(['global', 'project', 'all'])
+            .default('all')
+            .describe('Filter by scope'),
+        limit: z
+            .number()
+            .int()
+            .min(1)
+            .max(20)
+            .default(10)
+            .describe('Max results'),
+        memory_type: z.enum(MEMORY_TYPES).optional().describe('Filter by type'),
+    }, async ({ query, scope, limit, memory_type }) => {
+        const projectId = detectProjectId();
+        const result = await api('/cogmemai/recall', 'POST', {
+            query,
+            scope,
+            limit,
+            memory_type: memory_type || undefined,
+            project_id: projectId,
+        });
+        return {
+            content: [
+                { type: 'text', text: JSON.stringify(result, null, 2) },
+            ],
+        };
+    });
+    // ─── 3. extract_memories ─────────────────────────────────
+    server.tool('extract_memories', 'Extract memories from a conversation exchange using AI. Send the developer message and assistant response, and the server identifies facts worth remembering (architecture decisions, preferences, bug fixes, etc.).', {
+        user_message: z
+            .string()
+            .min(1)
+            .max(4000)
+            .describe("The developer's message"),
+        assistant_response: z
+            .string()
+            .max(4000)
+            .optional()
+            .describe("The assistant's response"),
+        previous_context: z
+            .string()
+            .max(2000)
+            .optional()
+            .describe('Previous exchange for context'),
+    }, async ({ user_message, assistant_response, previous_context }) => {
+        const projectId = detectProjectId();
+        const result = await api('/cogmemai/extract', 'POST', {
+            user_message,
+            assistant_response: assistant_response || '',
+            previous_context: previous_context || '',
+            project_id: projectId,
+        });
+        return {
+            content: [
+                { type: 'text', text: JSON.stringify(result, null, 2) },
+            ],
+        };
+    });
+    // ─── 4. get_project_context ──────────────────────────────
+    server.tool('get_project_context', 'Load all stored memories for the current project plus relevant global memories. Use at the start of a session to get full context from previous sessions.', {
+        project_id: z
+            .string()
+            .max(200)
+            .optional()
+            .describe('Project identifier (auto-detected from git remote if omitted)'),
+        include_global: z
+            .boolean()
+            .default(true)
+            .describe('Include global developer preferences'),
+    }, async ({ project_id, include_global }) => {
+        const pid = project_id || detectProjectId();
+        const result = await api('/cogmemai/context', 'GET', {
+            project_id: pid,
+            include_global: include_global ? 'true' : 'false',
+        });
+        return {
+            content: [
+                { type: 'text', text: JSON.stringify(result, null, 2) },
+            ],
+        };
+    });
+    // ─── 5. list_memories ────────────────────────────────────
+    server.tool('list_memories', 'List all stored memories with optional filters by type, category, scope, or project.', {
+        memory_type: z.enum(MEMORY_TYPES).optional().describe('Filter by type'),
+        category: z.enum(CATEGORIES).optional().describe('Filter by category'),
+        scope: z
+            .enum(['global', 'project', 'all'])
+            .default('all')
+            .describe('Filter by scope'),
+        limit: z
+            .number()
+            .int()
+            .min(1)
+            .max(100)
+            .default(50)
+            .describe('Results per page'),
+        offset: z.number().int().default(0).describe('Pagination offset'),
+    }, async ({ memory_type, category, scope, limit, offset }) => {
+        const projectId = detectProjectId();
+        const params = {
+            limit,
+            offset,
+            project_id: projectId,
+        };
+        if (memory_type)
+            params.memory_type = memory_type;
+        if (category)
+            params.category = category;
+        if (scope && scope !== 'all')
+            params.scope = scope;
+        const result = await api('/cogmemai/memories', 'GET', params);
+        return {
+            content: [
+                { type: 'text', text: JSON.stringify(result, null, 2) },
+            ],
+        };
+    });
+    // ─── 6. delete_memory ────────────────────────────────────
+    server.tool('delete_memory', 'Delete a specific memory by its ID. This is permanent.', {
+        memory_id: z.number().int().describe('Memory ID to delete'),
+    }, async ({ memory_id }) => {
+        const result = await api(`/cogmemai/memory/${memory_id}`, 'DELETE');
+        return {
+            content: [
+                { type: 'text', text: JSON.stringify(result, null, 2) },
+            ],
+        };
+    });
+    // ─── 7. update_memory ────────────────────────────────────
+    server.tool('update_memory', "Update an existing memory's content, importance, or scope.", {
+        memory_id: z.number().int().describe('Memory ID to update'),
+        content: z
+            .string()
+            .min(5)
+            .max(500)
+            .optional()
+            .describe('New content'),
+        importance: z
+            .number()
+            .int()
+            .min(1)
+            .max(10)
+            .optional()
+            .describe('New importance (1-10)'),
+        scope: z
+            .enum(['global', 'project'])
+            .optional()
+            .describe('New scope'),
+    }, async ({ memory_id, content, importance, scope }) => {
+        const body = {};
+        if (content !== undefined)
+            body.content = content;
+        if (importance !== undefined)
+            body.importance = importance;
+        if (scope !== undefined)
+            body.scope = scope;
+        const result = await api(`/cogmemai/memory/${memory_id}`, 'PATCH', body);
+        return {
+            content: [
+                { type: 'text', text: JSON.stringify(result, null, 2) },
+            ],
+        };
+    });
+    // ─── 8. get_usage ────────────────────────────────────────
+    server.tool('get_usage', 'Get current usage statistics — memory count, extractions this month, tier info, projects.', {}, async () => {
+        const result = await api('/cogmemai/usage', 'GET');
+        return {
+            content: [
+                { type: 'text', text: JSON.stringify(result, null, 2) },
+            ],
+        };
+    });
+}

package/build/types.d.ts

@@ -0,0 +1,71 @@
+/**
+ * CogmemAi TypeScript types
+ */
+export interface ApiResponse<T = unknown> {
+    error?: string;
+    [key: string]: unknown;
+}
+export interface Memory {
+    id: number;
+    content: string;
+    memory_type: string;
+    category: string;
+    subject: string;
+    importance: number;
+    scope: string;
+    project_id: string | null;
+    relevance_score?: number;
+    created_at: string;
+    updated_at?: string;
+}
+export interface StoreResult {
+    memory_id: number;
+    stored: boolean;
+}
+export interface RecallResult {
+    memories: Memory[];
+    total: number;
+}
+export interface ExtractResult {
+    extracted: number;
+    memories: Array<{
+        subject: string;
+        content: string;
+        memory_type: string;
+        scope: string;
+    }>;
+}
+export interface ContextResult {
+    project_memories: Memory[];
+    global_memories: Memory[];
+    formatted_context: string;
+    total_count: number;
+}
+export interface ListResult {
+    memories: Memory[];
+    total: number;
+    has_more: boolean;
+}
+export interface UpdateResult {
+    success: boolean;
+    updated_fields: string[];
+}
+export interface UsageStats {
+    tier: string;
+    tier_name: string;
+    memory_count: number;
+    memory_limit: number;
+    extractions_used: number;
+    extractions_limit: number;
+    recalls_used: number;
+    recalls_limit: number;
+    stores_used: number;
+    stores_limit: number;
+    project_count: number;
+    project_limit: number;
+    projects: Array<{
+        project_id: string;
+        project_name: string;
+        last_used: string;
+    }>;
+}

package/build/types.js

@@ -0,0 +1,4 @@
+/**
+ * CogmemAi TypeScript types
+ */
+export {};

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "cogmemai-mcp",
+  "version": "1.0.0",
+  "description": "CogmemAi — Cognitive Memory for Claude Code. Persistent memory across sessions for developers.",
+  "type": "module",
+  "main": "build/index.js",
+  "bin": {
+    "cogmemai-mcp": "build/index.js"
+  },
+  "files": [
+    "build",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node build/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "memory",
+    "claude-code",
+    "cognitive-memory",
+    "ai-agent",
+    "persistent-memory",
+    "developer-tools",
+    "context",
+    "cogmemai"
+  ],
+  "author": "HiFriendbot (https://hifriendbot.com)",
+  "license": "MIT",
+  "homepage": "https://hifriendbot.com/developer/",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/hifriendbot/cogmemai-mcp"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.11.4",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.3.0"
+  }
+}