\n Persistent memory for AI coding tools. The first MCP-native memory server.\n
\n\n
\n \n \n \n
\n\nGive Claude Code, Cursor, Windsurf, VS Code Copilot, OpenAI Codex, or any MCP-compatible AI tool persistent memory across sessions. Your AI remembers decisions, conventions, bugs, and context — picks up exactly where you left off.\n\n## Install — One Command\n\nRun this in your project directory:\n\n```bash\nnpx -y @shackleai/memory-mcp@latest setup\n```\n\nThis creates two files in your project:\n\n- **`.mcp.json`** — registers the memory server so your AI tool auto-starts it\n- **`CLAUDE.md`** — tells the AI to actively use memory every session\n\nCommit both to git so your whole team gets memory. That's it — no config, no API keys, no accounts.\n\n> **npm/npx version too old?** If the command fails, see [Troubleshooting](#npx-setup-fails-or-command-not-found-setup).\n\n## How It Works\n\n```\n1. Run the setup command above (one-time)\n2. Start your AI tool in the project directory\n3. Memory server starts automatically in the background\n4. AI stores decisions, conventions, and bugs as you work\n5. Next session — AI searches memory and picks up where you left off\n```\n\n**You don't need to do anything after setup.** The AI sees the memory tools and uses them proactively — storing important decisions, searching for past context, and saving session summaries.\n\n### Verify It Works\n\nAfter setup, start a session and give your AI a task. Then ask:\n\n> \"What have you stored in memory so far?\"\n\nIf it calls `memory_search` and shows stored entries, it's working. In your next session, ask:\n\n> \"What do you remember about this project?\"\n\nIt should recall context from the previous session without reading any files.\n\n## Alternative Setup Methods\n\nThe `npx setup` command works for all MCP clients. If you prefer client-specific configuration:\n\n\nClaude Code (global config)\n\n```bash\nclaude mcp add memory -- npx -y @shackleai/memory-mcp@latest\n```\n\nThis adds memory to your global Claude Code config. It works across all projects, but won't be shared with your team via git.\n\n\n\n\nCursor\n\nAdd to `~/.cursor/mcp.json`:\n\n```json\n{\n \"mcpServers\": {\n \"memory\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@shackleai/memory-mcp@latest\"]\n }\n }\n}\n```\n\n\n\n\nWindsurf\n\nAdd to `~/.codeium/windsurf/mcp_config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"memory\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@shackleai/memory-mcp@latest\"]\n }\n }\n}\n```\n\n\n\n\nVS Code Copilot\n\nAdd to `.vscode/mcp.json` in your project:\n\n```json\n{\n \"servers\": {\n \"memory\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@shackleai/memory-mcp@latest\"]\n }\n }\n}\n```\n\n\n\n\nClaude Desktop\n\nAdd to your Claude Desktop config:\n\n- **Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n\n```json\n{\n \"mcpServers\": {\n \"memory\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@shackleai/memory-mcp@latest\"]\n }\n }\n}\n```\n\n\n\n\nInstall globally (if npx doesn't work)\n\n```bash\nnpm install -g @shackleai/memory-mcp\nshackleai-memory setup\n```\n\nOr use the global binary directly in your MCP config:\n\n```json\n{\n \"mcpServers\": {\n \"memory\": {\n \"command\": \"shackleai-memory\"\n }\n }\n}\n```\n\n\n\n\nRun from source (for contributors)\n\n```bash\ngit clone https://github.com/shackleai/memory-mcp.git\ncd memory-mcp && npm install && npm run build\n```\n\n```json\n{\n \"mcpServers\": {\n \"memory\": {\n \"command\": \"node\",\n \"args\": [\"/absolute/path/to/memory-mcp/dist/index.js\"]\n }\n }\n}\n```\n\n\n\n### First Run\n\nThe first run downloads the embedding model (~80MB, one-time). After that, everything works offline.\n\n## Features\n\n- **One-command setup** — `npx -y @shackleai/memory-mcp@latest setup` and you're done\n- **Fully automatic** — auto-detects project on startup, no manual init needed\n- **11 MCP tools** — init, store, search, update, delete, list projects, session end, TODO status, export, import, cleanup\n- **MCP resources** — project context available as a readable resource\n- **Local-first** — everything stored on your machine at `~/.shackleai/`\n- **Zero config** — no API keys, no cloud account, no setup beyond the install command\n- **Offline** — local embeddings via MiniLM-L6-v2 (free, runs on CPU)\n- **Human-readable** — memories stored as Markdown files you can read and edit\n- **Git-friendly** — version control your AI's memory with standard git\n- **Semantic search** — find relevant memories by meaning, not just keywords\n- **Deduplication** — automatically detects and merges duplicate memories\n- **Auto-archive** — old session files cleaned up based on retention period\n- **Multi-project** — separate memory spaces per project, auto-detected\n- **LLM-portable** — switch AI tools anytime, your memory stays\n\n## MCP Tools Reference\n\n### memory_init\n\nInitialize or switch project context. **Auto-called on server startup** — only call manually if switching projects mid-session.\n\n```\nInput: { project_path: \"/path/to/project\" }\nOutput: { project_name, tech_stack, memory_count, summary }\n```\n\nAuto-detects project name from `package.json`, `pyproject.toml`, or directory name. Detects tech stack (Node.js, Python, Rust, Go, Java, Ruby, PHP, .NET, Docker, etc.).\n\n### memory_store\n\nSave important information to persistent memory. Use for decisions, conventions, bugs, architecture, preferences, TODOs, and context.\n\n```\nInput: {\n content: \"We chose PostgreSQL with Prisma ORM for type-safe queries\",\n category: \"decision\", // decision|convention|bug|architecture|preference|todo|context|session_summary\n importance: \"high\", // low|medium|high (optional, default: medium)\n tags: [\"database\", \"orm\"] // optional\n}\nOutput: { id, stored: true, deduplicated: false }\n```\n\nAutomatically checks for duplicates. If similar content exists (cosine similarity > 0.9), updates the existing memory instead of creating a new one.\n\n### memory_search\n\nSearch past memories by semantic meaning.\n\n```\nInput: { query: \"what database are we using\", category: \"decision\", limit: 5 }\nOutput: { results: [{ id, content, category, relevance, ... }], count }\n```\n\nUses vector similarity search — finds relevant memories even when wording differs.\n\n### memory_update\n\nUpdate an existing memory when information changes.\n\n```\nInput: { id: \"mem-uuid\", content: \"Updated content\", reason: \"Changed approach\" }\nOutput: { updated: true, previous_content }\n```\n\n### memory_delete\n\nRemove a memory that is no longer relevant (soft delete).\n\n```\nInput: { id: \"mem-uuid\" }\nOutput: { deleted: true }\n```\n\n### memory_list_projects\n\nList all projects with stored memories.\n\n```\nInput: {}\nOutput: { projects: [{ name, path, tech_stack, memory_count, last_session }], count }\n```\n\n### memory_session_end\n\nSave a session summary and open items. Creates continuity between sessions.\n\n```\nInput: { summary: \"Built auth system with JWT\", open_items: [\"Add refresh tokens\", \"Write tests\"] }\nOutput: { saved: true, date: \"2026-03-04\" }\n```\n\n## MCP Resources\n\nThe server exposes project context as an MCP resource:\n\n- **`memory://project/context`** — Current project's conventions, decisions, architecture, bugs, and TODOs. MCP clients that support resources can auto-load this at session start.\n\n## Storage\n\nAll data lives locally on your machine:\n\n```\n~/.shackleai/\n db/\n memory.db SQLite database + vector index\n projects/\n my-project/\n decisions.md Key decisions with reasoning\n conventions.md Coding standards and patterns\n bugs.md Known issues and fixes\n architecture.md Architecture choices\n preferences.md Developer preferences\n todos.md Open items\n context.md General context\n sessions/\n 2026-03-04.md Today's session summary\n 2026-03-03.md Yesterday's session\n config.yaml Optional configuration\n```\n\n**Markdown is the source of truth.** You can read, edit, or delete any memory file with a text editor. The SQLite database is the search index.\n\n## Configuration\n\nCreate `~/.shackleai/config.yaml` (optional — sensible defaults work out of the box):\n\n```yaml\n# Embedding provider: \"local\" (free, offline) or \"openai\" (better quality, requires API key)\nembedding:\n provider: local\n\n# Custom storage path (default: ~/.shackleai)\n# storage_path: /path/to/custom/location\n\n# Maximum memories per project before oldest are archived\nmax_memories_per_project: 10000\n\n# Session files older than this are auto-archived\nmax_session_history_days: 90\n\n# Automatically detect and merge duplicate memories\nauto_dedup: true\n\n# Cosine similarity threshold for deduplication (0.0 to 1.0)\ndedup_threshold: 0.9\n```\n\n## Cloud Mode\n\nBy default, ShackleAI Memory runs locally with SQLite — no account needed. **Cloud mode** syncs your memories to ShackleAI's managed infrastructure via the Gateway, giving you server-side persistence, cross-device access, and PostgreSQL + pgvector-powered semantic search.\n\n### Local vs Cloud\n\n| | Local (default) | Cloud |\n|---|---|---|\n| **Storage** | SQLite + sqlite-vec on your machine | PostgreSQL + pgvector via ShackleAI Gateway |\n| **Embeddings** | Local MiniLM-L6-v2 (CPU) | Server-side embeddings |\n| **Account required** | No | Yes (free tier available) |\n| **Cross-device** | No — `~/.shackleai/` is per-machine | Yes — memories persist in the cloud |\n| **Tools available** | All 11 tools | All 11 tools |\n| **Offline support** | Full | Requires internet |\n\n### Get an API Key\n\n1. Go to [shackleai.com](https://shackleai.com) and sign in (or create an account)\n2. Navigate to **Settings > API Keys**\n3. Click **Create Key** — you'll get a unified account key in the format `sk_shackle_*`\n4. Copy the key. It won't be shown again.\n\n### Configure Cloud Mode\n\nCloud mode connects to the ShackleAI Gateway MCP endpoint with Bearer authentication. Configure your MCP client to point at the Gateway instead of running the local server.\n\n\nClaude Code\n\n```bash\nclaude mcp add memory-cloud --transport http https://gateway.shackleai.com/mcp \\\n --header \"Authorization: Bearer sk_shackle_YOUR_KEY_HERE\"\n```\n\nOr add to `.mcp.json` in your project:\n\n```json\n{\n \"mcpServers\": {\n \"memory\": {\n \"type\": \"http\",\n \"url\": \"https://gateway.shackleai.com/mcp\",\n \"headers\": {\n \"Authorization\": \"Bearer sk_shackle_YOUR_KEY_HERE\"\n }\n }\n }\n}\n```\n\n\n\n\nCursor / Windsurf / VS Code Copilot\n\nAdd to your client's MCP config file:\n\n```json\n{\n \"mcpServers\": {\n \"memory\": {\n \"type\": \"http\",\n \"url\": \"https://gateway.shackleai.com/mcp\",\n \"headers\": {\n \"Authorization\": \"Bearer sk_shackle_YOUR_KEY_HERE\"\n }\n }\n }\n}\n```\n\n\n\nAll 11 memory tools (`memory_init`, `memory_store`, `memory_search`, `memory_update`, `memory_delete`, `memory_list_projects`, `memory_session_end`, `memory_status`, `memory_export`, `memory_import`, `memory_cleanup`) work identically in cloud mode — no code changes needed.\n\n## Advanced: Auto-Init Options\n\nThe server auto-detects your project in this order:\n\n1. **CLI argument**: `--project-path /path/to/project`\n2. **Environment variable**: `SHACKLEAI_PROJECT_PATH=/path/to/project`\n3. **Working directory**: Uses `process.cwd()` (this is what most MCP clients pass)\n\nFor explicit control, set the project path in your MCP config:\n\n```json\n{\n \"mcpServers\": {\n \"memory\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@shackleai/memory-mcp@latest\", \"--project-path\", \"/path/to/project\"]\n }\n }\n}\n```\n\nOr via environment variable:\n\n```json\n{\n \"mcpServers\": {\n \"memory\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@shackleai/memory-mcp@latest\"],\n \"env\": {\n \"SHACKLEAI_PROJECT_PATH\": \"/path/to/project\"\n }\n }\n }\n}\n```\n\n## Troubleshooting\n\n### `npx setup` fails or \"command not found: setup\"\n\nYour npm/npx is too old. This happens when npm is v6.x (ships with older Node installers). Check with:\n\n```bash\nnpm --version\n```\n\nIf it shows 6.x, fix it:\n\n```bash\n# Option 1: Update npm (recommended — gets you modern npx)\nnpm install -g npm@latest\n\n# If that fails on Windows with \"Refusing to delete\" error:\n# Delete the stale files first, then retry:\n# Remove-Item \"$env:APPDATA\\npm\\npm.cmd\", \"$env:APPDATA\\npm\\npx.cmd\" -Force\n# npm install -g npm@latest\n\n# Option 2: Install globally instead (works with any npm version)\nnpm install -g @shackleai/memory-mcp\nshackleai-memory setup\n```\n\n### \"Cannot connect to MCP server\" / Server fails to start\n\nMake sure Node.js 20+ is installed. Then verify the server runs:\n\n```bash\nnpx -y @shackleai/memory-mcp --help\n```\n\nIf using a global install, verify the binary is in your PATH:\n\n```bash\nshackleai-memory --help\n```\n\n### Claude Code: \"memory\" not showing in `claude mcp list`\n\nIf you used `npx setup`, Claude Code reads `.mcp.json` from your project directory automatically — you don't need `claude mcp list` to show it. Just start `claude` in the project directory.\n\nIf you used `claude mcp add` instead, verify with:\n\n```bash\nclaude mcp list\n# Should show: memory: connected\n```\n\n### AI not storing memories during sessions\n\nThe `setup` command creates a `CLAUDE.md` file with instructions that tell the AI to use memory proactively. If you already had a `CLAUDE.md`, the setup appends memory instructions to it. Check that your `CLAUDE.md` contains the \"ShackleAI Memory\" section.\n\nIf the AI still isn't storing, you can ask it directly:\n\n> \"Store what you just did in memory\"\n\nThis confirms the tools work, and the AI will be more proactive about storing in subsequent interactions.\n\n### First tool call is slow\n\nThe embedding model (~80MB) downloads on first use. This is a one-time download. Subsequent runs use the cached model and are fast.\n\n### Memory not persisting between sessions\n\nCheck that `~/.shackleai/` directory exists and has write permissions. The server creates it automatically on first run.\n\n### Wrong project detected\n\nUse `--project-path` to explicitly set the project, or call `memory_init` with the correct path.\n\n## Why ShackleAI?\n\nEvery AI coding tool today has amnesia. Close the session, context is gone. Switch tools, everything lost.\n\nShackleAI fixes this by providing a **universal memory layer** that works across every MCP-compatible AI tool:\n\n- **Works with every AI tool** — Claude Code, Cursor, Windsurf, VS Code Copilot, OpenAI Codex, Claude Desktop\n- **Works with every LLM** — Claude, GPT, Gemini, Llama, Mistral — any LLM behind any MCP client\n- **Your memory is YOUR asset** — switch tools anytime, your knowledge stays\n- **No vendor lock-in** — open source, local storage, standard protocol\n\n## Requirements\n\n- Node.js 20 or later\n- npm 7 or later (for `npx setup` — or install globally with any npm version)\n- Any MCP-compatible AI client\n\n## Contributing\n\nIssues and PRs welcome at [github.com/shackleai/memory-mcp](https://github.com/shackleai/memory-mcp).\n\n## License\n\nMIT — free and open source forever.\n\n---\n\n*The shackle that keeps your AI anchored.* Built by [ShackleAI](https://shackleai.com).\n",
"bytes": 16022,
"sha": "f232e3b2da9d9832eee76354103fed7fa7a65d0a684bf5c65c09f1fa67041120",
"repo_slug": "shackleai/memory-mcp",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_shackleai_memory_96448bcb/readme"
}
![\"ShackleAI\"](\"logo.png\")
\n![\"npm](\"https://img.shields.io/npm/v/@shackleai/memory-mcp.svg\")
\n ![\"npm](\"https://img.shields.io/npm/dw/@shackleai/memory-mcp.svg\")
\n ![\"MIT](\"https://img.shields.io/badge/license-MIT-blue.svg\"){kind=icon}
\n