memory

ShackleAI Memory

AI コーディングツール向けの永続メモリです。 初の MCP ネイティブなメモリサーバーです。

Claude Code、Cursor、Windsurf、VS Code Copilot、OpenAI Codex、または MCP 対応の AI ツールで、セッションをまたいで使える永続メモリを利用できます。AI は決定事項、規約、バグ、コンテキストを記憶し、中断したところから正確に再開できます。

インストール — 1 つのコマンド

プロジェクトディレクトリで以下を実行します。

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

プロジェクトに次の 2 つのファイルが作成されます。

• .mcp.json — メモリサーバーを登録し、AI ツールが自動的に起動できるようにします
• CLAUDE.md — 毎回のセッションで AI がメモリを積極的に使うよう指示します

チーム全体でメモリを使えるよう、両方を git にコミットしてください。これだけです。設定も、API キーも、アカウントも必要ありません。

npm/npx のバージョンが古すぎますか？ コマンドが失敗する場合は、トラブルシューティングをご覧ください。

仕組み

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

セットアップ後に、何か操作する必要はありません。 AI はメモリツールを認識し、重要な決定事項の保存、過去のコンテキストの検索、セッションの要約の保存を自発的に行います。

動作確認

セットアップ後、セッションを開始して AI にタスクを与えます。それから次のように尋ねてください。

「これまでメモリに何を保存しましたか？」

memory_search を呼び出して保存済みのエントリを表示すれば、正常に動作しています。次のセッションで、次のように尋ねてください。

「このプロジェクトについて何を覚えていますか？」

ファイルを読み込まずに、前のセッションのコンテキストを思い出すはずです。

別のセットアップ方法

npx setup コマンドはすべての MCP クライアントで動作します。クライアント固有の設定を使いたい場合は、次の方法があります。

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

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

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

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

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

npm install -g @shackleai/memory-mcp
shackleai-memory setup

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

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"]
    }
  }
}

初回起動

初回起動時に、埋め込みモデルがダウンロードされます（約 80 MB、初回のみ）。その後はすべてオフラインで動作します。

特長

• ワンコマンドでセットアップ — npx -y @shackleai/memory-mcp@latest setup を実行するだけです
• 完全自動 — 起動時にプロジェクトを自動検出するため、手動で初期化する必要はありません
• 11 個の MCP ツール — 初期化、保存、検索、更新、削除、プロジェクト一覧、セッション終了、TODO の状態、エクスポート、インポート、クリーンアップ
• MCP リソース — プロジェクトのコンテキストを読み取り可能なリソースとして利用できます
• ローカル優先 — すべてのデータはお使いのマシンの ~/.shackleai/ に保存されます
• 設定不要 — API キーやクラウドアカウントは不要で、インストールコマンド以外のセットアップも必要ありません
• オフライン対応 — MiniLM-L6-v2 によるローカル埋め込みを利用します（無料、CPU で動作）
• 人が読みやすい形式 — メモリは読み書き可能な Markdown ファイルとして保存されます
• Git と相性抜群 — 標準の git で AI のメモリをバージョン管理できます
• セマンティック検索 — キーワードだけでなく、意味に基づいて関連するメモリを見つけます
• 重複排除 — 重複したメモリを自動検出して統合します
• 自動アーカイブ — 保存期間に基づいて古いセッションファイルを整理します
• 複数プロジェクト対応 — プロジェクトごとにメモリ領域を分け、自動検出します
• LLM を問わず利用可能 — AI ツールをいつでも切り替えられ、メモリはそのまま使えます

MCP ツールのリファレンス

memory_init

プロジェクトのコンテキストを初期化または切り替えます。サーバー起動時に自動で呼び出されます。手動で呼び出すのは、セッション中にプロジェクトを切り替える場合のみです。

Input:  { project_path: "/path/to/project" }
Output: { project_name, tech_stack, memory_count, summary }

package.json、pyproject.toml、またはディレクトリ名からプロジェクト名を自動検出します。技術スタック（Node.js、Python、Rust、Go、Java、Ruby、PHP、.NET、Docker など）も検出します。

memory_store

重要な情報を永続メモリに保存します。決定事項、規約、バグ、アーキテクチャ、好み、TODO、コンテキストの保存に使用します。

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 }

重複を自動で確認します。類似した内容（コサイン類似度 > 0.9）がある場合は、新しいメモリを作成せず、既存のメモリを更新します。

memory_search

過去のメモリを意味に基づいて検索します。

Input:  { query: "what database are we using", category: "decision", limit: 5 }
Output: { results: [{ id, content, category, relevance, ... }], count }

ベクトル類似度検索を使用するため、表現が異なっていても関連するメモリを見つけられます。

memory_update

情報が変わったときに、既存のメモリを更新します。

Input:  { id: "mem-uuid", content: "Updated content", reason: "Changed approach" }
Output: { updated: true, previous_content }

memory_delete

不要になったメモリを削除します（論理削除）。

Input:  { id: "mem-uuid" }
Output: { deleted: true }

memory_list_projects

メモリが保存されているすべてのプロジェクトを一覧表示します。

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

memory_session_end

セッションの要約と未完了項目を保存します。セッション間の継続性を保ちます。

Input:  { summary: "Built auth system with JWT", open_items: ["Add refresh tokens", "Write tests"] }
Output: { saved: true, date: "2026-03-04" }

MCP リソース

サーバーは、プロジェクトのコンテキストを MCP リソースとして公開します。

• memory://project/context — 現在のプロジェクトの規約、決定事項、アーキテクチャ、バグ、TODO。リソースに対応する MCP クライアントは、セッション開始時にこれを自動読み込みできます。

ストレージ

すべてのデータはお使いのマシン上にローカル保存されます。

