memory-mcp

Personal External Brain MCP Server - A stateless MCP server for syncing templates, standards, and knowledge via GitHub.

Features

• Zero-latency reads: In-memory cache for instant access to templates and standards
• Non-blocking writes: Async GitHub sync with local queue for resilience
• Auto-categorization: Files organized by category (templates, standards, knowledge, etc.)
• Full-text search: Search across file paths and content

Installation

VS Code / Copilot

Add to your ~/.vscode/mcp.json or VS Code settings:

{
  "servers": {
    "memory-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "memory-mcp"],
      "env": {
        "MEMORY_MCP_REPO": "your-username/memory-mcp-storage",
        "MEMORY_MCP_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "memory-mcp": {
      "command": "npx",
      "args": ["-y", "memory-mcp"],
      "env": {
        "MEMORY_MCP_REPO": "your-username/memory-mcp-storage",
        "MEMORY_MCP_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

Configuration

Variable	Required	Description
MEMORY_MCP_REPO	Yes	GitHub repository in owner/repo format
MEMORY_MCP_TOKEN	Yes	GitHub Personal Access Token with repo scope

Tools

list_knowledge

List all available memory files organized by category.

read_memory

Read the content of a specific memory file.

{ "path": "templates/user-story.md" }

save_memory

Create or update a memory file. Category folders are auto-created.

{ "category": "templates", "name": "user-story.md", "content": "..." }

delete_memory

Delete a memory file.

{ "path": "templates/old-template.md" }

search_memory

Search across all memory files by keyword.

{ "query": "graphql error" }

Storage Repository Structure

Create a private GitHub repository (e.g., memory-mcp-storage) with this structure:

/
├── index.json             # Auto-generated manifest
├── templates/             # Markdown templates
│   ├── user-story.md
│   └── pull-request.md
├── standards/             # Technical rules (YAML/JSON)
│   ├── typescript.yaml
│   └── graphql.yaml
└── knowledge/             # Long-form context
    └── architecture.md

How It Works

1. Startup: Fetches all files from GitHub, populates in-memory cache
2. Reads: Cache-first (instant), falls back to GitHub API on miss
3. Writes: Updates cache immediately, returns to agent, syncs GitHub async
4. Failures: Failed writes queue to ~/.memory-mcp-queue.json and retry on next operation

Development

# Install dependencies
npm install

# Build
npm run build

# Watch mode
npm run dev

License

MIT