امنح عميل AI ذاكرة طويلة المدى باستخدام pgvector (2026)

نافذة السياق (context window) الخاصة بعميل الذكاء الاصطناعي يتم إعادة ضبطها في كل جلسة — لذا فهو لا يملك أي فكرة عن هويتك في المرة الثانية التي تتحدث فيها معه. يقوم هذا البرنامج التعليمي ببناء عميل TypeScript صغير يحل هذه المشكلة باستخدام Postgres وإضافة pgvector: حيث يقرر Claude ما الذي يستحق التذكر، وتقوم أداة remember_fact بتخزينه كـ embedding، بينما يقوم استعلام cosine-similarity باسترجاعه في كل دورة لاحقة — بما في ذلك بعد إيقاف العملية بالكامل وإعادة تشغيلها¹.

ملخص

ستقوم ببناء عميل CLI يربط Claude (claude-sonnet-5) بمخزن ذاكرة Postgres 18 + pgvector². تتيح أداة remember_fact لـ Claude تحديد متى يكون شيء ما عن المستخدم يستحق الحفظ؛ وقبل كل رد، يقوم التطبيق بتحويل رسالة المستخدم إلى embedding باستخدام text-embedding-3-small من OpenAI³ ويسحب الذكريات الأكثر تطابقاً باستخدام عامل مسافة جيب التمام (cosine-distance) <=> الخاص بـ pgvector⁴، ثم يحقنها في موجه النظام (system prompt). أوقف العملية، ابدأها مرة أخرى، وسيظل العميل يعرف اسمك. بيئة التشغيل: Node.js 24 LTS⁵، @anthropic-ai/sdk@0.112.1، pg@8.22.0. وقت البناء: 25-30 دقيقة.

ما ستتعلمه

• كيفية تشغيل Postgres مع إضافة pgvector مثبتة مسبقاً باستخدام صورة Docker الرسمية pgvector/pgvector
• كيفية تخزين الـ embeddings في عمود vector والاستعلام عنها باستخدام عامل مسافة جيب التمام <=> في pgvector
• كيفية إعطاء Claude أداة remember_fact لكي يقرر النموذج ما الذي يستحق الحفظ، بدلاً من تحويل كل رسالة إلى embedding بشكل أعمى
• كيفية استرجاع الذكريات ذات الصلة قبل كل دورة وحقنها في موجه النظام
• كيفية إثبات أن الذاكرة صمدت بعد إعادة التشغيل عن طريق إنهاء عملية Node وبدء عملية جديدة
• ماذا تفعل عندما لا يعيد الاسترجاع أي شيء، أو يعيد ذكريات خاطئة

المتطلبات الأساسية

• Docker (أي إصدار حديث) — يُستخدم لتشغيل pgvector/pgvector:pg18، وهي صورة Postgres 18 الرسمية مع pgvector مثبتة مسبقاً⁶
• Node.js 24 LTS أو أحدث — صدر في 2025-05-06، وفي مرحلة Active LTS منذ 2025-10-28 (ينتقل إلى Maintenance LTS في 2026-10-20)، ومدعوم حتى 2028-04-30⁵
• مفتاح ANTHROPIC_API_KEY (لـ Claude) ومفتاح OPENAI_API_KEY (للـ embeddings فقط — لأن Anthropic لا توفر نقطة نهاية للـ embeddings، لذا فإن text-embedding-3-small يسد هذه الفجوة)⁷
• إلمام بأساسيات SQL؛ لن تكتب أي أدوات تهجير (migrations)، فقط استعلامات CREATE TABLE خام واستعلامات ذات معاملات (parameterized queries)

الخطوة 1: تشغيل Postgres مع pgvector

تجاوز عملية تجميع الإضافة بنفسك — ينشر مشروع pgvector صورة Docker وهي صورة Postgres القياسية مع pgvector مدمجة بالفعل⁶:

