Memory

ShackleAI Memory

Persistent memory for AI coding tools. The first MCP-native memory server.

Give 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.

Install — One Command

Run this in your project directory:

npx -y @shackleai/memory-mcp@latest setup

This creates two files in your project:

• `.mcp.json` — registers the memory server so your AI tool auto-starts it
• `CLAUDE.md` — tells the AI to actively use memory every session

Commit both to git so your whole team gets memory. That's it — no config, no API keys, no accounts.

npm/npx version too old? If the command fails, see Troubleshooting.

How It Works

1. Run the setup command above (one-time)

1. Start your AI tool in the project directory
2. Memory server starts automatically in the background
3. AI stores decisions, conventions, and bugs as you work
4. Next session — AI searches memory and picks up where you left off

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.

Verify It Works

After setup, start a session and give your AI a task. Then ask:

"What have you stored in memory so far?"

If it calls memory_search and shows stored entries, it's working. In your next session, ask:

"What do you remember about this project?"

It should recall context from the previous session without reading any files.

Alternative Setup Methods

The npx setup command works for all MCP clients. If you prefer client-specific configuration:

Claude Code (global config)

claude mcp add memory -- npx -y @shackleai/memory-mcp@latest

This adds memory to your global Claude Code config. It works across all projects, but won't be shared with your team via git.

Cursor

Add to ~/.cursor/mcp.json:

{

"mcpServers": { "memory": { "command": "npx", "args": ["-y", "@shackleai/memory-mcp@latest"] } } }

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{

"mcpServers": { "memory": { "command": "npx", "args": ["-y", "@shackleai/memory-mcp@latest"] } } }

VS Code Copilot

Add to .vscode/mcp.json in your project:

{

"servers": { "memory": { "command": "npx", "args": ["-y", "@shackleai/memory-mcp@latest"] } } }

Claude Desktop

Add to your Claude Desktop config:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{

"mcpServers": { "memory": { "command": "npx", "args": ["-y", "@shackleai/memory-mcp@latest"] } } }

Install globally (if npx doesn't work)

npm install -g @shackleai/memory-mcp

shackleai-memory setup

Or use the global binary directly in your MCP config:

{

"mcpServers": { "memory": { "command": "shackleai-memory" } } }

Run from source (for contributors)

git clone https://github.com/shackleai/memory-mcp.git

cd memory-mcp && npm install && npm run build

{

"mcpServers": { "memory": { "command": "node", "args": ["/absolute/path/to/memory-mcp/dist/index.js"] } } }

First Run

The first run downloads the embedding model (~80MB, one-time). After that, everything works offline.

Features

• One-command setup — npx -y @shackleai/memory-mcp@latest setup and you're done
• Fully automatic — auto-detects project on startup, no manual init needed
• 11 MCP tools — init, store, search, update, delete, list projects, session end, TODO status, export, import, cleanup
• MCP resources — project context available as a readable resource
• Local-first — everything stored on your machine at ~/.shackleai/
• Zero config — no API keys, no cloud account, no setup beyond the install command
• Offline — local embeddings via MiniLM-L6-v2 (free, runs on CPU)
• Human-readable — memories stored as Markdown files you can read and edit
• Git-friendly — version control your AI's memory with standard git
• Semantic search — find relevant memories by meaning, not just keywords
• Deduplication — automatically detects and merges duplicate memories
• Auto-archive — old session files cleaned up based on retention period
• Multi-project — separate memory spaces per project, auto-detected
• LLM-portable — switch AI tools anytime, your memory stays

MCP Tools Reference

memory_init

Initialize or switch project context. Auto-called on server startup — only call manually if switching projects mid-session.

Input:  { project_path: "/path/to/project" }

Output: { project_name, tech_stack, memory_count, summary }

Auto-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.).

memory_store

Save important information to persistent memory. Use for decisions, conventions, bugs, architecture, preferences, TODOs, and context.

Input:  {

content: "We chose PostgreSQL with Prisma ORM for type-safe queries", category: "decision", // decision|convention|bug|architecture|preference|todo|context|session_summary importance: "high", // low|medium|high (optional, default: medium) tags: ["database", "orm"] // optional } Output: { id, stored: true, deduplicated: false }

Automatically checks for duplicates. If similar content exists (cosine similarity > 0.9), updates the existing memory instead of creating a new one.

memory_search

Search past memories by semantic meaning.

Input:  { query: "what database are we using", category: "decision", limit: 5 }

Output: { results: [{ id, content, category, relevance, ... }], count }

Uses vector similarity search — finds relevant memories even when wording differs.

memory_update

Update an existing memory when information changes.

Input:  { id: "mem-uuid", content: "Updated content", reason: "Changed approach" }

Output: { updated: true, previous_content }

memory_delete

Remove a memory that is no longer relevant (soft delete).

Input:  { id: "mem-uuid" }

Output: { deleted: true }

memory_list_projects

List all projects with stored memories.

Input:  {}

Output: { projects: [{ name, path, tech_stack, memory_count, last_session }], count }

memory_session_end

Save a session summary and open items. Creates continuity between sessions.

Input:  { summary: "Built auth system with JWT", open_items: ["Add refresh tokens", "Write tests"] }

Output: { saved: true, date: "2026-03-04" }

MCP Resources

The server exposes project context as an MCP resource:

• `memory://project/context` — Current project's conventions, decisions, architecture, bugs, and TODOs. MCP clients that support resources can auto-load this at session start.

Storage

All data lives locally on your machine:

~/.shackleai/

db/ memory.db SQLite database + vector index projects/ my-project/ decisions.md Key decisions with reasoning conventions.md Coding standards and patterns bugs.md Known issues and fixes architecture.md Architecture choices preferences.md Developer preferences todos.md Open items context.md General context sessions/ 2026-03-04.md Today's session summary 2026-03-03.md Yesterday's session config.yaml Optional configuration

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.

Configuration

Create ~/.shackleai/config.yaml (optional — sensible defaults work out of the box):

# Embedding provider: "local" (free, offline) or "openai" (better quality, requires API key)

embedding: provider: local

Custom storage path (default: ~/.shackleai)

storage_path: /path/to/custom/location

Maximum memories per project before oldest are archived

max_memories_per_project: 10000

Session files older than this are auto-archived

max_session_history_days: 90

Automatically detect and merge duplicate memories

auto_dedup: true

Cosine similarity threshold for deduplication (0.0 to 1.0)

dedup_threshold: 0.9

Cloud Mode

By 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.

Local vs Cloud

Get an API Key

1. Go to shackleai.com and sign in (or create an account)
2. Navigate to Settings > API Keys
3. Click Create Key — you'll get a unified account key in the format sk_shackle_*
4. Copy the key. It won't be shown again.

Configure Cloud Mode

Cloud 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.

Claude Code

claude mcp add memory-cloud --transport http https://gateway.shackleai.com/mcp \

--header "Authorization: Bearer sk_shackle_YOUR_KEY_HERE"

Or add to .mcp.json in your project:

{

"mcpServers": { "memory": { "type": "http", "url": "https://gateway.shackleai.com/mcp", "headers": { "Authorization": "Bearer sk_shackle_YOUR_KEY_HERE" } } } }

Cursor / Windsurf / VS Code Copilot

Add to your client's MCP config file:

{

"mcpServers": { "memory": { "type": "http", "url": "https://gateway.shackleai.com/mcp", "headers": { "Authorization": "Bearer sk_shackle_YOUR_KEY_HERE" } } } }

All 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.

Advanced: Auto-Init Options