Claude API × pgvector 永続メモリエージェント実装ガイド：PostgreSQL + Redis で構築する階層型記憶システム

# docker-compose.yml
version: "3.9"
 
services:
  postgres:
    image: pgvector/pgvector:pg16
    environment:
      POSTGRES_USER: agent_user
      POSTGRES_PASSWORD: your_secure_password
      POSTGRES_DB: agent_memory
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data
      - ./init.sql:/docker-entrypoint-initdb.d/init.sql
 
  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    command: redis-server --appendonly yes
    volumes:
      - redis_data:/data
 
volumes:
  postgres_data:
  redis_data:

-- init.sql
CREATE EXTENSION IF NOT EXISTS vector;
 
-- 長期記憶テーブル
CREATE TABLE long_term_memories (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  user_id TEXT NOT NULL,
  content TEXT NOT NULL,
  content_embedding vector(1536),  -- text-embedding-3-small の次元数
  memory_type TEXT NOT NULL,       -- 'fact', 'preference', 'skill', 'event'
  importance_score FLOAT DEFAULT 0.5,
  access_count INTEGER DEFAULT 0,
  last_accessed_at TIMESTAMPTZ DEFAULT NOW(),
  created_at TIMESTAMPTZ DEFAULT NOW(),
  expires_at TIMESTAMPTZ           -- NULL = 永続
);
 
-- ベクトル検索用インデックス（HNSW）
CREATE INDEX ON long_term_memories
  USING hnsw (content_embedding vector_cosine_ops)
  WITH (m = 16, ef_construction = 64);
 
-- ユーザー別の検索最適化
CREATE INDEX ON long_term_memories (user_id, created_at DESC);
 
-- エピソード記憶テーブル
CREATE TABLE episode_memories (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  user_id TEXT NOT NULL,
  session_id TEXT NOT NULL,
  summary TEXT NOT NULL,
  key_topics TEXT[],
  sentiment TEXT,
  created_at TIMESTAMPTZ DEFAULT NOW()
);
 
CREATE INDEX ON episode_memories (user_id, created_at DESC);

// src/memory/LongTermMemory.ts
import { Pool } from "pg";
import OpenAI from "openai";
 
interface Memory {
  id: string;
  content: string;
  memoryType: "fact" | "preference" | "skill" | "event";
  importanceScore: number;
  createdAt: Date;
}
 
export class LongTermMemory {
  private pool: Pool;
  private openai: OpenAI;
 
  constructor() {
    this.pool = new Pool({
      host: process.env.POSTGRES_HOST ?? "localhost",
      port: 5432,
      user: process.env.POSTGRES_USER ?? "agent_user",
      password: process.env.POSTGRES_PASSWORD,
      database: process.env.POSTGRES_DB ?? "agent_memory",
    });
    this.openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
  }
 
  /** テキストを埋め込みベクトルに変換 */
  private async embed(text: string): Promise<number[]> {
    const response = await this.openai.embeddings.create({
      model: "text-embedding-3-small",
      input: text,
    });
    return response.data[0].embedding;
  }
 
  /** 新しい記憶を保存 */
  async save(
    userId: string,
    content: string,
    type: Memory["memoryType"],
    importanceScore = 0.5
  ): Promise<string> {
    const embedding = await this.embed(content);
    const result = await this.pool.query(
      `INSERT INTO long_term_memories
         (user_id, content, content_embedding, memory_type, importance_score)
       VALUES ($1, $2, $3::vector, $4, $5)
       RETURNING id`,
      [userId, content, JSON.stringify(embedding), type, importanceScore]
    );
    return result.rows[0].id;
  }
 
  /** 類似記憶を検索（コサイン類似度） */
  async search(
    userId: string,
    query: string,
    limit = 5,
    threshold = 0.75
  ): Promise<Memory[]> {
    const queryEmbedding = await this.embed(query);
 
    const result = await this.pool.query(
      `SELECT id, content, memory_type, importance_score, created_at,
              1 - (content_embedding <=> $2::vector) AS similarity
       FROM long_term_memories
       WHERE user_id = $1
         AND (expires_at IS NULL OR expires_at > NOW())
         AND 1 - (content_embedding <=> $2::vector) > $3
       ORDER BY similarity DESC, importance_score DESC
       LIMIT $4`,
      [userId, JSON.stringify(queryEmbedding), threshold, limit]
    );
 
    // アクセス頻度の更新（よく参照される記憶は重要度が上がる）
    if (result.rows.length > 0) {
      const ids = result.rows.map((r) => r.id);
      await this.pool.query(
        `UPDATE long_term_memories
         SET access_count = access_count + 1, last_accessed_at = NOW()
         WHERE id = ANY($1)`,
        [ids]
      );
    }
 
    return result.rows.map((row) => ({
      id: row.id,
      content: row.content,
      memoryType: row.memory_type,
      importanceScore: row.importance_score,
      createdAt: row.created_at,
    }));
  }
 