~/.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 が信頼できる唯一の情報源です。 テキストエディターで、任意のメモリファイルを読み取り、編集、削除できます。SQLite データベースは検索インデックスです。

設定

~/.shackleai/config.yaml を作成します（任意。適切なデフォルト設定が用意されているため、すぐに利用できます）。

# 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

クラウドモード

デフォルトでは、ShackleAI Memory は SQLite を使ってローカルで動作するため、アカウントは不要です。クラウドモードでは、Gateway 経由でメモリを ShackleAI のマネージドインフラストラクチャと同期できます。これにより、サーバー側での永続化、デバイス間でのアクセス、PostgreSQL + pgvector を利用したセマンティック検索が可能になります。

ローカルとクラウドの比較

API キーを取得する

1. shackleai.com にアクセスしてサインインします（またはアカウントを作成します）
2. Settings > API Keys に移動します
3. Create Key をクリックすると、sk_shackle_* 形式の統合アカウントキーが発行されます
4. キーをコピーします。再表示はできません。

クラウドモードを設定する

クラウドモードでは、Bearer 認証を使用して ShackleAI Gateway MCP エンドポイントに接続します。ローカルサーバーを実行する代わりに、Gateway を参照するよう MCP クライアントを設定してください。

claude mcp add memory-cloud --transport http https://gateway.shackleai.com/mcp \
  --header "Authorization: Bearer sk_shackle_YOUR_KEY_HERE"

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

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

11 個のメモリツール（memory_init、memory_store、memory_search、memory_update、memory_delete、memory_list_projects、memory_session_end、memory_status、memory_export、memory_import、memory_cleanup）はすべてクラウドモードでも同じように動作します。コードを変更する必要はありません。

上級者向け：自動初期化オプション

サーバーは次の順序でプロジェクトを自動検出します。

1. CLI 引数：--project-path /path/to/project
2. 環境変数：SHACKLEAI_PROJECT_PATH=/path/to/project
3. 作業ディレクトリ：process.cwd() を使用します（ほとんどの MCP クライアントが渡す値です）。

明示的に指定するには、MCP 設定でプロジェクトパスを設定します。

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

または、環境変数で設定します。

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "@shackleai/memory-mcp@latest"],
      "env": {
        "SHACKLEAI_PROJECT_PATH": "/path/to/project"
      }
    }
  }
}

トラブルシューティング

npx setup が失敗する、または「command not found: setup」と表示される

npm/npx のバージョンが古すぎます。npm が v6.x の場合に発生します（古い Node インストーラーに付属しています）。次のコマンドで確認してください。

npm --version

6.x と表示された場合は、次の手順で修正します。

# 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」／サーバーが起動しない

Node.js 20 以降がインストールされていることを確認してください。次に、サーバーが動作することを確認します。

npx -y @shackleai/memory-mcp --help

グローバルインストールを使用している場合は、バイナリが PATH にあることを確認します。

shackleai-memory --help

Claude Code：「memory」が claude mcp list に表示されない

npx setup を使用した場合、Claude Code はプロジェクトディレクトリの .mcp.json を自動的に読み込みます。そのため、claude mcp list に表示させる必要はありません。プロジェクトディレクトリで claude を起動するだけです。

代わりに claude mcp add を使用した場合は、次のコマンドで確認します。

claude mcp list
# Should show: memory: connected

セッション中に AI がメモリを保存しない

setup コマンドは、AI にメモリを積極的に使うよう指示する CLAUDE.md ファイルを作成します。すでに CLAUDE.md がある場合、セットアップによってメモリに関する指示が追記されます。CLAUDE.md に「ShackleAI Memory」セクションが含まれていることを確認してください。

それでも AI がメモリを保存しない場合は、直接次のように依頼できます。

「今行ったことをメモリに保存してください」

これによりツールが動作することを確認でき、以降のやり取りで AI がより積極的に情報を保存するようになります。

最初のツール呼び出しが遅い

埋め込みモデル（約 80 MB）は初回使用時にダウンロードされます。これは一度限りのダウンロードです。以降の実行ではキャッシュされたモデルを使うため、高速に動作します。

セッション間でメモリが保持されない

~/.shackleai/ ディレクトリが存在し、書き込み権限があることを確認してください。サーバーは初回起動時にこのディレクトリを自動的に作成します。

間違ったプロジェクトが検出される

--project-path を使ってプロジェクトを明示的に設定するか、正しいパスを指定して memory_init を呼び出してください。

ShackleAI を選ぶ理由

現在の AI コーディングツールには、どれも記憶がありません。セッションを閉じると、コンテキストは失われます。ツールを切り替えると、すべてが失われます。

ShackleAI は、MCP 対応のあらゆる AI ツールで使えるユニバーサルメモリレイヤーを提供することで、この問題を解決します。

• あらゆる AI ツールで動作 — Claude Code、Cursor、Windsurf、VS Code Copilot、OpenAI Codex、Claude Desktop
• あらゆる LLM で動作 — Claude、GPT、Gemini、Llama、Mistralなど、あらゆる MCP クライアントで使える LLM
• あなたのメモリはあなたの資産です — いつでもツールを切り替えられ、ナレッジはそのまま保持されます
• ベンダーロックインなし — オープンソース、ローカルストレージ、標準プロトコル

必要条件

• Node.js 20 以降
• npm 7 以降（npx setup を使用する場合。任意の npm バージョンでグローバルインストールすることもできます）
• MCP 対応の AI クライアント

コントリビューション

Issue や PR は github.com/shackleai/memory-mcp で歓迎します。

ライセンス

MIT — 永久に無料のオープンソースです。

AI をつなぎ留める鎖。 ShackleAI が開発しました。