Docker run -d \
  --name agent-memory-db \
  -e POSTGRES_PASSWORD=postgres \
  -e POSTGRES_DB=agent_memory \
  -p 5432:5432 \
  pgvector/pgvector:pg18

pg18 تشير إلى Postgres 18 (حالياً في إصدار التصحيح 18.4) مع أحدث تصحيح لـ pgvector مثبت مسبقاً — يتتبع الوسم (tag) وتيرة إصدارات pgvector تلقائياً، لذا ستحصل على أي تصحيح متاح عند سحب الصورة، وليس بالضرورة ما كان متاحاً عند كتابة هذا الدليل. إصدار 0.8.2 (2026-02-25) أصلح خطأ buffer-overflow في عمليات بناء فهرس HNSW المتوازية²⁸؛ بعد الخطوة 2، سيخبرك الاستعلام SELECT extversion FROM pg_extension WHERE extname = 'vector'; بالضبط عن التصحيح الذي حصلت عليه. تأكد من أن الحاوية تعمل:

Docker exec agent-memory-db pg_isready -U postgres
# /var/run/postgresql:5432 - accepting connections

الخطوة 2: إنشاء جدول الذاكرة

قم بتفعيل الإضافة وإنشاء جدول واحد: معرف المورد (resource ID) لمن تعود هذه الذاكرة، والحقيقة كنص، والـ embedding الخاص بها.

-- schema.sql
CREATE EXTENSION IF NOT EXISTS vector;

CREATE TABLE IF NOT EXISTS agent_memories (
  id bigserial PRIMARY KEY,
  resource_id text NOT NULL,
  content text NOT NULL,
  embedding vector(1536) NOT NULL,
  created_at timestamptz NOT NULL DEFAULT now()
);

CREATE INDEX IF NOT EXISTS agent_memories_embedding_idx
  ON agent_memories USING hnsw (embedding vector_cosine_ops);

vector(1536) يتطابق مع حجم المخرجات الافتراضي لـ text-embedding-3-small³. فهرس hnsw مع vector_cosine_ops هو ما يجعل <=> سريعاً بمجرد أن يكون لديك أكثر من بضع مئات من الصفوف — حيث يقوم pgvector بالبحث الدقيق افتراضياً ولا يتحول إلى البحث التقريبي إلا عند وجود فهرس كهذا⁴. قم بتطبيقه:

Docker exec -i agent-memory-db psql -U postgres -d agent_memory < schema.sql

الخطوة 3: إعداد مشروع TypeScript

mkdir agent-memory && cd agent-memory
npm init -y
npm install @anthropic-ai/sdk@0.112.1 openai@6.48.0 pg@8.22.0 pgvector@0.3.0
npm install -D TypeScript@6.0.3 @types/node@24.13.3 @types/pg@8.20.0 tsx@4.23.1

pgvector هنا هي حزمة npm (غير مرتبطة في رقم الإصدار بإضافة Postgres) التي تحول مصفوفات الأرقام في JS إلى تنسيق literal الخاص بـ Postgres vector وتقوم بتسجيل النوع على عميل pg⁹. أضف "type": "module" إلى package.json، ثم أنشئ tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "strict": true,
    "skipLibCheck": true,
    "noEmit": true,
    "allowImportingTsExtensions": true
  },
  "include": ["*.ts"]
}

خيار allowImportingTsExtensions مهم: الملفات أدناه تستورد بعضها البعض كـ ./db.ts، وليس ./db.js، وهو ما يعمل فقط عند تفعيل هذا الخيار (ويتطلب noEmit: true، وهو ما تريده على أي حال لأن tsx يتولى التنفيذ).

الخطوة 4: الاتصال بـ Postgres وكتابة وظائف الذاكرة

يقوم ملف db.ts بفتح مجمع اتصالات (connection pool) وتسجيل أنواع pgvector في كل اتصال جديد:

