.mcp.json — registers the memory server so your AI tool auto-starts it
— tells the AI to actively use memory every session
Persistent memory for AI coding tools. 11 tools for any MCP-compatible AI tool.
2026-11-10
ดาว
—
เครื่องมือ
—
อัปไทม์
—
CLAUDE.md
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)
2. Start your AI tool in the project directory
3. Memory server starts automatically in the background
4. AI stores decisions, conventions, and bugs as you work
5. 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 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.
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
Local (default)
Cloud
Storage
SQLite + sqlite-vec on your machine
PostgreSQL + pgvector via ShackleAI Gateway
Embeddings
Local MiniLM-L6-v2 (CPU)
Server-side embeddings
Account required
No
Yes (free tier available)
Cross-device
No — ~/.shackleai/ is per-machine
Yes — memories persist in the cloud
Tools available
All 11 tools
All 11 tools
Offline support
Full
Requires internet
Get an API Key
Go to shackleai.com and sign in (or create an account)
Navigate to Settings > API Keys
Click Create Key — you'll get a unified account key in the format sk_shackle_*
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.
Your npm/npx is too old. This happens when npm is v6.x (ships with older Node installers). Check with:
npm --version
If it shows 6.x, fix it:
# Option 1: Update npm (recommended — gets you modern npx)
npm install -g npm@latest
# If that fails on Windows with "Refusing to delete" error:
# Delete the stale files first, then retry:
# Remove-Item "$env:APPDATA\npm\npm.cmd", "$env:APPDATA\npm\npx.cmd" -Force
# npm install -g npm@latest
# Option 2: Install globally instead (works with any npm version)
npm install -g @shackleai/memory-mcp
shackleai-memory setup
"Cannot connect to MCP server" / Server fails to start
Make sure Node.js 20+ is installed. Then verify the server runs:
npx -y @shackleai/memory-mcp --help
If using a global install, verify the binary is in your PATH:
shackleai-memory --help
Claude Code: "memory" not showing in claude mcp list
If 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.
If you used claude mcp add instead, verify with:
claude mcp list
# Should show: memory: connected
AI not storing memories during sessions
The 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.
If the AI still isn't storing, you can ask it directly:
"Store what you just did in memory"
This confirms the tools work, and the AI will be more proactive about storing in subsequent interactions.
First tool call is slow
The embedding model (~80MB) downloads on first use. This is a one-time download. Subsequent runs use the cached model and are fast.
Memory not persisting between sessions
Check that ~/.shackleai/ directory exists and has write permissions. The server creates it automatically on first run.
Wrong project detected
Use --project-path to explicitly set the project, or call memory_init with the correct path.
Why ShackleAI?
Every AI coding tool today has amnesia. Close the session, context is gone. Switch tools, everything lost.
ShackleAI fixes this by providing a universal memory layer that works across every MCP-compatible AI tool:
Works with every AI tool — Claude Code, Cursor, Windsurf, VS Code Copilot, OpenAI Codex, Claude Desktop
Works with every LLM — Claude, GPT, Gemini, Llama, Mistral — any LLM behind any MCP client
Your memory is YOUR asset — switch tools anytime, your knowledge stays
No vendor lock-in — open source, local storage, standard protocol
Requirements
Node.js 20 or later
npm 7 or later (for npx setup — or install globally with any npm version)