memory-mcp-lite

memory-mcp-lite

AI コーディングアシスタント（Windsurf、Cursor、Claude Desktop など、MCP に対応するものすべて）のための、小さく、独自の方針を持つメモリーサーバーです。

ローカルで動作し、ディスクに永続的なナレッジを保存します。また、本当に必要になるまで、エージェントの邪魔にならないよう細心の注意を払っています。

このプロジェクトの目的

ほとんどの AI クライアントには、何らかの短期メモリーがすでに備わっています。現在の会話や、設定したいくつかのルールなどは覚えてくれますが、それだけです。セッションが終わった後も残しておきたい情報、たとえば先週決めたアーキテクチャ上の判断、このリポジトリ固有の少し変わったビルドコマンド、何度も遭遇した落とし穴などを置いておく場所はありません。

memory-mcp-lite は、そのための場所です。次の情報を保存します。

• 技術的な判断と、その背景にある理由。
• プロジェクトのアーキテクチャと規約。
• コマンド、環境に関するメモ、リンク、落とし穴。
• 後で作業を再開できるようにするタスクの状態。
• グローバル／プロジェクト／タスクの各レベルでまとめたサマリー。

生のチャットの記録を保存したり、クライアントに組み込まれているルールを置き換えたり、埋め込みやベクトル検索を実行したりすることは意図的に避けています。また、サーバーやクラウドへの接続も不要です。

構成

メモリーはツリー構造で保存されます。

global
└── project
    ├── [project_summary]
    └── task
        ├── [task_summary]
        └── atomic  // decision | fact | gotcha | command | link | convention

このツリーに加えて、任意で任意の2つのノード間にグラフ形式の軽量なエッジを作成できます。エッジには related_to、depends_on、affects、caused_by、supersedes、references があります。ある判断が別の判断を無効にする場合や、特定のコマンドとの関連でのみ問題となる落とし穴を記録する場合に便利です。

情報の取得は低コストになるよう設計されています。サーバーの指示により、エージェントはコストの低い順に次の3段階を踏みます。

Stage 1 — summaries              get_global_summary / get_project_summary / get_task_summary
        │
        ▼ (only if summaries aren't enough)
Stage 2 — FTS5 light search      search_memory_light → compact candidates
        │
        ▼ (only for the 1–3 most relevant hits)
Stage 3 — full detail            get_memory_detail

実際には、まずエージェントがサマリーを取得し、具体的な理由がある場合にのみ、大きなペイロードを取得することになります。この方針を無視すると、理由もなく文字列型の JSON が大量にコンテキストへ追加されるだけです。

技術スタック

• TypeScript、Node ≥ 20
• libSQL 上の Drizzle ORM（@libsql/client）
• 字句検索用の SQLite FTS5
• サブツリーを効率よくたどるためのクロージャテーブル
• MCP TypeScript SDK（@modelcontextprotocol/sdk）

ローカルファイル、リモートの libSQL インスタンス、Turso データベースのいずれを指定しても、同じように動作します。

インストール

手早く使い始めるには、npx を使って MCP クライアントにパッケージを取得させます。

Windsurf — ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "memory-mcp-lite": {
      "command": "npx",
      "args": ["memory-mcp-lite"]
    }
  }
}

Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "memory-mcp-lite": {
      "command": "npx",
      "args": ["memory-mcp-lite"]
    }
  }
}

ほかの MCP 対応クライアントでも同じ形式を使えます。異なるのは設定ファイルのパスだけです。

ソースからインストール

npm install
npm run build    # outputs dist/index.js; the schema is created on first run

次に、コンパイル済みのバンドルを使うようクライアントを設定します。

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

ビルドせずにコードを変更しながら試したい場合は、tsx を使えます。

{
  "mcpServers": {
    "memory-mcp-lite": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/memory-mcp-lite/apps/server/src/index.ts"]
    }
  }
}

データの保存場所

デフォルトでは ~/.memory-mcp/memory.db に保存されます。次のいずれかを使って変更できます。

環境変数	用途
MEMORY_DB_PATH	フルパス、または libsql://… / file: URL。
MEMORY_DATA_DIR	ディレクトリ。ファイル名は引き続き memory.db です。
DATABASE_URL	下位互換性のために受け付けます。
MEMORY_DB_AUTH_TOKEN	リモートの libSQL / Turso 用のベアラートークン。

Turso に接続して実行するには、次のようにします。

MEMORY_DB_PATH="libsql://your-db.turso.io" \
MEMORY_DB_AUTH_TOKEN="eyJhbGci..." \
npm run dev

ツール

9 つのツールがあり、いずれも人が読める JSON ブロックと、プログラムから利用するクライアント向けの structuredContent オブジェクトの両方を返します。また、サーバーは各ツールについて厳密な description と annotations のペイロードも提供するため、エージェントは推測せずに適切なツールを選べます。

ツール	使用する場面
get_global_summary	繰り返し適用される好み、プロジェクト横断の規約
get_project_summary	アーキテクチャ、重要な決定、長期的なプロジェクトのコンテキスト
get_task_summary	特定の作業の再開
search_memory_light	要約だけでは足りず、簡潔な候補を探したいとき
get_memory_detail	候補を選び、その全内容が必要なとき
remember_decision	アーキテクチャ上の選択、トレードオフ、または却下した案
remember_fact	コマンド、環境に関するメモ、注意点、リンク、または規約
upsert_project_summary	アーキテクチャ変更後、または記録する価値のある新しい規約の追加後
upsert_task_summary	進捗、ブロッカー、または計画の変更後

サーバーがエージェントに求める検索の手順は次のとおりです。

1. まず要約を確認します。
2. 要約だけでは足りない場合に限り、簡易検索を行います。
3. 詳細を取得するのは、最大 1～3 件のヒットにします。
4. 取得できるからといって、すべてのメモリを決して一括出力しないでください。

プロジェクトの識別

プロジェクトは次の優先順位で検索されます。

1. 正規化された git リモート URL — 最も安定しており、ディレクトリの移動やクローン後も維持されます。
2. Git ルートパス — リモートがない場合に使用されます。
3. 正規化されたワークスペースパス — フォールバックとして使用されます。

つまり、クライアントによってパスの渡し方に多少の違いがあっても、同じプロジェクトでは同じメモリが維持されます。また、リポジトリを移動しても、保存した内容がすべて参照できなくなることはありません。

開発

npm run typecheck      # TypeScript
npm run lint           # oxlint
npm run test           # vitest
npm run build          # esbuild bundle to dist/
npm run dev            # tsx watch
npm run db:studio      # Drizzle Studio for poking at the DB
npm run db:generate    # generate migration SQL when the schema changes

スキーマは apps/server/src/db/schema.ts で定義され、起動のたびに ensureSchema() によって再確認されます（apps/server/src/db/migrate.ts を参照）。この関数では、FTS5 仮想テーブルとそのトリガーも作成されます。Drizzle は仮想テーブルを管理しないため、通常の SQL を使って自分たちで作成しています。この処理は冪等なので、手動で実行するものはありません。

ロードマップ

• オプションのセマンティックフォールバック（ローカル埋め込み、機能フラグで制御）。
• 長期運用されるプロジェクト向けのノードのアーカイブ／クリーンアップ。
• 認証の適切な方法が整い次第、チーム共有メモリ。