  /** ユーザーの記憶を削除（GDPR対応） */
  async deleteAll(userId: string): Promise<void> {
    await this.pool.query(
      "DELETE FROM long_term_memories WHERE user_id = $1",
      [userId]
    );
    await this.pool.query(
      "DELETE FROM episode_memories WHERE user_id = $1",
      [userId]
    );
  }
}

// src/memory/ShortTermMemory.ts
import { createClient } from "redis";
 
interface Message {
  role: "user" | "assistant";
  content: string;
  timestamp: number;
}
 
export class ShortTermMemory {
  private client: ReturnType<typeof createClient>;
  private ttl: number; // 秒単位
 
  constructor(ttlSeconds = 86400) {
    // デフォルト24時間
    this.client = createClient({
      url: process.env.REDIS_URL ?? "redis://localhost:6379",
    });
    this.ttl = ttlSeconds;
    this.client.connect();
  }
 
  private key(userId: string, sessionId: string): string {
    return `session:${userId}:${sessionId}`;
  }
 
  /** メッセージをセッションに追加 */
  async push(
    userId: string,
    sessionId: string,
    message: Omit<Message, "timestamp">
  ): Promise<void> {
    const key = this.key(userId, sessionId);
    const entry: Message = { ...message, timestamp: Date.now() };
 
    await this.client.rPush(key, JSON.stringify(entry));
    await this.client.expire(key, this.ttl);
 
    // 最大50件を超えたら古いものを削除
    const length = await this.client.lLen(key);
    if (length > 50) {
      await this.client.lTrim(key, -50, -1);
    }
  }
 
  /** セッションの会話履歴を取得 */
  async getHistory(
    userId: string,
    sessionId: string,
    limit = 20
  ): Promise<Message[]> {
    const key = this.key(userId, sessionId);
    const items = await this.client.lRange(key, -limit, -1);
    return items.map((item) => JSON.parse(item));
  }
 
  /** セッションを終了してクリア */
  async endSession(userId: string, sessionId: string): Promise<Message[]> {
    const history = await this.getHistory(userId, sessionId, 100);
    await this.client.del(this.key(userId, sessionId));
    return history;
  }
}

// src/agent/MemoryAgent.ts
import Anthropic from "@anthropic-ai/sdk";
import { LongTermMemory } from "../memory/LongTermMemory";
import { ShortTermMemory } from "../memory/ShortTermMemory";
 
const client = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
 
export class MemoryAgent {
  private longTerm: LongTermMemory;
  private shortTerm: ShortTermMemory;
 
  constructor() {
    this.longTerm = new LongTermMemory();
    this.shortTerm = new ShortTermMemory();
  }
 
  private tools: Anthropic.Tool[] = [
    {
      name: "search_memory",
      description:
        "ユーザーの過去の会話や保存済みの知識を検索します。" +
        "現在の会話に関連する情報を取得するために使用してください。",
      input_schema: {
        type: "object" as const,
        properties: {
          query: {
            type: "string",
            description: "検索クエリ（自然言語で記述）",
          },
          limit: {
            type: "number",
            description: "返す記憶の最大件数（デフォルト: 3）",
          },
        },
        required: ["query"],
      },
    },
    {
      name: "save_memory",
      description:
        "重要な情報を長期記憶に保存します。" +
        "ユーザーの好み、重要な事実、スキル、出来事などを保存してください。",
      input_schema: {
        type: "object" as const,
        properties: {
          content: {
            type: "string",
            description: "保存する情報の内容",
          },
          memory_type: {
            type: "string",
            enum: ["fact", "preference", "skill", "event"],
            description: "記憶の種類",
          },
          importance: {
            type: "number",
            description: "重要度スコア（0.0〜1.0）",
          },
        },
        required: ["content", "memory_type"],
      },
    },
  ];
 