// db.ts
import pg from "pg";
import pgvector from "pgvector/pg";

const { Pool } = pg;

export const pool = new Pool({
  connectionString: process.env.DATABASE_URL ?? "postgres://postgres:postgres@localhost:5432/agent_memory",
  onConnect: async (client) => {
    await pgvector.registerTypes(client);
  },
});

يقوم ملف memory.ts بالعمل الفعلي: تحويل النص إلى embedding باستخدام OpenAI، وتخزينه، واسترجاع أقرب التطابقات لمستخدم معين.

// memory.ts
import OpenAI from "openai";
import pgvector from "pgvector/pg";
import { pool } from "./db.ts";

const openai = new OpenAI();

export async function embed(text: string): Promise<number[]> {
  const response = await openai.embeddings.create({
    model: "text-embedding-3-small",
    input: text,
  });
  const vector = response.data[0]?.embedding;
  if (!vector) throw new Error("OpenAI returned no embedding");
  return vector;
}

export async function rememberFact(resourceId: string, fact: string): Promise<void> {
  const embedding = await embed(fact);
  await pool.query(
    "INSERT INTO agent_memories (resource_id, content, embedding) VALUES ($1, $2, $3)",
    [resourceId, fact, pgvector.toSql(embedding)],
  );
}

export interface RecalledMemory {
  content: string;
  distance: number;
}

export async function recallMemories(
  resourceId: string,
  query: string,
  limit = 3,
): Promise<RecalledMemory[]> {
  const embedding = await embed(query);
  const result = await pool.query<{ content: string; distance: number }>(
    `SELECT content, embedding <=> $2 AS distance
       FROM agent_memories
      WHERE resource_id = $1
      ORDER BY embedding <=> $2
      LIMIT $3`,
    [resourceId, pgvector.toSql(embedding), limit],
  );
  return result.rows;
}

تقوم pgvector.toSql() بتحويل مصفوفة JS إلى السلسلة النصية التي يتوقعها Postgres لـ literal من نوع vector — فتتحول [1, 2, 3] إلى "[1,2,3]"، بما يتطابق مع أمثلة SQL الخام في وثائق pgvector نفسها⁹. <=> تعني مسافة جيب التمام، لذا فإن القيمة الأصغر تعني تشابهاً أكبر؛ و ORDER BY ... ASC تضع بالفعل أقرب التطابقات أولاً، لذا لا حاجة لتحويلها إلى "تشابه" (similarity)⁴.

// run.ts
import { createInterface } from "node:readline/promises";
import { stdin, stdout } from "node:process";
import { runTurn } from "./agent.ts";
import { pool } from "./db.ts";

const RESOURCE_ID = "demo-user";

async function main() {
  const rl = createInterface({ input: stdin, output: stdout });
  console.log("Agent memory demo. Type a message, or 'exit' to quit.\n");

  while (true) {
    const input = await rl.question("you> ");
    if (input.trim().toLowerCase() === "exit") break;
    const reply = await runTurn(RESOURCE_ID, input);
    console.log(`agent> ${reply}\n`);
  }

  rl.close();
  await pool.end();
}

main().catch((err) => {
  console.error(err);
  process.exit(1);
});

you> My name is Sam and I'm on the Pro plan.
agent> Nice to meet you, Sam! I've made a note that you're on the Pro plan —
let me know if you need help with anything.
you> exit

you> What's my name, and what plan am I on?
agent> Your name is Sam, and you're on the Pro plan.
you> exit

Docker exec agent-memory-db psql -U postgres -d agent_memory \
  -c "SELECT resource_id, content, created_at FROM agent_memories ORDER BY created_at;"

 resource_id |            content             |          created_at
-------------+---------------------------------+-------------------------------
 demo-user   | The user's name is Sam.         | 2026-07-17 09:14:02.113+00
 demo-user   | The user is on the Pro plan.    | 2026-07-17 09:14:02.897+00