  async chat(
    userId: string,
    sessionId: string,
    userMessage: string
  ): Promise<string> {
    // 短期記憶にユーザーのメッセージを追加
    await this.shortTerm.push(userId, sessionId, {
      role: "user",
      content: userMessage,
    });
 
    // 短期記憶から会話履歴を取得
    const history = await this.shortTerm.getHistory(userId, sessionId, 10);
    const messages: Anthropic.MessageParam[] = history.map((h) => ({
      role: h.role,
      content: h.content,
    }));
 
    // ツール呼び出しループ
    while (true) {
      const response = await client.messages.create({
        model: "claude-opus-4-6",
        max_tokens: 2048,
        system: `あなたは記憶システムを持つAIアシスタントです。
ユーザーとの会話を始める前に必ず search_memory ツールを使って
関連する過去の情報を確認してください。
重要な情報は積極的に save_memory で保存し、
ユーザーの体験を継続的に向上させてください。`,
        messages,
        tools: this.tools,
      });
 
      if (response.stop_reason === "end_turn") {
        const text = response.content
          .filter((b) => b.type === "text")
          .map((b) => (b as Anthropic.TextBlock).text)
          .join("");
 
        // アシスタントの応答を短期記憶に追加
        await this.shortTerm.push(userId, sessionId, {
          role: "assistant",
          content: text,
        });
        return text;
      }
 
      if (response.stop_reason === "tool_use") {
        // ツール呼び出しの処理
        const assistantMessage: Anthropic.MessageParam = {
          role: "assistant",
          content: response.content,
        };
        messages.push(assistantMessage);
 
        const toolResults: Anthropic.ToolResultBlockParam[] = [];
 
        for (const block of response.content) {
          if (block.type !== "tool_use") continue;
 
          let result = "";
 
          if (block.name === "search_memory") {
            const input = block.input as { query: string; limit?: number };
            const memories = await this.longTerm.search(
              userId,
              input.query,
              input.limit ?? 3
            );
            result =
              memories.length > 0
                ? memories
                    .map(
                      (m) =>
                        `[${m.memoryType}] ${m.content} (重要度: ${m.importanceScore})`
                    )
                    .join("\n")
                : "関連する記憶は見つかりませんでした。";
          }
 
          if (block.name === "save_memory") {
            const input = block.input as {
              content: string;
              memory_type: "fact" | "preference" | "skill" | "event";
              importance?: number;
            };
            const id = await this.longTerm.save(
              userId,
              input.content,
              input.memory_type,
              input.importance ?? 0.5
            );
            result = `記憶を保存しました（ID: ${id}）`;
          }
 
          toolResults.push({
            type: "tool_result",
            tool_use_id: block.id,
            content: result,
          });
        }
 
        messages.push({ role: "user", content: toolResults });
      }
    }
  }
}

// セッション終了処理
async endSession(userId: string, sessionId: string): Promise<void> {
  const history = await this.shortTerm.endSession(userId, sessionId);
  if (history.length < 3) return; // 短すぎるセッションはスキップ
 
  const conversationText = history
    .map((h) => `${h.role}: ${h.content}`)
    .join("\n");
 
  // Claude にサマリーを生成させる
  const summaryResponse = await client.messages.create({
    model: "claude-haiku-4-5-20251001", // コスト最適化のためHaikuを使用
    max_tokens: 512,
    messages: [
      {
        role: "user",
        content: `以下の会話を3文以内で要約してください。
重要なトピックとユーザーが学んだことを中心にまとめてください。
 
${conversationText}`,
      },
    ],
  });
 
  const summary =
    summaryResponse.content[0].type === "text"
      ? summaryResponse.content[0].text
      : "";
 
  // エピソード記憶として保存
  const pool = (this.longTerm as any).pool; // 実際はプロパティを公開する
  await pool.query(
    `INSERT INTO episode_memories (user_id, session_id, summary, key_topics)
     VALUES ($1, $2, $3, $4)`,
    [userId, sessionId, summary, []] // topic抽出は省略
  );
}

// NG: 数値配列を直接渡す
await pool.query("INSERT INTO ... VALUES ($1)", [embedding]);
 
// OK: JSON文字列 + ::vector キャスト
await pool.query("INSERT INTO ... VALUES ($1::vector)", [
  JSON.stringify(embedding),
]);

// GDPR 対応：ユーザーデータの完全削除
async deleteUserData(userId: string): Promise<void> {
  await this.longTerm.deleteAll(userId); // long_term_memories + episode_memories を削除
  // Redis のセッションデータも削除
  const keys = await this.shortTerm.client.keys(`session:${userId}:*`);
  if (keys.length > 0) {
    await this.shortTerm.client.del(keys);
  }
}

// 埋め込みのキャッシュ（Redis・TTL 2時間）
import { createHash } from "crypto";
 
async embedCached(text: string): Promise<number[]> {
  const key = `embed:${createHash("md5").update(text).digest("hex")}`;
  const cached = await this.redisClient.get(key);
  if (cached) return JSON.parse(cached);
 
  const embedding = await this.embed(text);
  await this.redisClient.setEx(key, 7200, JSON.stringify(embedding));
  return embedding;
}